@usestatemachines/sdk 0.5.0 → 0.6.0

package/esm/extensions/credentials.js

@@ -0,0 +1,73 @@
+const HTTP_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+// Checked on the path part only. Covers protocol-relative starts, backslashes, control
+// characters and encoded dots, slashes and backslashes, including double encoding.
+const UNSAFE_PATH = /^\/\/|\\|%(?:25)*(?:2e|2f|5c)|\p{Cc}/iu;
+const OUTSIDE = 'Credentials.fetch only reaches paths under the app url.';
+export function bindCredentials(data, apis, fetcher) {
+    const base = URL.canParse(data.url) ? new URL(data.url) : null;
+    if (!base || !/^https?:$/.test(base.protocol) || base.search || base.hash) {
+        throw new TypeError('The credentials url is not a plain http(s) URL.');
+    }
+    if (!base.pathname.endsWith('/')) {
+        base.pathname += '/';
+    }
+    const send = async (path, init = {}) => {
+        const url = resolve(base, path);
+        const headers = new Headers(init.headers);
+        const actor = actorHeader(apis, `/${url.pathname.slice(base.pathname.length)}`, data.token);
+        // Ours go last so a caller header of the same name cannot replace them.
+        for (const [name, value] of Object.entries(data.headers)) {
+            headers.set(name, value);
+        }
+        if (actor) {
+            headers.set(actor.name, actor.value);
+        }
+        const request = new Request(url, { ...init, headers, redirect: 'manual' });
+        // Called on `globalThis` at use time: a stored unbound `fetch` throws "Illegal invocation" in Workers.
+        return fetcher ? fetcher(request) : globalThis.fetch(request);
+    };
+    return Object.defineProperty({ ...data }, 'fetch', {
+        value: send,
+        enumerable: false,
+    });
+}
+/** The longest `pathTemplate` that prefixes the path names the API; `{...}` matches one segment. */
+function actorHeader(apis, path, token) {
+    let match = null;
+    for (const api of apis) {
+        const pattern = api.pathTemplate
+            .replace(/\/+$/, '')
+            .split(/\{[^}]*\}/)
+            .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+            .join('[^/]+');
+        if (new RegExp(`^${pattern}(?:/|$)`).test(path) &&
+            api.pathTemplate.length > (match?.pathTemplate.length ?? -1)) {
+            match = api;
+        }
+    }
+    if (!match || !HTTP_TOKEN.test(match.actorHeader)) {
+        return null;
+    }
+    return match.actorHeader.toLowerCase() === 'authorization'
+        ? { name: 'Authorization', value: `Bearer ${token}` }
+        : { name: match.actorHeader, value: token };
+}
+function resolve(base, path) {
+    const pathPart = path.split(/[?#]/, 1)[0] ?? '';
+    if (UNSAFE_PATH.test(pathPart)) {
+        throw new TypeError(OUTSIDE);
+    }
+    // A leading `/` means the root of the app, not of the gateway.
+    const relative = path.startsWith('/') ? `.${path}` : path;
+    // `URL` errors carry the input, query included, so they are replaced rather than rethrown.
+    const url = URL.canParse(relative, base) ? new URL(relative, base) : null;
+    if (!url ||
+        url.origin !== base.origin ||
+        url.username ||
+        url.password ||
+        !url.pathname.startsWith(base.pathname) ||
+        UNSAFE_PATH.test(url.pathname)) {
+        throw new TypeError(OUTSIDE);
+    }
+    return url;
+}

package/esm/extensions/environment.d.ts

@@ -0,0 +1,25 @@
+import type { Environment as EnvironmentData } from '../models/environment.js';
+import type { Snapshot } from '../models/snapshot.js';
+import type { ConnectOptions, CreateSnapshotOptions, ResumeOptions, SignalOptions } from './client.js';
+import type { Credentials } from './credentials.js';
+/**
+ * An environment as the API returned it, with helpers bound to it. The helpers are not
+ * enumerable, so `JSON.stringify` and spreading see only the API's fields.
+ */
+export type Environment = EnvironmentData & EnvironmentHelpers;
+export interface EnvironmentHelpers {
+    /** Credentials for one app; `actorId` defaults to the app's default actor. */
+    connect(app: string, options?: ConnectOptions): Promise<Credentials>;
+    pause(options?: SignalOptions): Promise<Environment>;
+    /** Waits until `running` unless `wait` is false. */
+    resume(options?: ResumeOptions): Promise<Environment>;
+    delete(options?: SignalOptions): Promise<Environment>;
+    /** Reads the environment again. */
+    refresh(): Promise<Environment>;
+    readonly snapshots: {
+        /** Waits until `ready` unless `wait` is false. */
+        create(input?: {
+            name?: string | null;
+        }, options?: CreateSnapshotOptions): Promise<Snapshot>;
+    };
+}

package/esm/extensions/environment.js

@@ -0,0 +1 @@
+export {};

package/esm/extensions/errors.d.ts

@@ -1,96 +1,63 @@
-import type { Environment } from '../models/environment.js';
-import type { EnvironmentSnapshot } from '../models/environment-snapshot.js';
-import type { Code } from '../models/error-response.js';
-/** What `environments.start()` adds to the error it rethrows after a failed wait. */
-export interface StartFailure {
-    /** The environment the start created. */
-    readonly environmentId?: string;
-    /** Whether the stop request succeeded. Disposal may still be in progress. */
-    readonly stopped?: boolean;
-    /** Why the stop request failed, when it did. */
-    readonly stopError?: unknown;
-}
-interface Details {
+import type { Environment as EnvironmentData } from '../models/environment.js';
+import type { ErrorCode } from '../models/error.js';
+import type { Snapshot } from '../models/snapshot.js';
+export interface ErrorDetails {
     readonly message: string;
     readonly cause?: unknown;
+    /** The HTTP status, or `null` when no response arrived or the SDK refused the input. */
     readonly status: number | null;
-    readonly code: Code | null;
+    readonly code: ErrorCode | null;
     readonly requestId: string | null;
+    /** Messages keyed by the dotted path of the field they are about. */
     readonly fields: Record<string, string[]> | null;
-    readonly retryAfter: number | null;
-    readonly retryable: boolean;
-    readonly idempotencyKey?: string;
+    /** How long the server asked the client to wait. */
+    readonly retryAfterMs: number | null;
 }
 /**
- * Any failed API call: an error response, an invalid response, no response at all,
- * or input the SDK rejected before sending (`status` null for the last three). The
- * message never includes a response body.
+ * Any failed call: an error response, an invalid response, no response at all, or input
+ * the SDK refused before sending. The message never includes a response body.
  */
-export declare class StateMachinesError extends Error implements Details, StartFailure {
-    readonly name = "StateMachinesError";
-    readonly environmentId?: string;
-    readonly stopped?: boolean;
-    readonly stopError?: unknown;
-    /** Set when `snapshots.capture()` fails after the snapshot was created. */
-    readonly snapshotId?: string;
+export declare class StateMachinesError extends Error implements ErrorDetails {
+    readonly name: string;
     readonly status: number | null;
-    readonly code: Code | null;
+    readonly code: ErrorCode | null;
     readonly requestId: string | null;
     readonly fields: Record<string, string[]> | null;
-    /** Milliseconds the server asked the client to wait. */
-    readonly retryAfter: number | null;
-    /** Transient: a 502, 503 or 504, or the request never got a response. */
-    readonly retryable: boolean;
-    /** Set on create and capture failures. A replay with it returns the same result, so use it when the outcome is unknown. */
-    readonly idempotencyKey?: string;
-    /** Wraps any thrown value. Wrapping a `StateMachinesError` copies it, keeping its cause. */
-    constructor(error: unknown, extra?: {
-        idempotencyKey?: string;
-    });
+    readonly retryAfterMs: number | null;
+    constructor(details: ErrorDetails);
 }
-export declare function toStateMachinesError(error: unknown): StateMachinesError;
-export declare class EnvironmentFailedError extends Error implements StartFailure {
-    readonly environment: Environment;
+export declare function isTransient(error: StateMachinesError): boolean;
+/** An environment the wait cannot bring to the target status because it failed. */
+export declare class EnvironmentFailedError extends StateMachinesError {
+    readonly environment: EnvironmentData;
     readonly name = "EnvironmentFailedError";
-    readonly environmentId?: string;
-    readonly stopped?: boolean;
-    readonly stopError?: unknown;
-    constructor(environment: Environment);
-}
-export declare class DisposalIncompleteError extends Error {
-    readonly environment: Environment;
-    readonly name = "DisposalIncompleteError";
-    constructor(environment: Environment);
+    constructor(environment: EnvironmentData);
 }
-export declare class TimeoutError extends Error implements StartFailure {
+/** A snapshot that ended `failed` while the SDK waited for it. */
+export declare class SnapshotFailedError extends StateMachinesError {
+    readonly snapshot: Snapshot;
+    readonly name = "SnapshotFailedError";
+    constructor(snapshot: Snapshot);
+}
+/** The resource reached a status from which the awaited one needs a call of yours. */
+export declare class UnexpectedStatusError extends Error {
+    readonly resource: EnvironmentData | Snapshot;
+    readonly name = "UnexpectedStatusError";
+    readonly status: string;
+    constructor(resource: EnvironmentData | Snapshot, expected: string);
+}
+/** The wait passed its deadline. The work it waited for may still finish. */
+export declare class WaitTimeoutError extends Error {
+    readonly resource: EnvironmentData | Snapshot | null;
     readonly timeoutMs: number;
-    readonly environment: Environment | null;
-    readonly name = "TimeoutError";
-    readonly environmentId?: string;
-    readonly stopped?: boolean;
-    readonly stopError?: unknown;
-    constructor(timeoutMs: number, environment: Environment | null);
+    readonly name = "WaitTimeoutError";
+    constructor(resource: EnvironmentData | Snapshot | null, timeoutMs: number, id: string);
 }
 /** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
 export declare class CallerAbortedError extends Error {
     readonly name = "CallerAbortedError";
     constructor(reason: unknown);
 }
-/** A snapshot that ended `failed`, or was deleted, while the SDK waited for `ready`. */
-export declare class SnapshotFailedError extends Error {
-    readonly snapshot: EnvironmentSnapshot;
-    readonly name = "SnapshotFailedError";
-    readonly snapshotId: string;
-    readonly idempotencyKey?: string;
-    constructor(snapshot: EnvironmentSnapshot);
-}
-/** The wait for `ready` passed its deadline. The capture may still finish on the server. */
-export declare class SnapshotTimeoutError extends Error {
-    readonly timeoutMs: number;
-    readonly snapshot: EnvironmentSnapshot | null;
-    readonly snapshotId: string;
-    readonly name = "SnapshotTimeoutError";
-    readonly idempotencyKey?: string;
-    constructor(timeoutMs: number, snapshot: EnvironmentSnapshot | null, snapshotId: string);
-}
-export {};
+/** The SDK refused input before sending it, as the API would with `invalid_request`. */
+export declare function invalidInput(message: string, fields: Record<string, string[]>): StateMachinesError;
+export declare function toStateMachinesError(error: unknown): StateMachinesError;

package/esm/extensions/errors.js

@@ -1,11 +1,10 @@
-import { ErrorResponse } from '../models/errors/error-response.js';
+import { ErrorT } from '../models/errors/error.js';
 import { ConnectionError, RequestTimeoutError, } from '../models/errors/http-client-errors.js';
 import { ResponseValidationError } from '../models/errors/response-validation-error.js';
 import { StateMachinesHTTPError } from '../models/errors/state-machines-http-error.js';
 /**
- * Any failed API call: an error response, an invalid response, no response at all,
- * or input the SDK rejected before sending (`status` null for the last three). The
- * message never includes a response body.
+ * Any failed call: an error response, an invalid response, no response at all, or input
+ * the SDK refused before sending. The message never includes a response body.
  */
 export class StateMachinesError extends Error {
     name = 'StateMachinesError';
@@ -13,84 +12,159 @@ export class StateMachinesError extends Error {
     code;
     requestId;
     fields;
-    /** Milliseconds the server asked the client to wait. */
-    retryAfter;
-    /** Transient: a 502, 503 or 504, or the request never got a response. */
-    retryable;
-    /** Set on create and capture failures. A replay with it returns the same result, so use it when the outcome is unknown. */
-    idempotencyKey;
-    /** Wraps any thrown value. Wrapping a `StateMachinesError` copies it, keeping its cause. */
-    constructor(error, extra = {}) {
-        const details = error instanceof StateMachinesError ? error : describe(error);
+    retryAfterMs;
+    constructor(details) {
         super(details.message, details.cause === undefined ? undefined : { cause: details.cause });
         this.status = details.status;
         this.code = details.code;
         this.requestId = details.requestId;
         this.fields = details.fields;
-        this.retryAfter = details.retryAfter;
-        this.retryable = details.retryable;
-        const idempotencyKey = extra.idempotencyKey ?? details.idempotencyKey;
-        if (idempotencyKey !== undefined) {
-            this.idempotencyKey = idempotencyKey;
-        }
+        this.retryAfterMs = details.retryAfterMs;
     }
 }
-export function toStateMachinesError(error) {
-    return error instanceof StateMachinesError
-        ? error
-        : new StateMachinesError(error);
+// A 502, 503 or 504, or a request that never got a response: the poller tries again.
+const transient = new WeakSet();
+export function isTransient(error) {
+    return transient.has(error);
 }
-// Matches the generated retry codes (.speakeasy/overlay.yaml): Cloudflare answers 502 and 504
-// when the API origin is unreachable, and the API answers 503 when it is saturated.
-const retryableStatuses = new Set([502, 503, 504]);
-function describe(error) {
-    const empty = {
-        status: null,
-        code: null,
-        requestId: null,
-        fields: null,
-        retryAfter: null,
-        retryable: false,
-    };
+function transientError(details) {
+    const error = new StateMachinesError(details);
+    transient.add(error);
+    return error;
+}
+const noResponse = {
+    status: null,
+    code: null,
+    requestId: null,
+    fields: null,
+    retryAfterMs: null,
+};
+/** An environment the wait cannot bring to the target status because it failed. */
+export class EnvironmentFailedError extends StateMachinesError {
+    environment;
+    name = 'EnvironmentFailedError';
+    constructor(environment) {
+        const failure = environment.failure;
+        super({
+            ...noResponse,
+            message: failure
+                ? `Environment ${environment.id} failed: ${failure.message} (${failure.code}, app ${failure.app}).`
+                : `Environment ${environment.id} failed.`,
+        });
+        this.environment = environment;
+    }
+}
+/** A snapshot that ended `failed` while the SDK waited for it. */
+export class SnapshotFailedError extends StateMachinesError {
+    snapshot;
+    name = 'SnapshotFailedError';
+    constructor(snapshot) {
+        const failure = snapshot.failure;
+        super({
+            ...noResponse,
+            message: failure
+                ? `Snapshot ${snapshot.id} failed: ${failure.message} (${failure.code}).`
+                : `Snapshot ${snapshot.id} failed.`,
+        });
+        this.snapshot = snapshot;
+    }
+}
+/** The resource reached a status from which the awaited one needs a call of yours. */
+export class UnexpectedStatusError extends Error {
+    resource;
+    name = 'UnexpectedStatusError';
+    status;
+    constructor(resource, expected) {
+        super(`${resource.id} is ${resource.status}; it cannot become ${expected} without another call.`);
+        this.resource = resource;
+        this.status = resource.status;
+    }
+}
+/** The wait passed its deadline. The work it waited for may still finish. */
+export class WaitTimeoutError extends Error {
+    resource;
+    timeoutMs;
+    name = 'WaitTimeoutError';
+    constructor(resource, timeoutMs, id) {
+        super(`Timed out after ${timeoutMs} ms waiting for ${id}.`);
+        this.resource = resource;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
+export class CallerAbortedError extends Error {
+    name = 'CallerAbortedError';
+    constructor(reason) {
+        super('The caller aborted the request.', { cause: reason });
+    }
+}
+/** The SDK refused input before sending it, as the API would with `invalid_request`. */
+export function invalidInput(message, fields) {
+    return new StateMachinesError({
+        ...noResponse,
+        message,
+        code: 'invalid_request',
+        fields,
+    });
+}
+export function toStateMachinesError(error) {
+    if (error instanceof StateMachinesError) {
+        return error;
+    }
     if (error instanceof StateMachinesHTTPError) {
-        return describeResponse(error);
+        return fromResponse(error);
     }
     if (error instanceof SyntaxError) {
         // A malformed JSON body; V8 quotes the body in the parser's message.
-        return { ...empty, message: 'Invalid response from the State API.' };
+        return new StateMachinesError({
+            ...noResponse,
+            message: 'Invalid response from the State Machines API.',
+        });
     }
     if (error instanceof Error) {
         // A `TimeoutError` DOMException is an attempt timeout that fired while the body was read.
         const retryable = error instanceof ConnectionError ||
             error instanceof RequestTimeoutError ||
             error.name === 'TimeoutError';
-        return { ...empty, message: error.message, cause: error, retryable };
+        const details = { ...noResponse, message: error.message, cause: error };
+        return retryable
+            ? transientError(details)
+            : new StateMachinesError(details);
     }
-    return { ...empty, message: String(error), cause: error };
+    return new StateMachinesError({
+        ...noResponse,
+        message: String(error),
+        cause: error,
+    });
 }
-function describeResponse(error) {
+// The generated retry codes (.speakeasy/overlay.yaml): Cloudflare answers 502 and 504 when
+// the API origin is unreachable, and the API answers 503 when it is saturated.
+const retryableStatuses = new Set([502, 503, 504]);
+function fromResponse(error) {
     const status = error.statusCode;
-    const body = error instanceof ErrorResponse ? error.error : undefined;
-    const success = status >= 200 && status < 300;
-    let message = `HTTP ${status} from the State API`;
-    if (success || error instanceof ResponseValidationError) {
-        message = `Invalid response from the State API (HTTP ${status})`;
+    const body = error instanceof ErrorT ? error.error : undefined;
+    let message = `HTTP ${status} from the State Machines API`;
+    if ((status >= 200 && status < 300) ||
+        error instanceof ResponseValidationError) {
+        message = `Invalid response from the State Machines API (HTTP ${status})`;
     }
     else if (body?.message) {
         message = body.message;
     }
-    return {
+    // No cause: generated HTTP errors hold the request, with its token, and the raw body.
+    const details = {
         message,
-        // No cause: generated HTTP errors hold the request (with the API key) and the raw body.
         status,
         code: body?.code ?? null,
-        requestId: body?.requestId ?? error.headers.get('x-request-id'),
+        requestId: body?.requestId ?? error.headers.get('request-id'),
         fields: body?.fields ?? null,
-        retryAfter: retryAfter(error.headers),
-        retryable: retryableStatuses.has(status),
+        retryAfterMs: retryAfterMs(error.headers),
     };
+    return retryableStatuses.has(status)
+        ? transientError(details)
+        : new StateMachinesError(details);
 }
-function retryAfter(headers) {
+function retryAfterMs(headers) {
     const value = headers.get('retry-after')?.trim();
     if (!value) {
         return null;
@@ -102,62 +176,3 @@ function retryAfter(headers) {
     const date = Date.parse(value);
     return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
 }
-export class EnvironmentFailedError extends Error {
-    environment;
-    name = 'EnvironmentFailedError';
-    constructor(environment) {
-        super(`Environment ${environment.id} is ${environment.status} (${environment.stopReason ?? 'no stop reason'}).`);
-        this.environment = environment;
-    }
-}
-export class DisposalIncompleteError extends Error {
-    environment;
-    name = 'DisposalIncompleteError';
-    constructor(environment) {
-        super(`Environment ${environment.id} ended, but not every sandbox was confirmed disposed.`);
-        this.environment = environment;
-    }
-}
-export class TimeoutError extends Error {
-    timeoutMs;
-    environment;
-    name = 'TimeoutError';
-    constructor(timeoutMs, environment) {
-        super(`Timed out after ${timeoutMs} ms.`);
-        this.timeoutMs = timeoutMs;
-        this.environment = environment;
-    }
-}
-/** Thrown from a hook so the generated retry loop stops, whatever the abort reason. */
-export class CallerAbortedError extends Error {
-    name = 'CallerAbortedError';
-    constructor(reason) {
-        super('The caller aborted the request.', { cause: reason });
-    }
-}
-/** A snapshot that ended `failed`, or was deleted, while the SDK waited for `ready`. */
-export class SnapshotFailedError extends Error {
-    snapshot;
-    name = 'SnapshotFailedError';
-    snapshotId;
-    constructor(snapshot) {
-        super(snapshot.status === 'failed'
-            ? `Snapshot ${snapshot.id} is failed (${snapshot.errorCode ?? 'no error code'}).`
-            : `Snapshot ${snapshot.id} was deleted.`);
-        this.snapshot = snapshot;
-        this.snapshotId = snapshot.id;
-    }
-}
-/** The wait for `ready` passed its deadline. The capture may still finish on the server. */
-export class SnapshotTimeoutError extends Error {
-    timeoutMs;
-    snapshot;
-    snapshotId;
-    name = 'SnapshotTimeoutError';
-    constructor(timeoutMs, snapshot, snapshotId) {
-        super(`Timed out after ${timeoutMs} ms waiting for snapshot ${snapshotId}.`);
-        this.timeoutMs = timeoutMs;
-        this.snapshot = snapshot;
-        this.snapshotId = snapshotId;
-    }
-}

package/esm/extensions/index.d.ts

@@ -1,13 +1,8 @@
-export type { Fetcher, HTTPClientOptions } from '../lib/http.js';
-export { HTTPClient } from '../lib/http.js';
-export { ConnectionError, ErrorResponse, HTTPClientError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, ResponseValidationError, SDKValidationError, StateMachinesHTTPError, UnexpectedClientError, UnexpectedResponseError, } from '../models/errors/index.js';
-export type { ApiProfile, App, AppInstanceSnapshot, Catalog, Connection as ConnectionDetails, ConnectionSecret, CreateEnvironmentInput, Credential, Environment, EnvironmentApp, EnvironmentRequest, EnvironmentRequestDetail, EnvironmentRequestStats, EnvironmentSnapshot, Event, EventPage, Release, ReleaseActor, Workspace, } from '../models/index.js';
-export { Code as ErrorCode, Disposal, EnvironmentStatus, StopReason, } from '../models/index.js';
-export { Status as EnvironmentListStatus } from '../models/operations/list-environments.js';
-export type { AppInput, EnvironmentInput, SnapshotEnvironmentInput, } from './apps.js';
-export type { CallOptions, CaptureInput, CaptureOptions, ConnectOptions, CreateOptions, LifecycleOptions, ListEnvironmentsQuery, ListSnapshotsQuery, Page, StartOptions, StateMachinesOptions, } from './client.js';
+export type { Actor, Api, App, AuditEvent, BodyPreview, CreateEnvironment, CreateEnvironmentApp, EnvironmentApp, EnvironmentFailure, EnvironmentFailureCode, EnvironmentStatus, ErrorCode, Me, Permission, Principal, RequestDetail, RequestStats, RequestT as Request, Snapshot, SnapshotStatus, Version, Workspace, } from '../models/index.js';
+export type { ConnectOptions, CreateEnvironmentOptions, CreateSnapshotOptions, ListAuditEventsQuery, ListEnvironmentsQuery, ListRequestsQuery, ListSnapshotsQuery, ListWorkspacesQuery, Page, PageQuery, RequestStatsQuery, ResumeOptions, SignalOptions, StateMachinesOptions, } from './client.js';
 export { StateMachines } from './client.js';
-export { Connection, formatActorHeader } from './connection.js';
-export { DisposalIncompleteError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, } from './errors.js';
-export { RunningEnvironment } from './running-environment.js';
+export type { Credentials } from './credentials.js';
+export type { Environment, EnvironmentHelpers } from './environment.js';
+export { EnvironmentFailedError, SnapshotFailedError, StateMachinesError, UnexpectedStatusError, WaitTimeoutError, } from './errors.js';
 export type { WaitOptions } from './wait.js';
+export { parseEnvironmentYaml } from './yaml.js';

package/esm/extensions/index.js

@@ -1,8 +1,3 @@
-export { HTTPClient } from '../lib/http.js';
-export { ConnectionError, ErrorResponse, HTTPClientError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, ResponseValidationError, SDKValidationError, StateMachinesHTTPError, UnexpectedClientError, UnexpectedResponseError, } from '../models/errors/index.js';
-export { Code as ErrorCode, Disposal, EnvironmentStatus, StopReason, } from '../models/index.js';
-export { Status as EnvironmentListStatus } from '../models/operations/list-environments.js';
 export { StateMachines } from './client.js';
-export { Connection, formatActorHeader } from './connection.js';
-export { DisposalIncompleteError, EnvironmentFailedError, SnapshotFailedError, SnapshotTimeoutError, StateMachinesError, TimeoutError, } from './errors.js';
-export { RunningEnvironment } from './running-environment.js';
+export { EnvironmentFailedError, SnapshotFailedError, StateMachinesError, UnexpectedStatusError, WaitTimeoutError, } from './errors.js';
+export { parseEnvironmentYaml } from './yaml.js';

package/esm/extensions/wait.d.ts

@@ -1,29 +1,28 @@
-import type { Environment } from '../models/environment.js';
-import type { EnvironmentSnapshot } from '../models/environment-snapshot.js';
-export interface WaitOptions {
-    /** Overall deadline for the wait. Defaults to 10 minutes. */
+import type { Environment as EnvironmentData } from '../models/environment.js';
+import type { EnvironmentStatus } from '../models/environment-status.js';
+import type { Snapshot } from '../models/snapshot.js';
+import type { SnapshotStatus } from '../models/snapshot-status.js';
+export interface WaitOptions<Status extends string> {
+    status: Status;
+    /** Deadline for the whole wait. Defaults to 10 minutes. */
     timeoutMs?: number;
     /** Aborting rejects the wait with `signal.reason`. */
     signal?: AbortSignal;
 }
-type Read<T> = (signal: AbortSignal) => Promise<T>;
-type Decide<T> = (value: T) => boolean;
 export declare const defaultTimeoutMs = 600000;
-export declare function poll(read: Read<Environment>, done: Decide<Environment>, options?: WaitOptions): Promise<Environment>;
+export type KnownEnvironmentStatus = (typeof EnvironmentStatus)[keyof typeof EnvironmentStatus];
+export type KnownSnapshotStatus = (typeof SnapshotStatus)[keyof typeof SnapshotStatus];
+/** True at the target; false while the target is still reachable; throws otherwise. */
+export declare function environmentAt(target: KnownEnvironmentStatus): (environment: EnvironmentData) => boolean;
+export declare function snapshotAt(target: KnownSnapshotStatus): (snapshot: Snapshot) => boolean;
 /**
- * Reads until `done` returns true. `done` throws to end the wait with a failure.
+ * Reads until `done` returns true; `done` throws to end the wait with a failure.
  * Transient read failures are retried with backoff until the deadline.
  */
-export declare function pollUntil<T>(read: Read<T>, done: Decide<T>, options: WaitOptions | undefined, timeout: (timeoutMs: number, last: T | null) => Error): Promise<T>;
-/** Resolves on `running`. Never suspends or stops the environment. */
-export declare function ready(environment: Environment): boolean;
-/** Resolves on `suspended`, when the environment can resume. */
-export declare function suspended(environment: Environment): boolean;
-/** Resolves once the environment ended and every app's sandbox is confirmed disposed. */
-export declare function disposed(environment: Environment): boolean;
-/** Resolves on `ready`. A failed or deleted snapshot ends the wait. */
-export declare function snapshotReady(snapshot: EnvironmentSnapshot): boolean;
+export declare function poll<T extends EnvironmentData | Snapshot>(id: string, read: (signal: AbortSignal) => Promise<T>, done: (value: T) => boolean, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<T>;
 /** 1 s × 1.5ⁿ, capped at 5 s, with ±20% jitter. */
 export declare function backoff(attempt: number): number;
 export declare function sleep(ms: number, signal: AbortSignal | null | undefined): Promise<void>;
-export {};