@layervai/qurl 3.1.0 → 4.0.0

package/dist/esm/client-errors.js

@@ -0,0 +1,206 @@
+import { ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_UNEXPECTED_RESPONSE, ValidationError, } from "./errors.js";
+import { MAX_DEBUG_BODY_KEYS, MAX_DIAGNOSTIC_COLLECTION_BYTES, MAX_ERROR_SNIPPET_BYTES, MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS, MAX_INVALID_FIELD_ENTRIES, } from "./client-limits.js";
+export const TEXT_ENCODER = new TextEncoder();
+const ERROR_SNIPPET_ELLIPSIS = "...";
+const ERROR_SNIPPET_ELLIPSIS_BYTES = 3;
+// RFC 8259 JSON exchanged between systems must be valid UTF-8. A non-fatal
+// decoder would replace malformed bytes with U+FFFD before JSON.parse and hide
+// the producer's exact contract violation.
+export const TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Construct a {@link ValidationError} for a client-side pre-flight check.
+ * Uses `status: 0` (matching {@link NetworkError}/{@link TimeoutError}) and
+ * `code: "client_validation"` so catch-by-class still works and callers can
+ * tell the error originated inside the SDK rather than from the API.
+ */
+export function clientValidationError(detail) {
+    return new ValidationError({
+        status: 0,
+        code: ERROR_CODE_CLIENT_VALIDATION,
+        title: "Invalid Argument",
+        detail,
+    });
+}
+/**
+ * Construct a {@link ValidationError} for the case where the API returned
+ * a response that parsed as JSON but didn't match the expected schema
+ * shape (e.g. 400 with a body that isn't a {@link BatchCreateOutput}).
+ *
+ * Distinct from {@link clientValidationError} so callers can `.code`-branch
+ * between "I passed bad input locally" (`"client_validation"`) and "the
+ * server returned a body I can't interpret" (`"unexpected_response"`).
+ * Uses `status: 0` by default because a logical shape mismatch is not tied to
+ * the HTTP classification. Callers that enforce an observed HTTP contract
+ * pass that status explicitly.
+ *
+ * Threads `request_id` through to {@link QURLError.requestId} when the
+ * server-side correlation ID is available — operators debugging
+ * "unexpected response" tickets need it on the *error* path too, not
+ * just on success/passthrough returns.
+ */
+export function unexpectedResponseError(detail, options = {}) {
+    // Every detail passed here is an SDK-authored contract message whose dynamic
+    // inputs were validated by the caller-side shape guards. Do not pass raw
+    // server strings to this helper. Server diagnostics use boundedErrorSnippet.
+    const safeRequestId = boundedErrorIdentifier(options.requestId);
+    return new ValidationError({
+        status: options.status ?? 0,
+        code: ERROR_CODE_UNEXPECTED_RESPONSE,
+        title: "Unexpected Response",
+        detail,
+        request_id: safeRequestId,
+    });
+}
+export function withErrorCause(error, cause) {
+    // Match the native Error `cause` descriptor. In particular, do not leak a
+    // transport object through Object.keys(), object spread, or JSON logging.
+    Object.defineProperty(error, "cause", {
+        value: cause,
+        writable: true,
+        configurable: true,
+    });
+    return error;
+}
+export function isIndependentAbort(error, requestSignal) {
+    return (error instanceof Error &&
+        (error.name === "AbortError" || error.name === "TimeoutError") &&
+        !requestSignal.aborted);
+}
+export function isSdkTimeout(error, requestSignal) {
+    return (error instanceof Error &&
+        requestSignal.aborted &&
+        (error.name === "TimeoutError" || error.name === "AbortError"));
+}
+/**
+ * Normalize a server-provided problem title/detail into a single-line,
+ * UTF-8-safe snippet. Error messages must stay bounded even when a proxy or
+ * compromised upstream returns very large structured problem fields.
+ */
+function normalizedErrorSnippet(value) {
+    if (typeof value !== "string")
+        return undefined;
+    // Bound source work before the Unicode regular expressions allocate
+    // normalized copies. The response body cap is much larger than one retained
+    // diagnostic, so processing the full server string would waste memory.
+    const normalized = value
+        .slice(0, MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS)
+        // Strip control characters plus bidi override/isolate controls that can
+        // visually reorder diagnostics. Preserve other formatting characters
+        // such as ZWJ/ZWNJ, which are required by legitimate scripts and emoji.
+        .replace(/[\p{Cc}\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu, " ")
+        .trim()
+        .replace(/\s+/g, " ");
+    return normalized === "" ? undefined : normalized;
+}
+export function boundedErrorSnippet(value) {
+    const sourceTruncated = typeof value === "string" && value.length > MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS;
+    const normalized = normalizedErrorSnippet(value);
+    if (normalized === undefined)
+        return undefined;
+    const contentLimit = sourceTruncated
+        ? MAX_ERROR_SNIPPET_BYTES - ERROR_SNIPPET_ELLIPSIS_BYTES
+        : MAX_ERROR_SNIPPET_BYTES;
+    // UTF-8 uses at most three bytes per UTF-16 code unit. Most diagnostics are
+    // short ASCII, so avoid an allocation only to prove they fit.
+    if (normalized.length * 3 <= contentLimit) {
+        return sourceTruncated ? `${normalized}${ERROR_SNIPPET_ELLIPSIS}` : normalized;
+    }
+    const encoded = TEXT_ENCODER.encode(normalized);
+    if (encoded.byteLength <= contentLimit) {
+        return sourceTruncated ? `${normalized}${ERROR_SNIPPET_ELLIPSIS}` : normalized;
+    }
+    let end = MAX_ERROR_SNIPPET_BYTES - ERROR_SNIPPET_ELLIPSIS_BYTES;
+    // Do not split a multi-byte UTF-8 sequence at the cap.
+    while (end > 0 && (encoded[end] & 0xc0) === 0x80)
+        end--;
+    return `${TEXT_DECODER.decode(encoded.subarray(0, end))}${ERROR_SNIPPET_ELLIPSIS}`;
+}
+/** Keep server identifiers useful as exact machine-readable discriminants. */
+export function boundedErrorIdentifier(value) {
+    if (typeof value !== "string" || value.length > MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS) {
+        return undefined;
+    }
+    const normalized = normalizedErrorSnippet(value);
+    if (normalized === undefined ||
+        normalized !== value ||
+        TEXT_ENCODER.encode(value).byteLength > MAX_ERROR_SNIPPET_BYTES) {
+        return undefined;
+    }
+    return value;
+}
+/** Keep only the documented retained metadata, with bounded wire values. */
+export function boundedTombstone(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const timestamp = boundedErrorIdentifier(raw.tombstoned_at);
+    if (timestamp === undefined ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(timestamp) ||
+        !Number.isFinite(Date.parse(timestamp)))
+        return undefined;
+    const out = { tombstoned_at: timestamp };
+    const count = raw.final_access_count;
+    // The API omits zero: absence means no snapshot or a redacted count.
+    if (typeof count === "number" && Number.isSafeInteger(count) && count >= 1) {
+        out.final_access_count = count;
+    }
+    return out;
+}
+/** Collect at most the first N enumerable own string keys without a full key-array copy. */
+function firstEnumerableOwnKeys(value, limit) {
+    const keys = [];
+    for (const key in value) {
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+            continue;
+        keys.push(key);
+        if (keys.length === limit)
+            break;
+    }
+    return keys;
+}
+/** Bound the structured per-field diagnostics exposed on ValidationError. */
+export function boundedInvalidFields(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const entries = [];
+    const retainedKeys = new Set();
+    let retainedBytes = 0;
+    // Bound inspected entries as well as retained entries. A hostile envelope
+    // whose values all have the wrong type must not make diagnostics scan every
+    // key in the response body.
+    for (const rawKey of firstEnumerableOwnKeys(value, MAX_INVALID_FIELD_ENTRIES)) {
+        const rawValue = value[rawKey];
+        const key = boundedErrorSnippet(rawKey);
+        const fieldDetail = boundedErrorSnippet(rawValue);
+        if (key !== undefined && fieldDetail !== undefined && !retainedKeys.has(key)) {
+            const entryBytes = TEXT_ENCODER.encode(key).byteLength + TEXT_ENCODER.encode(fieldDetail).byteLength;
+            // A later, smaller entry can still fit even when this one cannot.
+            if (retainedBytes + entryBytes > MAX_DIAGNOSTIC_COLLECTION_BYTES)
+                continue;
+            retainedKeys.add(key);
+            entries.push([key, fieldDetail]);
+            retainedBytes += entryBytes;
+        }
+    }
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+/** Bound server-controlled object keys before forwarding them to a debug sink. */
+export function boundedObjectKeys(value) {
+    // Stop before normalization so a hostile envelope cannot force work over
+    // every enumerable own key. Some early keys may normalize away; bounded
+    // diagnostics are more important here than filling every available slot.
+    const retained = [];
+    let retainedBytes = 0;
+    for (const rawKey of firstEnumerableOwnKeys(value, MAX_DEBUG_BODY_KEYS)) {
+        const key = boundedErrorSnippet(rawKey);
+        if (key === undefined)
+            continue;
+        const keyBytes = TEXT_ENCODER.encode(key).byteLength;
+        // A later, smaller key can still fit even when this one cannot.
+        if (retainedBytes + keyBytes > MAX_DIAGNOSTIC_COLLECTION_BYTES)
+            continue;
+        retained.push(key);
+        retainedBytes += keyBytes;
+    }
+    return retained;
+}

package/dist/esm/client-http-types.d.ts

@@ -0,0 +1,37 @@
+export interface ApiResponse<T> {
+    data: T;
+    meta?: {
+        found_existing?: unknown;
+        request_id?: string;
+        page_size?: number;
+        has_more?: boolean;
+        next_cursor?: string;
+    };
+}
+export interface HttpResponse<T> {
+    envelope: ApiResponse<T>;
+    status: number;
+    bodyEmpty: boolean;
+    headers?: Headers;
+}
+export interface ApiErrorEnvelope {
+    error?: {
+        type?: string;
+        title?: string;
+        status?: number;
+        detail?: string;
+        code?: string;
+        instance?: string;
+        invalid_fields?: Record<string, string>;
+        /**
+         * Legacy field from pre-RFC-7807 error shapes. Supported for backward
+         * compatibility when the API has been configured to return the older
+         * `{ error: { code, message } }` envelope.
+         */
+        message?: string;
+    };
+    meta?: {
+        request_id?: string;
+        tombstone?: unknown;
+    };
+}

package/dist/esm/client-http-types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/client-input-fields.d.ts

@@ -0,0 +1,53 @@
+/** Allowlist of known query-param keys for the `list()` endpoint. */
+export declare const LIST_PARAM_KEYS: readonly ["limit", "cursor", "status", "q", "sort", "created_after", "created_before", "expires_before", "expires_after"];
+export declare const REQUEST_OPTION_KEYS: readonly ["idempotencyKey"];
+export declare const DELEGATED_BATCH_INPUT_KEYS: readonly ["mint_capability", "grants"];
+export declare const DELEGATED_BATCH_GRANT_KEYS: readonly ["expires_in", "label", "one_time_use", "max_sessions", "session_duration", "access_policy"];
+export declare const DELEGATED_BATCH_CREATE_OPTION_KEYS: readonly ["idempotencyKey"];
+export declare const DELEGATED_BATCH_GET_OPTION_KEYS: readonly ["etag"];
+export declare function assertExhaustive<T extends true>(_: T): void;
+export declare const CREATE_FIELD_KEYS: readonly ["name", "private", "type", "target_url", "expires_in", "one_time_use", "max_sessions", "session_duration", "label", "access_policy", "custom_domain"];
+/**
+ * Fields accepted by `update()`. The empty-input pre-flight check in
+ * {@link QURLClient.update} iterates this const — so adding a new field to
+ * {@link UpdateInput} without listing it here will fail the
+ * paired `assertExhaustive` witness at compile time rather than silently
+ * sneaking through an empty-input request.
+ */
+export declare const UPDATE_FIELD_KEYS: readonly ["extend_by", "expires_at", "description", "tags"];
+/**
+ * Fields accepted by `mintLink()`. Iterated by the null-stripping
+ * normalization loop in {@link QURLClient.mintLink} so unknown keys
+ * from untyped-JS callers don't leak through to the wire body.
+ * Symmetric with `LIST_PARAM_KEYS` / `UPDATE_FIELD_KEYS`.
+ */
+export declare const MINT_FIELD_KEYS: readonly ["expires_in", "expires_at", "label", "one_time_use", "max_sessions", "session_duration", "access_policy"];
+export declare const RESOURCE_LIST_PARAM_KEYS: readonly ["cursor", "limit", "alias", "slug", "status", "type"];
+export declare const CREATE_RESOURCE_FIELD_KEYS: readonly ["name", "private", "consumer_access", "type", "target_url", "description", "tags", "custom_domain", "alias", "slug", "find_or_create"];
+export declare const UPDATE_RESOURCE_FIELD_KEYS: readonly ["allowed_device_keys_add", "allowed_device_keys_remove", "consumer_access", "expected_consumer_access_version", "description", "tags", "custom_domain", "preserve_host", "alias"];
+export declare const CREATE_QURL_FOR_RESOURCE_FIELD_KEYS: readonly ["expires_in", "one_time_use", "max_sessions", "session_duration", "label", "access_policy", "target_path"];
+export declare const SHARE_RESOURCE_OPTION_KEYS: readonly ["ttlSeconds"];
+/**
+ * Options accepted by the portal-verb `protectUrl` / `createPortal`
+ * surface. These are camelCase caller-facing options (the portal verbs are
+ * the idiomatic layer); the build helpers map them onto the same wire
+ * fields the REST-shaped methods send.
+ */
+export declare const PROTECT_URL_OPTION_KEYS: readonly ["name", "private", "consumerAccess", "description", "tags", "customDomain", "alias"];
+export declare const CREATE_PORTAL_OPTION_KEYS: readonly ["name", "validFor", "label", "oneTimeUse", "maxSessions", "sessionDuration", "targetPath"];
+export declare const UPDATE_RESOURCE_QURL_FIELD_KEYS: readonly ["extend_by", "expires_at", "label", "access_policy", "max_sessions", "session_duration"];
+export declare const UPDATE_CUSTOMER_FIELD_KEYS: readonly ["spending_cap_cents"];
+export declare const CREATE_BILLING_CHECKOUT_FIELD_KEYS: readonly ["plan"];
+export declare const REGISTER_DOMAIN_FIELD_KEYS: readonly ["domain"];
+export declare const CREATE_WEBHOOK_FIELD_KEYS: readonly ["url", "events", "description"];
+export declare const UPDATE_WEBHOOK_FIELD_KEYS: readonly ["url", "events", "description", "status"];
+export declare const CREATE_API_KEY_FIELD_KEYS: readonly ["kind", "name", "scopes", "target", "claims", "expires_in"];
+export declare const UPDATE_API_KEY_FIELD_KEYS: readonly ["name", "scopes"];
+export declare const REDEEM_ACCESS_CODE_FIELD_KEYS: readonly ["code", "honeypot", "elapsed_ms"];
+export declare const CREATE_ACCESS_CODE_FIELD_KEYS: readonly ["resource_id", "name", "max_uses", "expires_at"];
+export declare const CONNECTOR_INSTALLATION_LIST_PARAM_KEYS: readonly ["cursor", "limit"];
+export declare const BILLING_INVOICE_LIST_PARAM_KEYS: readonly ["limit", "cursor"];
+export declare const DOMAIN_LIST_PARAM_KEYS: readonly ["limit", "cursor"];
+export declare const WEBHOOK_LIST_PARAM_KEYS: readonly ["limit", "cursor"];
+export declare const WEBHOOK_DELIVERY_LIST_PARAM_KEYS: readonly ["limit", "cursor"];
+export declare const API_KEY_LIST_PARAM_KEYS: readonly ["limit", "cursor", "status"];

package/dist/esm/client-input-fields.js

@@ -0,0 +1,258 @@
+/** Allowlist of known query-param keys for the `list()` endpoint. */
+export const LIST_PARAM_KEYS = [
+    "limit",
+    "cursor",
+    "status",
+    "q",
+    "sort",
+    "created_after",
+    "created_before",
+    "expires_before",
+    "expires_after",
+];
+export const REQUEST_OPTION_KEYS = [
+    "idempotencyKey",
+];
+export const DELEGATED_BATCH_INPUT_KEYS = [
+    "mint_capability",
+    "grants",
+];
+export const DELEGATED_BATCH_GRANT_KEYS = [
+    "expires_in",
+    "label",
+    "one_time_use",
+    "max_sessions",
+    "session_duration",
+    "access_policy",
+];
+export const DELEGATED_BATCH_CREATE_OPTION_KEYS = [
+    "idempotencyKey",
+];
+export const DELEGATED_BATCH_GET_OPTION_KEYS = [
+    "etag",
+];
+// Compile-time witness: `Exclude<keyof X, (typeof KEYS)[number]>` is
+// `never` iff KEYS lists every key of X. Paired with the
+// `satisfies readonly (keyof X)[]` clause on the array (which catches
+// the other direction), this gives bidirectional drift detection on
+// the *_KEYS allowlists at zero runtime cost.
+export function assertExhaustive(_) {
+    /* type-only check */
+}
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+export const CREATE_FIELD_KEYS = [
+    "name",
+    "private",
+    "type",
+    "target_url",
+    "expires_in",
+    "one_time_use",
+    "max_sessions",
+    "session_duration",
+    "label",
+    "access_policy",
+    "custom_domain",
+];
+assertExhaustive(true);
+/**
+ * Fields accepted by `update()`. The empty-input pre-flight check in
+ * {@link QURLClient.update} iterates this const — so adding a new field to
+ * {@link UpdateInput} without listing it here will fail the
+ * paired `assertExhaustive` witness at compile time rather than silently
+ * sneaking through an empty-input request.
+ */
+export const UPDATE_FIELD_KEYS = [
+    "extend_by",
+    "expires_at",
+    "description",
+    "tags",
+];
+assertExhaustive(true);
+/**
+ * Fields accepted by `mintLink()`. Iterated by the null-stripping
+ * normalization loop in {@link QURLClient.mintLink} so unknown keys
+ * from untyped-JS callers don't leak through to the wire body.
+ * Symmetric with `LIST_PARAM_KEYS` / `UPDATE_FIELD_KEYS`.
+ */
+export const MINT_FIELD_KEYS = [
+    "expires_in",
+    "expires_at",
+    "label",
+    "one_time_use",
+    "max_sessions",
+    "session_duration",
+    "access_policy",
+];
+assertExhaustive(true);
+export const RESOURCE_LIST_PARAM_KEYS = [
+    "cursor",
+    "limit",
+    "alias",
+    "slug",
+    "status",
+    "type",
+];
+assertExhaustive(true);
+export const CREATE_RESOURCE_FIELD_KEYS = [
+    "name",
+    "private",
+    "consumer_access",
+    "type",
+    "target_url",
+    "description",
+    "tags",
+    "custom_domain",
+    "alias",
+    "slug",
+    "find_or_create",
+];
+assertExhaustive(true);
+export const UPDATE_RESOURCE_FIELD_KEYS = [
+    "allowed_device_keys_add",
+    "allowed_device_keys_remove",
+    "consumer_access",
+    "expected_consumer_access_version",
+    "description",
+    "tags",
+    "custom_domain",
+    "preserve_host",
+    "alias",
+];
+assertExhaustive(true);
+export const CREATE_QURL_FOR_RESOURCE_FIELD_KEYS = [
+    "expires_in",
+    "one_time_use",
+    "max_sessions",
+    "session_duration",
+    "label",
+    "access_policy",
+    "target_path",
+];
+export const SHARE_RESOURCE_OPTION_KEYS = [
+    "ttlSeconds",
+];
+assertExhaustive(true);
+assertExhaustive(true);
+/**
+ * Options accepted by the portal-verb `protectUrl` / `createPortal`
+ * surface. These are camelCase caller-facing options (the portal verbs are
+ * the idiomatic layer); the build helpers map them onto the same wire
+ * fields the REST-shaped methods send.
+ */
+export const PROTECT_URL_OPTION_KEYS = [
+    "name",
+    "private",
+    "consumerAccess",
+    "description",
+    "tags",
+    "customDomain",
+    "alias",
+];
+assertExhaustive(true);
+export const CREATE_PORTAL_OPTION_KEYS = [
+    "name",
+    "validFor",
+    "label",
+    "oneTimeUse",
+    "maxSessions",
+    "sessionDuration",
+    "targetPath",
+];
+assertExhaustive(true);
+export const UPDATE_RESOURCE_QURL_FIELD_KEYS = [
+    "extend_by",
+    "expires_at",
+    "label",
+    "access_policy",
+    "max_sessions",
+    "session_duration",
+];
+assertExhaustive(true);
+export const UPDATE_CUSTOMER_FIELD_KEYS = [
+    "spending_cap_cents",
+];
+assertExhaustive(true);
+export const CREATE_BILLING_CHECKOUT_FIELD_KEYS = [
+    "plan",
+];
+assertExhaustive(true);
+export const REGISTER_DOMAIN_FIELD_KEYS = [
+    "domain",
+];
+assertExhaustive(true);
+export const CREATE_WEBHOOK_FIELD_KEYS = [
+    "url",
+    "events",
+    "description",
+];
+assertExhaustive(true);
+export const UPDATE_WEBHOOK_FIELD_KEYS = [
+    "url",
+    "events",
+    "description",
+    "status",
+];
+assertExhaustive(true);
+export const CREATE_API_KEY_FIELD_KEYS = [
+    "kind",
+    "name",
+    "scopes",
+    "target",
+    "claims",
+    "expires_in",
+];
+assertExhaustive(true);
+export const UPDATE_API_KEY_FIELD_KEYS = [
+    "name",
+    "scopes",
+];
+assertExhaustive(true);
+export const REDEEM_ACCESS_CODE_FIELD_KEYS = [
+    "code",
+    "honeypot",
+    "elapsed_ms",
+];
+assertExhaustive(true);
+export const CREATE_ACCESS_CODE_FIELD_KEYS = [
+    "resource_id",
+    "name",
+    "max_uses",
+    "expires_at",
+];
+assertExhaustive(true);
+export const CONNECTOR_INSTALLATION_LIST_PARAM_KEYS = [
+    "cursor",
+    "limit",
+];
+assertExhaustive(true);
+export const BILLING_INVOICE_LIST_PARAM_KEYS = [
+    "limit",
+    "cursor",
+];
+assertExhaustive(true);
+export const DOMAIN_LIST_PARAM_KEYS = [
+    "limit",
+    "cursor",
+];
+assertExhaustive(true);
+export const WEBHOOK_LIST_PARAM_KEYS = [
+    "limit",
+    "cursor",
+];
+assertExhaustive(true);
+export const WEBHOOK_DELIVERY_LIST_PARAM_KEYS = [
+    "limit",
+    "cursor",
+];
+assertExhaustive(true);
+export const API_KEY_LIST_PARAM_KEYS = [
+    "limit",
+    "cursor",
+    "status",
+];
+assertExhaustive(true);

package/dist/esm/client-limits.d.ts

@@ -0,0 +1,36 @@
+export declare const MAX_RESPONSE_BODY_BYTES: number;
+export declare const MAX_CONFIGURABLE_RESPONSE_BODY_BYTES: number;
+export declare const MAX_ERROR_SNIPPET_BYTES = 512;
+export declare const MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS = 512;
+export declare const MAX_INVALID_FIELD_ENTRIES = 100;
+export declare const MAX_DEBUG_BODY_KEYS = 100;
+export declare const MAX_DIAGNOSTIC_COLLECTION_BYTES: number;
+export declare const RETRY_BASE_DELAY_MS = 500;
+export declare const RETRY_MAX_DELAY_MS = 30000;
+export declare const RETRY_AFTER_HARD_CAP_MS: number;
+export declare const RETRY_AFTER_PARSE_LIMIT_S: number;
+export declare const MAX_IDEMPOTENCY_KEY = 256;
+export declare const MAX_TARGET_URL = 2048;
+export declare const MAX_LABEL = 500;
+export declare const MAX_BATCH_ITEMS = 100;
+export declare const MAX_DESCRIPTION = 500;
+/** Code points, matching qurl-service ValidatePreviewName. */
+export declare const MAX_RESOURCE_NAME = 100;
+export declare const MAX_CUSTOM_DOMAIN = 253;
+export declare const MAX_MAX_SESSIONS = 1000;
+export declare const MAX_API_KEY_NAME = 100;
+export declare const MAX_ENROLLMENT_TOKEN_TTL_SECONDS = 86400n;
+export declare const MAX_ALIAS = 64;
+export declare const MAX_SLUG = 64;
+export declare const MAX_TARGET_PATH = 2048;
+export declare const MAX_TAGS = 10;
+export declare const MAX_TAG_LENGTH = 50;
+export declare const MAX_AUTO_PAGINATION_PAGES = 10000;
+export declare const MAX_DELEGATED_MINT_CAPABILITY = 8192;
+export declare const MAX_DELEGATED_ETAG = 96;
+export declare const MAX_DELEGATED_BATCH_ITEMS = 100;
+export declare const MAX_PATH_ID_DECODE_PASSES = 3;
+export declare const MAX_PATH_ID_LENGTH = 4096;
+export declare const MAX_ALLOWED_DEVICE_KEYS = 256;
+export declare const MAX_LIST_LIMIT = 100;
+export declare const MAX_CONSUMER_CONTRACT_ID_BYTES = 128;

package/dist/esm/client-limits.js

@@ -0,0 +1,58 @@
+// Joint Go/TypeScript policy: docs/api-response-limits.md.
+// Keep the 1 MiB default and bounded opt-in ceiling aligned across both SDKs.
+// Decoded streaming bytes remain authoritative when length hints are unusable.
+export const MAX_RESPONSE_BODY_BYTES = 1 << 20;
+export const MAX_CONFIGURABLE_RESPONSE_BODY_BYTES = 16 << 20;
+export const MAX_ERROR_SNIPPET_BYTES = 512;
+// UTF-8 uses at least one byte per UTF-16 code unit. Reading more source units
+// cannot add a byte that fits in a 512-byte retained diagnostic.
+export const MAX_ERROR_SNIPPET_SOURCE_CODE_UNITS = MAX_ERROR_SNIPPET_BYTES;
+export const MAX_INVALID_FIELD_ENTRIES = 100;
+export const MAX_DEBUG_BODY_KEYS = 100;
+// Bound each retained diagnostic collection as well as each string. Without
+// this aggregate cap, 100 valid 512-byte keys and values could turn a small
+// server error into a large caller-visible object. This is a diagnostic budget,
+// not part of the API wire contract.
+export const MAX_DIAGNOSTIC_COLLECTION_BYTES = 8 << 10;
+export const RETRY_BASE_DELAY_MS = 500;
+// Bounds local exponential backoff (NOT server-asserted Retry-After —
+// see `RETRY_AFTER_HARD_CAP_MS` for that).
+export const RETRY_MAX_DELAY_MS = 30_000;
+// Hard cap on server-asserted Retry-After. Guards against `Retry-After`
+// values >2^31-1 ms overflowing Node's setTimeout (silently truncated to
+// 1ms — turns a "wait a month" directive into a hot retry loop).
+export const RETRY_AFTER_HARD_CAP_MS = 60 * 60 * 1000;
+export const RETRY_AFTER_PARSE_LIMIT_S = RETRY_AFTER_HARD_CAP_MS / 1000;
+export const MAX_IDEMPOTENCY_KEY = 256;
+// ---- Spec-derived validation helpers ------------------------------------
+// These mirror constraints documented on each request schema in
+// `openapi.yaml` so obvious mistakes fail fast instead of round-tripping
+// to the API and coming back as a generic 400.
+// CI checks every MAX_* constant against contract/validation-bounds.json; the
+// weekly published-spec check detects upstream changes. Local safety budgets
+// are classified separately and must not be raised to bypass a service cap.
+export const MAX_TARGET_URL = 2048;
+export const MAX_LABEL = 500;
+export const MAX_BATCH_ITEMS = 100;
+export const MAX_DESCRIPTION = 500;
+/** Code points, matching qurl-service ValidatePreviewName. */
+export const MAX_RESOURCE_NAME = 100;
+export const MAX_CUSTOM_DOMAIN = 253;
+export const MAX_MAX_SESSIONS = 1000;
+export const MAX_API_KEY_NAME = 100;
+export const MAX_ENROLLMENT_TOKEN_TTL_SECONDS = 86400n;
+export const MAX_ALIAS = 64;
+export const MAX_SLUG = 64;
+export const MAX_TARGET_PATH = 2048;
+export const MAX_TAGS = 10;
+export const MAX_TAG_LENGTH = 50;
+export const MAX_AUTO_PAGINATION_PAGES = 10_000;
+export const MAX_DELEGATED_MINT_CAPABILITY = 8192;
+export const MAX_DELEGATED_ETAG = 96;
+export const MAX_DELEGATED_BATCH_ITEMS = 100;
+export const MAX_PATH_ID_DECODE_PASSES = 3;
+export const MAX_PATH_ID_LENGTH = 4096;
+export const MAX_ALLOWED_DEVICE_KEYS = 256;
+export const MAX_LIST_LIMIT = 100;
+// Local UTF-8 budget; OpenAPI maxLength counts characters, not bytes.
+export const MAX_CONSUMER_CONTRACT_ID_BYTES = 128;

package/dist/esm/client-management.d.ts

@@ -0,0 +1,12 @@
+import type { ApiKeyRequestScope } from "./types.js";
+/** Narrow a response scope before reusing it in a create/update request. */
+export declare function isApiKeyRequestScope(scope: string): scope is ApiKeyRequestScope;
+export declare function validateWebhookWriteFields(input: Record<string, unknown>, method: string, requiredFields?: {
+    url?: boolean;
+    events?: boolean;
+}): void;
+export declare function validateApiKeyWriteFields(input: Record<string, unknown>, method: string, requiredFields?: {
+    name?: boolean;
+    scopes?: boolean;
+}): void;
+export declare function validateEnrollmentTokenFields(input: Record<string, unknown>, method: string): void;