@layervai/qurl 0.7.0 → 2.0.0

package/dist/cjs/client.js

@@ -77,6 +77,7 @@ class ResponseBodyMaterializationError extends Error {
 }
 const NO_PASSTHROUGH_STATUSES = [];
 const BATCH_PASSTHROUGH_STATUSES = [400];
+const DELEGATED_BATCH_PASSTHROUGH_STATUSES = [304];
 /** Allowlist of known query-param keys for the `list()` endpoint. */
 const LIST_PARAM_KEYS = [
     "limit",
@@ -90,6 +91,24 @@ const LIST_PARAM_KEYS = [
     "expires_after",
 ];
 const REQUEST_OPTION_KEYS = ["idempotencyKey"];
+const DELEGATED_BATCH_INPUT_KEYS = [
+    "mint_capability",
+    "grants",
+];
+const DELEGATED_BATCH_GRANT_KEYS = [
+    "expires_in",
+    "label",
+    "one_time_use",
+    "max_sessions",
+    "session_duration",
+    "access_policy",
+];
+const DELEGATED_BATCH_CREATE_OPTION_KEYS = [
+    "idempotencyKey",
+];
+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
@@ -100,6 +119,10 @@ function assertExhaustive(_) {
 }
 assertExhaustive(true);
 assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
 const CREATE_FIELD_KEYS = [
     "type",
     "target_url",
@@ -767,6 +790,14 @@ const MAX_TARGET_PATH = 2048;
 const MAX_TAGS = 10;
 const MAX_TAG_LENGTH = 50;
 const MAX_AUTO_PAGINATION_PAGES = 10_000;
+const MIN_DELEGATED_BATCH_IDEMPOTENCY_KEY = 32;
+const MAX_DELEGATED_MINT_CAPABILITY = 8192;
+const MAX_DELEGATED_ETAG = 96;
+const MAX_DELEGATED_BATCH_ITEMS = 100;
+const DELEGATED_BATCH_ID_PATTERN = /^dqb_[A-Za-z0-9_-]{22}$/;
+const DELEGATED_QURL_ID_PATTERN = /^q_[0-9a-f]{11}$/;
+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$/;
 // Keep these identity contracts aligned with qurl-go and the public API.
 const CONNECTOR_SLUG_PATTERN = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
 // Current service schemas intentionally share this grammar, but keep the
@@ -1252,6 +1283,289 @@ function requireValidAccessPolicy(policy) {
         }
     }
 }
+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);
+        }
+    }
+}
+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`);
+    }
+}
+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");
+    }
+}
+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;
+}
+function delegatedEnvelope(envelope, status) {
+    if (typeof envelope.meta !== "object" || envelope.meta === null || Array.isArray(envelope.meta)) {
+        throw delegatedResponseError(status, "response meta is not an object");
+    }
+    const meta = envelope.meta;
+    if (typeof meta.request_id !== "string") {
+        throw delegatedResponseError(status, "response meta has invalid request_id");
+    }
+    const data = delegatedResponseObject(envelope.data, status, "response data", meta.request_id);
+    return { data, requestId: meta.request_id };
+}
+function requiredDelegatedHeader(envelope, name, status, requestId) {
+    const headers = envelope.__http_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;
+}
+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");
+}
+function delegatedResponseHeaders(envelope, status, requestId) {
+    const cacheControl = envelope.__http_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(envelope, "Cache-Control", status, requestId);
+    }
+    const etag = envelope.__http_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 = envelope.__http_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 };
+}
+function isUtcTimestamp(value) {
+    return (typeof value === "string" &&
+        UTC_TIMESTAMP_PATTERN.test(value) &&
+        Number.isFinite(Date.parse(value)));
+}
+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,
+    };
+}
+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;
+    }
+}
+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 };
+}
+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;
+}
+function classifyDelegatedBatchCreateFailure(error, batchId) {
+    if (!(error instanceof errors_js_1.QURLError)) {
+        throw new errors_js_1.DelegatedBatchOutcomeUnknownError(new errors_js_1.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 errors_js_1.DelegatedBatchOutcomeUnknownError(error, batchId);
+}
 // `format: uri` in the OpenAPI spec allows schemes the SDK doesn't
 // usefully support (`ftp://`, `file://`, `javascript:`, …). This is a
 // cheap client-side sanity check — the server is still the
@@ -2506,6 +2820,195 @@ class QURLClient {
         }
         return requestId !== undefined ? { ...result, request_id: requestId } : result;
     }
+    /**
+     * Start one durable delegated qURL batch. The SDK sends this mutation once.
+     * If the result may have committed, retry explicitly with the same key and
+     * semantic body.
+     */
+    async createDelegatedQurlBatch(input, options) {
+        validateCreateDelegatedQurlBatchInput(input);
+        validateDelegatedBatchCreateOptions(options);
+        let dispatched = false;
+        let acceptedBatchId;
+        try {
+            const envelope = await this.rawRequest("POST", "/v1/delegated-qurl-batches", input, {
+                requestOptions: options,
+                retry: false,
+                generateIdempotencyKey: false,
+                captureResponseHeaders: true,
+                onDispatch: () => {
+                    dispatched = true;
+                },
+            });
+            const status = envelope.__http_status ?? 0;
+            if (status !== 202) {
+                throw delegatedResponseError(status, "create returned an unexpected success status");
+            }
+            const rawData = envelope.data;
+            if (typeof rawData === "object" && rawData !== null && !Array.isArray(rawData)) {
+                const candidate = rawData.batch_id;
+                if (typeof candidate === "string" && DELEGATED_BATCH_ID_PATTERN.test(candidate)) {
+                    acceptedBatchId = candidate;
+                }
+            }
+            const { data, requestId } = delegatedEnvelope(envelope, status);
+            const base = delegatedBatchBase(data, status, requestId);
+            if (data.status !== "queued" || base.itemCount !== input.grants.length) {
+                throw delegatedResponseError(status, "acceptance data is inconsistent", requestId);
+            }
+            const responseHeaders = delegatedResponseHeaders(envelope, status, requestId);
+            const location = validateDelegatedLocation(requiredDelegatedHeader(envelope, "Location", status, requestId), this.baseUrl, base.batchId, status, requestId);
+            return {
+                http_status: 202,
+                batch_id: base.batchId,
+                status: "queued",
+                item_count: base.itemCount,
+                submitted_at: base.submittedAt,
+                etag: responseHeaders.etag,
+                retry_after: responseHeaders.retryAfter,
+                location,
+                request_id: requestId,
+            };
+        }
+        catch (error) {
+            if (!dispatched)
+                throw error;
+            classifyDelegatedBatchCreateFailure(error, acceptedBatchId);
+        }
+    }
+    /**
+     * Read one delegated qURL batch state. One call performs one logical read;
+     * callers retain control of the poll count and total deadline.
+     */
+    async getDelegatedQurlBatch(batchId, options) {
+        if (typeof batchId !== "string" || !DELEGATED_BATCH_ID_PATTERN.test(batchId)) {
+            throw clientValidationError("getDelegatedQurlBatch: batchId must match dqb_ plus 22 URL-safe characters");
+        }
+        validateGetDelegatedQurlBatchOptions(options);
+        const envelope = await this.rawRequest("GET", `/v1/delegated-qurl-batches/${encodeURIComponent(batchId)}`, undefined, {
+            passthroughStatuses: DELEGATED_BATCH_PASSTHROUGH_STATUSES,
+            allowEmptyPassthroughBody: true,
+            ifNoneMatch: options?.etag,
+            retry: false,
+            captureResponseHeaders: true,
+        });
+        const status = envelope.__http_status ?? 0;
+        if (status === 304) {
+            if (envelope.__http_body_empty !== true || options?.etag === undefined) {
+                throw delegatedResponseError(status, "304 response is inconsistent");
+            }
+            const responseHeaders = delegatedResponseHeaders(envelope, status);
+            if (responseHeaders.etag !== undefined && responseHeaders.etag !== options.etag) {
+                throw delegatedResponseError(status, "304 response changed the ETag");
+            }
+            return {
+                http_status: 304,
+                etag: responseHeaders.etag ?? options.etag,
+                ...(responseHeaders.retryAfter === undefined
+                    ? {}
+                    : { retry_after: responseHeaders.retryAfter }),
+            };
+        }
+        if (status !== 200 && status !== 202) {
+            throw delegatedResponseError(status, "read returned an unexpected success status");
+        }
+        const { data, requestId } = delegatedEnvelope(envelope, status);
+        const base = delegatedBatchBase(data, status, requestId, batchId);
+        if (status === 202) {
+            if (data.status !== "queued" && data.status !== "running") {
+                throw delegatedResponseError(status, "pending data has a terminal status", requestId);
+            }
+            const responseHeaders = delegatedResponseHeaders(envelope, status, requestId);
+            return {
+                http_status: 202,
+                batch_id: base.batchId,
+                status: data.status,
+                item_count: base.itemCount,
+                submitted_at: base.submittedAt,
+                etag: responseHeaders.etag,
+                retry_after: responseHeaders.retryAfter,
+                request_id: requestId,
+            };
+        }
+        if (data.status !== "succeeded" &&
+            data.status !== "partially_failed" &&
+            data.status !== "failed") {
+            throw delegatedResponseError(status, "terminal data has a non-terminal status", requestId);
+        }
+        let results;
+        try {
+            if (!isUtcTimestamp(data.completed_at)) {
+                throw delegatedResponseError(status, "terminal data has invalid completed_at", requestId);
+            }
+            results = validateDelegatedBatchResults(data.results, base.itemCount, data.status, status, requestId);
+        }
+        catch (error) {
+            const partialQurlIds = Array.isArray(data.results)
+                ? [
+                    ...new Set(data.results.flatMap((item) => item &&
+                        typeof item === "object" &&
+                        item.status === "succeeded" &&
+                        typeof item.qurl?.qurl_id === "string" &&
+                        DELEGATED_QURL_ID_PATTERN.test(item.qurl.qurl_id)
+                        ? [item.qurl.qurl_id]
+                        : [])),
+                ]
+                : [];
+            if (error instanceof errors_js_1.QURLError)
+                Object.defineProperty(error, "partialQurlIds", {
+                    value: Object.freeze(partialQurlIds),
+                    enumerable: true,
+                });
+            throw error;
+        }
+        // This is the caller's only copy of the bearer links. Do not discard a
+        // valid terminal body because an intermediary removed a cache validator;
+        // qurl-service owns the required no-store response policy.
+        const cacheControl = envelope.__http_headers?.get("Cache-Control") ?? null;
+        if (!hasDelegatedNoStore(cacheControl)) {
+            this.log("delegated batch terminal response is missing private, no-store", {
+                batch_id: base.batchId,
+            });
+        }
+        const etag = envelope.__http_headers?.get("ETag") ?? undefined;
+        const terminalEtag = etag !== undefined && etag.length <= MAX_DELEGATED_ETAG && STRONG_ETAG_PATTERN.test(etag)
+            ? etag
+            : undefined;
+        return {
+            http_status: 200,
+            batch_id: base.batchId,
+            status: data.status,
+            item_count: base.itemCount,
+            submitted_at: base.submittedAt,
+            completed_at: data.completed_at,
+            results,
+            ...(terminalEtag === undefined ? {} : { etag: terminalEtag }),
+            request_id: requestId,
+        };
+    }
+    /** Read owner-visible metadata for one delegated qURL. */
+    async getDelegatedQurl(qurlId) {
+        if (typeof qurlId !== "string" || !DELEGATED_QURL_ID_PATTERN.test(qurlId)) {
+            throw clientValidationError("getDelegatedQurl: qurlId must match q_ plus 11 lowercase hexadecimal characters");
+        }
+        const envelope = await this.rawRequest("GET", `/v1/delegated-qurls/${encodeURIComponent(qurlId)}`);
+        const status = envelope.__http_status ?? 0;
+        if (status !== 200) {
+            throw delegatedResponseError(status, "read returned an unexpected success status");
+        }
+        const { data, requestId } = delegatedEnvelope(envelope, status);
+        return validateDelegatedQurl(data, qurlId, status, requestId);
+    }
+    /**
+     * Revoke one delegated qURL. DELETE is never retried automatically. A 503
+     * `mutation_outcome_unknown` is safe to retry with the same qURL ID.
+     */
+    async deleteDelegatedQurl(qurlId) {
+        if (typeof qurlId !== "string" || !DELEGATED_QURL_ID_PATTERN.test(qurlId)) {
+            throw clientValidationError("deleteDelegatedQurl: qurlId must match q_ plus 11 lowercase hexadecimal characters");
+        }
+        await this.requestNoContent(`/v1/delegated-qurls/${encodeURIComponent(qurlId)}`);
+    }
     /**
      * Get a qURL resource and its access tokens.
      *
@@ -3258,7 +3761,7 @@ class QURLClient {
      */
     async rawRequest(method, path, body, rawOptions = {}) {
         const url = `${this.baseUrl}${path}`;
-        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, retry = true, generateIdempotencyKey = true, } = rawOptions;
+        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, allowEmptyPassthroughBody = false, retry = true, generateIdempotencyKey = true, ifNoneMatch, captureResponseHeaders = false, onDispatch, } = rawOptions;
         const idempotencyKey = idempotencyKeyForRequest(method, requestOptions, generateIdempotencyKey);
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
@@ -3271,6 +3774,9 @@ class QURLClient {
         if (idempotencyKey !== undefined) {
             headers["Idempotency-Key"] = idempotencyKey;
         }
+        if (ifNoneMatch !== undefined) {
+            headers["If-None-Match"] = ifNoneMatch;
+        }
         // Reads may retry transient statuses and transport failures. POST/PATCH
         // keep status-code retries limited to rate limits and reuse the same
         // Idempotency-Key for fetch-level failures. DELETE is deliberately never
@@ -3307,6 +3813,7 @@ class QURLClient {
                 // attempt shouldn't poison the next try's deadline. Total
                 // request bound: roughly `timeout * (maxRetries + 1) +
                 // sum(retryDelay)`.
+                onDispatch?.();
                 response = await this.fetchFn(url, {
                     method,
                     headers,
@@ -3482,16 +3989,20 @@ class QURLClient {
                         data: undefined,
                         __http_status: response.status,
                         __http_body_empty: responseBody.length === 0,
+                        __http_headers: captureResponseHeaders ? response.headers : undefined,
                     };
                 }
                 // Exact no-content helpers must inspect both axes of the success
                 // contract. Let only those callers observe an empty non-204 response;
                 // body-returning methods still reject it as non-JSON below.
-                if (response.ok && allowEmptySuccessBody && responseBody.length === 0) {
+                if (((response.ok && allowEmptySuccessBody) ||
+                    (isPassthrough && allowEmptyPassthroughBody)) &&
+                    responseBody.length === 0) {
                     return {
                         data: undefined,
                         __http_status: response.status,
                         __http_body_empty: true,
+                        __http_headers: captureResponseHeaders ? response.headers : undefined,
                     };
                 }
                 try {
@@ -3501,6 +4012,7 @@ class QURLClient {
                         __http_status: response.status,
                         // JSON.parse("") throws, so parsed JSON is necessarily non-empty.
                         __http_body_empty: false,
+                        __http_headers: captureResponseHeaders ? response.headers : undefined,
                     };
                 }
                 catch {
@@ -3611,14 +4123,13 @@ class QURLClient {
         const header = response.headers.get("Retry-After");
         if (!header)
             return undefined;
-        // TODO: parse HTTP-date format per RFC 7231 §7.1.3 — currently only
-        // handles delta-seconds; HTTP-date headers fall through to the
-        // exponential-backoff branch in `retryDelay`. Tracked in #61.
-        //
-        // Digit-only pre-check rather than `parseInt` alone: `parseInt("60abc")`
-        // returns `60` and would silently honor a malformed header. The
-        // strict check makes any deviation observable (debug log) instead.
         const trimmed = header.trim();
+        if (/^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(trimmed)) {
+            const seconds = Math.ceil((Date.parse(trimmed) - Date.now()) / 1000);
+            return Number.isSafeInteger(seconds) && seconds > 0 && seconds <= RETRY_AFTER_PARSE_LIMIT_S
+                ? seconds
+                : undefined;
+        }
         if (!/^\d+$/.test(trimmed)) {
             this.log("Retry-After header was non-numeric, using exponential backoff", {
                 header_value: header.slice(0, 100),

package/dist/cjs/crid.d.ts

@@ -1,2 +1,3 @@
-export declare function parseCrid(value: unknown): Uint8Array | undefined;
+export declare const CRID_DOMAIN = "NHP-QURL-CRID-V1\0";
+export declare function parseCrid(value: unknown, knownVersionOnly?: boolean): Uint8Array | undefined;
 export declare function cridKeyMatches(value: unknown, der: Uint8Array): Promise<boolean>;

package/dist/cjs/crid.js

@@ -1,13 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CRID_DOMAIN = void 0;
 exports.parseCrid = parseCrid;
 exports.cridKeyMatches = cridKeyMatches;
 // CRID v1 local gate and delivered-key binding, matching qurl-go/crid.
 // The byte selects a version/environment/digest width, not a new hash scheme.
 // All key matches use the v1 domain separator, as in qurl-go/crid.KeyMatches.
 // Unknown nonzero versions remain forwardable; the service owns activation.
+// Access binding requires a locally known version and its registered width.
 const ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
-function parseCrid(value) {
+exports.CRID_DOMAIN = "NHP-QURL-CRID-V1\0";
+function parseCrid(value, knownVersionOnly = false) {
     if (typeof value !== "string" || ![47, 60].includes(value.length))
         return undefined;
     const bytes = new Uint8Array(Math.floor((value.length * 5) / 8));
@@ -27,6 +30,12 @@ function parseCrid(value) {
     if (buffer !== 0 || bytes[0] === 0)
         return undefined;
     const payload = bytes.subarray(0, -4);
+    if (knownVersionOnly) {
+        const version = bytes[0];
+        const width = version === 1 || version === 0x81 ? 32 : version === 2 || version === 0x82 ? 24 : 0;
+        if (payload.length !== width + 1 || width === 0)
+            return undefined;
+    }
     let crc = 0xffffffff;
     for (const byte of payload) {
         crc ^= byte;
@@ -41,7 +50,7 @@ async function cridKeyMatches(value, der) {
     const expected = parseCrid(value);
     if (!expected)
         return false;
-    const prefix = new TextEncoder().encode("NHP-QURL-CRID-V1\0");
+    const prefix = new TextEncoder().encode(exports.CRID_DOMAIN);
     const message = new Uint8Array(prefix.length + der.length);
     message.set(prefix);
     message.set(der, prefix.length);