withruntime 0.11.2 → 0.14.0

package/dist/products/resources.js

@@ -0,0 +1,122 @@
+import { RuntimeError } from "../errors.js";
+import { Page } from "../page.js";
+import { pause } from "../wait.js";
+export const enc = encodeURIComponent;
+function invalid(field) {
+    return new RuntimeError({
+        code: "invalid_request",
+        status: 0,
+        message: `${field} must be a finite, nonnegative number.`,
+        hint: "Fix the option and call again; nothing was sent.",
+        details: { field },
+    });
+}
+/** One deadline covers the write, retries and every read. A timed-out delete
+ * can be retried after a process restart with this same key. */
+export async function following(options, work) {
+    const { pollMs = 250, timeoutMs = 300_000, signal, ...rest } = options;
+    if (!Number.isFinite(pollMs) || pollMs < 0)
+        throw invalid("pollMs");
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        throw invalid("timeoutMs");
+    const deadline = new AbortController();
+    const combined = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+    const timer = timeoutMs > 0 ? setTimeout(() => deadline.abort(), timeoutMs) : undefined;
+    const request = { ...rest, timeoutMs: 0, signal: combined };
+    const poll = () => pause(pollMs, combined);
+    try {
+        combined.throwIfAborted();
+        const result = await work(request, poll);
+        combined.throwIfAborted();
+        return result;
+    }
+    catch (cause) {
+        if (!combined.aborted) {
+            // A read failure still belongs to the write that started this wait.
+            // Keep its key so a caller can recover after losing the reply.
+            if (cause instanceof RuntimeError && rest.idempotencyKey && !cause.idempotencyKey)
+                throw new RuntimeError({
+                    message: cause.message,
+                    code: cause.code,
+                    status: cause.status,
+                    requestId: cause.requestId,
+                    hint: cause.hint,
+                    details: cause.details,
+                    retryAfterMs: cause.retryAfterMs,
+                    idempotencyKey: rest.idempotencyKey,
+                    cause,
+                });
+            throw cause;
+        }
+        throw new RuntimeError({
+            code: "timeout",
+            status: 0,
+            message: "Waiting was cancelled or reached its deadline; the resource may still change.",
+            hint: "Read the resource to resume waiting. Retry a write with the same idempotencyKey.",
+            ...(rest.idempotencyKey === undefined ? {} : { idempotencyKey: rest.idempotencyKey }),
+            cause,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** A resource product's client at `/v1/<path>`. A wait ends at its target
+ * or at any of `settled`, which answers with the resource's error. */
+export function resource(t, path, settled) {
+    const base = `/v1/${path}`;
+    const get = (id, options = {}) => {
+        const { waitFor, timeoutSeconds, ...request } = options;
+        return t.json({
+            method: "GET",
+            path: `${base}/${enc(id)}`,
+            query: { waitFor, timeoutSeconds },
+            ...request,
+        });
+    };
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: base,
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    const follow = async (id, target, request, pause, initial) => {
+        let record = initial ?? (await get(id, request));
+        for (;;) {
+            if (record.state === target)
+                return record;
+            if (settled.includes(record.state))
+                throw new RuntimeError({
+                    code: record.error?.code ?? "unexpected_state",
+                    status: 0,
+                    message: record.error?.message ?? `Expected ${target}, but ${id} reached ${record.state}.`,
+                    hint: "Read the resource and inspect its error before starting another change.",
+                    details: { id, state: record.state, target, resource: record },
+                    ...(request.idempotencyKey === undefined
+                        ? {}
+                        : { idempotencyKey: request.idempotencyKey }),
+                });
+            await pause();
+            record = await get(id, request);
+        }
+    };
+    return {
+        base,
+        /** Defaults belong to the API, so the SDK does not override them. */
+        create: (input, options) => t.json({ method: "POST", path: base, body: input, ...options }),
+        get,
+        list,
+        update: (id, input, options) => t.json({ method: "POST", path: `${base}/${enc(id)}:update`, body: input, ...options }),
+        wait: (id, target, options = {}) => following(options, (request, pause) => follow(id, target, request, pause)),
+        delete: (id, options = {}) => {
+            const { wait = false, pollMs, ...request } = options;
+            const remove = (rest) => t.json({ method: "DELETE", path: `${base}/${enc(id)}`, ...rest });
+            if (!wait)
+                return remove(request);
+            return following({ ...request, pollMs, idempotencyKey: request.idempotencyKey ?? crypto.randomUUID() }, async (rest, pause) => follow(id, "deleted", rest, pause, await remove(rest)));
+        },
+    };
+}

package/dist/products/secrets.d.ts

@@ -9,10 +9,23 @@ export type SecretRule = {
     methods?: string[];
     paths: string[];
 };
+/** Which sandboxes get a secret: those whose labels hold every pair of any one
+ * selector in `labels` (including sandboxes created or labelled later), and
+ * those named in `sandboxes`. Any other sandbox of the organization sees no
+ * placeholder, and its requests never carry the value. Absent on a secret:
+ * every sandbox of the organization. */
+export type SecretScope = {
+    /** 1 to 8 selectors of 1 to 8 key/value pairs: `[{ role: "hub" }]`. */
+    labels?: Array<Record<string, string>>;
+    /** 1 to 100 sandbox ids of the organization. */
+    sandboxes?: string[];
+};
 /** A secret your sandboxes use without seeing it. Every sandbox of your
  * organization has an environment variable of the secret's name holding
- * `placeholder`; the egress proxy puts the value into HTTPS requests to
- * `hosts` (in the URL and headers), or sets `header` on every such request.
+ * `placeholder`; the egress proxy sets `header` on every HTTPS request to
+ * `hosts`, or, without `header`, replaces the placeholder in a credential
+ * header (Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key,
+ * x-subscription-token, private-token). Never in the URL or another header.
  * The value is never returned. */
 export type Secret = {
     name: string;
@@ -20,6 +33,8 @@ export type Secret = {
     header?: string;
     format?: string;
     rules?: SecretRule[];
+    /** Absent: every sandbox of the organization. */
+    only?: SecretScope;
     placeholder: string;
     valueBytes: number;
     createdAt: string;
@@ -33,7 +48,9 @@ export type SetSecret = {
     /** Where the value may go: `api.openai.com`, `*.github.com`. 1 to 16.
      * Required unless `jobs` is true. */
     hosts?: string[];
-    /** Set this header on every request to the hosts, replacing the sandbox's own. */
+    /** Set this header on every request to the hosts, replacing the sandbox's
+     * own; the value then goes nowhere else. Needed when the API reads its key
+     * from a header that is not a credential header (see `Secret`). */
     header?: string;
     /** With `header`: its value, `{value}` where the secret goes. Default `{value}`. */
     format?: string;
@@ -41,6 +58,10 @@ export type SetSecret = {
      * Absent: every request to the hosts; replacing a secret without rules
      * clears them. */
     rules?: SecretRule[];
+    /** Only these sandboxes get it. Absent when replacing a secret: the scope it
+     * has stays, so a new value never widens who gets it. `{}`: every sandbox of
+     * the organization again. */
+    only?: SecretScope;
     /** Also keep a copy for scheduled jobs, which a job puts into its run's
      * environment (`jobs.create({ secrets: [...] })`). Unlike the sandboxes'
      * copy, the jobs copy is yours rather than the account's, versioned, and can
@@ -94,6 +115,11 @@ export declare function secrets(t: Transport): {
             enforced: boolean;
         }>>;
     };
+    /** Changes which sandboxes get a secret, without its value: `{}` is every
+     * sandbox of the organization again. */
+    scope: (name: string, only: SecretScope, options?: RequestOptions) => Promise<Secret & {
+        enforced: boolean;
+    }>;
     /** The sandboxes' secrets: names, hosts and placeholders. Never values.
      * `all()` includes the jobs copies. */
     list: (options?: RequestOptions) => Promise<Secret[]>;

package/dist/products/secrets.js

@@ -36,16 +36,47 @@ export function secrets(t) {
     const key = (options, part) => options?.idempotencyKey
         ? { ...options, idempotencyKey: `${options.idempotencyKey}:${part}`.slice(0, 128) }
         : options;
+    const create = (name, value, options) => store({ method: "POST", path: "/v1/secrets", body: { name, value }, ...options });
+    const rotate = (live, value, version, options) => store({
+        method: "POST",
+        path: `${jobPath(live.id)}:rotate`,
+        body: { value, expectedVersion: version },
+        ...options,
+    });
+    /** Rotates the jobs copy from the version it has now. A key used before,
+     * by this same call whose answer was lost, is answered by the identical
+     * request again, with no second rotation: the rotate from the version
+     * before, or one of `earlier` (a set's create). Until 10 October 2026 the
+     * retry read the copy as it is now, changed its request, and was refused
+     * as a conflict. */
+    async function rotateOrReplay(live, value, options, earlier = []) {
+        try {
+            return await rotate(live, value, live.version, options);
+        }
+        catch (error) {
+            if (!(error instanceof RuntimeError) || error.code !== "idempotency_conflict")
+                throw error;
+            const replays = [
+                ...earlier,
+                ...(live.version > 1 ? [() => rotate(live, value, live.version - 1, options)] : []),
+            ];
+            for (const replay of replays) {
+                const answer = await replay().catch((again) => {
+                    if (again instanceof RuntimeError && again.status === 409)
+                        return undefined;
+                    throw again;
+                });
+                if (answer)
+                    return answer;
+            }
+            throw error;
+        }
+    }
     async function setJobCopy(name, value, options) {
         const copies = await jobCopies(options);
         const live = copies.find((s) => s.name === name && s.deletedAt === null);
         if (live)
-            return store({
-                method: "POST",
-                path: `${jobPath(live.id)}:rotate`,
-                body: { value, expectedVersion: live.version },
-                ...options,
-            });
+            return rotateOrReplay(live, value, options, [() => create(name, value, options)]);
         if (copies.some((s) => s.name === name))
             throw new RuntimeError({
                 message: `A jobs secret named ${name} was deleted, and a deleted name cannot be used again.`,
@@ -54,12 +85,7 @@ export function secrets(t) {
                 hint: "Store it under another name.",
                 details: { field: "name" },
             });
-        return store({
-            method: "POST",
-            path: "/v1/secrets",
-            body: { name, value },
-            ...options,
-        });
+        return create(name, value, options);
     }
     async function all(options) {
         const [forSandboxes, forJobs] = await Promise.all([
@@ -127,6 +153,14 @@ export function secrets(t) {
          * at once store both; if only the first lands, `SecretPartlyStoredError`
          * says so and the same call again finishes it. */
         set,
+        /** Changes which sandboxes get a secret, without its value: `{}` is every
+         * sandbox of the organization again. */
+        scope: (name, only, options) => t.json({
+            method: "PUT",
+            path: `${path(name)}/sandboxes`,
+            body: only,
+            ...options,
+        }),
         /** The sandboxes' secrets: names, hosts and placeholders. Never values.
          * `all()` includes the jobs copies. */
         list,
@@ -156,12 +190,7 @@ export function secrets(t) {
                     status: 404,
                     hint: "Store one with set(name, { value, jobs: true }). The sandboxes' copy is replaced by set, not rotated.",
                 });
-            return store({
-                method: "POST",
-                path: `${jobPath(live.id)}:rotate`,
-                body: { value, expectedVersion: live.version },
-                ...options,
-            });
+            return rotateOrReplay(live, value, options);
         },
         /** Read the jobs copy's value back (needs the key's secrets_reveal
          * permission). The sandboxes' copy can never be read back. */

package/dist/products/signed-requests.d.ts

@@ -0,0 +1,21 @@
+import type { RequestOptions, Transport } from "../transport.js";
+export type SignedRequests = {
+    /** Whether your sandboxes may get Runtime's request signature now. */
+    enabled: boolean;
+    /** Whether this account may turn it on: it must have credit. */
+    allowed: boolean;
+    /** Why not, when `allowed` is false: `no_credit`, `revoked` or `suspended`. */
+    why: string | null;
+    enabledAt: string | null;
+    disabledAt: string | null;
+};
+export declare function signedRequests(t: Transport): {
+    /** On or off, and whether this account may turn it on. */
+    get: (options?: RequestOptions) => Promise<SignedRequests>;
+    /** `enabled: true` lets your sandboxes get Runtime's request signature;
+     * `false` stops new signatures at once, and ones already given expire
+     * within 5 minutes. */
+    set: (input: {
+        enabled: boolean;
+    }, options?: RequestOptions) => Promise<SignedRequests>;
+};

package/dist/products/signed-requests.js

@@ -0,0 +1,11 @@
+export function signedRequests(t) {
+    const path = "/v1/networks/signed-requests";
+    return {
+        /** On or off, and whether this account may turn it on. */
+        get: (options) => t.json({ method: "GET", path, ...options }),
+        /** `enabled: true` lets your sandboxes get Runtime's request signature;
+         * `false` stops new signatures at once, and ones already given expire
+         * within 5 minutes. */
+        set: (input, options) => t.json({ method: "PUT", path, body: input, ...options }),
+    };
+}

package/dist/products/streams.d.ts

@@ -0,0 +1,73 @@
+import type { RequestOptions, Transport } from "../transport.js";
+import { type RecordResource } from "./queues.js";
+/** Private until launch.
+ * Kafka clients use kafka.bootstrap and kafka.topic unchanged.
+ * Offsets and byte counts use decimal strings so JSON never rounds them. */
+export type Stream = RecordResource & {
+    partitions: number;
+    retentionMs: number;
+    retentionBytes: string;
+    kafka: {
+        bootstrap: string;
+        topic: string;
+    };
+};
+export type CreateStream = {
+    name: string;
+    labels?: Record<string, string>;
+    partitions?: number;
+    retentionMs?: number;
+    retentionBytes?: string;
+};
+export type UpdateStream = Partial<CreateStream>;
+/** Text values are UTF-8. Use a Kafka client for arbitrary binary records. */
+export type StreamRecord = {
+    key?: string | null;
+    value: string | null;
+    headers?: {
+        key: string;
+        value: string | null;
+    }[];
+};
+export type PublishRecords = {
+    records: StreamRecord[];
+};
+export type ReadStream = {
+    partition: number;
+    maxBytes?: number;
+    waitMs?: number;
+} & ({
+    offset: string;
+    time?: never;
+} | {
+    time: number;
+    offset?: never;
+});
+export type PublishedRecord = {
+    partition: number;
+    offset: string;
+};
+export type StreamRead = {
+    records: (StreamRecord & PublishedRecord & {
+        time: number;
+    })[];
+    nextOffset: string;
+};
+/** Private until launch. Proposed routes only; nothing is registered here. */
+export declare function streams(t: Transport): {
+    publish: (id: string, input: PublishRecords, options?: RequestOptions) => Promise<{
+        records: PublishedRecord[];
+    }>;
+    read: (id: string, input: ReadStream, options?: RequestOptions) => Promise<StreamRead>;
+    /** Trim returns the resource; follow its state with wait(id). */
+    trim: (id: string, input: {
+        partition: number;
+        before: string;
+    }, options?: RequestOptions) => Promise<Stream>;
+    create: (input: CreateStream, options?: RequestOptions) => Promise<Stream>;
+    get: (id: string, options?: RequestOptions) => Promise<Stream>;
+    list: (query?: import("./queues.js").RecordListQuery, options?: RequestOptions) => Promise<import("../page.js").Page<Stream>>;
+    update: (id: string, input: Partial<CreateStream>, options?: RequestOptions) => Promise<Stream>;
+    delete: (id: string, options?: RequestOptions) => Promise<Stream>;
+    wait(id: string, target?: "ready" | "deleted", options?: import("./queues.js").RecordWaitOptions): Promise<Stream>;
+};

package/dist/products/streams.js

@@ -0,0 +1,17 @@
+import { recordResources } from "./queues.js";
+/** Private until launch. Proposed routes only; nothing is registered here. */
+export function streams(t) {
+    const path = (id) => `/v1/streams/${encodeURIComponent(id)}`;
+    return {
+        ...recordResources(t, "streams"),
+        publish: (id, input, options) => t.json({
+            ...options,
+            method: "POST",
+            path: `${path(id)}:publish`,
+            body: input,
+        }),
+        read: (id, input, options) => t.json({ ...options, method: "GET", path: `${path(id)}:read`, query: input }),
+        /** Trim returns the resource; follow its state with wait(id). */
+        trim: (id, input, options) => t.json({ ...options, method: "POST", path: `${path(id)}:trim`, body: input }),
+    };
+}

package/dist/products/switching.d.ts

@@ -9,7 +9,7 @@ export type SwitchProvider = "e2b" | "daytona" | "vercel" | "modal" | "cloudflar
 export type SwitchingSummary = {
     /** False while the programme is paused. */
     enabled: boolean;
-    /** The most a first top-up is matched to. */
+    /** The most the organization's payments are matched to, in total. */
     maxMicros: string;
     providers: SwitchProvider[];
     /** Whether this organization can record a switch now: none recorded, and
@@ -17,14 +17,41 @@ export type SwitchingSummary = {
     eligible: boolean;
     switch: {
         provider: SwitchProvider;
-        /** superseded: a referral matched the first top-up instead, which is
+        /** superseded: a referral matches the payments instead, which is
          * never less. The two are never both paid. */
         status: "pending" | "paid" | "superseded" | "refused" | "reversed";
-        refusedReason: "program_off" | "suspended" | "same_card" | "fraud" | null;
+        refusedReason: "program_off" | "suspended" | "same_card" | "fraud" | "too_late" | null;
         recordedAt: string;
-        /** The switching credit this organization got and kept. */
+        /** The matches this organization got and kept. */
         creditMicros: string;
     } | null;
+    /** The welcome match: credit an organization adds within 30 days of
+     * signing up is matched, up to $1,000 in total. */
+    welcome: WelcomeMatch;
+};
+export type WelcomeMatch = {
+    /** False while the match is paused. */
+    enabled: boolean;
+    /** The most the organization's payments are matched to, in total. */
+    maxMicros: string;
+    /** When the offer ends: 30 days after the organization signed up. */
+    endsAt: string;
+    /** Whether credit added now would be matched: some is left, before endsAt. */
+    eligible: boolean;
+    /** Whether credit has been added. */
+    toppedUp: boolean;
+    /** Null until a payment is decided; paid while a match is kept.
+     * superseded: a referral matches the payments instead, which is never
+     * less. */
+    status: "pending" | "paid" | "superseded" | "refused" | "reversed" | null;
+    /** The matches this organization got and kept. */
+    creditMicros: string;
+    /** The part of maxMicros used so far. Absent from a server before
+     * 8 October 2026. */
+    usedMicros?: string;
+    /** What credit added now could still get; "0" once the offer ends. Absent
+     * from a server before 8 October 2026. */
+    leftMicros?: string;
 };
 export type UsageComparison = {
     provider: CompareProvider;
@@ -76,8 +103,9 @@ export type UsageComparison = {
     switching: SwitchingSummary;
 };
 /** `runtime.switching`: compare your usage with a rival's published rates,
- * and record the rival you are leaving so your first top-up is matched, up to
- * $100, once the payment settles. */
+ * record the rival you are leaving, and read the welcome match: credit added
+ * within 30 days of signing up is matched, up to $1,000 in total, as each
+ * payment settles. */
 export declare function switching(t: Transport): {
     /** Your settled sandbox usage over the last `days` (default 30, at most
      * 90), priced on Runtime and at the rival, with the saving. */
@@ -85,7 +113,7 @@ export declare function switching(t: Transport): {
         provider: CompareProvider;
         days?: number;
     }, options?: RequestOptions) => Promise<UsageComparison>;
-    /** Whether a switch can still be recorded, and what it paid. */
+    /** Whether a switch can still be recorded, and what the welcome match paid. */
     get: (options?: RequestOptions) => Promise<SwitchingSummary>;
     /** Once per organization, before its first top-up. Recording the same
      * provider again answers the same summary; another fails with 409. */

package/dist/products/switching.js

@@ -1,6 +1,7 @@
 /** `runtime.switching`: compare your usage with a rival's published rates,
- * and record the rival you are leaving so your first top-up is matched, up to
- * $100, once the payment settles. */
+ * record the rival you are leaving, and read the welcome match: credit added
+ * within 30 days of signing up is matched, up to $1,000 in total, as each
+ * payment settles. */
 export function switching(t) {
     return {
         /** Your settled sandbox usage over the last `days` (default 30, at most
@@ -11,7 +12,7 @@ export function switching(t) {
             query: { provider: input.provider, days: input.days },
             ...options,
         }),
-        /** Whether a switch can still be recorded, and what it paid. */
+        /** Whether a switch can still be recorded, and what the welcome match paid. */
         get: (options) => t.json({ method: "GET", path: "/v1/switching", ...options }),
         /** Once per organization, before its first top-up. Recording the same
          * provider again answers the same summary; another fails with 409. */

package/dist/products/volumes.d.ts

@@ -86,7 +86,13 @@ export type VolumeBackup = {
     storedBytes: number | null;
     meteredBytes: number | null;
     error: string | null;
+    /** Why it failed, when a code says it: `backup_stalled` when its copy off
+     * the host never began; back it up again. */
+    errorCode?: string | null;
     createdAt: string;
+    /** When its copy off the volume's server began; null while it waits its
+     * turn behind other copies there. */
+    copyStartedAt?: string | null;
     readyAt: string | null;
     expiresAt: string;
 };

package/dist/record-cli.d.ts

@@ -0,0 +1,23 @@
+import type { queues } from "./products/queues.js";
+import type { streams } from "./products/streams.js";
+/** Private until launch. CLOUD.md section 4. cli.ts does not call this module. */
+export declare const RECORD_PRODUCTS: readonly ["queue", "stream"];
+export type RecordProduct = (typeof RECORD_PRODUCTS)[number];
+export type RecordClient = {
+    queues: ReturnType<typeof queues>;
+    streams: ReturnType<typeof streams>;
+};
+type Args = {
+    positional: string[];
+    flags: Map<string, string[]>;
+    rest?: string[];
+};
+type Out = {
+    json: boolean;
+    write(text: string): void;
+    error(text: string): void;
+};
+export declare const RECORD_HELP: Record<RecordProduct, string>;
+/** Parsed like networkProductCommand; never obtains credentials for help or bad flags. */
+export declare function recordCommand(product: RecordProduct, args: Args, out: Out, client: () => Promise<RecordClient>, signal?: AbortSignal): Promise<number>;
+export {};