@layervai/qurl 0.4.0 → 0.6.0

package/dist/cjs/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProtectedResource = exports.QURLClient = exports.SIGNED_FRAGMENT_RE = void 0;
+exports.ConnectorResource = exports.ProtectedResource = exports.QURLClient = exports.SIGNED_FRAGMENT_RE = void 0;
 const errors_js_1 = require("./errors.js");
 const internal_js_1 = require("./internal.js");
 const version_js_1 = require("./version.js");
@@ -196,6 +196,7 @@ const CREATE_PORTAL_OPTION_KEYS = [
     "oneTimeUse",
     "maxSessions",
     "sessionDuration",
+    "targetPath",
 ];
 assertExhaustive(true);
 const UPDATE_RESOURCE_QURL_FIELD_KEYS = [
@@ -322,14 +323,14 @@ function validateRequestOptions(options) {
         }
     }
 }
-function idempotencyKeyForRequest(method, options) {
+function idempotencyKeyForRequest(method, options, generateWhenMissing = true) {
     // Validate before method gating so future read-only methods that accept
     // RequestOptions fail loudly on malformed options instead of discarding them.
     validateRequestOptions(options);
     if (!IDEMPOTENCY_KEY_METHODS.has(method)) {
         return undefined;
     }
-    return options?.idempotencyKey ?? generateUuidV7();
+    return options?.idempotencyKey ?? (generateWhenMissing ? generateUuidV7() : undefined);
 }
 function generateUuidV7() {
     const bytes = new Uint8Array(16);
@@ -723,6 +724,14 @@ const MAX_TARGET_PATH = 2048;
 const MAX_TAGS = 10;
 const MAX_TAG_LENGTH = 50;
 const MAX_AUTO_PAGINATION_PAGES = 10_000;
+// 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
+// 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]$/;
 // CreateQurlRequest.target_url pattern is loose (just a URI) but
 // UpdateQurlRequest.tags pattern is specific — enforce it here.
 const TAG_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9 _-]*$/;
@@ -741,6 +750,17 @@ function requireMaxLength(value, field, max) {
         throw clientValidationError(`${field}: must be ${max} characters or fewer (got ${value.length})`);
     }
 }
+function requireMaxUtf8Bytes(value, field, max) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string") {
+        throw clientValidationError(`${field}: must be a string (got ${value === null ? "null" : typeof value})`);
+    }
+    const bytes = TEXT_ENCODER.encode(value).byteLength;
+    if (bytes > max) {
+        throw clientValidationError(`${field}: must be ${max} UTF-8 bytes or fewer (got ${bytes})`);
+    }
+}
 function requireNonEmptyIfPresent(value, field) {
     // Reject `""` so uninitialized form state doesn't reach the wire.
     if (value === "") {
@@ -833,6 +853,163 @@ function requireNonEmptyId(id, method, field = "id") {
         throw clientValidationError(`${method}: ${field} must not include leading or trailing whitespace`);
     }
 }
+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`);
+    }
+}
+function classifyConnectorMutationFailure(operation, error) {
+    if (!(error instanceof errors_js_1.QURLError)) {
+        throw new errors_js_1.ConnectorResourceOutcomeUnknownError(new errors_js_1.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 errors_js_1.ConnectorResourceOutcomeUnknownError(error);
+    }
+    if (error.status >= 400 && error.status < 500) {
+        throw error;
+    }
+    throw new errors_js_1.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;
+    }
+}
+async function isValidConnectorResourceId(value) {
+    const der = decodeCanonicalBase64Url(value);
+    if (!der)
+        return false;
+    if (!globalThis.crypto?.subtle) {
+        throw new errors_js_1.RuntimeError("qURL Connector resource validation requires the Web Crypto SubtleCrypto API");
+    }
+    return importsAsConnectorPublicKey(der);
+}
+function requireConnectorSubtleCrypto(method) {
+    if (!globalThis.crypto?.subtle) {
+        throw new errors_js_1.RuntimeError(`${method}: requires the Web Crypto SubtleCrypto API`);
+    }
+}
+async function requireConnectorResourceId(resourceId, method) {
+    const der = decodeCanonicalBase64Url(resourceId);
+    if (!der) {
+        throw clientValidationError(`${method}: resource id must be a canonical unpadded base64url P-256 DER SPKI public key`);
+    }
+    requireConnectorSubtleCrypto(method);
+    if (!(await importsAsConnectorPublicKey(der))) {
+        throw clientValidationError(`${method}: resource id must be a canonical unpadded base64url P-256 DER SPKI public key`);
+    }
+}
+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;
+    }
+}
+function containsControlCharacter(value) {
+    return Array.from(value).some((character) => {
+        const codePoint = character.codePointAt(0);
+        return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+    });
+}
+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;
+    if (typeof resource.resource_id !== "string") {
+        throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`);
+    }
+    if (expectation.resourceId !== undefined && resource.resource_id !== expectation.resourceId) {
+        throw unexpectedResponseError(`${method}: response resource_id does not match the request`);
+    }
+    // A by-ID request already validated its requested resource key and matched
+    // this response byte-for-byte, so do not repeat the async key import.
+    if (expectation.resourceId === undefined &&
+        !(await isValidConnectorResourceId(resource.resource_id))) {
+        throw unexpectedResponseError(`${method}: response has missing or invalid resource_id`);
+    }
+    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.crid !== undefined && typeof resource.crid !== "string") {
+        throw unexpectedResponseError(`${method}: response has invalid crid`);
+    }
+    // Match qurl-go: ConnectorResource carries an optional producer CRID
+    // verbatim. Consumers that possess a trusted delivered key can verify the
+    // binding separately; this management-plane row is not itself a trust root.
+    if (resource.status === "revoked") {
+        if (expectation.revokedIsLifecycleError !== true) {
+            throw unexpectedResponseError(`${method}: active-only operation returned a revoked connector resource`);
+        }
+        throw new errors_js_1.QURLError({
+            status: 0,
+            code: errors_js_1.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);
+}
 function requireValidTags(tags) {
     // null tolerance for untyped-JS callers — treated as "don't touch."
     // Duplicates pass through to the server (authoritative on dedupe policy).
@@ -1038,7 +1215,7 @@ function validateQurlTokenOptions(input) {
     // gate server-authoritative (`invalid_target_path`); a client-side regex
     // would create a drift surface. Keep max-before-empty consistent with label;
     // empty strings pass the length check and are rejected by the next guard.
-    requireMaxLength(input.target_path, "target_path", MAX_TARGET_PATH);
+    requireMaxUtf8Bytes(input.target_path, "target_path", MAX_TARGET_PATH);
     requireNonEmptyIfPresent(input.target_path, "target_path");
     requireBooleanIfPresent(input.one_time_use, "one_time_use");
     requireMaxSessionsInRange(input.max_sessions);
@@ -1415,16 +1592,15 @@ function parsePortal(data, method) {
     };
 }
 /**
- * Validate portal options and build the create-portal wire body, or
- * `undefined` when every option is omitted so no request body is sent and
- * the server applies its default lifetime (matching mintLink /
- * createQurlForResource).
+ * Validate portal options and build the create-portal wire body. The service
+ * requires a JSON object even when every option is omitted; `{}` selects the
+ * owner's plan defaults and matches qurl-go's zero-value request struct.
  */
 function buildCreatePortalBody(opts, method) {
     requireObjectInput(opts, method);
     requireNoUnknownFields(opts, CREATE_PORTAL_OPTION_KEYS, method);
     // null → omitted, via the SDK-wide normalizePatchFields convention.
-    const { validFor, label, oneTimeUse, maxSessions, sessionDuration } = normalizePatchFields(opts, CREATE_PORTAL_OPTION_KEYS);
+    const { validFor, label, oneTimeUse, maxSessions, sessionDuration, targetPath } = normalizePatchFields(opts, CREATE_PORTAL_OPTION_KEYS);
     if (label !== undefined) {
         requireMaxLength(label, "label", MAX_LABEL);
         // qurl-go's WithLabel rejects blank labels; the REST-shaped mintLink
@@ -1435,6 +1611,11 @@ function buildCreatePortalBody(opts, method) {
     }
     requireBooleanIfPresent(oneTimeUse, "oneTimeUse");
     requireMaxSessionsInRange(maxSessions, "maxSessions");
+    requireMaxUtf8Bytes(targetPath, "targetPath", MAX_TARGET_PATH);
+    requireNonEmptyIfPresent(targetPath, "targetPath");
+    if (targetPath !== undefined && method === "createPortalForUrl") {
+        throw clientValidationError("targetPath: requires an existing resource");
+    }
     const body = {};
     const expiresIn = serializeApiDuration(validFor, "validFor", MIN_PORTAL_VALID_FOR_SECONDS);
     if (expiresIn !== undefined)
@@ -1449,7 +1630,9 @@ function buildCreatePortalBody(opts, method) {
     const wireSessionDuration = serializeApiDuration(sessionDuration, "sessionDuration", MIN_SESSION_DURATION_SECONDS);
     if (wireSessionDuration !== undefined)
         body.session_duration = wireSessionDuration;
-    return Object.keys(body).length > 0 ? body : undefined;
+    if (targetPath !== undefined)
+        body.target_path = targetPath;
+    return body;
 }
 /** qURL API client. */
 class QURLClient {
@@ -1772,49 +1955,110 @@ class QURLClient {
         requireNonEmptyId(id, "resourceById");
         return new ProtectedResource(this, id);
     }
-    /**
-     * Return the resource qURL Connector created for `connectorId`.
-     *
-     * Use when qURL Connector already protects the service — do not call
-     * {@link protectUrl} again for the same service. The connector id is the
-     * resource slug LayerV stores for that connector; the LayerV API performs
-     * the slug lookup, and the SDK confirms the returned alias matches
-     * `connectorId` before binding the handle (qurl-go:
-     * `Client.ConnectorResource`).
-     *
-     * Throws {@link NotFoundError} (`status: 0`, `code: "resource_not_found"`)
-     * when no resource exists for the connector id, {@link QURLError}
-     * (`code: "ambiguous_resource"`) when the lookup returns more than one
-     * resource, and {@link ValidationError} (`code: "unexpected_response"`)
-     * when the returned resource's alias is missing or does not match.
-     */
-    async connectorResource(connectorId) {
-        requireNonEmptyId(connectorId, "connectorResource", "connector id");
-        const { resources } = await this.listResources({ slug: connectorId });
-        if (resources.length === 0) {
+    /** Find or create the active qURL Connector resource for an immutable slug. */
+    async ensureConnectorResource(slug, requestOptions) {
+        requireConnectorSlug(slug, "ensureConnectorResource");
+        // 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");
+        // Keep invalid options in the known pre-dispatch error arm. rawRequest
+        // validates again when building the request, which protects future callers
+        // that do not have this mutation-specific outcome contract.
+        validateRequestOptions(requestOptions);
+        let response;
+        let resource;
+        try {
+            response = await this.rawRequest("POST", "/v1/resources", {
+                type: "tunnel",
+                slug,
+                find_or_create: true,
+            }, { 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"}`);
+            }
+            resource = await parseConnectorResource(this, response.data, "ensureConnectorResource", {
+                slug,
+            });
+        }
+        catch (error) {
+            classifyConnectorMutationFailure("ensure", error);
+        }
+        if (response.meta !== undefined &&
+            response.meta !== null &&
+            (typeof response.meta !== "object" || Array.isArray(response.meta))) {
+            classifyConnectorMutationFailure("ensure", unexpectedResponseError("ensureConnectorResource: response has invalid meta"));
+        }
+        const foundExisting = response.meta
+            ?.found_existing;
+        if (foundExisting === undefined || foundExisting === null) {
+            throw unexpectedResponseError("ensureConnectorResource: response is missing meta.found_existing; the validated resource exists, so reconcile by slug before retrying");
+        }
+        if (typeof foundExisting !== "boolean") {
+            classifyConnectorMutationFailure("ensure", unexpectedResponseError("ensureConnectorResource: response has invalid meta.found_existing"));
+        }
+        return { resource, foundExisting };
+    }
+    /** Fetch a qURL Connector resource by its immutable public resource ID. */
+    async getConnectorResource(resourceId) {
+        await requireConnectorResourceId(resourceId, "getConnectorResource");
+        const { data, __http_status } = await this.rawRequest("GET", `/v1/resources/${encodeURIComponent(resourceId)}`, undefined, { retry: false });
+        if (__http_status !== 200) {
+            throw unexpectedResponseError(`getConnectorResource: expected HTTP 200, got ${__http_status ?? "unknown"}`);
+        }
+        return parseConnectorResource(this, data?.resource, "getConnectorResource", {
+            resourceId,
+            revokedIsLifecycleError: true,
+        });
+    }
+    /** Fetch the single active qURL Connector resource for an immutable slug. */
+    async getConnectorResourceBySlug(slug) {
+        requireConnectorSlug(slug, "getConnectorResourceBySlug");
+        // Parsing validates the returned P-256 resource key; avoid dispatching a
+        // read that this runtime cannot safely consume.
+        requireConnectorSubtleCrypto("getConnectorResourceBySlug");
+        // The slug point lookup is intrinsically active-only. It also
+        // rejects combining `slug` with `status`, so this query must stay slug-only.
+        const { data, __http_status } = await this.rawRequest("GET", `/v1/resources?slug=${encodeURIComponent(slug)}`, undefined, { retry: false });
+        if (__http_status !== 200) {
+            throw unexpectedResponseError(`getConnectorResourceBySlug: expected HTTP 200, got ${__http_status ?? "unknown"}`);
+        }
+        if (!Array.isArray(data)) {
+            throw unexpectedResponseError("getConnectorResourceBySlug: response has missing or invalid data");
+        }
+        if (data.length === 0) {
             throw new errors_js_1.NotFoundError({
                 status: 0,
                 code: errors_js_1.ERROR_CODE_RESOURCE_NOT_FOUND,
                 title: "Resource Not Found",
-                detail: `connectorResource: no resource found for connector "${connectorId}"`,
+                detail: "getConnectorResourceBySlug: no active resource exists for the requested slug",
             });
         }
-        if (resources.length > 1) {
+        if (data.length > 1) {
             throw new errors_js_1.QURLError({
                 status: 0,
                 code: errors_js_1.ERROR_CODE_AMBIGUOUS_RESOURCE,
                 title: "Ambiguous Resource",
-                detail: `connectorResource: connector "${connectorId}" returned ${resources.length} resources`,
+                detail: `getConnectorResourceBySlug: expected one active resource, got ${data.length}`,
             });
         }
-        const resource = resources[0];
-        if (resource.alias !== connectorId) {
-            throw unexpectedResponseError(`connectorResource: connector "${connectorId}" returned a resource with a missing or different alias`);
+        return parseConnectorResource(this, data[0], "getConnectorResourceBySlug", { slug });
+    }
+    /**
+     * Revoke a qURL Connector resource by immutable public resource ID.
+     *
+     * The API does not apply Idempotency-Key replay to DELETE. After an
+     * outcome-unknown failure, reconcile by ID before issuing a deliberate retry.
+     */
+    async deleteConnectorResource(resourceId) {
+        await requireConnectorResourceId(resourceId, "deleteConnectorResource");
+        try {
+            await this.requestNoContent(`/v1/resources/${encodeURIComponent(resourceId)}`);
         }
-        if (typeof resource.resource_id !== "string" || resource.resource_id.trim() === "") {
-            throw unexpectedResponseError("connectorResource: response is missing resource_id");
+        catch (error) {
+            classifyConnectorMutationFailure("delete", error);
         }
-        return new ProtectedResource(this, resource.resource_id, resource.target_url, resource);
     }
     /**
      * Mint a short-lived qURL link (a portal) for a protected resource.
@@ -1823,14 +2067,15 @@ class QURLClient {
      * reach one private resource. Recipients open `portal.link` directly and
      * need no LayerV credentials. Prefer short lifetimes such as
      * `{ validFor: "5m" }`. Accepts a {@link ProtectedResource} handle or a
-     * resource id (`r_` prefix). REST-shaped equivalents: {@link mintLink} /
+     * public resource ID string. REST-shaped equivalents: {@link mintLink} /
      * {@link createQurlForResource}.
      *
      * Duration options take a string (`"5m"`, `"24h"`; server-validated) or a
      * number of milliseconds with qurl-go's client-side guardrails: whole
      * seconds only, at least one minute for `validFor` and one second for
      * `sessionDuration`. `maxSessions: 0` is sent explicitly and means
-     * unlimited; blank labels are rejected.
+     * unlimited; blank labels are rejected. `targetPath` is valid only for an
+     * existing resource. The API owns its full grammar and tunnel-only gate.
      */
     async createPortal(resource, opts = {}, requestOptions) {
         let resourceId;
@@ -1860,7 +2105,9 @@ class QURLClient {
      * {@link protectUrl} when you need the full server-populated resource
      * metadata. Portal options match {@link createPortal}; `targetUrl` gets
      * the same malformed-URL and embedded-credentials rejection as
-     * {@link protectUrl}. REST-shaped equivalent: {@link create}.
+     * {@link protectUrl}. `targetPath` is rejected because this call creates a
+     * URL resource instead of addressing an existing resource. REST-shaped
+     * equivalent: {@link create}.
      */
     async createPortalForUrl(targetUrl, opts = {}, requestOptions) {
         requirePortalTargetUrl(targetUrl);
@@ -2753,8 +3000,8 @@ class QURLClient {
      */
     async rawRequest(method, path, body, rawOptions = {}) {
         const url = `${this.baseUrl}${path}`;
-        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, } = rawOptions;
-        const idempotencyKey = idempotencyKeyForRequest(method, requestOptions);
+        const { passthroughStatuses = NO_PASSTHROUGH_STATUSES, requestOptions, allowEmptySuccessBody = false, retry = true, generateIdempotencyKey = true, } = rawOptions;
+        const idempotencyKey = idempotencyKeyForRequest(method, requestOptions, generateIdempotencyKey);
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             Accept: "application/json",
@@ -2773,13 +3020,15 @@ class QURLClient {
         // retry rule and avoids SDK pacing on an application request path. The
         // caller receives retryAfter when supplied and must reconcile resource
         // state before it chooses to issue another delete.
-        const idempotencyKeyBackedRetry = MUTATING_RETRY_METHODS.has(method);
-        const retryFetchFailure = method === "GET" || idempotencyKeyBackedRetry;
-        const retryable = method === "GET"
-            ? RETRYABLE_STATUS
-            : idempotencyKeyBackedRetry
-                ? RETRYABLE_STATUS_MUTATING
-                : NO_RETRYABLE_STATUSES;
+        const idempotencyKeyBackedRetry = retry && MUTATING_RETRY_METHODS.has(method);
+        const retryFetchFailure = retry && (method === "GET" || idempotencyKeyBackedRetry);
+        const retryable = !retry
+            ? NO_RETRYABLE_STATUSES
+            : method === "GET"
+                ? RETRYABLE_STATUS
+                : idempotencyKeyBackedRetry
+                    ? RETRYABLE_STATUS_MUTATING
+                    : NO_RETRYABLE_STATUSES;
         const serializedBody = body !== undefined ? JSON.stringify(body) : undefined;
         let lastError;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
@@ -3197,8 +3446,7 @@ exports.QURLClient = QURLClient;
 /**
  * A LayerV-protected resource, bound to the client that produced it.
  *
- * Obtained from {@link QURLClient.protectUrl},
- * {@link QURLClient.connectorResource}, or {@link QURLClient.resourceById} —
+ * Obtained from {@link QURLClient.protectUrl} or {@link QURLClient.resourceById} —
  * not constructed directly. Mint short-lived access links for the resource
  * with {@link createPortal} (qurl-go: `qurl.Resource`).
  */
@@ -3207,7 +3455,7 @@ class ProtectedResource {
     // CONTRIBUTING.md's dual-build rule bars) so the binding stays on the
     // instance and out of Object.keys/JSON.stringify output.
     #client;
-    /** The LayerV resource id (`r_` prefix). */
+    /** The LayerV public resource ID. */
     id;
     /** The private URL protected by this resource, when known. */
     targetUrl;
@@ -3241,3 +3489,39 @@ class ProtectedResource {
     }
 }
 exports.ProtectedResource = ProtectedResource;
+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.
+ */
+class ConnectorResource {
+    #client;
+    resourceId;
+    /** Producer-supplied CRID carried verbatim; verify it against a trusted key before trust. */
+    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.resourceId = 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.resourceId, opts, requestOptions);
+    }
+}
+exports.ConnectorResource = ConnectorResource;

package/dist/cjs/errors.d.ts

@@ -14,9 +14,13 @@ export declare const ERROR_CODE_UNEXPECTED_RESPONSE = "unexpected_response";
 export declare const ERROR_CODE_NETWORK = "network_error";
 export declare const ERROR_CODE_TIMEOUT = "timeout";
 export declare const ERROR_CODE_RUNTIME = "runtime_error";
-/** `connectorResource` found no resource for the connector id (client-detected, `status: 0`). */
+/** A dispatched Connector resource mutation could have committed and must be reconciled. */
+export declare const ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = "connector_resource_outcome_unknown";
+/** A by-ID Connector resource lookup found a revoked lifecycle row. */
+export declare const ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = "connector_resource_revoked";
+/** A Connector slug lookup found no active resource (client-detected, `status: 0`). */
 export declare const ERROR_CODE_RESOURCE_NOT_FOUND = "resource_not_found";
-/** `connectorResource` matched more than one resource where exactly one is required (client-detected, `status: 0`). */
+/** A Connector slug lookup matched more than one active resource (client-detected, `status: 0`). */
 export declare const ERROR_CODE_AMBIGUOUS_RESOURCE = "ambiguous_resource";
 /** Fallback `.code` when the server returns a non-RFC-7807 response (HTML proxy page, plaintext gateway error, JSON without `error` envelope). */
 export declare const ERROR_CODE_UNKNOWN = "unknown";
@@ -78,7 +82,10 @@ export declare class NotFoundError extends QURLError {
  *   returning HTML on a passthrough status, or a batch response missing
  *   required fields).
  *
- * `instanceof ValidationError` catches both. To distinguish them, check
+ * `instanceof ValidationError` catches both on ordinary client/response
+ * paths. A Connector mutation wraps a post-dispatch `unexpected_response`
+ * in {@link ConnectorResourceOutcomeUnknownError}; inspect that error's
+ * typed `cause` before deciding whether to retry. To distinguish them, check
  * `.code` rather than using `instanceof` alone.
  *
  * **`.status` asymmetry within `code: "unexpected_response"`:**
@@ -107,6 +114,20 @@ export declare class RateLimitError extends QURLError {
 export declare class ServerError extends QURLError {
     constructor(data: QURLErrorData);
 }
+/**
+ * A Connector resource ensure/delete was dispatched, but the response cannot
+ * prove whether it committed. Reconcile by immutable slug or resource ID
+ * before choosing whether to retry. The original typed failure is in `cause`.
+ * The wrapper uses `status: 0` so generic HTTP-status retry predicates cannot
+ * replay the mutation; inspect `cause.status` for the observed HTTP status.
+ * A valid HTTP 201 Connector row missing only `meta.found_existing` is a known
+ * committed/selected row with incomplete metadata and is not wrapped here.
+ */
+export declare class ConnectorResourceOutcomeUnknownError extends QURLError {
+    readonly code: typeof ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN;
+    readonly cause: QURLError;
+    constructor(cause: QURLError);
+}
 /** Transport-level error — DNS failure, connection refused, etc. */
 export declare class NetworkError extends QURLError {
     constructor(message: string, options?: {

package/dist/cjs/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RuntimeError = exports.TimeoutError = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_CLIENT_VALIDATION = void 0;
+exports.RuntimeError = exports.TimeoutError = exports.NetworkError = exports.ConnectorResourceOutcomeUnknownError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_CLIENT_VALIDATION = void 0;
 exports.createError = createError;
 /**
  * Sentinel `.code` values for SDK-internal failure modes (no real HTTP
@@ -17,9 +17,13 @@ exports.ERROR_CODE_UNEXPECTED_RESPONSE = "unexpected_response";
 exports.ERROR_CODE_NETWORK = "network_error";
 exports.ERROR_CODE_TIMEOUT = "timeout";
 exports.ERROR_CODE_RUNTIME = "runtime_error";
-/** `connectorResource` found no resource for the connector id (client-detected, `status: 0`). */
+/** A dispatched Connector resource mutation could have committed and must be reconciled. */
+exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = "connector_resource_outcome_unknown";
+/** A by-ID Connector resource lookup found a revoked lifecycle row. */
+exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = "connector_resource_revoked";
+/** A Connector slug lookup found no active resource (client-detected, `status: 0`). */
 exports.ERROR_CODE_RESOURCE_NOT_FOUND = "resource_not_found";
-/** `connectorResource` matched more than one resource where exactly one is required (client-detected, `status: 0`). */
+/** A Connector slug lookup matched more than one active resource (client-detected, `status: 0`). */
 exports.ERROR_CODE_AMBIGUOUS_RESOURCE = "ambiguous_resource";
 /** Fallback `.code` when the server returns a non-RFC-7807 response (HTML proxy page, plaintext gateway error, JSON without `error` envelope). */
 exports.ERROR_CODE_UNKNOWN = "unknown";
@@ -109,7 +113,10 @@ exports.NotFoundError = NotFoundError;
  *   returning HTML on a passthrough status, or a batch response missing
  *   required fields).
  *
- * `instanceof ValidationError` catches both. To distinguish them, check
+ * `instanceof ValidationError` catches both on ordinary client/response
+ * paths. A Connector mutation wraps a post-dispatch `unexpected_response`
+ * in {@link ConnectorResourceOutcomeUnknownError}; inspect that error's
+ * typed `cause` before deciding whether to retry. To distinguish them, check
  * `.code` rather than using `instanceof` alone.
  *
  * **`.status` asymmetry within `code: "unexpected_response"`:**
@@ -161,6 +168,29 @@ function attachErrorCause(error, options) {
         configurable: true,
     });
 }
+/**
+ * A Connector resource ensure/delete was dispatched, but the response cannot
+ * prove whether it committed. Reconcile by immutable slug or resource ID
+ * before choosing whether to retry. The original typed failure is in `cause`.
+ * The wrapper uses `status: 0` so generic HTTP-status retry predicates cannot
+ * replay the mutation; inspect `cause.status` for the observed HTTP status.
+ * A valid HTTP 201 Connector row missing only `meta.found_existing` is a known
+ * committed/selected row with incomplete metadata and is not wrapped here.
+ */
+class ConnectorResourceOutcomeUnknownError extends QURLError {
+    constructor(cause) {
+        super({
+            status: 0,
+            code: exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN,
+            title: "Connector Resource Outcome Unknown",
+            detail: `Mutation outcome is unknown; reconcile before retrying. ${cause.detail}`,
+            request_id: cause.requestId,
+        });
+        this.name = "ConnectorResourceOutcomeUnknownError";
+        attachErrorCause(this, { cause });
+    }
+}
+exports.ConnectorResourceOutcomeUnknownError = ConnectorResourceOutcomeUnknownError;
 /** Transport-level error — DNS failure, connection refused, etc. */
 class NetworkError extends QURLError {
     constructor(message, options) {