@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.
- package/README.md +2 -2
- package/dist/customer-oauth.d.ts +21 -21
- package/dist/customer-oauth.js +12 -12
- package/dist/customer.d.ts +22 -22
- package/dist/customer.js +20 -11
- package/dist/delivery.d.ts +9 -9
- package/dist/delivery.js +6 -6
- package/dist/edge.d.ts +25 -21
- package/dist/edge.js +19 -19
- package/dist/forms.d.ts +13 -13
- package/dist/forms.js +13 -13
- package/dist/generated/delivery.d.ts +35 -7
- package/dist/generated/management.d.ts +111 -26
- package/dist/http.d.ts +13 -13
- package/dist/http.js +8 -8
- package/dist/index.js +2 -2
- package/dist/locales.d.ts +22 -22
- package/dist/locales.js +12 -12
- package/dist/management.d.ts +5 -5
- package/dist/management.js +3 -3
- package/dist/paginate.d.ts +3 -3
- package/dist/paginate.js +3 -3
- package/dist/preview.d.ts +13 -13
- package/dist/preview.js +11 -11
- package/dist/protection.d.ts +18 -18
- package/dist/protection.js +11 -11
- package/dist/revalidate.d.ts +22 -22
- package/dist/revalidate.js +14 -14
- package/dist/seo.d.ts +20 -20
- package/dist/seo.js +20 -20
- package/dist/server-key.d.ts +2 -2
- package/dist/server-key.js +2 -2
- package/dist/shared/api/delivery/cache-tags.d.ts +39 -39
- package/dist/shared/api/delivery/cache-tags.js +34 -34
- package/dist/shared/api/server-key.d.ts +32 -28
- package/dist/shared/api/server-key.js +41 -33
- package/dist/shared/business-registry/attribution.d.ts +5 -5
- package/dist/shared/business-registry/attribution.js +4 -4
- package/dist/shared/business-registry/define.d.ts +1 -1
- package/dist/shared/business-registry/define.js +1 -1
- package/dist/shared/business-registry/formats/eu-vat.js +4 -4
- package/dist/shared/business-registry/formats/hk-br.d.ts +2 -2
- package/dist/shared/business-registry/formats/hk-br.js +4 -4
- package/dist/shared/business-registry/formats/jp-trn.d.ts +3 -3
- package/dist/shared/business-registry/formats/jp-trn.js +4 -4
- package/dist/shared/business-registry/formats/kr-brn.d.ts +2 -2
- package/dist/shared/business-registry/formats/kr-brn.js +3 -3
- package/dist/shared/business-registry/formats/my.d.ts +3 -3
- package/dist/shared/business-registry/formats/my.js +4 -4
- package/dist/shared/business-registry/formats/sg-uen.js +4 -4
- package/dist/shared/business-registry/formats/tw-vat.d.ts +5 -5
- package/dist/shared/business-registry/formats/tw-vat.js +6 -6
- package/dist/shared/business-registry/index.js +1 -1
- package/dist/shared/business-registry/lookup-wire.d.ts +9 -9
- package/dist/shared/business-registry/lookup-wire.js +4 -4
- package/dist/shared/business-registry/normalize.d.ts +3 -3
- package/dist/shared/business-registry/normalize.js +4 -4
- package/dist/shared/business-registry/registry.d.ts +9 -9
- package/dist/shared/business-registry/registry.js +13 -13
- package/dist/shared/business-registry/types.d.ts +20 -20
- package/dist/shared/business-registry/types.js +6 -6
- package/dist/shared/localization/locale-path.d.ts +18 -18
- package/dist/shared/localization/locale-path.js +18 -18
- package/dist/shared/localization/request-locale.d.ts +16 -16
- package/dist/shared/localization/request-locale.js +13 -13
- package/dist/shared/seo/alternates.d.ts +26 -26
- package/dist/shared/seo/alternates.js +18 -18
- package/dist/shared/types/forms-logic.d.ts +28 -28
- package/dist/shared/types/forms-logic.js +27 -27
- package/dist/shared/types/number-input.d.ts +2 -2
- package/dist/shared/types/number-input.js +3 -3
- package/dist/shared/utils/redirect-matching.d.ts +33 -24
- package/dist/shared/utils/redirect-matching.js +73 -40
- package/dist/typed.d.ts +5 -5
- package/dist/typed.js +3 -3
- package/package.json +10 -10
package/dist/revalidate.js
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Kanorio
|
|
2
|
+
* Kanorio webhook signature verification and an on-demand `revalidateTag` handler for Next.js and Astro.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
* - `X-Kanorio-Signature: t=<unix
|
|
6
|
-
* -
|
|
7
|
-
* - `X-Kanorio-Event`
|
|
8
|
-
* -
|
|
9
|
-
* -
|
|
10
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
//
|
|
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
|
-
*
|
|
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
|
-
*
|
|
3
|
-
* - `seoRewrites({ siteUrl, framework })
|
|
4
|
-
* - `fetchDeliveryJsonLd({ siteUrl, path })
|
|
5
|
-
* - `fetchSitemapEntries({ siteUrl })
|
|
6
|
-
* - `listingRobots(site, key)
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
66
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
|
86
|
-
* - `off
|
|
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`
|
|
89
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
3
|
-
* - `seoRewrites({ siteUrl, framework })
|
|
4
|
-
* - `fetchDeliveryJsonLd({ siteUrl, path })
|
|
5
|
-
* - `fetchSitemapEntries({ siteUrl })
|
|
6
|
-
* - `listingRobots(site, key)
|
|
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
|
|
29
|
-
// source
|
|
30
|
-
// Astro
|
|
31
|
-
// `
|
|
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
|
|
63
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
//
|
|
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
|
-
*
|
|
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
|
|
95
|
-
* - `off
|
|
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`
|
|
98
|
-
*
|
|
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
|
-
/**
|
|
121
|
+
/** A page's canonical and hreflang on multilingual sites (`locales.alternates`) */
|
|
122
122
|
alternates: buildAlternates,
|
|
123
123
|
languageSwitcher,
|
|
124
124
|
create: createSeoHelpers,
|
package/dist/server-key.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Server key support shared by every client in this package.
|
|
3
3
|
*
|
|
4
|
-
* A server key (`
|
|
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 (`
|
|
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;
|
package/dist/server-key.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Server key support shared by every client in this package.
|
|
3
3
|
*
|
|
4
|
-
* A server key (`
|
|
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
|
|
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
|
|
2
|
+
* Cache tags of the Content Delivery API (the single source of truth).
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
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
|
-
*
|
|
8
|
-
* -
|
|
9
|
-
* -
|
|
10
|
-
* -
|
|
11
|
-
* -
|
|
12
|
-
* -
|
|
13
|
-
*
|
|
14
|
-
* -
|
|
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
|
-
*
|
|
17
|
-
* `revalidateTag`
|
|
18
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
23
|
+
/** Separator between a tag and its locale: `item:abc@en-US` */
|
|
24
24
|
export declare const CACHE_TAG_LOCALE_SEPARATOR = "@";
|
|
25
|
-
/** SDK
|
|
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
|
-
*
|
|
56
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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`
|
|
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`
|
|
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
|
-
/**
|
|
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`
|
|
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
|
-
/**
|
|
113
|
+
/** Full-site publish: pages, header and footer, redirects and SEO files may all change */
|
|
114
114
|
readonly sitePublished: (siteId: string) => string[];
|
|
115
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
-
//
|
|
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
|
|
3
|
+
* Cache tags of the Content Delivery API (the single source of truth).
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
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
|
-
*
|
|
9
|
-
* -
|
|
10
|
-
* -
|
|
11
|
-
* -
|
|
12
|
-
* -
|
|
13
|
-
* -
|
|
14
|
-
*
|
|
15
|
-
* -
|
|
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
|
-
*
|
|
18
|
-
* `revalidateTag`
|
|
19
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
24
|
+
/** Separator between a tag and its locale: `item:abc@en-US` */
|
|
25
25
|
export const CACHE_TAG_LOCALE_SEPARATOR = "@";
|
|
26
|
-
/** SDK
|
|
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
|
-
*
|
|
75
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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);
|