@pingroom/sdk 0.7.1 → 0.9.0

package/dist/internal/async.js.map

@@ -1 +1 @@
-{"version":3,"file":"async.js","sourceRoot":"","sources":["../../src/internal/async.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,OAAoB,EAAE,KAAmB;IACtE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAI,WAA4E,CAAC,GAAG,CAAC;IAChG,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,CAAC,CAAc,EAAQ,EAAE;QACvC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,OAAO,CAAC,CAAC,CAAC,CAAC;YACX,MAAM;QACR,CAAC;QACD,CAAC,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../../src/internal/async.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,OAAoB,EAAE,KAAmB;IACtE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAI,WAA4E,CAAC,GAAG,CAAC;IAChG,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,CAAC,CAAc,EAAQ,EAAE;QACvC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,OAAO,CAAC,CAAC,CAAC,CAAC;YACX,MAAM;QACR,CAAC;QACD,CAAC,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/dist/internal/guards.d.ts

@@ -5,8 +5,24 @@ export declare const MAX_PRIVATE_PING_MESSAGE_LENGTH = 120;
 export declare const MAX_PUBLIC_PING_MESSAGE_LENGTH = 160;
 export declare const MAX_PING_TITLE_LENGTH = 40;
 export declare function assertMaxLength(value: unknown, max: number, field: string): void;
+/**
+ * Bytes a JSON string takes as PHP's default json_encode() writes it, which is
+ * what the server's 8 KB cap measures: every non-ASCII UTF-16 unit becomes a
+ * six-byte `\uXXXX` escape and `/` becomes `\/`. Non-Latin text is several
+ * times larger there than its UTF-8 size.
+ */
+export declare function serverJsonByteLength(json: string): number;
 export declare function assertStructuredData(data: unknown): void;
 export declare function assertActionNumber(n: unknown): void;
+/**
+ * Normalize an idempotency key the way the server reads it
+ * (`RequestIdempotency::keyFrom`): trimmed, then 1–255 characters. It travels
+ * as the `Idempotency-Key` header, so it must also be printable ASCII (space
+ * included): fetch throws on a character outside Latin-1, which surfaced as a
+ * retryable `network_error` that every retry repeated, and a Latin-1 byte above
+ * 0x7E reaches the server as invalid UTF-8.
+ */
+export declare function normalizeIdempotencyKey(value: unknown, field?: string): string;
 export declare function requireNonEmpty(value: unknown, field: string): void;
 /** Validate before uppercasing so Unicode case expansion cannot become a code. */
 export declare function normalizeRedeemCode(value: unknown): string;

package/dist/internal/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/internal/guards.ts"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,eAAO,MAAM,cAAc,QAAW,CAAC;AACvC,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAClD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAOxC,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAchF;AAmBD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAqBxD;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAOnD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAInE;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAK1D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIxE"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/internal/guards.ts"],"names":[],"mappings":"AAEA,8FAA8F;AAC9F,eAAO,MAAM,cAAc,QAAW,CAAC;AACvC,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAClD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAOxC,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAchF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASzD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAqBxD;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAOnD;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAmB,GAAG,MAAM,CAYxF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAInE;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAK1D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIxE"}

package/dist/internal/guards.js

@@ -27,7 +27,7 @@ export function assertMaxLength(value, max, field) {
  * six-byte `\uXXXX` escape and `/` becomes `\/`. Non-Latin text is several
  * times larger there than its UTF-8 size.
  */
-function serverJsonByteLength(json) {
+export function serverJsonByteLength(json) {
     let bytes = 0;
     for (let index = 0; index < json.length; index += 1) {
         const code = json.charCodeAt(index);
@@ -71,6 +71,27 @@ export function assertActionNumber(n) {
         throw new PingRoomError('action_number must be an integer 1–16.', { code: 'invalid_request' });
     }
 }
+const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/** PHP trim()'s default set: what the server strips from both ends of a key. */
+const SERVER_TRIM = /^[ \t\n\r\0\x0B]+|[ \t\n\r\0\x0B]+$/g;
+/**
+ * Normalize an idempotency key the way the server reads it
+ * (`RequestIdempotency::keyFrom`): trimmed, then 1–255 characters. It travels
+ * as the `Idempotency-Key` header, so it must also be printable ASCII (space
+ * included): fetch throws on a character outside Latin-1, which surfaced as a
+ * retryable `network_error` that every retry repeated, and a Latin-1 byte above
+ * 0x7E reaches the server as invalid UTF-8.
+ */
+export function normalizeIdempotencyKey(value, field = 'idempotencyKey') {
+    if (typeof value !== 'string') {
+        throw new PingRoomError(`\`${field}\` must be a string.`, { code: 'invalid_request' });
+    }
+    const key = value.replace(SERVER_TRIM, '');
+    if (key.length < 1 || key.length > MAX_IDEMPOTENCY_KEY_LENGTH || !/^[\x20-\x7E]+$/.test(key)) {
+        throw new PingRoomError(`\`${field}\` must be 1–${MAX_IDEMPOTENCY_KEY_LENGTH} printable ASCII characters (letters, digits, punctuation or spaces).`, { code: 'invalid_request' });
+    }
+    return key;
+}
 export function requireNonEmpty(value, field) {
     if (typeof value !== 'string' || value.trim() === '') {
         throw new PingRoomError(`\`${field}\` is required.`, { code: 'invalid_request' });

package/dist/internal/guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/internal/guards.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/internal/guards.ts"],"names":[],"mappings":"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"}

package/dist/internal/request.d.ts

@@ -0,0 +1,41 @@
+import type { PingInput } from '../types.js';
+/**
+ * Minimum spacing between the starts of two handoff-wait polls. The route is
+ * throttled at 30 requests a minute per human; a short or zero `timeout`
+ * would otherwise let one loop exhaust it.
+ */
+export declare const MIN_HANDOFF_POLL_INTERVAL_MS = 2100;
+/**
+ * Minimum spacing between the starts of two `listen()` polls after an empty
+ * answer. `notifications/wait` is throttled at 30 requests a minute per human,
+ * shared with every other listener on the account (the CLI, other agents); a
+ * zero hold or a proxy that answers early would otherwise spin the loop and
+ * keep that bucket exhausted. Same floor as the handoff wait.
+ */
+export declare const MIN_LISTEN_POLL_INTERVAL_MS = 2100;
+/**
+ * Minimum spacing between the starts of two approval or question wait polls.
+ * The server normally holds each one, but a proxy or a zero hold that answers
+ * `pending` at once would otherwise spin the loop and keep that route's
+ * 30-per-minute bucket for the human exhausted. Same floor as the handoff wait and the
+ * CLI (2100 ms keeps one loop under 30 a minute).
+ */
+export declare const MIN_WAIT_POLL_INTERVAL_MS = 2100;
+export declare function enc(segment: string): string;
+/**
+ * Lift the SDK-only `idempotencyKey` out of an input and into the
+ * `Idempotency-Key` header the server reads. The server trims the key and
+ * accepts 1–255 characters; as a header it must also be printable ASCII.
+ */
+export declare function splitIdempotencyKey<T extends {
+    idempotencyKey?: string;
+}>(input: T): {
+    body: Omit<T, 'idempotencyKey'>;
+    headers?: Record<string, string>;
+};
+/** `onRetry`, when given, must be callable: a TypeError mid-outage would hide the real failure. */
+export declare function assertOnRetry(onRetry: unknown): void;
+export declare function dropUndefined<T extends Record<string, unknown>>(obj: T): Partial<T>;
+export declare function assertPing(ping: PingInput): void;
+export declare function waitTimeoutMs(seconds: number | undefined): number;
+//# sourceMappingURL=request.d.ts.map

package/dist/internal/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/internal/request.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,OAA+B,CAAC;AACxE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,OAA+B,CAAC;AAEtE,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ3C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,EACvE,KAAK,EAAE,CAAC,GACP;IAAE,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAMvE;AAED,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAIpD;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQnF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAQhD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEjE"}

package/dist/internal/request.js

@@ -0,0 +1,78 @@
+// Request building shared by the PingRoom namespaces: path segments, bodies,
+// the Idempotency-Key header, ping input checks and long-poll timing.
+import { PingRoomError } from '../errors.js';
+import { assertActionNumber, assertMaxLength, assertStructuredData, MAX_PING_TITLE_LENGTH, MAX_PUBLIC_PING_MESSAGE_LENGTH, normalizeIdempotencyKey, requireNonEmpty, } from './guards.js';
+/** Extra wall-clock allowance over the server's hold window for long-poll calls. */
+const LONG_POLL_BUFFER_MS = 10_000;
+const DEFAULT_WAIT_SECONDS = 20;
+/**
+ * Minimum spacing between the starts of two handoff-wait polls. The route is
+ * throttled at 30 requests a minute per human; a short or zero `timeout`
+ * would otherwise let one loop exhaust it.
+ */
+export const MIN_HANDOFF_POLL_INTERVAL_MS = 2100;
+/**
+ * Minimum spacing between the starts of two `listen()` polls after an empty
+ * answer. `notifications/wait` is throttled at 30 requests a minute per human,
+ * shared with every other listener on the account (the CLI, other agents); a
+ * zero hold or a proxy that answers early would otherwise spin the loop and
+ * keep that bucket exhausted. Same floor as the handoff wait.
+ */
+export const MIN_LISTEN_POLL_INTERVAL_MS = MIN_HANDOFF_POLL_INTERVAL_MS;
+/**
+ * Minimum spacing between the starts of two approval or question wait polls.
+ * The server normally holds each one, but a proxy or a zero hold that answers
+ * `pending` at once would otherwise spin the loop and keep that route's
+ * 30-per-minute bucket for the human exhausted. Same floor as the handoff wait and the
+ * CLI (2100 ms keeps one loop under 30 a minute).
+ */
+export const MIN_WAIT_POLL_INTERVAL_MS = MIN_HANDOFF_POLL_INTERVAL_MS;
+export function enc(segment) {
+    // encodeURIComponent leaves `.` and `..` alone, and URL parsing then
+    // resolves them as dot segments: `live.get('AB12', '..')` would request the
+    // room itself. No id is empty or a dot segment, so refuse them.
+    if (segment === '' || segment === '.' || segment === '..') {
+        throw new PingRoomError('A path parameter may not be empty, `.` or `..`.', { code: 'invalid_request' });
+    }
+    return encodeURIComponent(segment);
+}
+/**
+ * Lift the SDK-only `idempotencyKey` out of an input and into the
+ * `Idempotency-Key` header the server reads. The server trims the key and
+ * accepts 1–255 characters; as a header it must also be printable ASCII.
+ */
+export function splitIdempotencyKey(input) {
+    const { idempotencyKey, ...body } = input;
+    if (idempotencyKey === undefined) {
+        return { body };
+    }
+    return { body, headers: { 'Idempotency-Key': normalizeIdempotencyKey(idempotencyKey) } };
+}
+/** `onRetry`, when given, must be callable: a TypeError mid-outage would hide the real failure. */
+export function assertOnRetry(onRetry) {
+    if (onRetry !== undefined && typeof onRetry !== 'function') {
+        throw new PingRoomError('`onRetry` must be a function.', { code: 'invalid_request' });
+    }
+}
+export function dropUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined) {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+export function assertPing(ping) {
+    requireNonEmpty(ping.message, 'message');
+    // The invite code does not expose room visibility. Permit the public-room
+    // ceiling locally; Laravel applies 120 for private and 160 for public rooms.
+    assertMaxLength(ping.message, MAX_PUBLIC_PING_MESSAGE_LENGTH, 'message');
+    assertMaxLength(ping.title, MAX_PING_TITLE_LENGTH, 'title');
+    assertActionNumber(ping.action_number);
+    assertStructuredData(ping.data);
+}
+export function waitTimeoutMs(seconds) {
+    return (seconds ?? DEFAULT_WAIT_SECONDS) * 1000 + LONG_POLL_BUFFER_MS;
+}
+//# sourceMappingURL=request.js.map

package/dist/internal/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/internal/request.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,sEAAsE;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,uBAAuB,EACvB,eAAe,GAChB,MAAM,aAAa,CAAC;AAGrB,oFAAoF;AACpF,MAAM,mBAAmB,GAAG,MAAM,CAAC;AACnC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEhC;;;;GAIG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AACjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,4BAA4B,CAAC;AACxE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,4BAA4B,CAAC;AAEtE,MAAM,UAAU,GAAG,CAAC,OAAe;IACjC,qEAAqE;IACrE,4EAA4E;IAC5E,gEAAgE;IAChE,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QAC1D,MAAM,IAAI,aAAa,CAAC,iDAAiD,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAQ;IAER,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IAC1C,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,EAAE,IAAI,EAAE,CAAC;IAClB,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,iBAAiB,EAAE,uBAAuB,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC;AAC3F,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3D,MAAM,IAAI,aAAa,CAAC,+BAA+B,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC,CAAC;IACxF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAoC,GAAM;IACrE,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,OAAO,GAAiB,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAe;IACxC,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACzC,0EAA0E;IAC1E,6EAA6E;IAC7E,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE,8BAA8B,EAAE,SAAS,CAAC,CAAC;IACzE,eAAe,CAAC,IAAI,CAAC,KAAK,EAAE,qBAAqB,EAAE,OAAO,CAAC,CAAC;IAC5D,kBAAkB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACvC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAA2B;IACvD,OAAO,CAAC,OAAO,IAAI,oBAAoB,CAAC,GAAG,IAAI,GAAG,mBAAmB,CAAC;AACxE,CAAC"}

package/dist/internal/retry.d.ts

@@ -0,0 +1,65 @@
+import { PingRoomError } from '../errors.js';
+/** First retry delay after a transient failure, in ms. */
+export declare const TRANSIENT_BACKOFF_BASE_MS = 1000;
+/**
+ * The smallest backoff base, whatever a caller asks for. A persistent failure
+ * would otherwise retry in a tight loop (a base of 0 never grows at all)
+ * against wait routes limited to 30 requests a minute each.
+ */
+export declare const MIN_TRANSIENT_BACKOFF_MS = 250;
+/** Ceiling on the exponential backoff (a server Retry-After may ask for longer). */
+export declare const TRANSIENT_BACKOFF_CAP_MS = 30000;
+/**
+ * How long past the last-seen `expires_at` a wait keeps retrying an
+ * unreachable API. The server reports `expired` once expires_at passes, so
+ * after this the only outcome left is one that cannot be read. Covers clock
+ * skew. Same bound as the CLI.
+ */
+export declare const WAIT_EXPIRY_GRACE_MS: number;
+/** The bound on an unbroken outage while no response has carried `expires_at`. */
+export declare const WAIT_UNKNOWN_EXPIRY_OUTAGE_MS: number;
+/**
+ * A failure a read loop may retry: a dropped connection, a request deadline,
+ * a 429 (each wait route has its own 30/min bucket per human), or a 5xx.
+ * Everything else — 401/403/404/422, a refused redirect, a malformed response —
+ * is permanent and must surface to the caller.
+ */
+export declare function isTransientError(error: unknown): error is PingRoomError;
+/**
+ * Delay before retrying after the `failures`-th consecutive transient failure:
+ * exponential from `baseMs`, capped at 30 s. A server `retryAfter` replaces the
+ * exponential step, but is never waited for less than `baseMs`. A `baseMs`
+ * below {@link MIN_TRANSIENT_BACKOFF_MS} is raised to it.
+ */
+export declare function transientDelayMs(error: PingRoomError, failures: number, baseMs?: number): number;
+export interface PollUntilSettledOptions<T> {
+    /** One bounded long-poll. Its errors are retried only when transient. */
+    poll: () => Promise<unknown>;
+    /** Check the response's minimal shape; throw `invalid_response` otherwise. */
+    validate: (value: unknown) => T;
+    /** True once the validated value is terminal. */
+    settled: (value: T) => boolean;
+    signal?: AbortSignal;
+    /** Minimum time between the starts of two polls, in ms. Default 0. */
+    minIntervalMs?: number;
+    /** Read `expires_at` (an ISO time) from a validated response; it bounds an outage. */
+    expiresAt?: (value: T) => unknown;
+    /** Names what is waited on in the give-up message, e.g. `approval a1`. */
+    what: string;
+    /** Called before each retry of a transient failure; `attempt` counts consecutive failures from 1. */
+    onRetry?: (error: PingRoomError, attempt: number) => void;
+}
+/**
+ * The shared human-in-the-loop wait loop. Polls until a validated response is
+ * terminal; retries transient failures with backoff; rejects with the
+ * signal's reason once it aborts. A response that fails validation is never
+ * returned as an outcome.
+ *
+ * The retries are bounded even without a signal. Once only failures have come
+ * back since the last valid response, and the last-seen `expires_at` plus
+ * {@link WAIT_EXPIRY_GRACE_MS} has passed (or, before any `expires_at` was
+ * seen, after {@link WAIT_UNKNOWN_EXPIRY_OUTAGE_MS} of unbroken failures), the
+ * wait rejects with `unavailable`, the last failure as its `cause`.
+ */
+export declare function pollUntilSettled<T>(options: PollUntilSettledOptions<T>): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/internal/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/internal/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,0DAA0D;AAC1D,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAG/C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAa,CAAC;AAC/C,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAQvE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,MAAkC,GACzC,MAAM,CAUR;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,yEAAyE;IACzE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC;IAChC,iDAAiD;IACjD,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAClC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,qGAAqG;IACrG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAeD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAkDzF"}

package/dist/internal/retry.js

@@ -0,0 +1,126 @@
+import { PingRoomError } from '../errors.js';
+import { sleep, throwIfAborted } from './async.js';
+/** First retry delay after a transient failure, in ms. */
+export const TRANSIENT_BACKOFF_BASE_MS = 1000;
+/**
+ * The smallest backoff base, whatever a caller asks for. A persistent failure
+ * would otherwise retry in a tight loop (a base of 0 never grows at all)
+ * against wait routes limited to 30 requests a minute each.
+ */
+export const MIN_TRANSIENT_BACKOFF_MS = 250;
+/** Ceiling on the exponential backoff (a server Retry-After may ask for longer). */
+export const TRANSIENT_BACKOFF_CAP_MS = 30_000;
+/** setTimeout fires immediately above this, so no delay may exceed it. */
+const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * How long past the last-seen `expires_at` a wait keeps retrying an
+ * unreachable API. The server reports `expired` once expires_at passes, so
+ * after this the only outcome left is one that cannot be read. Covers clock
+ * skew. Same bound as the CLI.
+ */
+export const WAIT_EXPIRY_GRACE_MS = 5 * 60_000;
+/** The bound on an unbroken outage while no response has carried `expires_at`. */
+export const WAIT_UNKNOWN_EXPIRY_OUTAGE_MS = 15 * 60_000;
+/**
+ * A failure a read loop may retry: a dropped connection, a request deadline,
+ * a 429 (each wait route has its own 30/min bucket per human), or a 5xx.
+ * Everything else — 401/403/404/422, a refused redirect, a malformed response —
+ * is permanent and must surface to the caller.
+ */
+export function isTransientError(error) {
+    return (error instanceof PingRoomError
+        && (error.code === 'network_error'
+            || error.code === 'timeout'
+            || error.status === 429
+            || error.status >= 500));
+}
+/**
+ * Delay before retrying after the `failures`-th consecutive transient failure:
+ * exponential from `baseMs`, capped at 30 s. A server `retryAfter` replaces the
+ * exponential step, but is never waited for less than `baseMs`. A `baseMs`
+ * below {@link MIN_TRANSIENT_BACKOFF_MS} is raised to it.
+ */
+export function transientDelayMs(error, failures, baseMs = TRANSIENT_BACKOFF_BASE_MS) {
+    const requested = Number.isFinite(baseMs) && baseMs >= 0 ? baseMs : TRANSIENT_BACKOFF_BASE_MS;
+    const base = Math.max(MIN_TRANSIENT_BACKOFF_MS, requested);
+    const retryAfter = error.retryAfter;
+    if (typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter >= 0) {
+        return Math.min(MAX_TIMER_MS, Math.max(retryAfter * 1000, base));
+    }
+    // Enough doublings to pass the cap from any base; also keeps 2 ** step finite.
+    const step = Math.min(Math.max(0, failures - 1), 30);
+    return Math.min(MAX_TIMER_MS, Math.max(base, TRANSIENT_BACKOFF_CAP_MS), base * 2 ** step);
+}
+function timeOf(value) {
+    const at = typeof value === 'string' ? Date.parse(value) : NaN;
+    return Number.isFinite(at) ? at : null;
+}
+function unavailable(last, since, what) {
+    const reason = last.status > 0 ? `HTTP ${last.status}` : (last.code ?? 'network error');
+    return new PingRoomError(`PingRoom unavailable since ${new Date(since).toISOString()} (${reason}); stopped waiting for ${what}.`, { code: 'unavailable', cause: last });
+}
+/**
+ * The shared human-in-the-loop wait loop. Polls until a validated response is
+ * terminal; retries transient failures with backoff; rejects with the
+ * signal's reason once it aborts. A response that fails validation is never
+ * returned as an outcome.
+ *
+ * The retries are bounded even without a signal. Once only failures have come
+ * back since the last valid response, and the last-seen `expires_at` plus
+ * {@link WAIT_EXPIRY_GRACE_MS} has passed (or, before any `expires_at` was
+ * seen, after {@link WAIT_UNKNOWN_EXPIRY_OUTAGE_MS} of unbroken failures), the
+ * wait rejects with `unavailable`, the last failure as its `cause`.
+ */
+export async function pollUntilSettled(options) {
+    const { poll, validate, settled, signal, minIntervalMs = 0, expiresAt, what, onRetry } = options;
+    let failures = 0;
+    let failingSince = null;
+    // expires_at plus grace, from the last valid response that carried one.
+    let deadline = null;
+    for (;;) {
+        throwIfAborted(signal);
+        const startedAt = Date.now();
+        let value;
+        try {
+            value = validate(await poll());
+        }
+        catch (error) {
+            throwIfAborted(signal);
+            if (!isTransientError(error)) {
+                throw error;
+            }
+            failures += 1;
+            failingSince ??= Date.now();
+            const remaining = (deadline ?? failingSince + WAIT_UNKNOWN_EXPIRY_OUTAGE_MS) - Date.now();
+            if (remaining <= 0) {
+                throw unavailable(error, failingSince, what);
+            }
+            onRetry?.(error, failures);
+            // A fast failure still consumes a poll. Keep retries spaced even when a
+            // pending response between failures resets the exponential backoff.
+            const delay = Math.max(transientDelayMs(error, failures), minIntervalMs - (Date.now() - startedAt));
+            // Do not retry earlier than the interval or Retry-After just to fit the
+            // outage bound. Wait out the budget, then stop without another request.
+            if (delay > remaining) {
+                await sleep(remaining, signal);
+                throwIfAborted(signal);
+                throw unavailable(error, failingSince, what);
+            }
+            await sleep(delay, signal);
+            continue;
+        }
+        failures = 0;
+        failingSince = null;
+        const expiry = expiresAt ? timeOf(expiresAt(value)) : null;
+        if (expiry !== null) {
+            deadline = expiry + WAIT_EXPIRY_GRACE_MS;
+        }
+        if (settled(value)) {
+            return value;
+        }
+        // An injected transport can resolve pending polls immediately. Yield
+        // between them so timer-driven cancellation and deadlines can run.
+        await sleep(Math.max(0, minIntervalMs - (Date.now() - startedAt)), signal);
+    }
+}
+//# sourceMappingURL=retry.js.map

package/dist/internal/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/internal/retry.ts"],"names":[],"mappings":"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"}

package/dist/internal/url.d.ts

@@ -12,4 +12,13 @@ export declare function assertSecureUrl(rawUrl: string, allowInsecure: boolean):
  * errors, so a message copied from one must not reach a caller's logs as-is.
  */
 export declare function redactUrlInMessage(message: string, url: URL, rawUrl: string): string;
+/**
+ * Every request goes out with `redirect: 'manual'` (Cloudflare Workers throw
+ * on `'error'`), so a redirect comes back as a response instead of being
+ * followed. Refuse it: a 307/308 would replay pairing secrets, uploaded bytes
+ * or a webhook body to whatever origin `Location` names. Browsers report a
+ * manual redirect as an `opaqueredirect` with status 0; other runtimes return
+ * the 3xx itself.
+ */
+export declare function refuseRedirect(res: Response): void;
 //# sourceMappingURL=url.d.ts.map

package/dist/internal/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/internal/url.ts"],"names":[],"mappings":"AAEA,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,GAAG,CAsB3E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUpF"}
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/internal/url.ts"],"names":[],"mappings":"AAEA,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,GAAG,CAsB3E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUpF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAelD"}

package/dist/internal/url.js

@@ -48,4 +48,29 @@ export function redactUrlInMessage(message, url, rawUrl) {
     }
     return out;
 }
+/**
+ * Every request goes out with `redirect: 'manual'` (Cloudflare Workers throw
+ * on `'error'`), so a redirect comes back as a response instead of being
+ * followed. Refuse it: a 307/308 would replay pairing secrets, uploaded bytes
+ * or a webhook body to whatever origin `Location` names. Browsers report a
+ * manual redirect as an `opaqueredirect` with status 0; other runtimes return
+ * the 3xx itself.
+ */
+export function refuseRedirect(res) {
+    if (res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400)) {
+        // Release the body, best effort. A custom `fetch` such as node-fetch hands
+        // back a Node Readable with no cancel(); calling it threw a TypeError that
+        // surfaced as a retryable network_error instead of this refusal.
+        try {
+            res.body?.cancel?.()?.catch?.(() => { });
+        }
+        catch {
+            // Ignored: the refusal below is what matters.
+        }
+        throw new PingRoomError('Refusing to follow a redirect; credentials and request bodies are never forwarded.', {
+            code: 'redirect_refused',
+            status: res.status,
+        });
+    }
+}
 //# sourceMappingURL=url.js.map

package/dist/internal/url.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/internal/url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AAC3F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,aAAsB;IACpE,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,2CAA2C;QAC3C,MAAM,IAAI,aAAa,CAAC,+DAA+D,EAAE;YACvF,IAAI,EAAE,aAAa;SACpB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,aAAa,IAAI,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAChF,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,IAAI,aAAa,CACrB,sDAAsD,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,KAAK;QAClF,sEAAsE,EACxE,EAAE,IAAI,EAAE,cAAc,EAAE,CACzB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,GAAQ,EAAE,MAAc;IAC1E,MAAM,QAAQ,GAAG,GAAG,GAAG,CAAC,MAAM,aAAa,CAAC;IAC5C,IAAI,GAAG,GAAG,OAAO,CAAC;IAClB,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,IAAI,IAAI;YAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjD,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7E,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/internal/url.ts"],"names":[],"mappings":"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"}

package/dist/internal/validate.d.ts

@@ -0,0 +1,13 @@
+import { PingRoomError } from '../errors.js';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isNonEmptyString(value: unknown): value is string;
+export declare function isNullableString(value: unknown): value is string | null;
+/** UUIDs are case-insensitive; a caller may hold an id in either case. */
+export declare function sameId(received: unknown, expected: string): boolean;
+export declare function invalidWaitResponse(subject: string, expectedId: string, value: unknown, stateField: string): never;
+/**
+ * A 2xx the PingRoom API never sends: a gateway's or captive portal's page, or
+ * a URL that is not PingRoom's. The body is kept short, for inspection only.
+ */
+export declare function invalidSuccessResponse(status: number, expected: string, body: unknown): PingRoomError;
+//# sourceMappingURL=validate.d.ts.map

package/dist/internal/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/internal/validate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,GAAG,IAAI,CAEvE;AAED,0EAA0E;AAC1E,wBAAgB,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,CASlH;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,aAAa,CAKrG"}

package/dist/internal/validate.js

@@ -0,0 +1,36 @@
+// Shape checks for server responses the wait loops and Agent Inbox trust.
+import { PingRoomError } from '../errors.js';
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+export function isNullableString(value) {
+    return value === null || typeof value === 'string';
+}
+/** UUIDs are case-insensitive; a caller may hold an id in either case. */
+export function sameId(received, expected) {
+    return typeof received === 'string' && received.toLowerCase() === expected.toLowerCase();
+}
+export function invalidWaitResponse(subject, expectedId, value, stateField) {
+    throw new PingRoomError(`PingRoom returned an invalid ${subject} wait response.`, {
+        code: 'invalid_response',
+        body: {
+            expected_id: expectedId,
+            received_id: isRecord(value) && typeof value['id'] === 'string' ? value['id'] : null,
+            [stateField]: isRecord(value) && typeof value[stateField] === 'string' ? value[stateField] : null,
+        },
+    });
+}
+/**
+ * A 2xx the PingRoom API never sends: a gateway's or captive portal's page, or
+ * a URL that is not PingRoom's. The body is kept short, for inspection only.
+ */
+export function invalidSuccessResponse(status, expected, body) {
+    return new PingRoomError(`PingRoom returned an invalid response (HTTP ${status}): expected ${expected}.`, {
+        code: 'invalid_response',
+        body: typeof body === 'string' ? body.slice(0, 512) : body,
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/internal/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/internal/validate.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;AACrD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,MAAM,CAAC,QAAiB,EAAE,QAAgB;IACxD,OAAO,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,UAAkB,EAAE,KAAc,EAAE,UAAkB;IACzG,MAAM,IAAI,aAAa,CAAC,gCAAgC,OAAO,iBAAiB,EAAE;QAChF,IAAI,EAAE,kBAAkB;QACxB,IAAI,EAAE;YACJ,WAAW,EAAE,UAAU;YACvB,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;YACpF,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI;SAClG;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,QAAgB,EAAE,IAAa;IACpF,OAAO,IAAI,aAAa,CAAC,+CAA+C,MAAM,eAAe,QAAQ,GAAG,EAAE;QACxG,IAAI,EAAE,kBAAkB;QACxB,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI;KAC3D,CAAC,CAAC;AACL,CAAC"}

package/dist/linkPing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linkPing.d.ts","sourceRoot":"","sources":["../src/linkPing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAKD,wFAAwF;AACxF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAmB3D"}
+{"version":3,"file":"linkPing.d.ts","sourceRoot":"","sources":["../src/linkPing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAUD,wFAAwF;AACxF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAmB3D"}

package/dist/linkPing.js

@@ -13,6 +13,10 @@
  */
 const URL_MAX = 2048;
 const LABEL_MAX = 26;
+/** Count code points, as the server's mb_strlen does — an emoji is one character, not two. */
+function characterLength(value) {
+    return Array.from(value).length;
+}
 /** Build the `data` fragment for a link ping. Spread it into a ping's `data` object. */
 export function linkPing(input) {
     let parsed;
@@ -25,10 +29,10 @@ export function linkPing(input) {
     if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
         throw new TypeError('linkPing: url must be an absolute http(s) URL');
     }
-    if (input.url.length > URL_MAX) {
+    if (characterLength(input.url) > URL_MAX) {
         throw new TypeError(`linkPing: url must be at most ${URL_MAX} characters`);
     }
-    if (input.buttonLabel !== undefined && input.buttonLabel.length > LABEL_MAX) {
+    if (input.buttonLabel !== undefined && characterLength(input.buttonLabel) > LABEL_MAX) {
         throw new TypeError(`linkPing: buttonLabel must be at most ${LABEL_MAX} characters`);
     }
     const out = { url: input.url };

package/dist/linkPing.js.map

@@ -1 +1 @@
-{"version":3,"file":"linkPing.js","sourceRoot":"","sources":["../src/linkPing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,MAAM,OAAO,GAAG,IAAI,CAAC;AACrB,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB,wFAAwF;AACxF,MAAM,UAAU,QAAQ,CAAC,KAAoB;IAC3C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CAAC,iCAAiC,OAAO,aAAa,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC5E,MAAM,IAAI,SAAS,CAAC,yCAAyC,SAAS,aAAa,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,GAAG,GAAiB,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;IAC7C,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,GAAG,CAAC,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;IAC1E,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"linkPing.js","sourceRoot":"","sources":["../src/linkPing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,MAAM,OAAO,GAAG,IAAI,CAAC;AACrB,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB,8FAA8F;AAC9F,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAClC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,QAAQ,CAAC,KAAoB;IAC3C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CAAC,kCAAkC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,eAAe,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,EAAE,CAAC;QACzC,MAAM,IAAI,SAAS,CAAC,iCAAiC,OAAO,aAAa,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,IAAI,eAAe,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,SAAS,EAAE,CAAC;QACtF,MAAM,IAAI,SAAS,CAAC,yCAAyC,SAAS,aAAa,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,GAAG,GAAiB,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;IAC7C,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,GAAG,CAAC,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC;IAC1E,OAAO,GAAG,CAAC;AACb,CAAC"}