@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,31 +1,31 @@
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
- * Content Delivery API 的快取標籤(SSOT;ADR-0010 決策 13 修訂二)。
3
+ * Cache tags of the Content Delivery API (the single source of truth).
4
4
  *
5
- * 標籤記的是「這個回應用到了哪些內容」,事件送的是「這次哪些內容變了」;兩邊由這一份函式產生,
6
- * `apps/main/__tests__/shared/api/delivery-cache-tags.test.ts` 的契約矩陣逐一檢查:該清的一定清到、不該清的一定碰不到。
5
+ * A response's tags say which content it used; an event's tags say which content changed. Both come from the functions in this file,
6
+ * and a contract matrix in Kanorio's tests checks every pairing: what should be cleared is cleared, and what should not is never touched.
7
7
  *
8
- * 分層(一個回應同時帶寬窄兩種標籤,與 CDN surrogate key 的慣例相同):
9
- * - 整站 `site:{id}`:所有回應都帶;只有整站發布與語系集合變動(上線、下線、移除、改前綴、換主語系)的事件送它
10
- * - 語系 `locale:{code}`:次語系的所有回應都帶;整站翻譯完成、網站設定譯文上線送它
11
- * - 內容 `page:{id}`、`item:{id}`、`product:{id}`、`form:{id}`:所有語系的回應都帶;主語系內容上線的事件送它(未翻譯的欄位沿用主語系,所以所有語系一起清)
12
- * - 內容+語系 `page:{id}@en-US`:只有該語系的回應帶;該語系的譯文上線時送它,其他語系不動
13
- * - 列表 `pages`、`collection:{key}`、`products`(+語系):只有列表回應帶,不逐項帶(事件本來就會一起送列表標籤;Next.js 一筆快取最多 128 個標籤);
14
- * 單筆回應不帶列表標籤,別的項目上線才不會清到它。`collection:{key}:items` 是該集合所有單筆回應(欄位結構變了要一起換)
15
- * - 衍生 `search`、`seo`、`redirects`:搜尋、SEO 衍生檔、轉址表;會改變它們的內容事件一起送
8
+ * Layers (one response carries both broad and narrow tags, like CDN surrogate keys):
9
+ * - Site `site:{id}`: on every response; sent only by events for a full-site publish and for changes to the locale set (enabled, disabled, removed, prefix changed, primary changed)
10
+ * - Locale `locale:{code}`: on every response of a secondary locale; sent when a full-site translation finishes or translated site settings go live
11
+ * - Content `page:{id}`, `item:{id}`, `product:{id}`, `form:{id}`: on the response in every locale; sent when primary-locale content goes live (untranslated fields fall back to the primary locale, so every locale is cleared)
12
+ * - Content plus locale `page:{id}@en-US`: only on that locale's response; sent when that locale's translation goes live, leaving other locales alone
13
+ * - Lists `pages`, `collection:{key}`, `products` (plus locale): on list responses only, not per item (events send the list tags anyway, and Next.js allows at most 128 tags per cache entry);
14
+ * single-item responses do not carry list tags, so another item going live does not clear them. `collection:{key}:items` is every single-item response of the collection (all replaced when the field structure changes)
15
+ * - Derived `search`, `seo`, `redirects`: search, SEO files and the redirect table; sent along with content events that change them
16
16
  *
17
- * 標籤用語系碼不用網址前綴(前綴站主可以改);語系以 `@` 接在後面,與 `type:id` 的冒號分得開。
18
- * `revalidateTag` 逐字比對、沒有萬用字元,所以事件必須列出具體標籤。純函式、無 server-only,main、邊緣 Worker 與 SDK 共用
19
- * (SDK 的副本 `packages/sdk/src/cache-tags.ts` 由 `pnpm --filter @kanorio/sdk gen` 複製,契約測試鎖兩份相同)。
17
+ * Tags use the locale code, not the URL prefix (owners can change the prefix); the locale is appended with `@`, apart from the colon of `type:id`.
18
+ * `revalidateTag` matches literally, with no wildcards, so events must list concrete tags. Pure functions with no server-only dependency, shared by Kanorio's server, its edge worker and the SDK
19
+ * (the SDK's copy is made by `pnpm --filter @kanorio/sdk gen`, and a contract test keeps the two identical).
20
20
  */
21
21
  export const DELIVERY_CACHE_TAGS_HEADER = "x-kanorio-cache-tags";
22
- /** 一個回應最多幾個標籤:Next.js 一筆快取上限 128,留餘裕給外部前端自己的標籤 */
22
+ /** Maximum tags per response: Next.js caps a cache entry at 128, leaving room for the external front end's own tags */
23
23
  export const DELIVERY_CACHE_TAG_LIMIT = 100;
24
- /** 語系接在標籤後面的分隔符:`item:abc@en-US` */
24
+ /** Separator between a tag and its locale: `item:abc@en-US` */
25
25
  export const CACHE_TAG_LOCALE_SEPARATOR = "@";
26
- /** SDK 交給框架(Next.js `revalidateTag`、`next.tags`)時加的命名空間,避免與網站自己的 `pages`、`seo` 這類標籤撞名 */
26
+ /** Namespace the SDK adds when handing tags to a framework (Next.js `revalidateTag`, `next.tags`), to avoid clashing with the site's own tags such as `pages` or `seo` */
27
27
  export const DEFAULT_CACHE_TAG_PREFIX = "kanorio:";
28
- /** 標籤字彙;只在這裡拼字串 */
28
+ /** The tag vocabulary; strings are only assembled here */
29
29
  export const cacheTag = {
30
30
  site: (siteId) => `site:${siteId}`,
31
31
  locale: (locale) => `locale:${locale}`,
@@ -36,7 +36,7 @@ export const cacheTag = {
36
36
  footer: () => "footer",
37
37
  collections: () => "collections",
38
38
  collection: (key) => `collection:${key}`,
39
- /** 該集合所有單筆回應:欄位結構變更、整批超過上限時用 */
39
+ /** Every single-item response of the collection: used when the field structure changes or a batch exceeds the limit */
40
40
  collectionItems: (key) => `collection:${key}:items`,
41
41
  item: (itemId) => `item:${itemId}`,
42
42
  products: () => "products",
@@ -71,8 +71,8 @@ function unique(tags) {
71
71
  return out;
72
72
  }
73
73
  /**
74
- * 回應的語系維度:主語系(`locale` 為 null)原樣;次語系在每個內容與列表標籤後面接語系(`site:` 不接),再加 `locale:{code}`。
75
- * 邊緣以請求正規化後的語系碼呼叫(省略與指定主語系都是 null),main 只需要說明內容依賴。
74
+ * The locale dimension of a response: the primary locale (`locale` is null) is left as is; a secondary locale gets the locale appended to every content and list tag (not to `site:`), plus `locale:{code}`.
75
+ * The edge calls this with the request's normalized locale code (omitted and explicitly primary are both null); the server only declares content dependencies.
76
76
  */
77
77
  export function localizeCacheTags(tags, locale) {
78
78
  const base = unique(tags);
@@ -85,7 +85,7 @@ const NARROW_PREFIXES = ["item:", "page:", "product:"];
85
85
  function isNarrowCacheTag(tag) {
86
86
  return NARROW_PREFIXES.some((prefix) => tag.startsWith(prefix));
87
87
  }
88
- /** 超過上限時先丟單筆內容的標籤(列表層的標籤留著,事件本來就會送列表標籤),仍超過就只留前 `limit` 個 */
88
+ /** Over the limit, single-content tags are dropped first (list tags stay, since events send them anyway); if still over, only the first `limit` are kept */
89
89
  export function capCacheTags(tags, limit = DELIVERY_CACHE_TAG_LIMIT) {
90
90
  const all = unique(tags);
91
91
  if (all.length <= limit)
@@ -93,7 +93,7 @@ export function capCacheTags(tags, limit = DELIVERY_CACHE_TAG_LIMIT) {
93
93
  const wide = all.filter((tag) => !isNarrowCacheTag(tag));
94
94
  return wide.length <= limit ? wide : wide.slice(0, limit);
95
95
  }
96
- /** `X-Kanorio-Cache-Tags` 以空白分隔 */
96
+ /** `X-Kanorio-Cache-Tags` is space-separated */
97
97
  export function parseCacheTagsHeader(raw) {
98
98
  if (!raw)
99
99
  return [];
@@ -102,7 +102,7 @@ export function parseCacheTagsHeader(raw) {
102
102
  export function formatCacheTagsHeader(tags) {
103
103
  return unique(tags).join(" ");
104
104
  }
105
- /** 交給框架前加命名空間;`prefix` 為空字串時原樣 */
105
+ /** Adds the namespace before handing tags to a framework; an empty `prefix` leaves them as is */
106
106
  export function prefixCacheTags(tags, prefix = DEFAULT_CACHE_TAG_PREFIX) {
107
107
  return unique(tags).map((tag) => `${prefix}${tag}`);
108
108
  }
@@ -137,7 +137,7 @@ export const responseCacheTags = {
137
137
  redirects: (siteId) => [cacheTag.site(siteId), cacheTag.redirects()],
138
138
  reviews: (siteId, productId) => [cacheTag.site(siteId), cacheTag.reviews(), ...(productId ? [cacheTag.product(productId)] : [])],
139
139
  };
140
- /** 系統集合:文章類紀錄的譯文變了,等於該集合項目變了 */
140
+ /** System collections: when an article-like record's translation changes, the collection item has changed */
141
141
  const SYSTEM_COLLECTION_OF_ENTITY = {
142
142
  post: "blog",
143
143
  post_category: "blog_categories",
@@ -145,12 +145,12 @@ const SYSTEM_COLLECTION_OF_ENTITY = {
145
145
  author: "authors",
146
146
  };
147
147
  export const eventCacheTags = {
148
- /** 整站發布:頁面、頁首頁尾、轉址、SEO 衍生檔都可能變 */
148
+ /** Full-site publish: pages, header and footer, redirects and SEO files may all change */
149
149
  sitePublished: (siteId) => [cacheTag.site(siteId), cacheTag.pages(), cacheTag.globals(), cacheTag.redirects(), cacheTag.seo()],
150
- /** 單頁上線、更新、下線、刪除:不送 `site:`,別的頁不動;改網址另送 `redirects` */
150
+ /** A single page going live, updated, taken offline or deleted: `site:` is not sent, so other pages stay; a changed URL also sends `redirects` */
151
151
  pageChanged: (input) => [cacheTag.pages(), cacheTag.page(input.pageId), cacheTag.seo(), cacheTag.search(), ...(input.renamed ? [cacheTag.redirects()] : [])],
152
152
  itemChanged: (input) => [cacheTag.collection(input.collectionKey), cacheTag.item(input.itemId), cacheTag.seo(), cacheTag.search()],
153
- /** 批次:項目標籤放得下才逐一列;放不下就改清該集合所有單筆(列表標籤一定在) */
153
+ /** Bulk: items are listed one by one when their tags fit; otherwise every single-item response of the collection is cleared (list tags are always sent) */
154
154
  itemsBulkChanged: (input) => {
155
155
  const wide = [cacheTag.collection(input.collectionKey), cacheTag.seo(), cacheTag.search()];
156
156
  const narrow = input.itemIds.map((id) => cacheTag.item(id));
@@ -158,15 +158,17 @@ export const eventCacheTags = {
158
158
  return [...wide, ...narrow];
159
159
  return [...wide, cacheTag.collectionItems(input.collectionKey)];
160
160
  },
161
- /** 欄位結構變了:集合清單、列表與該集合所有單筆(投影的欄位變了) */
161
+ /** The field structure changed: the collection list, the item list and every single-item response of the collection (projected fields changed) */
162
162
  schemaChanged: (input) => [cacheTag.collections(), cacheTag.collection(input.collectionKey), cacheTag.collectionItems(input.collectionKey)],
163
- /** 語系集合變了(上線、下線、移除、改前綴、順序、換主語系):語言切換與 hreflang 在每一頁都有 */
163
+ /** A form's definition changed, it was paused or resumed, or it moved to or from the trash: the form's own response in every locale */
164
+ formChanged: (formId) => [cacheTag.form(formId)],
165
+ /** The locale set changed (enabled, disabled, removed, prefix, order, primary): the language switcher and hreflang are on every page */
164
166
  localeChanged: (siteId) => [cacheTag.site(siteId)],
165
- /** 整站翻譯完成:該語系所有回應 */
167
+ /** A full-site translation finished: every response in that locale */
166
168
  translationJobCompleted: (locale) => [cacheTag.locale(locale)],
167
169
  /**
168
- * 一筆紀錄在一個語系的譯文上線或刪除:只送帶語系的標籤,其他語系與主語系的快取不動。
169
- * 網站設定與站上公告是整個語系的外框 → `locale:{code}`;商品的規格、分類、課程大綱沒有單一商品 id → `products@{code}`。
170
+ * One record's translation in one locale went live or was deleted: only locale-specific tags are sent, so the caches of other locales and the primary locale stay.
171
+ * Site settings and site announcements frame the whole locale, hence `locale:{code}`; product options, categories and course outlines have no single product id, hence `products@{code}`.
170
172
  */
171
173
  translationChanged: (input) => {
172
174
  const l = (tag) => localizeCacheTag(tag, input.locale);
@@ -1,43 +1,47 @@
1
1
  /**
2
- * 網站主機金鑰(server key)的共用契約:main、public-sites Worker 與 SDK 讀同一份。
2
+ * The shared contract of server keys: Kanorio's server, its edge worker and the SDK read the same file.
3
3
  *
4
- * 主機金鑰是用途為「網站主機用」的服務帳號金鑰(`knr_sa_`)。站主自建前端的伺服器帶著它代訪客寫入
5
- * (送表單、顧客登入、回報爬蟲),邊緣驗過後才採信它宣稱的訪客 IP。它打不開 Management API。
6
- * 設計見 docs/platform/decisions/0002-operation-context.md「修訂一」。
4
+ * A server key is a service account key issued for a website's own server (`knr_sk_`). The server of a self-hosted front end sends it when writing on behalf of a visitor
5
+ * (submitting a form, customer sign-in, reporting crawlers), and the edge trusts the visitor IP it states only after verifying the key. It cannot open the Management API.
6
+ * See the Authentication page of the developer documentation.
7
7
  */
8
- /** 主機帶金鑰的標頭 */
8
+ /** The header the server sends the key in */
9
9
  export declare const SERVER_KEY_HEADER = "X-Kanorio-Server-Key";
10
- /** 主機轉述的訪客 IP;只在金鑰驗過時採信 */
10
+ /** The visitor IP relayed by the server; trusted only when the key has been verified */
11
11
  export declare const SERVER_KEY_VISITOR_IP_HEADER = "X-Kanorio-Visitor-IP";
12
12
  /**
13
- * Worker → main:這個請求帶著驗過的主機金鑰(值是金鑰 id)。main 只在它與 Worker 金鑰(X-API-Key)俱全時
14
- * 才採信 `x-kanorio-client-ip` 裡主機轉述的訪客 IP(apps/main/lib/utils/ip-address.ts)。
13
+ * Edge worker to server: this request carries a verified server key (the value is the key id). The server trusts the relayed visitor IP in
14
+ * `x-kanorio-client-ip` only when this header and the worker's own key (X-API-Key) are both present.
15
15
  */
16
16
  export declare const SERVER_KEY_ID_FORWARD_HEADER = "x-kanorio-server-key-id";
17
17
  /**
18
- * 服務帳號授予與金鑰 scopes 裡的機器專用標記。不在「人的權限目錄」(`ALL_PERMISSIONS`)裡:
19
- * 沒有任何團隊角色持有它、角色編輯器不會出現、PAT 與 OAuth 選不到。建立這種服務帳號只需要 `developer:manage`。
18
+ * Machine-only marker in a service account's grants and its keys' scopes. It is not in the catalog of permissions people can hold:
19
+ * no team role has it, the role editor does not show it, and personal access tokens and OAuth cannot select it. Creating such a service account only needs `developer:manage`.
20
20
  */
21
21
  export declare const STOREFRONT_SERVER_SCOPE = "storefront:server";
22
- export declare const SERVER_KEY_PREFIX = "knr_sa_";
22
+ /**
23
+ * The server key's own prefix: one prefix per credential type (as GitHub and Stripe do), so whoever holds a key, and leak scanners, can tell from the prefix
24
+ * that it cannot open the Management API. Service account keys for managing a site start with `knr_sa_`.
25
+ */
26
+ export declare const SERVER_KEY_PREFIX = "knr_sk_";
23
27
  export declare function isServerKeyFormat(raw: string): boolean;
24
28
  /**
25
- * 外部視角探針用的假金鑰(格式正確、永遠不存在):監控每輪拿它 POST 一個站,確認假金鑰會被拒。
26
- * 邊緣認得它,照常驗證與拒絕,但不計入該站的「主機金鑰驗證失敗」異常訊號(那是我們自己的探針,不是有人在試)。
29
+ * A fake key for outside-in probes (well-formed and never valid): monitoring POSTs with it to a site every round to confirm that fake keys are refused.
30
+ * The edge recognizes it, verifies and refuses it as usual, but does not count it toward the site's failed-server-key signal (it is Kanorio's own probe, not someone guessing).
27
31
  */
28
32
  export declare const PROBE_FAKE_SERVER_KEY: string;
29
- /** 服務帳號的用途:由授予是否帶 `STOREFRONT_SERVER_SCOPE` 決定,建立後不可改 */
33
+ /** A service account's purpose: decided by whether its grant carries `STOREFRONT_SERVER_SCOPE`, and fixed after creation */
30
34
  export type ServiceAccountPurpose = "management" | "storefront_server";
31
35
  export declare function purposeOfGrant(permissions: readonly string[]): ServiceAccountPurpose;
32
- /** 環境變數的慣用名稱(後台的一次性顯示、CLI `--write-env`、文件都用這個) */
36
+ /** Conventional environment variable name (used by the dashboard's one-time display, the CLI's `--write-env` and the documentation) */
33
37
  export declare const SERVER_KEY_ENV_NAME = "KANORIO_SERVER_KEY";
34
- /** Worker → main 驗證端點的回應 */
38
+ /** Response of the edge worker's verification call to the server */
35
39
  export interface ServerKeyVerifyResponse {
36
40
  valid: boolean;
37
41
  tokenId?: string;
38
- /** ISO 時間;null=不過期 */
42
+ /** ISO time; null means it does not expire */
39
43
  expiresAt?: string | null;
40
- /** 來源限制(空陣列=不限制);比對的是實際連線 IP 與 ASN */
44
+ /** Source restrictions (an empty array means none); matched against the actual connecting IP and ASN */
41
45
  allowedCidrs?: string[];
42
46
  allowedAsns?: number[];
43
47
  }
@@ -45,26 +49,26 @@ export interface ParsedIp {
45
49
  version: 4 | 6;
46
50
  bytes: number[];
47
51
  }
48
- /** 解析 IP;`::ffff:a.b.c.d` 視為 IPv4。不合法回 null */
52
+ /** Parses an IP; `::ffff:a.b.c.d` is treated as IPv4. null when invalid */
49
53
  export declare function parseIp(raw: string): ParsedIp | null;
50
54
  export declare function isPublicIp(ip: ParsedIp): boolean;
51
55
  /**
52
- * 主機轉述的訪客 IP:必須是合法的公開位址,否則視為沒帶(回 null)。
53
- * 設錯的反向代理會把 10.x 這類內網位址轉過來,照收的話全站訪客會共用一個限流桶。
56
+ * The visitor IP relayed by the server: it must be a valid public address, otherwise it counts as absent (null).
57
+ * A misconfigured reverse proxy relays internal addresses such as 10.x; accepting them would put every visitor of the site in one rate-limit bucket.
54
58
  */
55
59
  export declare function normalizeVisitorIp(raw: string | null | undefined): string | null;
56
- /** 限流桶的鍵:IPv4 用整個位址,IPv6 用 /64(同一個用戶端通常拿到整段 /64) */
60
+ /** Rate-limit bucket key: the whole address for IPv4, the /64 for IPv6 (one client usually gets a whole /64) */
57
61
  export declare function rateLimitKeyForIp(ip: string): string;
58
62
  export interface ParsedCidr {
59
63
  version: 4 | 6;
60
64
  bytes: number[];
61
65
  bits: number;
62
- /** 正規化後的寫法(網路位址+前綴長度) */
66
+ /** Normalized form (network address and prefix length) */
63
67
  text: string;
64
68
  }
65
69
  /**
66
- * 解析來源限制的一筆 IP 或 CIDR。單一 IP 視為 /32(IPv6 為 /128)。
67
- * 拒收:格式錯、非公開網段、前綴過寬。
70
+ * Parses one IP or CIDR of a source restriction. A single IP is a /32 (/128 for IPv6).
71
+ * Rejected: malformed input, non-public ranges and prefixes that are too wide.
68
72
  */
69
73
  export declare function parseAllowedCidr(raw: string): ParsedCidr | null;
70
74
  export declare function ipInCidr(ip: string, cidr: ParsedCidr): boolean;
@@ -76,9 +80,9 @@ export interface SourcePolicy {
76
80
  }
77
81
  export declare function hasSourcePolicy(policy: SourcePolicy): boolean;
78
82
  /**
79
- * 來源限制判定(比照 Stripe 存取政策):設了哪一類條件,那一類就必須符合;兩類都設就兩類都要符合。
80
- * 比對的是 Cloudflare 給的實際連線 IP 與 ASN,不是主機轉述的訪客 IP。
81
- * 有 ASN 條件但拿不到 ASN(本機開發、邊緣沒帶)時視為不符合。
83
+ * Source restriction check (like Stripe's access policies): whichever kind of condition is set must match; when both are set, both must match.
84
+ * Matched against the actual connecting IP and ASN from Cloudflare, not the visitor IP relayed by the server.
85
+ * With an ASN condition but no ASN available (local development, or the edge did not send it), the check fails.
82
86
  */
83
87
  export declare function isSourceAllowed(policy: SourcePolicy, source: {
84
88
  ip: string | null;
@@ -1,42 +1,50 @@
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
- * 網站主機金鑰(server key)的共用契約:main、public-sites Worker 與 SDK 讀同一份。
3
+ * The shared contract of server keys: Kanorio's server, its edge worker and the SDK read the same file.
4
4
  *
5
- * 主機金鑰是用途為「網站主機用」的服務帳號金鑰(`knr_sa_`)。站主自建前端的伺服器帶著它代訪客寫入
6
- * (送表單、顧客登入、回報爬蟲),邊緣驗過後才採信它宣稱的訪客 IP。它打不開 Management API。
7
- * 設計見 docs/platform/decisions/0002-operation-context.md「修訂一」。
5
+ * A server key is a service account key issued for a website's own server (`knr_sk_`). The server of a self-hosted front end sends it when writing on behalf of a visitor
6
+ * (submitting a form, customer sign-in, reporting crawlers), and the edge trusts the visitor IP it states only after verifying the key. It cannot open the Management API.
7
+ * See the Authentication page of the developer documentation.
8
8
  */
9
- /** 主機帶金鑰的標頭 */
9
+ /** The header the server sends the key in */
10
10
  export const SERVER_KEY_HEADER = "X-Kanorio-Server-Key";
11
- /** 主機轉述的訪客 IP;只在金鑰驗過時採信 */
11
+ /** The visitor IP relayed by the server; trusted only when the key has been verified */
12
12
  export const SERVER_KEY_VISITOR_IP_HEADER = "X-Kanorio-Visitor-IP";
13
13
  /**
14
- * Worker → main:這個請求帶著驗過的主機金鑰(值是金鑰 id)。main 只在它與 Worker 金鑰(X-API-Key)俱全時
15
- * 才採信 `x-kanorio-client-ip` 裡主機轉述的訪客 IP(apps/main/lib/utils/ip-address.ts)。
14
+ * Edge worker to server: this request carries a verified server key (the value is the key id). The server trusts the relayed visitor IP in
15
+ * `x-kanorio-client-ip` only when this header and the worker's own key (X-API-Key) are both present.
16
16
  */
17
17
  export const SERVER_KEY_ID_FORWARD_HEADER = "x-kanorio-server-key-id";
18
18
  /**
19
- * 服務帳號授予與金鑰 scopes 裡的機器專用標記。不在「人的權限目錄」(`ALL_PERMISSIONS`)裡:
20
- * 沒有任何團隊角色持有它、角色編輯器不會出現、PAT 與 OAuth 選不到。建立這種服務帳號只需要 `developer:manage`。
19
+ * Machine-only marker in a service account's grants and its keys' scopes. It is not in the catalog of permissions people can hold:
20
+ * no team role has it, the role editor does not show it, and personal access tokens and OAuth cannot select it. Creating such a service account only needs `developer:manage`.
21
21
  */
22
22
  export const STOREFRONT_SERVER_SCOPE = "storefront:server";
23
- export const SERVER_KEY_PREFIX = "knr_sa_";
24
- /** `knr_sa_` + 43 字元 base64url(32 bytes)。格式不符就不必回源查 */
25
- const SERVER_KEY_PATTERN = /^knr_sa_[A-Za-z0-9_-]{43}$/;
23
+ /**
24
+ * The server key's own prefix: one prefix per credential type (as GitHub and Stripe do), so whoever holds a key, and leak scanners, can tell from the prefix
25
+ * that it cannot open the Management API. Service account keys for managing a site start with `knr_sa_`.
26
+ */
27
+ export const SERVER_KEY_PREFIX = "knr_sk_";
28
+ /**
29
+ * The prefix followed by 43 base64url characters (32 bytes). A malformed key is rejected without a lookup.
30
+ * Server keys have this one prefix only.
31
+ * Keys issued earlier with `knr_sa_` are not accepted and must be created again.
32
+ */
33
+ const SERVER_KEY_PATTERN = /^knr_sk_[A-Za-z0-9_-]{43}$/;
26
34
  export function isServerKeyFormat(raw) {
27
35
  return SERVER_KEY_PATTERN.test(raw);
28
36
  }
29
37
  /**
30
- * 外部視角探針用的假金鑰(格式正確、永遠不存在):監控每輪拿它 POST 一個站,確認假金鑰會被拒。
31
- * 邊緣認得它,照常驗證與拒絕,但不計入該站的「主機金鑰驗證失敗」異常訊號(那是我們自己的探針,不是有人在試)。
38
+ * A fake key for outside-in probes (well-formed and never valid): monitoring POSTs with it to a site every round to confirm that fake keys are refused.
39
+ * The edge recognizes it, verifies and refuses it as usual, but does not count it toward the site's failed-server-key signal (it is Kanorio's own probe, not someone guessing).
32
40
  */
33
41
  export const PROBE_FAKE_SERVER_KEY = `${SERVER_KEY_PREFIX}${"0".repeat(43)}`;
34
42
  export function purposeOfGrant(permissions) {
35
43
  return permissions.includes(STOREFRONT_SERVER_SCOPE) ? "storefront_server" : "management";
36
44
  }
37
- /** 環境變數的慣用名稱(後台的一次性顯示、CLI `--write-env`、文件都用這個) */
45
+ /** Conventional environment variable name (used by the dashboard's one-time display, the CLI's `--write-env` and the documentation) */
38
46
  export const SERVER_KEY_ENV_NAME = "KANORIO_SERVER_KEY";
39
- // ─── IP 工具(Worker 與 main 共用;不依賴 node:net,Workers 也能跑) ───
47
+ // --- IP utilities (shared by the edge worker and the server; no node:net dependency, so they run on Workers) ---
40
48
  function parseIpv4(value) {
41
49
  const parts = value.split(".");
42
50
  if (parts.length !== 4)
@@ -52,7 +60,7 @@ function parseIpv4(value) {
52
60
  }
53
61
  return out;
54
62
  }
55
- /** IPv6 → 16 bytes;支援 `::` 壓縮與結尾的 IPv4(`::ffff:1.2.3.4`)。不收 zone id */
63
+ /** IPv6 to 16 bytes; supports `::` compression and a trailing IPv4 (`::ffff:1.2.3.4`). Zone ids are not accepted */
56
64
  function parseIpv6(value) {
57
65
  if (!value.includes(":") || value.includes("%"))
58
66
  return null;
@@ -94,7 +102,7 @@ function parseIpv6(value) {
94
102
  bytes.splice(12, 4, ...tailV4);
95
103
  return bytes;
96
104
  }
97
- /** 解析 IP;`::ffff:a.b.c.d` 視為 IPv4。不合法回 null */
105
+ /** Parses an IP; `::ffff:a.b.c.d` is treated as IPv4. null when invalid */
98
106
  export function parseIp(raw) {
99
107
  const value = raw.trim();
100
108
  if (!value || value.length > 45)
@@ -121,7 +129,7 @@ function inPrefix(bytes, prefix, bits) {
121
129
  const mask = (0xff << (8 - rest)) & 0xff;
122
130
  return ((bytes[full] ?? 0) & mask) === ((prefix[full] ?? 0) & mask);
123
131
  }
124
- /** 不可路由到公網的位址:私有、loopback、link-local、CGNAT、文件用、多播與保留網段 */
132
+ /** Addresses not routable on the public internet: private, loopback, link-local, CGNAT, documentation, multicast and reserved ranges */
125
133
  const NON_PUBLIC_V4 = [
126
134
  [[0, 0, 0, 0], 8],
127
135
  [[10, 0, 0, 0], 8],
@@ -138,15 +146,15 @@ const NON_PUBLIC_V4 = [
138
146
  [[224, 0, 0, 0], 3],
139
147
  ];
140
148
  const NON_PUBLIC_V6 = [
141
- // ::/127(未指定與 loopback)
149
+ // ::/127 (unspecified and loopback)
142
150
  [[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 127],
143
151
  // fc00::/7 unique local
144
152
  [[0xfc, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 7],
145
153
  // fe80::/10 link-local
146
154
  [[0xfe, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 10],
147
- // ff00::/8 多播
155
+ // ff00::/8 multicast
148
156
  [[0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 8],
149
- // 2001:db8::/32 文件用
157
+ // 2001:db8::/32 documentation
150
158
  [[0x20, 0x01, 0x0d, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 32],
151
159
  ];
152
160
  export function isPublicIp(ip) {
@@ -162,8 +170,8 @@ function formatIp(ip) {
162
170
  return groups.join(":");
163
171
  }
164
172
  /**
165
- * 主機轉述的訪客 IP:必須是合法的公開位址,否則視為沒帶(回 null)。
166
- * 設錯的反向代理會把 10.x 這類內網位址轉過來,照收的話全站訪客會共用一個限流桶。
173
+ * The visitor IP relayed by the server: it must be a valid public address, otherwise it counts as absent (null).
174
+ * A misconfigured reverse proxy relays internal addresses such as 10.x; accepting them would put every visitor of the site in one rate-limit bucket.
167
175
  */
168
176
  export function normalizeVisitorIp(raw) {
169
177
  if (!raw)
@@ -173,7 +181,7 @@ export function normalizeVisitorIp(raw) {
173
181
  return null;
174
182
  return formatIp(parsed);
175
183
  }
176
- /** 限流桶的鍵:IPv4 用整個位址,IPv6 用 /64(同一個用戶端通常拿到整段 /64) */
184
+ /** Rate-limit bucket key: the whole address for IPv4, the /64 for IPv6 (one client usually gets a whole /64) */
177
185
  export function rateLimitKeyForIp(ip) {
178
186
  const parsed = parseIp(ip);
179
187
  if (!parsed)
@@ -182,11 +190,11 @@ export function rateLimitKeyForIp(ip) {
182
190
  return formatIp(parsed);
183
191
  return `${formatIp({ version: 6, bytes: [...parsed.bytes.slice(0, 8), 0, 0, 0, 0, 0, 0, 0, 0] })}/64`;
184
192
  }
185
- /** 最寬只收到 IPv4 /8、IPv6 /16:再寬就等於沒限制 */
193
+ /** The widest ranges accepted are IPv4 /8 and IPv6 /16: anything wider is no restriction at all */
186
194
  const MIN_PREFIX_BITS = { 4: 8, 6: 16 };
187
195
  /**
188
- * 解析來源限制的一筆 IP 或 CIDR。單一 IP 視為 /32(IPv6 為 /128)。
189
- * 拒收:格式錯、非公開網段、前綴過寬。
196
+ * Parses one IP or CIDR of a source restriction. A single IP is a /32 (/128 for IPv6).
197
+ * Rejected: malformed input, non-public ranges and prefixes that are too wide.
190
198
  */
191
199
  export function parseAllowedCidr(raw) {
192
200
  const value = raw.trim();
@@ -228,9 +236,9 @@ export function hasSourcePolicy(policy) {
228
236
  return policy.allowedCidrs.length > 0 || policy.allowedAsns.length > 0;
229
237
  }
230
238
  /**
231
- * 來源限制判定(比照 Stripe 存取政策):設了哪一類條件,那一類就必須符合;兩類都設就兩類都要符合。
232
- * 比對的是 Cloudflare 給的實際連線 IP 與 ASN,不是主機轉述的訪客 IP。
233
- * 有 ASN 條件但拿不到 ASN(本機開發、邊緣沒帶)時視為不符合。
239
+ * Source restriction check (like Stripe's access policies): whichever kind of condition is set must match; when both are set, both must match.
240
+ * Matched against the actual connecting IP and ASN from Cloudflare, not the visitor IP relayed by the server.
241
+ * With an ASN condition but no ASN available (local development, or the edge did not send it), the check fails.
234
242
  */
235
243
  export function isSourceAllowed(policy, source) {
236
244
  if (policy.allowedCidrs.length > 0) {
@@ -1,14 +1,14 @@
1
1
  import type { RegistryAttributionWire } from "./types.js";
2
- /** 登記資料的來源(是哪個登記,不是從哪條路徑取得) */
2
+ /** The source of registry data (which registry it is, not the route it was fetched through) */
3
3
  export type RegistrySource = "fia_tax_registration" | "gcis_company";
4
4
  /**
5
- * 政府開放資料的來源標示。授權條件(政府資料開放授權條款-第 1 版)要求使用時標示提供機關,
6
- * 所以回應、自動帶入的畫面與文件都要帶這一份。
5
+ * Attribution for government open data. The license (Taiwan's Open Government Data License, version 1) requires naming the providing agency on use,
6
+ * so responses, prefilled screens and documentation all carry this.
7
7
  */
8
8
  export declare const REGISTRY_ATTRIBUTION: Record<RegistrySource, RegistryAttributionWire>;
9
9
  export declare function registryAttribution(source: RegistrySource, dataDate?: string): RegistryAttributionWire;
10
10
  /**
11
- * 顯示來源標示時用哪個機關名稱:中文介面用原文,其餘語系用英文名稱。
12
- * 結帳、顧客中心、表單與後台都用這一份,不各自判斷語系。
11
+ * Which agency name to show in the attribution: the original name in Chinese interfaces, the English name in every other locale.
12
+ * Checkout, the customer account, forms and the dashboard all use this instead of deciding by locale themselves.
13
13
  */
14
14
  export declare function registryProviderName(attribution: Pick<RegistryAttributionWire, "provider" | "providerEn">, locale: string | null | undefined): string;
@@ -1,6 +1,6 @@
1
1
  /**
2
- * 政府開放資料的來源標示。授權條件(政府資料開放授權條款-第 1 版)要求使用時標示提供機關,
3
- * 所以回應、自動帶入的畫面與文件都要帶這一份。
2
+ * Attribution for government open data. The license (Taiwan's Open Government Data License, version 1) requires naming the providing agency on use,
3
+ * so responses, prefilled screens and documentation all carry this.
4
4
  */
5
5
  export const REGISTRY_ATTRIBUTION = {
6
6
  fia_tax_registration: {
@@ -20,8 +20,8 @@ export function registryAttribution(source, dataDate) {
20
20
  return dataDate ? { ...REGISTRY_ATTRIBUTION[source], dataDate } : REGISTRY_ATTRIBUTION[source];
21
21
  }
22
22
  /**
23
- * 顯示來源標示時用哪個機關名稱:中文介面用原文,其餘語系用英文名稱。
24
- * 結帳、顧客中心、表單與後台都用這一份,不各自判斷語系。
23
+ * Which agency name to show in the attribution: the original name in Chinese interfaces, the English name in every other locale.
24
+ * Checkout, the customer account, forms and the dashboard all use this instead of deciding by locale themselves.
25
25
  */
26
26
  export function registryProviderName(attribution, locale) {
27
27
  return locale?.toLowerCase().startsWith("zh") ? attribution.provider : attribution.providerEn;
@@ -1,3 +1,3 @@
1
1
  import type { TaxIdFormatDefinition } from "./types.js";
2
- /** 宣告一個稅號格式。只做型別收斂;登錄在 registry.ts */
2
+ /** Declares a tax ID format. It only narrows types; formats are registered in registry.ts */
3
3
  export declare function defineTaxIdFormat(definition: TaxIdFormatDefinition): TaxIdFormatDefinition;
@@ -1,4 +1,4 @@
1
- /** 宣告一個稅號格式。只做型別收斂;登錄在 registry.ts */
1
+ /** Declares a tax ID format. It only narrows types; formats are registered in registry.ts */
2
2
  export function defineTaxIdFormat(definition) {
3
3
  return definition;
4
4
  }
@@ -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
- * 歐盟 VAT 識別號:會員國前綴+各國格式。希臘的前綴是 EL(國碼是 GR)。
6
- * 各國格式依歐盟 VIES 的公開說明整理,尚未逐國對照官方文件核實,所以只警示、不擋;
7
- * 各國的檢查碼也還沒做。使用者只打號碼沒打前綴時補上前綴。
5
+ * EU VAT identification number: a member state prefix plus that country's format. Greece's prefix is EL (its country code is GR).
6
+ * The country formats follow the EU's public VIES notes and are not verified against each country's official documentation yet, so this only warns and never blocks;
7
+ * the countries' check digits are not implemented either. When the user types only the number, the prefix is added.
8
8
  */
9
9
  const EU_VAT = {
10
10
  AT: { prefix: "AT", pattern: /^ATU\d{8}$/, example: "ATU12345678" },
@@ -1,5 +1,5 @@
1
1
  /**
2
- * 香港商業登記號碼:8 碼數字(2023-12 起同時是「唯一業務識別碼」的號碼部分)。
3
- * 商業登記證上的完整號碼是「8 碼-分行 3 碼-…」,貼上整串時只取前 8 碼。官方沒有公開檢查碼。
2
+ * Hong Kong Business Registration number: 8 digits (since December 2023 also the number part of the Unique Business Identifier).
3
+ * The full number on a Business Registration Certificate is "8 digits - 3-digit branch - ...", so only the first 8 digits are taken from a pasted full number. No check digit is published.
4
4
  */
5
5
  export declare const hkBr: import("../types.js").TaxIdFormatDefinition;
@@ -1,9 +1,9 @@
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
- * 香港商業登記號碼:8 碼數字(2023-12 起同時是「唯一業務識別碼」的號碼部分)。
6
- * 商業登記證上的完整號碼是「8 碼-分行 3 碼-…」,貼上整串時只取前 8 碼。官方沒有公開檢查碼。
5
+ * Hong Kong Business Registration number: 8 digits (since December 2023 also the number part of the Unique Business Identifier).
6
+ * The full number on a Business Registration Certificate is "8 digits - 3-digit branch - ...", so only the first 8 digits are taken from a pasted full number. No check digit is published.
7
7
  */
8
8
  export const hkBr = defineTaxIdFormat({
9
9
  type: "hk_br",
@@ -11,7 +11,7 @@ export const hkBr = defineTaxIdFormat({
11
11
  stripeType: "hk_br",
12
12
  normalize: (cleaned) => {
13
13
  const digits = stripSeparators(cleaned);
14
- // 完整的登記證號碼:8 碼+分行 3 碼+年月等,共 16 碼
14
+ // The full certificate number: 8 digits, a 3-digit branch, year and month and so on, 16 digits in total
15
15
  return /^\d{16}$/.test(digits) && /\D/.test(cleaned) ? digits.slice(0, 8) : digits;
16
16
  },
17
17
  validate: (normalized) => (/^\d{8}$/.test(normalized) ? null : "FORMAT"),
@@ -1,6 +1,6 @@
1
1
  /**
2
- * 日本適格請求書發行事業者登錄番號:「T」+13 碼數字(國稅廳)。
3
- * 法人是 T+法人番號(有檢查碼);個人事業者是另外配發的 13 碼,官方沒有說明它是否滿足法人番號的檢查碼,
4
- * 所以這裡只驗格式,不驗檢查碼。只打 13 碼數字時補上 T。
2
+ * Japan's Qualified Invoice Issuer registration number: "T" plus 13 digits (National Tax Agency).
3
+ * A corporation's is T plus its Corporate Number (which has a check digit); a sole proprietor's is a separately assigned 13 digits, and the authority does not say whether it satisfies the Corporate Number check digit,
4
+ * so only the format is validated here, not a check digit. When only 13 digits are typed, the T is added.
5
5
  */
6
6
  export declare const jpTrn: import("../types.js").TaxIdFormatDefinition;
@@ -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
- * 日本適格請求書發行事業者登錄番號:「T」+13 碼數字(國稅廳)。
6
- * 法人是 T+法人番號(有檢查碼);個人事業者是另外配發的 13 碼,官方沒有說明它是否滿足法人番號的檢查碼,
7
- * 所以這裡只驗格式,不驗檢查碼。只打 13 碼數字時補上 T。
5
+ * Japan's Qualified Invoice Issuer registration number: "T" plus 13 digits (National Tax Agency).
6
+ * A corporation's is T plus its Corporate Number (which has a check digit); a sole proprietor's is a separately assigned 13 digits, and the authority does not say whether it satisfies the Corporate Number check digit,
7
+ * so only the format is validated here, not a check digit. When only 13 digits are typed, the T is added.
8
8
  */
9
9
  export const jpTrn = defineTaxIdFormat({
10
10
  type: "jp_trn",
@@ -1,6 +1,6 @@
1
1
  /**
2
- * 韓國事業者登錄番號:10 碼數字(常寫成 XXX-XX-XXXXX)+檢查碼。
3
- * 前 9 碼乘上權重 [1,3,7,1,3,7,1,3,5] 加總,再加上「第 9 碼 × 5」的十位數;(10 − 總和 % 10) % 10 要等於第 10 碼。
2
+ * South Korea's Business Registration Number: 10 digits (often written XXX-XX-XXXXX) with a check digit.
3
+ * The first 9 digits are multiplied by the weights [1,3,7,1,3,7,1,3,5] and summed, plus the tens digit of "9th digit x 5"; (10 - sum % 10) % 10 must equal the 10th digit.
4
4
  */
5
5
  export declare function isValidKrBrn(normalized: string): boolean;
6
6
  export declare const krBrn: import("../types.js").TaxIdFormatDefinition;
@@ -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
  const WEIGHTS = [1, 3, 7, 1, 3, 7, 1, 3, 5];
5
5
  /**
6
- * 韓國事業者登錄番號:10 碼數字(常寫成 XXX-XX-XXXXX)+檢查碼。
7
- * 前 9 碼乘上權重 [1,3,7,1,3,7,1,3,5] 加總,再加上「第 9 碼 × 5」的十位數;(10 − 總和 % 10) % 10 要等於第 10 碼。
6
+ * South Korea's Business Registration Number: 10 digits (often written XXX-XX-XXXXX) with a check digit.
7
+ * The first 9 digits are multiplied by the weights [1,3,7,1,3,7,1,3,5] and summed, plus the tens digit of "9th digit x 5"; (10 - sum % 10) % 10 must equal the 10th digit.
8
8
  */
9
9
  export function isValidKrBrn(normalized) {
10
10
  if (!/^\d{10}$/.test(normalized))
@@ -1,7 +1,7 @@
1
1
  /**
2
- * 馬來西亞稅號。兩種都依公開範例整理、尚未對照 LHDN 與關稅局的官方文件核實,只警示不擋。
3
- * - my_itn:所得稅號(TIN),類別字母 1–2 碼+數字(如 C 1234567890);電子發票(MyInvois)用的就是它
4
- * - my_sst:銷售與服務稅登記號(如 A12-3456-78912345)
2
+ * 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.
3
+ * - 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
4
+ * - my_sst: Sales and Service Tax registration number (for example A12-3456-78912345)
5
5
  */
6
6
  export declare const myItn: import("../types.js").TaxIdFormatDefinition;
7
7
  export declare const mySst: import("../types.js").TaxIdFormatDefinition;