@layervai/qurl 0.7.0 → 3.0.0

package/dist/esm/client.js

@@ -1,5 +1,5 @@
 import { parseCrid, cridKeyMatches } from "./crid.js";
-import { ConnectorResourceOutcomeUnknownError, createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RuntimeError, TimeoutError, ValidationError, } from "./errors.js";
+import { ConnectorResourceOutcomeUnknownError, createError, DelegatedBatchOutcomeUnknownError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RuntimeError, TimeoutError, ValidationError, } from "./errors.js";
 import { stripTrailingSlashes } from "./internal.js";
 import { ShareLink } from "./share.js";
 import { VERSION } from "./version.js";
@@ -73,6 +73,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",
@@ -86,6 +87,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
@@ -96,6 +115,10 @@ function assertExhaustive(_) {
 }
 assertExhaustive(true);
 assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
+assertExhaustive(true);
 const CREATE_FIELD_KEYS = [
     "type",
     "target_url",
@@ -148,6 +171,8 @@ const RESOURCE_LIST_PARAM_KEYS = [
 ];
 assertExhaustive(true);
 const CREATE_RESOURCE_FIELD_KEYS = [
+    "private",
+    "consumer_access",
     "type",
     "target_url",
     "description",
@@ -159,6 +184,8 @@ const CREATE_RESOURCE_FIELD_KEYS = [
 ];
 assertExhaustive(true);
 const UPDATE_RESOURCE_FIELD_KEYS = [
+    "consumer_access",
+    "expected_consumer_access_version",
     "description",
     "tags",
     "custom_domain",
@@ -187,6 +214,8 @@ assertExhaustive(true);
  * fields the REST-shaped methods send.
  */
 const PROTECT_URL_OPTION_KEYS = [
+    "private",
+    "consumerAccess",
     "description",
     "tags",
     "customDomain",
@@ -763,6 +792,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
@@ -1248,6 +1285,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 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);
+}
 // `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
@@ -1422,6 +1742,13 @@ function normalizePatchFields(input, fields, options = {}) {
     }
     return normalized;
 }
+function requireConsumerDecision(id, version, allowNew = false) {
+    if (typeof id !== "string" ||
+        (!/^[a-f0-9]{64}$/.test(id) && !(allowNew && id === "new")) ||
+        !Number.isSafeInteger(version) ||
+        version < (allowNew ? 0 : 1))
+        throw clientValidationError("consumer decision: invalid id or expected version");
+}
 function validateResourceWriteFields(input, options = {}) {
     const errors = [];
     const collect = (fn) => {
@@ -1436,6 +1763,50 @@ function validateResourceWriteFields(input, options = {}) {
             throw err;
         }
     };
+    collect(() => {
+        if (input.private !== undefined && typeof input.private !== "boolean") {
+            throw clientValidationError("private: must be a boolean");
+        }
+        if (input.consumer_access !== undefined) {
+            const policy = input.consumer_access;
+            requireObjectInput(policy, "consumer_access");
+            const p = policy;
+            requireNoUnknownFields(p, ["mode", "version", "contract_id"], "consumer_access");
+            if (!["keys", "invite_only", "email_capture", "review", "contract"].includes(p.mode) ||
+                !Number.isSafeInteger(p.version) ||
+                p.version < 1) {
+                throw clientValidationError("consumer_access: invalid mode or version");
+            }
+            if (p.mode === "contract") {
+                if (typeof p.contract_id !== "string" ||
+                    !p.contract_id.trim() ||
+                    new TextEncoder().encode(p.contract_id).length > 128) {
+                    throw clientValidationError("consumer_access: contract mode requires a bounded contract_id");
+                }
+            }
+            else if (p.contract_id !== undefined) {
+                throw clientValidationError("consumer_access: contract_id requires contract mode");
+            }
+            if (input.private === false)
+                throw clientValidationError("consumer_access: requires a private resource");
+            if (options.requireUrlTarget) {
+                if (p.version !== 1 || input.private !== true)
+                    throw clientValidationError("consumer_access: creation requires private true and version one");
+            }
+            else if (options.allowAliasClear) {
+                const expected = input.expected_consumer_access_version;
+                if (!Number.isSafeInteger(expected) ||
+                    expected < 0 ||
+                    p.version !== expected + 1 ||
+                    Object.keys(input).some((key) => key !== "consumer_access" && key !== "expected_consumer_access_version")) {
+                    throw clientValidationError("consumer_access: update requires its expected version and no metadata changes");
+                }
+            }
+        }
+        else if (input.expected_consumer_access_version !== undefined) {
+            throw clientValidationError("expected_consumer_access_version: requires consumer_access");
+        }
+    });
     const resourceType = input.type;
     if (resourceType !== undefined && typeof resourceType !== "string") {
         errors.push(`type: must be a string (got ${resourceType === null ? "null" : typeof resourceType})`);
@@ -2108,6 +2479,12 @@ export class QURLClient {
         // SDK-wide normalizePatchFields convention.
         const normalized = normalizePatchFields(opts, PROTECT_URL_OPTION_KEYS);
         const body = { target_url: targetUrl };
+        if (normalized.private !== undefined)
+            body.private = normalized.private;
+        if (normalized.consumerAccess !== undefined) {
+            body.private = normalized.private ?? true;
+            body.consumer_access = normalized.consumerAccess;
+        }
         if (normalized.description !== undefined)
             body.description = normalized.description;
         if (normalized.tags !== undefined)
@@ -2116,9 +2493,19 @@ export class QURLClient {
             body.custom_domain = normalized.customDomain;
         if (normalized.alias !== undefined)
             body.alias = normalized.alias;
-        validateResourceWriteFields(body);
-        const resource = await this.request("POST", "/v1/resources", body, requestOptions);
+        validateResourceWriteFields(body, { requireUrlTarget: true });
+        const response = await this.rawRequest("POST", "/v1/resources", body, {
+            requestOptions,
+        });
+        if (response.__http_status === 204)
+            throw unexpectedResponseError("protectUrl: expected a resource response body");
+        const resource = response.data;
         await verifyResourceIdentity(resource, "protectUrl");
+        if (normalized.consumerAccess &&
+            (resource.private !== true ||
+                !sameConsumerPolicy(resource.consumer_access, normalized.consumerAccess, response.meta?.found_existing === true))) {
+            throw unexpectedResponseError("protectUrl: private policy was not confirmed");
+        }
         return new ProtectedResource(this, resource.crid, 
         // Some resource types redact target_url in responses; fall back to
         // the caller-supplied URL so the handle stays useful.
@@ -2144,8 +2531,13 @@ export class QURLClient {
         return new ProtectedResource(this, id);
     }
     /** Find or create the active qURL Connector resource for an immutable slug. */
-    async ensureConnectorResource(slug, requestOptions) {
+    async ensureConnectorResource(slug, requestOptions, consumerAccess) {
         requireConnectorSlug(slug, "ensureConnectorResource");
+        if (consumerAccess !== undefined) {
+            validateResourceWriteFields({ consumer_access: consumerAccess, private: true });
+            if (consumerAccess.version !== 1)
+                throw clientValidationError("consumer_access: creation requires version one");
+        }
         // Response validation imports the producer's P-256 resource key. Preflight
         // before POST so a missing runtime capability cannot orphan a committed row.
         requireConnectorSubtleCrypto("ensureConnectorResource");
@@ -2160,12 +2552,18 @@ export class QURLClient {
                 type: "tunnel",
                 slug,
                 find_or_create: true,
+                ...(consumerAccess ? { private: true, consumer_access: consumerAccess } : {}),
             }, { requestOptions, retry: false, generateIdempotencyKey: false });
             // The find-or-create endpoint returns 201 for both newly-created
             // and found-existing rows; meta.found_existing distinguishes the arms.
             if (response.__http_status !== 201) {
                 throw unexpectedResponseError(`ensureConnectorResource: expected HTTP 201, got ${response.__http_status ?? "unknown"}`);
             }
+            if (consumerAccess &&
+                (response.data.private !== true ||
+                    !sameConsumerPolicy(response.data.consumer_access, consumerAccess, response.meta?.found_existing === true))) {
+                throw unexpectedResponseError("ensureConnectorResource: private policy was not confirmed");
+            }
             resource = await parseConnectorResource(this, response.data, "ensureConnectorResource", {
                 slug,
             });
@@ -2502,6 +2900,195 @@ export 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 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.
      *
@@ -2763,6 +3350,76 @@ export class QURLClient {
         });
         return this.request("PATCH", `/v1/resources/${encodeURIComponent(id)}`, validationInput, options);
     }
+    /** Send a publisher-only invitation. Mail delivery does not prove enrollment. */
+    async inviteConsumer(id, email) {
+        requireResourceCrid(id, "inviteConsumer");
+        requireNonEmptyIfPresent(email, "email");
+        if (typeof email !== "string" || email.length > 320)
+            throw clientValidationError("email: must be a bounded string");
+        return this.request("POST", `/v1/resources/${encodeURIComponent(id)}/invitations`, { email });
+    }
+    async listConsumerInvitations(id, input = {}) {
+        requireResourceCrid(id, "listConsumerInvitations");
+        const { data, meta } = await this.rawRequest("GET", appendQuery(`/v1/resources/${encodeURIComponent(id)}/invitations`, input, ["cursor", "limit"], "listConsumerInvitations"));
+        return pageFromMeta({ invitations: data ?? [] }, meta);
+    }
+    async listConsumerGrants(id, input = {}) {
+        requireResourceCrid(id, "listConsumerGrants");
+        const { data, meta } = await this.rawRequest("GET", appendQuery(`/v1/resources/${encodeURIComponent(id)}/consumer-grants`, input, ["cursor", "limit"], "listConsumerGrants"));
+        return pageFromMeta({ grants: data ?? [] }, meta);
+    }
+    async resendConsumerInvitation(id, invitationId, expectedVersion) {
+        requireResourceCrid(id, "resendConsumerInvitation");
+        requireConsumerDecision(invitationId, expectedVersion);
+        return this.request("POST", `/v1/resources/${encodeURIComponent(id)}/invitations/${encodeURIComponent(invitationId)}/resend`, { expected_version: expectedVersion });
+    }
+    /** Remove the invitation and its grant. Inspect session_cleanup before reporting stream removal. */
+    async revokeConsumerInvitation(id, invitationId, expectedVersion) {
+        requireResourceCrid(id, "revokeConsumerInvitation");
+        requireConsumerDecision(invitationId, expectedVersion);
+        return this.request("DELETE", `/v1/resources/${encodeURIComponent(id)}/invitations/${encodeURIComponent(invitationId)}?expected_version=${expectedVersion}`);
+    }
+    /** Review approval, key opt-in with grantId new, or trusted publisher entitlement. */
+    async approveConsumerGrant(id, grantId, input) {
+        requireResourceCrid(id, "approveConsumerGrant");
+        requireObjectInput(input, "approveConsumerGrant");
+        requireNoUnknownFields(input, [
+            "expected_version",
+            "credential_kind",
+            "credential_id",
+            "credential_public_key_b64",
+            "entitlement_id",
+            "expires_at",
+        ], "approveConsumerGrant");
+        requireConsumerDecision(grantId, input.expected_version, grantId === "new");
+        return this.request("POST", `/v1/resources/${encodeURIComponent(id)}/consumer-grants/${encodeURIComponent(grantId)}/approve`, input);
+    }
+    async denyConsumerGrant(id, grantId, expectedVersion) {
+        requireResourceCrid(id, "denyConsumerGrant");
+        requireConsumerDecision(grantId, expectedVersion);
+        return this.request("POST", `/v1/resources/${encodeURIComponent(id)}/consumer-grants/${encodeURIComponent(grantId)}/deny`, { expected_version: expectedVersion });
+    }
+    async revokeConsumerGrant(id, grantId, expectedVersion) {
+        requireResourceCrid(id, "revokeConsumerGrant");
+        requireConsumerDecision(grantId, expectedVersion);
+        return this.request("DELETE", `/v1/resources/${encodeURIComponent(id)}/consumer-grants/${encodeURIComponent(grantId)}?expected_version=${expectedVersion}`);
+    }
+    /**
+     * Revoke an API resource identifier retained by a client migrating to CRIDs.
+     * New callers should use deleteResource with the resource CRID.
+     */
+    async deleteResourceByIdentifier(id) {
+        if (typeof id !== "string")
+            throw clientValidationError("id: invalid resource identifier");
+        if (/^r_[a-z0-9_-]{11}$/.test(id)) {
+            await this.requestNoContent(`/v1/qurls/${encodeURIComponent(id)}`);
+            return;
+        }
+        const publicKey = /^[A-Za-z0-9_-]{107,214}$/.test(id) && id.length % 4 !== 1;
+        if (!publicKey)
+            requireResourceCrid(id, "deleteResourceByIdentifier");
+        await this.requestNoContent(`/v1/resources/${encodeURIComponent(id)}`);
+    }
     /** Revoke a resource and all of its qURLs. */
     async deleteResource(id) {
         requireResourceCrid(id, "deleteResource");
@@ -2869,43 +3526,63 @@ export class QURLClient {
         validateResourceQurlUpdateInput(normalized);
         return this.request("PATCH", `/v1/resources/${encodeURIComponent(id)}/qurls/${encodeURIComponent(qurlId)}`, normalized, options);
     }
-    /**
-     * List active access sessions for a resource.
-     *
-     * The current API contract has no cursor query params for this endpoint.
-     * If the service later advertises pagination metadata, the SDK returns
-     * this page and emits a debug log rather than pretending it fetched all pages.
-     */
+    /** List every active session, following bounded service pages. */
     async listResourceSessions(id) {
         requireResourceCrid(id, "listResourceSessions");
-        const { data, meta } = await this.rawRequest("GET", `/v1/resources/${encodeURIComponent(id)}/sessions`);
-        if (meta?.has_more || meta?.next_cursor) {
-            this.log("listResourceSessions: pagination metadata surfaced on unpaginated endpoint", {
-                has_more: meta.has_more,
-                next_cursor: meta.next_cursor,
-            });
+        const sessions = [];
+        let request_id;
+        let page_size;
+        for await (const session of this.paginateAll("listResourceSessions", {}, async ({ cursor }) => {
+            const { data, meta } = await this.rawRequest("GET", appendQuery(`/v1/resources/${encodeURIComponent(id)}/sessions`, { paged: "true", cursor }, ["paged", "cursor"], "listResourceSessions"));
+            if (meta?.has_more && !meta.next_cursor) {
+                throw unexpectedResponseError("Session page has no continuation cursor", {
+                    requestId: meta.request_id,
+                });
+            }
+            request_id = meta?.request_id;
+            page_size = meta?.page_size;
+            return { ...meta, sessions: data ?? [] };
+        }, (page) => page.sessions)) {
+            sessions.push(session);
         }
-        return {
-            sessions: data ?? [],
-            request_id: meta?.request_id,
-            has_more: false,
-            page_size: meta?.page_size,
-        };
+        return { sessions, request_id, has_more: false, page_size };
     }
-    /** Terminate all active sessions for a resource and return the server count. */
+    /**
+     * End every session page. This is not atomic: a failed page throws after earlier
+     * pages may have closed sessions. List sessions to reconcile, then retry the call.
+     * A retry can close newly admitted sessions and counts only its own transitions.
+     */
     async terminateAllResourceSessions(id) {
         requireResourceCrid(id, "terminateAllResourceSessions");
         const path = `/v1/resources/${encodeURIComponent(id)}/sessions`;
-        const { data, meta, __http_status } = await this.rawRequest("DELETE", path);
-        if (__http_status === 204) {
-            throw unexpectedResponseError(`Unexpected 204 No Content from DELETE ${path}; expected response body`);
-        }
-        if (data?.terminated === undefined) {
-            this.log("terminateAllResourceSessions: missing terminated count; defaulting to zero", {
-                request_id: meta?.request_id,
-            });
+        let terminated = 0;
+        let request_id;
+        for await (const count of this.paginateAll("terminateAllResourceSessions", {}, async ({ cursor }) => {
+            const { data, meta, __http_status } = await this.rawRequest("DELETE", appendQuery(path, { paged: "true", cursor }, ["paged", "cursor"], "terminateAllResourceSessions"));
+            if (__http_status === 204) {
+                throw unexpectedResponseError(`Unexpected 204 No Content from DELETE ${path}; expected response body`, { status: 204, requestId: meta?.request_id });
+            }
+            if (meta?.has_more && !meta.next_cursor) {
+                throw unexpectedResponseError("Session page has no continuation cursor", {
+                    requestId: meta.request_id,
+                });
+            }
+            if (data?.terminated === undefined) {
+                this.log("terminateAllResourceSessions: missing terminated count; defaulting to zero", {
+                    request_id: meta?.request_id,
+                });
+            }
+            else if (!Number.isSafeInteger(data.terminated) || data.terminated < 0) {
+                throw unexpectedResponseError("terminateAllResourceSessions: invalid terminated count", {
+                    requestId: meta?.request_id,
+                });
+            }
+            request_id = meta?.request_id;
+            return { ...meta, counts: [data?.terminated ?? 0] };
+        }, (page) => page.counts)) {
+            terminated += count;
         }
-        return { terminated: data?.terminated ?? 0, request_id: meta?.request_id };
+        return { terminated, request_id };
     }
     /** Terminate a specific resource session. */
     async terminateResourceSession(id, sessionId) {
@@ -3254,7 +3931,7 @@ export 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}`,
@@ -3267,6 +3944,9 @@ export 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
@@ -3303,6 +3983,7 @@ export 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,
@@ -3478,16 +4159,20 @@ export 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 {
@@ -3497,6 +4182,7 @@ export 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 {
@@ -3607,14 +4293,13 @@ export 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),
@@ -3776,4 +4461,12 @@ export class ConnectorResource {
         return this.#client.createPortal(this.crid, opts, requestOptions);
     }
 }
+function sameConsumerPolicy(actual, expected, foundExisting) {
+    return (actual?.mode === expected.mode &&
+        (actual?.version === expected.version ||
+            (foundExisting &&
+                Number.isSafeInteger(actual?.version) &&
+                Number(actual?.version) > expected.version)) &&
+        actual?.contract_id === expected.contract_id);
+}
 //# sourceMappingURL=client.js.map