@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,13 +1,13 @@
1
1
  /**
2
- * Kanorio Webhook 驗章與 Next.js / Astro On-Demand ISR `revalidateTag` 處理器(階段 6)。
2
+ * Kanorio webhook signature verification and an on-demand `revalidateTag` handler for Next.js and Astro.
3
3
  *
4
- * 契約與伺服器端 `lib/notifications/team/adapters/webhook.ts` 及 docs/infrastructure/webhooks/README.md 一致:
5
- * - `X-Kanorio-Signature: t=<unix 秒>,v1=<hex>[,v1=<hex>]`,`v1` 是以端點簽章金鑰對 `${t}.${rawBody}` 計算的 HMAC-SHA256
6
- * - 金鑰輪替並行期內會同時附新舊兩個 `v1=`,任一相符即通過
7
- * - `X-Kanorio-Event` 為事件鍵、`X-Kanorio-Delivery` 為投遞 id(重試與重送間不變,可去重)
8
- * - 使用 Web Crypto API(`crypto.subtle`),於 Node 20+、Cloudflare Workers、Vercel Edge 皆零依賴可用
9
- * - 從 payload 的 `data.cacheTags` 取出標籤、加上命名空間(預設 `kanorio:`,與 `frameworkCacheTags` 同一套)後呼叫 `revalidateTag`;
10
- * 事件只列出真的變了的標籤(單筆內容的事件不帶 `site:<id>`,別的頁不動),不再自動補整站標籤
4
+ * The contract matches the server and the webhook documentation:
5
+ * - `X-Kanorio-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]`, where `v1` is the HMAC-SHA256 of `${t}.${rawBody}` with the endpoint's signing secret
6
+ * - While a secret is being rotated, both the new and the old `v1=` are sent; a match on either passes
7
+ * - `X-Kanorio-Event` is the event key and `X-Kanorio-Delivery` is the delivery id (unchanged across retries and resends, so it can deduplicate)
8
+ * - Uses the Web Crypto API (`crypto.subtle`), with no dependencies on Node 20+, Cloudflare Workers and Vercel Edge
9
+ * - Takes the tags from the payload's `data.cacheTags`, adds the namespace (`kanorio:` by default, the same as `frameworkCacheTags`) and calls `revalidateTag`;
10
+ * an event lists only the tags that really changed (a single record's event does not carry `site:<id>`, so other pages stay cached), and no site-wide tag is added
11
11
  */
12
12
  import { DEFAULT_CACHE_TAG_PREFIX, prefixCacheTags } from "./shared/api/delivery/cache-tags.js";
13
13
  export const WEBHOOK_SIGNATURE_HEADER = "x-kanorio-signature";
@@ -30,7 +30,7 @@ function constantTimeEqual(a, b) {
30
30
  }
31
31
  return diff === 0;
32
32
  }
33
- /** 解析 `t=<unix>,v1=<hex>[,v1=<hex>]`;格式不符回 null */
33
+ /** Parses `t=<unix>,v1=<hex>[,v1=<hex>]`; null when malformed */
34
34
  export function parseWebhookSignatureHeader(header) {
35
35
  if (!header)
36
36
  return null;
@@ -55,14 +55,14 @@ export function parseWebhookSignatureHeader(header) {
55
55
  return null;
56
56
  return { timestamp, signatures };
57
57
  }
58
- /** 計算單一 `v1` 值(hex);多把金鑰請各呼叫一次再以 `t=…,v1=…,v1=…` 組合 */
58
+ /** Computes one `v1` value (hex); for several secrets, call once each and join as `t=...,v1=...,v1=...` */
59
59
  export async function computeWebhookSignature(signingSecret, timestamp, rawBody) {
60
60
  const enc = new TextEncoder();
61
61
  const key = await crypto.subtle.importKey("raw", enc.encode(signingSecret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
62
62
  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(`${timestamp}.${rawBody}`));
63
63
  return bytesToHex(new Uint8Array(sig));
64
64
  }
65
- /** 產生與伺服器相同格式的 `X-Kanorio-Signature` 值(測試或本機模擬投遞用) */
65
+ /** Builds an `X-Kanorio-Signature` value in the server's format (for tests or simulating a delivery locally) */
66
66
  export async function buildWebhookSignatureHeader(signingSecrets, rawBody, timestamp) {
67
67
  const list = typeof signingSecrets === "string" ? [signingSecrets] : signingSecrets;
68
68
  const parts = [];
@@ -82,10 +82,10 @@ export async function verifyWebhookSignature(options) {
82
82
  if (Math.abs(nowSeconds - parsed.timestamp) > tolerance)
83
83
  return false;
84
84
  const expected = await computeWebhookSignature(options.signingSecret, parsed.timestamp, options.rawBody);
85
- // 輪替期內伺服器會附新舊兩個 v1;接收端只持有其中一把,任一相符即通過
85
+ // During a rotation the server sends both the new and the old v1; the receiver holds one of the secrets, and a match on either passes
86
86
  return parsed.signatures.some((sig) => constantTimeEqual(sig, expected));
87
87
  }
88
- /** 事件要清的標籤(原始字串,不含命名空間);事件本身已列出該清的全部標籤 */
88
+ /** The tags an event asks to clear (raw strings, no namespace); the event already lists every tag to clear */
89
89
  export function extractWebhookCacheTags(payload) {
90
90
  const tags = new Set();
91
91
  if (Array.isArray(payload.data?.cacheTags)) {
@@ -97,7 +97,7 @@ export function extractWebhookCacheTags(payload) {
97
97
  return [...tags];
98
98
  }
99
99
  /**
100
- * 建立標準 `POST` Route Handler(直接 export 於 Next.js `app/api/revalidate/route.ts` 或 Astro endpoint)。
100
+ * Creates a standard `POST` route handler (export it from Next.js `app/api/revalidate/route.ts` or an Astro endpoint).
101
101
  */
102
102
  export function createRevalidateHandler(options) {
103
103
  return async function POST(request) {
package/dist/seo.d.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  /**
2
- * Headless SEO/AEO 衍生檔與 JSON-LD 輔助工具(階段 6/PR-4h):
3
- * - `seoRewrites({ siteUrl, framework })`:回傳可直接展開進 `next.config` `rewrites()` 或 `astro.config` 的規則陣列/映射
4
- * - `fetchDeliveryJsonLd({ siteUrl, path })`:抓取指定路徑的 Schema.org JSON-LD `@graph` 與安全轉義後的 `<script>` 字串
5
- * - `fetchSitemapEntries({ siteUrl })`:`sitemap.xml` 的資料版,給自己組 sitemap 的前端合併用
6
- * - `listingRobots(site, key)`:依 `/api/v1/site` 的 `listings` 決定列表頁的 robots 值
2
+ * Helpers for headless SEO and AEO files and JSON-LD:
3
+ * - `seoRewrites({ siteUrl, framework })`: rules to spread into `next.config` `rewrites()`, or a map for `astro.config`
4
+ * - `fetchDeliveryJsonLd({ siteUrl, path })`: fetches a path's Schema.org JSON-LD `@graph` and a safely escaped `<script>` string
5
+ * - `fetchSitemapEntries({ siteUrl })`: `sitemap.xml` as data, for front ends that build their own sitemap and merge it in
6
+ * - `listingRobots(site, key)`: the robots value of a list page, from `listings` in `/api/v1/site`
7
7
  */
8
8
  import type { components as DeliveryComponents } from "./generated/delivery.js";
9
9
  import { buildAlternates, languageSwitcher } from "./locales.js";
@@ -15,7 +15,7 @@ export interface NextSeoRewriteRule {
15
15
  destination: string;
16
16
  }
17
17
  export interface SeoRewritesOptions {
18
- /** 站台系統網址或自訂網域(例如 `https://s-k4m9x2p7q8w3.kanorio.com`) */
18
+ /** The site's system URL or custom domain (for example `https://s-k4m9x2p7q8w3.kanorio.com`) */
19
19
  siteUrl: string;
20
20
  framework: SeoRewriteFramework;
21
21
  }
@@ -30,7 +30,7 @@ export declare function seoRewrites(options: {
30
30
  export declare function seoRewrites(options: SeoRewritesOptions): NextSeoRewriteRule[] | Record<string, string>;
31
31
  export interface DeliveryJsonLdResult {
32
32
  jsonLd: Record<string, unknown>;
33
- /** 已將 `<`、`>`、`&` 轉義為 Unicode escape 的 JSON 字串,可安全放入 `<script type="application/ld+json">` */
33
+ /** A JSON string with `<`, `>` and `&` escaped as Unicode escapes, safe inside `<script type="application/ld+json">` */
34
34
  scriptJson: string;
35
35
  cacheTags: string[];
36
36
  }
@@ -39,16 +39,16 @@ export declare function fetchDeliveryJsonLd(options: {
39
39
  path?: string;
40
40
  fetch?: typeof globalThis.fetch;
41
41
  }): Promise<DeliveryJsonLdResult | null>;
42
- /** 一筆 sitemap 項目(`GET /api/v1/seo/sitemap`) */
42
+ /** One sitemap entry (`GET /api/v1/seo/sitemap`) */
43
43
  export interface SitemapEntry {
44
44
  url: string;
45
- /** 站內路徑,以 `/` 開頭 */
45
+ /** In-site path, starting with `/` */
46
46
  path: string;
47
47
  /** YYYY-MM-DD */
48
48
  lastModified: string;
49
49
  changeFrequency: string;
50
50
  priority: number;
51
- /** 這個網址是什麼:page、blog-post、product、collection-item… */
51
+ /** What the URL is: page, blog-post, product, collection-item, ... */
52
52
  kind: string;
53
53
  locale?: string;
54
54
  alternates?: Array<{
@@ -62,31 +62,31 @@ export interface SitemapEntriesResult {
62
62
  cacheTags: string[];
63
63
  }
64
64
  /**
65
- * Kanorio 管的網址清單(與 `/api/v1/seo/sitemap.xml` 同一份,資料格式)。
66
- * 只有部分內容在 Kanorio 的站,在自己的 sitemap 產生器把這份清單和自己的網址合在一起:
65
+ * The URLs Kanorio manages (the same list as `/api/v1/seo/sitemap.xml`, as data).
66
+ * A site with only part of its content on Kanorio merges this list with its own URLs in its sitemap generator:
67
67
  *
68
68
  * ```ts
69
- * // app/sitemap.ts(Next.js)
69
+ * // app/sitemap.ts (Next.js)
70
70
  * export default async function sitemap() {
71
71
  * const kanorio = await fetchSitemapEntries({ siteUrl });
72
72
  * return [...ownUrls, ...(kanorio?.urls ?? []).map((u) => ({ url: u.url, lastModified: u.lastModified }))];
73
73
  * }
74
74
  * ```
75
75
  *
76
- * 回源失敗回 null,由呼叫端決定要不要只輸出自己的網址。
76
+ * Returns null when the origin fetch fails, so the caller can decide whether to output only its own URLs.
77
77
  */
78
78
  export declare function fetchSitemapEntries(options: {
79
79
  siteUrl: string;
80
80
  fetch?: typeof globalThis.fetch;
81
81
  }): Promise<SitemapEntriesResult | null>;
82
82
  /**
83
- * 列表頁(部落格首頁、文章分類頁、商店首頁…)該輸出的 robots 值,與 Kanorio 的 sitemap/IndexNow 同一套判斷:
83
+ * The robots value a list page (blog index, post category page, shop index, ...) should output, by the same rules as Kanorio's sitemap and IndexNow:
84
84
  * - `live` → `"index, follow"`
85
- * - `empty`(還沒有內容)→ `"noindex, follow"`,頁面照常渲染
86
- * - `off`(站主隱藏,或沒有在 externalListings 宣告)→ `null`:這頁不該對外提供,請回 404
85
+ * - `empty` (no content yet): `"noindex, follow"`, and the page renders as usual
86
+ * - `off` (hidden by the owner, or not declared in externalListings): `null`; the page should not be served, so answer 404
87
87
  *
88
- * `site` 是 `GET /api/v1/site` 的回應。缺 `listings` 只會發生在升級前就快取的舊回應;SDK 端沒有內容
89
- * 旗標可推導,退回 `live` 以維持升級前的行為,不是正式語意。
88
+ * `site` is the `GET /api/v1/site` response. `listings` is missing only in responses cached before the upgrade; the SDK has no content
89
+ * flags to derive it from, so it falls back to `live` to keep the earlier behavior. That fallback is not a defined meaning.
90
90
  */
91
91
  export declare function listingRobots(site: {
92
92
  listings?: Partial<Record<ListingKey, ListingState>> | null;
@@ -113,7 +113,7 @@ export declare const seo: {
113
113
  readonly jsonLd: typeof fetchDeliveryJsonLd;
114
114
  readonly sitemapEntries: typeof fetchSitemapEntries;
115
115
  readonly listingRobots: typeof listingRobots;
116
- /** 多語網站一頁的 canonical 與 hreflang(`locales.alternates`) */
116
+ /** A page's canonical and hreflang on multilingual sites (`locales.alternates`) */
117
117
  readonly alternates: typeof buildAlternates;
118
118
  readonly languageSwitcher: typeof languageSwitcher;
119
119
  readonly create: typeof createSeoHelpers;
package/dist/seo.js CHANGED
@@ -1,9 +1,9 @@
1
1
  /**
2
- * Headless SEO/AEO 衍生檔與 JSON-LD 輔助工具(階段 6/PR-4h):
3
- * - `seoRewrites({ siteUrl, framework })`:回傳可直接展開進 `next.config` `rewrites()` 或 `astro.config` 的規則陣列/映射
4
- * - `fetchDeliveryJsonLd({ siteUrl, path })`:抓取指定路徑的 Schema.org JSON-LD `@graph` 與安全轉義後的 `<script>` 字串
5
- * - `fetchSitemapEntries({ siteUrl })`:`sitemap.xml` 的資料版,給自己組 sitemap 的前端合併用
6
- * - `listingRobots(site, key)`:依 `/api/v1/site` 的 `listings` 決定列表頁的 robots 值
2
+ * Helpers for headless SEO and AEO files and JSON-LD:
3
+ * - `seoRewrites({ siteUrl, framework })`: rules to spread into `next.config` `rewrites()`, or a map for `astro.config`
4
+ * - `fetchDeliveryJsonLd({ siteUrl, path })`: fetches a path's Schema.org JSON-LD `@graph` and a safely escaped `<script>` string
5
+ * - `fetchSitemapEntries({ siteUrl })`: `sitemap.xml` as data, for front ends that build their own sitemap and merge it in
6
+ * - `listingRobots(site, key)`: the robots value of a list page, from `listings` in `/api/v1/site`
7
7
  */
8
8
  import { deliveryBaseUrl, parseDeliveryCacheTags } from "./delivery.js";
9
9
  import { buildAlternates, languageSwitcher } from "./locales.js";
@@ -25,10 +25,10 @@ export function seoRewrites(options) {
25
25
  if (options.framework === "astro") {
26
26
  return Object.fromEntries(rules.map((r) => [r.source, r.destination]));
27
27
  }
28
- // IndexNow 要求金鑰驗證檔可從 `https://{host}/{key}.txt` 取得;用 Next.js 的動態路徑
29
- // source 一次涵蓋所有可能的金鑰值,不需要事先知道金鑰內容(內容由伺服器端比對、回應)。
30
- // Astro 的靜態 source→destination 映射表達不了動態路徑,改以 `@kanorio/sdk/edge` 的
31
- // `createKanorioMiddleware`(`features.indexNow`,預設啟用)在邊緣直接回應。
28
+ // IndexNow requires the key verification file at `https://{host}/{key}.txt`; a dynamic Next.js path
29
+ // source covers every possible key value, without knowing the key in advance (the server matches it and answers).
30
+ // Astro's static source-to-destination map cannot express a dynamic path; there, `createKanorioMiddleware`
31
+ // from `@kanorio/sdk/edge` (`features.indexNow`, on by default) answers at the edge.
32
32
  rules.push({
33
33
  source: "/:key([a-f0-9]{32}).txt",
34
34
  destination: `${base}/seo/indexnow-key.txt`,
@@ -59,18 +59,18 @@ export async function fetchDeliveryJsonLd(options) {
59
59
  };
60
60
  }
61
61
  /**
62
- * Kanorio 管的網址清單(與 `/api/v1/seo/sitemap.xml` 同一份,資料格式)。
63
- * 只有部分內容在 Kanorio 的站,在自己的 sitemap 產生器把這份清單和自己的網址合在一起:
62
+ * The URLs Kanorio manages (the same list as `/api/v1/seo/sitemap.xml`, as data).
63
+ * A site with only part of its content on Kanorio merges this list with its own URLs in its sitemap generator:
64
64
  *
65
65
  * ```ts
66
- * // app/sitemap.ts(Next.js)
66
+ * // app/sitemap.ts (Next.js)
67
67
  * export default async function sitemap() {
68
68
  * const kanorio = await fetchSitemapEntries({ siteUrl });
69
69
  * return [...ownUrls, ...(kanorio?.urls ?? []).map((u) => ({ url: u.url, lastModified: u.lastModified }))];
70
70
  * }
71
71
  * ```
72
72
  *
73
- * 回源失敗回 null,由呼叫端決定要不要只輸出自己的網址。
73
+ * Returns null when the origin fetch fails, so the caller can decide whether to output only its own URLs.
74
74
  */
75
75
  export async function fetchSitemapEntries(options) {
76
76
  const fetchImpl = options.fetch ?? globalThis.fetch;
@@ -84,18 +84,18 @@ export async function fetchSitemapEntries(options) {
84
84
  return { siteUrl: body.siteUrl, urls: body.urls, cacheTags: parseDeliveryCacheTags(res.headers) };
85
85
  }
86
86
  catch {
87
- // 連不上、逾時或回的不是 JSON:呼叫端的 sitemap 仍要能輸出自己的網址
87
+ // Unreachable, timed out or not JSON: the caller's sitemap must still be able to output its own URLs
88
88
  return null;
89
89
  }
90
90
  }
91
91
  /**
92
- * 列表頁(部落格首頁、文章分類頁、商店首頁…)該輸出的 robots 值,與 Kanorio 的 sitemap/IndexNow 同一套判斷:
92
+ * The robots value a list page (blog index, post category page, shop index, ...) should output, by the same rules as Kanorio's sitemap and IndexNow:
93
93
  * - `live` → `"index, follow"`
94
- * - `empty`(還沒有內容)→ `"noindex, follow"`,頁面照常渲染
95
- * - `off`(站主隱藏,或沒有在 externalListings 宣告)→ `null`:這頁不該對外提供,請回 404
94
+ * - `empty` (no content yet): `"noindex, follow"`, and the page renders as usual
95
+ * - `off` (hidden by the owner, or not declared in externalListings): `null`; the page should not be served, so answer 404
96
96
  *
97
- * `site` 是 `GET /api/v1/site` 的回應。缺 `listings` 只會發生在升級前就快取的舊回應;SDK 端沒有內容
98
- * 旗標可推導,退回 `live` 以維持升級前的行為,不是正式語意。
97
+ * `site` is the `GET /api/v1/site` response. `listings` is missing only in responses cached before the upgrade; the SDK has no content
98
+ * flags to derive it from, so it falls back to `live` to keep the earlier behavior. That fallback is not a defined meaning.
99
99
  */
100
100
  export function listingRobots(site, key) {
101
101
  const state = site.listings?.[key] ?? "live";
@@ -118,7 +118,7 @@ export const seo = {
118
118
  jsonLd: fetchDeliveryJsonLd,
119
119
  sitemapEntries: fetchSitemapEntries,
120
120
  listingRobots,
121
- /** 多語網站一頁的 canonical 與 hreflang(`locales.alternates`) */
121
+ /** A page's canonical and hreflang on multilingual sites (`locales.alternates`) */
122
122
  alternates: buildAlternates,
123
123
  languageSwitcher,
124
124
  create: createSeoHelpers,
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Server key support shared by every client in this package.
3
3
  *
4
- * A server key (`knr_sa_…`, created under Site settings > Developer with the purpose "Website server") lets
4
+ * A server key (`knr_sk_…`, created under Site settings > Developer with the purpose "Website server") lets
5
5
  * **your server** call the visitor-facing write endpoints on behalf of a visitor: submit a form, exchange a
6
6
  * customer sign-in code, report an AI crawler hit. Without it, Kanorio's edge treats server-to-server writes
7
7
  * as automated traffic and answers with a challenge page.
@@ -17,7 +17,7 @@ export { SERVER_KEY_HEADER, SERVER_KEY_VISITOR_IP_HEADER };
17
17
  export type VisitorIpSource = string | null | undefined | (() => string | null | undefined | Promise<string | null | undefined>);
18
18
  export interface ServerKeyOptions {
19
19
  /**
20
- * Server key (`knr_sa_…`). Server-side only: read it from an environment variable such as
20
+ * Server key (`knr_sk_…`). Server-side only: read it from an environment variable such as
21
21
  * `KANORIO_SERVER_KEY`. Required when your server writes on behalf of a visitor.
22
22
  */
23
23
  serverKey?: string;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Server key support shared by every client in this package.
3
3
  *
4
- * A server key (`knr_sa_…`, created under Site settings > Developer with the purpose "Website server") lets
4
+ * A server key (`knr_sk_…`, created under Site settings > Developer with the purpose "Website server") lets
5
5
  * **your server** call the visitor-facing write endpoints on behalf of a visitor: submit a form, exchange a
6
6
  * customer sign-in code, report an AI crawler hit. Without it, Kanorio's edge treats server-to-server writes
7
7
  * as automated traffic and answers with a challenge page.
@@ -98,6 +98,6 @@ export function edgeChallengeMessage(hasServerKey) {
98
98
  return "Kanorio's edge challenged this request. In a browser this usually clears after the visitor passes the check; retry the request.";
99
99
  }
100
100
  return hasServerKey
101
- ? "Kanorio's edge challenged this server-side request even though a server key was sent. Check that the key is a server key (starts with knr_sa_, purpose \"Website server\") and that it is sent to the site's own hostname."
101
+ ? "Kanorio's edge challenged this server-side request even though a server key was sent. Check that the key is a server key (starts with knr_sk_, purpose \"Website server\") and that it is sent to the site's own hostname."
102
102
  : "Kanorio's edge challenged this server-side request. Server-side writes need a server key: create one under Site settings > Developer (purpose \"Website server\"), store it as KANORIO_SERVER_KEY, and pass `serverKey` to the client. Do not paste the key into chat or commit it.";
103
103
  }
@@ -1,30 +1,30 @@
1
1
  /**
2
- * Content Delivery API 的快取標籤(SSOT;ADR-0010 決策 13 修訂二)。
2
+ * Cache tags of the Content Delivery API (the single source of truth).
3
3
  *
4
- * 標籤記的是「這個回應用到了哪些內容」,事件送的是「這次哪些內容變了」;兩邊由這一份函式產生,
5
- * `apps/main/__tests__/shared/api/delivery-cache-tags.test.ts` 的契約矩陣逐一檢查:該清的一定清到、不該清的一定碰不到。
4
+ * 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,
5
+ * and a contract matrix in Kanorio's tests checks every pairing: what should be cleared is cleared, and what should not is never touched.
6
6
  *
7
- * 分層(一個回應同時帶寬窄兩種標籤,與 CDN surrogate key 的慣例相同):
8
- * - 整站 `site:{id}`:所有回應都帶;只有整站發布與語系集合變動(上線、下線、移除、改前綴、換主語系)的事件送它
9
- * - 語系 `locale:{code}`:次語系的所有回應都帶;整站翻譯完成、網站設定譯文上線送它
10
- * - 內容 `page:{id}`、`item:{id}`、`product:{id}`、`form:{id}`:所有語系的回應都帶;主語系內容上線的事件送它(未翻譯的欄位沿用主語系,所以所有語系一起清)
11
- * - 內容+語系 `page:{id}@en-US`:只有該語系的回應帶;該語系的譯文上線時送它,其他語系不動
12
- * - 列表 `pages`、`collection:{key}`、`products`(+語系):只有列表回應帶,不逐項帶(事件本來就會一起送列表標籤;Next.js 一筆快取最多 128 個標籤);
13
- * 單筆回應不帶列表標籤,別的項目上線才不會清到它。`collection:{key}:items` 是該集合所有單筆回應(欄位結構變了要一起換)
14
- * - 衍生 `search`、`seo`、`redirects`:搜尋、SEO 衍生檔、轉址表;會改變它們的內容事件一起送
7
+ * Layers (one response carries both broad and narrow tags, like CDN surrogate keys):
8
+ * - 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)
9
+ * - Locale `locale:{code}`: on every response of a secondary locale; sent when a full-site translation finishes or translated site settings go live
10
+ * - 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)
11
+ * - 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
12
+ * - 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);
13
+ * 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)
14
+ * - Derived `search`, `seo`, `redirects`: search, SEO files and the redirect table; sent along with content events that change them
15
15
  *
16
- * 標籤用語系碼不用網址前綴(前綴站主可以改);語系以 `@` 接在後面,與 `type:id` 的冒號分得開。
17
- * `revalidateTag` 逐字比對、沒有萬用字元,所以事件必須列出具體標籤。純函式、無 server-only,main、邊緣 Worker 與 SDK 共用
18
- * (SDK 的副本 `packages/sdk/src/cache-tags.ts` 由 `pnpm --filter @kanorio/sdk gen` 複製,契約測試鎖兩份相同)。
16
+ * 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`.
17
+ * `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
18
+ * (the SDK's copy is made by `pnpm --filter @kanorio/sdk gen`, and a contract test keeps the two identical).
19
19
  */
20
20
  export declare const DELIVERY_CACHE_TAGS_HEADER = "x-kanorio-cache-tags";
21
- /** 一個回應最多幾個標籤:Next.js 一筆快取上限 128,留餘裕給外部前端自己的標籤 */
21
+ /** Maximum tags per response: Next.js caps a cache entry at 128, leaving room for the external front end's own tags */
22
22
  export declare const DELIVERY_CACHE_TAG_LIMIT = 100;
23
- /** 語系接在標籤後面的分隔符:`item:abc@en-US` */
23
+ /** Separator between a tag and its locale: `item:abc@en-US` */
24
24
  export declare const CACHE_TAG_LOCALE_SEPARATOR = "@";
25
- /** SDK 交給框架(Next.js `revalidateTag`、`next.tags`)時加的命名空間,避免與網站自己的 `pages`、`seo` 這類標籤撞名 */
25
+ /** 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` */
26
26
  export declare const DEFAULT_CACHE_TAG_PREFIX = "kanorio:";
27
- /** 標籤字彙;只在這裡拼字串 */
27
+ /** The tag vocabulary; strings are only assembled here */
28
28
  export declare const cacheTag: {
29
29
  readonly site: (siteId: string) => string;
30
30
  readonly locale: (locale: string) => string;
@@ -35,7 +35,7 @@ export declare const cacheTag: {
35
35
  readonly footer: () => string;
36
36
  readonly collections: () => string;
37
37
  readonly collection: (key: string) => string;
38
- /** 該集合所有單筆回應:欄位結構變更、整批超過上限時用 */
38
+ /** Every single-item response of the collection: used when the field structure changes or a batch exceeds the limit */
39
39
  readonly collectionItems: (key: string) => string;
40
40
  readonly item: (itemId: string) => string;
41
41
  readonly products: () => string;
@@ -52,32 +52,32 @@ export declare function isLocaleCacheTag(tag: string): boolean;
52
52
  /** `item:abc` → `item:abc@en-US` */
53
53
  export declare function localizeCacheTag(tag: string, locale: string): string;
54
54
  /**
55
- * 回應的語系維度:主語系(`locale` 為 null)原樣;次語系在每個內容與列表標籤後面接語系(`site:` 不接),再加 `locale:{code}`。
56
- * 邊緣以請求正規化後的語系碼呼叫(省略與指定主語系都是 null),main 只需要說明內容依賴。
55
+ * 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}`.
56
+ * The edge calls this with the request's normalized locale code (omitted and explicitly primary are both null); the server only declares content dependencies.
57
57
  */
58
58
  export declare function localizeCacheTags(tags: readonly string[], locale: string | null | undefined): string[];
59
- /** 超過上限時先丟單筆內容的標籤(列表層的標籤留著,事件本來就會送列表標籤),仍超過就只留前 `limit` 個 */
59
+ /** 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 */
60
60
  export declare function capCacheTags(tags: readonly string[], limit?: number): string[];
61
- /** `X-Kanorio-Cache-Tags` 以空白分隔 */
61
+ /** `X-Kanorio-Cache-Tags` is space-separated */
62
62
  export declare function parseCacheTagsHeader(raw: string | null | undefined): string[];
63
63
  export declare function formatCacheTagsHeader(tags: readonly string[]): string;
64
- /** 交給框架前加命名空間;`prefix` 為空字串時原樣 */
64
+ /** Adds the namespace before handing tags to a framework; an empty `prefix` leaves them as is */
65
65
  export declare function prefixCacheTags(tags: readonly string[], prefix?: string): string[];
66
66
  export interface PageResponseDeps {
67
67
  pageId: string;
68
- /** 麵包屑裡的祖先頁(標題跟著祖先頁變) */
68
+ /** Ancestor pages in the breadcrumb (titles follow the ancestors) */
69
69
  ancestorIds?: readonly string[];
70
- /** 頁面指派的頁首(`primary` 或自訂 key);頁面回應帶頁首資料時給 */
70
+ /** The header assigned to the page (`primary` or a custom key); given when the page response includes header data */
71
71
  headerKey?: string | null;
72
- /** 頁面回應帶頁尾資料時給 */
72
+ /** Given when the page response includes footer data */
73
73
  withFooter?: boolean;
74
74
  }
75
75
  export interface ItemsResponseDeps {
76
- /** `expand` 展開的參照所屬的集合 key(作者、分類…):那些集合的項目改了,列表也要換 */
76
+ /** Collection keys of references expanded with `expand` (authors, categories, ...): when items in those collections change, the list must change too */
77
77
  expandedCollectionKeys?: readonly string[];
78
78
  }
79
79
  export interface ItemResponseDeps extends ItemsResponseDeps {
80
- /** `expand` 展開的參照項目 id */
80
+ /** Ids of the reference items expanded with `expand` */
81
81
  expandedItemIds?: readonly string[];
82
82
  }
83
83
  export declare const responseCacheTags: {
@@ -100,19 +100,19 @@ export declare const responseCacheTags: {
100
100
  readonly redirects: (siteId: string) => string[];
101
101
  readonly reviews: (siteId: string, productId: string | null) => string[];
102
102
  };
103
- /** 可翻譯的紀錄型別(與 `packages/shared/localization/translatable-fields.ts` 同一組字串;這裡不 import,SDK 的副本才能獨立) */
103
+ /** Translatable record types (the same strings as Kanorio's translatable-fields registry; not imported here, so the SDK's copy stands alone) */
104
104
  export type TranslationCacheScope = "page" | "global_sections" | "site_settings" | "store_settings" | "post" | "post_category" | "post_tag" | "author" | "product" | "product_option" | "pricing_tier" | "product_category" | "deliverable" | "deliverable_unit" | "form" | "top_bar_banner" | "modal_announcement" | "floating_widget" | "collection_item";
105
105
  export interface TranslationEventInput {
106
106
  entityType: TranslationCacheScope;
107
107
  entityId: string;
108
108
  locale: string;
109
- /** `collection_item` 所屬的集合 key(呼叫端查好帶進來) */
109
+ /** The collection key a `collection_item` belongs to (looked up by the caller) */
110
110
  collectionKey?: string | null;
111
111
  }
112
112
  export declare const eventCacheTags: {
113
- /** 整站發布:頁面、頁首頁尾、轉址、SEO 衍生檔都可能變 */
113
+ /** Full-site publish: pages, header and footer, redirects and SEO files may all change */
114
114
  readonly sitePublished: (siteId: string) => string[];
115
- /** 單頁上線、更新、下線、刪除:不送 `site:`,別的頁不動;改網址另送 `redirects` */
115
+ /** A single page going live, updated, taken offline or deleted: `site:` is not sent, so other pages stay; a changed URL also sends `redirects` */
116
116
  readonly pageChanged: (input: {
117
117
  pageId: string;
118
118
  renamed?: boolean;
@@ -121,22 +121,22 @@ export declare const eventCacheTags: {
121
121
  collectionKey: string;
122
122
  itemId: string;
123
123
  }) => string[];
124
- /** 批次:項目標籤放得下才逐一列;放不下就改清該集合所有單筆(列表標籤一定在) */
124
+ /** 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) */
125
125
  readonly itemsBulkChanged: (input: {
126
126
  collectionKey: string;
127
127
  itemIds: readonly string[];
128
128
  }) => string[];
129
- /** 欄位結構變了:集合清單、列表與該集合所有單筆(投影的欄位變了) */
129
+ /** The field structure changed: the collection list, the item list and every single-item response of the collection (projected fields changed) */
130
130
  readonly schemaChanged: (input: {
131
131
  collectionKey: string;
132
132
  }) => string[];
133
- /** 語系集合變了(上線、下線、移除、改前綴、順序、換主語系):語言切換與 hreflang 在每一頁都有 */
133
+ /** The locale set changed (enabled, disabled, removed, prefix, order, primary): the language switcher and hreflang are on every page */
134
134
  readonly localeChanged: (siteId: string) => string[];
135
- /** 整站翻譯完成:該語系所有回應 */
135
+ /** A full-site translation finished: every response in that locale */
136
136
  readonly translationJobCompleted: (locale: string) => string[];
137
137
  /**
138
- * 一筆紀錄在一個語系的譯文上線或刪除:只送帶語系的標籤,其他語系與主語系的快取不動。
139
- * 網站設定與站上公告是整個語系的外框 → `locale:{code}`;商品的規格、分類、課程大綱沒有單一商品 id → `products@{code}`。
138
+ * 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.
139
+ * 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}`.
140
140
  */
141
141
  readonly translationChanged: (input: TranslationEventInput) => string[];
142
142
  };
@@ -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,15 @@ 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
+ /** The locale set changed (enabled, disabled, removed, prefix, order, primary): the language switcher and hreflang are on every page */
164
164
  localeChanged: (siteId) => [cacheTag.site(siteId)],
165
- /** 整站翻譯完成:該語系所有回應 */
165
+ /** A full-site translation finished: every response in that locale */
166
166
  translationJobCompleted: (locale) => [cacheTag.locale(locale)],
167
167
  /**
168
- * 一筆紀錄在一個語系的譯文上線或刪除:只送帶語系的標籤,其他語系與主語系的快取不動。
169
- * 網站設定與站上公告是整個語系的外框 → `locale:{code}`;商品的規格、分類、課程大綱沒有單一商品 id → `products@{code}`。
168
+ * 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.
169
+ * 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
170
  */
171
171
  translationChanged: (input) => {
172
172
  const l = (tag) => localizeCacheTag(tag, input.locale);