@layervai/qurl 3.1.0 → 4.0.0

package/dist/esm/client-connectors.js

@@ -0,0 +1,180 @@
+import { getResponseMetadata } from "./response-metadata.js";
+import { ConnectorResourceOutcomeUnknownError, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, QURLError, RuntimeError, } from "./errors.js";
+import { cridKeyMatches } from "./crid.js";
+import { clientValidationError, unexpectedResponseError } from "./client-errors.js";
+import { containsControlCharacter } from "./client-validation.js";
+// Keep these identity contracts aligned with qurl-go and the public API.
+export const CONNECTOR_SLUG_PATTERN = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
+// Current service schemas intentionally share this grammar, but keep the
+// mutable alias contract separate from the immutable lookup identity.
+const CONNECTOR_ALIAS_PATTERN = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
+const CONNECTOR_RESOURCE_ID_PATTERN = /^[A-Za-z0-9_-]{122}$/;
+const CONNECTOR_RESOURCE_ID_DER_PREFIX = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE";
+const CONNECTOR_ROUTING_ID_PATTERN = /^c-[a-z2-7]{51}[aq]$/;
+export function requireConnectorSlug(slug, method) {
+    if (typeof slug !== "string" || !CONNECTOR_SLUG_PATTERN.test(slug)) {
+        throw clientValidationError(`${method}: slug must be 3-64 lowercase alphanumeric or hyphen characters, start with a letter, and end alphanumeric`);
+    }
+}
+export function classifyConnectorMutationFailure(operation, error) {
+    if (!(error instanceof QURLError)) {
+        throw new ConnectorResourceOutcomeUnknownError(new RuntimeError("Unexpected failure after Connector mutation dispatch", { cause: error }));
+    }
+    // Most authoritative 4xx responses prove that the mutation was rejected.
+    // bootstrap_key_consumed is the exception: the service returns it from the
+    // consume phase after the resource may have been bound or found.
+    // Callers perform argument/runtime preflight outside their mutation try
+    // blocks; every other surfaced failure therefore follows dispatch or a
+    // nominal success whose resource contract could not be consumed, so callers
+    // must reconcile before retrying. Ensure's exact 201 + valid resource but
+    // missing found_existing is handled after this classifier: the row proves
+    // the selected resource, while only its required metadata is unavailable.
+    if (operation === "ensure" && error.status === 409 && error.code === "bootstrap_key_consumed") {
+        throw new ConnectorResourceOutcomeUnknownError(error);
+    }
+    if (error.status >= 400 && error.status < 500) {
+        throw error;
+    }
+    throw new ConnectorResourceOutcomeUnknownError(error);
+}
+function decodeCanonicalBase64Url(value) {
+    if (!CONNECTOR_RESOURCE_ID_PATTERN.test(value) ||
+        !value.startsWith(CONNECTOR_RESOURCE_ID_DER_PREFIX)) {
+        return undefined;
+    }
+    try {
+        const padded = value.replace(/-/g, "+").replace(/_/g, "/") + "==";
+        const binary = atob(padded);
+        const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+        const canonical = btoa(String.fromCharCode(...bytes))
+            .replace(/\+/g, "-")
+            .replace(/\//g, "_")
+            .replace(/=+$/, "");
+        return canonical === value ? bytes : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function requireConnectorSubtleCrypto(method) {
+    if (!globalThis.crypto?.subtle) {
+        throw new RuntimeError(`${method}: requires the Web Crypto SubtleCrypto API`);
+    }
+}
+async function importsAsConnectorPublicKey(der) {
+    try {
+        const keyData = new ArrayBuffer(der.byteLength);
+        new Uint8Array(keyData).set(der);
+        await globalThis.crypto.subtle.importKey("spki", keyData, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function verifyResourceIdentity(resource, method, expectedCrid) {
+    const errorOptions = { requestId: getResponseMetadata(resource)?.requestId };
+    if (!resource || typeof resource.resource_id !== "string") {
+        throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`, errorOptions);
+    }
+    const resourceKey = decodeCanonicalBase64Url(resource.resource_id);
+    requireConnectorSubtleCrypto(method);
+    if (!resourceKey || !(await importsAsConnectorPublicKey(resourceKey))) {
+        throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`, errorOptions);
+    }
+    if (expectedCrid !== undefined && resource.crid !== expectedCrid) {
+        throw unexpectedResponseError(`${method}: response crid does not match the request`, errorOptions);
+    }
+    if (!(await cridKeyMatches(resource.crid, resourceKey))) {
+        throw unexpectedResponseError(`${method}: response has missing, invalid, or public-key-mismatched crid`, errorOptions);
+    }
+}
+export async function parseConnectorResource(client, value, method, expectation = {}) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw unexpectedResponseError(`${method}: response is missing connector resource data`);
+    }
+    const resource = value;
+    await verifyResourceIdentity(resource, method, expectation.crid);
+    if (typeof resource.connector_routing_id !== "string" ||
+        !CONNECTOR_ROUTING_ID_PATTERN.test(resource.connector_routing_id)) {
+        throw unexpectedResponseError(`${method}: response has missing or invalid connector_routing_id`);
+    }
+    if (typeof resource.knock_resource_id !== "string" ||
+        resource.knock_resource_id.trim() === "" ||
+        resource.knock_resource_id.trim() !== resource.knock_resource_id ||
+        containsControlCharacter(resource.knock_resource_id)) {
+        throw unexpectedResponseError(`${method}: response has missing or invalid knock_resource_id`);
+    }
+    if (resource.resource_id === resource.knock_resource_id ||
+        resource.connector_routing_id === resource.knock_resource_id) {
+        throw unexpectedResponseError(`${method}: response cross-wires resource identity, routing, and admission values`);
+    }
+    if (resource.type !== "tunnel") {
+        throw unexpectedResponseError(`${method}: response resource type is not tunnel`);
+    }
+    if (typeof resource.slug !== "string" || !CONNECTOR_SLUG_PATTERN.test(resource.slug)) {
+        throw unexpectedResponseError(`${method}: response has missing or invalid slug`);
+    }
+    if (expectation.slug !== undefined && resource.slug !== expectation.slug) {
+        throw unexpectedResponseError(`${method}: response slug does not match the request`);
+    }
+    if (resource.alias !== undefined &&
+        resource.alias !== null &&
+        (typeof resource.alias !== "string" || !CONNECTOR_ALIAS_PATTERN.test(resource.alias))) {
+        // The public API intentionally gives mutable aliases and immutable slugs the
+        // same canonical wire grammar (domain aliasPattern/slugPattern). Keeping
+        // response validation aligned avoids accepting a row the service itself
+        // could not create or update.
+        throw unexpectedResponseError(`${method}: response has invalid alias`);
+    }
+    if (resource.status === "revoked") {
+        if (expectation.revokedIsLifecycleError !== true) {
+            throw unexpectedResponseError(`${method}: active-only operation returned a revoked connector resource`);
+        }
+        throw new QURLError({
+            status: 0,
+            code: ERROR_CODE_CONNECTOR_RESOURCE_REVOKED,
+            title: "Connector Resource Revoked",
+            detail: `${method}: qURL Connector resource is revoked`,
+        });
+    }
+    if (resource.status !== "active") {
+        throw unexpectedResponseError(`${method}: response has invalid resource status`);
+    }
+    return new ConnectorResource(client, resource, CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN);
+}
+const CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN = Symbol("validated ConnectorResource");
+/**
+ * A validated qURL Connector resource bound to the client that loaded it.
+ *
+ * Resource identity, reverse-routing identity, and NHP admission identity are
+ * distinct server-issued values. Callers must consume each field verbatim and
+ * must never derive one from another.
+ */
+export class ConnectorResource {
+    #client;
+    resourcePublicKey;
+    /** Required public identifier, verified against the returned resource key. */
+    crid;
+    connectorRoutingId;
+    knockResourceId;
+    slug;
+    alias;
+    /** @internal Instances are returned by QURLClient after wire validation. */
+    constructor(client, details, validationToken) {
+        if (validationToken !== CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN) {
+            throw clientValidationError("ConnectorResource cannot be constructed directly; load it through QURLClient");
+        }
+        this.#client = client;
+        this.resourcePublicKey = details.resource_id;
+        this.crid = details.crid;
+        this.connectorRoutingId = details.connector_routing_id;
+        this.knockResourceId = details.knock_resource_id;
+        this.slug = details.slug;
+        this.alias = details.alias ?? undefined;
+    }
+    /** Mint a short-lived portal for this Connector resource. */
+    async createPortal(opts = {}, requestOptions) {
+        return this.#client.createPortal(this.crid, opts, requestOptions);
+    }
+}

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

@@ -0,0 +1,30 @@
+import type { CreateDelegatedQurlBatchInput, CreateDelegatedQurlBatchOptions, DelegatedQurl, DelegatedQurlBatchItemResult, GetDelegatedQurlBatchOptions } from "./types.js";
+import { ValidationError } from "./errors.js";
+import type { HttpResponse } from "./client-http-types.js";
+export declare const DELEGATED_BATCH_ID_PATTERN: RegExp;
+export declare const DELEGATED_QURL_ID_PATTERN: RegExp;
+export declare const STRONG_ETAG_PATTERN: RegExp;
+export declare function validateCreateDelegatedQurlBatchInput(input: unknown): asserts input is CreateDelegatedQurlBatchInput;
+export declare function validateDelegatedBatchCreateOptions(options: unknown): asserts options is CreateDelegatedQurlBatchOptions;
+export declare function validateGetDelegatedQurlBatchOptions(options: unknown): asserts options is GetDelegatedQurlBatchOptions | undefined;
+export declare function delegatedResponseError(status: number, detail: string, requestId?: string): ValidationError;
+export declare function delegatedEnvelope(response: HttpResponse<unknown>, status: number): {
+    data: Record<string, unknown>;
+    requestId: string;
+};
+export declare function requiredDelegatedHeader(response: HttpResponse<unknown>, name: string, status: number, requestId?: string): string;
+export declare function hasDelegatedNoStore(value: string | null): boolean;
+export declare function delegatedResponseHeaders(response: HttpResponse<unknown>, status: number, requestId?: string): {
+    etag?: string;
+    retryAfter?: number;
+};
+export declare function isUtcTimestamp(value: unknown): value is string;
+export declare function delegatedBatchBase(data: Record<string, unknown>, status: number, requestId: string, expectedBatchId?: string): {
+    batchId: string;
+    itemCount: number;
+    submittedAt: string;
+};
+export declare function validateDelegatedLocation(value: string, baseUrl: string, batchId: string, status: number, requestId: string): string;
+export declare function validateDelegatedQurl(value: unknown, expectedQurlId: string, status: number, requestId: string): DelegatedQurl;
+export declare function validateDelegatedBatchResults(value: unknown, itemCount: number, batchStatus: "succeeded" | "partially_failed" | "failed", status: number, requestId: string): DelegatedQurlBatchItemResult[];
+export declare function classifyDelegatedBatchCreateFailure(error: unknown, batchId?: string): never;

package/dist/esm/client-delegated.js

@@ -0,0 +1,295 @@
+import { DelegatedBatchOutcomeUnknownError, QURLError, RuntimeError, } from "./errors.js";
+import { clientValidationError, unexpectedResponseError } from "./client-errors.js";
+import { describeShape, requireBooleanIfPresent, requireMaxSessionsInRange, requireMaxUtf8Bytes, requireNoUnknownFields, requireValidAccessPolicy, } from "./client-validation.js";
+import { DELEGATED_BATCH_CREATE_OPTION_KEYS, DELEGATED_BATCH_GET_OPTION_KEYS, DELEGATED_BATCH_GRANT_KEYS, DELEGATED_BATCH_INPUT_KEYS, } from "./client-input-fields.js";
+import { MAX_DELEGATED_BATCH_ITEMS, MAX_DELEGATED_ETAG, MAX_DELEGATED_MINT_CAPABILITY, MAX_IDEMPOTENCY_KEY, MAX_LABEL, RETRY_AFTER_PARSE_LIMIT_S, } from "./client-limits.js";
+const MIN_DELEGATED_BATCH_IDEMPOTENCY_KEY = 32;
+export const DELEGATED_BATCH_ID_PATTERN = /^dqb_[A-Za-z0-9_-]{22}$/;
+export const DELEGATED_QURL_ID_PATTERN = /^q_[0-9a-f]{11}$/;
+export const STRONG_ETAG_PATTERN = /^"[\x21\x23-\x7e]+"$/;
+const UTC_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+export function validateCreateDelegatedQurlBatchInput(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw clientValidationError(`createDelegatedQurlBatch: input must be an object (got ${describeShape(input)})`);
+    }
+    const typed = input;
+    requireNoUnknownFields(typed, DELEGATED_BATCH_INPUT_KEYS, "createDelegatedQurlBatch");
+    if (typeof typed.mint_capability !== "string" ||
+        typed.mint_capability.length < 1 ||
+        typed.mint_capability.length > MAX_DELEGATED_MINT_CAPABILITY) {
+        throw clientValidationError(`createDelegatedQurlBatch: mint_capability must be a string of 1-${MAX_DELEGATED_MINT_CAPABILITY} characters`);
+    }
+    if (!Array.isArray(typed.grants) ||
+        typed.grants.length < 1 ||
+        typed.grants.length > MAX_DELEGATED_BATCH_ITEMS) {
+        throw clientValidationError(`createDelegatedQurlBatch: grants must contain 1-${MAX_DELEGATED_BATCH_ITEMS} items`);
+    }
+    for (const [index, grant] of typed.grants.entries()) {
+        const field = `createDelegatedQurlBatch: grants[${index}]`;
+        if (typeof grant !== "object" || grant === null || Array.isArray(grant)) {
+            throw clientValidationError(`${field}: must be an object (got ${describeShape(grant)})`);
+        }
+        requireNoUnknownFields(grant, DELEGATED_BATCH_GRANT_KEYS, field);
+        requireMaxUtf8Bytes(grant.label, `${field}.label`, MAX_LABEL);
+        requireBooleanIfPresent(grant.one_time_use, `${field}.one_time_use`);
+        requireMaxSessionsInRange(grant.max_sessions, `${field}.max_sessions`);
+        for (const durationField of ["expires_in", "session_duration"]) {
+            const value = grant[durationField];
+            if (value !== undefined && (typeof value !== "string" || value.length === 0)) {
+                throw clientValidationError(`${field}.${durationField}: must be a non-empty string`);
+            }
+        }
+        if (grant.access_policy !== undefined) {
+            requireValidAccessPolicy(grant.access_policy);
+        }
+    }
+}
+export function validateDelegatedBatchCreateOptions(options) {
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        throw clientValidationError("createDelegatedQurlBatch: options are required");
+    }
+    requireNoUnknownFields(options, DELEGATED_BATCH_CREATE_OPTION_KEYS, "createDelegatedQurlBatch options");
+    const key = options.idempotencyKey;
+    if (typeof key !== "string" ||
+        key.length < MIN_DELEGATED_BATCH_IDEMPOTENCY_KEY ||
+        key.length > MAX_IDEMPOTENCY_KEY ||
+        !/^[!-~]+$/.test(key)) {
+        throw clientValidationError(`createDelegatedQurlBatch: idempotencyKey must contain ${MIN_DELEGATED_BATCH_IDEMPOTENCY_KEY}-${MAX_IDEMPOTENCY_KEY} visible ASCII characters`);
+    }
+}
+export function validateGetDelegatedQurlBatchOptions(options) {
+    if (options === undefined)
+        return;
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        throw clientValidationError(`getDelegatedQurlBatch: options must be an object (got ${describeShape(options)})`);
+    }
+    requireNoUnknownFields(options, DELEGATED_BATCH_GET_OPTION_KEYS, "getDelegatedQurlBatch options");
+    const etag = options.etag;
+    if (etag !== undefined &&
+        (typeof etag !== "string" ||
+            etag.length > MAX_DELEGATED_ETAG ||
+            !STRONG_ETAG_PATTERN.test(etag))) {
+        throw clientValidationError("getDelegatedQurlBatch: etag must be a valid strong ETag");
+    }
+}
+export function delegatedResponseError(status, detail, requestId) {
+    return unexpectedResponseError(`Delegated qURL batch ${detail}`, { status, requestId });
+}
+function delegatedResponseObject(value, status, label, requestId) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw delegatedResponseError(status, `${label} is not an object`, requestId);
+    }
+    return value;
+}
+export function delegatedEnvelope(response, status) {
+    if (typeof response.envelope.meta !== "object" ||
+        response.envelope.meta === null ||
+        Array.isArray(response.envelope.meta)) {
+        throw delegatedResponseError(status, "response meta is not an object");
+    }
+    const meta = response.envelope.meta;
+    if (typeof meta.request_id !== "string") {
+        throw delegatedResponseError(status, "response meta has invalid request_id");
+    }
+    const data = delegatedResponseObject(response.envelope.data, status, "response data", meta.request_id);
+    return { data, requestId: meta.request_id };
+}
+export function requiredDelegatedHeader(response, name, status, requestId) {
+    const headers = response.headers;
+    if (!headers || typeof headers.get !== "function") {
+        throw delegatedResponseError(status, "response headers are unavailable", requestId);
+    }
+    const value = headers.get(name);
+    if (value === null) {
+        throw delegatedResponseError(status, `response is missing ${name}`, requestId);
+    }
+    return value;
+}
+export function hasDelegatedNoStore(value) {
+    if (value === null)
+        return false;
+    const directives = new Set(value.split(",").map((directive) => directive.trim().split("=", 1)[0].toLowerCase()));
+    return directives.has("private") && directives.has("no-store");
+}
+export function delegatedResponseHeaders(response, status, requestId) {
+    const cacheControl = response.headers?.get("Cache-Control") ?? null;
+    if (cacheControl !== null) {
+        if (!hasDelegatedNoStore(cacheControl)) {
+            throw delegatedResponseError(status, "response has invalid Cache-Control", requestId);
+        }
+    }
+    else if (status !== 304) {
+        requiredDelegatedHeader(response, "Cache-Control", status, requestId);
+    }
+    const etag = response.headers?.get("ETag") ?? undefined;
+    if (etag !== undefined && (etag.length > MAX_DELEGATED_ETAG || !STRONG_ETAG_PATTERN.test(etag))) {
+        throw delegatedResponseError(status, "response has invalid strong ETag", requestId);
+    }
+    const rawRetryAfter = response.headers?.get("Retry-After") ?? "";
+    const trimmed = rawRetryAfter.trim();
+    const seconds = /^\d+$/.test(trimmed)
+        ? Number(trimmed)
+        : /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(trimmed)
+            ? Math.ceil((Date.parse(trimmed) - Date.now()) / 1000)
+            : NaN;
+    const retryAfter = Number.isSafeInteger(seconds) && seconds > 0 && seconds <= RETRY_AFTER_PARSE_LIMIT_S
+        ? seconds
+        : undefined;
+    return { etag, retryAfter };
+}
+export function isUtcTimestamp(value) {
+    return (typeof value === "string" &&
+        UTC_TIMESTAMP_PATTERN.test(value) &&
+        Number.isFinite(Date.parse(value)));
+}
+export function delegatedBatchBase(data, status, requestId, expectedBatchId) {
+    if (typeof data.batch_id !== "string" ||
+        !DELEGATED_BATCH_ID_PATTERN.test(data.batch_id) ||
+        (expectedBatchId !== undefined && data.batch_id !== expectedBatchId)) {
+        throw delegatedResponseError(status, "response has invalid batch_id", requestId);
+    }
+    if (!Number.isInteger(data.item_count) ||
+        Number(data.item_count) < 1 ||
+        Number(data.item_count) > MAX_DELEGATED_BATCH_ITEMS) {
+        throw delegatedResponseError(status, "response has invalid item_count", requestId);
+    }
+    if (!isUtcTimestamp(data.submitted_at)) {
+        throw delegatedResponseError(status, "response has invalid submitted_at", requestId);
+    }
+    return {
+        batchId: data.batch_id,
+        itemCount: Number(data.item_count),
+        submittedAt: data.submitted_at,
+    };
+}
+export function validateDelegatedLocation(value, baseUrl, batchId, status, requestId) {
+    let location;
+    try {
+        const base = new URL(`${baseUrl}/`);
+        const relative = value.startsWith("/v1/delegated-qurl-batches/")
+            ? `${base.pathname.replace(/\/$/, "")}${value}`
+            : value;
+        location = new URL(relative, base);
+    }
+    catch {
+        throw delegatedResponseError(status, "response has invalid Location", requestId);
+    }
+    const expected = new URL(`${baseUrl}/v1/delegated-qurl-batches/${batchId}`);
+    if (location.username !== "" ||
+        location.password !== "" ||
+        location.search !== "" ||
+        location.hash !== "" ||
+        location.href !== expected.href) {
+        throw delegatedResponseError(status, "response has invalid Location", requestId);
+    }
+    return location.href;
+}
+function validateDelegatedQurlLink(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const link = new URL(value);
+        return (link.protocol === "https:" &&
+            link.username === "" &&
+            link.password === "" &&
+            link.hash.length > 1);
+    }
+    catch {
+        return false;
+    }
+}
+export function validateDelegatedQurl(value, expectedQurlId, status, requestId) {
+    const data = delegatedResponseObject(value, status, "response data", requestId);
+    if (data.qurl_id !== expectedQurlId) {
+        throw delegatedResponseError(status, "response has invalid qurl_id", requestId);
+    }
+    if (data.status !== "active" &&
+        data.status !== "consumed" &&
+        data.status !== "expired" &&
+        data.status !== "revoked") {
+        throw delegatedResponseError(status, "response has invalid status", requestId);
+    }
+    if (!isUtcTimestamp(data.expires_at) ||
+        typeof data.one_time_use !== "boolean" ||
+        !Number.isInteger(data.max_sessions) ||
+        Number(data.max_sessions) < 0 ||
+        !Number.isInteger(data.session_duration) ||
+        Number(data.session_duration) <= 0 ||
+        (data.label !== undefined && typeof data.label !== "string") ||
+        (data.access_policy !== undefined &&
+            (typeof data.access_policy !== "object" ||
+                data.access_policy === null ||
+                Array.isArray(data.access_policy)))) {
+        throw delegatedResponseError(status, "response has invalid qURL metadata", requestId);
+    }
+    return { ...data, request_id: requestId };
+}
+export function validateDelegatedBatchResults(value, itemCount, batchStatus, status, requestId) {
+    if (!Array.isArray(value) || value.length !== itemCount) {
+        throw delegatedResponseError(status, "terminal response has invalid results", requestId);
+    }
+    let succeeded = 0;
+    const qurlIds = new Set();
+    const links = new Set();
+    const results = value.map((raw, index) => {
+        const item = delegatedResponseObject(raw, status, `result ${index}`, requestId);
+        if (item.index !== index) {
+            throw delegatedResponseError(status, `result ${index} has invalid index`, requestId);
+        }
+        if (item.status === "succeeded") {
+            if (item.error !== undefined && item.error !== null) {
+                throw delegatedResponseError(status, `result ${index} has conflicting fields`, requestId);
+            }
+            const qurl = delegatedResponseObject(item.qurl, status, `result ${index} qurl`, requestId);
+            if (typeof qurl.qurl_id !== "string" ||
+                !DELEGATED_QURL_ID_PATTERN.test(qurl.qurl_id) ||
+                !validateDelegatedQurlLink(qurl.qurl_link) ||
+                !isUtcTimestamp(qurl.expires_at) ||
+                qurlIds.has(qurl.qurl_id) ||
+                links.has(qurl.qurl_link)) {
+                throw delegatedResponseError(status, `result ${index} has invalid qurl`, requestId);
+            }
+            qurlIds.add(qurl.qurl_id);
+            links.add(qurl.qurl_link);
+            succeeded++;
+            return {
+                index,
+                status: "succeeded",
+                qurl: {
+                    qurl_id: qurl.qurl_id,
+                    qurl_link: qurl.qurl_link,
+                    expires_at: qurl.expires_at,
+                },
+            };
+        }
+        if (item.status !== "failed" || (item.qurl !== undefined && item.qurl !== null)) {
+            throw delegatedResponseError(status, `result ${index} has invalid status`, requestId);
+        }
+        const error = delegatedResponseObject(item.error, status, `result ${index} error`, requestId);
+        if (typeof error.code !== "string" ||
+            error.code.length === 0 ||
+            typeof error.message !== "string") {
+            throw delegatedResponseError(status, `result ${index} has invalid error`, requestId);
+        }
+        return {
+            index,
+            status: "failed",
+            error: { code: error.code, message: error.message },
+        };
+    });
+    if ((batchStatus === "succeeded" && succeeded !== itemCount) ||
+        (batchStatus === "failed" && succeeded !== 0) ||
+        (batchStatus === "partially_failed" && (succeeded === 0 || succeeded === itemCount))) {
+        throw delegatedResponseError(status, "terminal status does not match results", requestId);
+    }
+    return results;
+}
+export function classifyDelegatedBatchCreateFailure(error, batchId) {
+    if (!(error instanceof QURLError)) {
+        throw new DelegatedBatchOutcomeUnknownError(new RuntimeError("Unexpected failure after delegated batch dispatch", { cause: error }), batchId);
+    }
+    if ((error.status >= 400 && error.status < 500 && error.status !== 408) || error.status === 501) {
+        throw error;
+    }
+    throw new DelegatedBatchOutcomeUnknownError(error, batchId);
+}

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

@@ -0,0 +1,44 @@
+import { ValidationError } from "./errors.js";
+import type { TombstoneInfo } from "./types.js";
+export declare const TEXT_ENCODER: import("node:util").TextEncoder;
+export declare const TEXT_DECODER: import("node:util").TextDecoder;
+/**
+ * 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 declare function clientValidationError(detail: string): ValidationError;
+/**
+ * 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 declare function unexpectedResponseError(detail: string, options?: {
+    status?: number;
+    requestId?: string;
+}): ValidationError;
+export declare function withErrorCause<T extends Error>(error: T, cause: unknown): T;
+export declare function isIndependentAbort(error: unknown, requestSignal: AbortSignal): boolean;
+export declare function isSdkTimeout(error: unknown, requestSignal: AbortSignal): boolean;
+export declare function boundedErrorSnippet(value: unknown): string | undefined;
+/** Keep server identifiers useful as exact machine-readable discriminants. */
+export declare function boundedErrorIdentifier(value: unknown): string | undefined;
+/** Keep only the documented retained metadata, with bounded wire values. */
+export declare function boundedTombstone(value: unknown): TombstoneInfo | undefined;
+/** Bound the structured per-field diagnostics exposed on ValidationError. */
+export declare function boundedInvalidFields(value: unknown): Record<string, string> | undefined;
+/** Bound server-controlled object keys before forwarding them to a debug sink. */
+export declare function boundedObjectKeys(value: object): string[];