@zentring/zinvoice 0.1.0 → 0.1.1

package/README.md

@@ -193,8 +193,7 @@ if (client.supports(Capability.CARRIER)) {
 }
 
 if (client.supports(Capability.EXCHANGE)) {
-  // 支援換開發票
-  await client.invoices.exchange(...);
+  // 支援 B2B 發票交換
 }
 
 // 取得所有支援的能力
@@ -213,7 +212,7 @@ console.log(capabilities);
 | `DONATION` | 捐贈 | ✓ |
 | `ALLOWANCE` | 折讓 | ✓ |
 | `VOID` | 作廢 | ✓ |
-| `EXCHANGE` | 換開 | ✓ |
+| `EXCHANGE` | B2B 交換 | ✓ |
 | `PRINT` | 列印格式 | ✓ |
 
 ## 錯誤處理
@@ -246,11 +245,51 @@ try {
 }
 ```
 
+## 自訂系統商
+
+如果您使用的加值中心尚未內建支援，可以自行實作：
+
+```typescript
+import { Zinvoice, Capability } from '@zentring/zinvoice';
+
+const client = Zinvoice.custom({
+  name: '自訂系統商',
+  capabilities: [Capability.B2C, Capability.QUERY, Capability.LIST],
+  invoices: {
+    issue: async (invoice) => {
+      // 實作開立發票邏輯
+      return {
+        invoiceNumber: InvoiceNumber.create('AA12345678'),
+        invoiceTime: new Date(),
+        randomNumber: '1234',
+        barcode: '...',
+        qrcodeLeft: '...',
+        qrcodeRight: '...',
+      };
+    },
+    findByNumber: async (number) => { /* ... */ },
+    findByOrderId: async (orderId) => { /* ... */ },
+    getStatus: async (numbers) => { /* ... */ },
+    list: async (query) => { /* ... */ },
+  },
+});
+```
+
+**重要：** 註冊的 Capability 必須實作對應的方法，否則會拋出 `ValidationError`：
+
+| Capability | 必須實作 |
+|------------|----------|
+| `B2C` / `B2B` | `invoices.issue` |
+| `VOID` | `invoices.void` |
+| `QUERY` | `invoices.findByNumber`, `findByOrderId`, `getStatus` |
+| `LIST` | `invoices.list` |
+| `ALLOWANCE` | `allowances.issue`, `void`, `findByNumber`, `findByInvoiceNumber`, `getStatus`, `list` |
+
 ## 支援的加值中心
 
 | Provider | 狀態 | 說明 |
 |----------|:----:|------|
-| `Provider.AMEGO` | ✓ | 光貿資訊 |
+| `Provider.AMEGO` | ✓ | 光貿科技 |
 
 ## 測試帳號
 

package/dist/index.cjs

@@ -35,7 +35,7 @@ var PROVIDER_CAPABILITIES = {
   ])
 };
 var PROVIDER_NAMES = {
-  ["amego" /* AMEGO */]: "\u5149\u8CBF\u8CC7\u8A0A"
+  ["amego" /* AMEGO */]: "\u5149\u8CBF\u79D1\u6280"
 };
 
 // src/errors/index.ts
@@ -2654,17 +2654,100 @@ var AmegoAllowanceService = class {
   }
 };
 
+// src/CustomProvider.ts
+var CAPABILITY_REQUIREMENTS = {
+  ["b2c" /* B2C */]: { invoices: ["issue"] },
+  ["b2b" /* B2B */]: { invoices: ["issue"] },
+  ["carrier" /* CARRIER */]: {},
+  // Part of issue, no separate handler
+  ["donation" /* DONATION */]: {},
+  // Part of issue, no separate handler
+  ["void" /* VOID */]: { invoices: ["void"] },
+  ["query" /* QUERY */]: { invoices: ["findByNumber", "findByOrderId", "getStatus"] },
+  ["list" /* LIST */]: { invoices: ["list"] },
+  ["allowance" /* ALLOWANCE */]: { allowances: ["issue", "void", "findByNumber", "findByInvoiceNumber", "getStatus", "list"] },
+  ["exchange" /* EXCHANGE */]: {},
+  // TODO: Add exchange handlers when implemented
+  ["print" /* PRINT */]: {}
+  // Part of issue result, no separate handler
+};
+function validateCustomProviderConfig(config) {
+  const missingHandlers = [];
+  for (const capability of config.capabilities) {
+    const requirements = CAPABILITY_REQUIREMENTS[capability];
+    if (requirements.invoices) {
+      for (const handler of requirements.invoices) {
+        if (!config.invoices?.[handler]) {
+          missingHandlers.push(`invoices.${handler} (required for ${capability})`);
+        }
+      }
+    }
+    if (requirements.allowances) {
+      for (const handler of requirements.allowances) {
+        if (!config.allowances?.[handler]) {
+          missingHandlers.push(`allowances.${handler} (required for ${capability})`);
+        }
+      }
+    }
+  }
+  if (missingHandlers.length > 0) {
+    throw new ValidationError(
+      "customProvider",
+      `Missing required handlers for registered capabilities:
+  - ${missingHandlers.join("\n  - ")}`
+    );
+  }
+}
+function createCustomInvoiceService(providerName, capabilities, handlers = {}) {
+  const notImplemented = (method, capability) => {
+    return async () => {
+      if (!capabilities.has(capability)) {
+        throw new UnsupportedCapabilityError(capability, providerName);
+      }
+      throw new Error(`${providerName}: ${method} is not implemented`);
+    };
+  };
+  return {
+    issue: handlers.issue ?? notImplemented("issue", "b2c" /* B2C */),
+    void: handlers.void ?? notImplemented("void", "void" /* VOID */),
+    findByNumber: handlers.findByNumber ?? notImplemented("findByNumber", "query" /* QUERY */),
+    findByOrderId: handlers.findByOrderId ?? notImplemented("findByOrderId", "query" /* QUERY */),
+    getStatus: handlers.getStatus ?? notImplemented("getStatus", "query" /* QUERY */),
+    list: handlers.list ?? notImplemented("list", "list" /* LIST */)
+  };
+}
+function createCustomAllowanceService(providerName, capabilities, handlers = {}) {
+  const notImplemented = (method) => {
+    return async () => {
+      if (!capabilities.has("allowance" /* ALLOWANCE */)) {
+        throw new UnsupportedCapabilityError("allowance" /* ALLOWANCE */, providerName);
+      }
+      throw new Error(`${providerName}: ${method} is not implemented`);
+    };
+  };
+  return {
+    issue: handlers.issue ?? notImplemented("issue"),
+    void: handlers.void ?? notImplemented("void"),
+    findByNumber: handlers.findByNumber ?? notImplemented("findByNumber"),
+    findByInvoiceNumber: handlers.findByInvoiceNumber ?? notImplemented("findByInvoiceNumber"),
+    getStatus: handlers.getStatus ?? notImplemented("getStatus"),
+    list: handlers.list ?? notImplemented("list")
+  };
+}
+
 // src/Zinvoice.ts
 var Zinvoice = class _Zinvoice {
   _provider;
+  _providerName;
   _invoiceService;
   _allowanceService;
   _capabilities;
-  constructor(provider, invoiceService, allowanceService) {
+  constructor(provider, providerName, capabilities, invoiceService, allowanceService) {
     this._provider = provider;
+    this._providerName = providerName;
+    this._capabilities = capabilities;
     this._invoiceService = invoiceService;
     this._allowanceService = allowanceService;
-    this._capabilities = PROVIDER_CAPABILITIES[provider];
   }
   /**
    * Create a Zinvoice client
@@ -2689,7 +2772,60 @@ var Zinvoice = class _Zinvoice {
     };
     const invoiceService = new AmegoInvoiceService(amegoConfig);
     const allowanceService = new AmegoAllowanceService(amegoConfig);
-    return new _Zinvoice("amego" /* AMEGO */, invoiceService, allowanceService);
+    return new _Zinvoice(
+      "amego" /* AMEGO */,
+      PROVIDER_NAMES["amego" /* AMEGO */],
+      PROVIDER_CAPABILITIES["amego" /* AMEGO */],
+      invoiceService,
+      allowanceService
+    );
+  }
+  /**
+   * Create a custom Zinvoice client with user-provided handlers
+   *
+   * @example
+   * ```typescript
+   * const client = Zinvoice.custom({
+   *   name: '自訂系統商',
+   *   capabilities: [Capability.B2C, Capability.QUERY, Capability.LIST],
+   *   invoices: {
+   *     issue: async (invoice) => {
+   *       // 實作開立發票邏輯
+   *       return { invoiceNumber, invoiceTime, randomNumber };
+   *     },
+   *     findByNumber: async (number) => {
+   *       // 實作查詢邏輯
+   *       return invoice;
+   *     },
+   *     findByOrderId: async (orderId) => { ... },
+   *     getStatus: async (numbers) => { ... },
+   *     list: async (query) => { ... },
+   *   },
+   * });
+   * ```
+   *
+   * @throws {ValidationError} If required handlers are not implemented for registered capabilities
+   */
+  static custom(config) {
+    validateCustomProviderConfig(config);
+    const capabilities = new Set(config.capabilities);
+    const invoiceService = createCustomInvoiceService(
+      config.name,
+      capabilities,
+      config.invoices
+    );
+    const allowanceService = createCustomAllowanceService(
+      config.name,
+      capabilities,
+      config.allowances
+    );
+    return new _Zinvoice(
+      "custom",
+      config.name,
+      capabilities,
+      invoiceService,
+      allowanceService
+    );
   }
   /**
    * Get the invoice service
@@ -2705,6 +2841,7 @@ var Zinvoice = class _Zinvoice {
   }
   /**
    * Get the current provider
+   * Returns 'custom' for custom providers
    */
   get provider() {
     return this._provider;
@@ -2713,7 +2850,7 @@ var Zinvoice = class _Zinvoice {
    * Get the provider display name
    */
   get providerName() {
-    return PROVIDER_NAMES[this._provider];
+    return this._providerName;
   }
   /**
    * Check if a capability is supported
@@ -2732,9 +2869,15 @@ var Zinvoice = class _Zinvoice {
    */
   requireCapability(capability) {
     if (!this.supports(capability)) {
-      throw new UnsupportedCapabilityError(capability, this._provider);
+      throw new UnsupportedCapabilityError(capability, this._providerName);
     }
   }
+  /**
+   * Check if this is a custom provider
+   */
+  get isCustom() {
+    return this._provider === "custom";
+  }
 };
 
 // src/domain/shared/CarrierCode.ts