sprntrl 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Supernatural
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# Supernatural Node SDK
+
+Official Node.js / TypeScript client for the [Supernatural](https://supernatural.sh) stealth browser-as-a-service API.
+
+## Installation
+
+```bash
+npm install sprntrl
+# Optional — pick whichever browser automation library you use:
+npm install playwright
+npm install puppeteer
+```
+
+## Quick start
+
+```ts
+import { Sprntrl } from "sprntrl";
+import type { Browser } from "playwright";
+
+const client = new Sprntrl(); // reads SPRNTRL_API_KEY from env
+
+const session = await client.sessions.create({ os: "macos", location: "us-east" });
+
+// browserSession waits for the session, connects Playwright, and hands you
+// a disposable handle. autoWhitelist registers your IP (CDP is IP-gated).
+const handle = await client.sessions.browserSession(session.id, { autoWhitelist: true });
+try {
+  const browser = handle.browser as Browser;
+  const page = await browser.contexts()[0].newPage();
+  await page.goto("https://bot.sannysoft.com");
+  await page.screenshot({ path: "out.png" });
+} finally {
+  await handle.close();
+  await client.sessions.stop(session.id);
+}
+```
+
+### With `await using` (Node 24+ / TS 5.2+)
+
+```ts
+{
+  await using handle = await client.sessions.browserSession(session.id, { autoWhitelist: true });
+  const page = await handle.browser.contexts()[0].newPage();
+  await page.goto("https://example.com");
+} // browser auto-closes here
+```
+
+### Puppeteer
+
+```ts
+const handle = await client.sessions.browserSession(session.id, {
+  framework: "puppeteer",
+  autoWhitelist: true,
+});
+```
+
+### Lower-level `connect()` and `cdpUrl()`
+
+If you want to manage the browser lifecycle yourself:
+
+```ts
+const browser = await client.sessions.connect(session.id, { autoWhitelist: true });
+// ...
+await browser.close();
+```
+
+Or get the raw CDP WebSocket URL for any CDP client (chrome-remote-interface, raw ws, etc.):
+
+```ts
+const url = client.sessions.cdpUrl(session.id);
+// wss://api.supernatural.sh/api/v1/sessions/<id>/cdp
+```
+
+## Configuration
+
+| Env var             | Default                    |
+|---------------------|----------------------------|
+| `SPRNTRL_API_KEY`   | —                          |
+| `SPRNTRL_BASE_URL`  | `https://api.supernatural.sh`   |
+
+Or per client:
+
+```ts
+const client = new Sprntrl({
+  apiKey: "sk_...",
+  baseURL: "https://api.supernatural.sh",
+  timeout: 30_000,
+  maxRetries: 2,
+});
+```
+
+## Resources
+
+- `client.sessions` — `create`, `list`, `listActive`, `listHistory`, `listResumable`, `listLocations`, `get`, `stop`, `resume`, `deletePersistent`, `waitUntilReady`, `connect`, `browserSession`, `cdpUrl`
+- `client.sessions.files` — `list`, `download`, `upload`
+- `client.profiles` — `create`, `list`, `get`, `update`, `duplicate`, `delete`
+- `client.templates.list()`
+- `client.ipWhitelist` — `list`, `add`, `remove`
+- `client.usage` — `current`, `history`
+- `client.user` — `me`, `update`, `updateSettings`, `changePassword`
+- `client.apiKeys` — `list`, `create` (full key returned ONCE), `revoke`
+
+## Error handling
+
+```ts
+import { Sprntrl, APIError, RateLimitError, AuthenticationError } from "sprntrl";
+
+try {
+  await client.sessions.create({ os: "macos", location: "us-east" });
+} catch (err) {
+  if (err instanceof RateLimitError) console.log("rate limited", err.status);
+  else if (err instanceof AuthenticationError) console.log("bad API key");
+  else if (err instanceof APIError) console.log("api error", err.status, err.body);
+  else throw err;
+}
+```
+
+Transient errors (5xx, 429, 408, connection errors) are retried automatically up to `maxRetries` with exponential backoff.
+
+## Gotchas
+
+- **CDP access is IP-whitelist gated.** The WebSocket at `/api/v1/sessions/:id/cdp` does not accept bearer auth — instead your public IP (as Cloudflare sees it) must be in your account's whitelist. Use `client.ipWhitelist.add("current")` or pass `{ autoWhitelist: true }` to `sessions.connect`.
+- **Sessions start async.** `sessions.create` returns immediately with `status: "creating"`. Call `sessions.waitUntilReady(id)` before connecting, or just use `sessions.connect()` which waits for you.
+- **API key is shown only once.** `apiKeys.create()` returns the full `key` field exactly once — store it immediately.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import { type RequestOptions } from "./core/request.js";
+import { Sessions } from "./resources/sessions.js";
+import { Profiles } from "./resources/profiles.js";
+import { Templates } from "./resources/templates.js";
+import { IPWhitelist } from "./resources/ip-whitelist.js";
+import { Usage } from "./resources/usage.js";
+import { User } from "./resources/user.js";
+import { APIKeys } from "./resources/api-keys.js";
+export interface ClientOptions {
+    apiKey?: string;
+    baseURL?: string;
+    timeout?: number;
+    maxRetries?: number;
+    defaultHeaders?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+export declare class Sprntrl {
+    readonly apiKey: string;
+    readonly baseURL: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    private readonly _config;
+    readonly sessions: Sessions;
+    readonly profiles: Profiles;
+    readonly templates: Templates;
+    readonly ipWhitelist: IPWhitelist;
+    readonly usage: Usage;
+    readonly user: User;
+    readonly apiKeys: APIKeys;
+    constructor(opts?: ClientOptions);
+    /** Low-level request escape hatch. Resources use this under the hood. */
+    request<T = unknown>(opts: RequestOptions): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,57 @@
+import { SprntrlError } from "./core/error.js";
+import { request as coreRequest } from "./core/request.js";
+import { Sessions } from "./resources/sessions.js";
+import { Profiles } from "./resources/profiles.js";
+import { Templates } from "./resources/templates.js";
+import { IPWhitelist } from "./resources/ip-whitelist.js";
+import { Usage } from "./resources/usage.js";
+import { User } from "./resources/user.js";
+import { APIKeys } from "./resources/api-keys.js";
+const DEFAULT_BASE_URL = "https://api.supernatural.sh";
+const DEFAULT_TIMEOUT = 60_000;
+const DEFAULT_MAX_RETRIES = 2;
+export class Sprntrl {
+    apiKey;
+    baseURL;
+    timeout;
+    maxRetries;
+    _config;
+    sessions;
+    profiles;
+    templates;
+    ipWhitelist;
+    usage;
+    user;
+    apiKeys;
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? process.env.SPRNTRL_API_KEY;
+        if (!apiKey) {
+            throw new SprntrlError("No API key provided. Pass apiKey or set SPRNTRL_API_KEY.");
+        }
+        const baseURL = (opts.baseURL ?? process.env.SPRNTRL_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.apiKey = apiKey;
+        this.baseURL = baseURL;
+        this.timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+        this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this._config = {
+            apiKey,
+            baseURL,
+            timeout: this.timeout,
+            maxRetries: this.maxRetries,
+            defaultHeaders: opts.defaultHeaders ?? {},
+            fetch: opts.fetch,
+        };
+        this.sessions = new Sessions(this);
+        this.profiles = new Profiles(this);
+        this.templates = new Templates(this);
+        this.ipWhitelist = new IPWhitelist(this);
+        this.usage = new Usage(this);
+        this.user = new User(this);
+        this.apiKeys = new APIKeys(this);
+    }
+    /** Low-level request escape hatch. Resources use this under the hood. */
+    request(opts) {
+        return coreRequest(this._config, opts);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,WAAW,EAA2C,MAAM,mBAAmB,CAAC;AACpG,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAWlD,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AACvD,MAAM,eAAe,GAAG,MAAM,CAAC;AAC/B,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B,MAAM,OAAO,OAAO;IACT,MAAM,CAAS;IACf,OAAO,CAAS;IAChB,OAAO,CAAS;IAChB,UAAU,CAAS;IAEX,OAAO,CAAgB;IAE/B,QAAQ,CAAW;IACnB,QAAQ,CAAW;IACnB,SAAS,CAAY;IACrB,WAAW,CAAc;IACzB,KAAK,CAAQ;IACb,IAAI,CAAO;IACX,OAAO,CAAU;IAE1B,YAAY,OAAsB,EAAE;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QAC1D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,YAAY,CACpB,0DAA0D,CAC3D,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,gBAAgB,CAAC,CAAC,OAAO,CACxF,MAAM,EACN,EAAE,CACH,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,eAAe,CAAC;QAC/C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAEzD,IAAI,CAAC,OAAO,GAAG;YACb,MAAM;YACN,OAAO;YACP,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,EAAE;YACzC,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;QAEF,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,yEAAyE;IACzE,OAAO,CAAc,IAAoB;QACvC,OAAO,WAAW,CAAI,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;CACF"}

package/dist/core/error.d.ts

@@ -0,0 +1,46 @@
+export declare class SprntrlError extends Error {
+    constructor(message: string);
+}
+export declare class APIError extends SprntrlError {
+    readonly status?: number;
+    readonly body?: unknown;
+    readonly headers?: Headers;
+    constructor(message: string, opts?: {
+        status?: number;
+        body?: unknown;
+        headers?: Headers;
+    });
+}
+export declare class BadRequestError extends APIError {
+    name: string;
+}
+export declare class AuthenticationError extends APIError {
+    name: string;
+}
+export declare class PermissionDeniedError extends APIError {
+    name: string;
+}
+export declare class NotFoundError extends APIError {
+    name: string;
+}
+export declare class ConflictError extends APIError {
+    name: string;
+}
+export declare class UnprocessableEntityError extends APIError {
+    name: string;
+}
+export declare class RateLimitError extends APIError {
+    name: string;
+}
+export declare class InternalServerError extends APIError {
+    name: string;
+}
+export declare class APIConnectionError extends APIError {
+    constructor(message?: string, opts?: {
+        cause?: unknown;
+    });
+}
+export declare class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message?: string);
+}
+export declare function errorForStatus(status: number, message: string, body?: unknown, headers?: Headers): APIError;

package/dist/core/error.js

@@ -0,0 +1,72 @@
+export class SprntrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SprntrlError";
+    }
+}
+export class APIError extends SprntrlError {
+    status;
+    body;
+    headers;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "APIError";
+        this.status = opts.status;
+        this.body = opts.body;
+        this.headers = opts.headers;
+    }
+}
+export class BadRequestError extends APIError {
+    name = "BadRequestError";
+}
+export class AuthenticationError extends APIError {
+    name = "AuthenticationError";
+}
+export class PermissionDeniedError extends APIError {
+    name = "PermissionDeniedError";
+}
+export class NotFoundError extends APIError {
+    name = "NotFoundError";
+}
+export class ConflictError extends APIError {
+    name = "ConflictError";
+}
+export class UnprocessableEntityError extends APIError {
+    name = "UnprocessableEntityError";
+}
+export class RateLimitError extends APIError {
+    name = "RateLimitError";
+}
+export class InternalServerError extends APIError {
+    name = "InternalServerError";
+}
+export class APIConnectionError extends APIError {
+    constructor(message = "Connection error", opts = {}) {
+        super(message);
+        this.name = "APIConnectionError";
+        if (opts.cause !== undefined)
+            this.cause = opts.cause;
+    }
+}
+export class APIConnectionTimeoutError extends APIConnectionError {
+    constructor(message = "Request timed out") {
+        super(message);
+        this.name = "APIConnectionTimeoutError";
+    }
+}
+export function errorForStatus(status, message, body, headers) {
+    const opts = { status, body, headers };
+    switch (status) {
+        case 400: return new BadRequestError(message, opts);
+        case 401: return new AuthenticationError(message, opts);
+        case 403: return new PermissionDeniedError(message, opts);
+        case 404: return new NotFoundError(message, opts);
+        case 409: return new ConflictError(message, opts);
+        case 422: return new UnprocessableEntityError(message, opts);
+        case 429: return new RateLimitError(message, opts);
+    }
+    if (status >= 500)
+        return new InternalServerError(message, opts);
+    return new APIError(message, opts);
+}
+//# sourceMappingURL=error.js.map

package/dist/core/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/core/error.ts"],"names":[],"mappings":"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"}

package/dist/core/request.d.ts

@@ -0,0 +1,24 @@
+export interface RequestConfig {
+    apiKey: string;
+    baseURL: string;
+    timeout: number;
+    maxRetries: number;
+    defaultHeaders: Record<string, string>;
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** If body is FormData/Blob/ArrayBuffer, don't set content-type/JSON-encode. */
+    rawBody?: boolean;
+    /** If true, return the raw Response (for binary downloads). */
+    stream?: boolean;
+    signal?: AbortSignal;
+    /** Per-request override. */
+    timeout?: number;
+    maxRetries?: number;
+}
+export declare function request<T = unknown>(config: RequestConfig, opts: RequestOptions): Promise<T>;

package/dist/core/request.js

@@ -0,0 +1,107 @@
+import { APIConnectionError, APIConnectionTimeoutError, APIError, errorForStatus, } from "./error.js";
+const USER_AGENT = "sprntrl-node/0.1.0";
+function buildURL(baseURL, path, query) {
+    const url = path.startsWith("http") ? new URL(path) : new URL(path, baseURL);
+    if (query) {
+        for (const [k, v] of Object.entries(query)) {
+            if (v !== undefined && v !== null)
+                url.searchParams.set(k, String(v));
+        }
+    }
+    return url.toString();
+}
+function shouldRetry(status) {
+    if (status === null)
+        return true;
+    return status === 408 || status === 409 || status === 429 || status >= 500;
+}
+function backoff(attempt) {
+    const base = 500 * 2 ** attempt;
+    return base + Math.floor(Math.random() * 250);
+}
+async function parseError(response) {
+    let body;
+    try {
+        body = await response.clone().json();
+    }
+    catch {
+        body = await response.clone().text().catch(() => undefined);
+    }
+    let message;
+    if (body && typeof body === "object") {
+        const b = body;
+        message = b.error || b.message || b.detail;
+    }
+    return { message: message ?? `HTTP ${response.status}`, body };
+}
+export async function request(config, opts) {
+    const url = buildURL(config.baseURL, opts.path, opts.query);
+    const headers = {
+        Authorization: `ApiKey ${config.apiKey}`,
+        Accept: "application/json",
+        "User-Agent": USER_AGENT,
+        ...config.defaultHeaders,
+        ...(opts.headers ?? {}),
+    };
+    let init = { method: opts.method, headers };
+    if (opts.body !== undefined) {
+        if (opts.rawBody) {
+            init.body = opts.body;
+        }
+        else {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(opts.body);
+        }
+    }
+    const fetchFn = config.fetch ?? fetch;
+    const timeout = opts.timeout ?? config.timeout;
+    const maxRetries = opts.maxRetries ?? config.maxRetries;
+    let lastErr;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new Error("timeout")), timeout);
+        const signal = opts.signal
+            ? AbortSignal.any([opts.signal, controller.signal])
+            : controller.signal;
+        try {
+            const response = await fetchFn(url, { ...init, signal });
+            clearTimeout(timer);
+            if (response.ok) {
+                if (opts.stream)
+                    return response;
+                if (response.status === 204)
+                    return undefined;
+                const ctype = response.headers.get("content-type") ?? "";
+                if (ctype.includes("application/json"))
+                    return (await response.json());
+                return (await response.arrayBuffer());
+            }
+            if (shouldRetry(response.status) && attempt < maxRetries) {
+                await sleep(backoff(attempt));
+                continue;
+            }
+            const { message, body } = await parseError(response);
+            throw errorForStatus(response.status, message, body, response.headers);
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err instanceof APIError)
+                throw err;
+            // network/abort
+            const isTimeout = err?.name === "AbortError";
+            lastErr = isTimeout
+                ? new APIConnectionTimeoutError()
+                : new APIConnectionError(err instanceof Error ? err.message : "Connection error", { cause: err });
+            if (attempt < maxRetries) {
+                await sleep(backoff(attempt));
+                continue;
+            }
+            throw lastErr;
+        }
+    }
+    throw lastErr;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=request.js.map

package/dist/core/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/core/request.ts"],"names":[],"mappings":"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"}

package/dist/core/resource.d.ts

@@ -0,0 +1,5 @@
+import type { Sprntrl } from "../client.js";
+export declare class APIResource {
+    protected _client: Sprntrl;
+    constructor(client: Sprntrl);
+}

package/dist/core/resource.js

@@ -0,0 +1,7 @@
+export class APIResource {
+    _client;
+    constructor(client) {
+        this._client = client;
+    }
+}
+//# sourceMappingURL=resource.js.map

package/dist/core/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/core/resource.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,WAAW;IACZ,OAAO,CAAU;IAE3B,YAAY,MAAe;QACzB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { Sprntrl, type ClientOptions } from "./client.js";
+export { SprntrlError, APIError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, APIConnectionError, APIConnectionTimeoutError, } from "./core/error.js";
+export type { OS, ProxyProtocol, ProxyConfig, SessionStatus, Session, ProxySummary, PaginatedSessions, Profile, Template, IPWhitelistEntry, APIKey, APIKeyCreated, Usage, UsageMonth, User, AccountStatus, FileInfo, } from "./types.js";
+export type { SessionCreateParams, ConnectOptions, BrowserHandle } from "./resources/sessions.js";
+export type { UserSettings, ChangePasswordResult } from "./resources/user.js";
+export type { ProfileCreateParams } from "./resources/profiles.js";
+export type { FileContent } from "./resources/session-files.js";
+export { Sprntrl as default } from "./client.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Sprntrl } from "./client.js";
+export { SprntrlError, APIError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, APIConnectionError, APIConnectionTimeoutError, } from "./core/error.js";
+export { Sprntrl as default } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAsB,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,wBAAwB,EACxB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAyBzB,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/browser.d.ts

@@ -0,0 +1,7 @@
+import type { Sprntrl } from "../client.js";
+import type { Session } from "../types.js";
+export interface ConnectArgs {
+    framework?: "playwright" | "puppeteer";
+    autoWhitelist?: boolean;
+}
+export declare function connect(client: Sprntrl, session: Session, opts?: ConnectArgs): Promise<unknown>;

package/dist/lib/browser.js

@@ -0,0 +1,56 @@
+import { SprntrlError } from "../core/error.js";
+function cdpUrlFor(client, session) {
+    // Build the URL from the client's base URL. The API proxies the WebSocket
+    // through /api/v1/sessions/:id/cdp with an IP-whitelist check — this is what
+    // external callers must hit. The server also returns session.cdp_url but
+    // that's an internal host:port that isn't reachable from outside the API host.
+    const base = new URL(client.baseURL);
+    const scheme = base.protocol === "https:" ? "wss:" : "ws:";
+    return `${scheme}//${base.host}/api/v1/sessions/${session.id}/cdp`;
+}
+export async function connect(client, session, opts = {}) {
+    const framework = opts.framework ?? "playwright";
+    if (opts.autoWhitelist) {
+        try {
+            await client.request({
+                method: "POST",
+                path: "/api/v1/settings/ip-whitelist",
+                body: { ip: "current" },
+            });
+        }
+        catch {
+            // Already-whitelisted or race; the connect attempt will surface real errors.
+        }
+    }
+    const cdpUrl = cdpUrlFor(client, session);
+    // Use a variable-indirected import so TypeScript does not resolve the
+    // optional peer dependency's types at compile time.
+    const dynImport = (name) => import(name);
+    if (framework === "playwright") {
+        let mod;
+        try {
+            mod = (await dynImport("playwright"));
+        }
+        catch {
+            throw new SprntrlError("playwright is not installed. Run `npm install playwright`.");
+        }
+        return mod.chromium.connectOverCDP(cdpUrl);
+    }
+    if (framework === "puppeteer") {
+        let mod;
+        try {
+            mod = (await dynImport("puppeteer-core"));
+        }
+        catch {
+            try {
+                mod = (await dynImport("puppeteer"));
+            }
+            catch {
+                throw new SprntrlError("puppeteer is not installed. Run `npm install puppeteer` (or puppeteer-core).");
+            }
+        }
+        return mod.connect({ browserWSEndpoint: cdpUrl });
+    }
+    throw new SprntrlError(`Unsupported framework '${framework}'`);
+}
+//# sourceMappingURL=browser.js.map

package/dist/lib/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/lib/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAShD,SAAS,SAAS,CAAC,MAAe,EAAE,OAAgB;IAClD,0EAA0E;IAC1E,6EAA6E;IAC7E,yEAAyE;IACzE,+EAA+E;IAC/E,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IAC3D,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC,IAAI,oBAAoB,OAAO,CAAC,EAAE,MAAM,CAAC;AACrE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAAe,EACf,OAAgB,EAChB,OAAoB,EAAE;IAEtB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,YAAY,CAAC;IACjD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC;gBACnB,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,+BAA+B;gBACrC,IAAI,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE;aACxB,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,6EAA6E;QAC/E,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1C,sEAAsE;IACtE,oDAAoD;IACpD,MAAM,SAAS,GAAuC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7E,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;QAC/B,IAAI,GAAwE,CAAC;QAC7E,IAAI,CAAC;YACH,GAAG,GAAG,CAAC,MAAM,SAAS,CAAC,YAAY,CAAC,CAAe,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,YAAY,CACpB,4DAA4D,CAC7D,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;QAC9B,IAAI,GAA2E,CAAC;QAChF,IAAI,CAAC;YACH,GAAG,GAAG,CAAC,MAAM,SAAS,CAAC,gBAAgB,CAAC,CAAe,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC;gBACH,GAAG,GAAG,CAAC,MAAM,SAAS,CAAC,WAAW,CAAC,CAAe,CAAC;YACrD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,YAAY,CACpB,8EAA8E,CAC/E,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC,OAAO,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,IAAI,YAAY,CAAC,0BAA0B,SAAS,GAAG,CAAC,CAAC;AACjE,CAAC"}

package/dist/resources/api-keys.d.ts

@@ -0,0 +1,11 @@
+import { APIResource } from "../core/resource.js";
+import type { APIKey, APIKeyCreated } from "../types.js";
+export declare class APIKeys extends APIResource {
+    list(): Promise<APIKey[]>;
+    /**
+     * Create an API key. The full `key` field is returned ONLY on creation —
+     * store it immediately; the server cannot show it again.
+     */
+    create(name: string): Promise<APIKeyCreated>;
+    revoke(keyId: string): Promise<void>;
+}