withruntime 0.23.0 → 0.33.0

package/dist/products/jobs.d.ts

@@ -15,6 +15,15 @@ export type JobCompute = {
     durationSeconds: number;
     /** The most one run may hold, in microdollars. */
     maxCostMicros?: number;
+    /** Volumes each run's sandbox attaches, at most four, as a sandbox create
+     * takes them. `"rw"` (the default) is read-write, one sandbox at a time, so
+     * what one run writes the next run reads; `"snapshot"` is a read-only copy
+     * as the run starts. The run starts on the volume's server. */
+    volumes?: {
+        volumeId: string;
+        path: string;
+        mode?: "rw" | "snapshot";
+    }[];
 };
 export type JobSchedule = {
     kind: "once"; /** Unix milliseconds. */
@@ -44,6 +53,40 @@ export type JobDefinition = {
         name: string;
         secretId: string;
     }>;
+    /** The id of the image each run starts from; absent, the standard image. */
+    image?: string;
+};
+/** Who hears when a job's runs fail. Once `afterFailures` runs in a row end
+ * failed, timed out or unknown, one alert goes out; once a run succeeds
+ * again, one more says it recovered. A run that will be retried counts at
+ * its last attempt. */
+export type JobAlert = {
+    /** Runs in a row, 1 to 100. Default 1. */
+    afterFailures?: number;
+    /** POSTed the account webhooks' body (`job.run.failed`, `job.recovered`),
+     * signed with the jobs secret `secretId` the way those are signed with
+     * theirs: check it with `verifyWebhook(body, header, secretValue)`. The
+     * key must be allowed to reveal that secret, not only use it. */
+    webhook?: {
+        url: string;
+        secretId?: string;
+    };
+    /** Mailed to the job's person: who made it, or whom its key serves. */
+    email?: true;
+};
+/** The last alert a job sent and how its delivery went. */
+export type JobAlertDelivery = {
+    id: string;
+    type: "job.run.failed" | "job.recovered";
+    channel: "webhook" | "email";
+    runId: string;
+    /** `pending` while it is retried (about three days, as webhooks are). */
+    state: "pending" | "succeeded" | "failed";
+    attempts: number;
+    lastStatus: number | null;
+    lastError: string | null;
+    createdAt: number;
+    deliveredAt: number | null;
 };
 export type Job = {
     id: string;
@@ -58,8 +101,18 @@ export type Job = {
     runRequestedAt: number | null;
     /** Why the last due run could not start, retried every 30 seconds:
      * `credits` (add credit), `capacity`, `cost_cap` (maxTotalCostMicros or a
-     * key's daily limit) or `permission` (the key that made the job lost it). */
-    blockedReason: "permission" | "capacity" | "credits" | "cost_cap" | null;
+     * key's daily limit), `permission` (the key that made the job lost it, or
+     * may not use a volume it attaches) or `volume` (a volume it attaches is
+     * deleted, not ready, or attached read-write to another sandbox). */
+    blockedReason: "permission" | "capacity" | "credits" | "cost_cap" | "volume" | null;
+    alert: (JobAlert & {
+        afterFailures: number;
+    }) | null;
+    /** Runs in a row that ended failing, until one succeeds. */
+    failingRuns: number;
+    /** When its alert went out, while its runs keep failing; Unix ms. */
+    alertingSince: number | null;
+    lastAlert: JobAlertDelivery | null;
     createdAt: number;
     updatedAt: number;
 };
@@ -137,6 +190,38 @@ export type CreateJob = {
     }>;
     /** The most every run of this job together may hold, in microdollars. */
     maxTotalCostMicros?: number;
+    /** An image of this account each run starts from: its id, name (its
+     * `latest` tag), `name:tag` or `name@version`, resolved to its id now, as
+     * an App deploy takes it. Default: the standard image. */
+    image?: string;
+    /** Tell a webhook or the job's person when runs fail, and when they
+     * recover. */
+    alert?: JobAlert;
+};
+/** What `jobs.update` changes; everything left out stays. The name stays,
+ * and the schedule moves with `reschedule`. */
+export type UpdateJob = {
+    command?: CreateJob["command"];
+    /** null: back to the standard image. */
+    image?: string | null;
+    /** The fields given; the rest stay. `volumes` replaces the whole list
+     * (`[]`: none). */
+    compute?: Partial<JobCompute>;
+    /** The whole list, replacing the one before. */
+    secrets?: Array<{
+        name: string;
+        secretId: string;
+    }>;
+    /** null: no alert. */
+    alert?: JobAlert | null;
+    timeoutSeconds?: number;
+    /** The fields given; the rest stay. */
+    retry?: Partial<{
+        maxAttempts: number;
+        backoffSeconds: number;
+    }>;
+    /** null: no cap. */
+    maxTotalCostMicros?: number | null;
 };
 /** The size a run gets when `compute` leaves a field out: the sandbox
  * defaults, in the region `us-east`. */
@@ -161,6 +246,7 @@ export declare const JOB_LIMITS: {
     maxDurationSeconds: number;
     maxAttempts: number;
     maxSecrets: number;
+    maxVolumes: number;
 };
 /** Unix milliseconds from a Date, an ISO time or a number. */
 export declare function jobTime(at: Date | string | number): number;
@@ -170,8 +256,11 @@ export declare function jobSchedule(input: CreateJob["schedule"]): JobSchedule;
 /** The API's job body from `CreateJob`, with every default filled in and the
  * sandbox's size checked before anything is sent. */
 export declare function jobBody(input: CreateJob): Record<string, unknown>;
-/** The API answers a product switched off where it runs with 503
- * `unavailable` and words that do not name it ("This product is not enabled
+/** The API's update body from `UpdateJob`: a command as an argv array is
+ * sent as `{ argv }`; the rest as given. */
+export declare function jobUpdateBody(input: UpdateJob): Record<string, unknown>;
+/** The API answers a product switched off where it runs with 501 (503
+ * from an older server) `unavailable` and words that do not name it ("This product is not enabled
  * on this deployment."). This names the product, keeps the code, status and
  * request id, and says no retry will change it. */
 export declare function switchedOff(product: string): (error: unknown) => never;
@@ -199,10 +288,14 @@ export declare function jobs(transport: Transport): {
         cursor?: string;
     }, options?: RequestOptions) => Promise<Page<Job>>;
     get: (id: string, options?: RequestOptions) => Promise<Job>;
-    /** A job's runs, oldest first: each attempt of each occurrence. */
+    /** A job's runs, oldest first: each attempt of each occurrence.
+     * `{ order: "newest" }`: newest first, so the last run is one call.
+     *
+     *   const [last] = (await runtime.jobs.runs(job.id, { limit: 1, order: "newest" })).data; */
     runs: (jobId: string, query?: {
         limit?: number;
         cursor?: string;
+        order?: "oldest" | "newest";
     }, options?: RequestOptions) => Promise<Page<JobRun>>;
     /** One run by its id. */
     run: (runId: string, options?: RequestOptions) => Promise<JobRun>;
@@ -228,4 +321,11 @@ export declare function jobs(transport: Transport): {
      * `{ at }`. The next run is the new schedule's next time; a run going
      * finishes as it began, and a paused job stays paused. */
     reschedule: (id: string, schedule: CreateJob["schedule"], options?: RequestOptions) => Promise<Job>;
+    /** Change a job in place: its command, image, compute, secrets, alert,
+     * timeout or retry. Its id, history and schedule stay; a run already
+     * started finishes as it began, and the next run is the new job.
+     *
+     *   await runtime.jobs.update(job.id, { image: "hub:latest" });
+     *   await runtime.jobs.update(job.id, { alert: { afterFailures: 3, email: true } }); */
+    update: (id: string, changes: UpdateJob, options?: RequestOptions) => Promise<Job>;
 };

package/dist/products/jobs.js

@@ -24,6 +24,7 @@ export const JOB_LIMITS = {
     maxDurationSeconds: 3600,
     maxAttempts: 5,
     maxSecrets: 16,
+    maxVolumes: 4,
 };
 function invalid(message, field) {
     return new RuntimeError({
@@ -87,7 +88,20 @@ export function jobBody(input) {
         durationSeconds: given.durationSeconds ??
             Math.min(JOB_LIMITS.maxDurationSeconds, timeoutSeconds + JOB_DEFAULTS.startSeconds),
         ...(given.maxCostMicros === undefined ? {} : { maxCostMicros: given.maxCostMicros }),
+        ...(given.volumes === undefined ? {} : { volumes: given.volumes }),
     };
+    // The API checks each volume is the key's, in the job's region; this
+    // catches a malformed list before anything is sent.
+    if (compute.volumes !== undefined) {
+        const volumes = compute.volumes;
+        if (!Array.isArray(volumes) ||
+            volumes.length > JOB_LIMITS.maxVolumes ||
+            volumes.some((v) => typeof v?.volumeId !== "string" ||
+                typeof v.path !== "string" ||
+                !v.path.startsWith("/") ||
+                (v.mode !== undefined && v.mode !== "rw" && v.mode !== "snapshot")))
+            throw invalid(`compute.volumes is at most ${JOB_LIMITS.maxVolumes} of { volumeId, path: "/data", mode?: "rw" | "snapshot" }.`, "compute.volumes");
+    }
     if (compute.vcpu > JOB_LIMITS.maxVcpu || compute.memoryMiB > JOB_LIMITS.maxMemoryMiB)
         throw invalid(`A run's sandbox is at most ${JOB_LIMITS.maxVcpu} vCPU and ${JOB_LIMITS.maxMemoryMiB / 1024} GiB of memory; asked for ${compute.vcpu} vCPU and ${compute.memoryMiB} MiB.`, compute.vcpu > JOB_LIMITS.maxVcpu ? "compute.vcpu" : "compute.memoryMiB");
     if (compute.diskMiB < JOB_LIMITS.minDiskMiB)
@@ -108,11 +122,26 @@ export function jobBody(input) {
         ...(input.maxTotalCostMicros === undefined
             ? {}
             : { maxTotalCostMicros: input.maxTotalCostMicros }),
+        ...(input.image === undefined ? {} : { image: input.image }),
+        ...(input.alert === undefined ? {} : { alert: input.alert }),
     };
 }
+/** The API's update body from `UpdateJob`: a command as an argv array is
+ * sent as `{ argv }`; the rest as given. */
+export function jobUpdateBody(input) {
+    const body = {};
+    for (const [field, value] of Object.entries(input))
+        if (value !== undefined)
+            body[field] = value;
+    if (Array.isArray(input.command))
+        body.command = { argv: input.command };
+    if (!Object.keys(body).length)
+        throw invalid("update takes at least one of command, image, compute, secrets, alert, timeoutSeconds, retry or maxTotalCostMicros.", "update");
+    return body;
+}
 const enc = encodeURIComponent;
-/** The API answers a product switched off where it runs with 503
- * `unavailable` and words that do not name it ("This product is not enabled
+/** The API answers a product switched off where it runs with 501 (503
+ * from an older server) `unavailable` and words that do not name it ("This product is not enabled
  * on this deployment."). This names the product, keeps the code, status and
  * request id, and says no retry will change it. */
 export function switchedOff(product) {
@@ -170,7 +199,10 @@ export function jobs(transport) {
         /** Your jobs, oldest first. Await for a page, or `for await` for all. */
         list,
         get: (id, options) => t.json({ method: "GET", path: `/v1/jobs/${enc(id)}`, ...options }),
-        /** A job's runs, oldest first: each attempt of each occurrence. */
+        /** A job's runs, oldest first: each attempt of each occurrence.
+         * `{ order: "newest" }`: newest first, so the last run is one call.
+         *
+         *   const [last] = (await runtime.jobs.runs(job.id, { limit: 1, order: "newest" })).data; */
         runs,
         /** One run by its id. */
         run: (runId, options) => t.json({ method: "GET", path: `/v1/job-runs/${enc(runId)}`, ...options }),
@@ -203,5 +235,17 @@ export function jobs(transport) {
             body: { schedule: jobSchedule(schedule) },
             ...options,
         }),
+        /** Change a job in place: its command, image, compute, secrets, alert,
+         * timeout or retry. Its id, history and schedule stay; a run already
+         * started finishes as it began, and the next run is the new job.
+         *
+         *   await runtime.jobs.update(job.id, { image: "hub:latest" });
+         *   await runtime.jobs.update(job.id, { alert: { afterFailures: 3, email: true } }); */
+        update: (id, changes, options) => t.json({
+            method: "POST",
+            path: `/v1/jobs/${enc(id)}:update`,
+            body: jobUpdateBody(changes),
+            ...options,
+        }),
     };
 }

package/dist/products/network.d.ts

@@ -28,6 +28,19 @@ export type NetworkPolicy = Required<NetworkRules> & {
     connectReason: string;
     forbiddenPorts: number[];
     updatedAt: string | null;
+    /** The outbound limits the sandbox's host holds it to. Open connections
+     * grow with its vCPUs when its organization keeps a top-up; past the rate
+     * or the new destinations a connection waits its turn. Meeting one sends
+     * the event `sandbox.network.limited`. */
+    limits: NetworkLimits;
+};
+export type NetworkLimits = {
+    /** Open connections at once. */
+    connections: number;
+    newConnectionsPerSecond: number;
+    /** New connections it may open at once before the rate holds. */
+    newConnectionBurst: number;
+    destinationsPerMinute: number;
 };
 /** `sbx.network`: turn the sandbox's internet off or on, narrow it to a list,
  * refuse destinations, or open host:port pairs. Changes apply at once, to open

package/dist/products/observability.d.ts

@@ -35,7 +35,7 @@ export type SandboxMetrics = {
     latest: MetricPoint | null;
     points: MetricPoint[];
 };
-export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "sandbox.host_unreachable" | "sandbox.host_reachable" | "sandbox.recovered" | "sandbox.recovery_failed" | "sandbox.files.changed" | "sandbox.out_of_memory" | "sandbox.secret_not_applied" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted" | "volume.recovered" | "egress_secret.created" | "egress_secret.updated" | "egress_secret.deleted" | "upstream_proxy.set" | "upstream_proxy.removed" | "credit.low" | "credit.empty";
+export type WebhookEventType = "sandbox.created" | "sandbox.running" | "sandbox.paused" | "sandbox.woken" | "sandbox.stopped" | "sandbox.start_failed" | "sandbox.wake_failed" | "sandbox.host_unreachable" | "sandbox.host_reachable" | "sandbox.recovered" | "sandbox.recovery_failed" | "sandbox.files.changed" | "sandbox.out_of_memory" | "sandbox.secret_not_applied" | "sandbox.network.limited" | "snapshot.ready" | "snapshot.failed" | "snapshot.deleted" | "volume.ready" | "volume.failed" | "volume.deleted" | "volume.recovered" | "egress_secret.created" | "egress_secret.updated" | "egress_secret.deleted" | "upstream_proxy.set" | "upstream_proxy.removed" | "credit.low" | "credit.empty" | "job.run.failed" | "job.recovered";
 /** An event as /v1/events lists it and a webhook delivers it. */
 export type RuntimeEvent = {
     id: string;

package/dist/products/plans.d.ts

@@ -0,0 +1,131 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** A ceiling a plan raises, as GET /v1/limits and quota_exceeded name it
+ * (sandbox.count); a null max is no limit at all. */
+export type PlanLimit = {
+    limit: string;
+    max: number | null;
+};
+/** Usage a plan includes each month beside its fee, such as Apps' traffic
+ * out. */
+export type PlanIncluded = {
+    product: string;
+    meter: string;
+    quantity: number;
+    unit: string;
+};
+/** An add-on a plan offers, charged monthly beside its fee. */
+export type PlanAddOn = {
+    /** What `addOn` takes. */
+    id: string;
+    name: string;
+    /** Monthly, beside the plan's fee. */
+    feeMicros: string;
+    /** What it adds to a limit. */
+    limits: {
+        limit: string;
+        add: number;
+    }[];
+    /** The feature it turns on, if any. */
+    feature: string | null;
+};
+/** One plan: a monthly fee that comes back as plan usage, spent first each
+ * month at the same measured prices, plus a bonus for committing. Money is
+ * integer microdollars in strings (1,000,000 = $1). */
+export type Plan = {
+    /** What choose takes. */
+    id: string;
+    name: string;
+    /** Plans shown as one card with a switch share it, such as Pro and its
+     * larger option. */
+    card: string | null;
+    /** The monthly fee, before tax; 0 for Free. */
+    feeMicros: string;
+    /** A year paid at once: ten months' fee for twelve. Null without a yearly
+     * price. */
+    yearlyFeeMicros: string | null;
+    /** Usage given on top of the fee each month. */
+    bonusMicros: string;
+    /** Days of trial, no card; 0 for none. */
+    trialDays: number;
+    /** The first month on the plan, and the first after an upgrade to it,
+     * holds twice its usage. */
+    firstPeriodDouble: boolean;
+    support: "docs" | "agent" | "slack" | "dedicated";
+    /** card: the fee is charged to the card the plan saves. invoice: a
+     * contract, invoiced. */
+    collection: "card" | "invoice";
+    /** A contract made for your organization alone. */
+    contract: boolean;
+    /** The catalogue's order: the next plan up is next. */
+    position: number;
+    included: PlanIncluded[];
+    /** Ceilings the plan raises, never lowers. A ceiling is not reserved room. */
+    limits: PlanLimit[];
+    /** What the plan turns on: sso, roles, audit, support-agent… */
+    features: string[];
+    addOns: PlanAddOn[];
+};
+/** The plan your organization is on, or null with none (Free). */
+export type PlanNow = {
+    planId: string;
+    name: string;
+    /** incomplete: the first payment is not through yet. trialing: a trial,
+     * until trialEndsAt. past_due: a payment failed and is retried. */
+    status: "incomplete" | "trialing" | "active" | "past_due" | "canceled";
+    interval: "month" | "year";
+    periodStart: string | null;
+    /** The next fee, or the end of a cancelled plan. */
+    periodEnd: string | null;
+    /** When a trial ends; null outside one. */
+    trialEndsAt: string | null;
+    /** True once a cancel takes effect at periodEnd. */
+    cancelAtPeriodEnd: boolean;
+    /** The plan a downgrade moves to at periodEnd. */
+    nextPlanId: string | null;
+    startedAt: string;
+    /** endsAt: when a removed add-on stops; null while it renews. */
+    addOns: {
+        id: string;
+        quantity: number;
+        endsAt: string | null;
+    }[];
+    /** An owner said yes to moving up a plan when a limit refuses. */
+    autoUpgrade: boolean;
+    /** This period's plan usage, spent before any credit; it ends with the
+     * period. */
+    planUsage: {
+        grantedMicros: string;
+        leftMicros: string;
+        expiresAt: string;
+    } | null;
+};
+export type Plans = {
+    current: PlanNow | null;
+    plans: Plan[];
+};
+/** What a change answers: a link where a person starts a first plan or a
+ * trial in the browser, or the plan as changed. */
+export type PlanChange = {
+    checkoutUrl: string | null;
+    current: PlanNow | null;
+};
+/** `runtime.plans`: monthly plans whose fee is prepaid usage. You still pay
+ * only for what runs, at the same prices; the fee comes back as usage. */
+export declare function plans(t: Transport): {
+    list: (options?: RequestOptions) => Promise<Plans>;
+    /** Start a plan, or move to another; interval year pays ten months for
+     * twelve. */
+    choose: (plan: string, options?: RequestOptions & {
+        interval?: "month" | "year";
+    }) => Promise<PlanChange>;
+    /** End the plan at periodEnd. */
+    cancel: (options?: RequestOptions) => Promise<PlanChange>;
+    /** Keep a plan you cancelled, before periodEnd. */
+    resume: (options?: RequestOptions) => Promise<PlanChange>;
+    /** Add an add-on to the plan, charged now prorated. */
+    addOn: (addOn: string, options?: RequestOptions) => Promise<PlanChange>;
+    /** Remove an add-on: its charge stops now, and it holds to periodEnd. */
+    removeAddOn: (addOn: string, options?: RequestOptions) => Promise<PlanChange>;
+    /** Move up a plan by itself when a limit refuses, or not. Owners only. */
+    autoUpgrade: (on: boolean, options?: RequestOptions) => Promise<PlanChange>;
+};

package/dist/products/plans.js

@@ -0,0 +1,24 @@
+/** `runtime.plans`: monthly plans whose fee is prepaid usage. You still pay
+ * only for what runs, at the same prices; the fee comes back as usage. */
+export function plans(t) {
+    const change = (method, path, body) => (options) => t.json({ method, path, ...(body ? { body } : {}), ...options });
+    return {
+        list: (options) => t.json({ method: "GET", path: "/v1/plans", ...options }),
+        /** Start a plan, or move to another; interval year pays ten months for
+         * twelve. */
+        choose: (plan, options) => {
+            const { interval, ...rest } = options ?? {};
+            return change("POST", "/v1/plans/choose", { plan, ...(interval ? { interval } : {}) })(rest);
+        },
+        /** End the plan at periodEnd. */
+        cancel: (options) => change("POST", "/v1/plans/cancel", {})(options),
+        /** Keep a plan you cancelled, before periodEnd. */
+        resume: (options) => change("POST", "/v1/plans/resume", {})(options),
+        /** Add an add-on to the plan, charged now prorated. */
+        addOn: (addOn, options) => change("POST", "/v1/plans/add-ons", { addOn })(options),
+        /** Remove an add-on: its charge stops now, and it holds to periodEnd. */
+        removeAddOn: (addOn, options) => change("DELETE", `/v1/plans/add-ons/${encodeURIComponent(addOn)}`, undefined)(options),
+        /** Move up a plan by itself when a limit refuses, or not. Owners only. */
+        autoUpgrade: (on, options) => change("PUT", "/v1/plans/auto-upgrade", { on })(options),
+    };
+}

package/dist/products/reservations.d.ts

@@ -0,0 +1,108 @@
+import type { RequestOptions, Transport } from "../transport.js";
+export type BookRoom = {
+    /** How many sandboxes of this size to hold room for: 1 to 10000. */
+    sandboxes: number;
+    /** When the window starts: a Date or an ISO 8601 time, within 14 days. */
+    startsAt: Date | string;
+    /** When it ends: at most 24 hours after it starts. */
+    endsAt: Date | string;
+    /** Size of each sandbox. Default 2 vCPU, 4096 MiB memory, 4096 MiB disk. */
+    vcpu?: number;
+    memoryMiB?: number;
+    diskMiB?: number;
+    /** Default: the account's default region. */
+    region?: string;
+};
+export type KeepRoom = {
+    /** How many sandboxes to hold room for: 1 to 10000. Keep a few more than
+     *  the pool runs, for deletes the servers are still finishing. */
+    sandboxes: number;
+    /** The snapshots its sandboxes fork from (at most 20, one size): the room is
+     *  held on the servers holding them, at their size. */
+    snapshots?: string[];
+    /** Size of each sandbox when no snapshots are named. Default 2 vCPU, 4096
+     *  MiB memory, 4096 MiB disk. */
+    vcpu?: number;
+    memoryMiB?: number;
+    diskMiB?: number;
+    /** Hold it for this key's sandboxes alone. Default: the whole account's. */
+    forKey?: boolean;
+    /** Default: the account's default region. */
+    region?: string;
+};
+/** A change to standing room: how many it holds, its snapshots, or both. */
+export type ChangeRoom = {
+    sandboxes?: number;
+    snapshots?: string[];
+};
+export type RoomBooking = {
+    id: string;
+    /** confirmed: the room is held. declined: nothing is held; `reason`,
+     *  `message`, `largestSandboxes` and `nearestWindow` say why and what would
+     *  fit. cancelled: given back. */
+    status: "confirmed" | "declined" | "cancelled";
+    /** Standing room: held until cancelled, with no window. */
+    standing: boolean;
+    /** Standing room's snapshots; empty: any server in the region. */
+    snapshots: string[];
+    /** Held for the key that booked it alone. */
+    forKey: boolean;
+    reason: "room" | "share" | "usage" | "credit" | null;
+    message: string;
+    region: string;
+    sandboxes: number;
+    vcpu: number;
+    memoryMiB: number;
+    diskMiB: number;
+    startsAt: string;
+    /** Null for standing room. */
+    endsAt: string | null;
+    /** endsAt while confirmed; null for standing room. */
+    heldUntil: string | null;
+    phase: "upcoming" | "active" | "ended" | null;
+    /** The most sandboxes of this size that fit in the window. */
+    largestSandboxes: number;
+    /** The nearest window the whole booking fits in, or null. */
+    nearestWindow: {
+        startsAt: string;
+        endsAt: string;
+    } | null;
+    /** The most the booking can cost: every booked sandbox running the whole window (any mix of running and unused costs less). */
+    estimateMicros: string;
+    /** What booked room no sandbox of the account uses costs, in microdollars per GiB-hour of the booked sandboxes' memory, as quoted when booked ("0" before it had a price). */
+    unusedRateMicros: string;
+    /** The most the booking costs if none of its sandboxes run (nothing if cancelled at least an hour before it starts). */
+    unusedMaxMicros: string | null;
+    /** The most its unused room costs an hour. */
+    unusedPerHourMicros: string;
+    /** What its unused room has been charged so far. */
+    unusedChargedMicros: string;
+    /** Sandboxes in use now, up to what it holds; for standing room, read live. */
+    inUse: number;
+    peakInUse: number;
+    releasedPercent: number;
+    createdAt: string;
+    cancelledAt: string | null;
+};
+export type RoomBookingPage = {
+    items: RoomBooking[];
+    nextCursor: string | null;
+};
+export declare function reservations(t: Transport): {
+    /** Book room. Check `status`: a decline is a 200, not an error. */
+    create: (input: BookRoom, options?: RequestOptions) => Promise<RoomBooking>;
+    /** Keep standing room until you cancel it. Check `status`: a decline is a
+     *  200, not an error. */
+    keep: (input: KeepRoom, options?: RequestOptions) => Promise<RoomBooking>;
+    /** Change standing room in place. It moves or grows only when all of it
+     *  fits now; otherwise it throws `no_capacity` and nothing changes. */
+    update: (id: string, change: ChangeRoom, options?: RequestOptions) => Promise<RoomBooking>;
+    /** Bookings, newest first; pass `nextCursor` as `cursor` for the next page. */
+    list: (query?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: RequestOptions) => Promise<RoomBookingPage>;
+    get: (id: string, options?: RequestOptions) => Promise<RoomBooking>;
+    /** Give the room back. The booking comes back with status "cancelled". */
+    cancel: (id: string, options?: RequestOptions) => Promise<RoomBooking>;
+};

package/dist/products/reservations.js

@@ -0,0 +1,41 @@
+const iso = (time) => (time instanceof Date ? time.toISOString() : time);
+export function reservations(t) {
+    return {
+        /** Book room. Check `status`: a decline is a 200, not an error. */
+        create: (input, options) => t.json({
+            method: "POST",
+            path: "/v1/reservations",
+            body: { ...input, startsAt: iso(input.startsAt), endsAt: iso(input.endsAt) },
+            ...options,
+        }),
+        /** Keep standing room until you cancel it. Check `status`: a decline is a
+         *  200, not an error. */
+        keep: (input, options) => t.json({
+            method: "POST",
+            path: "/v1/reservations",
+            body: { ...input, standing: true },
+            ...options,
+        }),
+        /** Change standing room in place. It moves or grows only when all of it
+         *  fits now; otherwise it throws `no_capacity` and nothing changes. */
+        update: (id, change, options) => t.json({
+            method: "POST",
+            path: `/v1/reservations/${encodeURIComponent(id)}:update`,
+            body: change,
+            ...options,
+        }),
+        /** Bookings, newest first; pass `nextCursor` as `cursor` for the next page. */
+        list: (query = {}, options) => t.json({ method: "GET", path: "/v1/reservations", query, ...options }),
+        get: (id, options) => t.json({
+            method: "GET",
+            path: `/v1/reservations/${encodeURIComponent(id)}`,
+            ...options,
+        }),
+        /** Give the room back. The booking comes back with status "cancelled". */
+        cancel: (id, options) => t.json({
+            method: "DELETE",
+            path: `/v1/reservations/${encodeURIComponent(id)}`,
+            ...options,
+        }),
+    };
+}

package/dist/products/resources.d.ts

@@ -3,7 +3,8 @@ import type { RequestOptions, Transport } from "../transport.js";
 /** The five verbs every resource product shares (CLOUD.md section 4, "One
  * shape for every interface"; packages/cloud/src/api/resource-product.ts),
  * and following one to a state. A product builds its client on these and
- * adds only its own verbs. */
+ * adds only its own verbs. Plain request builders over Transport: nothing
+ * runs at import, no dependency beyond this package. */
 export type ResourceRecord = {
     id: string;
     state: string;