@akilin/api-kit 0.0.0-stage → 0.2.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.
@@ -0,0 +1,67 @@
1
+ import { send } from './send.js';
2
+ import { isAbsoluteUrl, joinUrl, originOf } from './url.js';
3
+ const defaultTelemetryUrl = '/api/client-logs';
4
+ // For the snippet and the URL. Characters, not bytes: text that JSON escapes heavily (a binary body read as text) can
5
+ // still take a trace past the server's ~16 KB cap, and that trace fails like any other.
6
+ const maxTextLength = 2000;
7
+ // Capped per client: during an outage (a proxy answering every call with a 502 page) each failed call would otherwise
8
+ // add a telemetry request, most likely failing too. Fixed, not an option.
9
+ const maxTracesPerWindow = 10;
10
+ const traceWindowMs = 60_000;
11
+ export function createReporter(config, options = {}) {
12
+ const url = telemetryUrl(config.baseUrl, options.url ?? defaultTelemetryUrl);
13
+ const sentAt = [];
14
+ const takeSlot = () => {
15
+ const now = Date.now();
16
+ while (sentAt.length > 0 && sentAt[0] <= now - traceWindowMs)
17
+ sentAt.shift();
18
+ if (sentAt.length >= maxTracesPerWindow)
19
+ return false;
20
+ sentAt.push(now);
21
+ return true;
22
+ };
23
+ return (request, error, durationMs) => {
24
+ if (!takeSlot())
25
+ return;
26
+ let body;
27
+ try {
28
+ const trace = {
29
+ kind: error.kind,
30
+ method: request.method,
31
+ url: truncate(withoutQuery(joinUrl(config.baseUrl, request.url))),
32
+ status: error.status,
33
+ traceId: error.traceId,
34
+ responseBodySnippet: truncate(error.responseText),
35
+ durationMs,
36
+ timestamp: new Date().toISOString(),
37
+ context: options.context?.(),
38
+ };
39
+ // Inside the try, so a `context()` result with a BigInt or a cycle drops the trace like a throwing `context()`:
40
+ // telemetry never breaks the app.
41
+ body = JSON.stringify(trace);
42
+ }
43
+ catch {
44
+ return;
45
+ }
46
+ // Straight to `send`, never through an `ApiRequest`: a failing telemetry request runs no handler or policy and is
47
+ // never reported itself (no loop). `send` resolves with the failure rather than rejecting, so it is simply
48
+ // dropped. The client's config is kept, so its `headers`, `credentials` and `fetch` apply to traces too (auth for
49
+ // the endpoint), the headers only on the origin of `baseUrl` like any request's; `unprefixed`, as the url already
50
+ // has its prefix. `keepalive`, so a full-page navigation in `onUnexpected` or `onUnauthorized`, right after this,
51
+ // doesn't cancel the trace (a trace stays well under keepalive's 64 KB).
52
+ void send(config, { method: 'POST', url, body, keepalive: true, unprefixed: true });
53
+ };
54
+ }
55
+ function withoutQuery(url) {
56
+ const end = url.search(/[?#]/);
57
+ return end < 0 ? url : url.slice(0, end);
58
+ }
59
+ // The `replace` drops the first half of a surrogate pair the cut split.
60
+ function truncate(text) {
61
+ return text.length <= maxTextLength ? text : text.slice(0, maxTextLength).replace(/[\ud800-\udbff]$/, '');
62
+ }
63
+ // Only the origin of `baseUrl` is prefixed, not its path, so the default `/api/client-logs` reaches the API's server
64
+ // even when the API is on another origin than the app.
65
+ function telemetryUrl(baseUrl, url) {
66
+ return isAbsoluteUrl(url) ? url : joinUrl(originOf(baseUrl), url);
67
+ }
package/dist/url.d.ts ADDED
@@ -0,0 +1,10 @@
1
+ export declare function isAbsoluteUrl(url: string): boolean;
2
+ export declare function originOf(url: string): string;
3
+ /**
4
+ * Whether `url` is fetched from the same origin as `baseUrl`: both relative to the page (a path, `?…`, `#…`), or both
5
+ * absolute with the same scheme and authority as written (case-insensitive; `https://host` and `https://host:443`, or
6
+ * `//host` and `https://host`, differ). Anything else, a url fetch would read another way than it reads here included,
7
+ * is another origin.
8
+ */
9
+ export declare function isSameOrigin(baseUrl: string, url: string): boolean;
10
+ export declare function joinUrl(baseUrl: string, url: string): string;
package/dist/url.js ADDED
@@ -0,0 +1,39 @@
1
+ // Parsed by hand: `URL` is outside the platform subset (platform.d.ts).
2
+ // Absolute is only `scheme://` or `//`. Any other `name:` start is a path (`items:batchGet`, `v1:search`), as relative
3
+ // paths are in practice.
4
+ const absolute = /^([a-z][a-z\d+.-]*:)?\/\//i;
5
+ export function isAbsoluteUrl(url) {
6
+ return absolute.test(url);
7
+ }
8
+ export function originOf(url) {
9
+ return /^([a-z][a-z\d+.-]*:)?\/\/[^/?#]*/i.exec(url)?.[0] ?? '';
10
+ }
11
+ /**
12
+ * Whether `url` is fetched from the same origin as `baseUrl`: both relative to the page (a path, `?…`, `#…`), or both
13
+ * absolute with the same scheme and authority as written (case-insensitive; `https://host` and `https://host:443`, or
14
+ * `//host` and `https://host`, differ). Anything else, a url fetch would read another way than it reads here included,
15
+ * is another origin.
16
+ */
17
+ export function isSameOrigin(baseUrl, url) {
18
+ const base = originKey(baseUrl);
19
+ return base !== undefined && base === originKey(url);
20
+ }
21
+ // `''` for a url relative to the page, `undefined` for one whose origin can't be told (a scheme without `//`, which
22
+ // fetch may read as a host: `https:evil.com`). First the WHATWG URL parser's own clean-up: it drops leading and
23
+ // trailing C0 controls and spaces, and every tab or newline, so `/\t/evil.com` is `//evil.com`. A `\` counts as a `/`
24
+ // before the host (`/\evil.com` is `//evil.com` in a browser) and stays in the authority after it, so
25
+ // `https://api.example.com\@evil.com` matches no base.
26
+ function originKey(url) {
27
+ const cleaned = url.replace(/^[\u0000- ]+|[\u0000- ]+$/g, '').replace(/[\t\n\r]/g, '').toLowerCase();
28
+ const withAuthority = /^([a-z][a-z\d+.-]*:)?[/\\]{2}[^/?#]*/.exec(cleaned);
29
+ if (withAuthority)
30
+ return withAuthority[0];
31
+ return /^[a-z][a-z\d+.-]*:/.test(cleaned) ? undefined : '';
32
+ }
33
+ export function joinUrl(baseUrl, url) {
34
+ if (baseUrl === '' || isAbsoluteUrl(url))
35
+ return url;
36
+ if (url === '' || url.startsWith('?') || url.startsWith('#'))
37
+ return baseUrl + url;
38
+ return `${baseUrl.replace(/\/+$/, '')}/${url.replace(/^\//, '')}`;
39
+ }
package/package.json CHANGED
@@ -1,6 +1,43 @@
1
1
  {
2
2
  "name": "@akilin/api-kit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Library-agnostic TypeScript API client for akilin.ApiKit (RFC 9457 Problem Details) APIs. Personal project — not intended for use by others; no support or stability guarantees.",
5
+ "license": "MIT",
6
+ "author": "akilin",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/akilin/api-kit.git",
10
+ "directory": "src/ts/api-kit"
11
+ },
12
+ "keywords": [
13
+ "api-client",
14
+ "fetch",
15
+ "problem-details",
16
+ "rfc9457",
17
+ "react-native"
18
+ ],
19
+ "type": "module",
20
+ "sideEffects": false,
21
+ "exports": {
22
+ ".": {
23
+ "types": "./dist/index.d.ts",
24
+ "default": "./dist/index.js"
25
+ },
26
+ "./package.json": "./package.json"
27
+ },
28
+ "main": "./dist/index.js",
29
+ "types": "./dist/index.d.ts",
30
+ "files": [
31
+ "dist"
32
+ ],
33
+ "publishConfig": {
34
+ "access": "public"
35
+ },
36
+ "scripts": {
37
+ "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
38
+ "prepack": "npm run build"
39
+ },
40
+ "devDependencies": {
41
+ "typescript": "^7.0.2"
42
+ }
43
+ }