@layervai/qurl 0.2.0 → 0.3.1

package/README.md

@@ -4,13 +4,34 @@
 [![CI](https://github.com/layervai/qurl-typescript/actions/workflows/ci.yml/badge.svg)](https://github.com/layervai/qurl-typescript/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/layervai/qurl-typescript)](LICENSE)
 
-TypeScript SDK for the [qURL™ API](https://docs.layerv.ai) — secure, time-limited access links for AI agents.
+**Use the LayerV [qURL™ Platform](https://docs.layerv.ai) from TypeScript: protect a
+private URL once, then mint short-lived portal links for it.**
 
 > **Quantum URL (qURL)** · The internet has a hidden layer. This is how you enter.
 
+Portal recipients do not need LayerV credentials, API keys, or SDK state. They
+open the qURL link. Credentials are only for software that protects URLs or
+creates portals.
+
 ## Why qURL?
 
-AI agents need to access protected resources — APIs, databases, internal tools — but giving them permanent credentials is a security risk. qURL creates time-limited, auditable access links that expire automatically. The SDK handles authentication, retries, pagination, and error handling so you can focus on your agent logic.
+Agents and services increasingly need to reach private MCP servers, APIs, and
+internal tools. The issue is visibility: every standing public endpoint becomes
+inventory for scanners, fingerprinting, credential attacks, and AI-assisted
+probing before a legitimate user or agent ever arrives.
+
+Opening an inbound port, running a VPN, shipping a bastion, publishing a
+Cloudflare Tunnel or ngrok URL, or passing around a long-lived key all leave
+something durable to find, scan, or steal. qURL flips that model: it is an
+invisibility primitive for authenticated access, and the private resource is
+not public inventory. A portal is **cryptographic, just-in-time permission for
+one actor to reach one private resource** — not another externally visible
+endpoint in front of the same service:
+
+- **Time-limited** — portals expire after minutes, hours, or days
+- **IP-scoped** — access is granted only to the requesting IP via NHP
+- **Auditable** — every access is logged with who, when, and from where
+- **Revocable** — kill access instantly if something goes wrong
 
 ## Installation
 
@@ -18,16 +39,99 @@ AI agents need to access protected resources — APIs, databases, internal tools
 npm install @layervai/qurl
 ```
 
-Requires Node.js 18+. Both `import { QURLClient } from '@layervai/qurl'` (ESM) and `const { QURLClient } = require('@layervai/qurl')` (CJS) work.
+Requires Node.js 20+ and has **no runtime dependencies**. Both `import { QURLClient } from '@layervai/qurl'` (ESM) and `const { QURLClient } = require('@layervai/qurl')` (CJS) work.
 
-## Quick Start
+## Quickstart
 
 ```typescript
 import { QURLClient } from '@layervai/qurl';
 
-const client = new QURLClient({ apiKey: 'lv_live_xxx' });
+const client = new QURLClient({ apiKey: 'YOUR_API_KEY' });
+
+const resource = await client.protectUrl('https://internal.example.com/dashboard');
+const portal = await resource.createPortal({ validFor: '5m' });
+
+console.log(portal.link); // Share this link — recipients need no credentials
+```
+
+That is the core flow:
+
+| Step | Call | What you provide |
+| --- | --- | --- |
+| Protect a private URL | `client.protectUrl` | The target URL you already know |
+| Mint a short-lived access link | `resource.createPortal` | The returned resource handle |
+
+`protectUrl` is idempotent for the same account and target URL: protecting the
+same URL again returns the existing resource. `validFor` accepts a duration
+string (`'5m'`, `'24h'`) or a number of milliseconds (whole seconds, at least
+one minute); prefer short portal lifetimes.
+
+If qURL Connector already protects the service, use the connector id instead
+of calling `protectUrl`:
+
+```typescript
+const resource = await client.connectorResource('prod-dashboard');
+const portal = await resource.createPortal({ validFor: '5m' });
+```
+
+If you persist the resource id, future calls do not need to recreate the
+handle (no API call is made until you mint):
+
+```typescript
+const resource = client.resourceById('r_demo1234567');
+const portal = await resource.createPortal({ validFor: '1h' });
+```
+
+For one-off scripts, `client.createPortalForUrl` combines the two API calls
+and returns both the portal and a reusable resource handle. The handle carries
+the resource id and target URL; use `protectUrl` when you need the full
+server-populated resource metadata:
 
-// Create a protected link
+```typescript
+const { portal, resource } = await client.createPortalForUrl(
+  'https://internal.example.com/dashboard',
+  { validFor: '5m' },
+);
+```
+
+Portal options mirror qurl-go:
+
+```typescript
+const portal = await resource.createPortal({
+  validFor: 5 * 60 * 1000, // milliseconds work too
+  label: 'Alice from Acme',
+  oneTimeUse: true,
+  maxSessions: 1,
+});
+```
+
+## Opening Portals
+
+Most recipients open qURL links directly and do not use this SDK at all. If
+you are building a service or agent that opens received qURL links
+programmatically, `enterPortal` accepts a full link or a bare access token,
+grants network access for the caller's IP, and returns the reachable resource:
+
+```typescript
+const handle = await client.enterPortal(link);
+console.log(handle.resourceUrl); // The reachable resource location
+console.log(handle.openSeconds); // How long access stays open
+```
+
+Unlike qurl-go's offline `EnterPortal`, this SDK opens links through the
+LayerV API: the client needs an API key with the `qurl:resolve` scope.
+`enterPortal` fails closed — if access is granted but no resource URL comes
+back, it throws instead of returning an empty handle.
+
+## REST-Shaped API (Compatibility)
+
+The original REST-shaped methods remain fully supported and share the same
+client. Use them for the qURL/resource/token management surface that has no
+portal-verb equivalent (listing, updating, revoking, quotas, webhooks, ...) or
+if you already build on them:
+
+```typescript
+// Create a protected link (portal equivalent: createPortalForUrl)
 const result = await client.create({
   target_url: 'https://api.example.com/data',
   expires_in: '24h',
@@ -35,8 +139,8 @@ const result = await client.create({
 });
 console.log(result.qurl_link);
 
-// Resolve a token (grants network access for your IP)
-const access = await client.resolve('at_...');
+// Resolve a token headlessly (portal equivalent: enterPortal)
+const access = await client.resolve('at_k8xqp9h2sj9lx7r4a');
 console.log(`Access granted to ${access.target_url} for ${access.access_grant?.expires_in}s`);
 ```
 
@@ -54,7 +158,18 @@ console.log(`Access granted to ${access.target_url} for ${access.access_grant?.e
 | `userAgent` | No | `qurl-typescript/<version>` |
 | `debug` | No | `false` |
 
-### Methods
+### Portal methods
+
+| Method | Description |
+|--------|-------------|
+| `protectUrl(targetUrl, opts?)` | Protect a private URL → portal-minting `ProtectedResource` handle |
+| `resource.createPortal(opts?)` / `createPortal(resourceOrId, opts?)` | Mint a short-lived portal link (`Portal`) |
+| `createPortalForUrl(targetUrl, opts?)` | Protect + mint in one API call → `{ portal, resource }` |
+| `connectorResource(connectorId)` | Handle for a service qURL Connector already protects |
+| `resourceById(id)` | Handle from a stored resource id (no API call) |
+| `enterPortal(linkOrToken)` | Open a qURL link programmatically → `ResourceHandle` |
+
+### REST-shaped methods
 
 | Method | Description |
 |--------|-------------|
@@ -122,7 +237,7 @@ Non-400 errors (401, 403, 429, 5xx, and unexpected 400 body shapes) still throw
 
 ## Error Handling
 
-All API errors throw typed error subclasses, so you can catch specific failure modes:
+Match errors by type, not message text — every failure throws a typed `QURLError` subclass, and message wording is not part of the API contract:
 
 ```typescript
 import {
@@ -134,16 +249,16 @@ import {
 } from '@layervai/qurl';
 
 try {
-  await client.create({ target_url: '' });
+  await client.enterPortal('https://qurl.link/#at_k8xqp9h2sj9lx7r4a');
 } catch (err) {
-  if (err instanceof ValidationError) {
-    console.error('Invalid input:', err.invalidFields);
-  } else if (err instanceof RateLimitError) {
-    console.error(`Rate limited — retry after ${err.retryAfter}s`);
-  } else if (err instanceof AuthenticationError) {
+  if (err instanceof AuthenticationError) {
     console.error('Bad API key');
   } else if (err instanceof NotFoundError) {
-    console.error('Resource not found');
+    console.error('Portal doesn\'t exist or already expired');
+  } else if (err instanceof RateLimitError) {
+    console.error(`Rate limited — retry after ${err.retryAfter}s`);
+  } else if (err instanceof ValidationError) {
+    console.error('Invalid input:', err.detail, err.invalidFields);
   } else if (err instanceof QURLError) {
     console.error(`API error [${err.code}]: ${err.detail}`);
   }
@@ -161,6 +276,13 @@ try {
 | `NetworkError` | — | Connection failure |
 | `TimeoutError` | — | Request exceeded timeout |
 
+Client-detected failures use `status: 0` with a discriminating `code`:
+`"client_validation"` for bad input caught before a request, and — on the
+portal surface — `"resource_not_found"` / `"ambiguous_resource"` when
+`connectorResource` cannot resolve a connector id to exactly one resource,
+and `"unexpected_response"` when a response is missing required fields (e.g.
+`enterPortal` failing closed on a grant with no resource URL).
+
 ## Pagination
 
 ```typescript
@@ -179,11 +301,11 @@ Enable debug output to see all HTTP requests and retries:
 
 ```typescript
 // Log to console
-const client = new QURLClient({ apiKey: 'lv_live_xxx', debug: true });
+const client = new QURLClient({ apiKey: 'YOUR_API_KEY', debug: true });
 
 // Custom logger
-const client = new QURLClient({
-  apiKey: 'lv_live_xxx',
+const clientWithLogger = new QURLClient({
+  apiKey: 'YOUR_API_KEY',
   debug: (message, data) => myLogger.debug(message, data),
 });
 ```
@@ -210,8 +332,23 @@ await client.create(
 );
 ```
 
+The portal verbs take the same per-call options as their final argument, e.g.
+`resource.createPortal({ validFor: '5m' }, { idempotencyKey: 'mint-alice-1' })`.
+
 SDK-generated keys require `globalThis.crypto.getRandomValues`, which is available in supported Node 20+ runtimes and modern edge/browser runtimes. In constrained runtimes without Web Crypto, pass a caller-provided key with `idempotencyKey`; otherwise POST/PATCH calls throw `RuntimeError` before sending a request.
 
+## Security Notes
+
+- Treat API keys and qURL links like credentials. Do not log them.
+- Prefer short portal lifetimes such as `validFor: '5m'`.
+- Do not ask portal recipients to handle credentials. Recipients only need
+  the link.
+- `protectUrl` and `createPortalForUrl` reject malformed target URLs and URLs
+  with embedded credentials (`https://user:pass@...`) before any request,
+  matching qurl-go.
+- The programmatic opener fails closed: `enterPortal` throws when access is
+  granted without a resource URL, and its error messages never echo the link.
+
 ## Versioning & breaking changes
 
 This SDK is pre-1.0; breaking changes between minor versions are possible until the API surface stabilizes. Significant changes are called out in [`CHANGELOG.md`](CHANGELOG.md) and in the corresponding GitHub release notes.

package/dist/cjs/client.d.ts

@@ -1,4 +1,4 @@
-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, AgentBootstrapInput, AgentBootstrapOutput, 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";
 /** qURL API client. */
 export declare class QURLClient {
     private readonly baseUrl;
@@ -49,7 +49,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 +283,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 +296,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.
      *
@@ -201,7 +318,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 +331,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>;
@@ -370,3 +496,37 @@ export declare class QURLClient {
     private retryDelay;
     private classifyFetchError;
 }
+/**
+ * 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>;
+}