@layervai/qurl 0.4.0 → 0.6.0

package/dist/cjs/index.d.ts

@@ -1,4 +1,5 @@
-export { ProtectedResource, QURLClient } from "./client.js";
-export { AuthenticationError, AuthorizationError, createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, 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 { ConnectorResource, ProtectedResource, QURLClient } from "./client.js";
+export type { EnsureConnectorResourceResult } from "./client.js";
+export { AuthenticationError, AuthorizationError, ConnectorResourceOutcomeUnknownError, createError, ERROR_CODE_AMBIGUOUS_RESOURCE, ERROR_CODE_CLIENT_VALIDATION, ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN, ERROR_CODE_CONNECTOR_RESOURCE_REVOKED, 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 { AccessCode, AccessCodeListOutput, AccessGrant, AccessPolicy, AccessToken, AIAgentCategory, AIAgentPolicy, ApiKey, ApiKeyListOutput, ApiKeyScope, BatchCreateInput, BatchCreateOutput, BatchItemFailure, BatchItemResult, BatchItemSuccess, BillingInvoiceListOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationCapabilities, ConnectorInstallationListOutput, ConnectorInstallationStats, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, DnsRecord, Domain, DomainCheckDetail, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, 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, TombstoneInfo, UnpaginatedOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCostEstimate, UsageCurrentPeriod, UsageDaily, UsageDailyEntry, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventType, WebhookEventTypeInfo, WebhookListOutput, WebhookPayload, WebhookWithSecret, } from "./types.js";

package/dist/cjs/index.js

@@ -1,15 +1,19 @@
 "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_CLIENT_VALIDATION = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.createError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLClient = exports.ProtectedResource = void 0;
+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_CONNECTOR_RESOURCE_REVOKED = exports.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN = exports.ERROR_CODE_CLIENT_VALIDATION = exports.ERROR_CODE_AMBIGUOUS_RESOURCE = exports.createError = exports.ConnectorResourceOutcomeUnknownError = exports.AuthorizationError = exports.AuthenticationError = exports.QURLClient = exports.ProtectedResource = 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, "ProtectedResource", { enumerable: true, get: function () { return client_js_1.ProtectedResource; } });
 Object.defineProperty(exports, "QURLClient", { enumerable: true, get: function () { return client_js_1.QURLClient; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
 Object.defineProperty(exports, "AuthorizationError", { enumerable: true, get: function () { return errors_js_1.AuthorizationError; } });
+Object.defineProperty(exports, "ConnectorResourceOutcomeUnknownError", { enumerable: true, get: function () { return errors_js_1.ConnectorResourceOutcomeUnknownError; } });
 Object.defineProperty(exports, "createError", { enumerable: true, get: function () { return errors_js_1.createError; } });
 Object.defineProperty(exports, "ERROR_CODE_AMBIGUOUS_RESOURCE", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_AMBIGUOUS_RESOURCE; } });
 Object.defineProperty(exports, "ERROR_CODE_CLIENT_VALIDATION", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CLIENT_VALIDATION; } });
+Object.defineProperty(exports, "ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CONNECTOR_RESOURCE_OUTCOME_UNKNOWN; } });
+Object.defineProperty(exports, "ERROR_CODE_CONNECTOR_RESOURCE_REVOKED", { enumerable: true, get: function () { return errors_js_1.ERROR_CODE_CONNECTOR_RESOURCE_REVOKED; } });
 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; } });

package/dist/cjs/node/deployment.d.ts

@@ -32,7 +32,7 @@ interface DeploymentFileRuntime {
     readonly read: (descriptor: number, buffer: Buffer, offset: number, length: number, position: number) => number;
     readonly close: (descriptor: number) => void;
 }
-/** Load and validate deployment trust once, before an opener can do network I/O. */
+/** Load and validate deployment trust before an opener can do network I/O. */
 export declare function loadPortalDeployment(explicit?: PortalDeployment): ValidatedDeployment;
 declare function readBoundedDeploymentFile(path: string, runtime?: DeploymentFileRuntime): Buffer;
 export declare function fingerprintKey(key: Uint8Array): string;

package/dist/cjs/node/deployment.js

@@ -17,7 +17,7 @@ const defaultDeploymentFileRuntime = {
     read: node_fs_1.readSync,
     close: node_fs_1.closeSync,
 };
-/** Load and validate deployment trust once, before an opener can do network I/O. */
+/** Load and validate deployment trust before an opener can do network I/O. */
 function loadPortalDeployment(explicit) {
     if (explicit !== undefined)
         return validateDeployment(explicit);
@@ -32,7 +32,7 @@ function loadPortalDeployment(explicit) {
     return validateDeploymentValue((0, strict_json_js_1.parseStrictJson)(raw, MAX_DEPLOYMENT_BYTES));
 }
 function readBoundedDeploymentFile(path, runtime = defaultDeploymentFileRuntime) {
-    // O_NONBLOCK prevents a FIFO or device path from hanging construction before
+    // O_NONBLOCK prevents a FIFO or device path from hanging startup before
     // fstat can enforce the regular-file contract. It has no effect on files.
     const descriptor = runtime.open(path, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NONBLOCK);
     try {

package/dist/cjs/node/native-udp.d.ts

@@ -2,13 +2,11 @@ import { lookup } from "node:dns/promises";
 import { type Socket } from "node:dgram";
 import { buildNHPMessage, decryptNHPReply, type NHPMessage } from "./nhp-wire.js";
 import type { ValidatedCell } from "./deployment.js";
-export declare const NATIVE_DEFAULT_TIMEOUT_MS = 3000;
-export declare const NATIVE_DEFAULT_MAX_ADDRESSES = 3;
 export interface NativeExchangeOptions {
     readonly signal?: AbortSignal;
-    /** Per-address timeout; serial fallback can use maxAddresses times this value. */
+    /** Internal per-address timeout. PortalOpener does not expose this setting. */
     readonly timeoutMs?: number;
-    /** Maximum number of resolved addresses tried serially. */
+    /** Internal serial-address cap. PortalOpener does not expose this setting. */
     readonly maxAddresses?: number;
 }
 interface NativeKnockRuntime {

package/dist/cjs/node/native-udp.js

@@ -1,15 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nativeUdpTesting = exports.NATIVE_DEFAULT_MAX_ADDRESSES = exports.NATIVE_DEFAULT_TIMEOUT_MS = void 0;
+exports.nativeUdpTesting = void 0;
 exports.nativeKnock = nativeKnock;
 const promises_1 = require("node:dns/promises");
 const node_dgram_1 = require("node:dgram");
 const node_net_1 = require("node:net");
 const nhp_wire_js_1 = require("./nhp-wire.js");
-// Keep these defaults exported inside the Node implementation so the portal
-// lifecycle can derive one bounded whole-open deadline from the same values.
-exports.NATIVE_DEFAULT_TIMEOUT_MS = 3_000;
-exports.NATIVE_DEFAULT_MAX_ADDRESSES = 3;
+// These are internal per-address exchange bounds. PortalOpener applies its own
+// whole-open deadline and does not expose per-address tuning.
+const NATIVE_DEFAULT_TIMEOUT_MS = 3_000;
+const NATIVE_DEFAULT_MAX_ADDRESSES = 3;
 const ipv4Denied = new node_net_1.BlockList();
 // Keep this set in lockstep with qurl-go's nonRoutablePrefixes plus the
 // IsPrivate/IsLoopback/IsLinkLocal/IsMulticast predicates it applies first.
@@ -107,13 +107,13 @@ async function nativeKnockWithRuntime(cell, devicePrivateKey, body, options, run
         body,
     });
     try {
-        const addresses = await runtime.resolveAddresses(cell.host, options.maxAddresses ?? exports.NATIVE_DEFAULT_MAX_ADDRESSES, options.signal);
+        const addresses = await runtime.resolveAddresses(cell.host, options.maxAddresses ?? NATIVE_DEFAULT_MAX_ADDRESSES, options.signal);
         let lastError;
         for (const address of addresses) {
             try {
-                const packet = await runtime.exchange(address.address, address.family, cell.port, built.packet, options.timeoutMs ?? exports.NATIVE_DEFAULT_TIMEOUT_MS, options.signal);
+                const packet = await runtime.exchange(address.address, address.family, cell.port, built.packet, options.timeoutMs ?? NATIVE_DEFAULT_TIMEOUT_MS, options.signal);
                 const reply = runtime.decryptReply(devicePrivateKey, cell.serverPublicKey, packet);
-                // NHP 1.1 COOKIE is a stateless busy response. Go intentionally does
+                // NHP COOKIE is a stateless busy response. Go intentionally does
                 // not bind its counter to the request; only an ACK must match it.
                 if (reply.type === nhp_wire_js_1.NHP_TYPE_COOKIE)
                     return reply;

package/dist/cjs/node/portal-opener.d.ts

@@ -3,43 +3,53 @@ import { type PortalDeployment, type ValidatedCell, type ValidatedDeployment } f
 import { type NativeExchangeOptions } from "./native-udp.js";
 import { type VerifiedQv2Link } from "./qv2.js";
 export interface CreatePortalOpenerOptions {
-    /** Full qv2t1 qURL. The opener verifies and then drops this immutable string. */
+    /** Full qv2t1 qURL. The opener re-verifies it before each native open. */
     readonly qurl: string;
-    /** Native-only is deliberate. There is no relay or HTTP-resolve fallback. */
-    readonly transport: "native-only";
-    /** Public deployment trust. Omit to load QURL_DEPLOYMENT once at construction. */
+    /** Public deployment trust. Omit to load QURL_DEPLOYMENT on the first start. */
     readonly deployment?: PortalDeployment;
-    /** Per-address UDP attempt timeout. Use start({ signal }) for one overall deadline. */
-    readonly timeoutMs?: number;
-    /** Maximum serial address attempts for one native exchange. */
-    readonly maxAddresses?: number;
+    /** Whole-operation deadline for each NHP open. The default is 15 seconds. */
+    readonly openTimeoutMs?: number;
+    /** Protected-content fetch implementation. Native NHP opening never uses it. */
+    readonly fetch?: typeof globalThis.fetch;
 }
 export interface PortalStartOptions {
     readonly signal?: AbortSignal;
 }
+/**
+ * Build one request for the exact target selected by `fetch` or
+ * `fetchDescendant`. The URL is a disposable copy; the opener pins the final
+ * request URL and Host to its SDK-owned target after this function returns.
+ */
 export type PortalRequestBuilder = (authenticatedTarget: URL) => RequestInit;
 export interface PortalFetchOptions {
     /** Use `error` for signed requests whose method, target, timestamp, and nonce must not be replayed. */
     readonly redirects?: "follow" | "error";
 }
-export type PortalRenewalFailure = {
-    readonly kind: "transport" | "busy" | "denied" | "invalid_reply" | "local_state";
-};
-export type PortalSessionHealth = {
-    readonly state: "idle" | "starting" | "closed";
-} | {
-    readonly state: "healthy" | "renewing" | "degraded" | "expired";
-    readonly expiresInMs: number;
-    readonly backgroundAttempts: number;
-    readonly renewalFailure?: PortalRenewalFailure;
-};
+export type PortalOpenerState = "new" | "starting" | "ready" | "degraded" | "closed";
+export type PortalOpenerFailureClass = "" | "open_failed" | "target_changed";
+/** Secret-free, nonblocking lifecycle snapshot. */
+export interface PortalOpenerHealth {
+    readonly state: PortalOpenerState;
+    readonly ready: boolean;
+    readonly expiresAt?: Date;
+    readonly renewAt?: Date;
+    readonly lastOpenSucceededAt?: Date;
+    readonly lastFailureClass: PortalOpenerFailureClass;
+    readonly consecutiveFailures: number;
+}
 export interface PortalOpener {
     /** Open now and schedule renewal before the admission expires. */
     start(options?: PortalStartOptions): Promise<void>;
     /** Start a fetch at the exact ACK URL. Same-origin redirects follow only when allowed. */
     fetch(init?: RequestInit | PortalRequestBuilder, options?: PortalFetchOptions): Promise<Response>;
+    /**
+     * Start a fetch below the ACK URL. Each caller value is one raw path segment;
+     * the opener validates and escapes each segment before use. The ACK target's
+     * query is preserved.
+     */
+    fetchDescendant(pathSegments: readonly string[], init?: RequestInit | PortalRequestBuilder, options?: PortalFetchOptions): Promise<Response>;
     /** Read local session state. This method does no I/O and exposes no capability. */
-    health(): PortalSessionHealth;
+    health(): PortalOpenerHealth;
     /** Stop renewal and wipe mutable private-key, visitor-secret, and token buffers. */
     close(): Promise<void>;
 }
@@ -56,6 +66,27 @@ export declare class PortalDenyError extends Error {
 export declare class PortalStateError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
+export declare class PortalOpenerNotStartedError extends PortalStateError {
+    constructor();
+}
+export declare class PortalOpenerNotReadyError extends PortalStateError {
+    constructor(options?: ErrorOptions);
+}
+export declare class PortalOpenerClosedError extends PortalStateError {
+    constructor(options?: ErrorOptions);
+}
+export declare class PortalOpenTimeoutError extends PortalStateError {
+    constructor();
+}
+export declare class PortalTargetChangedError extends PortalStateError {
+    constructor();
+}
+export declare class PortalRedirectError extends PortalStateError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class PortalTooManyRedirectsError extends PortalStateError {
+    constructor();
+}
 export declare class PortalBusyError extends PortalStateError {
     constructor();
 }
@@ -66,7 +97,7 @@ interface PortalRuntime {
     readonly knock: (cell: ValidatedCell, key: Uint8Array, body: Uint8Array, options: NativeExchangeOptions) => Promise<NHPMessage>;
     readonly fetch: typeof globalThis.fetch;
     readonly nowNanos: () => bigint;
-    readonly randomFraction: () => number;
+    readonly nowEpochMs: () => number;
     readonly setTimer: (callback: () => void, delayMs: number) => NodeJS.Timeout;
     readonly clearTimer: (timer: NodeJS.Timeout) => void;
     readonly setDeadlineTimer: (callback: () => void, delayMs: number) => NodeJS.Timeout;
@@ -74,10 +105,10 @@ interface PortalRuntime {
 }
 export declare function createPortalOpener(options: CreatePortalOpenerOptions): PortalOpener;
 export declare function createPortalOpenerWithRuntime(options: CreatePortalOpenerOptions, runtime: PortalRuntime): PortalOpener;
-declare function constructVerifiedPortalOpener(options: CreatePortalOpenerOptions, link: VerifiedQv2Link, deployment: ValidatedDeployment, runtime: PortalRuntime): PortalOpener;
+declare function validatedCellForLink(link: VerifiedQv2Link, deployment: ValidatedDeployment): ValidatedCell;
 declare function validateSessionToken(value: string, decode?: (part: string) => Buffer): void;
 export declare const portalOpenerTesting: {
-    constructVerifiedPortalOpener: typeof constructVerifiedPortalOpener;
+    validatedCellForLink: typeof validatedCellForLink;
     validateSessionToken: typeof validateSessionToken;
 };
 export {};