@kanorio/sdk 1.0.0 → 1.1.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 (76) hide show
  1. package/README.md +2 -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 +19 -19
  10. package/dist/forms.d.ts +13 -13
  11. package/dist/forms.js +13 -13
  12. package/dist/generated/delivery.d.ts +35 -7
  13. package/dist/generated/management.d.ts +111 -26
  14. package/dist/http.d.ts +13 -13
  15. package/dist/http.js +8 -8
  16. package/dist/index.js +2 -2
  17. package/dist/locales.d.ts +22 -22
  18. package/dist/locales.js +12 -12
  19. package/dist/management.d.ts +5 -5
  20. package/dist/management.js +3 -3
  21. package/dist/paginate.d.ts +3 -3
  22. package/dist/paginate.js +3 -3
  23. package/dist/preview.d.ts +13 -13
  24. package/dist/preview.js +11 -11
  25. package/dist/protection.d.ts +18 -18
  26. package/dist/protection.js +11 -11
  27. package/dist/revalidate.d.ts +22 -22
  28. package/dist/revalidate.js +14 -14
  29. package/dist/seo.d.ts +20 -20
  30. package/dist/seo.js +20 -20
  31. package/dist/server-key.d.ts +2 -2
  32. package/dist/server-key.js +2 -2
  33. package/dist/shared/api/delivery/cache-tags.d.ts +39 -39
  34. package/dist/shared/api/delivery/cache-tags.js +34 -34
  35. package/dist/shared/api/server-key.d.ts +32 -28
  36. package/dist/shared/api/server-key.js +41 -33
  37. package/dist/shared/business-registry/attribution.d.ts +5 -5
  38. package/dist/shared/business-registry/attribution.js +4 -4
  39. package/dist/shared/business-registry/define.d.ts +1 -1
  40. package/dist/shared/business-registry/define.js +1 -1
  41. package/dist/shared/business-registry/formats/eu-vat.js +4 -4
  42. package/dist/shared/business-registry/formats/hk-br.d.ts +2 -2
  43. package/dist/shared/business-registry/formats/hk-br.js +4 -4
  44. package/dist/shared/business-registry/formats/jp-trn.d.ts +3 -3
  45. package/dist/shared/business-registry/formats/jp-trn.js +4 -4
  46. package/dist/shared/business-registry/formats/kr-brn.d.ts +2 -2
  47. package/dist/shared/business-registry/formats/kr-brn.js +3 -3
  48. package/dist/shared/business-registry/formats/my.d.ts +3 -3
  49. package/dist/shared/business-registry/formats/my.js +4 -4
  50. package/dist/shared/business-registry/formats/sg-uen.js +4 -4
  51. package/dist/shared/business-registry/formats/tw-vat.d.ts +5 -5
  52. package/dist/shared/business-registry/formats/tw-vat.js +6 -6
  53. package/dist/shared/business-registry/index.js +1 -1
  54. package/dist/shared/business-registry/lookup-wire.d.ts +9 -9
  55. package/dist/shared/business-registry/lookup-wire.js +4 -4
  56. package/dist/shared/business-registry/normalize.d.ts +3 -3
  57. package/dist/shared/business-registry/normalize.js +4 -4
  58. package/dist/shared/business-registry/registry.d.ts +9 -9
  59. package/dist/shared/business-registry/registry.js +13 -13
  60. package/dist/shared/business-registry/types.d.ts +20 -20
  61. package/dist/shared/business-registry/types.js +6 -6
  62. package/dist/shared/localization/locale-path.d.ts +18 -18
  63. package/dist/shared/localization/locale-path.js +18 -18
  64. package/dist/shared/localization/request-locale.d.ts +16 -16
  65. package/dist/shared/localization/request-locale.js +13 -13
  66. package/dist/shared/seo/alternates.d.ts +26 -26
  67. package/dist/shared/seo/alternates.js +18 -18
  68. package/dist/shared/types/forms-logic.d.ts +28 -28
  69. package/dist/shared/types/forms-logic.js +27 -27
  70. package/dist/shared/types/number-input.d.ts +2 -2
  71. package/dist/shared/types/number-input.js +3 -3
  72. package/dist/shared/utils/redirect-matching.d.ts +33 -24
  73. package/dist/shared/utils/redirect-matching.js +73 -40
  74. package/dist/typed.d.ts +5 -5
  75. package/dist/typed.js +3 -3
  76. package/package.json +10 -10
@@ -1,19 +1,19 @@
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
- * 用戶網站的 canonical 與 hreflang(ADR-0010 決策 4、10;benchmark §H)。`<head>` 與 sitemap 都呼叫這一個函式,確保同源。
3
+ * Canonical and hreflang for a customer site. `<head>` and the sitemap both call this one function, so they always agree.
4
4
  *
5
- * 規則:
6
- * - 主語系無前綴(`/about`),次語系子目錄(`/en/about`);前綴是語系存下來的 `pathPrefix`(`locale-path.ts`)。
7
- * - 每個語系版本 self-canonical;只列「已上線且這一頁有翻譯」的語系,加主語系;x-default 指主語系。
8
- * - fallback 頁(請求次語系但這一頁沒翻譯,服務的是主語系內容):canonical 指主語系網址、不出 hreflang。
9
- * - hreflang 代碼:`zh-Hant → zh-TW`,其餘照語系碼;Google 接受 `en-US`、`pt-BR` 這類 BCP 47。
10
- * - 語言 catchall(Nuxt i18n 做法,benchmark §C3b):某語言在這組版本裡只有一個地區版本(`en-US`)時,
11
- * 多列一個純語言 hreflang(`en`)指同一個網址,其他地區的同語言使用者也對得到;同語言有兩個以上版本時不列
12
- * (指哪一個沒有依據,交給 Google);中文不列(繁、簡、港是不同書寫系統)。
13
- * - 永不依 Accept-Language 或 IP 轉址(這裡只產生標記)。
5
+ * Rules:
6
+ * - The primary locale has no prefix (`/about`) and secondary locales use a subdirectory (`/en/about`); the prefix is the locale's saved `pathPrefix` (`locale-path.ts`).
7
+ * - Each locale version is self-canonical; only locales that are live and have a translation of this page are listed, plus the primary locale; x-default points to the primary locale.
8
+ * - A fallback page (a secondary locale was requested but this page has no translation, so primary-locale content is served): canonical points to the primary locale URL and no hreflang is emitted.
9
+ * - hreflang codes: `zh-Hant` becomes `zh-TW`, everything else is the locale code; Google accepts BCP 47 such as `en-US` and `pt-BR`.
10
+ * - Language catch-all (as Nuxt i18n does): when a language has a single regional version in this set (`en-US`),
11
+ * a bare-language hreflang (`en`) is added for the same URL so users of that language elsewhere match it too; it is not added when the language has two or more versions
12
+ * (there is no basis for choosing one, so it is left to Google) and never for Chinese (Traditional, Simplified and Hong Kong are different writing systems).
13
+ * - Never redirects by Accept-Language or IP (this only produces markup).
14
14
  */
15
15
  import { languageOfLocale } from "../localization/locale-path.js";
16
- /** 網站語系碼 → hreflang(行銷站 LOCALE_TO_HREFLANG 的泛化) */
16
+ /** Site locale code to hreflang */
17
17
  export function hreflangOf(locale) {
18
18
  if (locale === "zh-Hant")
19
19
  return "zh-TW";
@@ -22,18 +22,18 @@ export function hreflangOf(locale) {
22
22
  function pathIn(locale, path, localizedPaths) {
23
23
  return localizedPaths?.[locale] ?? path;
24
24
  }
25
- /** 某語系的這一頁網址 */
25
+ /** This page's URL in a locale */
26
26
  export function localizedSiteUrl(siteUrl, primaryLocale, locale, path, localePrefixes) {
27
27
  const base = siteUrl.replace(/\/+$/, "");
28
28
  const cleanPath = path === "/" || path === "" ? "" : path.startsWith("/") ? path : `/${path}`;
29
- // 首頁沿用站內既有慣例:主語系首頁是 `https://host`(不帶尾斜線),次語系 `https://host/en`
29
+ // The home page follows the site's convention: the primary home page is `https://host` (no trailing slash), a secondary one is `https://host/en`
30
30
  if (locale === primaryLocale)
31
31
  return `${base}${cleanPath}`;
32
32
  return `${base}/${localePrefixes[locale] ?? locale.toLowerCase()}${cleanPath}`;
33
33
  }
34
34
  /**
35
- * 一組語系版本的 hreflang → 網址(主語系在前、次語系依碼排序、語言 catchall、最後 x-default 指主語系)。
36
- * `<head>` 的 alternates 與 sitemap 的 `<xhtml:link>` 都由這裡產生。
35
+ * hreflang to URL for a set of locale versions (primary first, secondary locales sorted by code, language catch-alls, and x-default last pointing to the primary).
36
+ * Both the alternates in `<head>` and the sitemap's `<xhtml:link>` are produced here.
37
37
  */
38
38
  export function hreflangEntries(siteUrl, path, primaryLocale, secondaryLocales, localePrefixes, localizedPaths) {
39
39
  const versions = [primaryLocale, ...[...new Set(secondaryLocales.filter((l) => l !== primaryLocale))].sort()];
@@ -57,7 +57,7 @@ export function hreflangEntries(siteUrl, path, primaryLocale, secondaryLocales,
57
57
  export function buildSiteAlternates(input) {
58
58
  const { siteUrl, path, primaryLocale, requestLocale, resolvedLocale, localePrefixes, localizedPaths } = input;
59
59
  const canonical = localizedSiteUrl(siteUrl, primaryLocale, resolvedLocale, pathIn(resolvedLocale, path, localizedPaths), localePrefixes);
60
- // fallback:請求次語系但服務的是主語系內容 → canonical 指主語系、不出 hreflang
60
+ // Fallback: a secondary locale was requested but primary-locale content is served, so canonical points to the primary and no hreflang is emitted
61
61
  if (resolvedLocale !== requestLocale)
62
62
  return { canonical, languages: {} };
63
63
  const languages = {};
@@ -65,7 +65,7 @@ export function buildSiteAlternates(input) {
65
65
  languages[entry.hreflang] = entry.href;
66
66
  return { canonical, languages };
67
67
  }
68
- /** sitemap `<xhtml:link rel="alternate">` 用:同一頁所有版本(含主語系、語言 catchall 與 x-default) */
68
+ /** For the sitemap's `<xhtml:link rel="alternate">`: every version of the same page (primary, language catch-alls and x-default) */
69
69
  export function sitemapAlternates(siteUrl, path, primaryLocale, availableLocales, localePrefixes, localizedPaths) {
70
70
  return hreflangEntries(siteUrl, path, primaryLocale, availableLocales, localePrefixes, localizedPaths).map(({ hreflang, href }) => ({ hreflang, href }));
71
71
  }
@@ -1,33 +1,33 @@
1
1
  /**
2
- * 線上表單的條件顯示:「選了 A 才出現這一題」。
2
+ * Conditional display for online forms: "this question appears only when A is chosen".
3
3
  *
4
- * 一題可以帶 `visibleWhen`:一組條件(最多 5 個),全部符合(`all`)或任一符合(`any`)時才顯示。
5
- * 前台(決定畫哪些題)與伺服器(決定驗哪些題、存哪些答案)都呼叫 `resolveVisibleFieldIds`,所以兩邊一定一致:
6
- * 被隱藏的題目不顯示、不驗證(必填也不擋)、答案存 null。
4
+ * A question can carry `visibleWhen`: a set of conditions (at most 5) that shows it when all (`all`) or any (`any`) of them match.
5
+ * The storefront (deciding which questions to draw) and the server (deciding which to validate and which answers to store) both call `resolveVisibleFieldIds`, so the two always agree:
6
+ * a hidden question is not shown, not validated (required does not block) and its answer is stored as null.
7
7
  *
8
- * 規則:
9
- * - 條件只能參照排在前面的題目(`kind: "field"`)或表單的隱藏欄位(`kind: "hidden"`)
10
- * - 來源題自己被隱藏時,當作沒有作答
11
- * - Email 與電話題不能被隱藏(它們是聯絡人的識別,表單的其他規則都靠它們)
12
- * - 規則無法判斷時(來源不存在、排在後面、運算子不適用)一律顯示:寧可多問一題,不要讓必填題永遠藏起來
8
+ * Rules:
9
+ * - A condition can only refer to an earlier question (`kind: "field"`) or one of the form's hidden fields (`kind: "hidden"`)
10
+ * - When the source question is itself hidden, it counts as unanswered
11
+ * - Email and phone questions cannot be hidden (they identify the contact, and the form's other rules rely on them)
12
+ * - When a rule cannot be evaluated (missing source, a later question, an operator that does not apply), the question is shown: better to ask one question too many than to hide a required one forever
13
13
  *
14
- * 零依賴的純函式:`@kanorio/sdk` 以複製的方式帶走,自建前端用同一份判斷。資料夾內只用相對 import。
15
- * 之後要做計分時,在 `kind` 加一種來源(變數)即可,不用搬資料。
14
+ * Pure functions with no dependencies: `@kanorio/sdk` carries a copy, so a self-hosted front end evaluates the same way. Only relative imports inside this folder.
15
+ * Scoring, if added later, only needs one more source in `kind` (a variable), with no data migration.
16
16
  */
17
17
  export declare const FORM_CONDITION_OPS: readonly ["answered", "not_answered", "includes", "not_includes", "equals", "not_equals", "contains", "gt", "gte", "lt", "lte"];
18
18
  export type FormConditionOp = (typeof FORM_CONDITION_OPS)[number];
19
19
  export declare const FORM_LOGIC_LIMITS: {
20
- /** 一題最多幾個條件 */
20
+ /** Maximum conditions per question */
21
21
  readonly MAX_CONDITIONS: 5;
22
- /** 條件比對文字的長度上限 */
22
+ /** Maximum length of a condition's comparison text */
23
23
  readonly VALUE_MAX: 200;
24
24
  };
25
25
  export interface FormCondition {
26
- /** 來源是題目(`ref` 為題目 id)還是隱藏欄位(`ref` 為隱藏欄位 id) */
26
+ /** Whether the source is a question (`ref` is the question id) or a hidden field (`ref` is the hidden field id) */
27
27
  kind: "field" | "hidden";
28
28
  ref: string;
29
29
  op: FormConditionOp;
30
- /** 選項 id(includes)、比對文字(equals/contains)或數字(數字比較);有無作答不用值 */
30
+ /** An option id (includes), comparison text (equals, contains) or a number (numeric comparison); answered and unanswered take no value */
31
31
  value?: string | number;
32
32
  }
33
33
  export interface FormVisibleWhen {
@@ -35,8 +35,8 @@ export interface FormVisibleWhen {
35
35
  conditions: FormCondition[];
36
36
  }
37
37
  /**
38
- * 每種來源可以用哪些運算子。電話、日期、時間、Email 只能判斷有沒有作答;檔案、說明文字、地址與稅號不能當來源(空陣列)。
39
- * 新增題型時要在這裡補一筆(forms.ts 有編譯期檢查)。
38
+ * Which operators each source supports. Phone, date, time and email can only be tested for answered or not; file, description text, address and tax ID cannot be sources (empty arrays).
39
+ * A new question type needs an entry here (forms.ts has a compile-time check).
40
40
  */
41
41
  export declare const CONDITION_OPS_BY_TYPE: {
42
42
  readonly short_text: readonly ["answered", "not_answered", "equals", "not_equals", "contains"];
@@ -53,15 +53,15 @@ export declare const CONDITION_OPS_BY_TYPE: {
53
53
  readonly statement: readonly [];
54
54
  readonly address: readonly [];
55
55
  readonly tax_id: readonly [];
56
- /** 隱藏欄位(網址參數帶入的字串) */
56
+ /** A hidden field (a string taken from a URL parameter) */
57
57
  readonly hidden: readonly ["answered", "not_answered", "equals", "not_equals", "contains"];
58
58
  };
59
59
  export type FormConditionSourceType = keyof typeof CONDITION_OPS_BY_TYPE;
60
60
  export declare function conditionOpsFor(sourceType: string): readonly FormConditionOp[];
61
- /** 這個運算子要搭配哪一種值 */
61
+ /** Which kind of value this operator takes */
62
62
  export type FormConditionValueKind = "none" | "option" | "text" | "number";
63
63
  export declare function conditionValueKind(sourceType: string, op: FormConditionOp): FormConditionValueKind;
64
- /** 條件判斷需要的題目資訊(表單定義的子集) */
64
+ /** The question details conditional logic needs (a subset of the form definition) */
65
65
  export interface LogicField {
66
66
  id: string;
67
67
  type: string;
@@ -71,13 +71,13 @@ export interface LogicField {
71
71
  }>;
72
72
  }
73
73
  export type FormConditionIssue =
74
- /** 來源不存在,或不是排在前面的題目 */
74
+ /** The source does not exist, or is not an earlier question */
75
75
  "missing_source" | "op_not_allowed" | "value_required" | "value_unexpected"
76
- /** 值的型別不對(該填數字卻是文字,或反過來) */
76
+ /** The value has the wrong type (text where a number is needed, or the reverse) */
77
77
  | "value_type" | "unknown_option";
78
78
  /**
79
- * 檢查一個條件對它的來源是否成立。`source` 為 undefined 表示找不到來源。
80
- * schema(存檔時擋)與編輯器(即時標示)共用。
79
+ * Checks whether a condition is valid for its source. `source` is undefined when the source cannot be found.
80
+ * Shared by the schema (blocking on save) and the editor (marking as you type).
81
81
  */
82
82
  export declare function findConditionIssue(condition: FormCondition, source: {
83
83
  type: string;
@@ -85,12 +85,12 @@ export declare function findConditionIssue(condition: FormCondition, source: {
85
85
  id: string;
86
86
  }>;
87
87
  } | undefined): FormConditionIssue | null;
88
- /** 單一條件對一個答案是否成立;運算子不適用於這種來源時回 null(無法判斷) */
88
+ /** Whether a single condition holds for an answer; null when the operator does not apply to this source (cannot be evaluated) */
89
89
  export declare function evaluateCondition(condition: FormCondition, sourceType: string, raw: unknown): boolean | null;
90
90
  /**
91
- * 依目前的答案算出要顯示哪些題目。`answers` 是「題目 id 或隱藏欄位 id → 值」(訪客輸入的原始值即可)。
92
- * 依題目順序往下算:前面的題目被隱藏時,參照它的條件把它當作沒有作答。
91
+ * Works out which questions to show from the current answers. `answers` maps a question id or hidden field id to its value (the raw value the visitor typed is fine).
92
+ * Evaluated in question order: when an earlier question is hidden, a condition referring to it treats it as unanswered.
93
93
  */
94
94
  export declare function resolveVisibleFieldIds(fields: readonly LogicField[], answers: Readonly<Record<string, unknown>>): Set<string>;
95
- /** 這張表單有沒有任何條件顯示(沒有的話前台不用每次輸入都重算) */
95
+ /** Whether this form has any conditional display (without it, the storefront need not recompute on every input) */
96
96
  export declare function hasVisibilityRules(fields: readonly LogicField[]): boolean;
@@ -1,19 +1,19 @@
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
- * 線上表單的條件顯示:「選了 A 才出現這一題」。
3
+ * Conditional display for online forms: "this question appears only when A is chosen".
4
4
  *
5
- * 一題可以帶 `visibleWhen`:一組條件(最多 5 個),全部符合(`all`)或任一符合(`any`)時才顯示。
6
- * 前台(決定畫哪些題)與伺服器(決定驗哪些題、存哪些答案)都呼叫 `resolveVisibleFieldIds`,所以兩邊一定一致:
7
- * 被隱藏的題目不顯示、不驗證(必填也不擋)、答案存 null。
5
+ * A question can carry `visibleWhen`: a set of conditions (at most 5) that shows it when all (`all`) or any (`any`) of them match.
6
+ * The storefront (deciding which questions to draw) and the server (deciding which to validate and which answers to store) both call `resolveVisibleFieldIds`, so the two always agree:
7
+ * a hidden question is not shown, not validated (required does not block) and its answer is stored as null.
8
8
  *
9
- * 規則:
10
- * - 條件只能參照排在前面的題目(`kind: "field"`)或表單的隱藏欄位(`kind: "hidden"`)
11
- * - 來源題自己被隱藏時,當作沒有作答
12
- * - Email 與電話題不能被隱藏(它們是聯絡人的識別,表單的其他規則都靠它們)
13
- * - 規則無法判斷時(來源不存在、排在後面、運算子不適用)一律顯示:寧可多問一題,不要讓必填題永遠藏起來
9
+ * Rules:
10
+ * - A condition can only refer to an earlier question (`kind: "field"`) or one of the form's hidden fields (`kind: "hidden"`)
11
+ * - When the source question is itself hidden, it counts as unanswered
12
+ * - Email and phone questions cannot be hidden (they identify the contact, and the form's other rules rely on them)
13
+ * - When a rule cannot be evaluated (missing source, a later question, an operator that does not apply), the question is shown: better to ask one question too many than to hide a required one forever
14
14
  *
15
- * 零依賴的純函式:`@kanorio/sdk` 以複製的方式帶走,自建前端用同一份判斷。資料夾內只用相對 import。
16
- * 之後要做計分時,在 `kind` 加一種來源(變數)即可,不用搬資料。
15
+ * Pure functions with no dependencies: `@kanorio/sdk` carries a copy, so a self-hosted front end evaluates the same way. Only relative imports inside this folder.
16
+ * Scoring, if added later, only needs one more source in `kind` (a variable), with no data migration.
17
17
  */
18
18
  import { parseNumberInput } from "./number-input.js";
19
19
  export const FORM_CONDITION_OPS = [
@@ -30,9 +30,9 @@ export const FORM_CONDITION_OPS = [
30
30
  "lte",
31
31
  ];
32
32
  export const FORM_LOGIC_LIMITS = {
33
- /** 一題最多幾個條件 */
33
+ /** Maximum conditions per question */
34
34
  MAX_CONDITIONS: 5,
35
- /** 條件比對文字的長度上限 */
35
+ /** Maximum length of a condition's comparison text */
36
36
  VALUE_MAX: 200,
37
37
  };
38
38
  const PRESENCE_OPS = ["answered", "not_answered"];
@@ -40,8 +40,8 @@ const TEXT_OPS = ["answered", "not_answered", "equals", "not_equals", "contains"
40
40
  const CHOICE_OPS = ["answered", "not_answered", "includes", "not_includes"];
41
41
  const NUMBER_OPS = ["answered", "not_answered", "equals", "not_equals", "gt", "gte", "lt", "lte"];
42
42
  /**
43
- * 每種來源可以用哪些運算子。電話、日期、時間、Email 只能判斷有沒有作答;檔案、說明文字、地址與稅號不能當來源(空陣列)。
44
- * 新增題型時要在這裡補一筆(forms.ts 有編譯期檢查)。
43
+ * Which operators each source supports. Phone, date, time and email can only be tested for answered or not; file, description text, address and tax ID cannot be sources (empty arrays).
44
+ * A new question type needs an entry here (forms.ts has a compile-time check).
45
45
  */
46
46
  export const CONDITION_OPS_BY_TYPE = {
47
47
  short_text: TEXT_OPS,
@@ -58,7 +58,7 @@ export const CONDITION_OPS_BY_TYPE = {
58
58
  statement: [],
59
59
  address: [],
60
60
  tax_id: [],
61
- /** 隱藏欄位(網址參數帶入的字串) */
61
+ /** A hidden field (a string taken from a URL parameter) */
62
62
  hidden: TEXT_OPS,
63
63
  };
64
64
  export function conditionOpsFor(sourceType) {
@@ -85,8 +85,8 @@ export function conditionValueKind(sourceType, op) {
85
85
  }
86
86
  }
87
87
  /**
88
- * 檢查一個條件對它的來源是否成立。`source` 為 undefined 表示找不到來源。
89
- * schema(存檔時擋)與編輯器(即時標示)共用。
88
+ * Checks whether a condition is valid for its source. `source` is undefined when the source cannot be found.
89
+ * Shared by the schema (blocking on save) and the editor (marking as you type).
90
90
  */
91
91
  export function findConditionIssue(condition, source) {
92
92
  if (!source)
@@ -116,11 +116,11 @@ function isAnswered(raw) {
116
116
  return raw.length > 0;
117
117
  return true;
118
118
  }
119
- /** 文字比對不分大小寫、不計頭尾空白、全形半形視為相同 */
119
+ /** Text comparison ignores case and surrounding whitespace, and treats full-width and half-width as the same */
120
120
  function foldText(value) {
121
121
  return typeof value === "string" ? value.normalize("NFKC").trim().toLowerCase() : typeof value === "number" ? String(value) : "";
122
122
  }
123
- /** 單一條件對一個答案是否成立;運算子不適用於這種來源時回 null(無法判斷) */
123
+ /** Whether a single condition holds for an answer; null when the operator does not apply to this source (cannot be evaluated) */
124
124
  export function evaluateCondition(condition, sourceType, raw) {
125
125
  if (!conditionOpsFor(sourceType).includes(condition.op))
126
126
  return null;
@@ -154,7 +154,7 @@ export function evaluateCondition(condition, sourceType, raw) {
154
154
  case "lte": {
155
155
  const number = parseNumberInput(raw);
156
156
  const target = typeof condition.value === "number" ? condition.value : null;
157
- // 沒填或不是數字:比較不成立
157
+ // Empty or not a number: the comparison does not hold
158
158
  if (number === null || target === null)
159
159
  return false;
160
160
  if (condition.op === "gt")
@@ -168,8 +168,8 @@ export function evaluateCondition(condition, sourceType, raw) {
168
168
  }
169
169
  }
170
170
  /**
171
- * 依目前的答案算出要顯示哪些題目。`answers` 是「題目 id 或隱藏欄位 id → 值」(訪客輸入的原始值即可)。
172
- * 依題目順序往下算:前面的題目被隱藏時,參照它的條件把它當作沒有作答。
171
+ * Works out which questions to show from the current answers. `answers` maps a question id or hidden field id to its value (the raw value the visitor typed is fine).
172
+ * Evaluated in question order: when an earlier question is hidden, a condition referring to it treats it as unanswered.
173
173
  */
174
174
  export function resolveVisibleFieldIds(fields, answers) {
175
175
  const visible = new Set();
@@ -177,7 +177,7 @@ export function resolveVisibleFieldIds(fields, answers) {
177
177
  for (const field of fields) {
178
178
  const rule = field.visibleWhen;
179
179
  const conditions = rule && Array.isArray(rule.conditions) ? rule.conditions : [];
180
- // Email 與電話是聯絡人的識別,不受條件影響
180
+ // Email and phone identify the contact and are not affected by conditions
181
181
  if (conditions.length === 0 || field.type === "email" || field.type === "phone") {
182
182
  visible.add(field.id);
183
183
  seen.set(field.id, field.type);
@@ -190,7 +190,7 @@ export function resolveVisibleFieldIds(fields, answers) {
190
190
  undecidable = true;
191
191
  return false;
192
192
  }
193
- // 來源題自己被隱藏:當作沒有作答
193
+ // The source question is itself hidden: treated as unanswered
194
194
  const raw = condition.kind === "hidden" || visible.has(condition.ref) ? answers[condition.ref] : null;
195
195
  const result = evaluateCondition(condition, sourceType, raw);
196
196
  if (result === null)
@@ -203,7 +203,7 @@ export function resolveVisibleFieldIds(fields, answers) {
203
203
  }
204
204
  return visible;
205
205
  }
206
- /** 這張表單有沒有任何條件顯示(沒有的話前台不用每次輸入都重算) */
206
+ /** Whether this form has any conditional display (without it, the storefront need not recompute on every input) */
207
207
  export function hasVisibilityRules(fields) {
208
208
  return fields.some((field) => (field.visibleWhen?.conditions?.length ?? 0) > 0);
209
209
  }
@@ -1,5 +1,5 @@
1
1
  /**
2
- * 訪客輸入的數字 → number。接受全形數字(中日韓輸入法常見)與千分位逗號;不是有限數字回 null。
3
- * 零依賴:表單驗證、條件判斷與 `@kanorio/sdk` 用同一份。
2
+ * A visitor's typed number to a number. Accepts full-width digits (common with Chinese, Japanese and Korean input methods) and thousands separators; null when it is not a finite number.
3
+ * No dependencies: form validation, conditional logic and `@kanorio/sdk` use the same code.
4
4
  */
5
5
  export declare function parseNumberInput(raw: unknown): number | null;
@@ -1,7 +1,7 @@
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
- * 訪客輸入的數字 → number。接受全形數字(中日韓輸入法常見)與千分位逗號;不是有限數字回 null。
4
- * 零依賴:表單驗證、條件判斷與 `@kanorio/sdk` 用同一份。
3
+ * A visitor's typed number to a number. Accepts full-width digits (common with Chinese, Japanese and Korean input methods) and thousands separators; null when it is not a finite number.
4
+ * No dependencies: form validation, conditional logic and `@kanorio/sdk` use the same code.
5
5
  */
6
6
  export function parseNumberInput(raw) {
7
7
  if (typeof raw === "number")
@@ -1,27 +1,36 @@
1
1
  /**
2
- * 網址轉址「比對 + 迴圈偵測」的單一真實來源(跨 app 契約)。
2
+ * The single source of truth for URL redirect matching and loop detection (a contract across apps).
3
3
  *
4
- * - public-sites middleware 於 runtime 用 `matchRedirect` 執行實際轉址。
5
- * - apps/main 於存檔前用 `isSelfLoop` / `findRedirectLoopKeys` / `hasRedirectChainLoop`
6
- * 模擬同一套比對來偵測迴圈。
4
+ * - The hosted-site middleware uses `matchRedirect` at runtime to perform redirects.
5
+ * - Before saving, the server uses `isSelfLoop`, `findRedirectLoopKeys` and `hasRedirectChainLoop`
6
+ * to simulate the same matching and detect loops.
7
7
  *
8
- * 兩者共用此模組,比對語意(精確優先 → 最長 wildcard prefix → 相對/wildcard 目標解析)
9
- * 永遠一致,不會 drift。純字串函式,無 React / node 依賴,可於 edge runtime 安全打包。
8
+ * Both use this module, so the matching rules (exact first, then the longest wildcard prefix, then resolving relative and wildcard targets)
9
+ * never drift apart. Pure string functions with no React or Node dependency, safe to bundle for an edge runtime.
10
10
  */
11
11
  export type RedirectRuleLite = {
12
12
  sourcePath: string;
13
13
  targetUrl: string;
14
14
  statusCode?: number;
15
15
  /**
16
- * 規則屬於哪個語系(ADR-0010 決策 18):null/未設=各語系共用,以無語系前綴的路徑比對、站內目標再接回前綴;
17
- * 有值=只屬於那個語系(翻譯代稱改名、語系停用、改前綴),來源與目標都已含前綴,以完整路徑比對、目標原樣用。
16
+ * The locale a rule belongs to. null or unset: shared by every locale, matched on the path without the locale prefix, with in-site targets given the prefix back.
17
+ * A value: belongs to that locale only (a renamed translated slug, a disabled locale, a changed prefix); source and target already include the prefix, matched on the full path with the target used as is.
18
18
  */
19
19
  locale?: string | null;
20
20
  };
21
21
  /**
22
- * 依比對規則解析單一路徑:精確比對優先,否則最長 wildcard prefix(`sourcePath` 結尾 `/*`)。
23
- * 目標結尾 `/*` 時保留剩餘子路徑;否則全部導向同一目標。
24
- * 回傳命中的規則、解析後目標字串(可為站內相對路徑或完整外部網址)與狀態碼;無匹配回傳 null。
22
+ * Paths are matched in canonical form: the percent-encoding browsers actually send, with escape codes in uppercase; query and fragment are not part of the path.
23
+ *
24
+ * A visitor's pathname arrives encoded (`/%E7%94%A2%E5%93%81.pdf`), while the source an owner typed may be raw characters
25
+ * or an encoded string pasted from the address bar (in either case). Compared as plain strings, a rule written in raw characters would never match.
26
+ * Both sides go through this function before comparing; it parses with the WHATWG URL, so the result agrees with browsers and `NextRequest.nextUrl.pathname`.
27
+ */
28
+ export declare function canonicalRedirectPath(path: string): string;
29
+ /**
30
+ * Resolves one path by the matching rules: exact match first, otherwise the longest wildcard prefix (a `sourcePath` ending in `/*`).
31
+ * A target ending in `/*` keeps the remaining sub-path; otherwise everything goes to the same target.
32
+ * Returns the matched rule, the resolved target (an in-site relative path or a full external URL) and the status code; null without a match.
33
+ * Path and source are both compared in the canonical form of `canonicalRedirectPath` (raw and percent-encoded are the same path).
25
34
  */
26
35
  export declare function matchRedirect<R extends RedirectRuleLite>(pathname: string, rules: R[]): {
27
36
  rule: R;
@@ -29,8 +38,8 @@ export declare function matchRedirect<R extends RedirectRuleLite>(pathname: stri
29
38
  statusCode: number;
30
39
  } | null;
31
40
  /**
32
- * 多語網站的轉址比對(ADR-0010 決策 18):先比帶語系的規則(完整路徑、目標原樣),再比共用規則(無前綴路徑)。
33
- * `scoped` 為 true 時目標已含語系前綴;false 時呼叫端把站內目標接回請求語系的前綴(與既有行為相同)。
41
+ * Redirect matching on multilingual sites: locale-specific rules first (full path, target as is), then shared rules (unprefixed path).
42
+ * When `scoped` is true the target already includes the locale prefix; when false the caller adds the request locale's prefix to in-site targets (the existing behavior).
34
43
  */
35
44
  export declare function matchLocalizedRedirect<R extends RedirectRuleLite>(fullPathname: string, localePathname: string, rules: R[]): {
36
45
  rule: R;
@@ -38,30 +47,30 @@ export declare function matchLocalizedRedirect<R extends RedirectRuleLite>(fullP
38
47
  statusCode: number;
39
48
  scoped: boolean;
40
49
  } | null;
41
- /** strip 結尾斜線(保留根 "/"),供自我轉址比對。 */
50
+ /** Strips the trailing slash (keeping the root "/"), for self-redirect comparison. */
42
51
  export declare function stripTrailingSlash(value: string): string;
43
- /** 精確自我轉址(/foo 與 /foo/ 視為相同)。 */
52
+ /** Exact self-redirect (/foo and /foo/ are the same). */
44
53
  export declare function isExactSelf(source: string, target: string): boolean;
45
54
  /**
46
- * wildcard 來源,且站內相對目標落在來源涵蓋範圍內(例如 "/*" → "/"、"/blog/*" → "/blog/x")。
47
- * 範圍外目標("/blog/*" → "/about")與外部網址不算。
55
+ * A wildcard source whose in-site relative target falls inside what the source covers ("/*" to "/", "/blog/*" to "/blog/x").
56
+ * Targets outside it ("/blog/*" to "/about") and external URLs do not count.
48
57
  */
49
58
  export declare function isScopeLoop(source: string, target: string): boolean;
50
- /** 單條規則是否自我迴圈(精確自我轉址或 wildcard 自我涵蓋)。 */
59
+ /** Whether a single rule loops on itself (an exact self-redirect or a wildcard covering its own target). */
51
60
  export declare function isSelfLoop(source: string, target: string): boolean;
52
61
  /**
53
- * 找出參與跨規則轉址迴圈(例如 /a → /b 且 /b → /a)的規則 key。
62
+ * Finds the keys of rules that take part in a redirect loop across rules (for example /a to /b and /b to /a).
54
63
  *
55
- * 從每條規則的代表路徑出發,重複套用 `matchRedirect` 逐跳解析,以 visited-set 偵測 cycle。
56
- * 單條自我迴圈應由呼叫端以 `isSelfLoop` 先行處理,這裡專注多條互指。
64
+ * Starting from each rule's representative path, it applies `matchRedirect` hop by hop and detects a cycle with a visited set.
65
+ * Single-rule self-loops should be handled first by the caller with `isSelfLoop`; this focuses on rules pointing at each other.
57
66
  *
58
- * 精確化:`maxHops = 規則數 + 1`。在此 functional 結構下,非循環走訪最多經過「規則數」個
59
- * 不同狀態即終止,故 `規則數 + 1` 為精確上限、零誤判;成長型鏈(永不終止)會在超過上限時被判為迴圈。
67
+ * Precision: `maxHops = number of rules + 1`. In this functional structure an acyclic walk ends after visiting at most as many
68
+ * distinct states as there are rules, so `number of rules + 1` is an exact bound with no false positives; a growing chain (never ending) is judged a loop once it exceeds the bound.
60
69
  */
61
70
  export declare function findRedirectLoopKeys<R extends {
62
71
  key: string;
63
72
  sourcePath: string;
64
73
  targetUrl: string;
65
74
  }>(rules: R[]): Set<string>;
66
- /** 是否存在跨規則轉址迴圈。單條自我迴圈請另以 `isSelfLoop` 檢查。 */
75
+ /** Whether a redirect loop across rules exists. Check single-rule self-loops separately with `isSelfLoop`. */
67
76
  export declare function hasRedirectChainLoop(rules: RedirectRuleLite[]): boolean;