@layervai/qurl 3.1.1 → 4.0.0

package/dist/cjs/errors.d.ts

@@ -1,4 +1,4 @@
-import type { QURLErrorData } from "./types.js";
+import type { QURLErrorData, TombstoneInfo } from "./types.js";
 /**
  * Sentinel `.code` values for SDK-internal failure modes (no real HTTP
  * status applies). Exported as constants so consumers branching on
@@ -32,6 +32,12 @@ export declare const ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = "connector_resource
 export declare const ERROR_CODE_RESOURCE_NOT_FOUND = "resource_not_found";
 /** A Connector slug lookup matched more than one active resource (client-detected, `status: 0`). */
 export declare const ERROR_CODE_AMBIGUOUS_RESOURCE = "ambiguous_resource";
+/**
+ * Server `.code` (on a 400 `ValidationError`) when a create that makes a new
+ * resource has no `name`, or `PATCH /v1/resources/{id}/preview` sets an empty
+ * one. Nothing was written; add the public name and retry.
+ */
+export declare const ERROR_CODE_NAME_REQUIRED = "name_required";
 /** 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";
 /**
@@ -67,6 +73,8 @@ export declare class QURLError extends Error {
     readonly invalidFields?: Record<string, string>;
     readonly requestId?: string;
     readonly retryAfter?: number;
+    /** Retained resource metadata supplied by a 410 Gone response. */
+    readonly tombstone?: TombstoneInfo;
     /** Known minted IDs from a rejected terminal batch, for bounded cleanup. No bearer links. */
     readonly partialQurlIds?: readonly string[];
     constructor(data: QURLErrorData);

package/dist/cjs/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RuntimeError = exports.TimeoutError = exports.NetworkError = exports.DelegatedBatchOutcomeUnknownError = 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_DELEGATED_BATCH_OUTCOME_UNKNOWN = exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = exports.ERROR_CODE_CRID_MISMATCH = exports.ERROR_CODE_INVALID_CRID_KEY = exports.ERROR_CODE_INVALID_CRID = exports.ERROR_CODE_MISSING_CRID = 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.DelegatedBatchOutcomeUnknownError = exports.ConnectorResourceOutcomeUnknownError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_NAME_REQUIRED = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = exports.ERROR_CODE_DELEGATED_BATCH_OUTCOME_UNKNOWN = exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = exports.ERROR_CODE_CRID_MISMATCH = exports.ERROR_CODE_INVALID_CRID_KEY = exports.ERROR_CODE_INVALID_CRID = exports.ERROR_CODE_MISSING_CRID = 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
@@ -35,6 +35,12 @@ exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = "connector_resource_revoked";
 exports.ERROR_CODE_RESOURCE_NOT_FOUND = "resource_not_found";
 /** A Connector slug lookup matched more than one active resource (client-detected, `status: 0`). */
 exports.ERROR_CODE_AMBIGUOUS_RESOURCE = "ambiguous_resource";
+/**
+ * Server `.code` (on a 400 `ValidationError`) when a create that makes a new
+ * resource has no `name`, or `PATCH /v1/resources/{id}/preview` sets an empty
+ * one. Nothing was written; add the public name and retry.
+ */
+exports.ERROR_CODE_NAME_REQUIRED = "name_required";
 /** 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";
 /**
@@ -70,6 +76,8 @@ class QURLError extends Error {
     invalidFields;
     requestId;
     retryAfter;
+    /** Retained resource metadata supplied by a 410 Gone response. */
+    tombstone;
     /** Known minted IDs from a rejected terminal batch, for bounded cleanup. No bearer links. */
     partialQurlIds;
     constructor(data) {
@@ -87,6 +95,7 @@ class QURLError extends Error {
         this.invalidFields = data.invalid_fields;
         this.requestId = data.request_id;
         this.retryAfter = data.retry_after;
+        this.tombstone = data.tombstone;
     }
 }
 exports.QURLError = QURLError;

package/dist/cjs/index.d.ts

@@ -2,6 +2,8 @@ export { ConnectorResource, isApiKeyRequestScope, ProtectedResource, QURLClient,
 export type { EnsureConnectorResourceResult } from "./client.js";
 export { CRIDVerificationError, ShareLink } from "./share.js";
 export type { CRIDVerificationErrorCode, ShareLinkInit, ShareLinkJSON } from "./share.js";
-export { AuthenticationError, AuthorizationError, ConnectorResourceOutcomeUnknownError, createError, DelegatedBatchOutcomeUnknownError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, ERROR_CODE_CRID_MISMATCH, ERROR_CODE_DELEGATED_BATCH_OUTCOME_UNKNOWN, ERROR_CODE_INVALID_CRID, ERROR_CODE_INVALID_CRID_KEY, ERROR_CODE_MISSING_CRID, ERROR_CODE_NETWORK, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_RUNTIME, ERROR_CODE_TIMEOUT, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RateLimitError, RuntimeError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
+export { AuthenticationError, AuthorizationError, ConnectorResourceOutcomeUnknownError, createError, DelegatedBatchOutcomeUnknownError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, ERROR_CODE_CRID_MISMATCH, ERROR_CODE_DELEGATED_BATCH_OUTCOME_UNKNOWN, ERROR_CODE_INVALID_CRID, ERROR_CODE_INVALID_CRID_KEY, ERROR_CODE_MISSING_CRID, ERROR_CODE_NAME_REQUIRED, ERROR_CODE_NETWORK, ERROR_CODE_RESOURCE_NOT_FOUND, ERROR_CODE_RUNTIME, ERROR_CODE_TIMEOUT, ERROR_CODE_UNEXPECTED_RESPONSE, ERROR_CODE_UNKNOWN, NetworkError, NotFoundError, QURLError, RateLimitError, RuntimeError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
 export { VERSION } from "./version.js";
-export type { ConsumerAccessPolicy, AccessCode, AccessCodeListOutput, AccessGrant, ConsumerInvitation, ConsumerGrant, ConsumerGrantApprovalInput, ConsumerListInput, ConsumerInvitationListOutput, ConsumerGrantListOutput, AccessPolicy, AccessToken, AIAgentCategory, AIAgentPolicy, ApiKey, ApiKeyListOutput, ApiKeyRequestScope, ApiKeyScope, BatchCreateInput, BatchCreateOutput, BatchItemFailure, BatchItemResult, BatchItemSuccess, BillingInvoiceListOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationCapabilities, ConnectorInstallationListOutput, ConnectorInstallationStats, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateDurableApiKeyInput, CreateEnrollmentTokenInput, CreateBillingCheckoutInput, CreateDelegatedQurlBatchInput, CreateDelegatedQurlBatchOptions, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, CredentialClaim, CredentialClaimInput, CredentialKind, CredentialTarget, CredentialTargetInput, Customer, CheckoutSession, DnsRecord, Domain, DomainCheckDetail, DomainListOutput, DomainVerifyResult, DelegatedQurl, DelegatedQurlBatchAccepted, DelegatedQurlBatchItemFailure, DelegatedQurlBatchItemResult, DelegatedQurlBatchItemSuccess, DelegatedQurlBatchNotModified, DelegatedQurlBatchPending, DelegatedQurlBatchStatus, DelegatedQurlBatchTerminal, DelegatedQurlCreatedData, DelegatedQurlGrant, ExtendInput, Invoice, GetDelegatedQurlBatchOptions, GetDelegatedQurlBatchOutput, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListInput, ListOutput, ListWebhooksInput, ListWebhookDeliveriesInput, Meta, MintInput, MintOutput, PaginatedOutput, Portal, PortalSession, ProtectUrlOptions, QURL, QURLErrorData, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceHandle, ResourceListInput, ResourceListOutput, ResourceType, RequestOptions, ResolveInput, ResolveOutput, Session, SessionListOutput, SessionTerminateOutput, ShareResourceOptions, TombstoneInfo, UnpaginatedOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCostEstimate, UsageCurrentPeriod, UsageDaily, UsageDailyEntry, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventType, WebhookEventTypeInfo, WebhookListOutput, WebhookPayload, WebhookWithSecret, } from "./types.js";
+export type { ConsumerAccessPolicy, CRIDPaymentPolicy, AccessCode, AccessCodeListOutput, AccessGrant, ConsumerInvitation, ConsumerGrant, ConsumerGrantApprovalInput, ConsumerListInput, ConsumerInvitationListOutput, ConsumerGrantListOutput, AccessPolicy, AccessToken, AIAgentCategory, AIAgentPolicy, ApiKey, ApiKeyListOutput, ApiKeyRequestScope, ApiKeyScope, BatchCreateInput, BatchCreateOutput, BatchItemFailure, BatchItemResult, BatchItemSuccess, BillingInvoiceListOutput, CallerIdentity, ClientOptions, ConnectorInstallation, ConnectorInstallationCapabilities, ConnectorInstallationListOutput, ConnectorInstallationStats, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateExternalIdentityBindingInput, CreateExternalIdentityBindingOutput, CreateDurableApiKeyInput, CreateEnrollmentTokenInput, CreateBillingCheckoutInput, CreateDelegatedQurlBatchInput, CreateDelegatedQurlBatchOptions, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, CredentialClaim, CredentialClaimInput, CredentialKind, CredentialTarget, CredentialTargetInput, Customer, CheckoutSession, DnsRecord, Domain, DomainCheckDetail, DomainListOutput, DomainVerifyResult, DelegatedQurl, DelegatedQurlBatchAccepted, DelegatedQurlBatchItemFailure, DelegatedQurlBatchItemResult, DelegatedQurlBatchItemSuccess, DelegatedQurlBatchNotModified, DelegatedQurlBatchPending, DelegatedQurlBatchStatus, DelegatedQurlBatchTerminal, DelegatedQurlCreatedData, DelegatedQurlGrant, ExternalIdentityProvider, ExtendInput, Invoice, GetDelegatedQurlBatchOptions, GetDelegatedQurlBatchOutput, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListInput, ListOutput, ListWebhooksInput, ListWebhookDeliveriesInput, Meta, MintInput, MintOutput, PaginatedOutput, Portal, PortalSession, ProtectUrlOptions, QURL, QURLErrorData, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceHandle, ResourceListInput, ResourceListOutput, ResourceType, RequestOptions, ResolveInput, ResolveOutput, Session, SessionListOutput, SessionTerminateOutput, ShareResourceOptions, TombstoneInfo, UnpaginatedOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCostEstimate, UsageCurrentPeriod, UsageDaily, UsageDailyEntry, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventType, WebhookEventTypeInfo, WebhookListOutput, WebhookPayload, WebhookWithSecret, } from "./types.js";
+export { getResponseMetadata } from "./response-metadata.js";
+export type { ResponseMetadata } from "./response-metadata.js";

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.ValidationError = exports.TimeoutError = exports.ServerError = exports.RuntimeError = exports.RateLimitError = exports.QURLError = exports.NotFoundError = exports.NetworkError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_MISSING_CRID = exports.ERROR_CODE_INVALID_CRID_KEY = exports.ERROR_CODE_INVALID_CRID = exports.ERROR_CODE_DELEGATED_BATCH_OUTCOME_UNKNOWN = exports.ERROR_CODE_CRID_MISMATCH = exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = exports.ERROR_CODE_CLIENT_VALIDATION = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.DelegatedBatchOutcomeUnknownError = exports.createError = exports.ConnectorResourceOutcomeUnknownError = exports.AuthorizationError = exports.AuthenticationError = exports.ShareLink = exports.CRIDVerificationError = exports.QURLClient = exports.ProtectedResource = exports.isApiKeyRequestScope = exports.ConnectorResource = void 0;
+exports.getResponseMetadata = exports.VERSION = exports.ValidationError = exports.TimeoutError = exports.ServerError = exports.RuntimeError = exports.RateLimitError = exports.QURLError = exports.NotFoundError = exports.NetworkError = exports.ERROR_CODE_UNKNOWN = exports.ERROR_CODE_UNEXPECTED_RESPONSE = exports.ERROR_CODE_TIMEOUT = exports.ERROR_CODE_RUNTIME = exports.ERROR_CODE_RESOURCE_NOT_FOUND = exports.ERROR_CODE_NETWORK = exports.ERROR_CODE_NAME_REQUIRED = exports.ERROR_CODE_MISSING_CRID = exports.ERROR_CODE_INVALID_CRID_KEY = exports.ERROR_CODE_INVALID_CRID = exports.ERROR_CODE_DELEGATED_BATCH_OUTCOME_UNKNOWN = exports.ERROR_CODE_CRID_MISMATCH = exports.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED = exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = exports.ERROR_CODE_CLIENT_VALIDATION = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.DelegatedBatchOutcomeUnknownError = exports.createError = exports.ConnectorResourceOutcomeUnknownError = exports.AuthorizationError = exports.AuthenticationError = exports.ShareLink = exports.CRIDVerificationError = exports.QURLClient = exports.ProtectedResource = exports.isApiKeyRequestScope = exports.ConnectorResource = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "ConnectorResource", { enumerable: true, get: function () { return client_js_1.ConnectorResource; } });
 Object.defineProperty(exports, "isApiKeyRequestScope", { enumerable: true, get: function () { return client_js_1.isApiKeyRequestScope; } });
@@ -24,6 +24,7 @@ Object.defineProperty(exports, "ERROR_CODE_DELEGATED_BATCH_OUTCOME_UNKNOWN", { e
 Object.defineProperty(exports, "ERROR_CODE_INVALID_CRID", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_INVALID_CRID; } });
 Object.defineProperty(exports, "ERROR_CODE_INVALID_CRID_KEY", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_INVALID_CRID_KEY; } });
 Object.defineProperty(exports, "ERROR_CODE_MISSING_CRID", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_MISSING_CRID; } });
+Object.defineProperty(exports, "ERROR_CODE_NAME_REQUIRED", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_NAME_REQUIRED; } });
 Object.defineProperty(exports, "ERROR_CODE_NETWORK", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_NETWORK; } });
 Object.defineProperty(exports, "ERROR_CODE_RESOURCE_NOT_FOUND", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_RESOURCE_NOT_FOUND; } });
 Object.defineProperty(exports, "ERROR_CODE_RUNTIME", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_RUNTIME; } });
@@ -40,3 +41,5 @@ Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function
 Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
 var version_js_1 = require("./version.js");
 Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_js_1.VERSION; } });
+var response_metadata_js_1 = require("./response-metadata.js");
+Object.defineProperty(exports, "getResponseMetadata", { enumerable: true, get: function () { return response_metadata_js_1.getResponseMetadata; } });

package/dist/cjs/response-metadata.d.ts

@@ -0,0 +1,13 @@
+/** Correlation metadata from one successful API response. */
+export interface ResponseMetadata {
+    readonly requestId: string;
+}
+/**
+ * Read this result's server correlation ID. Metadata is non-enumerable and is
+ * not part of its JSON payload. Local handles and responses without an ID return undefined.
+ */
+export declare function getResponseMetadata(value: unknown): Readonly<ResponseMetadata> | undefined;
+/** @internal Attach only an identifier already validated at the HTTP boundary. */
+export declare function withResponseMetadata<T>(value: T, requestId: string | undefined): T;
+/** @internal Preserve correlation when a response becomes a new SDK value. */
+export declare function copyResponseMetadata<T>(source: unknown, value: T): T;

package/dist/cjs/response-metadata.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getResponseMetadata = getResponseMetadata;
+exports.withResponseMetadata = withResponseMetadata;
+exports.copyResponseMetadata = copyResponseMetadata;
+// A constant global symbol survives mixed ESM/CJS loads without a mutable registry.
+const RESPONSE_METADATA = Symbol.for("@layervai/qurl.responseMetadata.v1");
+function isObject(value) {
+    return value !== null && (typeof value === "object" || typeof value === "function");
+}
+/**
+ * Read this result's server correlation ID. Metadata is non-enumerable and is
+ * not part of its JSON payload. Local handles and responses without an ID return undefined.
+ */
+function getResponseMetadata(value) {
+    if (!isObject(value))
+        return undefined;
+    return Object.getOwnPropertyDescriptor(value, RESPONSE_METADATA)?.value;
+}
+/** @internal Attach only an identifier already validated at the HTTP boundary. */
+function withResponseMetadata(value, requestId) {
+    if (!isObject(value) || !requestId)
+        return value;
+    // Diagnostic metadata must not turn a successful mutation into a failure.
+    if (Object.getOwnPropertyDescriptor(value, RESPONSE_METADATA) || !Object.isExtensible(value))
+        return value;
+    Object.defineProperty(value, RESPONSE_METADATA, {
+        value: Object.freeze({ requestId }),
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return value;
+}
+/** @internal Preserve correlation when a response becomes a new SDK value. */
+function copyResponseMetadata(source, value) {
+    return withResponseMetadata(value, getResponseMetadata(source)?.requestId);
+}

package/dist/cjs/share.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShareLink = exports.CRIDVerificationError = void 0;
+const response_metadata_js_1 = require("./response-metadata.js");
 const errors_js_1 = require("./errors.js");
 const crid_js_1 = require("./crid.js");
 /** A local, fail-closed CRID verification failure. */
@@ -48,6 +49,7 @@ class ShareLink {
         this.#expiresAtEpochMs = Number.isFinite(expiresAtEpochMs) ? expiresAtEpochMs : undefined;
         this.expiresInSeconds = init.expiresInSeconds;
         this.singleUse = init.singleUse;
+        (0, response_metadata_js_1.copyResponseMetadata)(init, this);
         Object.freeze(this);
     }
     /** Effective expiry as a defensive copy; mutating it does not change this share. */

package/dist/cjs/target-path.d.ts

@@ -0,0 +1,2 @@
+export declare function isCanonicalTargetPath(value: unknown): value is string;
+export declare function requireCanonicalTargetPath(value: string | undefined, field: string): void;

package/dist/cjs/target-path.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCanonicalTargetPath = isCanonicalTargetPath;
+exports.requireCanonicalTargetPath = requireCanonicalTargetPath;
+const client_errors_js_1 = require("./client-errors.js");
+const client_limits_js_1 = require("./client-limits.js");
+const client_validation_js_1 = require("./client-validation.js");
+// TODO(upstream-contract): qurl-service ValidateTargetPath and the released
+// target_path_v1_vectors define this grammar without normalization.
+const INVALID_TARGET_PATH_ASCII = /[^A-Za-z0-9._~!$&()*+,;=:@%/?-]/;
+const MALFORMED_PERCENT_ESCAPE = /%(?![0-9a-fA-F]{2})/;
+function isCanonicalTargetPath(value) {
+    if (typeof value !== "string" ||
+        value.length > client_limits_js_1.MAX_TARGET_PATH ||
+        value.startsWith("//") ||
+        !value.startsWith("/") ||
+        INVALID_TARGET_PATH_ASCII.test(value) ||
+        MALFORMED_PERCENT_ESCAPE.test(value))
+        return false;
+    const path = value.split("?", 1)[0];
+    // Queries remain encoded data; only the path defines authorization.
+    return (!/[%!()*;]/.test(path) &&
+        !path.slice(1).includes("//") &&
+        !path.split("/").some((segment) => segment === "." || segment === ".."));
+}
+function requireCanonicalTargetPath(value, field) {
+    if (value === undefined)
+        return;
+    (0, client_validation_js_1.requireMaxUtf8Bytes)(value, field, client_limits_js_1.MAX_TARGET_PATH);
+    (0, client_validation_js_1.requireNonEmptyIfPresent)(value, field);
+    if (!isCanonicalTargetPath(value)) {
+        throw (0, client_errors_js_1.clientValidationError)(`${field}: must be a canonical ASCII path with optional query`);
+    }
+}

package/dist/cjs/types.d.ts

@@ -56,7 +56,8 @@ export interface AccessToken {
     use_count: number;
     qurl_site?: string;
     created_at: string;
-    expires_at: string;
+    /** Optional in API summaries; omission does not imply an unlimited lifetime. */
+    expires_at?: string;
 }
 /** Per-qURL summary returned from resource-detail and token-update endpoints. */
 export interface QurlSummary {
@@ -113,6 +114,15 @@ export interface QURL {
  * the resource and must be set through {@link UpdateInput} after creation.
  */
 export interface CreateInput {
+    /**
+     * Public name recipients see: the qURL page, link previews, and the passkey
+     * they save. Not `description`, which stays a private owner note. Sent only
+     * when set; needs a qURL API version that accepts it. The service requires
+     * it when this call creates a resource (`400 name_required` otherwise) and
+     * ignores it when an existing resource is reused. Rename later with
+     * `PATCH /v1/resources/{id}/preview`.
+     */
+    name?: string;
     /** Omit to keep an existing resource's privacy; a new URL or Connector resource defaults to private. */
     private?: boolean;
     type?: ResourceType;
@@ -137,6 +147,8 @@ export interface CreateOutput {
     expires_at?: string;
     label?: string;
     type?: ResourceType;
+    /** Recorded Connector path scope; omitted for the bare origin. */
+    target_path?: string;
 }
 /** Input for listing qURLs. */
 export interface ListInput {
@@ -237,6 +249,8 @@ export interface MintOutput {
 }
 /** Options for `QURLClient.protectUrl`. */
 export interface ProtectUrlOptions {
+    /** Public resource name; see {@link CreateInput.name}. */
+    name?: string;
     private?: boolean;
     consumerAccess?: ConsumerAccessPolicy;
     /** Optional resource-level metadata. Max 500 chars. */
@@ -282,11 +296,17 @@ export interface CreatePortalOptions {
     sessionDuration?: string | number;
     /**
      * Scope a qURL for an existing tunnel resource to one path and its
-     * descendants. The SDK rejects only empty values and values over 2048 UTF-8
-     * bytes; the API remains authoritative for the path grammar and resource
-     * type. This option is invalid with `createPortalForUrl`.
+     * descendants. Must be a canonical ASCII path with optional query, at most
+     * 2048 bytes. The API enforces the tunnel-only resource boundary.
+     * This option is invalid with `createPortalForUrl`.
      */
     targetPath?: string;
+    /**
+     * Public name of the resource `createPortalForUrl` creates; see
+     * {@link CreateInput.name}. Required by the service when that call creates a
+     * resource. `createPortal` rejects it: the resource already exists.
+     */
+    name?: string;
 }
 /**
  * A qURL link minted for a protected resource.
@@ -312,6 +332,8 @@ export interface Portal {
     qurlId?: string;
     /** Token label, when returned by the API. */
     label?: string;
+    /** Recorded Connector path scope; absent means bare origin. */
+    targetPath?: string;
 }
 /**
  * Result of a successful `enterPortal`: the reachable resource.
@@ -345,7 +367,10 @@ export interface ResolveOutput {
     resource_id: string;
     access_grant?: AccessGrant;
 }
-/** Quota information. */
+/**
+ * Quota information. The API schema does not require rate_limits, usage, or
+ * their inner fields; minimal responses may omit them. Check presence before use.
+ */
 export interface Quota {
     plan: "free" | "growth" | "enterprise" | (string & {});
     period_start: string;
@@ -413,6 +438,7 @@ export interface BatchCreateOutput {
     succeeded: number;
     failed: number;
     results: BatchItemResult[];
+    /** Canonical meta.request_id wins; data.request_id is preserved when meta omits it. */
     request_id?: string;
 }
 /** One recipient grant redeemed from an opaque delegated mint capability. */
@@ -513,13 +539,22 @@ export interface DelegatedQurl {
     access_policy?: AccessPolicy;
 }
 /** Private resource policy. Contract fulfillment comes from the publisher backend. */
+export interface CRIDPaymentPolicy {
+    account_id: string;
+    price_id: string;
+    /** One-time access duration; zero lasts for the resource lifetime. Subscriptions require zero. */
+    access_seconds: number;
+}
 export interface ConsumerAccessPolicy {
     mode: "keys" | "invite_only" | "email_capture" | "review" | "contract";
     version: number;
     contract_id?: string;
+    payment?: CRIDPaymentPolicy;
 }
 /** Input for creating a resource directly. */
 export interface CreateResourceInput {
+    /** Public resource name; see {@link CreateInput.name}. */
+    name?: string;
     private?: boolean;
     consumer_access?: ConsumerAccessPolicy;
     type?: ResourceType;
@@ -603,7 +638,7 @@ export interface ShareResourceOptions {
     ttlSeconds?: number;
 }
 /** Input for minting a qURL against an existing resource. */
-export type CreateQurlForResourceInput = Omit<CreateInput, "target_url" | "custom_domain" | "type" | "private"> & {
+export type CreateQurlForResourceInput = Omit<CreateInput, "target_url" | "custom_domain" | "type" | "private" | "name"> & {
     /**
      * Path this resource qURL resolves to (e.g. "/api/detect").
      *
@@ -916,6 +951,16 @@ export interface UpdateApiKeyInput {
     name?: string;
     scopes?: ApiKeyRequestScope[];
 }
+/** Identity of the credential used for the current request. */
+export interface CallerIdentity {
+    owner_id: string;
+    auth_type: OpenString<"api_key" | "jwt">;
+    /**
+     * Available API-key metadata, which may be omitted even for an API-key caller.
+     * JWT callers omit it. Display fields are optional; no credential secret is returned.
+     */
+    api_key?: ApiKey;
+}
 export interface ApiKey {
     key_id?: string;
     key_prefix?: string;
@@ -997,6 +1042,7 @@ export interface QURLErrorData {
     invalid_fields?: Record<string, string>;
     request_id?: string;
     retry_after?: number;
+    tombstone?: TombstoneInfo;
 }
 /** Per-call options accepted by mutating requests. */
 export interface RequestOptions {
@@ -1018,13 +1064,19 @@ export interface ClientOptions {
     /** Base URL. Defaults to https://api.layerv.ai */
     baseUrl?: string;
     /**
-     * Custom fetch implementation. Redirect-safety requires it to honor
+     * Custom fetch implementation, called with globalThis as its receiver.
+     * Bind methods that need a different receiver. Redirect-safety requires it to honor
      * `redirect: "manual"`, accurately expose `Response.redirected`, and leave
      * `Response.url` empty or set it to the normalized request URL when no
      * redirect was followed. Every Response-like result must also provide a
      * `headers` object with a WHATWG-compatible `headers.get(name)` method.
      */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Decoded API response bytes per request. Default: 1 MiB.
+     * Integer range: 1 byte through 16 MiB.
+     */
+    maxResponseBodyBytes?: number;
     /** Maximum retry attempts for transient errors (429, 5xx). Default: 3. */
     maxRetries?: number;
     /**
@@ -1081,4 +1133,28 @@ export interface ConsumerInvitationListOutput extends PaginatedOutput {
 export interface ConsumerGrantListOutput extends PaginatedOutput {
     grants: ConsumerGrant[];
 }
+/** Provider authenticated by its configured confidential OAuth client. */
+export type ExternalIdentityProvider = "slack" | "discord" | "teams";
+export interface CreateExternalIdentityBindingInput {
+    provider: ExternalIdentityProvider;
+    external_id: string;
+    display_name?: string;
+    /** Explicit reauthorization only; revokes the previous binding key. */
+    rotate_existing?: boolean;
+}
+/** Persist api_key.plaintext securely immediately; never log this result. */
+export interface CreateExternalIdentityBindingOutput {
+    binding_id: string;
+    provider: ExternalIdentityProvider;
+    external_id: string;
+    display_name?: string;
+    api_key: {
+        key_id: string;
+        key_prefix: string;
+        /** One-time secret, replayable only with the same request within 24 hours. */
+        plaintext: string;
+    };
+    scopes: ApiKeyRequestScope[];
+    created_at: string;
+}
 export {};

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "3.1.1";
+export declare const VERSION = "4.0.0";

package/dist/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = "3.1.1"; // x-release-please-version
+exports.VERSION = "4.0.0"; // x-release-please-version

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

@@ -0,0 +1,44 @@
+import type { CreatePortalOptions, Portal, RequestOptions, Resource } from "./types.js";
+import type { QURLClient } from "./client.js";
+export declare const CONNECTOR_SLUG_PATTERN: RegExp;
+export declare function requireConnectorSlug(slug: string, method: string): void;
+export declare function classifyConnectorMutationFailure(operation: "ensure" | "delete", error: unknown): never;
+export declare function requireConnectorSubtleCrypto(method: string): void;
+type ConnectorResourceExpectation = {
+    slug?: string;
+    crid?: string;
+    revokedIsLifecycleError?: boolean;
+};
+export declare function verifyResourceIdentity(resource: {
+    resource_id?: unknown;
+    crid?: unknown;
+} | undefined, method: string, expectedCrid?: string): Promise<void>;
+export declare function parseConnectorResource(client: QURLClient, value: unknown, method: string, expectation?: ConnectorResourceExpectation): Promise<ConnectorResource>;
+/** Result of idempotently ensuring a qURL Connector resource. */
+export interface EnsureConnectorResourceResult {
+    resource: ConnectorResource;
+    foundExisting: boolean;
+}
+declare const CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN: unique symbol;
+/**
+ * A validated qURL Connector resource bound to the client that loaded it.
+ *
+ * Resource identity, reverse-routing identity, and NHP admission identity are
+ * distinct server-issued values. Callers must consume each field verbatim and
+ * must never derive one from another.
+ */
+export declare class ConnectorResource {
+    #private;
+    readonly resourcePublicKey: string;
+    /** Required public identifier, verified against the returned resource key. */
+    readonly crid: string;
+    readonly connectorRoutingId: string;
+    readonly knockResourceId: string;
+    readonly slug: string;
+    readonly alias?: string;
+    /** @internal Instances are returned by QURLClient after wire validation. */
+    constructor(client: QURLClient, details: Resource, validationToken: typeof CONNECTOR_RESOURCE_CONSTRUCTOR_TOKEN);
+    /** Mint a short-lived portal for this Connector resource. */
+    createPortal(opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
+}
+export {};