@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.
@@ -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;
@@ -134,7 +134,7 @@ export declare const eventCacheTags: {
134
134
  readonly formChanged: (formId: string) => string[];
135
135
  /** The locale set changed (enabled, disabled, removed, prefix, order, primary): the language switcher and hreflang are on every page */
136
136
  readonly localeChanged: (siteId: string) => string[];
137
- /** 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 */
138
138
  readonly translationJobCompleted: (locale: string) => string[];
139
139
  /**
140
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.
@@ -164,7 +164,7 @@ export const eventCacheTags = {
164
164
  formChanged: (formId) => [cacheTag.form(formId)],
165
165
  /** The locale set changed (enabled, disabled, removed, prefix, order, primary): the language switcher and hreflang are on every page */
166
166
  localeChanged: (siteId) => [cacheTag.site(siteId)],
167
- /** 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 */
168
168
  translationJobCompleted: (locale) => [cacheTag.locale(locale)],
169
169
  /**
170
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.
@@ -181,6 +181,8 @@ export const eventCacheTags = {
181
181
  case "top_bar_banner":
182
182
  case "modal_announcement":
183
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":
184
186
  return [cacheTag.locale(input.locale)];
185
187
  case "post":
186
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.2.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,