@kanorio/sdk 1.0.0 → 1.1.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 +2 -2
- package/dist/customer-oauth.d.ts +21 -21
- package/dist/customer-oauth.js +12 -12
- package/dist/customer.d.ts +22 -22
- package/dist/customer.js +20 -11
- package/dist/delivery.d.ts +9 -9
- package/dist/delivery.js +6 -6
- package/dist/edge.d.ts +25 -21
- package/dist/edge.js +19 -19
- package/dist/forms.d.ts +13 -13
- package/dist/forms.js +13 -13
- package/dist/generated/delivery.d.ts +35 -7
- package/dist/generated/management.d.ts +111 -26
- package/dist/http.d.ts +13 -13
- package/dist/http.js +8 -8
- package/dist/index.js +2 -2
- package/dist/locales.d.ts +22 -22
- package/dist/locales.js +12 -12
- package/dist/management.d.ts +5 -5
- package/dist/management.js +3 -3
- package/dist/paginate.d.ts +3 -3
- package/dist/paginate.js +3 -3
- package/dist/preview.d.ts +13 -13
- package/dist/preview.js +11 -11
- package/dist/protection.d.ts +18 -18
- package/dist/protection.js +11 -11
- package/dist/revalidate.d.ts +22 -22
- package/dist/revalidate.js +14 -14
- package/dist/seo.d.ts +20 -20
- package/dist/seo.js +20 -20
- package/dist/server-key.d.ts +2 -2
- package/dist/server-key.js +2 -2
- package/dist/shared/api/delivery/cache-tags.d.ts +39 -39
- package/dist/shared/api/delivery/cache-tags.js +34 -34
- package/dist/shared/api/server-key.d.ts +32 -28
- package/dist/shared/api/server-key.js +41 -33
- package/dist/shared/business-registry/attribution.d.ts +5 -5
- package/dist/shared/business-registry/attribution.js +4 -4
- package/dist/shared/business-registry/define.d.ts +1 -1
- package/dist/shared/business-registry/define.js +1 -1
- package/dist/shared/business-registry/formats/eu-vat.js +4 -4
- package/dist/shared/business-registry/formats/hk-br.d.ts +2 -2
- package/dist/shared/business-registry/formats/hk-br.js +4 -4
- package/dist/shared/business-registry/formats/jp-trn.d.ts +3 -3
- package/dist/shared/business-registry/formats/jp-trn.js +4 -4
- package/dist/shared/business-registry/formats/kr-brn.d.ts +2 -2
- package/dist/shared/business-registry/formats/kr-brn.js +3 -3
- package/dist/shared/business-registry/formats/my.d.ts +3 -3
- package/dist/shared/business-registry/formats/my.js +4 -4
- package/dist/shared/business-registry/formats/sg-uen.js +4 -4
- package/dist/shared/business-registry/formats/tw-vat.d.ts +5 -5
- package/dist/shared/business-registry/formats/tw-vat.js +6 -6
- package/dist/shared/business-registry/index.js +1 -1
- package/dist/shared/business-registry/lookup-wire.d.ts +9 -9
- package/dist/shared/business-registry/lookup-wire.js +4 -4
- package/dist/shared/business-registry/normalize.d.ts +3 -3
- package/dist/shared/business-registry/normalize.js +4 -4
- package/dist/shared/business-registry/registry.d.ts +9 -9
- package/dist/shared/business-registry/registry.js +13 -13
- package/dist/shared/business-registry/types.d.ts +20 -20
- package/dist/shared/business-registry/types.js +6 -6
- package/dist/shared/localization/locale-path.d.ts +18 -18
- package/dist/shared/localization/locale-path.js +18 -18
- package/dist/shared/localization/request-locale.d.ts +16 -16
- package/dist/shared/localization/request-locale.js +13 -13
- package/dist/shared/seo/alternates.d.ts +26 -26
- package/dist/shared/seo/alternates.js +18 -18
- package/dist/shared/types/forms-logic.d.ts +28 -28
- package/dist/shared/types/forms-logic.js +27 -27
- package/dist/shared/types/number-input.d.ts +2 -2
- package/dist/shared/types/number-input.js +3 -3
- package/dist/shared/utils/redirect-matching.d.ts +33 -24
- package/dist/shared/utils/redirect-matching.js +73 -40
- package/dist/typed.d.ts +5 -5
- package/dist/typed.js +3 -3
- package/package.json +10 -10
|
@@ -1,43 +1,47 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* The shared contract of server keys: Kanorio's server, its edge worker and the SDK read the same file.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* A server key is a service account key issued for a website's own server (`knr_sk_`). The server of a self-hosted front end sends it when writing on behalf of a visitor
|
|
5
|
+
* (submitting a form, customer sign-in, reporting crawlers), and the edge trusts the visitor IP it states only after verifying the key. It cannot open the Management API.
|
|
6
|
+
* See the Authentication page of the developer documentation.
|
|
7
7
|
*/
|
|
8
|
-
/**
|
|
8
|
+
/** The header the server sends the key in */
|
|
9
9
|
export declare const SERVER_KEY_HEADER = "X-Kanorio-Server-Key";
|
|
10
|
-
/**
|
|
10
|
+
/** The visitor IP relayed by the server; trusted only when the key has been verified */
|
|
11
11
|
export declare const SERVER_KEY_VISITOR_IP_HEADER = "X-Kanorio-Visitor-IP";
|
|
12
12
|
/**
|
|
13
|
-
*
|
|
14
|
-
*
|
|
13
|
+
* Edge worker to server: this request carries a verified server key (the value is the key id). The server trusts the relayed visitor IP in
|
|
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
17
|
/**
|
|
18
|
-
*
|
|
19
|
-
*
|
|
18
|
+
* 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
|
+
* 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`.
|
|
20
20
|
*/
|
|
21
21
|
export declare const STOREFRONT_SERVER_SCOPE = "storefront:server";
|
|
22
|
-
|
|
22
|
+
/**
|
|
23
|
+
* The server key's own prefix: one prefix per credential type (as GitHub and Stripe do), so whoever holds a key, and leak scanners, can tell from the prefix
|
|
24
|
+
* that it cannot open the Management API. Service account keys for managing a site start with `knr_sa_`.
|
|
25
|
+
*/
|
|
26
|
+
export declare const SERVER_KEY_PREFIX = "knr_sk_";
|
|
23
27
|
export declare function isServerKeyFormat(raw: string): boolean;
|
|
24
28
|
/**
|
|
25
|
-
*
|
|
26
|
-
*
|
|
29
|
+
* A fake key for outside-in probes (well-formed and never valid): monitoring POSTs with it to a site every round to confirm that fake keys are refused.
|
|
30
|
+
* The edge recognizes it, verifies and refuses it as usual, but does not count it toward the site's failed-server-key signal (it is Kanorio's own probe, not someone guessing).
|
|
27
31
|
*/
|
|
28
32
|
export declare const PROBE_FAKE_SERVER_KEY: string;
|
|
29
|
-
/**
|
|
33
|
+
/** A service account's purpose: decided by whether its grant carries `STOREFRONT_SERVER_SCOPE`, and fixed after creation */
|
|
30
34
|
export type ServiceAccountPurpose = "management" | "storefront_server";
|
|
31
35
|
export declare function purposeOfGrant(permissions: readonly string[]): ServiceAccountPurpose;
|
|
32
|
-
/**
|
|
36
|
+
/** Conventional environment variable name (used by the dashboard's one-time display, the CLI's `--write-env` and the documentation) */
|
|
33
37
|
export declare const SERVER_KEY_ENV_NAME = "KANORIO_SERVER_KEY";
|
|
34
|
-
/**
|
|
38
|
+
/** Response of the edge worker's verification call to the server */
|
|
35
39
|
export interface ServerKeyVerifyResponse {
|
|
36
40
|
valid: boolean;
|
|
37
41
|
tokenId?: string;
|
|
38
|
-
/** ISO
|
|
42
|
+
/** ISO time; null means it does not expire */
|
|
39
43
|
expiresAt?: string | null;
|
|
40
|
-
/**
|
|
44
|
+
/** Source restrictions (an empty array means none); matched against the actual connecting IP and ASN */
|
|
41
45
|
allowedCidrs?: string[];
|
|
42
46
|
allowedAsns?: number[];
|
|
43
47
|
}
|
|
@@ -45,26 +49,26 @@ export interface ParsedIp {
|
|
|
45
49
|
version: 4 | 6;
|
|
46
50
|
bytes: number[];
|
|
47
51
|
}
|
|
48
|
-
/**
|
|
52
|
+
/** Parses an IP; `::ffff:a.b.c.d` is treated as IPv4. null when invalid */
|
|
49
53
|
export declare function parseIp(raw: string): ParsedIp | null;
|
|
50
54
|
export declare function isPublicIp(ip: ParsedIp): boolean;
|
|
51
55
|
/**
|
|
52
|
-
*
|
|
53
|
-
*
|
|
56
|
+
* The visitor IP relayed by the server: it must be a valid public address, otherwise it counts as absent (null).
|
|
57
|
+
* A misconfigured reverse proxy relays internal addresses such as 10.x; accepting them would put every visitor of the site in one rate-limit bucket.
|
|
54
58
|
*/
|
|
55
59
|
export declare function normalizeVisitorIp(raw: string | null | undefined): string | null;
|
|
56
|
-
/**
|
|
60
|
+
/** Rate-limit bucket key: the whole address for IPv4, the /64 for IPv6 (one client usually gets a whole /64) */
|
|
57
61
|
export declare function rateLimitKeyForIp(ip: string): string;
|
|
58
62
|
export interface ParsedCidr {
|
|
59
63
|
version: 4 | 6;
|
|
60
64
|
bytes: number[];
|
|
61
65
|
bits: number;
|
|
62
|
-
/**
|
|
66
|
+
/** Normalized form (network address and prefix length) */
|
|
63
67
|
text: string;
|
|
64
68
|
}
|
|
65
69
|
/**
|
|
66
|
-
*
|
|
67
|
-
*
|
|
70
|
+
* Parses one IP or CIDR of a source restriction. A single IP is a /32 (/128 for IPv6).
|
|
71
|
+
* Rejected: malformed input, non-public ranges and prefixes that are too wide.
|
|
68
72
|
*/
|
|
69
73
|
export declare function parseAllowedCidr(raw: string): ParsedCidr | null;
|
|
70
74
|
export declare function ipInCidr(ip: string, cidr: ParsedCidr): boolean;
|
|
@@ -76,9 +80,9 @@ export interface SourcePolicy {
|
|
|
76
80
|
}
|
|
77
81
|
export declare function hasSourcePolicy(policy: SourcePolicy): boolean;
|
|
78
82
|
/**
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
83
|
+
* Source restriction check (like Stripe's access policies): whichever kind of condition is set must match; when both are set, both must match.
|
|
84
|
+
* Matched against the actual connecting IP and ASN from Cloudflare, not the visitor IP relayed by the server.
|
|
85
|
+
* With an ASN condition but no ASN available (local development, or the edge did not send it), the check fails.
|
|
82
86
|
*/
|
|
83
87
|
export declare function isSourceAllowed(policy: SourcePolicy, source: {
|
|
84
88
|
ip: string | null;
|
|
@@ -1,42 +1,50 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
3
|
+
* The shared contract of server keys: Kanorio's server, its edge worker and the SDK read the same file.
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* A server key is a service account key issued for a website's own server (`knr_sk_`). The server of a self-hosted front end sends it when writing on behalf of a visitor
|
|
6
|
+
* (submitting a form, customer sign-in, reporting crawlers), and the edge trusts the visitor IP it states only after verifying the key. It cannot open the Management API.
|
|
7
|
+
* See the Authentication page of the developer documentation.
|
|
8
8
|
*/
|
|
9
|
-
/**
|
|
9
|
+
/** The header the server sends the key in */
|
|
10
10
|
export const SERVER_KEY_HEADER = "X-Kanorio-Server-Key";
|
|
11
|
-
/**
|
|
11
|
+
/** The visitor IP relayed by the server; trusted only when the key has been verified */
|
|
12
12
|
export const SERVER_KEY_VISITOR_IP_HEADER = "X-Kanorio-Visitor-IP";
|
|
13
13
|
/**
|
|
14
|
-
*
|
|
15
|
-
*
|
|
14
|
+
* Edge worker to server: this request carries a verified server key (the value is the key id). The server trusts the relayed visitor IP in
|
|
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
18
|
/**
|
|
19
|
-
*
|
|
20
|
-
*
|
|
19
|
+
* 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
|
+
* 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`.
|
|
21
21
|
*/
|
|
22
22
|
export const STOREFRONT_SERVER_SCOPE = "storefront:server";
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
23
|
+
/**
|
|
24
|
+
* The server key's own prefix: one prefix per credential type (as GitHub and Stripe do), so whoever holds a key, and leak scanners, can tell from the prefix
|
|
25
|
+
* that it cannot open the Management API. Service account keys for managing a site start with `knr_sa_`.
|
|
26
|
+
*/
|
|
27
|
+
export const SERVER_KEY_PREFIX = "knr_sk_";
|
|
28
|
+
/**
|
|
29
|
+
* The prefix followed by 43 base64url characters (32 bytes). A malformed key is rejected without a lookup.
|
|
30
|
+
* Server keys have this one prefix only.
|
|
31
|
+
* Keys issued earlier with `knr_sa_` are not accepted and must be created again.
|
|
32
|
+
*/
|
|
33
|
+
const SERVER_KEY_PATTERN = /^knr_sk_[A-Za-z0-9_-]{43}$/;
|
|
26
34
|
export function isServerKeyFormat(raw) {
|
|
27
35
|
return SERVER_KEY_PATTERN.test(raw);
|
|
28
36
|
}
|
|
29
37
|
/**
|
|
30
|
-
*
|
|
31
|
-
*
|
|
38
|
+
* A fake key for outside-in probes (well-formed and never valid): monitoring POSTs with it to a site every round to confirm that fake keys are refused.
|
|
39
|
+
* The edge recognizes it, verifies and refuses it as usual, but does not count it toward the site's failed-server-key signal (it is Kanorio's own probe, not someone guessing).
|
|
32
40
|
*/
|
|
33
41
|
export const PROBE_FAKE_SERVER_KEY = `${SERVER_KEY_PREFIX}${"0".repeat(43)}`;
|
|
34
42
|
export function purposeOfGrant(permissions) {
|
|
35
43
|
return permissions.includes(STOREFRONT_SERVER_SCOPE) ? "storefront_server" : "management";
|
|
36
44
|
}
|
|
37
|
-
/**
|
|
45
|
+
/** Conventional environment variable name (used by the dashboard's one-time display, the CLI's `--write-env` and the documentation) */
|
|
38
46
|
export const SERVER_KEY_ENV_NAME = "KANORIO_SERVER_KEY";
|
|
39
|
-
//
|
|
47
|
+
// --- IP utilities (shared by the edge worker and the server; no node:net dependency, so they run on Workers) ---
|
|
40
48
|
function parseIpv4(value) {
|
|
41
49
|
const parts = value.split(".");
|
|
42
50
|
if (parts.length !== 4)
|
|
@@ -52,7 +60,7 @@ function parseIpv4(value) {
|
|
|
52
60
|
}
|
|
53
61
|
return out;
|
|
54
62
|
}
|
|
55
|
-
/** IPv6
|
|
63
|
+
/** IPv6 to 16 bytes; supports `::` compression and a trailing IPv4 (`::ffff:1.2.3.4`). Zone ids are not accepted */
|
|
56
64
|
function parseIpv6(value) {
|
|
57
65
|
if (!value.includes(":") || value.includes("%"))
|
|
58
66
|
return null;
|
|
@@ -94,7 +102,7 @@ function parseIpv6(value) {
|
|
|
94
102
|
bytes.splice(12, 4, ...tailV4);
|
|
95
103
|
return bytes;
|
|
96
104
|
}
|
|
97
|
-
/**
|
|
105
|
+
/** Parses an IP; `::ffff:a.b.c.d` is treated as IPv4. null when invalid */
|
|
98
106
|
export function parseIp(raw) {
|
|
99
107
|
const value = raw.trim();
|
|
100
108
|
if (!value || value.length > 45)
|
|
@@ -121,7 +129,7 @@ function inPrefix(bytes, prefix, bits) {
|
|
|
121
129
|
const mask = (0xff << (8 - rest)) & 0xff;
|
|
122
130
|
return ((bytes[full] ?? 0) & mask) === ((prefix[full] ?? 0) & mask);
|
|
123
131
|
}
|
|
124
|
-
/**
|
|
132
|
+
/** Addresses not routable on the public internet: private, loopback, link-local, CGNAT, documentation, multicast and reserved ranges */
|
|
125
133
|
const NON_PUBLIC_V4 = [
|
|
126
134
|
[[0, 0, 0, 0], 8],
|
|
127
135
|
[[10, 0, 0, 0], 8],
|
|
@@ -138,15 +146,15 @@ const NON_PUBLIC_V4 = [
|
|
|
138
146
|
[[224, 0, 0, 0], 3],
|
|
139
147
|
];
|
|
140
148
|
const NON_PUBLIC_V6 = [
|
|
141
|
-
// ::/127
|
|
149
|
+
// ::/127 (unspecified and loopback)
|
|
142
150
|
[[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 127],
|
|
143
151
|
// fc00::/7 unique local
|
|
144
152
|
[[0xfc, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 7],
|
|
145
153
|
// fe80::/10 link-local
|
|
146
154
|
[[0xfe, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 10],
|
|
147
|
-
// ff00::/8
|
|
155
|
+
// ff00::/8 multicast
|
|
148
156
|
[[0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 8],
|
|
149
|
-
// 2001:db8::/32
|
|
157
|
+
// 2001:db8::/32 documentation
|
|
150
158
|
[[0x20, 0x01, 0x0d, 0xb8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 32],
|
|
151
159
|
];
|
|
152
160
|
export function isPublicIp(ip) {
|
|
@@ -162,8 +170,8 @@ function formatIp(ip) {
|
|
|
162
170
|
return groups.join(":");
|
|
163
171
|
}
|
|
164
172
|
/**
|
|
165
|
-
*
|
|
166
|
-
*
|
|
173
|
+
* The visitor IP relayed by the server: it must be a valid public address, otherwise it counts as absent (null).
|
|
174
|
+
* A misconfigured reverse proxy relays internal addresses such as 10.x; accepting them would put every visitor of the site in one rate-limit bucket.
|
|
167
175
|
*/
|
|
168
176
|
export function normalizeVisitorIp(raw) {
|
|
169
177
|
if (!raw)
|
|
@@ -173,7 +181,7 @@ export function normalizeVisitorIp(raw) {
|
|
|
173
181
|
return null;
|
|
174
182
|
return formatIp(parsed);
|
|
175
183
|
}
|
|
176
|
-
/**
|
|
184
|
+
/** Rate-limit bucket key: the whole address for IPv4, the /64 for IPv6 (one client usually gets a whole /64) */
|
|
177
185
|
export function rateLimitKeyForIp(ip) {
|
|
178
186
|
const parsed = parseIp(ip);
|
|
179
187
|
if (!parsed)
|
|
@@ -182,11 +190,11 @@ export function rateLimitKeyForIp(ip) {
|
|
|
182
190
|
return formatIp(parsed);
|
|
183
191
|
return `${formatIp({ version: 6, bytes: [...parsed.bytes.slice(0, 8), 0, 0, 0, 0, 0, 0, 0, 0] })}/64`;
|
|
184
192
|
}
|
|
185
|
-
/**
|
|
193
|
+
/** The widest ranges accepted are IPv4 /8 and IPv6 /16: anything wider is no restriction at all */
|
|
186
194
|
const MIN_PREFIX_BITS = { 4: 8, 6: 16 };
|
|
187
195
|
/**
|
|
188
|
-
*
|
|
189
|
-
*
|
|
196
|
+
* Parses one IP or CIDR of a source restriction. A single IP is a /32 (/128 for IPv6).
|
|
197
|
+
* Rejected: malformed input, non-public ranges and prefixes that are too wide.
|
|
190
198
|
*/
|
|
191
199
|
export function parseAllowedCidr(raw) {
|
|
192
200
|
const value = raw.trim();
|
|
@@ -228,9 +236,9 @@ export function hasSourcePolicy(policy) {
|
|
|
228
236
|
return policy.allowedCidrs.length > 0 || policy.allowedAsns.length > 0;
|
|
229
237
|
}
|
|
230
238
|
/**
|
|
231
|
-
*
|
|
232
|
-
*
|
|
233
|
-
*
|
|
239
|
+
* Source restriction check (like Stripe's access policies): whichever kind of condition is set must match; when both are set, both must match.
|
|
240
|
+
* Matched against the actual connecting IP and ASN from Cloudflare, not the visitor IP relayed by the server.
|
|
241
|
+
* With an ASN condition but no ASN available (local development, or the edge did not send it), the check fails.
|
|
234
242
|
*/
|
|
235
243
|
export function isSourceAllowed(policy, source) {
|
|
236
244
|
if (policy.allowedCidrs.length > 0) {
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
import type { RegistryAttributionWire } from "./types.js";
|
|
2
|
-
/**
|
|
2
|
+
/** The source of registry data (which registry it is, not the route it was fetched through) */
|
|
3
3
|
export type RegistrySource = "fia_tax_registration" | "gcis_company";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* Attribution for government open data. The license (Taiwan's Open Government Data License, version 1) requires naming the providing agency on use,
|
|
6
|
+
* so responses, prefilled screens and documentation all carry this.
|
|
7
7
|
*/
|
|
8
8
|
export declare const REGISTRY_ATTRIBUTION: Record<RegistrySource, RegistryAttributionWire>;
|
|
9
9
|
export declare function registryAttribution(source: RegistrySource, dataDate?: string): RegistryAttributionWire;
|
|
10
10
|
/**
|
|
11
|
-
*
|
|
12
|
-
*
|
|
11
|
+
* Which agency name to show in the attribution: the original name in Chinese interfaces, the English name in every other locale.
|
|
12
|
+
* Checkout, the customer account, forms and the dashboard all use this instead of deciding by locale themselves.
|
|
13
13
|
*/
|
|
14
14
|
export declare function registryProviderName(attribution: Pick<RegistryAttributionWire, "provider" | "providerEn">, locale: string | null | undefined): string;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* Attribution for government open data. The license (Taiwan's Open Government Data License, version 1) requires naming the providing agency on use,
|
|
3
|
+
* so responses, prefilled screens and documentation all carry this.
|
|
4
4
|
*/
|
|
5
5
|
export const REGISTRY_ATTRIBUTION = {
|
|
6
6
|
fia_tax_registration: {
|
|
@@ -20,8 +20,8 @@ export function registryAttribution(source, dataDate) {
|
|
|
20
20
|
return dataDate ? { ...REGISTRY_ATTRIBUTION[source], dataDate } : REGISTRY_ATTRIBUTION[source];
|
|
21
21
|
}
|
|
22
22
|
/**
|
|
23
|
-
*
|
|
24
|
-
*
|
|
23
|
+
* Which agency name to show in the attribution: the original name in Chinese interfaces, the English name in every other locale.
|
|
24
|
+
* Checkout, the customer account, forms and the dashboard all use this instead of deciding by locale themselves.
|
|
25
25
|
*/
|
|
26
26
|
export function registryProviderName(attribution, locale) {
|
|
27
27
|
return locale?.toLowerCase().startsWith("zh") ? attribution.provider : attribution.providerEn;
|
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
import type { TaxIdFormatDefinition } from "./types.js";
|
|
2
|
-
/**
|
|
2
|
+
/** Declares a tax ID format. It only narrows types; formats are registered in registry.ts */
|
|
3
3
|
export declare function defineTaxIdFormat(definition: TaxIdFormatDefinition): TaxIdFormatDefinition;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* EU VAT identification number: a member state prefix plus that country's format. Greece's prefix is EL (its country code is GR).
|
|
6
|
+
* The country formats follow the EU's public VIES notes and are not verified against each country's official documentation yet, so this only warns and never blocks;
|
|
7
|
+
* the countries' check digits are not implemented either. When the user types only the number, the prefix is added.
|
|
8
8
|
*/
|
|
9
9
|
const EU_VAT = {
|
|
10
10
|
AT: { prefix: "AT", pattern: /^ATU\d{8}$/, example: "ATU12345678" },
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* Hong Kong Business Registration number: 8 digits (since December 2023 also the number part of the Unique Business Identifier).
|
|
3
|
+
* The full number on a Business Registration Certificate is "8 digits - 3-digit branch - ...", so only the first 8 digits are taken from a pasted full number. No check digit is published.
|
|
4
4
|
*/
|
|
5
5
|
export declare const hkBr: import("../types.js").TaxIdFormatDefinition;
|
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* Hong Kong Business Registration number: 8 digits (since December 2023 also the number part of the Unique Business Identifier).
|
|
6
|
+
* The full number on a Business Registration Certificate is "8 digits - 3-digit branch - ...", so only the first 8 digits are taken from a pasted full number. No check digit is published.
|
|
7
7
|
*/
|
|
8
8
|
export const hkBr = defineTaxIdFormat({
|
|
9
9
|
type: "hk_br",
|
|
@@ -11,7 +11,7 @@ export const hkBr = defineTaxIdFormat({
|
|
|
11
11
|
stripeType: "hk_br",
|
|
12
12
|
normalize: (cleaned) => {
|
|
13
13
|
const digits = stripSeparators(cleaned);
|
|
14
|
-
//
|
|
14
|
+
// The full certificate number: 8 digits, a 3-digit branch, year and month and so on, 16 digits in total
|
|
15
15
|
return /^\d{16}$/.test(digits) && /\D/.test(cleaned) ? digits.slice(0, 8) : digits;
|
|
16
16
|
},
|
|
17
17
|
validate: (normalized) => (/^\d{8}$/.test(normalized) ? null : "FORMAT"),
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
2
|
+
* Japan's Qualified Invoice Issuer registration number: "T" plus 13 digits (National Tax Agency).
|
|
3
|
+
* A corporation's is T plus its Corporate Number (which has a check digit); a sole proprietor's is a separately assigned 13 digits, and the authority does not say whether it satisfies the Corporate Number check digit,
|
|
4
|
+
* so only the format is validated here, not a check digit. When only 13 digits are typed, the T is added.
|
|
5
5
|
*/
|
|
6
6
|
export declare const jpTrn: import("../types.js").TaxIdFormatDefinition;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* Japan's Qualified Invoice Issuer registration number: "T" plus 13 digits (National Tax Agency).
|
|
6
|
+
* A corporation's is T plus its Corporate Number (which has a check digit); a sole proprietor's is a separately assigned 13 digits, and the authority does not say whether it satisfies the Corporate Number check digit,
|
|
7
|
+
* so only the format is validated here, not a check digit. When only 13 digits are typed, the T is added.
|
|
8
8
|
*/
|
|
9
9
|
export const jpTrn = defineTaxIdFormat({
|
|
10
10
|
type: "jp_trn",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
2
|
+
* South Korea's Business Registration Number: 10 digits (often written XXX-XX-XXXXX) with a check digit.
|
|
3
|
+
* The first 9 digits are multiplied by the weights [1,3,7,1,3,7,1,3,5] and summed, plus the tens digit of "9th digit x 5"; (10 - sum % 10) % 10 must equal the 10th digit.
|
|
4
4
|
*/
|
|
5
5
|
export declare function isValidKrBrn(normalized: string): boolean;
|
|
6
6
|
export declare const krBrn: import("../types.js").TaxIdFormatDefinition;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
const WEIGHTS = [1, 3, 7, 1, 3, 7, 1, 3, 5];
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
7
|
-
*
|
|
6
|
+
* South Korea's Business Registration Number: 10 digits (often written XXX-XX-XXXXX) with a check digit.
|
|
7
|
+
* The first 9 digits are multiplied by the weights [1,3,7,1,3,7,1,3,5] and summed, plus the tens digit of "9th digit x 5"; (10 - sum % 10) % 10 must equal the 10th digit.
|
|
8
8
|
*/
|
|
9
9
|
export function isValidKrBrn(normalized) {
|
|
10
10
|
if (!/^\d{10}$/.test(normalized))
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
* - my_itn
|
|
4
|
-
* - my_sst
|
|
2
|
+
* Malaysian tax IDs. Both follow public examples and are not verified against the official documentation of LHDN and Customs yet, so they only warn and never block.
|
|
3
|
+
* - my_itn: income tax number (TIN), a 1 to 2 letter category plus digits (for example C 1234567890); this is the one e-invoicing (MyInvois) uses
|
|
4
|
+
* - my_sst: Sales and Service Tax registration number (for example A12-3456-78912345)
|
|
5
5
|
*/
|
|
6
6
|
export declare const myItn: import("../types.js").TaxIdFormatDefinition;
|
|
7
7
|
export declare const mySst: import("../types.js").TaxIdFormatDefinition;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
* - my_itn
|
|
7
|
-
* - my_sst
|
|
5
|
+
* Malaysian tax IDs. Both follow public examples and are not verified against the official documentation of LHDN and Customs yet, so they only warn and never block.
|
|
6
|
+
* - my_itn: income tax number (TIN), a 1 to 2 letter category plus digits (for example C 1234567890); this is the one e-invoicing (MyInvois) uses
|
|
7
|
+
* - my_sst: Sales and Service Tax registration number (for example A12-3456-78912345)
|
|
8
8
|
*/
|
|
9
9
|
export const myItn = defineTaxIdFormat({
|
|
10
10
|
type: "my_itn",
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* Singapore UEN, in three formats: businesses (8 digits plus a letter), local companies (a 4-digit year, 5 digits and a letter)
|
|
6
|
+
* and other entities (T, S or R, a 2-digit year, a 2-letter category, 4 digits and a letter).
|
|
7
|
+
* The algorithm of the trailing check letter is not published, so only the format is validated; the formats follow ACRA's public notes and are not verified line by line yet, so this only warns and never blocks.
|
|
8
8
|
*/
|
|
9
9
|
const SG_UEN = [/^\d{8}[A-Z]$/, /^(18|19|20)\d{2}\d{5}[A-Z]$/, /^[TSR]\d{2}[A-Z]{2}\d{4}[A-Z]$/];
|
|
10
10
|
export const sgUen = defineTaxIdFormat({
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Taiwan's Unified Business Number: 8 digits including a check digit (the Ministry of Finance's rule revised in April 2023).
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
4
|
+
* Each digit is multiplied by the weights [1,2,1,2,1,2,4,1]; a two-digit product contributes its tens digit plus its ones digit, and the number is valid when the sum is divisible by 5
|
|
5
|
+
* (the old rule required divisibility by 10; the ministry relaxed it to enlarge the number space, and 04595252, 10458570 and 62176616, issued under the new rule, would be misjudged by the old one).
|
|
6
|
+
* Exception: when the 7th digit is 7 (the product 28 can count as 10 or 1), the number is also valid when the sum plus 1 is divisible by 5.
|
|
7
|
+
* Source: the Fiscal Information Agency (Ministry of Finance, Taiwan), notice on the revised check digit logic for the Unified Business Number.
|
|
8
8
|
*/
|
|
9
9
|
export declare function isValidTwVat(normalized: string): boolean;
|
|
10
10
|
export declare const twVat: import("../types.js").TaxIdFormatDefinition;
|
|
@@ -1,15 +1,15 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
import { defineTaxIdFormat } from "../define.js";
|
|
3
3
|
import { stripSeparators } from "../normalize.js";
|
|
4
4
|
const WEIGHTS = [1, 2, 1, 2, 1, 2, 4, 1];
|
|
5
5
|
const sumOfDigits = (n) => (n < 10 ? n : Math.floor(n / 10) + (n % 10));
|
|
6
6
|
/**
|
|
7
|
-
*
|
|
7
|
+
* Taiwan's Unified Business Number: 8 digits including a check digit (the Ministry of Finance's rule revised in April 2023).
|
|
8
8
|
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
9
|
+
* Each digit is multiplied by the weights [1,2,1,2,1,2,4,1]; a two-digit product contributes its tens digit plus its ones digit, and the number is valid when the sum is divisible by 5
|
|
10
|
+
* (the old rule required divisibility by 10; the ministry relaxed it to enlarge the number space, and 04595252, 10458570 and 62176616, issued under the new rule, would be misjudged by the old one).
|
|
11
|
+
* Exception: when the 7th digit is 7 (the product 28 can count as 10 or 1), the number is also valid when the sum plus 1 is divisible by 5.
|
|
12
|
+
* Source: the Fiscal Information Agency (Ministry of Finance, Taiwan), notice on the revised check digit logic for the Unified Business Number.
|
|
13
13
|
*/
|
|
14
14
|
export function isValidTwVat(normalized) {
|
|
15
15
|
if (!/^\d{8}$/.test(normalized))
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
export * from "./types.js";
|
|
3
3
|
export * from "./define.js";
|
|
4
4
|
export * from "./normalize.js";
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Response shape of a tax ID registry lookup (from the context-bound lookup endpoint to the storefront's tax ID input). No dependencies; only relative imports inside this folder.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
* `NOT_FOUND`
|
|
4
|
+
* The lookup is only for prefilling the name and labeling; no result may ever block a submit:
|
|
5
|
+
* `NOT_FOUND` only means the public data has no match, not that the tax ID is invalid.
|
|
6
6
|
*/
|
|
7
7
|
import type { RegistryAttributionWire, TaxIdType } from "./types.js";
|
|
8
8
|
export type TaxIdLookupStatus = "VERIFIED" | "NOT_FOUND" | "VALID_FORMAT" | "UNAVAILABLE";
|
|
@@ -11,21 +11,21 @@ export interface TaxIdLookupWire {
|
|
|
11
11
|
status: TaxIdLookupStatus;
|
|
12
12
|
country: string;
|
|
13
13
|
type: TaxIdType;
|
|
14
|
-
/**
|
|
14
|
+
/** The normalized tax ID */
|
|
15
15
|
normalized: string;
|
|
16
|
-
/** `VERIFIED`
|
|
16
|
+
/** Present only when `VERIFIED` */
|
|
17
17
|
registry?: {
|
|
18
18
|
name: string;
|
|
19
19
|
address?: string;
|
|
20
|
-
/** ACTIVE
|
|
20
|
+
/** ACTIVE, SUSPENDED, CLOSED or UNKNOWN (UNKNOWN when the source does not say; do not treat it as active) */
|
|
21
21
|
registryStatus: string;
|
|
22
|
-
/**
|
|
22
|
+
/** The name contains custom characters most fonts show as boxes: do not prefill it, let the person type it */
|
|
23
23
|
nameHasPrivateUse?: boolean;
|
|
24
24
|
};
|
|
25
|
-
/**
|
|
25
|
+
/** The attribution that must be shown whenever government open data is used */
|
|
26
26
|
attribution?: RegistryAttributionWire;
|
|
27
27
|
}
|
|
28
|
-
/**
|
|
28
|
+
/** The lookup could not run (wrong context, rate limited, bad format); the storefront always treats it as nothing to prefill and shows no error */
|
|
29
29
|
export interface TaxIdLookupUnavailableWire {
|
|
30
30
|
ok: false;
|
|
31
31
|
reason: "invalid_tax_id" | "unavailable" | "rate_limited";
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Copied from Kanorio's shared code by `pnpm --filter @kanorio/sdk gen`. Do not edit by hand; a contract test keeps the two copies identical.
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
3
|
+
* Response shape of a tax ID registry lookup (from the context-bound lookup endpoint to the storefront's tax ID input). No dependencies; only relative imports inside this folder.
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
* `NOT_FOUND`
|
|
5
|
+
* The lookup is only for prefilling the name and labeling; no result may ever block a submit:
|
|
6
|
+
* `NOT_FOUND` only means the public data has no match, not that the tax ID is invalid.
|
|
7
7
|
*/
|
|
8
8
|
export {};
|