@layervai/qurl 0.3.0 → 0.4.0

package/dist/cjs/client.d.ts

@@ -1,4 +1,12 @@
-import type { AccessCodeListOutput, AgentBootstrapInput, AgentBootstrapOutput, ApiKey, ApiKeyListOutput, BillingInvoiceListOutput, BatchCreateInput, BatchCreateOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationListOutput, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, Domain, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListInput, ListOutput, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListWebhookDeliveriesInput, ListWebhooksInput, MintInput, MintOutput, PortalSession, QURL, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceListInput, ResourceListOutput, RequestOptions, ResolveInput, ResolveOutput, SessionListOutput, SessionTerminateOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCurrentPeriod, UsageDaily, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventTypeInfo, WebhookListOutput, WebhookWithSecret } from "./types.js";
+import type { AccessCodeListOutput, ApiKey, ApiKeyListOutput, BillingInvoiceListOutput, BatchCreateInput, BatchCreateOutput, ClientOptions, ConnectorInstallation, ConnectorInstallationListOutput, CreateAccessCodeInput, CreateAccessCodeOutput, CreateApiKeyInput, CreateApiKeyOutput, CreateBillingCheckoutInput, CreateInput, CreateOutput, CreatePortalOptions, CreateQurlForResourceInput, CreateResourceInput, CreateWebhookInput, Customer, CheckoutSession, Domain, DomainListOutput, DomainVerifyResult, ExtendInput, Invoice, ListInput, ListOutput, ListApiKeysInput, ListBillingInvoicesInput, ListConnectorInstallationsInput, ListDomainsInput, ListWebhookDeliveriesInput, ListWebhooksInput, MintInput, MintOutput, Portal, PortalSession, ProtectUrlOptions, QURL, QurlSummary, Quota, RedeemAccessCodeInput, RedeemAccessCodeOutput, RegisterDomainInput, Resource, ResourceDetail, ResourceHandle, ResourceListInput, ResourceListOutput, RequestOptions, ResolveInput, ResolveOutput, SessionListOutput, SessionTerminateOutput, UpdateApiKeyInput, UpdateCustomerInput, UpdateInput, UpdateResourceInput, UpdateResourceQurlInput, UpdateWebhookInput, UsageCurrentPeriod, UsageDaily, Webhook, WebhookDelivery, WebhookDeliveryListOutput, WebhookEventTypeInfo, WebhookListOutput, WebhookWithSecret } from "./types.js";
+/**
+ * Shape of qurl-go's offline signed-fragment links: three or more
+ * dot-separated base64url parts (<version>.<claims>.<secret>.<sig>).
+ * Detected only to give those links a precise error in extractAccessToken.
+ *
+ * @internal Exported for in-package tests; not re-exported from index.ts.
+ */
+export declare const SIGNED_FRAGMENT_RE: RegExp;
 /** qURL API client. */
 export declare class QURLClient {
     private readonly baseUrl;
@@ -49,7 +57,119 @@ export declare class QURLClient {
      */
     private validateBatchCreateResponse;
     private paginateAll;
-    /** Create a new qURL. */
+    /**
+     * Protect a private URL — create or reuse its LayerV resource.
+     *
+     * The first step of the portal flow (qurl-go: `Client.ProtectURL`).
+     * Protect the URL once, then mint short-lived links for it with
+     * {@link ProtectedResource.createPortal}:
+     *
+     * ```ts
+     * const resource = await client.protectUrl("https://internal.example.com/dashboard");
+     * const portal = await resource.createPortal({ validFor: "5m" });
+     * share(portal.link);
+     * ```
+     *
+     * Protecting the same target URL again returns the existing resource.
+     * Malformed URLs and URLs with embedded credentials (userinfo) are
+     * rejected before any request, mirroring qurl-go. REST-shaped equivalent:
+     * {@link createResource}.
+     */
+    protectUrl(targetUrl: string, opts?: ProtectUrlOptions, requestOptions?: RequestOptions): Promise<ProtectedResource>;
+    /**
+     * Return a portal-minting handle for a stored resource id, without an API
+     * call.
+     *
+     * Use when you persisted a LayerV resource id and want to mint more
+     * portals for it (qurl-go: `Client.ResourceByID`):
+     *
+     * ```ts
+     * const resource = client.resourceById("r_demo1234567");
+     * const portal = await resource.createPortal({ validFor: "1h" });
+     * ```
+     *
+     * The handle carries no server metadata; use {@link getResource} when you
+     * need the full resource details.
+     */
+    resourceById(id: string): ProtectedResource;
+    /**
+     * 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.
+     */
+    connectorResource(connectorId: string): Promise<ProtectedResource>;
+    /**
+     * Mint a short-lived qURL link (a portal) for a protected resource.
+     *
+     * A portal is cryptographic, just-in-time permission for one actor to
+     * 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} /
+     * {@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.
+     */
+    createPortal(resource: ProtectedResource | string, opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
+    /**
+     * Protect `targetUrl` and mint a portal in one API call.
+     *
+     * Convenience for one-off scripts (qurl-go: `Client.CreatePortalForURL`).
+     * The returned resource handle is reusable for minting more portals but
+     * carries only the resource id and the caller-supplied target URL; use
+     * {@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}.
+     */
+    createPortalForUrl(targetUrl: string, opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<{
+        portal: Portal;
+        resource: ProtectedResource;
+    }>;
+    /**
+     * Open a qURL link programmatically and return the reachable resource.
+     *
+     * For services and agents that open received qURL links in code — human
+     * recipients just open the link. Accepts a full platform link
+     * (`https://qurl.link/#at_...`) or a bare access token. Triggers an NHP
+     * knock that grants network access for the caller's IP and returns a
+     * {@link ResourceHandle} with the reachable resource URL and access
+     * lifetime.
+     *
+     * Unlike qurl-go's `EnterPortal` (which verifies links locally and needs
+     * no LayerV credentials), this SDK opens links through the LayerV API:
+     * the client needs an API key with the `qurl:resolve` scope. REST-shaped
+     * equivalent: {@link resolve}.
+     *
+     * Throws {@link ValidationError} (`code: "client_validation"`) when no
+     * access token can be extracted from `qurlLink`, and
+     * (`code: "unexpected_response"`) when access is granted but the API
+     * reports no resource URL — it fails closed rather than returning an
+     * empty handle. Error messages never echo the link; qURL links are
+     * credentials.
+     */
+    enterPortal(qurlLink: string, requestOptions?: RequestOptions): Promise<ResourceHandle>;
+    /**
+     * Create a new qURL.
+     *
+     * Portal-flow equivalent: {@link createPortalForUrl} (same endpoint,
+     * returns a {@link Portal} plus a reusable resource handle).
+     */
     create(input: CreateInput, options?: RequestOptions): Promise<CreateOutput>;
     /**
      * Batch create multiple qURLs (1-`MAX_BATCH_ITEMS` items).
@@ -171,6 +291,8 @@ export declare class QURLClient {
     /**
      * Mint a new access link for a qURL.
      *
+     * Portal-flow equivalent: {@link createPortal}.
+     *
      * Accepts either a resource ID (`r_` prefix) or a qURL display ID (`q_`
      * prefix); the API resolves `q_` IDs to the parent resource automatically.
      *
@@ -182,6 +304,9 @@ export declare class QURLClient {
     /**
      * Resolve a qURL access token (headless).
      *
+     * Portal-flow equivalent: {@link enterPortal} (also accepts full qURL
+     * links and fails closed when no resource URL is returned).
+     *
      * Triggers an NHP knock to grant network access for the caller's IP.
      * Requires `qurl:resolve` scope on the API key.
      *
@@ -190,8 +315,6 @@ export declare class QURLClient {
     resolve(input: ResolveInput | string, options?: RequestOptions): Promise<ResolveOutput>;
     /** Get quota and usage information. */
     getQuota(): Promise<Quota>;
-    /** Bootstrap a LayerV qURL Connector agent. */
-    bootstrapAgent(input: AgentBootstrapInput, options?: RequestOptions): Promise<AgentBootstrapOutput>;
     /** List resources from the `/v1/resources` API. */
     listResources(input?: ResourceListInput): Promise<ResourceListOutput>;
     /**
@@ -201,7 +324,12 @@ export declare class QURLClient {
      * iteration begins.
      */
     listAllResources(input?: Omit<ResourceListInput, "cursor">): AsyncGenerator<Resource, void, undefined>;
-    /** Create a resource directly. */
+    /**
+     * Create a resource directly.
+     *
+     * Portal-flow equivalent for URL resources: {@link protectUrl} (returns
+     * a portal-minting handle).
+     */
     createResource(input: CreateResourceInput, options?: RequestOptions): Promise<Resource>;
     /** Get one resource plus its bounded qURL preview. */
     getResource(id: string): Promise<ResourceDetail>;
@@ -209,7 +337,11 @@ export declare class QURLClient {
     updateResource(id: string, input: UpdateResourceInput, options?: RequestOptions): Promise<Resource>;
     /** Revoke a resource and all of its qURLs. */
     deleteResource(id: string): Promise<void>;
-    /** Mint a qURL against an existing resource. */
+    /**
+     * Mint a qURL against an existing resource.
+     *
+     * Portal-flow equivalent: {@link createPortal} (same endpoint).
+     */
     createQurlForResource(id: string, input?: CreateQurlForResourceInput, options?: RequestOptions): Promise<CreateOutput>;
     /** Revoke a specific qURL token on a resource. */
     revokeResourceQurl(id: string, qurlId: string): Promise<void>;
@@ -223,13 +355,7 @@ export declare class QURLClient {
      * this page and emits a debug log rather than pretending it fetched all pages.
      */
     listResourceSessions(id: string): Promise<SessionListOutput>;
-    /**
-     * Terminate all active sessions for a resource.
-     *
-     * The returned count is best-effort under retries: if the first DELETE
-     * succeeds server-side but the response is lost, a retried request may
-     * return `0` because there are no sessions left to terminate.
-     */
+    /** Terminate all active sessions for a resource and return the server count. */
     terminateAllResourceSessions(id: string): Promise<SessionTerminateOutput>;
     /** Terminate a specific resource session. */
     terminateResourceSession(id: string, sessionId: string): Promise<void>;
@@ -342,6 +468,12 @@ export declare class QURLClient {
     /** Revoke an access code. */
     revokeAccessCode(id: string): Promise<void>;
     private request;
+    /**
+     * Require the service's exact 204 response with no response bytes exposed by
+     * Fetch. A standards-compliant Fetch implementation discards any forbidden
+     * wire body on 204, so the SDK cannot detect bytes that Fetch did not expose.
+     */
+    private requestNoContent;
     /**
      * Issue an HTTP request and parse the JSON response.
      *
@@ -369,4 +501,39 @@ export declare class QURLClient {
      */
     private retryDelay;
     private classifyFetchError;
+    private classifyResponseReadError;
+}
+/**
+ * A LayerV-protected resource, bound to the client that produced it.
+ *
+ * Obtained from {@link QURLClient.protectUrl},
+ * {@link QURLClient.connectorResource}, or {@link QURLClient.resourceById} —
+ * not constructed directly. Mint short-lived access links for the resource
+ * with {@link createPortal} (qurl-go: `qurl.Resource`).
+ */
+export declare class ProtectedResource {
+    #private;
+    /** The LayerV resource id (`r_` prefix). */
+    readonly id: string;
+    /** The private URL protected by this resource, when known. */
+    readonly targetUrl?: string;
+    /**
+     * Full server-populated {@link Resource} metadata when the handle came
+     * from an API response; `undefined` for {@link QURLClient.resourceById}
+     * handles and for the one-call {@link QURLClient.createPortalForUrl} path.
+     */
+    readonly details?: Resource;
+    constructor(client: QURLClient, id: string, targetUrl?: string, details?: Resource);
+    /**
+     * Whether `resource` was produced by `client`. A static because the
+     * binding lives in a private field that only this class can read; used
+     * by {@link QURLClient.createPortal} to refuse handles bound to a
+     * different client.
+     */
+    static isBoundTo(resource: ProtectedResource, client: QURLClient): boolean;
+    /**
+     * Mint a short-lived qURL link (a portal) for this resource. See
+     * {@link QURLClient.createPortal} for the option reference.
+     */
+    createPortal(opts?: CreatePortalOptions, requestOptions?: RequestOptions): Promise<Portal>;
 }