withruntime 0.11.2 → 0.14.0

package/dist/products/balancers.d.ts

@@ -0,0 +1,87 @@
+import type { Transport } from "../transport.js";
+import { type ResourceRecord } from "./resources.js";
+/** Private until launch: load balancers and the inbound firewall
+ * (packages/cloud/src/api/products/balancers.ts). A change answers
+ * `applying`; it is `active` once every router serves it, and `waitingOn`
+ * names any router that does not yet. */
+export type AddressState = "applying" | "active" | "failed" | "deleting" | "deleted";
+type Common = ResourceRecord & {
+    name: string | null;
+    labels: Record<string, string>;
+    state: AddressState;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+    /** Routers that do not yet serve the newest change. */
+    waitingOn: string[];
+};
+/** A sandbox with the port it serves on, or an App or Function by id. */
+export type BalancerTarget = {
+    id: string;
+    port?: number;
+};
+export type Balancer = Common & {
+    hostname: string;
+    targets: BalancerTarget[];
+};
+export type CreateBalancer = {
+    name?: string;
+    labels?: Record<string, string>;
+    /** Up to 1000, all the organization's own. */
+    targets?: BalancerTarget[];
+};
+export type UpdateBalancer = {
+    name?: string | null;
+    labels?: Record<string, string>;
+    /** Replaces the whole list. */
+    targets?: BalancerTarget[];
+};
+export type FirewallRule = Common & {
+    address: string;
+    effect: "allow" | "deny" | "limit";
+    source?: string;
+    ports?: string;
+    requests?: number;
+    seconds?: number;
+    burst?: number;
+    priority: number;
+};
+export type CreateFirewallRule = {
+    name?: string;
+    labels?: Record<string, string>;
+    /** The load balancer it guards. */
+    address: string;
+    priority?: number;
+} & ({
+    effect: "allow" | "deny";
+    source?: string;
+    ports?: string;
+} | {
+    effect: "limit";
+    requests: number;
+    seconds: number;
+    burst?: number;
+});
+export type UpdateFirewallRule = {
+    name?: string | null;
+    labels?: Record<string, string>;
+};
+export declare function balancers(t: Transport): {
+    base: string;
+    create: (input: CreateBalancer, options?: import("../transport.js").RequestOptions) => Promise<Balancer>;
+    get: (id: string, options?: import("./resources.js").ResourceGetOptions<"active" | "deleted" | "failed" | "deleting" | "applying">) => Promise<Balancer>;
+    list: (query?: import("./resources.js").ResourceListQuery<"active" | "deleted" | "failed" | "deleting" | "applying">, options?: import("../transport.js").RequestOptions) => Promise<import("../page.js").Page<Balancer>>;
+    update: (id: string, input: UpdateBalancer, options?: import("../transport.js").RequestOptions) => Promise<Balancer>;
+    wait: (id: string, target: "active" | "deleted" | "failed" | "deleting" | "applying", options?: import("./resources.js").ResourceWaitOptions) => Promise<Balancer>;
+    delete: (id: string, options?: import("./resources.js").ResourceDeleteOptions) => Promise<Balancer>;
+};
+export declare function firewall(t: Transport): {
+    base: string;
+    create: (input: CreateFirewallRule, options?: import("../transport.js").RequestOptions) => Promise<FirewallRule>;
+    get: (id: string, options?: import("./resources.js").ResourceGetOptions<"active" | "deleted" | "failed" | "deleting" | "applying">) => Promise<FirewallRule>;
+    list: (query?: import("./resources.js").ResourceListQuery<"active" | "deleted" | "failed" | "deleting" | "applying">, options?: import("../transport.js").RequestOptions) => Promise<import("../page.js").Page<FirewallRule>>;
+    update: (id: string, input: UpdateFirewallRule, options?: import("../transport.js").RequestOptions) => Promise<FirewallRule>;
+    wait: (id: string, target: "active" | "deleted" | "failed" | "deleting" | "applying", options?: import("./resources.js").ResourceWaitOptions) => Promise<FirewallRule>;
+    delete: (id: string, options?: import("./resources.js").ResourceDeleteOptions) => Promise<FirewallRule>;
+};
+export {};

package/dist/products/balancers.js

@@ -0,0 +1,8 @@
+import { resource } from "./resources.js";
+const SETTLED = ["failed", "deleted"];
+export function balancers(t) {
+    return resource(t, "balancers", SETTLED);
+}
+export function firewall(t) {
+    return resource(t, "firewall/rules", SETTLED);
+}

package/dist/products/billing.d.ts

@@ -24,6 +24,39 @@ export type Topup = {
         }[];
     }[];
 };
+/** Auto top-up: when credit falls below `below`, the saved card is charged
+ *  `amount` plus tax, within `monthlyLimit` a calendar month (UTC). Each
+ *  automatic top-up adds 5% more as credit, and while it is on the account
+ *  may run 200 sandboxes at once. Dollars are numbers in whole cents. */
+export type AutoTopUp = {
+    /** Charging now. */
+    enabled: boolean;
+    /** Asked to turn on; turns on once a person saves a card at `saveCardAt`. */
+    waitingForCard: boolean;
+    below: number | null;
+    amount: number | null;
+    monthlyLimit: number | null;
+    /** Dollars added this month, a charge in flight included. */
+    thisMonth: number;
+    card: boolean;
+    /** Why it turned itself off; null while on. */
+    offReason: "declined" | "authentication_required" | "card_removed" | "no_address" | "blocked" | "failed" | null;
+    offAt: string | null;
+    /** Where a person saves the card, while none is saved. */
+    saveCardAt: string | null;
+};
+/** A figure left out keeps the one saved, or takes its default. */
+export type AutoTopUpInput = {
+    enabled: boolean;
+    /** Charge when credit falls below this: $10 at least, and the default. */
+    below?: number;
+    /** Each time, before tax: $20 (the default) to $10,000, and at most $500
+     *  in an account's first week. */
+    amount?: number;
+    /** The most a calendar month (UTC): $100 at least and at least `amount`;
+     *  $500 by default. */
+    monthlyLimit?: number;
+};
 export declare function billing(t: Transport): {
     /** Open a stablecoin top-up of `usd` dollars ($10 to $10,000). Pass the
      *  same `idempotencyKey` when retrying to get the same top-up back. */
@@ -32,4 +65,12 @@ export declare function billing(t: Transport): {
     }, options?: RequestOptions) => Promise<Topup>;
     /** Read a top-up: whether its payment has arrived. */
     topupStatus: (purchaseId: string, options?: RequestOptions) => Promise<Topup>;
+    /** Auto top-up's settings. A person saves its card on the website. */
+    autoTopUp: {
+        get: (options?: RequestOptions) => Promise<AutoTopUp>;
+        /** Set the three figures, and turn it on (once a card is saved) or keep it off. */
+        set: (input: AutoTopUpInput, options?: RequestOptions) => Promise<AutoTopUp>;
+        /** Turn it off. The figures and the card are kept; running sandboxes are never stopped. */
+        off: (options?: RequestOptions) => Promise<AutoTopUp>;
+    };
 };

package/dist/products/billing.js

@@ -9,5 +9,18 @@ export function billing(t) {
             path: `/v1/billing/topups/${encodeURIComponent(purchaseId)}`,
             ...options,
         }),
+        /** Auto top-up's settings. A person saves its card on the website. */
+        autoTopUp: {
+            get: (options) => t.json({ method: "GET", path: "/v1/billing/auto-top-up", ...options }),
+            /** Set the three figures, and turn it on (once a card is saved) or keep it off. */
+            set: (input, options) => t.json({
+                method: "PUT",
+                path: "/v1/billing/auto-top-up",
+                body: input,
+                ...options,
+            }),
+            /** Turn it off. The figures and the card are kept; running sandboxes are never stopped. */
+            off: (options) => t.json({ method: "DELETE", path: "/v1/billing/auto-top-up", ...options }),
+        },
     };
 }

package/dist/products/browser.d.ts

@@ -18,6 +18,11 @@ export type SandboxBrowser = {
     expiresAt: string | null;
     /** headless: false only: the desktop's live view. */
     streamUrl?: string;
+    /** start() only: the sandbox's memory, which is the browser's. */
+    memoryMiB?: number;
+    /** start() only, under 2 GiB: heavy apps such as Google Sheets, YouTube
+     * and StackBlitz need a 2 GiB sandbox; 1 GiB suits light pages. */
+    hint?: string;
 };
 export type BrowserStartOptions = {
     /** true (the default): no window. false: on the sandbox's desktop, with a live view. */
@@ -52,6 +57,11 @@ export declare function sandboxBrowser(t: Transport, sandbox: Sandbox): {
         expiresAt: string | null;
         /** headless: false only: the desktop's live view. */
         streamUrl?: string;
+        /** start() only: the sandbox's memory, which is the browser's. */
+        memoryMiB?: number;
+        /** start() only, under 2 GiB: heavy apps such as Google Sheets, YouTube
+         * and StackBlitz need a 2 GiB sandbox; 1 GiB suits light pages. */
+        hint?: string;
     }>;
     /** Whether it runs, and a fresh cdpUrl when it does. */
     get: (options?: RequestOptions) => Promise<SandboxBrowser>;

package/dist/products/browsers.d.ts

@@ -0,0 +1,71 @@
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type CreateBrowser = {
+    /** 1024–16384 MiB; the server defaults to 2048. */
+    memoryMiB?: number;
+    /** The server defaults to 1 vCPU. */
+    vcpu?: number;
+    /** Defaults to true; false requests a visible browser. */
+    headless?: boolean;
+    width?: number;
+    height?: number;
+    timeoutSeconds?: number;
+    idlePauseSeconds?: number;
+    name?: string;
+    labels?: Record<string, string>;
+};
+export type UpdateBrowser = {
+    name?: string | null;
+    labels?: Record<string, string>;
+};
+export type ListBrowsers = {
+    limit?: number;
+    cursor?: string;
+};
+/** A browser resource and its current connection credentials. */
+export type BrowserInfo = {
+    id: string;
+    name: string | null;
+    labels: Record<string, string>;
+    state: string;
+    sandboxId: string;
+    memoryMiB: number;
+    vcpu: number;
+    headless: boolean;
+    version: string;
+    cdpUrl: string;
+    httpUrl: string;
+    headers: Record<string, string>;
+    expiresAt: string | null;
+    liveViewUrl?: string;
+    hint?: string;
+};
+export type BrowserConnectOptions = {
+    playwright: [endpointURL: string, options: {
+        headers: Record<string, string>;
+    }];
+    puppeteer: {
+        browserWSEndpoint: string;
+        headers: Record<string, string>;
+    };
+};
+export type Browser = BrowserInfo & {
+    /** End this browser; concurrent calls share one request, and failures can be retried. */
+    delete(options?: RequestOptions): Promise<void>;
+    /** Get Playwright's argument tuple and Puppeteer's options, including authentication headers. */
+    connectOptions(): BrowserConnectOptions;
+    /** End this browser on scope exit; an already missing browser counts as cleaned up. */
+    [Symbol.asyncDispose](): Promise<void>;
+};
+/** Browsers follow the shared resource interface: id, name, labels, state. */
+export declare function browsers(t: Transport): {
+    /** Create a browser ready to connect; omitted fields use the server's defaults. */
+    create(input?: CreateBrowser, options?: RequestOptions): Promise<Browser>;
+    /** Fetch a browser by id with fresh CDP connection credentials. */
+    get(id: string, options?: RequestOptions): Promise<Browser>;
+    list: (query?: ListBrowsers, options?: RequestOptions) => Promise<Page<Browser>>;
+    /** Change a browser's name or labels without changing its compute settings. */
+    update(id: string, input: UpdateBrowser, options?: RequestOptions): Promise<Browser>;
+    /** End a browser by id; pass RequestOptions to bound or deduplicate the request. */
+    delete: (id: string, options?: RequestOptions) => Promise<void>;
+};

package/dist/products/browsers.js

@@ -0,0 +1,102 @@
+/**
+ * Managed Chromium browsers with authenticated Chrome DevTools Protocol (CDP) connections.
+ *
+ * await using browser = await runtime.browsers.create();
+ * const playwrightBrowser = await chromium.connectOverCDP(...browser.connectOptions().playwright);
+ * const puppeteerBrowser = await puppeteer.connect(browser.connectOptions().puppeteer);
+ *
+ * Use `get(browser.id)` for fresh connection credentials after `expiresAt`.
+ */
+import { RuntimeError } from "../errors.js";
+import { Page } from "../page.js";
+/** Browsers follow the shared resource interface: id, name, labels, state. */
+export function browsers(t) {
+    const path = (id) => `/v1/browsers/${encodeURIComponent(id)}`;
+    /** End a browser by id; API errors retain their code and recovery hint. */
+    const remove = async (id, options) => {
+        await t.json({ method: "DELETE", path: path(id), ...options });
+    };
+    const wrap = (info) => {
+        let deleted = false;
+        let deleting;
+        const browser = {
+            ...info,
+            delete(options) {
+                if (deleted)
+                    return Promise.resolve();
+                if (!deleting) {
+                    deleting = remove(info.id, options)
+                        .then(() => {
+                        deleted = true;
+                    })
+                        .catch((error) => {
+                        if (error instanceof RuntimeError && error.status === 404)
+                            deleted = true;
+                        throw error;
+                    })
+                        .finally(() => {
+                        deleting = undefined;
+                    });
+                }
+                return deleting;
+            },
+            connectOptions() {
+                return {
+                    playwright: [browser.cdpUrl, { headers: { ...browser.headers } }],
+                    puppeteer: {
+                        browserWSEndpoint: browser.cdpUrl,
+                        headers: { ...browser.headers },
+                    },
+                };
+            },
+            async [Symbol.asyncDispose]() {
+                // Creation's signal/key belong to creation: an aborted task must still clean up.
+                try {
+                    await browser.delete();
+                }
+                catch (error) {
+                    if (!(error instanceof RuntimeError && error.status === 404))
+                        throw error;
+                }
+            },
+        };
+        return browser;
+    };
+    /** Fetch one page; `for await (const browser of await list())` follows every cursor. */
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/browsers",
+            query,
+            ...options,
+        });
+        return new Page(page.data.map(wrap), page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    return {
+        /** Create a browser ready to connect; omitted fields use the server's defaults. */
+        async create(input = {}, options) {
+            return wrap(await t.json({
+                method: "POST",
+                path: "/v1/browsers",
+                body: input,
+                ...options,
+            }));
+        },
+        /** Fetch a browser by id with fresh CDP connection credentials. */
+        async get(id, options) {
+            return wrap(await t.json({ method: "GET", path: path(id), ...options }));
+        },
+        list,
+        /** Change a browser's name or labels without changing its compute settings. */
+        async update(id, input, options) {
+            return wrap(await t.json({
+                method: "POST",
+                path: `${path(id)}:update`,
+                body: input,
+                ...options,
+            }));
+        },
+        /** End a browser by id; pass RequestOptions to bound or deduplicate the request. */
+        delete: remove,
+    };
+}

package/dist/products/builds.d.ts

@@ -0,0 +1,156 @@
+import { Page } from "../page.js";
+import { type RequestOptions, type Transport } from "../transport.js";
+export type BuildState = "queued" | "fetching" | "building" | "deploying" | "succeeded" | "failed" | "cancelled" | "superseded";
+type Resource = {
+    id: string;
+    name: string | null;
+    labels: Record<string, string>;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+};
+export type Build = Resource & {
+    repositoryId: string;
+    ref: string;
+    /** The branch whose move asked for it, when the caller said. */
+    branch: string | null;
+    commit: string | null;
+    state: BuildState;
+    reason: string | null;
+    /** Milliseconds per step once the runner is done (install, build, mirror,
+     * fork, snapshot, total, ...); null until then. */
+    timings: Record<string, number> | null;
+    /** The saved server an App deploys, once a build of a repository with a
+     * start command succeeded; null otherwise. */
+    outputSnapshotId: string | null;
+};
+export type CreateBuild = {
+    repositoryId: string;
+    ref: string;
+    /** The same branch and commit is one build; a newer build of the branch
+     * supersedes older ones not yet ended. */
+    branch?: string;
+    name?: string;
+    labels?: Record<string, string>;
+};
+/** A connected repository's settings changed in place; its id and builds
+ * stay. A field left out stays as it is; a null name clears it. */
+export type ChangeRepository = Partial<Omit<ConnectRepository, "provider" | "name" | "labels">> & {
+    name?: string | null;
+    labels?: Record<string, string>;
+};
+export type ConnectRepository = {
+    provider: "github" | "git";
+    repository: string;
+    deploy: `app:${string}` | `function:${string}` | `container:${string}`;
+    productionBranch?: string;
+    previews?: boolean;
+    /** The folder the build runs in; the repository's root by default. */
+    rootDirectory?: string;
+    /** Leave out to choose by the lockfile (bun, pnpm, Yarn or npm). */
+    installCommand?: string | null;
+    buildCommand?: string | null;
+    /** Run after the build with PORT set; the build ends as this server,
+     * answering healthPath with 200 and saved with its memory. */
+    startCommand?: string | null;
+    port?: number;
+    healthPath?: string | null;
+    /** Settings install and build are given. Never a secret: anyone who reads
+     * the repository sees them. */
+    buildEnv?: Record<string, string>;
+    name?: string;
+    labels?: Record<string, string>;
+};
+export type Repository = Resource & {
+    provider: "github" | "git";
+    repository: string;
+    deploy: ConnectRepository["deploy"];
+    productionBranch: string;
+    previews: boolean;
+    rootDirectory: string;
+    installCommand: string | null;
+    buildCommand: string | null;
+    startCommand: string | null;
+    port: number;
+    healthPath: string | null;
+    buildEnv: Record<string, string>;
+    state: "connected" | "disconnected";
+};
+export type ListBuilds = {
+    limit?: number;
+    cursor?: string;
+    name?: string;
+    label?: string[];
+    state?: BuildState[];
+};
+export type ListRepositories = Omit<ListBuilds, "state"> & {
+    state?: Repository["state"][];
+};
+export type BuildLine = {
+    cursor: string | null;
+    at: number;
+    step: string | null;
+    text: string;
+    stream: "stdout" | "stderr";
+};
+export type FailingStep = {
+    name: string;
+    exitCode: number | null;
+    lastLines: string[];
+};
+export type BuildLog = {
+    lines: BuildLine[];
+    cursor: string | null;
+    state: BuildState;
+    reason: string | null;
+    failingStep: FailingStep | null;
+    hasMore: boolean;
+    nextCursor: string | null;
+};
+export type BuildLogEvent = ({
+    type: "line";
+} & BuildLine & {
+    cursor: string;
+}) | {
+    type: "gap";
+    cursor: string | null;
+    earliestCursor: string;
+} | {
+    type: "terminal";
+    cursor: string | null;
+    state: "succeeded" | "failed" | "cancelled" | "superseded";
+    reason: string;
+    failingStep: FailingStep | null;
+};
+/** cursor resumes a follow; pageCursor pages older search results. */
+export type LogOptions = {
+    follow?: boolean;
+    cursor?: string;
+    pageCursor?: string;
+};
+export declare function builds(t: Transport): {
+    create: (input: CreateBuild, options?: RequestOptions) => Promise<Build>;
+    get: (id: string, options?: RequestOptions) => Promise<Build>;
+    list: (query?: ListBuilds, options?: RequestOptions) => Promise<Page<Build>>;
+    logs: {
+        (id: string, query: LogOptions & {
+            follow: true;
+        }, options?: RequestOptions): AsyncGenerator<BuildLogEvent>;
+        (id: string, query?: LogOptions & {
+            follow?: false;
+        }, options?: RequestOptions): Promise<BuildLog>;
+        (id: string, query: LogOptions, options?: RequestOptions): Promise<BuildLog> | AsyncGenerator<BuildLogEvent>;
+    };
+    cancel: (id: string, options?: RequestOptions) => Promise<Build>;
+    repositories: {
+        connect: (input: ConnectRepository, options?: RequestOptions) => Promise<Repository>;
+        list: (query?: ListRepositories, options?: RequestOptions) => Promise<Page<Repository>>;
+        update: (id: string, change: ChangeRepository, options?: RequestOptions) => Promise<Repository>;
+        disconnect: (id: string, options?: RequestOptions) => Promise<Repository>;
+    };
+};
+export {};