@kanorio/sdk 1.2.0 → 1.4.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 +36 -6
- package/dist/edge.d.ts +4 -3
- package/dist/edge.js +20 -12
- package/dist/forms.d.ts +25 -2
- package/dist/forms.js +20 -7
- package/dist/generated/delivery.d.ts +125 -28
- package/dist/generated/management.d.ts +1361 -90
- package/dist/http.d.ts +2 -2
- package/dist/http.js +2 -2
- package/dist/image.d.ts +48 -18
- package/dist/image.js +74 -16
- package/dist/index.d.ts +3 -3
- package/dist/index.js +1 -1
- package/dist/next.d.ts +8 -2
- package/dist/next.js +16 -2
- package/dist/paginate.d.ts +23 -0
- package/dist/paginate.js +28 -2
- package/dist/seo.d.ts +31 -3
- package/dist/seo.js +41 -8
- package/dist/server-key.d.ts +13 -3
- package/dist/server-key.js +24 -5
- package/dist/shared/api/delivery/cache-tags.d.ts +2 -2
- package/dist/shared/api/delivery/cache-tags.js +3 -1
- package/dist/shared/api/server-key.d.ts +8 -0
- package/dist/shared/api/server-key.js +8 -0
- package/dist/shared/types/forms-logic.js +7 -2
- package/dist/warn-once.d.ts +3 -0
- package/dist/warn-once.js +16 -0
- package/package.json +1 -1
package/dist/server-key.d.ts
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
*
|
|
4
4
|
* A server key (`knr_sk_…`, created under Site settings > Developer with the purpose "Website server") lets
|
|
5
5
|
* **your server** call the visitor-facing write endpoints on behalf of a visitor: submit a form, exchange a
|
|
6
|
-
* customer sign-in code, report an AI crawler hit.
|
|
7
|
-
*
|
|
6
|
+
* customer sign-in code, report an AI crawler hit. With the key, Kanorio trusts the visitor IP your server
|
|
7
|
+
* relays, so each visitor gets their own rate limit and spam reputation. Without it, every request from your
|
|
8
|
+
* server counts as one visitor (your server's IP), and crawler reports are refused (`SERVER_KEY_REQUIRED`).
|
|
8
9
|
*
|
|
9
10
|
* Rules enforced here:
|
|
10
11
|
* - Never in a browser. The key is a secret; passing it in browser code throws.
|
|
@@ -29,6 +30,12 @@ export interface ServerKeyOptions {
|
|
|
29
30
|
*/
|
|
30
31
|
visitorIp?: VisitorIpSource;
|
|
31
32
|
}
|
|
33
|
+
/**
|
|
34
|
+
* True when this code is not running on the visitor's device (a browser page, a web worker or a React Native
|
|
35
|
+
* app), so it is most likely your server, an edge function or a script. Only used to decide whether to warn
|
|
36
|
+
* about a missing server key; it never changes what is sent.
|
|
37
|
+
*/
|
|
38
|
+
export declare function runsOnServer(): boolean;
|
|
32
39
|
/**
|
|
33
40
|
* Headers and fetch options for a request that carries a server key. Returns `null` when no key is set.
|
|
34
41
|
* Throws when called in a browser or against a non-HTTPS URL.
|
|
@@ -67,5 +74,8 @@ export declare function isEdgeChallenge(response: {
|
|
|
67
74
|
};
|
|
68
75
|
}): boolean;
|
|
69
76
|
export declare const EDGE_CHALLENGE_CODE = "EDGE_CHALLENGE";
|
|
70
|
-
/**
|
|
77
|
+
/**
|
|
78
|
+
* What to tell the developer (or their AI tool) when a request was challenged at the edge. API requests are not
|
|
79
|
+
* normally challenged, so this only happens when something at the edge is off; the message says what to check.
|
|
80
|
+
*/
|
|
71
81
|
export declare function edgeChallengeMessage(hasServerKey: boolean): string;
|
package/dist/server-key.js
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
*
|
|
4
4
|
* A server key (`knr_sk_…`, created under Site settings > Developer with the purpose "Website server") lets
|
|
5
5
|
* **your server** call the visitor-facing write endpoints on behalf of a visitor: submit a form, exchange a
|
|
6
|
-
* customer sign-in code, report an AI crawler hit.
|
|
7
|
-
*
|
|
6
|
+
* customer sign-in code, report an AI crawler hit. With the key, Kanorio trusts the visitor IP your server
|
|
7
|
+
* relays, so each visitor gets their own rate limit and spam reputation. Without it, every request from your
|
|
8
|
+
* server counts as one visitor (your server's IP), and crawler reports are refused (`SERVER_KEY_REQUIRED`).
|
|
8
9
|
*
|
|
9
10
|
* Rules enforced here:
|
|
10
11
|
* - Never in a browser. The key is a secret; passing it in browser code throws.
|
|
@@ -18,6 +19,21 @@ const LOCAL_HOST_RE = /^(localhost|127\.0\.0\.1|\[::1\])$/i;
|
|
|
18
19
|
function isBrowser() {
|
|
19
20
|
return typeof window !== "undefined" && typeof document !== "undefined";
|
|
20
21
|
}
|
|
22
|
+
/**
|
|
23
|
+
* True when this code is not running on the visitor's device (a browser page, a web worker or a React Native
|
|
24
|
+
* app), so it is most likely your server, an edge function or a script. Only used to decide whether to warn
|
|
25
|
+
* about a missing server key; it never changes what is sent.
|
|
26
|
+
*/
|
|
27
|
+
export function runsOnServer() {
|
|
28
|
+
if (isBrowser())
|
|
29
|
+
return false;
|
|
30
|
+
const scope = globalThis;
|
|
31
|
+
if (scope.navigator?.product === "ReactNative")
|
|
32
|
+
return false;
|
|
33
|
+
if (typeof scope.importScripts === "function")
|
|
34
|
+
return false;
|
|
35
|
+
return true;
|
|
36
|
+
}
|
|
21
37
|
/**
|
|
22
38
|
* Headers and fetch options for a request that carries a server key. Returns `null` when no key is set.
|
|
23
39
|
* Throws when called in a browser or against a non-HTTPS URL.
|
|
@@ -92,12 +108,15 @@ export function isEdgeChallenge(response) {
|
|
|
92
108
|
return response.headers.get("cf-mitigated") === "challenge";
|
|
93
109
|
}
|
|
94
110
|
export const EDGE_CHALLENGE_CODE = "EDGE_CHALLENGE";
|
|
95
|
-
/**
|
|
111
|
+
/**
|
|
112
|
+
* What to tell the developer (or their AI tool) when a request was challenged at the edge. API requests are not
|
|
113
|
+
* normally challenged, so this only happens when something at the edge is off; the message says what to check.
|
|
114
|
+
*/
|
|
96
115
|
export function edgeChallengeMessage(hasServerKey) {
|
|
97
116
|
if (isBrowser()) {
|
|
98
|
-
return "Kanorio's edge
|
|
117
|
+
return "Kanorio's edge answered this request with a security check page, so it never reached the API. API requests are not normally checked this way: retry in a moment, and contact Kanorio support if it keeps happening.";
|
|
99
118
|
}
|
|
100
119
|
return hasServerKey
|
|
101
120
|
? "Kanorio's edge challenged this server-side request even though a server key was sent. Check that the key is a server key (starts with knr_sk_, purpose \"Website server\") and that it is sent to the site's own hostname."
|
|
102
|
-
: "Kanorio's edge challenged this server-side request
|
|
121
|
+
: "Kanorio's edge challenged this server-side request, so it never reached the API. Sending a server key avoids this: create one under Site settings > Developer (purpose \"Website server\"), store it as KANORIO_SERVER_KEY, and pass `serverKey` to the client. Do not paste the key into chat or commit it.";
|
|
103
122
|
}
|
|
@@ -101,7 +101,7 @@ export declare const responseCacheTags: {
|
|
|
101
101
|
readonly reviews: (siteId: string, productId: string | null) => string[];
|
|
102
102
|
};
|
|
103
103
|
/** Translatable record types (the same strings as Kanorio's translatable-fields registry; not imported here, so the SDK's copy stands alone) */
|
|
104
|
-
export type TranslationCacheScope = "page" | "global_sections" | "site_settings" | "store_settings" | "post" | "post_category" | "post_tag" | "author" | "product" | "product_option" | "pricing_tier" | "product_category" | "deliverable" | "deliverable_unit" | "form" | "top_bar_banner" | "modal_announcement" | "floating_widget" | "collection_item";
|
|
104
|
+
export type TranslationCacheScope = "page" | "global_sections" | "site_settings" | "store_settings" | "post" | "post_category" | "post_tag" | "author" | "product" | "product_option" | "pricing_tier" | "product_category" | "deliverable" | "deliverable_unit" | "form" | "top_bar_banner" | "modal_announcement" | "floating_widget" | "collection_item" | "media_asset";
|
|
105
105
|
export interface TranslationEventInput {
|
|
106
106
|
entityType: TranslationCacheScope;
|
|
107
107
|
entityId: string;
|
|
@@ -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
|
-
|
|
197
|
+
// The source question is itself hidden: treated as unanswered. Only the answers' own keys count: an id can be a built-in
|
|
198
|
+
// object property name (`constructor`), and reading it from an object without that key returns the prototype's function
|
|
199
|
+
const raw = condition.kind === "hidden" || visible.has(condition.ref) ? ownAnswer(answers, condition.ref) : null;
|
|
195
200
|
const result = evaluateCondition(condition, sourceType, raw);
|
|
196
201
|
if (result === null)
|
|
197
202
|
undecidable = true;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Console warnings that should appear once per process. A flag kept on a helpers object is not enough: the usual server pattern
|
|
3
|
+
* creates the helpers inside each request (the visitor IP differs per request), so a per-instance flag would print on every call.
|
|
4
|
+
* Internal: not part of the package's public surface.
|
|
5
|
+
*/
|
|
6
|
+
const printed = new Set();
|
|
7
|
+
export function warnOnce(key, message) {
|
|
8
|
+
if (printed.has(key))
|
|
9
|
+
return;
|
|
10
|
+
printed.add(key);
|
|
11
|
+
console.warn(message);
|
|
12
|
+
}
|
|
13
|
+
/** For tests: forget which warnings were printed */
|
|
14
|
+
export function resetWarnOnce() {
|
|
15
|
+
printed.clear();
|
|
16
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kanorio/sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.4.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,
|