Pbsq Sk

🚀 PayBySquare Generator

このライブラリは、Node.js/TypeScript用の包括的な PayBySquare QRコードライブラリです。支払いQRコードの生成、デコード、検証が可能です。PayBySquareは、スロバキア銀行協会（SBA）によって採用されたスロバキアの支払いQRコードの国家标准です。

✨ 主な機能

生成

• ✅ シンプルなJSONベースのAPI
• ✅ QRコードをPNGバッファまたはファイルとして生成
• ✅ すべてのPayBySquare支払いフィールドをサポート
• ✅ QRコードのスタイルをカスタマイズ可能（サイズ、色、誤り訂正）

デコード

• ✅ PNGバッファからPayBySquare QRコードをデコード
• ✅ 支払いデータをJSON形式に抽出
• ✅ ラウンドトリップ検証（損失のないエンコード/デコード）

コンプライアンスと検証

• ✅ IBANチェックサム検証（mod-97アルゴリズム）
• ✅ フィールド形式のコンプライアンスチェック
• ✅ 銀行規格の検証（BIC/SWIFT、通貨コード）
• ✅ エラーの重大度レベルを含む詳細なコンプライアンスレポート

開発

• ✅ 完全なTypeScriptサポートと型定義
• ✅ ゼロUI依存 - 純粋な関数ベースのAPI
• ✅ ESMモジュール形式（Node.js >= 18）
• ✅ 徹底的なテスト（96の単体テストで90%以上のカバレッジ）
• ✅ MCP Server - Claude Desktopや他のMCPクライアントと共に使用可能

破壊的変更

MCP Server v1.1.0 (2026年1月)

⚠️ 破壊的変更: generate_paybysquare ツールが、base64エンコードされた画像ではなくファイルパスを返すようになりました

MCPサーバーの generate_paybysquare ツールは、QRコードをファイルとして保存し、base64でエンコードされたバイナリデータではなくファイルパスを返すように更新されました。この変更により、LLMのコンテキスト効率が向上し、生成されたQRコードを後で使用できるようになります。

変更前 (v1.0.0):

{
  "success": true,
  "imageBase64": "iVBORw0KGgoAAAANSUhEUg...",
  "size": 12345,
  "message": "QR code generated successfully"
}

変更後 (v1.1.0):

{
  "success": true,
  "filePath": "/Users/username/paybysquare-qr-codes/paybysquare-1705331234567-a3f2.png",
  "fileName": "paybysquare-1705331234567-a3f2.png",
  "message": "QR code generated and saved successfully"
}

移行方法:

• QRコードはデフォルトで ~/paybysquare-qr-codes/ に保存されます
• outputDirectory オプションを使用して、カスタムの保存場所を指定できます
• 返された filePath を使用して生成されたファイルにアクセスします
• 注意: コアライブラリの関数 (generatePayBySquare, generatePayBySquareToFile) は変更されていません

ドキュメントの強化:

• ツールの説明で、beneficiaryName が 必須 であることが強調されるようになりました
• swift (BICコード) は、国際支払いの場合は 推奨 としてマークされるようになりました

利点:

• トークン使用量の削減（ファイルパス vs. base64データ）
• より良いLLMコンテキスト効率
• 後から参照できる永続的なQRコード
• ファイルベースのワークフローとの統合が容易になります

注意: この変更はMCPサーバーにのみ影響します。コアのNode.js/TypeScriptライブラリのAPIは完全に下位互換性があります。

📦 インストール

npm install paybysquare-generator

必要条件

• Node.js >= 18.0.0
• ESMモジュールサポート

🚀 クイックスタート

import { generatePayBySquare } from 'paybysquare-generator';

// 支払いQRコードを生成
const buffer = await generatePayBySquare({
  iban: 'SK9611000000002918599669',
  beneficiaryName: 'John Doe',
  amount: 100.50,
  currency: 'EUR',
  variableSymbol: '123456',
  paymentNote: 'Invoice payment'
});

// bufferはPNG画像のBufferです - 保存、送信などが可能です

📚 ドキュメント

generatePayBySquare(input, options?)

支払いデータからPayBySquare QRコードのPNGを生成します。

パラメータ:

• input: PayBySquareInput - 支払いデータ（以下を参照）
• options?: GenerationOptions - オプションのQRコード生成オプション

返り値: Promise<Buffer> - Node.jsのBufferとしてのPNG画像

エラー:

• ValidationError - 入力データが無効な場合
• EncodingError - 支払いデータのエンコードが失敗した場合
• GenerationError - QRコードのPNG生成が失敗した場合

generatePayBySquareToFile(input, filePath, options?)

PayBySquare QRコードを生成し、ファイルに保存します。

パラメータ:

• input: PayBySquareInput - 支払いデータ
• filePath: string - PNGファイルを保存するパス
• options?: GenerationOptions - オプションのQRコード生成オプション

返り値: Promise<void>

decodePayBySquare(buffer)

PNGバッファからPayBySquare QRコードをデコードし、支払いデータに戻します。

パラメータ:

• buffer: Buffer - PayBySquare QRコードを含むPNG画像のバッファ

返り値: Promise<PayBySquareInput> - デコードされた支払いデータ

エラー:

• DecodingError - QRコードを読み取りまたはデコードできない場合

例:

import { readFile } from 'fs/promises';
import { decodePayBySquare } from 'paybysquare-generator';

const qrBuffer = await readFile('./payment-qr.png');
const paymentData = await decodePayBySquare(qrBuffer);

console.log(paymentData.iban, paymentData.amount);

isCompliant(input)

支払いデータのコンプライアンスを簡単にパス/フェイルでチェックします。

パラメータ:

• input: PayBySquareInput - 検証する支払いデータ

返り値: boolean - 完全にコンプライアントであれば true、そうでなければ false

例:

import { isCompliant } from 'paybysquare-generator';

const isValid = isCompliant({
  iban: 'SK9611000000002918599669',
  beneficiaryName: 'Test'
});

console.log(isValid); // trueまたはfalse

checkCompliance(input)

エラー、警告、重大度レベルを含む詳細なコンプライアンスレポートを提供します。

パラメータ:

• input: PayBySquareInput - 検証する支払いデータ

返り値: Promise<ComplianceResult> - 構造化されたコンプライアンスレポート

例:

import { checkCompliance } from 'paybysquare-generator';

const report = await checkCompliance(paymentData);

if (!report.isCompliant) {
  console.log('Errors:', report.errors);
  console.log('Warnings:', report.warnings);
  console.log('Details:', report.details);
}

ComplianceResult:

interface ComplianceResult {
  isCompliant: boolean;
  errors: ComplianceIssue[];     // 支払いを妨げる重大な問題
  warnings: ComplianceIssue[];   // 重大でない問題
  details: {
    ibanValid: boolean;
    fieldsValid: boolean;
    bankingStandardsValid: boolean;
    totalIssues: number;
  };
}

interface ComplianceIssue {
  type: 'error' | 'warning';
  field: string;
  message: string;
  severity: 'critical' | 'major' | 'minor';
}

checkQRCompliance(buffer)

PNGバッファから直接QRコードのコンプライアンスをチェックします。

パラメータ:

• buffer: Buffer - QRコードを含むPNG画像のバッファ

返り値: Promise<ComplianceResult> - デコードされたデータのコンプライアンスレポート

verifyRoundTrip(input)

支払いデータがエンコードとデコードの過程で損失なく保存されることを検証します。

パラメータ:

• input: PayBySquareInput - 元の支払いデータ

返り値: Promise<RoundTripResult> - ラウンドトリップ検証結果

例:

import { verifyRoundTrip } from 'paybysquare-generator';

const result = await verifyRoundTrip(originalData);

if (!result.isLossless) {
  console.log('Data loss detected:', result.differences);
}

RoundTripResult:

interface RoundTripResult {
  isLossless: boolean;
  differences: FieldDifference[];
  input: PayBySquareInput;    // 元のデータ
  decoded: PayBySquareInput;  // エンコード/デコードサイクル後のデータ
}

interface FieldDifference {
  field: string;
  original: any;
  decoded: any;
}

入力データ形式

PayBySquareInput

interface PayBySquareInput {
  // 必須フィールド
  iban: string;                    // 例: "SK9611000000002918599669"
  beneficiaryName: string;         // 受取人名 (最大70文字)

  // オプションの支払い詳細
  amount?: number;                 // 支払い金額 (正数)
  currency?: string;               // ISO 4217コード (デフォルト: "EUR")
  variableSymbol?: string;         // 1 - 10桁
  constantSymbol?: string;         // 1 - 4桁
  specificSymbol?: string;         // 1 - 10桁
  paymentNote?: string;            // 最大140文字
  dueDate?: string;                // ISO形式: "YYYY-MM-DD"
  swift?: string;                  // SWIFT/BICコード
  originatorReference?: string;    // 参照情報

  // オプションの受取人住所
  beneficiaryAddress?: {
    street?: string;               // 最大70文字
    city?: string;                 // 最大70文字
  };
}

GenerationOptions

interface GenerationOptions {
  width?: number;                  // QRコードの幅 (ピクセル単位、デフォルト: 300)
  margin?: number;                 // QRコードの周囲の余白 (デフォルト: 4)
  errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';  // デフォルト: 'M'
  color?: {
    dark?: string;                 // 暗い色 (デフォルト: '#000000')
    light?: string;                // 明るい色 (デフォルト: '#ffffff')
  };
  removeAccents?: boolean;         // アクセント記号を削除 (デフォルト: true)
}

💻 使用例

最小限の支払い

import { generatePayBySquare } from 'paybysquare-generator';
import { writeFile } from 'fs/promises';

const buffer = await generatePayBySquare({
  iban: 'SK9611000000002918599669',
  beneficiaryName: 'John Doe'
});

await writeFile('payment.png', buffer);

すべてのフィールドを含む完全な支払い

const buffer = await generatePayBySquare({
  iban: 'SK9611000000002918599669',
  beneficiaryName: 'Acme Corporation',
  amount: 150.50,
  currency: 'EUR',
  variableSymbol: '2026001',
  constantSymbol: '0308',
  paymentNote: 'Invoice #2026001',
  dueDate: '2026-02-15',
  swift: 'TATRSKBX',
  originatorReference: 'REF-2026-001',
  beneficiaryAddress: {
    street: 'Business Street 123',
    city: 'Bratislava 81108'
  }
});

寄付 (固定金額なし)

// 任意の寄付の場合は金額を省略できます
const buffer = await generatePayBySquare({
  iban: 'SK9611000000002918599669',
  beneficiaryName: 'Charity Organization',
  paymentNote: 'Voluntary donation'
});

カスタムQRコードスタイル

const buffer = await generatePayBySquare(
  {
    iban: 'SK9611000000002918599669',
    beneficiaryName: 'Shop Name',
    amount: 99.99
  },
  {
    width: 500,                    // より大きなQRコード
    margin: 2,                     // より小さな余白
    errorCorrectionLevel: 'H',     // 高い誤り訂正
    color: {
      dark: '#1E40AF',             // 青いQRコード
      light: '#FFFFFF'             // 白い背景
    }
  }
);

直接ファイルに保存

import { generatePayBySquareToFile } from 'paybysquare-generator';

await generatePayBySquareToFile(
  {
    iban: 'SK9611000000002918599669',
    beneficiaryName: 'Recipient',
    amount: 25.00
  },
  './payment.png'
);

エラーハンドリング

import {
  generatePayBySquare,
  ValidationError,
  EncodingError,
  GenerationError
} from 'paybysquare-generator';

try {
  const buffer = await generatePayBySquare({
    iban: 'INVALID',
    beneficiaryName: 'Test'
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof EncodingError) {
    console.error('Encoding failed:', error.message);
  } else if (error instanceof GenerationError) {
    console.error('QR generation failed:', error.message);
  }
}

QRコードのデコード

import { decodePayBySquare } from 'paybysquare-generator';
import { readFile } from 'fs/promises';

// ファイルからQRコードを読み取る
const qrBuffer = await readFile('./payment-qr.png');

// 支払いデータをデコードする
const paymentData = await decodePayBySquare(qrBuffer);

console.log('IBAN:', paymentData.iban);
console.log('Beneficiary:', paymentData.beneficiaryName);
console.log('Amount:', paymentData.amount, paymentData.currency);
console.log('Variable Symbol:', paymentData.variableSymbol);

簡単なコンプライアンスチェック

import { isCompliant } from 'paybysquare-generator';

const paymentData = {
  iban: 'SK9611000000002918599669',
  beneficiaryName: 'Test Merchant',
  amount: 100,
  currency: 'EUR'
};

if (isCompliant(paymentData)) {
  console.log('✓ Payment data is valid');
} else {
  console.log('✗ Payment data has issues');
}

詳細なコンプライアンスレポート

import { checkCompliance } from 'paybysquare-generator';

const paymentData = {
  iban: 'SK9999999999999999999999',  // 無効なチェックサム
  beneficiaryName: 'Test',
  amount: -50,  // 負の金額
  variableSymbol: 'ABC123',  // 数字のみである必要があります
  swift: 'INVALID'  // 無効なBIC形式
};

const report = await checkCompliance(paymentData);

console.log('Compliant:', report.isCompliant);
console.log('\nErrors:');
report.errors.forEach(err => {
  console.log(`  [${err.severity}] ${err.field}: ${err.message}`);
});

console.log('\nValidation Details:');
console.log('  IBAN valid:', report.details.ibanValid);
console.log('  Fields valid:', report.details.fieldsValid);
console.log('  Banking standards valid:', report.details.bankingStandardsValid);
console.log('  Total issues:', report.details.totalIssues);

ラウンドトリップ検証

import { verifyRoundTrip } from 'paybysquare-generator';

const originalData = {
  iban: 'SK9611000000002918599669',
  beneficiaryName: 'Test Company',
  amount: 250.75,
  currency: 'EUR',
  variableSymbol: '123456',
  paymentNote: 'Testing round-trip'
};

const result = await verifyRoundTrip(originalData);

if (result.isLossless) {
  console.log('✓ Data perfectly preserved through encode/decode cycle!');
} else {
  console.log('✗ Data loss detected:');
  result.differences.forEach(diff => {
    console.log(`  ${diff.field}:`);
    console.log(`    Original: ${diff.original}`);
    console.log(`    Decoded:  ${diff.decoded}`);
  });
}

検証ルール

このライブラリは、すべての入力に対して包括的な検証を実行します。

• IBAN: 必須、有効な形式（2文字の国コード + 2桁 + 11 - 30の英数字）である必要があります
• Beneficiary Name: 必須、最大70文字
• Amount: オプション、指定された場合は正数で有限である必要があります
• Currency: オプション、3文字のISO 4217コードである必要があります（デフォルト: EUR）
• Variable Symbol: オプション、1 - 10桁の数字のみ
• Constant Symbol: オプション、1 - 4桁の数字のみ
• Specific Symbol: オプション、1 - 10桁の数字のみ
• Payment Note: オプション、最大140文字
• Due Date: オプション、ISO 8601形式（YYYY-MM-DD）である必要があります
• Address Fields: オプション、それぞれ最大70文字

サンプルの実行

リポジトリには包括的なサンプルが含まれています。

git clone https://github.com/yourusername/paybysquare-generator
cd paybysquare-generator
npm install
npm run example

これにより、さまざまな使用例を示すいくつかのサンプルQRコードが生成されます。

テストの実行

npm test              # テストを1回実行
npm run test:watch    # ウォッチモードでテストを実行
npm run test:coverage # カバレッジレポート付きでテストを実行

ソースからのビルド

npm run build         # TypeScriptをdist/にコンパイル

PayBySquare標準

このライブラリは、スロバキア銀行協会（SBA）によって定義されたPayBySquare標準バージョン1.1.0を実装しています。詳細については、以下を参照してください。

• PayBySquare公式サイト
• PayBySquare仕様書 (PDF)

依存関係

本番環境

• bysquare - 公式PayBySquareエンコーダ/デコーダ
• qrcode - QRコードのPNG生成器
• jsqr - QRコードスキャナー（純粋なJavaScript）
• jimp - QRコードデコードのための画像処理
• ibantools - mod-97チェックサムを使用したIBAN検証

TypeScriptサポート

このライブラリはTypeScriptで記述されており、完全な型定義が含まれています。すべての型は便利にエクスポートされています。

import type {
  // 入力/出力型
  PayBySquareInput,
  BeneficiaryAddress,
  GenerationOptions,

  // コンプライアンス型
  ComplianceResult,
  ComplianceIssue,
  ComplianceDetails,
  RoundTripResult,
  FieldDifference
} from 'paybysquare-generator';

// エラークラスもエクスポートされています
import {
  PayBySquareError,
  ValidationError,
  EncodingError,
  GenerationError,
  DecodingError
} from 'paybysquare-generator';

MCPサーバー

このライブラリには、Claudeや他のMCPクライアントにすべての機能を公開する Model Context Protocol (MCP) サーバー が含まれています。

利用可能なツール

• generate_paybysquare - 支払いデータからQRコードを生成します（ファイルに保存し、ファイルパスを返します）
  • 必須: beneficiaryName (受取人のフルネーム)
  • 推奨: swift (国際送金のためのBICコード)
  • オプション: outputDirectory (カスタムの保存場所、デフォルト: ~/paybysquare-qr-codes/)
• decode_paybysquare - QRコードを支払いデータにデコードします（base64エンコードされたPNGから）
• check_compliance - 詳細なエラーレポート付きで支払いデータのコンプライアンスを検証します
• verify_roundtrip - 損失のないエンコード/デコードを検証します（データの整合性チェック）

クイックセットアップ

1. サーバーをビルドします:

   npm run build:mcp
   

2. Claude Desktopを設定します: claude_desktop_config.json に以下を追加します。

   {
     "mcpServers": {
       "paybysquare": {
         "command": "node",
         "args": ["/absolute/path/to/paybysquare/dist/mcp-server/index.js"]
       }
     }
   }
   

3. Claude Desktopを再起動します

Claudeでの使用例

設定が完了すると、自然言語を使用できます。

Generate a PayBySquare QR code for:
- IBAN: SK9611000000002918599669
- Beneficiary: John Doe
- Amount: 100.50 EUR
- SWIFT: TATRSKBX
- Payment note: Invoice #12345

ClaudeはQRコードを生成し、ファイルに保存して、以下のように返します。

✓ QR code generated successfully!
File saved to: /Users/username/paybysquare-qr-codes/paybysquare-1705331234567-a3f2.png

Decode this PayBySquare QR code and tell me the payment details
[Attach image]

Check if this payment data is compliant with banking standards:
- IBAN: SK9611000000002918599669
- Beneficiary: Test Company
- Amount: 250 EUR
- SWIFT: TATRSKBX

注意: QRコードはデフォルトで ~/paybysquare-qr-codes/ に自動的に保存されます。outputDirectory オプションを使用して、カスタムのディレクトリを指定できます。

詳細なMCPサーバーのドキュメントについては、mcp-server/README.md を参照してください。

📄 ライセンス

MIT

コントリビュート

コントリビューションは大歓迎です！プルリクエストを送信してください。

関連プロジェクト

• bysquare - 公式PayBySquareエンコーダライブラリ
• node-qrcode - Node.js用のQRコード生成器

サポート

問題が発生した場合は、または質問がある場合は、GitHubのissueを開いてください。

Made with ❤️ for the Slovak developer community