@kanorio/sdk 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +41 -2
  2. package/dist/customer-oauth.d.ts +21 -21
  3. package/dist/customer-oauth.js +12 -12
  4. package/dist/customer.d.ts +22 -22
  5. package/dist/customer.js +20 -11
  6. package/dist/delivery.d.ts +9 -9
  7. package/dist/delivery.js +6 -6
  8. package/dist/edge.d.ts +25 -21
  9. package/dist/edge.js +36 -20
  10. package/dist/forms.d.ts +33 -14
  11. package/dist/forms.js +20 -14
  12. package/dist/generated/delivery.d.ts +564 -13
  13. package/dist/generated/management.d.ts +790 -81
  14. package/dist/http.d.ts +13 -13
  15. package/dist/http.js +8 -8
  16. package/dist/image.d.ts +77 -0
  17. package/dist/image.js +78 -0
  18. package/dist/index.d.ts +2 -1
  19. package/dist/index.js +4 -3
  20. package/dist/locales.d.ts +22 -22
  21. package/dist/locales.js +12 -12
  22. package/dist/management.d.ts +5 -5
  23. package/dist/management.js +3 -3
  24. package/dist/next.d.ts +66 -0
  25. package/dist/next.js +58 -0
  26. package/dist/paginate.d.ts +3 -3
  27. package/dist/paginate.js +3 -3
  28. package/dist/preview.d.ts +13 -13
  29. package/dist/preview.js +11 -11
  30. package/dist/protection.d.ts +18 -18
  31. package/dist/protection.js +11 -11
  32. package/dist/revalidate.d.ts +22 -22
  33. package/dist/revalidate.js +14 -14
  34. package/dist/seo.d.ts +137 -21
  35. package/dist/seo.js +113 -21
  36. package/dist/server-key.d.ts +2 -2
  37. package/dist/server-key.js +2 -2
  38. package/dist/shared/api/delivery/cache-tags.d.ts +41 -39
  39. package/dist/shared/api/delivery/cache-tags.js +36 -34
  40. package/dist/shared/api/server-key.d.ts +32 -28
  41. package/dist/shared/api/server-key.js +41 -33
  42. package/dist/shared/business-registry/attribution.d.ts +5 -5
  43. package/dist/shared/business-registry/attribution.js +4 -4
  44. package/dist/shared/business-registry/define.d.ts +1 -1
  45. package/dist/shared/business-registry/define.js +1 -1
  46. package/dist/shared/business-registry/formats/eu-vat.js +4 -4
  47. package/dist/shared/business-registry/formats/hk-br.d.ts +2 -2
  48. package/dist/shared/business-registry/formats/hk-br.js +4 -4
  49. package/dist/shared/business-registry/formats/jp-trn.d.ts +3 -3
  50. package/dist/shared/business-registry/formats/jp-trn.js +4 -4
  51. package/dist/shared/business-registry/formats/kr-brn.d.ts +2 -2
  52. package/dist/shared/business-registry/formats/kr-brn.js +3 -3
  53. package/dist/shared/business-registry/formats/my.d.ts +3 -3
  54. package/dist/shared/business-registry/formats/my.js +4 -4
  55. package/dist/shared/business-registry/formats/sg-uen.js +4 -4
  56. package/dist/shared/business-registry/formats/tw-vat.d.ts +5 -5
  57. package/dist/shared/business-registry/formats/tw-vat.js +6 -6
  58. package/dist/shared/business-registry/index.js +1 -1
  59. package/dist/shared/business-registry/lookup-wire.d.ts +9 -9
  60. package/dist/shared/business-registry/lookup-wire.js +4 -4
  61. package/dist/shared/business-registry/normalize.d.ts +3 -3
  62. package/dist/shared/business-registry/normalize.js +4 -4
  63. package/dist/shared/business-registry/registry.d.ts +9 -9
  64. package/dist/shared/business-registry/registry.js +13 -13
  65. package/dist/shared/business-registry/types.d.ts +20 -20
  66. package/dist/shared/business-registry/types.js +6 -6
  67. package/dist/shared/localization/locale-path.d.ts +18 -18
  68. package/dist/shared/localization/locale-path.js +18 -18
  69. package/dist/shared/localization/request-locale.d.ts +16 -16
  70. package/dist/shared/localization/request-locale.js +13 -13
  71. package/dist/shared/seo/alternates.d.ts +26 -26
  72. package/dist/shared/seo/alternates.js +18 -18
  73. package/dist/shared/types/forms-logic.d.ts +28 -28
  74. package/dist/shared/types/forms-logic.js +27 -27
  75. package/dist/shared/types/number-input.d.ts +2 -2
  76. package/dist/shared/types/number-input.js +3 -3
  77. package/dist/shared/utils/redirect-matching.d.ts +33 -24
  78. package/dist/shared/utils/redirect-matching.js +73 -40
  79. package/dist/typed.d.ts +5 -5
  80. package/dist/typed.js +3 -3
  81. package/package.json +15 -10
@@ -1,10 +1,10 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  import { defineTaxIdFormat } from "../define.js";
3
3
  import { stripSeparators } from "../normalize.js";
4
4
  /**
5
- * 馬來西亞稅號。兩種都依公開範例整理、尚未對照 LHDN 與關稅局的官方文件核實,只警示不擋。
6
- * - my_itn:所得稅號(TIN),類別字母 1–2 碼+數字(如 C 1234567890);電子發票(MyInvois)用的就是它
7
- * - my_sst:銷售與服務稅登記號(如 A12-3456-78912345)
5
+ * Malaysian tax IDs. Both follow public examples and are not verified against the official documentation of LHDN and Customs yet, so they only warn and never block.
6
+ * - my_itn: income tax number (TIN), a 1 to 2 letter category plus digits (for example C 1234567890); this is the one e-invoicing (MyInvois) uses
7
+ * - my_sst: Sales and Service Tax registration number (for example A12-3456-78912345)
8
8
  */
9
9
  export const myItn = defineTaxIdFormat({
10
10
  type: "my_itn",
@@ -1,10 +1,10 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  import { defineTaxIdFormat } from "../define.js";
3
3
  import { stripSeparators } from "../normalize.js";
4
4
  /**
5
- * 新加坡 UEN:三種格式——商號(8 碼數字+字母)、本地公司(西元年 4 碼+5 碼數字+字母)、
6
- * 其他實體(T/S/R+年 2 碼+類別 2 字母+4 碼數字+字母)。
7
- * 結尾的檢查字母演算法官方沒有公開,這裡只驗格式;格式依 ACRA 的公開說明整理、尚未逐條核實,只警示不擋。
5
+ * Singapore UEN, in three formats: businesses (8 digits plus a letter), local companies (a 4-digit year, 5 digits and a letter)
6
+ * and other entities (T, S or R, a 2-digit year, a 2-letter category, 4 digits and a letter).
7
+ * The algorithm of the trailing check letter is not published, so only the format is validated; the formats follow ACRA's public notes and are not verified line by line yet, so this only warns and never blocks.
8
8
  */
9
9
  const SG_UEN = [/^\d{8}[A-Z]$/, /^(18|19|20)\d{2}\d{5}[A-Z]$/, /^[TSR]\d{2}[A-Z]{2}\d{4}[A-Z]$/];
10
10
  export const sgUen = defineTaxIdFormat({
@@ -1,10 +1,10 @@
1
1
  /**
2
- * 台灣統一編號:8 碼數字+檢查碼(財政部 112 年 4 月新制)。
2
+ * Taiwan's Unified Business Number: 8 digits including a check digit (the Ministry of Finance's rule revised in April 2023).
3
3
  *
4
- * 各位數乘上權重 [1,2,1,2,1,2,4,1],乘積為兩位數時取十位+個位,加總後能被 5 整除即有效
5
- * (舊制是被 10 整除;財政部為擴增號碼空間放寬,新制配發的 04595252、10458570、62176616 在舊制會被誤判)。
6
- * 例外:第 7 碼是 7 時(乘積 28 可視為 10 或 1),總和加 1 能被 5 整除也有效。
7
- * 來源:財政部財政資訊中心「營利事業統一編號檢查碼邏輯修正說明」。
4
+ * Each digit is multiplied by the weights [1,2,1,2,1,2,4,1]; a two-digit product contributes its tens digit plus its ones digit, and the number is valid when the sum is divisible by 5
5
+ * (the old rule required divisibility by 10; the ministry relaxed it to enlarge the number space, and 04595252, 10458570 and 62176616, issued under the new rule, would be misjudged by the old one).
6
+ * Exception: when the 7th digit is 7 (the product 28 can count as 10 or 1), the number is also valid when the sum plus 1 is divisible by 5.
7
+ * Source: the Fiscal Information Agency (Ministry of Finance, Taiwan), notice on the revised check digit logic for the Unified Business Number.
8
8
  */
9
9
  export declare function isValidTwVat(normalized: string): boolean;
10
10
  export declare const twVat: import("../types.js").TaxIdFormatDefinition;
@@ -1,15 +1,15 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  import { defineTaxIdFormat } from "../define.js";
3
3
  import { stripSeparators } from "../normalize.js";
4
4
  const WEIGHTS = [1, 2, 1, 2, 1, 2, 4, 1];
5
5
  const sumOfDigits = (n) => (n < 10 ? n : Math.floor(n / 10) + (n % 10));
6
6
  /**
7
- * 台灣統一編號:8 碼數字+檢查碼(財政部 112 年 4 月新制)。
7
+ * Taiwan's Unified Business Number: 8 digits including a check digit (the Ministry of Finance's rule revised in April 2023).
8
8
  *
9
- * 各位數乘上權重 [1,2,1,2,1,2,4,1],乘積為兩位數時取十位+個位,加總後能被 5 整除即有效
10
- * (舊制是被 10 整除;財政部為擴增號碼空間放寬,新制配發的 04595252、10458570、62176616 在舊制會被誤判)。
11
- * 例外:第 7 碼是 7 時(乘積 28 可視為 10 或 1),總和加 1 能被 5 整除也有效。
12
- * 來源:財政部財政資訊中心「營利事業統一編號檢查碼邏輯修正說明」。
9
+ * Each digit is multiplied by the weights [1,2,1,2,1,2,4,1]; a two-digit product contributes its tens digit plus its ones digit, and the number is valid when the sum is divisible by 5
10
+ * (the old rule required divisibility by 10; the ministry relaxed it to enlarge the number space, and 04595252, 10458570 and 62176616, issued under the new rule, would be misjudged by the old one).
11
+ * Exception: when the 7th digit is 7 (the product 28 can count as 10 or 1), the number is also valid when the sum plus 1 is divisible by 5.
12
+ * Source: the Fiscal Information Agency (Ministry of Finance, Taiwan), notice on the revised check digit logic for the Unified Business Number.
13
13
  */
14
14
  export function isValidTwVat(normalized) {
15
15
  if (!/^\d{8}$/.test(normalized))
@@ -1,4 +1,4 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  export * from "./types.js";
3
3
  export * from "./define.js";
4
4
  export * from "./normalize.js";
@@ -1,8 +1,8 @@
1
1
  /**
2
- * 稅號登記查詢的回應形狀(綁定情境的查詢端點 → 前台的稅號輸入元件)。零依賴,資料夾內只用相對 import。
2
+ * Response shape of a tax ID registry lookup (from the context-bound lookup endpoint to the storefront's tax ID input). No dependencies; only relative imports inside this folder.
3
3
  *
4
- * 這個查詢只用來「自動帶入名稱」與「標示」,任何結果都不能拿來擋送出:
5
- * `NOT_FOUND` 只代表公開資料裡沒查到,不代表稅號無效。
4
+ * The lookup is only for prefilling the name and labeling; no result may ever block a submit:
5
+ * `NOT_FOUND` only means the public data has no match, not that the tax ID is invalid.
6
6
  */
7
7
  import type { RegistryAttributionWire, TaxIdType } from "./types.js";
8
8
  export type TaxIdLookupStatus = "VERIFIED" | "NOT_FOUND" | "VALID_FORMAT" | "UNAVAILABLE";
@@ -11,21 +11,21 @@ export interface TaxIdLookupWire {
11
11
  status: TaxIdLookupStatus;
12
12
  country: string;
13
13
  type: TaxIdType;
14
- /** 正規化後的稅號 */
14
+ /** The normalized tax ID */
15
15
  normalized: string;
16
- /** `VERIFIED` 時才有 */
16
+ /** Present only when `VERIFIED` */
17
17
  registry?: {
18
18
  name: string;
19
19
  address?: string;
20
- /** ACTIVE/SUSPENDED/CLOSED/UNKNOWN(來源沒給就是 UNKNOWN,不要當成營業中) */
20
+ /** ACTIVE, SUSPENDED, CLOSED or UNKNOWN (UNKNOWN when the source does not say; do not treat it as active) */
21
21
  registryStatus: string;
22
- /** 名稱含造字、多數字型顯示成方框:不要自動帶入,讓對方自己填 */
22
+ /** The name contains custom characters most fonts show as boxes: do not prefill it, let the person type it */
23
23
  nameHasPrivateUse?: boolean;
24
24
  };
25
- /** 用到政府開放資料時必須一併顯示的來源標示 */
25
+ /** The attribution that must be shown whenever government open data is used */
26
26
  attribution?: RegistryAttributionWire;
27
27
  }
28
- /** 查不了(情境不符、被限流、格式不對);前台一律當成「沒有可帶入的資料」,不顯示錯誤 */
28
+ /** The lookup could not run (wrong context, rate limited, bad format); the storefront always treats it as nothing to prefill and shows no error */
29
29
  export interface TaxIdLookupUnavailableWire {
30
30
  ok: false;
31
31
  reason: "invalid_tax_id" | "unavailable" | "rate_limited";
@@ -1,8 +1,8 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  /**
3
- * 稅號登記查詢的回應形狀(綁定情境的查詢端點 → 前台的稅號輸入元件)。零依賴,資料夾內只用相對 import。
3
+ * Response shape of a tax ID registry lookup (from the context-bound lookup endpoint to the storefront's tax ID input). No dependencies; only relative imports inside this folder.
4
4
  *
5
- * 這個查詢只用來「自動帶入名稱」與「標示」,任何結果都不能拿來擋送出:
6
- * `NOT_FOUND` 只代表公開資料裡沒查到,不代表稅號無效。
5
+ * The lookup is only for prefilling the name and labeling; no result may ever block a submit:
6
+ * `NOT_FOUND` only means the public data has no match, not that the tax ID is invalid.
7
7
  */
8
8
  export {};
@@ -1,7 +1,7 @@
1
1
  /**
2
- * 稅號輸入的共通清理:全形轉半形(NFKC)、去掉空白、轉大寫。
3
- * 各類型的 normalize 再處理自己的分隔符號與前綴。
2
+ * Shared cleanup of tax ID input: full-width to half-width (NFKC), whitespace removed, uppercased.
3
+ * Each type's normalize then handles its own separators and prefix.
4
4
  */
5
5
  export declare function cleanTaxIdInput(raw: string): string;
6
- /** 去掉常見分隔符號(橫線、點、斜線) */
6
+ /** Removes common separators (hyphens, dots, slashes) */
7
7
  export declare function stripSeparators(value: string): string;
@@ -1,12 +1,12 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  /**
3
- * 稅號輸入的共通清理:全形轉半形(NFKC)、去掉空白、轉大寫。
4
- * 各類型的 normalize 再處理自己的分隔符號與前綴。
3
+ * Shared cleanup of tax ID input: full-width to half-width (NFKC), whitespace removed, uppercased.
4
+ * Each type's normalize then handles its own separators and prefix.
5
5
  */
6
6
  export function cleanTaxIdInput(raw) {
7
7
  return raw.normalize("NFKC").replace(/\s+/g, "").toUpperCase();
8
8
  }
9
- /** 去掉常見分隔符號(橫線、點、斜線) */
9
+ /** Removes common separators (hyphens, dots, slashes) */
10
10
  export function stripSeparators(value) {
11
11
  return value.replace(/[-./]/g, "");
12
12
  }
@@ -2,15 +2,15 @@ import type { TaxIdFormatDefinition, TaxIdFormatResult, TaxIdType } from "./type
2
2
  export declare const TAX_ID_FORMATS: readonly TaxIdFormatDefinition[];
3
3
  export declare function isTaxIdType(value: unknown): value is TaxIdType;
4
4
  export declare function getTaxIdFormat(type: TaxIdType): TaxIdFormatDefinition;
5
- /** 這個國家可用的稅號類型;第一個是預設。沒有登錄的國家回空陣列(呼叫端當成自由文字) */
5
+ /** The tax ID types available for a country; the first is the default. An unregistered country returns an empty array (the caller treats the value as free text) */
6
6
  export declare function listTaxIdTypes(country: string): readonly TaxIdType[];
7
- /** 有登錄稅號格式的國家(稅號題的國家選單用) */
7
+ /** Countries with a registered tax ID format (for the country menu of a tax ID question) */
8
8
  export declare function listTaxIdCountries(): readonly string[];
9
9
  /**
10
- * 驗證並正規化一個稅號。
11
- * - 沒指定 type 時用該國的預設類型
12
- * - 國家沒有登錄任何類型、或指定的類型不屬於該國 → `UNSUPPORTED`(enforcement 為 warn:呼叫端當成自由文字收下)
13
- * - 格式或檢查碼不符 → 依該類型的 enforcement 決定要不要擋,見 `isBlockingTaxIdIssue`
10
+ * Validates and normalizes a tax ID.
11
+ * - Without a type, the country's default type is used
12
+ * - A country with no registered type, or a type that does not belong to the country: `UNSUPPORTED` (enforcement is warn: the caller accepts it as free text)
13
+ * - A format or check digit mismatch: whether it blocks depends on the type's enforcement, see `isBlockingTaxIdIssue`
14
14
  */
15
15
  export declare function validateTaxIdFormat(input: {
16
16
  country: string;
@@ -18,9 +18,9 @@ export declare function validateTaxIdFormat(input: {
18
18
  value: string;
19
19
  }): TaxIdFormatResult;
20
20
  /**
21
- * 檢查一個「已經是正規化形式」的值,不做任何清理。給值要原樣存檔或送給第三方的 schema 用
22
- * (例如金流開通表單:放行帶分隔符號的寫法卻原樣送出,對方會退件)。合法回 null。
21
+ * Checks a value that is already in normalized form, with no cleanup. For schemas whose value is stored or sent to a third party as is
22
+ * (a payment onboarding form, for example: accepting a value with separators and sending it unchanged gets it rejected). Returns null when valid.
23
23
  */
24
24
  export declare function checkNormalizedTaxId(type: TaxIdType, country: string, value: string): null | "FORMAT" | "CHECKSUM";
25
- /** 這個結果要不要擋下(格式錯且該類型的規則已核實)。`warn` 與 `UNSUPPORTED` 不擋 */
25
+ /** Whether this result should block (the format is wrong and the type's rules are verified). `warn` and `UNSUPPORTED` do not block */
26
26
  export declare function isBlockingTaxIdIssue(result: TaxIdFormatResult): boolean;
@@ -1,8 +1,8 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  /**
3
- * 稅號格式的登錄表與唯一入口 `validateTaxIdFormat`。
4
- * 新增國家:寫一個 formats/<類型>.ts、在 TAX_ID_FORMATS 加一筆;UI 與契約不需要改(沒有國別分支)。
5
- * 同一國有多種類型時,陣列裡排前面的是預設。
3
+ * The registry of tax ID formats and the single entry point `validateTaxIdFormat`.
4
+ * To add a country: write formats/<type>.ts and add an entry to TAX_ID_FORMATS; the UI and the contract need no change (there are no per-country branches).
5
+ * When a country has several types, the first in the array is the default.
6
6
  */
7
7
  import { euVat } from "./formats/eu-vat.js";
8
8
  import { hkBr } from "./formats/hk-br.js";
@@ -20,20 +20,20 @@ export function isTaxIdType(value) {
20
20
  export function getTaxIdFormat(type) {
21
21
  return BY_TYPE.get(type);
22
22
  }
23
- /** 這個國家可用的稅號類型;第一個是預設。沒有登錄的國家回空陣列(呼叫端當成自由文字) */
23
+ /** The tax ID types available for a country; the first is the default. An unregistered country returns an empty array (the caller treats the value as free text) */
24
24
  export function listTaxIdTypes(country) {
25
25
  const code = country.toUpperCase();
26
26
  return TAX_ID_FORMATS.filter((format) => format.countries.includes(code)).map((format) => format.type);
27
27
  }
28
- /** 有登錄稅號格式的國家(稅號題的國家選單用) */
28
+ /** Countries with a registered tax ID format (for the country menu of a tax ID question) */
29
29
  export function listTaxIdCountries() {
30
30
  return [...new Set(TAX_ID_FORMATS.flatMap((format) => format.countries))];
31
31
  }
32
32
  /**
33
- * 驗證並正規化一個稅號。
34
- * - 沒指定 type 時用該國的預設類型
35
- * - 國家沒有登錄任何類型、或指定的類型不屬於該國 → `UNSUPPORTED`(enforcement 為 warn:呼叫端當成自由文字收下)
36
- * - 格式或檢查碼不符 → 依該類型的 enforcement 決定要不要擋,見 `isBlockingTaxIdIssue`
33
+ * Validates and normalizes a tax ID.
34
+ * - Without a type, the country's default type is used
35
+ * - A country with no registered type, or a type that does not belong to the country: `UNSUPPORTED` (enforcement is warn: the caller accepts it as free text)
36
+ * - A format or check digit mismatch: whether it blocks depends on the type's enforcement, see `isBlockingTaxIdIssue`
37
37
  */
38
38
  export function validateTaxIdFormat(input) {
39
39
  const country = input.country.toUpperCase();
@@ -52,8 +52,8 @@ export function validateTaxIdFormat(input) {
52
52
  return { ok: true, country, type: format.type, normalized };
53
53
  }
54
54
  /**
55
- * 檢查一個「已經是正規化形式」的值,不做任何清理。給值要原樣存檔或送給第三方的 schema 用
56
- * (例如金流開通表單:放行帶分隔符號的寫法卻原樣送出,對方會退件)。合法回 null。
55
+ * Checks a value that is already in normalized form, with no cleanup. For schemas whose value is stored or sent to a third party as is
56
+ * (a payment onboarding form, for example: accepting a value with separators and sending it unchanged gets it rejected). Returns null when valid.
57
57
  */
58
58
  export function checkNormalizedTaxId(type, country, value) {
59
59
  const format = BY_TYPE.get(type);
@@ -61,7 +61,7 @@ export function checkNormalizedTaxId(type, country, value) {
61
61
  return "FORMAT";
62
62
  return format.validate(value, country.toUpperCase());
63
63
  }
64
- /** 這個結果要不要擋下(格式錯且該類型的規則已核實)。`warn` 與 `UNSUPPORTED` 不擋 */
64
+ /** Whether this result should block (the format is wrong and the type's rules are verified). `warn` and `UNSUPPORTED` do not block */
65
65
  export function isBlockingTaxIdIssue(result) {
66
66
  return !result.ok && result.enforcement === "block";
67
67
  }
@@ -1,36 +1,36 @@
1
1
  /**
2
- * 稅號與企業資料驗證的共用型別(ADR-0005 修訂一)。
2
+ * Shared types for tax ID and business data validation.
3
3
  *
4
- * 這個資料夾是「格式與檢查碼」的唯一實作:純函式、零依賴(不用 zod、不碰 DOM/Node),
5
- * 前台(託管結帳、表單、Elements)、後台與 `@kanorio/sdk`(以複製的方式帶走,見 packages/sdk/scripts/copy-shared.mjs)用同一份。
6
- * 登記機關查詢在 apps/main/lib/business-registry(只在伺服器)。
7
- * 資料夾內只用相對 import。
4
+ * This folder is the only implementation of formats and check digits: pure functions with no dependencies (no zod, no DOM or Node APIs),
5
+ * used by Kanorio's storefront (hosted checkout, forms, Elements), its dashboard and `@kanorio/sdk` (which carries a copy).
6
+ * Registry lookups run on Kanorio's server only.
7
+ * Only relative imports inside this folder.
8
8
  */
9
- /** 稅號類型;名稱沿用 Stripe Customer Tax IDs 的命名 */
9
+ /** Tax ID types; the names follow Stripe's Customer Tax IDs */
10
10
  export type TaxIdType = "tw_vat" | "hk_br" | "jp_trn" | "kr_brn" | "eu_vat" | "sg_uen" | "my_itn" | "my_sst";
11
11
  /**
12
- * 格式不符時要不要擋:
13
- * - `block`:規則已對照官方文件核實,格式錯就是錯
14
- * - `warn`:規則還沒逐條核實(或官方沒有公開完整規則),只提醒、不擋送出,避免我們比官方嚴
12
+ * Whether a format mismatch blocks:
13
+ * - `block`: the rules are verified against official documentation, so a wrong format is wrong
14
+ * - `warn`: the rules are not verified line by line yet (or the authority has not published full rules), so it only warns and never blocks a submit, to avoid being stricter than the authority
15
15
  */
16
16
  export type TaxIdEnforcement = "block" | "warn";
17
17
  export type TaxIdFormatIssue = "EMPTY" | "FORMAT" | "CHECKSUM" | "UNSUPPORTED";
18
18
  export interface TaxIdFormatDefinition {
19
19
  type: TaxIdType;
20
- /** 適用的國家(ISO 3166-1 alpha-2) */
20
+ /** The country it applies to (ISO 3166-1 alpha-2) */
21
21
  countries: readonly string[];
22
- /** 對應的 Stripe tax id type(平台收費把稅號交給 Stripe 時用) */
22
+ /** The matching Stripe tax id type (used when platform billing passes the tax ID to Stripe) */
23
23
  stripeType: string;
24
- /** 輸入 → 存檔與比對用的正規化值(已先做過全形轉半形、去空白、轉大寫) */
24
+ /** Input to the normalized value used for storage and comparison (already full-width to half-width, whitespace removed, uppercased) */
25
25
  normalize(cleaned: string, country: string): string;
26
- /** 正規化值是否合法;合法回 null */
26
+ /** Whether the normalized value is valid; null when valid */
27
27
  validate(normalized: string, country: string): null | "FORMAT" | "CHECKSUM";
28
28
  enforcement: TaxIdEnforcement;
29
- /** 有沒有檢查碼(有的話打錯一碼多半擋得住) */
29
+ /** Whether it has a check digit (when it does, a single mistyped digit is usually caught) */
30
30
  hasChecksum: boolean;
31
- /** 給輸入框 placeholder 的範例(合法值) */
31
+ /** An example for the input's placeholder (a valid value) */
32
32
  example(country: string): string;
33
- /** 輸入框的長度上限(含使用者可能打的分隔符號) */
33
+ /** Maximum input length (including separators the user may type) */
34
34
  maxLength: number;
35
35
  inputMode: "numeric" | "text";
36
36
  }
@@ -44,17 +44,17 @@ export type TaxIdFormatResult = {
44
44
  country: string;
45
45
  type: TaxIdType | null;
46
46
  issue: TaxIdFormatIssue;
47
- /** `warn` 時呼叫端只提醒、不擋 */
47
+ /** With `warn`, the caller only warns and does not block */
48
48
  enforcement: TaxIdEnforcement;
49
49
  normalized: string;
50
50
  };
51
- /** 政府開放資料的來源標示(授權條件:使用時必須標示提供機關) */
51
+ /** Attribution for government open data (license condition: the providing agency must be named on use) */
52
52
  export interface RegistryAttributionWire {
53
- /** 提供機關(原文) */
53
+ /** The providing agency (original name) */
54
54
  provider: string;
55
55
  providerEn: string;
56
56
  license: "OGDL-TW-1.0";
57
57
  licenseUrl: "https://data.gov.tw/license";
58
- /** 資料日期(快照的版本日,YYYY-MM-DD);即時查詢沒有 */
58
+ /** Data date (the snapshot's version date, YYYY-MM-DD); absent for live lookups */
59
59
  dataDate?: string;
60
60
  }
@@ -1,10 +1,10 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  /**
3
- * 稅號與企業資料驗證的共用型別(ADR-0005 修訂一)。
3
+ * Shared types for tax ID and business data validation.
4
4
  *
5
- * 這個資料夾是「格式與檢查碼」的唯一實作:純函式、零依賴(不用 zod、不碰 DOM/Node),
6
- * 前台(託管結帳、表單、Elements)、後台與 `@kanorio/sdk`(以複製的方式帶走,見 packages/sdk/scripts/copy-shared.mjs)用同一份。
7
- * 登記機關查詢在 apps/main/lib/business-registry(只在伺服器)。
8
- * 資料夾內只用相對 import。
5
+ * This folder is the only implementation of formats and check digits: pure functions with no dependencies (no zod, no DOM or Node APIs),
6
+ * used by Kanorio's storefront (hosted checkout, forms, Elements), its dashboard and `@kanorio/sdk` (which carries a copy).
7
+ * Registry lookups run on Kanorio's server only.
8
+ * Only relative imports inside this folder.
9
9
  */
10
10
  export {};
@@ -1,38 +1,38 @@
1
1
  /**
2
- * 次語系的網址前綴(ADR-0010 決策 4 修訂,2026-11-02 Wilson 定案 A;benchmark §C3b)。
2
+ * URL prefixes of secondary locales.
3
3
  *
4
- * 語系碼(`en-US`,BCP 47)與網址前綴(`en`)是兩個值——Webflow、Framer、Shopify Hydrogen、next-intl、Nuxt、Astro、Docusaurus 同做法:
5
- * - 前綴在**加入語系時決定並存下來**(`WebsiteLocale.pathPrefix`),之後加別的語系不會搬動既有網址(決策 4「既有網址永不搬動」)。
6
- * - 預設:同一種語言站上只有這一個版本 → 純語言(`/en`);已經有同語言的其他版本 → 語言+地區(`/en-gb`)。
7
- * 中文的繁、簡、港是不同書寫系統,一律保留完整碼(`/zh-hant`、`/zh-cn`、`/zh-hk`)。
8
- * - 站主可以改成自訂字(設定 › 語言;格式見 `isValidLocalePathPrefix`),改了舊前綴整批 301 到新前綴。
9
- * - 主語系永遠沒有前綴。
4
+ * The locale code (`en-US`, BCP 47) and the URL prefix (`en`) are two values, as in Webflow, Framer, Shopify Hydrogen, next-intl, Nuxt, Astro and Docusaurus:
5
+ * - The prefix is **decided and saved when the locale is added**, so adding other locales later never moves existing URLs.
6
+ * - Default: when the site has only this version of a language, the bare language (`/en`); when another version of the same language already exists, language plus region (`/en-gb`).
7
+ * Traditional, Simplified and Hong Kong Chinese are different writing systems and always keep the full code (`/zh-hant`, `/zh-cn`, `/zh-hk`).
8
+ * - The owner can change it to a custom word (Settings > Languages; see `isValidLocalePathPrefix` for the format), and the old prefix then redirects 301 to the new one as a whole.
9
+ * - The primary locale never has a prefix.
10
10
  *
11
- * 純函式、邊緣可跑:public-sites middleware、main 的 service、Delivery 共用。
11
+ * Pure functions that run at the edge: shared by Kanorio's hosted-site middleware, its server and the Delivery API.
12
12
  */
13
- /** 帶前綴的語系資料(lookup、站資訊、編輯器都用這個形狀) */
13
+ /** Locale data with its prefix (the shape used by site lookup, site info and the editor) */
14
14
  export interface LocaleRoute {
15
15
  locale: string;
16
16
  isPrimary?: boolean;
17
- /** 次語系的網址前綴(不含斜線、小寫);主語系 null。舊資料沒有時以語系碼小寫代替 */
17
+ /** URL prefix of a secondary locale (no slashes, lowercase); null for the primary locale. Older data without one falls back to the lowercase locale code */
18
18
  pathPrefix?: string | null;
19
19
  }
20
20
  export declare const LOCALE_PATH_PREFIX_MIN = 2;
21
21
  export declare const LOCALE_PATH_PREFIX_MAX = 30;
22
- /** 語系碼的語言子標籤(`en-US` → `en`、`zh-Hant` → `zh`) */
22
+ /** The language subtag of a locale code (`en-US` to `en`, `zh-Hant` to `zh`) */
23
23
  export declare function languageOfLocale(locale: string): string;
24
24
  /**
25
- * 加入語系時的預設前綴。`siteLocales` 是站上已經有的語系(含主語系,不含這個)。
26
- * `takenPrefixes` 是站上其他語系已經用掉的前綴:預設撞到時退回完整碼。
25
+ * The default prefix when a locale is added. `siteLocales` are the locales the site already has (including the primary, excluding this one).
26
+ * `takenPrefixes` are the prefixes other locales on the site already use: on a clash the default falls back to the full code.
27
27
  */
28
28
  export declare function defaultLocalePathPrefix(locale: string, siteLocales: readonly string[], takenPrefixes?: readonly string[]): string;
29
- /** 自訂前綴的格式:小寫英數與單一連字號、不在頭尾,2–30 字(`en`、`english`、`en-us`) */
29
+ /** Format of a custom prefix: lowercase letters and digits with single hyphens, not at either end, 2 to 30 characters (`en`, `english`, `en-us`) */
30
30
  export declare function isValidLocalePathPrefix(prefix: string): boolean;
31
- /** 使用者輸入 → 前綴:去頭尾空白與斜線、轉小寫;格式不對回 null */
31
+ /** User input to prefix: trims whitespace and slashes and lowercases; null when the format is wrong */
32
32
  export declare function normalizeLocalePathPrefix(input: string): string | null;
33
- /** 這個語系在網址上的前綴段(不含斜線);主語系 null */
33
+ /** This locale's prefix segment in URLs (no slashes); null for the primary locale */
34
34
  export declare function localePrefixOf(locale: string, routes: readonly LocaleRoute[], primaryLocale: string): string | null;
35
- /** 語系 → 前綴的對照(只有次語系);給一次要算很多網址的地方(sitemap、alternates) */
35
+ /** Locale to prefix map (secondary locales only); for places that build many URLs at once (sitemap, alternates) */
36
36
  export declare function localePrefixMap(routes: readonly LocaleRoute[], primaryLocale: string): Record<string, string>;
37
- /** 網址第一段 → 語系(只認次語系的前綴,不分大小寫);不是前綴回 null */
37
+ /** First URL segment to locale (only secondary-locale prefixes, case-insensitive); null when it is not a prefix */
38
38
  export declare function localeOfPrefix(segment: string, routes: readonly LocaleRoute[], primaryLocale: string): string | null;
@@ -1,30 +1,30 @@
1
- // 由 `pnpm --filter @kanorio/sdk gen` 從 packages/shared 複製,請勿手改(契約測試鎖兩份相同)。
1
+ // Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
2
2
  /**
3
- * 次語系的網址前綴(ADR-0010 決策 4 修訂,2026-11-02 Wilson 定案 A;benchmark §C3b)。
3
+ * URL prefixes of secondary locales.
4
4
  *
5
- * 語系碼(`en-US`,BCP 47)與網址前綴(`en`)是兩個值——Webflow、Framer、Shopify Hydrogen、next-intl、Nuxt、Astro、Docusaurus 同做法:
6
- * - 前綴在**加入語系時決定並存下來**(`WebsiteLocale.pathPrefix`),之後加別的語系不會搬動既有網址(決策 4「既有網址永不搬動」)。
7
- * - 預設:同一種語言站上只有這一個版本 → 純語言(`/en`);已經有同語言的其他版本 → 語言+地區(`/en-gb`)。
8
- * 中文的繁、簡、港是不同書寫系統,一律保留完整碼(`/zh-hant`、`/zh-cn`、`/zh-hk`)。
9
- * - 站主可以改成自訂字(設定 › 語言;格式見 `isValidLocalePathPrefix`),改了舊前綴整批 301 到新前綴。
10
- * - 主語系永遠沒有前綴。
5
+ * The locale code (`en-US`, BCP 47) and the URL prefix (`en`) are two values, as in Webflow, Framer, Shopify Hydrogen, next-intl, Nuxt, Astro and Docusaurus:
6
+ * - The prefix is **decided and saved when the locale is added**, so adding other locales later never moves existing URLs.
7
+ * - Default: when the site has only this version of a language, the bare language (`/en`); when another version of the same language already exists, language plus region (`/en-gb`).
8
+ * Traditional, Simplified and Hong Kong Chinese are different writing systems and always keep the full code (`/zh-hant`, `/zh-cn`, `/zh-hk`).
9
+ * - The owner can change it to a custom word (Settings > Languages; see `isValidLocalePathPrefix` for the format), and the old prefix then redirects 301 to the new one as a whole.
10
+ * - The primary locale never has a prefix.
11
11
  *
12
- * 純函式、邊緣可跑:public-sites middleware、main 的 service、Delivery 共用。
12
+ * Pure functions that run at the edge: shared by Kanorio's hosted-site middleware, its server and the Delivery API.
13
13
  */
14
14
  export const LOCALE_PATH_PREFIX_MIN = 2;
15
15
  export const LOCALE_PATH_PREFIX_MAX = 30;
16
16
  const PREFIX_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
17
- /** 語系碼的語言子標籤(`en-US` → `en`、`zh-Hant` → `zh`) */
17
+ /** The language subtag of a locale code (`en-US` to `en`, `zh-Hant` to `zh`) */
18
18
  export function languageOfLocale(locale) {
19
19
  return (locale.split("-")[0] ?? locale).toLowerCase();
20
20
  }
21
- /** 中文的變體是不同書寫系統,前綴與 hreflang 都不收成純語言 */
21
+ /** Chinese variants are different writing systems; neither prefixes nor hreflang collapse them to the bare language */
22
22
  function keepsFullCode(locale) {
23
23
  return languageOfLocale(locale) === "zh";
24
24
  }
25
25
  /**
26
- * 加入語系時的預設前綴。`siteLocales` 是站上已經有的語系(含主語系,不含這個)。
27
- * `takenPrefixes` 是站上其他語系已經用掉的前綴:預設撞到時退回完整碼。
26
+ * The default prefix when a locale is added. `siteLocales` are the locales the site already has (including the primary, excluding this one).
27
+ * `takenPrefixes` are the prefixes other locales on the site already use: on a clash the default falls back to the full code.
28
28
  */
29
29
  export function defaultLocalePathPrefix(locale, siteLocales, takenPrefixes = []) {
30
30
  const full = locale.toLowerCase();
@@ -36,16 +36,16 @@ export function defaultLocalePathPrefix(locale, siteLocales, takenPrefixes = [])
36
36
  return full;
37
37
  return language;
38
38
  }
39
- /** 自訂前綴的格式:小寫英數與單一連字號、不在頭尾,2–30 字(`en`、`english`、`en-us`) */
39
+ /** Format of a custom prefix: lowercase letters and digits with single hyphens, not at either end, 2 to 30 characters (`en`, `english`, `en-us`) */
40
40
  export function isValidLocalePathPrefix(prefix) {
41
41
  return prefix.length >= LOCALE_PATH_PREFIX_MIN && prefix.length <= LOCALE_PATH_PREFIX_MAX && PREFIX_RE.test(prefix);
42
42
  }
43
- /** 使用者輸入 → 前綴:去頭尾空白與斜線、轉小寫;格式不對回 null */
43
+ /** User input to prefix: trims whitespace and slashes and lowercases; null when the format is wrong */
44
44
  export function normalizeLocalePathPrefix(input) {
45
45
  const value = input.trim().replace(/^\/+|\/+$/g, "").toLowerCase();
46
46
  return isValidLocalePathPrefix(value) ? value : null;
47
47
  }
48
- /** 這個語系在網址上的前綴段(不含斜線);主語系 null */
48
+ /** This locale's prefix segment in URLs (no slashes); null for the primary locale */
49
49
  export function localePrefixOf(locale, routes, primaryLocale) {
50
50
  if (locale === primaryLocale)
51
51
  return null;
@@ -54,7 +54,7 @@ export function localePrefixOf(locale, routes, primaryLocale) {
54
54
  return null;
55
55
  return route?.pathPrefix || locale.toLowerCase();
56
56
  }
57
- /** 語系 → 前綴的對照(只有次語系);給一次要算很多網址的地方(sitemap、alternates) */
57
+ /** Locale to prefix map (secondary locales only); for places that build many URLs at once (sitemap, alternates) */
58
58
  export function localePrefixMap(routes, primaryLocale) {
59
59
  const out = {};
60
60
  for (const route of routes) {
@@ -64,7 +64,7 @@ export function localePrefixMap(routes, primaryLocale) {
64
64
  }
65
65
  return out;
66
66
  }
67
- /** 網址第一段 → 語系(只認次語系的前綴,不分大小寫);不是前綴回 null */
67
+ /** First URL segment to locale (only secondary-locale prefixes, case-insensitive); null when it is not a prefix */
68
68
  export function localeOfPrefix(segment, routes, primaryLocale) {
69
69
  const wanted = segment.toLowerCase();
70
70
  for (const route of routes) {
@@ -1,42 +1,42 @@
1
1
  /**
2
- * 請求語系解析(ADR-0010 決策 4、5;P3):從路徑第一層段落辨認語系前綴。
3
- * public-sites middleware 與 Delivery SDK 的 middleware 共用;邊緣可跑(純函式、無 Node 依賴)。
2
+ * Request locale resolution: recognizes the locale prefix in the first path segment.
3
+ * Shared by Kanorio's hosted-site middleware and the SDK's middleware; runs at the edge (pure functions, no Node dependency).
4
4
  *
5
- * - 次語系以 `/{前綴}/` 子目錄交付;前綴是語系存下來的 `pathPrefix`(預設 `/en`,見 `locale-path.ts`),不分大小寫。
6
- * - 主語系永遠無前綴:`/zh-hant/about`(主語系碼當前綴)要 301 到 `/about`(`redirectTo`)。
7
- * - 不是任何已上線語系的前綴,當一般路徑。
5
+ * - Secondary locales are served under a `/{prefix}/` subdirectory; the prefix is the locale's saved `pathPrefix` (default `/en`, see `locale-path.ts`), case-insensitive.
6
+ * - The primary locale never has a prefix: `/zh-hant/about` (the primary locale code used as a prefix) must redirect 301 to `/about` (`redirectTo`).
7
+ * - Anything that is not a live locale's prefix is an ordinary path.
8
8
  */
9
9
  import { type LocaleRoute } from "./locale-path.js";
10
10
  export interface RequestLocaleInput {
11
11
  pathname: string;
12
12
  primaryLocale: string;
13
- /** 已上線的語系(含主語系),帶各自的前綴 */
13
+ /** Live locales (including the primary), each with its prefix */
14
14
  locales: readonly LocaleRoute[];
15
15
  }
16
16
  export interface RequestLocaleResult {
17
- /** 採用的語系 */
17
+ /** The locale in effect */
18
18
  locale: string;
19
- /** 剝掉前綴後的路徑(主語系空間的路徑),至少 `/` */
19
+ /** The path without the prefix (a path in the primary locale's space), at least `/` */
20
20
  pathname: string;
21
- /** 網址是否帶了次語系前綴 */
21
+ /** Whether the URL carried a secondary-locale prefix */
22
22
  prefixed: boolean;
23
- /** 主語系帶前綴時要 301 到的路徑;其餘 null */
23
+ /** The path to redirect 301 to when the primary locale was used as a prefix; otherwise null */
24
24
  redirectTo: string | null;
25
25
  }
26
26
  export declare function resolveRequestLocale(input: RequestLocaleInput): RequestLocaleResult;
27
- /** 把主語系空間的路徑換成某語系的網址路徑(主語系無前綴;次語系用存下來的前綴) */
27
+ /** Turns a path in the primary locale's space into a locale's URL path (no prefix for the primary; the saved prefix for a secondary locale) */
28
28
  export declare function withLocalePrefix(pathname: string, locale: string, primaryLocale: string, routes: readonly LocaleRoute[]): string;
29
29
  /**
30
- * 託管站的路由參數(ADR-0010 P3):訪客端頁面是 ISR,請求語系不能靠 header,所以 middleware 把語系
31
- * 編進 `[siteId]` 段:`/en-us/about` → `/public/{siteId}__en-us/about`。主語系不編(參數就是 siteId)。
32
- * 分隔用 `__`:cuid 只有小寫英數,語系碼只有字母、數字與連字號,不會撞到。
30
+ * Route parameter of hosted sites: visitor pages are statically regenerated, so the request locale cannot come from a header and the middleware
31
+ * encodes it into the `[siteId]` segment: `/en-us/about` becomes `/public/{siteId}__en-us/about`. The primary locale is not encoded (the parameter is just the siteId).
32
+ * The separator is `__`: site ids contain only lowercase letters and digits, and locale codes only letters, digits and hyphens, so they cannot clash.
33
33
  */
34
34
  export declare const SITE_PARAM_LOCALE_SEPARATOR = "__";
35
35
  export declare function composeSiteParam(siteId: string, locale: string | null | undefined, primaryLocale?: string): string;
36
- /** 把路由參數拆回 siteId 與請求語系(小寫碼;沒有前綴就是 null=主語系) */
36
+ /** Splits the route parameter back into siteId and request locale (lowercase code; null without a prefix, meaning the primary locale) */
37
37
  export declare function parseSiteParam(param: string): {
38
38
  siteId: string;
39
39
  locale: string | null;
40
40
  };
41
- /** 語系在網址上的根路徑:主語系空字串,次語系 `/{前綴}`;路徑建構器把它接在最前面 */
41
+ /** A locale's root path in URLs: empty for the primary locale, `/{prefix}` for a secondary one; path builders put it first */
42
42
  export declare function localeRootPath(locale: string | null | undefined, primaryLocale: string, routes: readonly LocaleRoute[]): string;