@kanorio/sdk 1.0.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +41 -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 +36 -20
- package/dist/forms.d.ts +33 -14
- package/dist/forms.js +20 -14
- package/dist/generated/delivery.d.ts +564 -13
- package/dist/generated/management.d.ts +790 -81
- package/dist/http.d.ts +13 -13
- package/dist/http.js +8 -8
- package/dist/image.d.ts +77 -0
- package/dist/image.js +78 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +4 -3
- 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/next.d.ts +66 -0
- package/dist/next.js +58 -0
- 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 +137 -21
- package/dist/seo.js +113 -21
- package/dist/server-key.d.ts +2 -2
- package/dist/server-key.js +2 -2
- package/dist/shared/api/delivery/cache-tags.d.ts +41 -39
- package/dist/shared/api/delivery/cache-tags.js +36 -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 +15 -10
package/dist/seo.d.ts
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
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
|
+
* - `seoMetadata(input, options)`: the `<head>` values of a post, a category, tag or author page, or a page, by the rules the hosted site uses
|
|
8
|
+
* - `shareImageOf(input)`: the image for `og:image`, already resolved by Kanorio
|
|
7
9
|
*/
|
|
8
10
|
import type { components as DeliveryComponents } from "./generated/delivery.js";
|
|
9
|
-
import { buildAlternates, languageSwitcher } from "./locales.js";
|
|
11
|
+
import { buildAlternates, languageSwitcher, type SiteLocaleMeta } from "./locales.js";
|
|
10
12
|
export type ListingState = DeliveryComponents["schemas"]["ListingState"];
|
|
11
13
|
export type ListingKey = keyof NonNullable<DeliveryComponents["schemas"]["SiteMeta"]["listings"]>;
|
|
12
14
|
export type SeoRewriteFramework = "next" | "astro";
|
|
@@ -15,7 +17,7 @@ export interface NextSeoRewriteRule {
|
|
|
15
17
|
destination: string;
|
|
16
18
|
}
|
|
17
19
|
export interface SeoRewritesOptions {
|
|
18
|
-
/**
|
|
20
|
+
/** The site's system URL or custom domain (for example `https://s-k4m9x2p7q8w3.kanorio.com`) */
|
|
19
21
|
siteUrl: string;
|
|
20
22
|
framework: SeoRewriteFramework;
|
|
21
23
|
}
|
|
@@ -30,7 +32,7 @@ export declare function seoRewrites(options: {
|
|
|
30
32
|
export declare function seoRewrites(options: SeoRewritesOptions): NextSeoRewriteRule[] | Record<string, string>;
|
|
31
33
|
export interface DeliveryJsonLdResult {
|
|
32
34
|
jsonLd: Record<string, unknown>;
|
|
33
|
-
/**
|
|
35
|
+
/** A JSON string with `<`, `>` and `&` escaped as Unicode escapes, safe inside `<script type="application/ld+json">` */
|
|
34
36
|
scriptJson: string;
|
|
35
37
|
cacheTags: string[];
|
|
36
38
|
}
|
|
@@ -39,16 +41,16 @@ export declare function fetchDeliveryJsonLd(options: {
|
|
|
39
41
|
path?: string;
|
|
40
42
|
fetch?: typeof globalThis.fetch;
|
|
41
43
|
}): Promise<DeliveryJsonLdResult | null>;
|
|
42
|
-
/**
|
|
44
|
+
/** One sitemap entry (`GET /api/v1/seo/sitemap`) */
|
|
43
45
|
export interface SitemapEntry {
|
|
44
46
|
url: string;
|
|
45
|
-
/**
|
|
47
|
+
/** In-site path, starting with `/` */
|
|
46
48
|
path: string;
|
|
47
49
|
/** YYYY-MM-DD */
|
|
48
50
|
lastModified: string;
|
|
49
51
|
changeFrequency: string;
|
|
50
52
|
priority: number;
|
|
51
|
-
/**
|
|
53
|
+
/** What the URL is: page, blog-post, product, collection-item, ... */
|
|
52
54
|
kind: string;
|
|
53
55
|
locale?: string;
|
|
54
56
|
alternates?: Array<{
|
|
@@ -62,35 +64,144 @@ export interface SitemapEntriesResult {
|
|
|
62
64
|
cacheTags: string[];
|
|
63
65
|
}
|
|
64
66
|
/**
|
|
65
|
-
* Kanorio
|
|
66
|
-
*
|
|
67
|
+
* The URLs Kanorio manages (the same list as `/api/v1/seo/sitemap.xml`, as data).
|
|
68
|
+
* A site with only part of its content on Kanorio merges this list with its own URLs in its sitemap generator:
|
|
67
69
|
*
|
|
68
70
|
* ```ts
|
|
69
|
-
* // app/sitemap.ts
|
|
71
|
+
* // app/sitemap.ts (Next.js)
|
|
70
72
|
* export default async function sitemap() {
|
|
71
73
|
* const kanorio = await fetchSitemapEntries({ siteUrl });
|
|
72
74
|
* return [...ownUrls, ...(kanorio?.urls ?? []).map((u) => ({ url: u.url, lastModified: u.lastModified }))];
|
|
73
75
|
* }
|
|
74
76
|
* ```
|
|
75
77
|
*
|
|
76
|
-
*
|
|
78
|
+
* Returns null when the origin fetch fails, so the caller can decide whether to output only its own URLs.
|
|
77
79
|
*/
|
|
78
80
|
export declare function fetchSitemapEntries(options: {
|
|
79
81
|
siteUrl: string;
|
|
80
82
|
fetch?: typeof globalThis.fetch;
|
|
81
83
|
}): Promise<SitemapEntriesResult | null>;
|
|
82
84
|
/**
|
|
83
|
-
*
|
|
85
|
+
* 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
86
|
* - `live` → `"index, follow"`
|
|
85
|
-
* - `empty
|
|
86
|
-
* - `off
|
|
87
|
+
* - `empty` (no content yet): `"noindex, follow"`, and the page renders as usual
|
|
88
|
+
* - `off` (hidden by the owner, or not declared in externalListings): `null`; the page should not be served, so answer 404
|
|
87
89
|
*
|
|
88
|
-
* `site`
|
|
89
|
-
*
|
|
90
|
+
* `site` is the `GET /api/v1/site` response. `listings` is missing only in responses cached before the upgrade; the SDK has no content
|
|
91
|
+
* flags to derive it from, so it falls back to `live` to keep the earlier behavior. That fallback is not a defined meaning.
|
|
90
92
|
*/
|
|
91
93
|
export declare function listingRobots(site: {
|
|
92
94
|
listings?: Partial<Record<ListingKey, ListingState>> | null;
|
|
93
95
|
}, key: ListingKey): "index, follow" | "noindex, follow" | null;
|
|
96
|
+
/** The SEO fields of a blog post, category, tag or author (`fieldData.seo` of a collection item) */
|
|
97
|
+
export interface ItemSeoFields {
|
|
98
|
+
title?: string | null;
|
|
99
|
+
description?: string | null;
|
|
100
|
+
keywords?: readonly string[] | null;
|
|
101
|
+
ogTitle?: string | null;
|
|
102
|
+
ogDescription?: string | null;
|
|
103
|
+
ogImageAlt?: string | null;
|
|
104
|
+
canonical?: string | null;
|
|
105
|
+
robotsIndex?: string | null;
|
|
106
|
+
robotsFollow?: string | null;
|
|
107
|
+
twitterCard?: string | null;
|
|
108
|
+
}
|
|
109
|
+
/** The SEO fields of a page (`page.seo` of `GET /pages/{slug}`). `ogImage` is already the URL to use: the chosen share image, cropped, or the generated title card */
|
|
110
|
+
export interface PageSeoFields {
|
|
111
|
+
seoTitle?: string | null;
|
|
112
|
+
seoDescription?: string | null;
|
|
113
|
+
seoKeywords?: readonly string[] | null;
|
|
114
|
+
ogTitle?: string | null;
|
|
115
|
+
ogDescription?: string | null;
|
|
116
|
+
ogImage?: string | null;
|
|
117
|
+
ogImageAlt?: string | null;
|
|
118
|
+
canonicalUrl?: string | null;
|
|
119
|
+
robotsIndex?: string | null;
|
|
120
|
+
robotsFollow?: string | null;
|
|
121
|
+
twitterCard?: string | null;
|
|
122
|
+
}
|
|
123
|
+
interface LocalizedResponseFields {
|
|
124
|
+
/** Path of the page on the site, in the locale of the response */
|
|
125
|
+
path?: string | null;
|
|
126
|
+
resolvedLocale?: string | null;
|
|
127
|
+
availableLocales?: readonly string[] | null;
|
|
128
|
+
localePaths?: Readonly<Record<string, string>> | null;
|
|
129
|
+
}
|
|
130
|
+
/** A collection item from the Delivery API that has a page of its own: a blog post, a category, a tag or an author */
|
|
131
|
+
export interface SeoItemInput extends LocalizedResponseFields {
|
|
132
|
+
fieldData: {
|
|
133
|
+
title?: unknown;
|
|
134
|
+
name?: unknown;
|
|
135
|
+
excerpt?: unknown;
|
|
136
|
+
seo?: ItemSeoFields | null;
|
|
137
|
+
share_image?: {
|
|
138
|
+
url: string;
|
|
139
|
+
alt?: string | null;
|
|
140
|
+
} | null;
|
|
141
|
+
[key: string]: unknown;
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
/** A page from `GET /pages/{slug}` */
|
|
145
|
+
export interface SeoPageInput extends LocalizedResponseFields {
|
|
146
|
+
title?: string | null;
|
|
147
|
+
seo?: PageSeoFields | null;
|
|
148
|
+
}
|
|
149
|
+
export type SeoInput = SeoItemInput | SeoPageInput;
|
|
150
|
+
export interface SeoMetadataOptions {
|
|
151
|
+
/** Your front end's public URL, without a trailing slash (`https://www.example.com`). Without it `canonical` is a path and there is no hreflang */
|
|
152
|
+
siteUrl?: string;
|
|
153
|
+
/** The `GET /api/v1/site` response. Needed on multilingual sites for hreflang and the canonical of a translated page */
|
|
154
|
+
site?: SiteLocaleMeta | null;
|
|
155
|
+
/** The locale in the URL of this request (`locale` from `resolveRequestLocale`); defaults to the locale the content was served in */
|
|
156
|
+
requestLocale?: string | null;
|
|
157
|
+
/**
|
|
158
|
+
* The page's path in the primary locale's space (no locale prefix), when the response does not carry one:
|
|
159
|
+
* an item of a custom collection without `pathTemplate`, or a page you route yourself
|
|
160
|
+
*/
|
|
161
|
+
path?: string;
|
|
162
|
+
}
|
|
163
|
+
export interface ShareImage {
|
|
164
|
+
url: string;
|
|
165
|
+
/** Alt text for the image; null when neither the author nor the image has one */
|
|
166
|
+
alt: string | null;
|
|
167
|
+
}
|
|
168
|
+
/** Everything a page's `<head>` needs, as plain values. `toNextMetadata` in `@kanorio/sdk/next` turns it into a Next.js `Metadata` object */
|
|
169
|
+
export interface SeoMetadata {
|
|
170
|
+
/** The page's own title, without the site name: add the site name in your layout */
|
|
171
|
+
title: string | null;
|
|
172
|
+
description: string | null;
|
|
173
|
+
keywords: string[] | null;
|
|
174
|
+
/** The canonical URL (absolute when `siteUrl` is given, otherwise a path); null when the response carries no path and none was passed */
|
|
175
|
+
canonical: string | null;
|
|
176
|
+
/** hreflang to URL, including `x-default`; empty on single-language sites, on pages without a translation, and without `siteUrl` and `site` */
|
|
177
|
+
languages: Record<string, string>;
|
|
178
|
+
robots: {
|
|
179
|
+
index: boolean;
|
|
180
|
+
follow: boolean;
|
|
181
|
+
};
|
|
182
|
+
openGraph: {
|
|
183
|
+
title: string | null;
|
|
184
|
+
description: string | null;
|
|
185
|
+
image: ShareImage | null;
|
|
186
|
+
};
|
|
187
|
+
twitterCard: "summary" | "summary_large_image";
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* The image to use as `og:image`, already resolved by Kanorio: the share image the author chose (cropped to 1200x630 the way they framed it),
|
|
191
|
+
* else, for a post, its cover, the generated title card or the first image in the body. Same image the hosted site uses.
|
|
192
|
+
* Reads `fieldData.share_image` of a collection item, or `seo.ogImage` of a page. Returns `null` when there is none.
|
|
193
|
+
*/
|
|
194
|
+
export declare function shareImageOf(input: SeoInput): ShareImage | null;
|
|
195
|
+
/**
|
|
196
|
+
* The `<head>` values of a blog post, a category, tag or author page, or a page, by the same rules the hosted site uses:
|
|
197
|
+
* - title and description: what the author wrote under SEO, else the item's own title and excerpt
|
|
198
|
+
* - canonical: the address the author set, on the primary locale only (a translated page always points to itself); otherwise the page's own URL
|
|
199
|
+
* - hreflang: every locale that has a published translation (needs `siteUrl` and `site`)
|
|
200
|
+
* - robots: `noindex` and `nofollow` when the author set them
|
|
201
|
+
* - share image: `shareImageOf(input)`; its alt text falls back to the title
|
|
202
|
+
* - share title and description: what the author wrote for sharing, else the SEO title and description
|
|
203
|
+
*/
|
|
204
|
+
export declare function seoMetadata(input: SeoInput, options?: SeoMetadataOptions): SeoMetadata;
|
|
94
205
|
export interface SeoHelpers {
|
|
95
206
|
rewrites(options: {
|
|
96
207
|
framework: "next";
|
|
@@ -113,8 +224,13 @@ export declare const seo: {
|
|
|
113
224
|
readonly jsonLd: typeof fetchDeliveryJsonLd;
|
|
114
225
|
readonly sitemapEntries: typeof fetchSitemapEntries;
|
|
115
226
|
readonly listingRobots: typeof listingRobots;
|
|
116
|
-
/**
|
|
227
|
+
/** The `<head>` values of a post, a category, tag or author page, or a page */
|
|
228
|
+
readonly metadata: typeof seoMetadata;
|
|
229
|
+
/** The image for `og:image`, already resolved by Kanorio */
|
|
230
|
+
readonly shareImage: typeof shareImageOf;
|
|
231
|
+
/** A page's canonical and hreflang on multilingual sites (`locales.alternates`) */
|
|
117
232
|
readonly alternates: typeof buildAlternates;
|
|
118
233
|
readonly languageSwitcher: typeof languageSwitcher;
|
|
119
234
|
readonly create: typeof createSeoHelpers;
|
|
120
235
|
};
|
|
236
|
+
export {};
|
package/dist/seo.js
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
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
|
+
* - `seoMetadata(input, options)`: the `<head>` values of a post, a category, tag or author page, or a page, by the rules the hosted site uses
|
|
8
|
+
* - `shareImageOf(input)`: the image for `og:image`, already resolved by Kanorio
|
|
7
9
|
*/
|
|
8
10
|
import { deliveryBaseUrl, parseDeliveryCacheTags } from "./delivery.js";
|
|
9
|
-
import { buildAlternates, languageSwitcher } from "./locales.js";
|
|
11
|
+
import { buildAlternates, languageSwitcher, requestLocaleOf } from "./locales.js";
|
|
10
12
|
const SEO_REWRITE_PATHS = [
|
|
11
13
|
{ source: "/sitemap.xml", apiPath: "/seo/sitemap.xml" },
|
|
12
14
|
{ source: "/robots.txt", apiPath: "/seo/robots.txt" },
|
|
@@ -25,10 +27,10 @@ export function seoRewrites(options) {
|
|
|
25
27
|
if (options.framework === "astro") {
|
|
26
28
|
return Object.fromEntries(rules.map((r) => [r.source, r.destination]));
|
|
27
29
|
}
|
|
28
|
-
// IndexNow
|
|
29
|
-
// source
|
|
30
|
-
// Astro
|
|
31
|
-
// `
|
|
30
|
+
// IndexNow requires the key verification file at `https://{host}/{key}.txt`; a dynamic Next.js path
|
|
31
|
+
// source covers every possible key value, without knowing the key in advance (the server matches it and answers).
|
|
32
|
+
// Astro's static source-to-destination map cannot express a dynamic path; there, `createKanorioMiddleware`
|
|
33
|
+
// from `@kanorio/sdk/edge` (`features.indexNow`, on by default) answers at the edge.
|
|
32
34
|
rules.push({
|
|
33
35
|
source: "/:key([a-f0-9]{32}).txt",
|
|
34
36
|
destination: `${base}/seo/indexnow-key.txt`,
|
|
@@ -59,18 +61,18 @@ export async function fetchDeliveryJsonLd(options) {
|
|
|
59
61
|
};
|
|
60
62
|
}
|
|
61
63
|
/**
|
|
62
|
-
* Kanorio
|
|
63
|
-
*
|
|
64
|
+
* The URLs Kanorio manages (the same list as `/api/v1/seo/sitemap.xml`, as data).
|
|
65
|
+
* A site with only part of its content on Kanorio merges this list with its own URLs in its sitemap generator:
|
|
64
66
|
*
|
|
65
67
|
* ```ts
|
|
66
|
-
* // app/sitemap.ts
|
|
68
|
+
* // app/sitemap.ts (Next.js)
|
|
67
69
|
* export default async function sitemap() {
|
|
68
70
|
* const kanorio = await fetchSitemapEntries({ siteUrl });
|
|
69
71
|
* return [...ownUrls, ...(kanorio?.urls ?? []).map((u) => ({ url: u.url, lastModified: u.lastModified }))];
|
|
70
72
|
* }
|
|
71
73
|
* ```
|
|
72
74
|
*
|
|
73
|
-
*
|
|
75
|
+
* Returns null when the origin fetch fails, so the caller can decide whether to output only its own URLs.
|
|
74
76
|
*/
|
|
75
77
|
export async function fetchSitemapEntries(options) {
|
|
76
78
|
const fetchImpl = options.fetch ?? globalThis.fetch;
|
|
@@ -84,18 +86,18 @@ export async function fetchSitemapEntries(options) {
|
|
|
84
86
|
return { siteUrl: body.siteUrl, urls: body.urls, cacheTags: parseDeliveryCacheTags(res.headers) };
|
|
85
87
|
}
|
|
86
88
|
catch {
|
|
87
|
-
//
|
|
89
|
+
// Unreachable, timed out or not JSON: the caller's sitemap must still be able to output its own URLs
|
|
88
90
|
return null;
|
|
89
91
|
}
|
|
90
92
|
}
|
|
91
93
|
/**
|
|
92
|
-
*
|
|
94
|
+
* 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
95
|
* - `live` → `"index, follow"`
|
|
94
|
-
* - `empty
|
|
95
|
-
* - `off
|
|
96
|
+
* - `empty` (no content yet): `"noindex, follow"`, and the page renders as usual
|
|
97
|
+
* - `off` (hidden by the owner, or not declared in externalListings): `null`; the page should not be served, so answer 404
|
|
96
98
|
*
|
|
97
|
-
* `site`
|
|
98
|
-
*
|
|
99
|
+
* `site` is the `GET /api/v1/site` response. `listings` is missing only in responses cached before the upgrade; the SDK has no content
|
|
100
|
+
* flags to derive it from, so it falls back to `live` to keep the earlier behavior. That fallback is not a defined meaning.
|
|
99
101
|
*/
|
|
100
102
|
export function listingRobots(site, key) {
|
|
101
103
|
const state = site.listings?.[key] ?? "live";
|
|
@@ -103,6 +105,92 @@ export function listingRobots(site, key) {
|
|
|
103
105
|
return null;
|
|
104
106
|
return state === "live" ? "index, follow" : "noindex, follow";
|
|
105
107
|
}
|
|
108
|
+
const text = (value) => (typeof value === "string" && value.trim() ? value.trim() : null);
|
|
109
|
+
function isItemInput(input) {
|
|
110
|
+
return typeof input.fieldData === "object" && input.fieldData !== null;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* The image to use as `og:image`, already resolved by Kanorio: the share image the author chose (cropped to 1200x630 the way they framed it),
|
|
114
|
+
* else, for a post, its cover, the generated title card or the first image in the body. Same image the hosted site uses.
|
|
115
|
+
* Reads `fieldData.share_image` of a collection item, or `seo.ogImage` of a page. Returns `null` when there is none.
|
|
116
|
+
*/
|
|
117
|
+
export function shareImageOf(input) {
|
|
118
|
+
if (isItemInput(input)) {
|
|
119
|
+
const image = input.fieldData.share_image;
|
|
120
|
+
const url = text(image?.url);
|
|
121
|
+
return url ? { url, alt: text(image?.alt) ?? text(input.fieldData.seo?.ogImageAlt) } : null;
|
|
122
|
+
}
|
|
123
|
+
const url = text(input.seo?.ogImage);
|
|
124
|
+
return url ? { url, alt: text(input.seo?.ogImageAlt) } : null;
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* The `<head>` values of a blog post, a category, tag or author page, or a page, by the same rules the hosted site uses:
|
|
128
|
+
* - title and description: what the author wrote under SEO, else the item's own title and excerpt
|
|
129
|
+
* - canonical: the address the author set, on the primary locale only (a translated page always points to itself); otherwise the page's own URL
|
|
130
|
+
* - hreflang: every locale that has a published translation (needs `siteUrl` and `site`)
|
|
131
|
+
* - robots: `noindex` and `nofollow` when the author set them
|
|
132
|
+
* - share image: `shareImageOf(input)`; its alt text falls back to the title
|
|
133
|
+
* - share title and description: what the author wrote for sharing, else the SEO title and description
|
|
134
|
+
*/
|
|
135
|
+
export function seoMetadata(input, options = {}) {
|
|
136
|
+
const item = isItemInput(input);
|
|
137
|
+
const itemSeo = item ? input.fieldData.seo ?? {} : {};
|
|
138
|
+
const pageSeo = item ? {} : input.seo ?? {};
|
|
139
|
+
const ownTitle = item ? text(input.fieldData.title) ?? text(input.fieldData.name) : text(input.title);
|
|
140
|
+
const title = (item ? text(itemSeo.title) : text(pageSeo.seoTitle)) ?? ownTitle;
|
|
141
|
+
const description = (item ? text(itemSeo.description) ?? text(input.fieldData.excerpt) : text(pageSeo.seoDescription)) ?? null;
|
|
142
|
+
const keywordList = item ? itemSeo.keywords : pageSeo.seoKeywords;
|
|
143
|
+
const keywords = keywordList && keywordList.length > 0 ? [...keywordList] : null;
|
|
144
|
+
const shared = item ? itemSeo : pageSeo;
|
|
145
|
+
const customCanonical = item ? text(itemSeo.canonical) : text(pageSeo.canonicalUrl);
|
|
146
|
+
const site = options.site ?? null;
|
|
147
|
+
const siteUrl = options.siteUrl ? options.siteUrl.replace(/\/+$/, "") : null;
|
|
148
|
+
const primaryLocale = site?.primaryLocale ?? null;
|
|
149
|
+
const resolvedLocale = input.resolvedLocale ?? null;
|
|
150
|
+
// The author's canonical is an address for the primary-locale page: a translated page ignores it
|
|
151
|
+
const servedInPrimary = !primaryLocale || !resolvedLocale || resolvedLocale === primaryLocale;
|
|
152
|
+
// The path in the primary locale's space: given by the caller, else from `localePaths`, else the response path with its locale prefix removed
|
|
153
|
+
const responsePath = text(input.path);
|
|
154
|
+
const primaryPath = text(options.path) ??
|
|
155
|
+
(primaryLocale ? text(input.localePaths?.[primaryLocale]) : null) ??
|
|
156
|
+
(responsePath ? (site ? requestLocaleOf(responsePath, site).pathname : responsePath) : null);
|
|
157
|
+
let canonical = null;
|
|
158
|
+
let languages = {};
|
|
159
|
+
if (primaryPath && siteUrl && site) {
|
|
160
|
+
const alternates = buildAlternates({
|
|
161
|
+
siteUrl,
|
|
162
|
+
site,
|
|
163
|
+
path: primaryPath,
|
|
164
|
+
requestLocale: options.requestLocale ?? resolvedLocale,
|
|
165
|
+
resolvedLocale,
|
|
166
|
+
availableLocales: input.availableLocales ?? null,
|
|
167
|
+
localePaths: input.localePaths ?? null,
|
|
168
|
+
});
|
|
169
|
+
canonical = alternates.canonical;
|
|
170
|
+
languages = alternates.languages;
|
|
171
|
+
}
|
|
172
|
+
else if (responsePath ?? primaryPath) {
|
|
173
|
+
const path = (responsePath ?? primaryPath);
|
|
174
|
+
canonical = siteUrl ? `${siteUrl}${path === "/" ? "" : path}` : path;
|
|
175
|
+
}
|
|
176
|
+
if (customCanonical && servedInPrimary)
|
|
177
|
+
canonical = customCanonical;
|
|
178
|
+
const image = shareImageOf(input);
|
|
179
|
+
return {
|
|
180
|
+
title,
|
|
181
|
+
description,
|
|
182
|
+
keywords,
|
|
183
|
+
canonical,
|
|
184
|
+
languages,
|
|
185
|
+
robots: { index: text(shared.robotsIndex) !== "noindex", follow: text(shared.robotsFollow) !== "nofollow" },
|
|
186
|
+
openGraph: {
|
|
187
|
+
title: text(shared.ogTitle) ?? title,
|
|
188
|
+
description: text(shared.ogDescription) ?? description,
|
|
189
|
+
image: image ? { url: image.url, alt: image.alt ?? ownTitle } : null,
|
|
190
|
+
},
|
|
191
|
+
twitterCard: text(shared.twitterCard) === "summary" ? "summary" : "summary_large_image",
|
|
192
|
+
};
|
|
193
|
+
}
|
|
106
194
|
export function createSeoHelpers(options) {
|
|
107
195
|
function rewrites(opts) {
|
|
108
196
|
return seoRewrites({ siteUrl: options.siteUrl, framework: opts.framework });
|
|
@@ -118,7 +206,11 @@ export const seo = {
|
|
|
118
206
|
jsonLd: fetchDeliveryJsonLd,
|
|
119
207
|
sitemapEntries: fetchSitemapEntries,
|
|
120
208
|
listingRobots,
|
|
121
|
-
/**
|
|
209
|
+
/** The `<head>` values of a post, a category, tag or author page, or a page */
|
|
210
|
+
metadata: seoMetadata,
|
|
211
|
+
/** The image for `og:image`, already resolved by Kanorio */
|
|
212
|
+
shareImage: shareImageOf,
|
|
213
|
+
/** A page's canonical and hreflang on multilingual sites (`locales.alternates`) */
|
|
122
214
|
alternates: buildAlternates,
|
|
123
215
|
languageSwitcher,
|
|
124
216
|
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,24 @@ 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
|
+
/** A form's definition changed, it was paused or resumed, or it moved to or from the trash: the form's own response in every locale */
|
|
134
|
+
readonly formChanged: (formId: string) => string[];
|
|
135
|
+
/** The locale set changed (enabled, disabled, removed, prefix, order, primary): the language switcher and hreflang are on every page */
|
|
134
136
|
readonly localeChanged: (siteId: string) => string[];
|
|
135
|
-
/**
|
|
137
|
+
/** A full-site translation finished: every response in that locale */
|
|
136
138
|
readonly translationJobCompleted: (locale: string) => string[];
|
|
137
139
|
/**
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
+
* 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.
|
|
141
|
+
* 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
142
|
*/
|
|
141
143
|
readonly translationChanged: (input: TranslationEventInput) => string[];
|
|
142
144
|
};
|