@kanorio/sdk 1.2.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 CHANGED
@@ -23,7 +23,7 @@ const customer = createCustomerClient({
23
23
  });
24
24
  ```
25
25
 
26
- When your own server writes on a visitor's behalf (submitting a form, exchanging a customer sign-in code, reporting crawler hits from middleware), pass a server key and the visitor's IP. Without the key, server-to-server writes are stopped by an edge challenge and the SDK throws `KanorioEdgeChallengeError`.
26
+ When your own server writes on a visitor's behalf (submitting a form, exchanging a customer sign-in code, reporting crawler hits from middleware), pass a server key and the visitor's IP. Without the key the write still reaches the API, but as an anonymous visitor at your server's IP address (all your visitors share one rate limit and one spam reputation), and crawler reports are refused with `401 SERVER_KEY_REQUIRED`.
27
27
 
28
28
  ```ts
29
29
  import { createFormsHelpers, visitorIpFromRequest } from "@kanorio/sdk";
@@ -52,14 +52,18 @@ const { item, assets } = await delivery.get("/collections/{key}/items/{slug}", {
52
52
  const cover = image.resolve(item.fieldData.cover_image, assets);
53
53
  if (cover) {
54
54
  cover.url; // the original
55
- image.url(cover.url, { width: 800 }); // resized by Kanorio's edge, never enlarged
56
- image.srcSet(cover.url); // 400w, 800w, 1200w, 1600w
55
+ image.url(cover, { width: 800 }); // resized by Kanorio's edge, never enlarged
56
+ image.url(cover, { width: 400, height: 400 }); // cropped to a square around the focal point the owner set
57
+ image.srcSet(cover); // 400w, 800w, 1200w, 1600w
58
+ cover.placeholder; // a tiny blurred preview, for Next.js `blurDataURL`
59
+ cover.focus; // { x, y } from 0 to 1, for `object-position` when CSS crops
60
+ cover.edgeColor; // the color around the photo, for the background behind `object-fit: contain`
57
61
  }
58
62
 
59
63
  const meta = seo.metadata(item, { siteUrl: "https://www.example.com", site });
60
64
  meta.canonical; // the author's canonical on the primary locale, else the page's own URL
61
65
  meta.robots; // { index, follow }
62
- meta.openGraph.image; // { url, alt }: the share image, already cropped the way the author framed it
66
+ meta.openGraph.image; // { url, alt, source, width, height }: the share image, already cropped the way the author framed it
63
67
  ```
64
68
 
65
69
  The share image comes from `fieldData.share_image`, which Kanorio resolves on the server: the image the author chose for sharing, else a post's cover, the generated title card, or the first image in the body. Pass `site` (the `GET /site` response) on multilingual sites to get hreflang and the right canonical for translated pages.
@@ -68,14 +72,40 @@ For Next.js, `@kanorio/sdk/next` adapts these without depending on `next`:
68
72
 
69
73
  ```ts
70
74
  import { seoMetadata } from "@kanorio/sdk";
71
- import { kanorioImageLoader, toNextMetadata } from "@kanorio/sdk/next";
75
+ import { toNextMetadata } from "@kanorio/sdk/next";
72
76
 
73
77
  export async function generateMetadata({ params }) {
74
78
  const data = await loadPost((await params).slug);
75
79
  return data ? toNextMetadata(seoMetadata(data.item, { siteUrl: SITE_URL, site })) : {};
76
80
  }
81
+ ```
82
+
83
+ `kanorioImageLoader` lets Kanorio's edge resize `next/image` (`kanorioRemotePatterns` allows Kanorio's image host when you let Next.js resize instead). A loader is a function, so pass it from a Client Component, or set it for the whole app with `images.loaderFile`:
84
+
85
+ ```tsx
86
+ "use client";
87
+
88
+ import Image from "next/image";
89
+ import { kanorioImageLoader } from "@kanorio/sdk/next";
90
+
91
+ export function CoverImage({ src, alt, width, height }: { src: string; alt: string; width: number; height: number }) {
92
+ return <Image loader={kanorioImageLoader} src={src} alt={alt} width={width} height={height} />;
93
+ }
94
+ ```
95
+
96
+ The [Next.js guide](https://kanorio.com/en/developers/guides/nextjs) has a complete component that also shows the blurred preview and keeps the owner's focal point.
97
+
98
+ To use `next/image` without the loader, allow Kanorio's image host in `next.config.ts`:
99
+
100
+ ```ts
101
+ import type { NextConfig } from "next";
102
+ import { kanorioRemotePatterns } from "@kanorio/sdk/next";
103
+
104
+ const nextConfig: NextConfig = {
105
+ images: { remotePatterns: kanorioRemotePatterns },
106
+ };
77
107
 
78
- // <Image loader={kanorioImageLoader} src={cover.url} width={cover.width} height={cover.height} alt={cover.alt ?? ""} />
108
+ export default nextConfig;
79
109
  ```
80
110
 
81
111
  ## Tax id validation
package/dist/edge.d.ts CHANGED
@@ -50,9 +50,10 @@ export interface KanorioMiddlewareOptions {
50
50
  };
51
51
  fetch?: typeof globalThis.fetch;
52
52
  /**
53
- * Server key (`knr_sk_…`, from an environment variable). Required for crawler hit reporting: the report is a
54
- * server-to-server write, and without a key Kanorio's edge challenges it and the hit is lost. The visitor's
55
- * (crawler's) IP is read from the incoming request with `visitorIpFromRequest`.
53
+ * Server key (`knr_sk_…`, from an environment variable). Required for crawler hit reporting: Kanorio only
54
+ * accepts crawler reports from your server with a key (`401 SERVER_KEY_REQUIRED` without one), so without it
55
+ * the middleware does not send them and warns once. Redirects and crawler blocking work either way. The
56
+ * visitor's (crawler's) IP is read from the incoming request with `visitorIpFromRequest`.
56
57
  */
57
58
  serverKey?: string;
58
59
  }
package/dist/edge.js CHANGED
@@ -154,25 +154,33 @@ export function createKanorioMiddleware(options) {
154
154
  })();
155
155
  return inflight;
156
156
  }
157
- // A rejected report must not fail the visitor's request, but it must not be silent either: the site would keep redirecting and
158
- // blocking while its crawler numbers quietly stop. One warning per middleware instance, never per request.
159
- let reportWarned = false;
157
+ const reportWarned = new Set();
158
+ function warnReportsLost(cause, reason) {
159
+ if (reportWarned.has(cause))
160
+ return;
161
+ reportWarned.add(cause);
162
+ console.warn(`@kanorio/sdk: AI crawler hits are not being recorded. ${reason} Redirects and crawler blocking are not affected.`);
163
+ }
160
164
  function warnReportRejected(response) {
161
- if (reportWarned || response.ok)
165
+ if (response.ok)
162
166
  return;
163
- reportWarned = true;
164
167
  const hasKey = Boolean(options.serverKey?.trim());
165
- const reason = isEdgeChallenge(response)
166
- ? edgeChallengeMessage(hasKey)
167
- : response.status === 401
168
- ? "Kanorio rejected the server key. Keys that start with knr_sa_ are no longer server keys, and a revoked key is rejected too: create a new one under Site settings > Developer (purpose \"Website server\") and store it as KANORIO_SERVER_KEY."
169
- : `Kanorio answered ${response.status}.`;
170
- console.warn(`@kanorio/sdk: AI crawler hits are not being recorded. ${reason} Redirects and crawler blocking are not affected.`);
168
+ if (isEdgeChallenge(response))
169
+ return warnReportsLost("edge-challenge", edgeChallengeMessage(hasKey));
170
+ if (response.status === 401) {
171
+ return warnReportsLost("key-rejected", "Kanorio rejected the server key. Keys that start with knr_sa_ are no longer server keys, and a revoked key is rejected too: create a new one under Site settings > Developer (purpose \"Website server\") and store it as KANORIO_SERVER_KEY.");
172
+ }
173
+ warnReportsLost("other", `Kanorio answered ${response.status}.`);
171
174
  }
172
175
  function reportBotHit(request, pathname, bot, blocked, event) {
176
+ // Kanorio only accepts crawler reports with a server key: without one, sending would only earn a 401 on every crawler hit
177
+ if (!options.serverKey?.trim()) {
178
+ warnReportsLost("no-key", "Crawler reports need a server key: create one under Site settings > Developer (purpose \"Website server\"), store it as KANORIO_SERVER_KEY and pass `serverKey` to createKanorioMiddleware. Do not paste the key into chat or commit it.");
179
+ return;
180
+ }
173
181
  const userAgent = request.headers.get("user-agent") ?? bot.uaToken;
174
182
  const url = `${apiBase}/analytics/bot-hit`;
175
- // Sends the server key and the visitor IP (read only from headers the platform guarantees); without a key it is still sent, the edge blocks it and the report is lost without affecting the request
183
+ // Sends the server key and the visitor IP (read only from headers the platform guarantees)
176
184
  const promise = serverKeyRequest({ serverKey: options.serverKey, visitorIp: visitorIpFromRequest(request) }, url)
177
185
  .then((viaServerKey) => f(url, {
178
186
  method: "POST",
package/dist/forms.d.ts CHANGED
@@ -51,7 +51,15 @@ export interface FormSubmitInput {
51
51
  protection?: FormProtectionFields | Record<string, unknown>;
52
52
  consent?: "checked" | "submit_statement";
53
53
  consentTextId?: string;
54
+ /** The visitor's language, kept on the submission and the contact (for example `navigator.language`). Defaults to the helpers' `locale`. */
54
55
  locale?: string;
56
+ /**
57
+ * The site locale of the page the form is on: a code from `locales[]` of `GET /api/v1/site` (`th`, `en-US`) or its URL prefix.
58
+ * A redirect after submit to a path on the site gets this locale's URL prefix. Defaults to the helpers' `locale`; `null` sends
59
+ * none. Without it, Kanorio reads the locale from `pagePath`.
60
+ */
61
+ pageLocale?: string | null;
62
+ /** Path of the page the form is on, kept on the submission record */
55
63
  pagePath?: string;
56
64
  /** Where this visit came from (kept on the submission record): UTM and ad-click parameters, external referrer host, landing path. */
57
65
  attribution?: {
@@ -76,7 +84,14 @@ export type FormSubmitResult = {
76
84
  error: FormApiError;
77
85
  };
78
86
  export interface FormsHelpers {
79
- get(formId: string): Promise<{
87
+ /**
88
+ * The form's definition. With `locale` (or the helpers' `locale`), question labels, options, the button and the success message
89
+ * are in that locale; text without a translation falls back to the primary locale. `locale: null` reads the primary locale
90
+ * even when the helpers have a `locale`.
91
+ */
92
+ get(formId: string, options?: {
93
+ locale?: string | null;
94
+ }): Promise<{
80
95
  form: FormDefinition;
81
96
  }>;
82
97
  challenge(formId: string): Promise<FormChallengeResponse>;
@@ -118,11 +133,19 @@ export declare function uploadProtectionFromChallenge(formId: string, challenge:
118
133
  export interface FormsHelpersOptions extends ServerKeyOptions {
119
134
  siteUrl: string;
120
135
  fetch?: typeof globalThis.fetch;
136
+ /**
137
+ * The locale of the page the form is on: a code from `locales[]` of `GET /api/v1/site` (`th`, `en-US`) or its URL prefix. `get()` reads
138
+ * the form in it, and `submit()` sends it as the submission's `pageLocale` and `locale` (an input's own values win), so the form's text
139
+ * and the redirect after submit follow the page's language. Omit it for the primary locale.
140
+ */
141
+ locale?: string | null;
121
142
  }
122
143
  /**
123
144
  * Pass `serverKey` (and `visitorIp`) when your **server** submits on behalf of a visitor. The key proves the
124
145
  * request comes from your server; it does not replace form protection, so the submission still needs the
125
- * `protection` fields the visitor's browser obtained.
146
+ * `protection` fields the visitor's browser obtained. Submitting from a server without a key works, but warns
147
+ * once per process (all visitors would share your server's IP). Once per process and not per helpers object: a server
148
+ * action usually creates the helpers inside each request, because the visitor IP differs per request.
126
149
  */
127
150
  export declare function createFormsHelpers(options: FormsHelpersOptions): FormsHelpers;
128
151
  /**
package/dist/forms.js CHANGED
@@ -5,7 +5,8 @@
5
5
  * Responses follow the contract shared by the three APIs: success is the object itself, failure is `{ error: { code, message, details? } }`.
6
6
  * Here both become `{ ok: true, ... }` or `{ ok: false, error }`, so a form UI does not have to read HTTP statuses.
7
7
  */
8
- import { EDGE_CHALLENGE_CODE, edgeChallengeMessage, isEdgeChallenge, serverKeyRequest } from "./server-key.js";
8
+ import { EDGE_CHALLENGE_CODE, edgeChallengeMessage, isEdgeChallenge, runsOnServer, serverKeyRequest } from "./server-key.js";
9
+ import { warnOnce } from "./warn-once.js";
9
10
  import { deliveryBaseUrl } from "./delivery.js";
10
11
  import { resolveVisibleFieldIds } from "./shared/types/forms-logic.js";
11
12
  import { protectionFromChallenge as protectionFieldsFromChallenge, uploadProtectionFromChallenge as uploadFieldsFromChallenge } from "./protection.js";
@@ -26,7 +27,7 @@ export function uploadProtectionFromChallenge(formId, challenge, renderedAt, sol
26
27
  return uploadFieldsFromChallenge(challenge, { context: formId, renderedAt, solved });
27
28
  }
28
29
  async function readFormError(res, hasServerKey) {
29
- // The edge's challenge page (a server call without a server key): return an error that says what to do next
30
+ // The edge's challenge page instead of an API response: return an error that says what to check next
30
31
  if (isEdgeChallenge(res))
31
32
  return { code: EDGE_CHALLENGE_CODE, message: edgeChallengeMessage(hasServerKey) };
32
33
  const body = (await res.json().catch(() => null));
@@ -42,10 +43,13 @@ async function readFormError(res, hasServerKey) {
42
43
  }
43
44
  return { code: res.status === 429 ? "RATE_LIMITED" : "UPSTREAM_UNAVAILABLE", message: `HTTP ${res.status}` };
44
45
  }
46
+ const SERVER_SUBMIT_WITHOUT_KEY_WARNING = "@kanorio/sdk: forms are being submitted from your server without a server key, so Kanorio sees every visitor as your server's IP address: they share one rate limit and one spam reputation, and a busy day can block real visitors. Create a server key under Site settings > Developer (purpose \"Website server\"), store it as KANORIO_SERVER_KEY, and pass `serverKey` and `visitorIp` to createFormsHelpers. Do not paste the key into chat or commit it.";
45
47
  /**
46
48
  * Pass `serverKey` (and `visitorIp`) when your **server** submits on behalf of a visitor. The key proves the
47
49
  * request comes from your server; it does not replace form protection, so the submission still needs the
48
- * `protection` fields the visitor's browser obtained.
50
+ * `protection` fields the visitor's browser obtained. Submitting from a server without a key works, but warns
51
+ * once per process (all visitors would share your server's IP). Once per process and not per helpers object: a server
52
+ * action usually creates the helpers inside each request, because the visitor IP differs per request.
49
53
  */
50
54
  export function createFormsHelpers(options) {
51
55
  const apiBase = deliveryBaseUrl(options.siteUrl);
@@ -53,6 +57,8 @@ export function createFormsHelpers(options) {
53
57
  const post = async (path, body) => {
54
58
  const url = `${apiBase}${path}`;
55
59
  const viaServerKey = await serverKeyRequest(options, url);
60
+ if (!viaServerKey && runsOnServer())
61
+ warnOnce("forms:no-server-key", SERVER_SUBMIT_WITHOUT_KEY_WARNING);
56
62
  return f(url, {
57
63
  method: "POST",
58
64
  headers: { "Content-Type": "application/json", Accept: "application/json", ...(viaServerKey?.headers ?? {}) },
@@ -62,8 +68,11 @@ export function createFormsHelpers(options) {
62
68
  };
63
69
  const readError = (res) => readFormError(res, Boolean(options.serverKey));
64
70
  return {
65
- async get(formId) {
66
- const res = await f(`${apiBase}/forms/${encodeURIComponent(formId)}`, { headers: { Accept: "application/json" } });
71
+ async get(formId, getOptions) {
72
+ // An explicit null reads the primary locale even when the helpers have a locale
73
+ const locale = getOptions?.locale !== undefined ? getOptions.locale : (options.locale ?? null);
74
+ const query = locale ? `?locale=${encodeURIComponent(locale)}` : "";
75
+ const res = await f(`${apiBase}/forms/${encodeURIComponent(formId)}${query}`, { headers: { Accept: "application/json" } });
67
76
  if (!res.ok)
68
77
  throw new Error(`Failed to fetch form ${formId}: HTTP ${res.status}`);
69
78
  return res.json();
@@ -104,8 +113,12 @@ export function createFormsHelpers(options) {
104
113
  return { ok: true, ...wire };
105
114
  },
106
115
  async submit(formId, input) {
107
- const { protection, ...rest } = input;
108
- const res = await post(`/forms/${encodeURIComponent(formId)}/submit`, { ...rest, ...(protection ?? {}) }).catch(() => null);
116
+ const { protection, pageLocale: ownPageLocale, ...rest } = input;
117
+ const locale = rest.locale ?? options.locale ?? undefined;
118
+ // The page's locale decides the redirect's URL prefix; an explicit null on the input sends none (Kanorio then reads it from pagePath)
119
+ const pageLocale = ownPageLocale !== undefined ? ownPageLocale : (options.locale ?? null);
120
+ const body = { ...rest, ...(locale ? { locale } : {}), ...(pageLocale ? { pageLocale } : {}), ...(protection ?? {}) };
121
+ const res = await post(`/forms/${encodeURIComponent(formId)}/submit`, body).catch(() => null);
109
122
  if (!res)
110
123
  return { ok: false, error: { code: "UPSTREAM_UNAVAILABLE", message: "Network error" } };
111
124
  if (!res.ok)
@@ -130,7 +130,7 @@ export interface paths {
130
130
  path?: never;
131
131
  cookie?: never;
132
132
  };
133
- /** Collections and their fields (self-describing). System collections also list virtualFields (projection-only fields such as blog segments/toc/contentHtml and taxonomy counts) with scope item|fieldData|expanded and a TypeScript type literal; a field whose shape is fixed (the seo field of blog, categories, tags and authors) carries tsType, and a system field whose value needs explaining (the blog cover_image, which is derived and can be an asset id or a URL) carries tsDoc. */
133
+ /** Collections and their fields (self-describing). System collections also list virtualFields (projection-only fields such as blog segments/toc/contentHtml and taxonomy counts) with scope item|fieldData|expanded and a TypeScript type literal; a field whose shape is fixed (the seo field of blog, categories, tags and authors) carries tsType, and a system field whose value needs explaining (the blog cover_image: the cover the author picked, an asset id or null, never derived and never a URL) carries tsDoc. A single-item collection (site settings, homepage sections) has singleton: true; read its one item at /collections/{key}/item. */
134
134
  get: operations["delivery_collections_list"];
135
135
  put?: never;
136
136
  post?: never;
@@ -174,6 +174,26 @@ export interface paths {
174
174
  patch?: never;
175
175
  trace?: never;
176
176
  };
177
+ "/collections/{key}/item": {
178
+ parameters: {
179
+ query?: never;
180
+ header?: never;
181
+ path?: never;
182
+ cookie?: never;
183
+ };
184
+ /**
185
+ * The item of a single-item collection
186
+ * @description Single-item collections (singleton: true in GET /collections) hold content that exists once, such as site settings or homepage sections. This returns their one published item in the same shape as GET /collections/{key}/items/{slug}, so no slug is needed. 404 ITEM_NOT_FOUND when nothing is published yet, or when the collection is not a single-item collection (read its items at /collections/{key}/items).
187
+ */
188
+ get: operations["delivery_collection_singleton"];
189
+ put?: never;
190
+ post?: never;
191
+ delete?: never;
192
+ options?: never;
193
+ head?: never;
194
+ patch?: never;
195
+ trace?: never;
196
+ };
177
197
  "/feed": {
178
198
  parameters: {
179
199
  query?: never;
@@ -359,7 +379,10 @@ export interface paths {
359
379
  };
360
380
  get?: never;
361
381
  put?: never;
362
- /** Record an AI crawler visit from an external storefront edge middleware (per-IP rate-limited) */
382
+ /**
383
+ * Record an AI crawler visit from your own server's edge middleware (requires a server key)
384
+ * @description Called by your server, never by a browser: send the server key in `X-Kanorio-Server-Key` and the crawler's IP address in `X-Kanorio-Visitor-IP`. Without a key the request is refused with `401 SERVER_KEY_REQUIRED`; an invalid key gets `401 UNAUTHORIZED`. `createKanorioMiddleware` in `@kanorio/sdk/edge` sends it when you pass `serverKey`.
385
+ */
363
386
  post: operations["delivery_analytics_bot_hit"];
364
387
  delete?: never;
365
388
  options?: never;
@@ -449,7 +472,7 @@ export interface paths {
449
472
  put?: never;
450
473
  /**
451
474
  * Submit answers to an online form
452
- * @description A 200 means the submission was stored. A challenge (or third-party widget token) stores one submission: sending other answers with one that was already used returns 400 VERIFICATION_EXPIRED, while sending exactly the same submission again returns 200 and stores nothing twice. After a rejected submission (INVALID_ANSWERS, DUPLICATE_SUBMISSION, RATE_LIMITED, a server error) the solved built-in challenge can be sent again. A submission is processed no sooner than 5 seconds after its challenge was issued; one that arrives earlier is held until then. Marketing consent is recorded only when consent is sent with the consentTextId from GET /forms/{id}. Requests that no real form produces (a filled honeypot field, a forged protection result, a challenge issued for another form) also get 200 and are discarded.
475
+ * @description A 200 with a submissionId means the submission was stored; a 200 with state means the form did not take it and nothing was stored. A challenge (or third-party widget token) stores one submission: sending other answers with one that was already used returns 400 VERIFICATION_EXPIRED, while sending exactly the same submission again returns 200 with the id of the stored submission and stores nothing twice. If the first is still being processed after 5 seconds, the second gets 503 UPSTREAM_UNAVAILABLE: send it again with the same challenge. 500 INTERNAL means Kanorio failed while processing the submission and nothing was stored: a third-party widget token is used up, so get a new one before sending again. After a submission that was not stored for a reason that can change (INVALID_ANSWERS, RATE_LIMITED, INTERNAL, or a form that is closed, not open yet or full) the solved built-in challenge can be sent again. DUPLICATE_SUBMISSION uses up the challenge: the same submission sent again gets the same answer, and different answers need a new challenge. A submission is processed no sooner than 5 seconds after its challenge was issued; one that arrives earlier is held until then. Marketing consent is recorded only when consent is sent with the consentTextId from GET /forms/{id}. Requests that no real form produces (a filled honeypot field, a forged protection result, a challenge issued for another form) also get 200 and are discarded.
453
476
  */
454
477
  post: operations["delivery_form_submit"];
455
478
  delete?: never;
@@ -580,7 +603,7 @@ export interface components {
580
603
  };
581
604
  };
582
605
  /** @enum {string} */
583
- ErrorCode: "BAD_HOST" | "COLLECTION_NOT_FOUND" | "DUPLICATE_SUBMISSION" | "FILE_TOO_LARGE" | "FILE_TYPE_NOT_ALLOWED" | "FORBIDDEN" | "FORM_NOT_FOUND" | "HEADER_NOT_FOUND" | "INVALID_ANSWERS" | "INVALID_BODY" | "INVALID_CURSOR" | "INVALID_KIND" | "INVALID_LIMIT" | "INVALID_PATH" | "INVALID_QUERY" | "ITEM_NOT_FOUND" | "NOT_PREVIEW" | "PAGE_NOT_FOUND" | "PAYLOAD_TOO_LARGE" | "PRODUCT_NOT_FOUND" | "QUERY_REQUIRED" | "QUERY_TIMEOUT" | "QUERY_TOO_LONG" | "QUERY_TOO_SHORT" | "RATE_LIMITED" | "SEARCH_BUSY" | "SITE_NOT_FOUND" | "TOO_MANY_PARAMS" | "UNAUTHORIZED" | "UNIT_NOT_FOUND" | "UNKNOWN_BOT" | "UNSUPPORTED_LOCALE" | "UPLOAD_UNAVAILABLE" | "UPSTREAM_UNAVAILABLE" | "VALIDATION" | "VERIFICATION_EXPIRED";
606
+ ErrorCode: "BAD_HOST" | "COLLECTION_NOT_FOUND" | "DUPLICATE_SUBMISSION" | "FILE_TOO_LARGE" | "FILE_TYPE_NOT_ALLOWED" | "FORBIDDEN" | "FORM_NOT_FOUND" | "HEADER_NOT_FOUND" | "INTERNAL" | "INVALID_ANSWERS" | "INVALID_BODY" | "INVALID_CURSOR" | "INVALID_KIND" | "INVALID_LIMIT" | "INVALID_PATH" | "INVALID_QUERY" | "ITEM_NOT_FOUND" | "NOT_PREVIEW" | "PAGE_NOT_FOUND" | "PAYLOAD_TOO_LARGE" | "PRODUCT_NOT_FOUND" | "QUERY_REQUIRED" | "QUERY_TIMEOUT" | "QUERY_TOO_LONG" | "QUERY_TOO_SHORT" | "RATE_LIMITED" | "SEARCH_BUSY" | "SERVER_KEY_REQUIRED" | "SITE_NOT_FOUND" | "TOO_MANY_PARAMS" | "UNAUTHORIZED" | "UNIT_NOT_FOUND" | "UNKNOWN_BOT" | "UNSUPPORTED_LOCALE" | "UPLOAD_UNAVAILABLE" | "UPSTREAM_UNAVAILABLE" | "VALIDATION" | "VERIFICATION_EXPIRED";
584
607
  Form: {
585
608
  id: string;
586
609
  name: string;
@@ -599,13 +622,13 @@ export interface components {
599
622
  /** @description Id of the consent text for the current settings.marketingConsent mode. Send it back unchanged as consentTextId on submit; consent is recorded only when it matches. Null when consent is off. */
600
623
  consentTextId: string | null;
601
624
  /** @description The consent text to show the visitor, in the requested locale: the owner's own wording, or the platform default with the site name and submit button text filled in. Null when consent is off. */
602
- consentText?: string | null;
625
+ consentText: string | null;
603
626
  /** @description Where to send the visitor after a successful submit, with the locale prefix already added. Null when not set, and null when the address has answers filled in (settings.redirectUrl contains {answers.<id>} or {submissionId}): in that case use redirectUrl of the submit response. The submit response always carries the address to use, so prefer it. */
604
- redirectUrl?: string | null;
627
+ redirectUrl: string | null;
605
628
  /** @description ISO 3166-1 alpha-2 country used for a phone question that sets no default country; the server parses national numbers with the same value. */
606
- defaultPhoneCountry?: string | null;
629
+ defaultPhoneCountry: string | null;
607
630
  /** @description The site's IANA time zone. "From today" bounds of date questions are computed in it, on the server too. */
608
- timezone?: string | null;
631
+ timezone: string | null;
609
632
  } & {
610
633
  [key: string]: unknown;
611
634
  };
@@ -674,7 +697,8 @@ export interface components {
674
697
  id: string;
675
698
  label: string;
676
699
  description?: string;
677
- required: unknown;
700
+ /** @constant */
701
+ required: true;
678
702
  /**
679
703
  * @default email
680
704
  * @constant
@@ -1044,8 +1068,9 @@ export interface components {
1044
1068
  type: "statement";
1045
1069
  label: string;
1046
1070
  description?: string;
1047
- required: unknown;
1048
- contactMapping?: unknown;
1071
+ /** @constant */
1072
+ required: false;
1073
+ contactMapping?: never;
1049
1074
  visibleWhen?: {
1050
1075
  /**
1051
1076
  * @default all
@@ -1107,13 +1132,18 @@ export interface components {
1107
1132
  };
1108
1133
  SiteMeta: {
1109
1134
  id: string;
1135
+ /** @description The site's display name (the brand display name, or the site name when none is set). With `locale`, its translation in that locale; untranslated falls back to the primary locale. */
1110
1136
  name: string | null;
1137
+ /** @description The site description. With `locale`, its translation in that locale; untranslated falls back to the primary locale. */
1111
1138
  description: string | null;
1139
+ /** @description The site's primary locale code (same as `primaryLocale`), whatever `locale` was requested */
1112
1140
  locale: string | null;
1113
1141
  /** @description Primary locale code; its pages have no URL prefix */
1114
- primaryLocale?: string | null;
1115
- /** @description Published locales (primary first). Each secondary locale lives under `/{pathPrefix}/`. */
1116
- locales?: components["schemas"]["SiteLocale"][];
1142
+ primaryLocale: string | null;
1143
+ /** @description Live locales (primary first; a single-language site lists only the primary locale). Each secondary locale lives under `/{pathPrefix}/`. */
1144
+ locales: components["schemas"]["SiteLocale"][];
1145
+ /** @description Locale of `name` and `description`: the requested locale when either has a translation in it, otherwise the primary locale */
1146
+ resolvedLocale: string | null;
1117
1147
  timezone: string | null;
1118
1148
  currency: string | null;
1119
1149
  /** @enum {string} */
@@ -1349,10 +1379,13 @@ export interface components {
1349
1379
  };
1350
1380
  Asset: {
1351
1381
  assetId: string;
1382
+ /** @description Where to get the file. For an image this is the image at its original size (width x height), re-encoded by the image edge: replace the last path segment with a size such as w=800,fit=scale-down for a smaller one (imageUrl and srcSet in @kanorio/sdk do it for you). The URL changes when the file is replaced, so look it up on every response instead of storing it. */
1352
1383
  url: string;
1384
+ /** @description Pixel width of the original; url delivers this size. null when unknown. */
1353
1385
  width?: number | null;
1386
+ /** @description Pixel height of the original; url delivers this size. null when unknown. */
1354
1387
  height?: number | null;
1355
- /** @description Alternative text: the alt written where the image is used, otherwise the asset's default alt text set in the media library; null when neither exists. */
1388
+ /** @description Alternative text: the asset's default alt text set in the media library, or the alt written next to the image in rich text and the share image; null when neither exists. With `locale` (another than the primary), the media library alt is that locale's version when it has one, otherwise the primary one. For an image or gallery field, an item's `imageAlt` overrides it where set. */
1356
1389
  alt?: string | null;
1357
1390
  /** @description true when url is the watermarked version of the image (the site has a watermark on and the image is used where it applies). For images uploaded or replaced with a new version after the watermark was turned on, url is a low-resolution placeholder (or empty) until the watermarked version is ready; the original is never returned. */
1358
1391
  watermarked?: boolean;
@@ -1396,20 +1429,33 @@ export interface components {
1396
1429
  mimeType?: string | null;
1397
1430
  fileSize?: number | null;
1398
1431
  kind?: string;
1432
+ /** @description Credit line set on the file in the media library (photographer or rights holder, for example "Jane Doe / Pexels"); filled automatically for stock photos. Show it where the license asks for attribution. null when there is none. */
1433
+ credit?: string | null;
1434
+ /**
1435
+ * Format: uri
1436
+ * @description Where the file came from (the stock photo's page, the original source); link the credit to it. null when there is none.
1437
+ */
1438
+ sourceUrl?: string | null;
1399
1439
  };
1400
1440
  /** @description One collection item. System collections add fields of their own at this level (blog: segments, toc, contentHtml, plaintext); GET /collections lists them in virtualFields. */
1401
1441
  Item: {
1402
1442
  id: string;
1403
1443
  /** @description URL slug in the locale of the response */
1404
1444
  slug: string;
1405
- /** @description Path of this item's page on the site, in the locale of the response (`/blog/hello`, or `/en/blog/hello` for a secondary locale). It is the address Kanorio lists in the sitemap, site search and JSON-LD, so link to it instead of building the URL from the slug. Present for blog posts, for categories, tags and authors whose listing page is served (see `listings` on /site), and for items of a custom collection that has a `pathTemplate` (primary locale only). Absent when the item has no page of its own. */
1445
+ /** @description Path of this item's page on the site, in the locale of the response, with the locale prefix (`/blog/hello`, or `/en/blog/hello-en` for a secondary locale). It is the address Kanorio lists in the sitemap, site search and JSON-LD, so link to it instead of building the URL from the slug. Present for blog posts, for categories, tags and authors whose listing page is served (see `listings` on /site), and for items of a custom collection that has a `pathTemplate` (a secondary locale gets its prefix plus the same template, with that locale's slug). Absent when the item has no page of its own. */
1406
1446
  path?: string;
1407
1447
  publishedAt: string | null;
1408
1448
  updatedAt: string;
1409
1449
  fieldData: {
1410
1450
  [key: string]: unknown;
1411
1451
  };
1412
- /** @description References named in `expand`, keyed by field id */
1452
+ /** @description Alt text written for an image where this item uses it, keyed by field id and then asset id: `imageAlt.cover[fieldData.cover]`, `imageAlt.photos[id]` for each gallery image. Use it instead of `assets[id].alt` when present; otherwise fall back to `assets[id].alt`. Lists only image and gallery fields that have one and that `fieldData` includes. The same text in every locale. */
1453
+ imageAlt: {
1454
+ [key: string]: {
1455
+ [key: string]: string;
1456
+ };
1457
+ };
1458
+ /** @description References named in `expand`, keyed by field id: `{ id, slug, title, fieldData, imageAlt }` (an array for a multi-reference field, null when the target is missing) */
1413
1459
  expanded?: {
1414
1460
  [key: string]: unknown;
1415
1461
  };
@@ -1422,7 +1468,7 @@ export interface components {
1422
1468
  localeSlugs?: {
1423
1469
  [key: string]: string;
1424
1470
  };
1425
- /** @description Multilingual sites, system collections: `path` in every live locale, for hreflang and a language switcher */
1471
+ /** @description Multilingual sites: this item's path in every live locale, keyed by locale code, without the locale prefix (each locale can have its own translated slug), like `localePaths` on pages and products. Present when `path` is. Use it for hreflang, a language switcher and sitemap alternates (`buildAlternates` and `seoMetadata` in @kanorio/sdk add the prefix). */
1426
1472
  localePaths?: {
1427
1473
  [key: string]: string;
1428
1474
  };
@@ -1728,6 +1774,8 @@ export interface operations {
1728
1774
  query?: {
1729
1775
  /** @description Pass `preview=1` with `X-Kanorio-Preview: knr_pv_<token>` to check a preview token before entering preview mode: the token's signature, expiry and site are verified at the edge and an invalid token gets `401`. Site meta has no draft, so the body is the same as without it (`Cache-Control: no-store`). Used by `createPreviewRouteHandler` in `@kanorio/sdk/preview`. */
1730
1776
  preview?: "1";
1777
+ /** @description Locale for `name` and `description` (the translations of the brand display name and the site description). One of the site's live locales (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale, and `resolvedLocale` says which locale was served. `locales` is the same in every locale. */
1778
+ locale?: string;
1731
1779
  };
1732
1780
  header?: never;
1733
1781
  path?: never;
@@ -1783,7 +1831,7 @@ export interface operations {
1783
1831
  delivery_pages_list: {
1784
1832
  parameters: {
1785
1833
  query?: {
1786
- /** @description Locale for page titles and SEO fields. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. On multilingual sites each page carries resolvedLocale and availableLocales. Slugs stay in the primary locale's path space; prefix them with the locale's pathPrefix. */
1834
+ /** @description Locale for page titles and SEO fields. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. On multilingual sites each page carries resolvedLocale and availableLocales. Slugs stay in the primary locale's path space; prefix them with the locale's pathPrefix. */
1787
1835
  locale?: string;
1788
1836
  /** @description Maximum number of items to return, 1-100. Defaults to 20. */
1789
1837
  limit?: number;
@@ -1820,7 +1868,7 @@ export interface operations {
1820
1868
  delivery_page_get: {
1821
1869
  parameters: {
1822
1870
  query?: {
1823
- /** @description Locale for the page title, SEO fields and section text. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. On multilingual sites the page carries resolvedLocale and availableLocales (use them for canonical and hreflang). Slugs and in-content links stay in the primary locale's path space; prefix them with the locale's pathPrefix. */
1871
+ /** @description Locale for the page title, SEO fields and section text. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. On multilingual sites the page carries resolvedLocale and availableLocales (use them for canonical and hreflang). Slugs and in-content links stay in the primary locale's path space; prefix them with the locale's pathPrefix. */
1824
1872
  locale?: string;
1825
1873
  };
1826
1874
  header?: never;
@@ -1854,7 +1902,7 @@ export interface operations {
1854
1902
  delivery_globals_header_get: {
1855
1903
  parameters: {
1856
1904
  query?: {
1857
- /** @description Locale for the header text and the site settings copy (address, hours, copyright, buttons). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. */
1905
+ /** @description Locale for the header text and the site settings copy (address, hours, copyright, buttons). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. */
1858
1906
  locale?: string;
1859
1907
  };
1860
1908
  header?: never;
@@ -1895,7 +1943,7 @@ export interface operations {
1895
1943
  delivery_globals_footer_get: {
1896
1944
  parameters: {
1897
1945
  query?: {
1898
- /** @description Locale for the footer text and the site settings copy (address, hours, copyright, buttons). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. */
1946
+ /** @description Locale for the footer text and the site settings copy (address, hours, copyright, buttons). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. */
1899
1947
  locale?: string;
1900
1948
  };
1901
1949
  header?: never;
@@ -1984,7 +2032,7 @@ export interface operations {
1984
2032
  includeDepth?: 1;
1985
2033
  /** @description Comma-separated blog content formats: markdown, html, plaintext */
1986
2034
  formats?: string;
1987
- /** @description Locale for item fields marked localized; for the blog, blog_categories, blog_tags and authors collections, the post, category, tag and author translations (titles, excerpts, bodies, SEO fields). Expanded references are translated too. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. On multilingual sites each item carries resolvedLocale and availableLocales. */
2035
+ /** @description Locale for item fields marked localized; for the blog, blog_categories, blog_tags and authors collections, the post, category, tag and author translations (titles, excerpts, bodies, SEO fields). Expanded references are translated too. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. On multilingual sites each item carries resolvedLocale and availableLocales. */
1988
2036
  locale?: string;
1989
2037
  /** @description Pass `preview=1` with `X-Kanorio-Preview: knr_pv_<token>` (or a server-held PAT with `collections:view`) to read unpublished draft `fieldData` (`Cache-Control: no-store`). */
1990
2038
  preview?: "1";
@@ -2022,7 +2070,7 @@ export interface operations {
2022
2070
  preview?: "1";
2023
2071
  /** @description Reference include depth. Only 1 is accepted in v1. */
2024
2072
  includeDepth?: 1;
2025
- /** @description Locale for the item, the same as the list endpoint (system collections use the post, category, tag and author translations; expanded references are translated too). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. On multilingual sites the item carries resolvedLocale and availableLocales. */
2073
+ /** @description Locale for the item, the same as the list endpoint (system collections use the post, category, tag and author translations; expanded references are translated too). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. On multilingual sites the item carries resolvedLocale and availableLocales. */
2026
2074
  locale?: string;
2027
2075
  };
2028
2076
  header?: never;
@@ -2055,6 +2103,46 @@ export interface operations {
2055
2103
  503: components["responses"]["Error503"];
2056
2104
  };
2057
2105
  };
2106
+ delivery_collection_singleton: {
2107
+ parameters: {
2108
+ query?: {
2109
+ fields?: string;
2110
+ expand?: string;
2111
+ preview?: "1";
2112
+ /** @description Reference include depth. Only 1 is accepted in v1. */
2113
+ includeDepth?: 1;
2114
+ /** @description Locale for the item, the same as GET /collections/{key}/items/{slug}. Omit it for the primary locale. */
2115
+ locale?: string;
2116
+ };
2117
+ header?: never;
2118
+ path: {
2119
+ key: string;
2120
+ };
2121
+ cookie?: never;
2122
+ };
2123
+ requestBody?: never;
2124
+ responses: {
2125
+ /** @description OK */
2126
+ 200: {
2127
+ headers: {
2128
+ [name: string]: unknown;
2129
+ };
2130
+ content: {
2131
+ "application/json": {
2132
+ item: components["schemas"]["Item"];
2133
+ assets: {
2134
+ [key: string]: components["schemas"]["Asset"];
2135
+ };
2136
+ access?: components["schemas"]["AccessSummary"];
2137
+ };
2138
+ };
2139
+ };
2140
+ 400: components["responses"]["Error400"];
2141
+ 404: components["responses"]["Error404"];
2142
+ 429: components["responses"]["Error429"];
2143
+ 503: components["responses"]["Error503"];
2144
+ };
2145
+ };
2058
2146
  delivery_blog_feed_rss: {
2059
2147
  parameters: {
2060
2148
  query?: {
@@ -2403,8 +2491,10 @@ export interface operations {
2403
2491
  delivery_form_get: {
2404
2492
  parameters: {
2405
2493
  query?: {
2406
- /** @description Locale for the form name, description, question labels, hints, choice labels, submit button and success message. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. Field and choice ids are locale-independent, so submissions are unaffected. */
2494
+ /** @description Locale for the form name, description, question labels, hints, choice labels, submit button and success message. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token (or a server-held PAT with `collections:view`) they are accepted and their draft translations are returned. A preview request for a locale that is not live is checked for its token first: without one it gets 401, whether or not the site has that locale. Untranslated fields fall back to the primary locale. Field and choice ids are locale-independent, so submissions are unaffected. */
2407
2495
  locale?: string;
2496
+ /** @description Pass `preview=1` with `X-Kanorio-Preview: knr_pv_<token>` (or a server-held PAT with `collections:view`) to read the form in a locale that is not live yet, with its draft translations (`Cache-Control: no-store`). Forms have no drafts of their own, so only such a locale makes a preview request: without `locale`, or with a live one, the response is the same cached one as without `preview` and no token is checked. */
2497
+ preview?: "1";
2408
2498
  };
2409
2499
  header?: never;
2410
2500
  path: {
@@ -2662,8 +2752,11 @@ export interface operations {
2662
2752
  consent?: "checked" | "submit_statement";
2663
2753
  /** @description Id of the consent text the visitor saw (consentTextId from GET /forms/{id}, whose consentText is the text to show). Required for consent to be recorded: without it, or when it no longer matches the form's current text, the submission is stored without consent. */
2664
2754
  consentTextId?: string;
2755
+ /** @description The visitor's language, such as the browser's (navigator.language). Kept on the submission and the contact; it does not decide the redirect. */
2665
2756
  locale?: string;
2666
- /** @description Path of the page the form was on, for the submission record. */
2757
+ /** @description The site locale of the page the form was on (a code from /site locales[] or its URL prefix). A redirect to a path on the site gets this locale's URL prefix. Without it, or when it is not a live locale, the locale is read from pagePath. */
2758
+ pageLocale?: string;
2759
+ /** @description Path of the page the form was on, for the submission record. Also decides the redirect's locale prefix when pageLocale is not sent. */
2667
2760
  pagePath?: string;
2668
2761
  /** @description Honeypot. Send an empty string; any value marks the request as automated. */
2669
2762
  _hp?: string;
@@ -2697,7 +2790,7 @@ export interface operations {
2697
2790
  state?: "closed" | "not_open" | "full";
2698
2791
  /** @description Id of this submission. Absent when state is present. */
2699
2792
  submissionId?: string;
2700
- /** @description Where to send the visitor now, when the form has a redirect after submit: a path on the site (with the locale prefix of the page the form was on) or an https URL, which can be on another site. Answers and the submission id are already filled in and percent-encoded. Absent when the form has no redirect. */
2793
+ /** @description Where to send the visitor now, when the form has a redirect after submit: a path on the site (with the URL prefix of pageLocale, or of the page the form was on, read from pagePath, when pageLocale was not sent) or an https URL, which can be on another site. Answers and the submission id are already filled in and percent-encoded. Absent when the form has no redirect. */
2701
2794
  redirectUrl?: string;
2702
2795
  };
2703
2796
  };