@kanorio/sdk 1.1.0 → 1.3.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 +70 -1
- package/dist/edge.d.ts +4 -3
- package/dist/edge.js +26 -2
- package/dist/forms.d.ts +44 -2
- package/dist/forms.js +27 -8
- package/dist/generated/delivery.d.ts +640 -24
- package/dist/generated/management.d.ts +2021 -247
- package/dist/http.d.ts +2 -2
- package/dist/http.js +2 -2
- package/dist/image.d.ts +107 -0
- package/dist/image.js +136 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +3 -2
- package/dist/next.d.ts +72 -0
- package/dist/next.js +72 -0
- package/dist/paginate.d.ts +23 -0
- package/dist/paginate.js +28 -2
- package/dist/seo.d.ts +145 -1
- package/dist/seo.js +126 -1
- package/dist/server-key.d.ts +13 -3
- package/dist/server-key.js +24 -5
- package/dist/shared/api/delivery/cache-tags.d.ts +4 -2
- package/dist/shared/api/delivery/cache-tags.js +5 -1
- package/dist/shared/api/server-key.d.ts +8 -0
- package/dist/shared/api/server-key.js +8 -0
- package/dist/shared/types/forms-logic.js +7 -2
- package/dist/warn-once.d.ts +3 -0
- package/dist/warn-once.js +16 -0
- package/package.json +6 -1
package/dist/seo.d.ts
CHANGED
|
@@ -4,9 +4,11 @@
|
|
|
4
4
|
* - `fetchDeliveryJsonLd({ siteUrl, path })`: fetches a path's Schema.org JSON-LD `@graph` and a safely escaped `<script>` string
|
|
5
5
|
* - `fetchSitemapEntries({ siteUrl })`: `sitemap.xml` as data, for front ends that build their own sitemap and merge it in
|
|
6
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";
|
|
@@ -91,6 +93,143 @@ export declare function fetchSitemapEntries(options: {
|
|
|
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
|
+
/** A category's description: the description of its page when no SEO description was written */
|
|
137
|
+
description?: unknown;
|
|
138
|
+
/** An author's bio: the description of their page when no SEO description was written */
|
|
139
|
+
bio?: unknown;
|
|
140
|
+
/**
|
|
141
|
+
* `{ posts }`, the number of published posts of a category, tag or author. The Delivery API sends it for these three only,
|
|
142
|
+
* so an item with it gets the rules of a category, tag or author page (keep it when you narrow the response with `fields`)
|
|
143
|
+
*/
|
|
144
|
+
counts?: unknown;
|
|
145
|
+
seo?: ItemSeoFields | null;
|
|
146
|
+
share_image?: {
|
|
147
|
+
url: string;
|
|
148
|
+
alt?: string | null;
|
|
149
|
+
source?: ShareImageSource | null;
|
|
150
|
+
width?: number | null;
|
|
151
|
+
height?: number | null;
|
|
152
|
+
} | null;
|
|
153
|
+
[key: string]: unknown;
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
/** A page from `GET /pages/{slug}` */
|
|
157
|
+
export interface SeoPageInput extends LocalizedResponseFields {
|
|
158
|
+
title?: string | null;
|
|
159
|
+
seo?: PageSeoFields | null;
|
|
160
|
+
}
|
|
161
|
+
export type SeoInput = SeoItemInput | SeoPageInput;
|
|
162
|
+
export interface SeoMetadataOptions {
|
|
163
|
+
/** 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 */
|
|
164
|
+
siteUrl?: string;
|
|
165
|
+
/** The `GET /api/v1/site` response. Needed on multilingual sites for hreflang and the canonical of a translated page */
|
|
166
|
+
site?: SiteLocaleMeta | null;
|
|
167
|
+
/** The locale in the URL of this request (`locale` from `resolveRequestLocale`); defaults to the locale the content was served in */
|
|
168
|
+
requestLocale?: string | null;
|
|
169
|
+
/**
|
|
170
|
+
* The page's path in the primary locale's space (no locale prefix), when the response does not carry one:
|
|
171
|
+
* an item of a custom collection without `pathTemplate`, or a page you route yourself
|
|
172
|
+
*/
|
|
173
|
+
path?: string;
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* Where a share image came from: the one the author `chosen`, the post's `cover`, the `title_card` Kanorio generates from the title,
|
|
177
|
+
* or the first image in the body (`body_image`). Skip `title_card` when you show the share image as a list card's thumbnail
|
|
178
|
+
*/
|
|
179
|
+
export type ShareImageSource = "chosen" | "cover" | "title_card" | "body_image";
|
|
180
|
+
export interface ShareImage {
|
|
181
|
+
url: string;
|
|
182
|
+
/**
|
|
183
|
+
* Alt text for the image: what the author wrote for the share image, else the image's own. When the image the author chose
|
|
184
|
+
* is gone and another one is used, only that image's own alt text applies. null when there is none
|
|
185
|
+
*/
|
|
186
|
+
alt: string | null;
|
|
187
|
+
/** Where the image came from; null for a page (`seo.ogImage` does not say) */
|
|
188
|
+
source: ShareImageSource | null;
|
|
189
|
+
/** Pixel size `url` delivers, for `og:image:width` and `og:image:height`; null when unknown (a page, an external URL, an SVG) */
|
|
190
|
+
width: number | null;
|
|
191
|
+
height: number | null;
|
|
192
|
+
}
|
|
193
|
+
/** Everything a page's `<head>` needs, as plain values. `toNextMetadata` in `@kanorio/sdk/next` turns it into a Next.js `Metadata` object */
|
|
194
|
+
export interface SeoMetadata {
|
|
195
|
+
/** The page's own title, without the site name: add the site name in your layout */
|
|
196
|
+
title: string | null;
|
|
197
|
+
description: string | null;
|
|
198
|
+
keywords: string[] | null;
|
|
199
|
+
/** The canonical URL (absolute when `siteUrl` is given, otherwise a path); null when the response carries no path and none was passed */
|
|
200
|
+
canonical: string | null;
|
|
201
|
+
/** hreflang to URL, including `x-default`; empty on single-language sites, on pages without a translation, and without `siteUrl` and `site` */
|
|
202
|
+
languages: Record<string, string>;
|
|
203
|
+
robots: {
|
|
204
|
+
index: boolean;
|
|
205
|
+
follow: boolean;
|
|
206
|
+
};
|
|
207
|
+
openGraph: {
|
|
208
|
+
title: string | null;
|
|
209
|
+
description: string | null;
|
|
210
|
+
image: ShareImage | null;
|
|
211
|
+
};
|
|
212
|
+
twitterCard: "summary" | "summary_large_image";
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* 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),
|
|
216
|
+
* else, for a post, its cover, the generated title card or the first image in the body. Same image the hosted site uses.
|
|
217
|
+
* Reads `fieldData.share_image` of a collection item, or `seo.ogImage` of a page. Returns `null` when there is none.
|
|
218
|
+
* The alt text is `share_image.alt` as Kanorio resolved it, `null` included: `seo.ogImageAlt` describes the image the author chose,
|
|
219
|
+
* which is not the one in `share_image` when that image is gone, so it is read only when `share_image` has no `alt` at all.
|
|
220
|
+
*/
|
|
221
|
+
export declare function shareImageOf(input: SeoInput): ShareImage | null;
|
|
222
|
+
/**
|
|
223
|
+
* The `<head>` values of a blog post, a category, tag or author page, or a page, by the same rules the hosted site uses:
|
|
224
|
+
* - title and description: what the author wrote under SEO, else the item's own title and excerpt. A category, tag or author
|
|
225
|
+
* (an item with `counts`) uses its name, and a category's description or an author's bio
|
|
226
|
+
* - canonical: the address the author set, on the primary locale only (a translated page always points to itself); otherwise the page's own URL
|
|
227
|
+
* - hreflang: every locale that has a published translation (needs `siteUrl` and `site`)
|
|
228
|
+
* - robots: `noindex` and `nofollow` when the author set them; a category, tag or author with no published posts is `noindex`
|
|
229
|
+
* - share image: `shareImageOf(input)`; its alt text falls back to the title
|
|
230
|
+
* - share title and description: what the author wrote for sharing, else the SEO title and description
|
|
231
|
+
*/
|
|
232
|
+
export declare function seoMetadata(input: SeoInput, options?: SeoMetadataOptions): SeoMetadata;
|
|
94
233
|
export interface SeoHelpers {
|
|
95
234
|
rewrites(options: {
|
|
96
235
|
framework: "next";
|
|
@@ -113,8 +252,13 @@ export declare const seo: {
|
|
|
113
252
|
readonly jsonLd: typeof fetchDeliveryJsonLd;
|
|
114
253
|
readonly sitemapEntries: typeof fetchSitemapEntries;
|
|
115
254
|
readonly listingRobots: typeof listingRobots;
|
|
255
|
+
/** The `<head>` values of a post, a category, tag or author page, or a page */
|
|
256
|
+
readonly metadata: typeof seoMetadata;
|
|
257
|
+
/** The image for `og:image`, already resolved by Kanorio */
|
|
258
|
+
readonly shareImage: typeof shareImageOf;
|
|
116
259
|
/** A page's canonical and hreflang on multilingual sites (`locales.alternates`) */
|
|
117
260
|
readonly alternates: typeof buildAlternates;
|
|
118
261
|
readonly languageSwitcher: typeof languageSwitcher;
|
|
119
262
|
readonly create: typeof createSeoHelpers;
|
|
120
263
|
};
|
|
264
|
+
export {};
|
package/dist/seo.js
CHANGED
|
@@ -4,9 +4,11 @@
|
|
|
4
4
|
* - `fetchDeliveryJsonLd({ siteUrl, path })`: fetches a path's Schema.org JSON-LD `@graph` and a safely escaped `<script>` string
|
|
5
5
|
* - `fetchSitemapEntries({ siteUrl })`: `sitemap.xml` as data, for front ends that build their own sitemap and merge it in
|
|
6
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" },
|
|
@@ -103,6 +105,125 @@ 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
|
+
const pixels = (value) => (typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null);
|
|
110
|
+
function isItemInput(input) {
|
|
111
|
+
return typeof input.fieldData === "object" && input.fieldData !== null;
|
|
112
|
+
}
|
|
113
|
+
/** The number of published posts of a category, tag or author (`fieldData.counts.posts`); null for any other item */
|
|
114
|
+
function termPostCount(fieldData) {
|
|
115
|
+
const counts = fieldData.counts;
|
|
116
|
+
if (!counts || typeof counts !== "object")
|
|
117
|
+
return null;
|
|
118
|
+
const posts = counts.posts;
|
|
119
|
+
return typeof posts === "number" && Number.isFinite(posts) ? posts : null;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* 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),
|
|
123
|
+
* else, for a post, its cover, the generated title card or the first image in the body. Same image the hosted site uses.
|
|
124
|
+
* Reads `fieldData.share_image` of a collection item, or `seo.ogImage` of a page. Returns `null` when there is none.
|
|
125
|
+
* The alt text is `share_image.alt` as Kanorio resolved it, `null` included: `seo.ogImageAlt` describes the image the author chose,
|
|
126
|
+
* which is not the one in `share_image` when that image is gone, so it is read only when `share_image` has no `alt` at all.
|
|
127
|
+
*/
|
|
128
|
+
export function shareImageOf(input) {
|
|
129
|
+
if (isItemInput(input)) {
|
|
130
|
+
const image = input.fieldData.share_image;
|
|
131
|
+
const url = text(image?.url);
|
|
132
|
+
if (!image || !url)
|
|
133
|
+
return null;
|
|
134
|
+
return {
|
|
135
|
+
url,
|
|
136
|
+
alt: image.alt !== undefined ? text(image.alt) : text(input.fieldData.seo?.ogImageAlt),
|
|
137
|
+
source: image.source ?? null,
|
|
138
|
+
width: pixels(image.width),
|
|
139
|
+
height: pixels(image.height),
|
|
140
|
+
};
|
|
141
|
+
}
|
|
142
|
+
const url = text(input.seo?.ogImage);
|
|
143
|
+
return url ? { url, alt: text(input.seo?.ogImageAlt), source: null, width: null, height: null } : null;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* The `<head>` values of a blog post, a category, tag or author page, or a page, by the same rules the hosted site uses:
|
|
147
|
+
* - title and description: what the author wrote under SEO, else the item's own title and excerpt. A category, tag or author
|
|
148
|
+
* (an item with `counts`) uses its name, and a category's description or an author's bio
|
|
149
|
+
* - canonical: the address the author set, on the primary locale only (a translated page always points to itself); otherwise the page's own URL
|
|
150
|
+
* - hreflang: every locale that has a published translation (needs `siteUrl` and `site`)
|
|
151
|
+
* - robots: `noindex` and `nofollow` when the author set them; a category, tag or author with no published posts is `noindex`
|
|
152
|
+
* - share image: `shareImageOf(input)`; its alt text falls back to the title
|
|
153
|
+
* - share title and description: what the author wrote for sharing, else the SEO title and description
|
|
154
|
+
*/
|
|
155
|
+
export function seoMetadata(input, options = {}) {
|
|
156
|
+
const item = isItemInput(input);
|
|
157
|
+
const itemSeo = item ? input.fieldData.seo ?? {} : {};
|
|
158
|
+
const pageSeo = item ? {} : input.seo ?? {};
|
|
159
|
+
// A category, tag or author page: its name is the title (an author's `title` is a job title), its description or bio describes it,
|
|
160
|
+
// and with no published posts it is an empty list page that search engines should not index
|
|
161
|
+
const termPosts = item ? termPostCount(input.fieldData) : null;
|
|
162
|
+
const isTerm = termPosts !== null;
|
|
163
|
+
const ownTitle = !item
|
|
164
|
+
? text(input.title)
|
|
165
|
+
: isTerm
|
|
166
|
+
? text(input.fieldData.name) ?? text(input.fieldData.title)
|
|
167
|
+
: text(input.fieldData.title) ?? text(input.fieldData.name);
|
|
168
|
+
const ownDescription = !item
|
|
169
|
+
? null
|
|
170
|
+
: isTerm
|
|
171
|
+
? text(input.fieldData.description) ?? text(input.fieldData.bio)
|
|
172
|
+
: text(input.fieldData.excerpt);
|
|
173
|
+
const title = (item ? text(itemSeo.title) : text(pageSeo.seoTitle)) ?? ownTitle;
|
|
174
|
+
const description = (item ? text(itemSeo.description) : text(pageSeo.seoDescription)) ?? ownDescription;
|
|
175
|
+
const keywordList = item ? itemSeo.keywords : pageSeo.seoKeywords;
|
|
176
|
+
const keywords = keywordList && keywordList.length > 0 ? [...keywordList] : null;
|
|
177
|
+
const shared = item ? itemSeo : pageSeo;
|
|
178
|
+
const customCanonical = item ? text(itemSeo.canonical) : text(pageSeo.canonicalUrl);
|
|
179
|
+
const site = options.site ?? null;
|
|
180
|
+
const siteUrl = options.siteUrl ? options.siteUrl.replace(/\/+$/, "") : null;
|
|
181
|
+
const primaryLocale = site?.primaryLocale ?? null;
|
|
182
|
+
const resolvedLocale = input.resolvedLocale ?? null;
|
|
183
|
+
// The author's canonical is an address for the primary-locale page: a translated page ignores it
|
|
184
|
+
const servedInPrimary = !primaryLocale || !resolvedLocale || resolvedLocale === primaryLocale;
|
|
185
|
+
// The path in the primary locale's space: given by the caller, else from `localePaths`, else the response path with its locale prefix removed
|
|
186
|
+
const responsePath = text(input.path);
|
|
187
|
+
const primaryPath = text(options.path) ??
|
|
188
|
+
(primaryLocale ? text(input.localePaths?.[primaryLocale]) : null) ??
|
|
189
|
+
(responsePath ? (site ? requestLocaleOf(responsePath, site).pathname : responsePath) : null);
|
|
190
|
+
let canonical = null;
|
|
191
|
+
let languages = {};
|
|
192
|
+
if (primaryPath && siteUrl && site) {
|
|
193
|
+
const alternates = buildAlternates({
|
|
194
|
+
siteUrl,
|
|
195
|
+
site,
|
|
196
|
+
path: primaryPath,
|
|
197
|
+
requestLocale: options.requestLocale ?? resolvedLocale,
|
|
198
|
+
resolvedLocale,
|
|
199
|
+
availableLocales: input.availableLocales ?? null,
|
|
200
|
+
localePaths: input.localePaths ?? null,
|
|
201
|
+
});
|
|
202
|
+
canonical = alternates.canonical;
|
|
203
|
+
languages = alternates.languages;
|
|
204
|
+
}
|
|
205
|
+
else if (responsePath ?? primaryPath) {
|
|
206
|
+
const path = (responsePath ?? primaryPath);
|
|
207
|
+
canonical = siteUrl ? `${siteUrl}${path === "/" ? "" : path}` : path;
|
|
208
|
+
}
|
|
209
|
+
if (customCanonical && servedInPrimary)
|
|
210
|
+
canonical = customCanonical;
|
|
211
|
+
const image = shareImageOf(input);
|
|
212
|
+
return {
|
|
213
|
+
title,
|
|
214
|
+
description,
|
|
215
|
+
keywords,
|
|
216
|
+
canonical,
|
|
217
|
+
languages,
|
|
218
|
+
robots: { index: text(shared.robotsIndex) !== "noindex" && termPosts !== 0, follow: text(shared.robotsFollow) !== "nofollow" },
|
|
219
|
+
openGraph: {
|
|
220
|
+
title: text(shared.ogTitle) ?? title,
|
|
221
|
+
description: text(shared.ogDescription) ?? description,
|
|
222
|
+
image: image ? { ...image, alt: image.alt ?? ownTitle } : null,
|
|
223
|
+
},
|
|
224
|
+
twitterCard: text(shared.twitterCard) === "summary" ? "summary" : "summary_large_image",
|
|
225
|
+
};
|
|
226
|
+
}
|
|
106
227
|
export function createSeoHelpers(options) {
|
|
107
228
|
function rewrites(opts) {
|
|
108
229
|
return seoRewrites({ siteUrl: options.siteUrl, framework: opts.framework });
|
|
@@ -118,6 +239,10 @@ export const seo = {
|
|
|
118
239
|
jsonLd: fetchDeliveryJsonLd,
|
|
119
240
|
sitemapEntries: fetchSitemapEntries,
|
|
120
241
|
listingRobots,
|
|
242
|
+
/** The `<head>` values of a post, a category, tag or author page, or a page */
|
|
243
|
+
metadata: seoMetadata,
|
|
244
|
+
/** The image for `og:image`, already resolved by Kanorio */
|
|
245
|
+
shareImage: shareImageOf,
|
|
121
246
|
/** A page's canonical and hreflang on multilingual sites (`locales.alternates`) */
|
|
122
247
|
alternates: buildAlternates,
|
|
123
248
|
languageSwitcher,
|
package/dist/server-key.d.ts
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
*
|
|
4
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
|
-
* customer sign-in code, report an AI crawler hit.
|
|
7
|
-
*
|
|
6
|
+
* customer sign-in code, report an AI crawler hit. With the key, Kanorio trusts the visitor IP your server
|
|
7
|
+
* relays, so each visitor gets their own rate limit and spam reputation. Without it, every request from your
|
|
8
|
+
* server counts as one visitor (your server's IP), and crawler reports are refused (`SERVER_KEY_REQUIRED`).
|
|
8
9
|
*
|
|
9
10
|
* Rules enforced here:
|
|
10
11
|
* - Never in a browser. The key is a secret; passing it in browser code throws.
|
|
@@ -29,6 +30,12 @@ export interface ServerKeyOptions {
|
|
|
29
30
|
*/
|
|
30
31
|
visitorIp?: VisitorIpSource;
|
|
31
32
|
}
|
|
33
|
+
/**
|
|
34
|
+
* True when this code is not running on the visitor's device (a browser page, a web worker or a React Native
|
|
35
|
+
* app), so it is most likely your server, an edge function or a script. Only used to decide whether to warn
|
|
36
|
+
* about a missing server key; it never changes what is sent.
|
|
37
|
+
*/
|
|
38
|
+
export declare function runsOnServer(): boolean;
|
|
32
39
|
/**
|
|
33
40
|
* Headers and fetch options for a request that carries a server key. Returns `null` when no key is set.
|
|
34
41
|
* Throws when called in a browser or against a non-HTTPS URL.
|
|
@@ -67,5 +74,8 @@ export declare function isEdgeChallenge(response: {
|
|
|
67
74
|
};
|
|
68
75
|
}): boolean;
|
|
69
76
|
export declare const EDGE_CHALLENGE_CODE = "EDGE_CHALLENGE";
|
|
70
|
-
/**
|
|
77
|
+
/**
|
|
78
|
+
* What to tell the developer (or their AI tool) when a request was challenged at the edge. API requests are not
|
|
79
|
+
* normally challenged, so this only happens when something at the edge is off; the message says what to check.
|
|
80
|
+
*/
|
|
71
81
|
export declare function edgeChallengeMessage(hasServerKey: boolean): string;
|
package/dist/server-key.js
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
*
|
|
4
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
|
-
* customer sign-in code, report an AI crawler hit.
|
|
7
|
-
*
|
|
6
|
+
* customer sign-in code, report an AI crawler hit. With the key, Kanorio trusts the visitor IP your server
|
|
7
|
+
* relays, so each visitor gets their own rate limit and spam reputation. Without it, every request from your
|
|
8
|
+
* server counts as one visitor (your server's IP), and crawler reports are refused (`SERVER_KEY_REQUIRED`).
|
|
8
9
|
*
|
|
9
10
|
* Rules enforced here:
|
|
10
11
|
* - Never in a browser. The key is a secret; passing it in browser code throws.
|
|
@@ -18,6 +19,21 @@ const LOCAL_HOST_RE = /^(localhost|127\.0\.0\.1|\[::1\])$/i;
|
|
|
18
19
|
function isBrowser() {
|
|
19
20
|
return typeof window !== "undefined" && typeof document !== "undefined";
|
|
20
21
|
}
|
|
22
|
+
/**
|
|
23
|
+
* True when this code is not running on the visitor's device (a browser page, a web worker or a React Native
|
|
24
|
+
* app), so it is most likely your server, an edge function or a script. Only used to decide whether to warn
|
|
25
|
+
* about a missing server key; it never changes what is sent.
|
|
26
|
+
*/
|
|
27
|
+
export function runsOnServer() {
|
|
28
|
+
if (isBrowser())
|
|
29
|
+
return false;
|
|
30
|
+
const scope = globalThis;
|
|
31
|
+
if (scope.navigator?.product === "ReactNative")
|
|
32
|
+
return false;
|
|
33
|
+
if (typeof scope.importScripts === "function")
|
|
34
|
+
return false;
|
|
35
|
+
return true;
|
|
36
|
+
}
|
|
21
37
|
/**
|
|
22
38
|
* Headers and fetch options for a request that carries a server key. Returns `null` when no key is set.
|
|
23
39
|
* Throws when called in a browser or against a non-HTTPS URL.
|
|
@@ -92,12 +108,15 @@ export function isEdgeChallenge(response) {
|
|
|
92
108
|
return response.headers.get("cf-mitigated") === "challenge";
|
|
93
109
|
}
|
|
94
110
|
export const EDGE_CHALLENGE_CODE = "EDGE_CHALLENGE";
|
|
95
|
-
/**
|
|
111
|
+
/**
|
|
112
|
+
* What to tell the developer (or their AI tool) when a request was challenged at the edge. API requests are not
|
|
113
|
+
* normally challenged, so this only happens when something at the edge is off; the message says what to check.
|
|
114
|
+
*/
|
|
96
115
|
export function edgeChallengeMessage(hasServerKey) {
|
|
97
116
|
if (isBrowser()) {
|
|
98
|
-
return "Kanorio's edge
|
|
117
|
+
return "Kanorio's edge answered this request with a security check page, so it never reached the API. API requests are not normally checked this way: retry in a moment, and contact Kanorio support if it keeps happening.";
|
|
99
118
|
}
|
|
100
119
|
return hasServerKey
|
|
101
120
|
? "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
|
-
: "Kanorio's edge challenged this server-side request
|
|
121
|
+
: "Kanorio's edge challenged this server-side request, so it never reached the API. Sending a server key avoids this: 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
122
|
}
|
|
@@ -101,7 +101,7 @@ export declare const responseCacheTags: {
|
|
|
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
|
-
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";
|
|
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" | "media_asset";
|
|
105
105
|
export interface TranslationEventInput {
|
|
106
106
|
entityType: TranslationCacheScope;
|
|
107
107
|
entityId: string;
|
|
@@ -130,9 +130,11 @@ export declare const eventCacheTags: {
|
|
|
130
130
|
readonly schemaChanged: (input: {
|
|
131
131
|
collectionKey: string;
|
|
132
132
|
}) => string[];
|
|
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[];
|
|
133
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
|
-
/** A full-site translation finished: every response in that locale */
|
|
137
|
+
/** A full-site translation finished, or stopped after it had written translations for a live locale (`localization.job.failed`): every response in that locale */
|
|
136
138
|
readonly translationJobCompleted: (locale: string) => string[];
|
|
137
139
|
/**
|
|
138
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.
|
|
@@ -160,9 +160,11 @@ export const eventCacheTags = {
|
|
|
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
|
+
/** A form's definition changed, it was paused or resumed, or it moved to or from the trash: the form's own response in every locale */
|
|
164
|
+
formChanged: (formId) => [cacheTag.form(formId)],
|
|
163
165
|
/** The locale set changed (enabled, disabled, removed, prefix, order, primary): the language switcher and hreflang are on every page */
|
|
164
166
|
localeChanged: (siteId) => [cacheTag.site(siteId)],
|
|
165
|
-
/** A full-site translation finished: every response in that locale */
|
|
167
|
+
/** A full-site translation finished, or stopped after it had written translations for a live locale (`localization.job.failed`): every response in that locale */
|
|
166
168
|
translationJobCompleted: (locale) => [cacheTag.locale(locale)],
|
|
167
169
|
/**
|
|
168
170
|
* One record's translation in one locale went live or was deleted: only locale-specific tags are sent, so the caches of other locales and the primary locale stay.
|
|
@@ -179,6 +181,8 @@ export const eventCacheTags = {
|
|
|
179
181
|
case "top_bar_banner":
|
|
180
182
|
case "modal_announcement":
|
|
181
183
|
case "floating_widget":
|
|
184
|
+
// A media library alt text is the fallback wherever that image is used without its own alt
|
|
185
|
+
case "media_asset":
|
|
182
186
|
return [cacheTag.locale(input.locale)];
|
|
183
187
|
case "post":
|
|
184
188
|
case "post_category":
|
|
@@ -14,6 +14,14 @@ export declare const SERVER_KEY_VISITOR_IP_HEADER = "X-Kanorio-Visitor-IP";
|
|
|
14
14
|
* `x-kanorio-client-ip` only when this header and the worker's own key (X-API-Key) are both present.
|
|
15
15
|
*/
|
|
16
16
|
export declare const SERVER_KEY_ID_FORWARD_HEADER = "x-kanorio-server-key-id";
|
|
17
|
+
/**
|
|
18
|
+
* Edge worker to server, only together with `SERVER_KEY_ID_FORWARD_HEADER` (value `"1"`): the server holding the key did not relay a
|
|
19
|
+
* visitor IP, so the client IP the worker forwards is that server's own address, shared by every visitor it calls for. The server trusts it
|
|
20
|
+
* only with the worker's own key (X-API-Key) and the key id, and then skips limits counted per visitor IP that would let one visitor's
|
|
21
|
+
* failures block everyone behind that server; the worker's per-key and per-site limits still apply. The worker sets it only from a
|
|
22
|
+
* verified key and never forwards a copy that a caller sent.
|
|
23
|
+
*/
|
|
24
|
+
export declare const SERVER_KEY_OWN_IP_HEADER = "x-kanorio-client-ip-is-server";
|
|
17
25
|
/**
|
|
18
26
|
* Machine-only marker in a service account's grants and its keys' scopes. It is not in the catalog of permissions people can hold:
|
|
19
27
|
* no team role has it, the role editor does not show it, and personal access tokens and OAuth cannot select it. Creating such a service account only needs `developer:manage`.
|
|
@@ -15,6 +15,14 @@ export const SERVER_KEY_VISITOR_IP_HEADER = "X-Kanorio-Visitor-IP";
|
|
|
15
15
|
* `x-kanorio-client-ip` only when this header and the worker's own key (X-API-Key) are both present.
|
|
16
16
|
*/
|
|
17
17
|
export const SERVER_KEY_ID_FORWARD_HEADER = "x-kanorio-server-key-id";
|
|
18
|
+
/**
|
|
19
|
+
* Edge worker to server, only together with `SERVER_KEY_ID_FORWARD_HEADER` (value `"1"`): the server holding the key did not relay a
|
|
20
|
+
* visitor IP, so the client IP the worker forwards is that server's own address, shared by every visitor it calls for. The server trusts it
|
|
21
|
+
* only with the worker's own key (X-API-Key) and the key id, and then skips limits counted per visitor IP that would let one visitor's
|
|
22
|
+
* failures block everyone behind that server; the worker's per-key and per-site limits still apply. The worker sets it only from a
|
|
23
|
+
* verified key and never forwards a copy that a caller sent.
|
|
24
|
+
*/
|
|
25
|
+
export const SERVER_KEY_OWN_IP_HEADER = "x-kanorio-client-ip-is-server";
|
|
18
26
|
/**
|
|
19
27
|
* Machine-only marker in a service account's grants and its keys' scopes. It is not in the catalog of permissions people can hold:
|
|
20
28
|
* no team role has it, the role editor does not show it, and personal access tokens and OAuth cannot select it. Creating such a service account only needs `developer:manage`.
|
|
@@ -167,6 +167,10 @@ export function evaluateCondition(condition, sourceType, raw) {
|
|
|
167
167
|
}
|
|
168
168
|
}
|
|
169
169
|
}
|
|
170
|
+
/** The answer stored under `id` itself, or undefined: never a value inherited from `Object.prototype` */
|
|
171
|
+
function ownAnswer(answers, id) {
|
|
172
|
+
return Object.prototype.hasOwnProperty.call(answers, id) ? answers[id] : undefined;
|
|
173
|
+
}
|
|
170
174
|
/**
|
|
171
175
|
* Works out which questions to show from the current answers. `answers` maps a question id or hidden field id to its value (the raw value the visitor typed is fine).
|
|
172
176
|
* Evaluated in question order: when an earlier question is hidden, a condition referring to it treats it as unanswered.
|
|
@@ -190,8 +194,9 @@ export function resolveVisibleFieldIds(fields, answers) {
|
|
|
190
194
|
undecidable = true;
|
|
191
195
|
return false;
|
|
192
196
|
}
|
|
193
|
-
// The source question is itself hidden: treated as unanswered
|
|
194
|
-
|
|
197
|
+
// The source question is itself hidden: treated as unanswered. Only the answers' own keys count: an id can be a built-in
|
|
198
|
+
// object property name (`constructor`), and reading it from an object without that key returns the prototype's function
|
|
199
|
+
const raw = condition.kind === "hidden" || visible.has(condition.ref) ? ownAnswer(answers, condition.ref) : null;
|
|
195
200
|
const result = evaluateCondition(condition, sourceType, raw);
|
|
196
201
|
if (result === null)
|
|
197
202
|
undecidable = true;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Console warnings that should appear once per process. A flag kept on a helpers object is not enough: the usual server pattern
|
|
3
|
+
* creates the helpers inside each request (the visitor IP differs per request), so a per-instance flag would print on every call.
|
|
4
|
+
* Internal: not part of the package's public surface.
|
|
5
|
+
*/
|
|
6
|
+
const printed = new Set();
|
|
7
|
+
export function warnOnce(key, message) {
|
|
8
|
+
if (printed.has(key))
|
|
9
|
+
return;
|
|
10
|
+
printed.add(key);
|
|
11
|
+
console.warn(message);
|
|
12
|
+
}
|
|
13
|
+
/** For tests: forget which warnings were printed */
|
|
14
|
+
export function resetWarnOnce() {
|
|
15
|
+
printed.clear();
|
|
16
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kanorio/sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.0",
|
|
4
4
|
"description": "Typed fetch clients and headless helpers (SEO rewrites, JSON-LD, webhook revalidateTag) for the Kanorio Management API, Content Delivery API and Customer API.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"private": false,
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
"directory": "packages/sdk"
|
|
26
26
|
},
|
|
27
27
|
"type": "module",
|
|
28
|
+
"sideEffects": false,
|
|
28
29
|
"main": "./dist/index.js",
|
|
29
30
|
"types": "./dist/index.d.ts",
|
|
30
31
|
"exports": {
|
|
@@ -63,6 +64,10 @@
|
|
|
63
64
|
"./preview": {
|
|
64
65
|
"types": "./dist/preview.d.ts",
|
|
65
66
|
"default": "./dist/preview.js"
|
|
67
|
+
},
|
|
68
|
+
"./next": {
|
|
69
|
+
"types": "./dist/next.d.ts",
|
|
70
|
+
"default": "./dist/next.js"
|
|
66
71
|
}
|
|
67
72
|
},
|
|
68
73
|
"files": [
|