@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/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,
@@ -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. Without it, Kanorio's edge treats server-to-server writes
7
- * as automated traffic and answers with a challenge page.
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
- /** What to tell the developer (or their AI tool) when a request was challenged at the edge. */
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;
@@ -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. Without it, Kanorio's edge treats server-to-server writes
7
- * as automated traffic and answers with a challenge page.
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
- /** What to tell the developer (or their AI tool) when a request was challenged at the edge. */
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 challenged this request. In a browser this usually clears after the visitor passes the check; retry the request.";
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. 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.";
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
- const raw = condition.kind === "hidden" || visible.has(condition.ref) ? answers[condition.ref] : null;
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,3 @@
1
+ export declare function warnOnce(key: string, message: string): void;
2
+ /** For tests: forget which warnings were printed */
3
+ export declare function resetWarnOnce(): void;
@@ -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.1.0",
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": [