@shardflux/sdk 0.5.0

package/dist/client.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Shardflux SDK entry point (TEMPLATES.md "Developer interface"):
+ *
+ *   const cloud = new Shardflux({ apiKey, baseUrl });
+ *   const workspace = await cloud.workspaces.open({ key, template });
+ *   await agent.run({ input, tools: workspaceTools(workspace) });
+ *
+ * Types are generated from the application API and cell gateway OpenAPI documents.
+ */
+import type { components, operations } from './generated/app-api.js';
+import { ShardfluxApiError } from './errors.js';
+import { HttpClient } from './http.js';
+import type { ToolName } from './tokens.js';
+import { Workspace } from './workspace.js';
+import { AuditApi } from './audit.js';
+import { EgressPolicyApi } from './egress.js';
+import { SecretsApi } from './secrets.js';
+import { TemplatesApi } from './templates.js';
+import { UsageApi } from './usage.js';
+import { VolumesApi } from './volumes.js';
+export type WorkspaceView = components['schemas']['Workspace'];
+export type Operation = components['schemas']['Operation'];
+type JsonOf<R> = R extends {
+    content: {
+        'application/json': infer T;
+    };
+} ? T : never;
+type Ok<Op> = Op extends {
+    responses: infer R;
+} ? {
+    [K in keyof R]: K extends 200 | 201 | 202 ? JsonOf<R[K]> : never;
+}[keyof R] : never;
+export type OpenResponse = Ok<operations['postV1WorkspacesOpen']>;
+export type AgentSession = Ok<operations['getV1WorkspacesWorkspaceIdAgentSessions']>['data'][number];
+export type Entitlements = Ok<operations['getV1OrganizationsOrganizationIdEntitlements']>;
+export type Me = Ok<operations['getV1Me']>;
+/** The versioned plan catalog admission enforces (public). */
+export type BillingCatalog = Ok<operations['getV1BillingCatalog']>;
+/** Billing state, subscription and effective plan of an organization. */
+export type BillingSubscription = Ok<operations['getV1OrganizationsOrganizationIdBillingSubscription']>;
+/** Browser (session) surface, for first-party frontends: Checkout intent, portal link and invoices. */
+export type CheckoutSession = Ok<operations['postApiV1OrganizationsOrganizationIdBillingCheckoutSessions']>;
+export type PortalSession = Ok<operations['postApiV1OrganizationsOrganizationIdBillingPortalSessions']>;
+export type InvoicePage = Ok<operations['getApiV1OrganizationsOrganizationIdBillingInvoices']>;
+export type Invoice = InvoicePage['data'][number];
+export interface ShardfluxOptions {
+    /** Project API key: sfk_<key_id>_<secret>. */
+    apiKey: string;
+    /** Default https://api.shardflux.dev (override with `baseUrl`). */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    userAgent?: string;
+    /** Per-request timeout (ms), default 30 s. */
+    timeoutMs?: number;
+    /** Retries of safe/idempotent requests on transient failures, default 2. */
+    maxRetries?: number;
+    /** Injected for tests; defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface Caps {
+    cpu_millis?: number;
+    memory_mib?: number;
+    disk_gib?: number;
+}
+export interface WaitOptions {
+    /** Give up waiting after this long (default 300 000 ms); the operation continues server side. */
+    timeoutMs?: number;
+    /** First poll delay (default 250 ms); doubles up to `maxPollIntervalMs` with jitter. */
+    pollIntervalMs?: number;
+    maxPollIntervalMs?: number;
+    signal?: AbortSignal;
+}
+export interface OpenParams {
+    key: string;
+    template: string;
+    caps?: Caps;
+    /** Browser/session principals only; API keys use their own project. */
+    projectId?: string;
+    /** Attribution label for tool tokens obtained through this workspace object. */
+    agentLabel?: string;
+    /** Tools to request in tool tokens (subset of the key's permissions); default all permitted. */
+    tools?: ToolName[];
+    /** `false`: return immediately (possibly not ready). Default: wait until ready. */
+    wait?: false | WaitOptions;
+    /** Defaults to a fresh key per open() call so transport retries replay instead of duplicating. */
+    idempotencyKey?: string;
+}
+export interface ListParams {
+    state?: WorkspaceView['observed_state'];
+    desiredState?: WorkspaceView['desired_state'];
+    keyPrefix?: string;
+    projectId?: string;
+    organizationId?: string;
+    includeDeleted?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+export interface Page<T> {
+    data: T[];
+    nextCursor: string | null;
+}
+/** Internal context shared with Workspace objects. */
+export interface ClientContext {
+    http: HttpClient;
+    authorization: string;
+    fetch: typeof fetch;
+    userAgent: string;
+    sleep: (ms: number) => Promise<void>;
+    workspaces: WorkspacesApi;
+}
+export declare class WorkspacesApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /**
+     * Opens a workspace by key: creates it from the template's latest published version on first
+     * use, reconnects (or resumes) afterwards; never resets an existing workspace. Waits until it is
+     * ready unless `wait: false`; on timeout throws OperationTimeoutError carrying the operation id.
+     */
+    open(params: OpenParams): Promise<Workspace>;
+    /**
+     * Polls GET /v1/operations/{id} with bounded exponential backoff (+-20 % jitter) until it
+     * succeeds (resolves), fails or is canceled (OperationFailedError), or `timeoutMs` passes
+     * (OperationTimeoutError; the operation keeps running and can be awaited again).
+     */
+    waitForOperation(operationId: string, opts?: WaitOptions): Promise<Operation>;
+    /** One operation (GET /v1/operations/{id}); lifecycle operations stay pollable after a workspace is deleted. */
+    getOperation(operationId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Operation>;
+    get(workspaceId: string, opts?: {
+        agentLabel?: string;
+        tools?: ToolName[];
+    }): Promise<Workspace>;
+    list(params?: ListParams): Promise<Page<Workspace>>;
+    /** Iterates every page. */
+    listAll(params?: Omit<ListParams, 'cursor'>): AsyncGenerator<Workspace>;
+    /** Tombstones the workspace now (tool access revoked); storage cleanup happens asynchronously. */
+    delete(workspaceId: string, opts?: {
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    suspend(workspaceId: string, opts?: {
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    resume(workspaceId: string, opts?: {
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    snapshot(workspaceId: string, opts?: {
+        label?: string;
+        idempotencyKey?: string;
+    }): Promise<Operation>;
+    fork(workspaceId: string, target: {
+        key: string;
+        caps?: Caps;
+    }, opts?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        operation: Operation;
+        workspace: Workspace;
+    }>;
+    operations(workspaceId: string, params?: {
+        limit?: number;
+        cursor?: string;
+        state?: Operation['state'];
+        kind?: Operation['kind'];
+    }): Promise<Page<Operation>>;
+    agentSessions(workspaceId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<AgentSession>>;
+}
+/**
+ * Read-only billing for API keys: the plan catalog and the organization's subscription/billing
+ * state. Purchases and the Stripe portal are owner/billing-member actions in the browser
+ * (session) surface; an open or resume refused after a payment grace period throws
+ * ShardfluxApiError { code: 'entitlement_required', details.reason: 'payment_past_due' | 'unpaid' }.
+ */
+export declare class BillingApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    catalog(): Promise<BillingCatalog>;
+    subscription(organizationId: string): Promise<BillingSubscription>;
+}
+/** The public plan catalog without an API key (pricing pages, CLIs before sign-up). */
+export declare function fetchBillingCatalog(opts?: {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<BillingCatalog>;
+export declare class Shardflux {
+    #private;
+    readonly workspaces: WorkspacesApi;
+    readonly billing: BillingApi;
+    /** Usage, allowances, estimates, grants/leases and spend (Phase 9). */
+    readonly usage: UsageApi;
+    /** Template registry and custom template builds. */
+    readonly templates: TemplatesApi;
+    /** Customer secrets (metadata only; values are write-only and resolved by the cell at session start). */
+    readonly secrets: SecretsApi;
+    /** Project/workspace outbound allowlists (stored and versioned; host enforcement state is reported). */
+    readonly egress: EgressPolicyApi;
+    /** Organization audit trail (owner/admin; API keys are refused with 403). */
+    readonly audit: AuditApi;
+    /** Shared volumes: persistent storage attached to workspaces at a mount path (contracts §15). */
+    readonly volumes: VolumesApi;
+    constructor(opts: ShardfluxOptions);
+    /** The authenticated principal (the API key, its organization and project). */
+    me(): Promise<Me>;
+    entitlements(organizationId: string): Promise<Entitlements>;
+    /** Raw access to any /v1 endpoint with the SDK's authentication and error handling. */
+    request<T>(method: string, path: string, init?: Parameters<HttpClient['json']>[2]): Promise<T>;
+}
+export { ShardfluxApiError };

package/dist/client.js

@@ -0,0 +1,238 @@
+import { OperationFailedError, OperationTimeoutError, ShardfluxApiError } from "./errors.js";
+import { HttpClient, SDK_VERSION, defaultSleep, randomId } from "./http.js";
+import { Workspace } from "./workspace.js";
+import { AuditApi } from "./audit.js";
+import { EgressPolicyApi } from "./egress.js";
+import { SecretsApi } from "./secrets.js";
+import { TemplatesApi } from "./templates.js";
+import { UsageApi } from "./usage.js";
+import { VolumesApi } from "./volumes.js";
+const TERMINAL = new Set(['succeeded', 'failed', 'canceled']);
+/** Races the injected sleep against the signal (the injected sleep itself may not be abortable). */
+function abortableSleep(sleep, ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            signal.removeEventListener('abort', done);
+            resolve();
+        };
+        signal.addEventListener('abort', done, { once: true });
+        void sleep(ms).then(done, done);
+    });
+}
+export class WorkspacesApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    get #http() {
+        return this.#ctx().http;
+    }
+    get #auth() {
+        return this.#ctx().authorization;
+    }
+    #wrap(view, opts = {}) {
+        return new Workspace(this.#ctx(), view, opts);
+    }
+    /**
+     * Opens a workspace by key: creates it from the template's latest published version on first
+     * use, reconnects (or resumes) afterwards; never resets an existing workspace. Waits until it is
+     * ready unless `wait: false`; on timeout throws OperationTimeoutError carrying the operation id.
+     */
+    async open(params) {
+        const body = { key: params.key, template: params.template };
+        if (params.caps !== undefined)
+            body.caps = params.caps;
+        if (params.projectId !== undefined)
+            body.project_id = params.projectId;
+        if (params.agentLabel !== undefined)
+            body.agent_label = params.agentLabel;
+        if (params.tools !== undefined)
+            body.tools = params.tools;
+        const res = await this.#http.jsonWithStatus('POST', '/v1/workspaces/open', { json: body, idempotencyKey: params.idempotencyKey ?? randomId('open-') }, this.#auth);
+        const wrapOpts = { agentLabel: params.agentLabel, tools: params.tools, token: res.body.tool_token };
+        if (res.status === 200 || params.wait === false || res.body.operation === null)
+            return this.#wrap(res.body.workspace, wrapOpts);
+        await this.waitForOperation(res.body.operation.id, params.wait ?? {});
+        return this.#wrap(await this.#getView(res.body.workspace.id), { agentLabel: params.agentLabel, tools: params.tools });
+    }
+    /**
+     * Polls GET /v1/operations/{id} with bounded exponential backoff (+-20 % jitter) until it
+     * succeeds (resolves), fails or is canceled (OperationFailedError), or `timeoutMs` passes
+     * (OperationTimeoutError; the operation keeps running and can be awaited again).
+     */
+    async waitForOperation(operationId, opts = {}) {
+        const { sleep } = this.#ctx();
+        const timeoutMs = opts.timeoutMs ?? 300_000;
+        const maxInterval = opts.maxPollIntervalMs ?? 5_000;
+        let interval = opts.pollIntervalMs ?? 250;
+        const started = Date.now();
+        const aborted = () => (opts.signal?.reason instanceof Error ? opts.signal.reason : new Error('aborted'));
+        for (;;) {
+            if (opts.signal?.aborted)
+                throw aborted();
+            const operation = await this.getOperation(operationId, opts.signal ? { signal: opts.signal } : {});
+            if (operation.state === 'succeeded')
+                return operation;
+            if (TERMINAL.has(operation.state))
+                throw new OperationFailedError(operation);
+            const waited = Date.now() - started;
+            if (waited >= timeoutMs)
+                throw new OperationTimeoutError(operation, waited);
+            const jitter = interval * 0.2 * (Math.random() * 2 - 1);
+            const delay = Math.max(10, Math.min(interval + jitter, timeoutMs - waited));
+            // The wait itself is abortable: a signal ends it at once instead of after the sleep.
+            await (opts.signal ? abortableSleep(sleep, delay, opts.signal) : sleep(delay));
+            if (opts.signal?.aborted)
+                throw aborted();
+            interval = Math.min(maxInterval, interval * 2);
+        }
+    }
+    /** One operation (GET /v1/operations/{id}); lifecycle operations stay pollable after a workspace is deleted. */
+    async getOperation(operationId, opts = {}) {
+        const { operation } = await this.#http.json('GET', `/v1/operations/${encodeURIComponent(operationId)}`, opts.signal ? { signal: opts.signal } : {}, this.#auth);
+        return operation;
+    }
+    async #getView(workspaceId) {
+        return this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}`, {}, this.#auth);
+    }
+    async get(workspaceId, opts = {}) {
+        return this.#wrap(await this.#getView(workspaceId), opts);
+    }
+    async list(params = {}) {
+        const page = await this.#http.json('GET', '/v1/workspaces', {
+            query: {
+                state: params.state,
+                desired_state: params.desiredState,
+                key_prefix: params.keyPrefix,
+                project_id: params.projectId,
+                organization_id: params.organizationId,
+                include_deleted: params.includeDeleted,
+                limit: params.limit,
+                cursor: params.cursor,
+            },
+        }, this.#auth);
+        return { data: page.data.map((v) => this.#wrap(v)), nextCursor: page.next_cursor };
+    }
+    /** Iterates every page. */
+    async *listAll(params = {}) {
+        let cursor;
+        do {
+            const page = await this.list({ ...params, ...(cursor ? { cursor } : {}) });
+            yield* page.data;
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor);
+    }
+    async #lifecycle(method, path, json, idempotencyKey) {
+        return this.#http.json(method, path, { ...(json === undefined ? {} : { json }), idempotencyKey: idempotencyKey ?? randomId('op-') }, this.#auth);
+    }
+    /** Tombstones the workspace now (tool access revoked); storage cleanup happens asynchronously. */
+    async delete(workspaceId, opts = {}) {
+        return (await this.#lifecycle('DELETE', `/v1/workspaces/${encodeURIComponent(workspaceId)}`, undefined, opts.idempotencyKey)).operation;
+    }
+    async suspend(workspaceId, opts = {}) {
+        return (await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/suspend`, undefined, opts.idempotencyKey)).operation;
+    }
+    async resume(workspaceId, opts = {}) {
+        return (await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/resume`, undefined, opts.idempotencyKey)).operation;
+    }
+    async snapshot(workspaceId, opts = {}) {
+        return (await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/snapshot`, opts.label === undefined ? {} : { label: opts.label }, opts.idempotencyKey)).operation;
+    }
+    async fork(workspaceId, target, opts = {}) {
+        const out = await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/fork`, target, opts.idempotencyKey);
+        return { operation: out.operation, workspace: this.#wrap(out.workspace) };
+    }
+    async operations(workspaceId, params = {}) {
+        const page = await this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}/operations`, { query: { limit: params.limit, cursor: params.cursor, state: params.state, kind: params.kind } }, this.#auth);
+        return { data: page.data, nextCursor: page.next_cursor };
+    }
+    async agentSessions(workspaceId, params = {}) {
+        const page = await this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}/agent-sessions`, { query: { limit: params.limit, cursor: params.cursor } }, this.#auth);
+        return { data: page.data, nextCursor: page.next_cursor };
+    }
+}
+/**
+ * Read-only billing for API keys: the plan catalog and the organization's subscription/billing
+ * state. Purchases and the Stripe portal are owner/billing-member actions in the browser
+ * (session) surface; an open or resume refused after a payment grace period throws
+ * ShardfluxApiError { code: 'entitlement_required', details.reason: 'payment_past_due' | 'unpaid' }.
+ */
+export class BillingApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    catalog() {
+        return this.#ctx().http.json('GET', '/v1/billing/catalog', {}, this.#ctx().authorization);
+    }
+    subscription(organizationId) {
+        return this.#ctx().http.json('GET', `/v1/organizations/${encodeURIComponent(organizationId)}/billing/subscription`, {}, this.#ctx().authorization);
+    }
+}
+/** The public plan catalog without an API key (pricing pages, CLIs before sign-up). */
+export async function fetchBillingCatalog(opts = {}) {
+    const http = new HttpClient({
+        baseUrl: opts.baseUrl ?? 'https://api.shardflux.dev',
+        fetch: opts.fetch ?? fetch,
+        userAgent: `shardflux-sdk-ts/${SDK_VERSION}`,
+        timeoutMs: opts.timeoutMs ?? 30_000,
+        maxRetries: 2,
+        source: 'api',
+        sleep: defaultSleep,
+    });
+    return http.json('GET', '/v1/billing/catalog');
+}
+export class Shardflux {
+    workspaces;
+    billing;
+    /** Usage, allowances, estimates, grants/leases and spend (Phase 9). */
+    usage;
+    /** Template registry and custom template builds. */
+    templates;
+    /** Customer secrets (metadata only; values are write-only and resolved by the cell at session start). */
+    secrets;
+    /** Project/workspace outbound allowlists (stored and versioned; host enforcement state is reported). */
+    egress;
+    /** Organization audit trail (owner/admin; API keys are refused with 403). */
+    audit;
+    /** Shared volumes: persistent storage attached to workspaces at a mount path (contracts §15). */
+    volumes;
+    #ctx;
+    constructor(opts) {
+        if (!/^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/.test(opts.apiKey))
+            throw new Error('apiKey must be a Shardflux project key (sfk_<key_id>_<secret>)');
+        const f = opts.fetch ?? fetch;
+        const userAgent = opts.userAgent ?? `shardflux-sdk-ts/${SDK_VERSION}`;
+        const sleep = opts.sleep ?? defaultSleep;
+        this.workspaces = new WorkspacesApi(() => this.#ctx);
+        this.billing = new BillingApi(() => this.#ctx);
+        this.usage = new UsageApi(() => this.#ctx);
+        this.templates = new TemplatesApi(() => this.#ctx);
+        this.secrets = new SecretsApi(() => this.#ctx);
+        this.egress = new EgressPolicyApi(() => this.#ctx);
+        this.audit = new AuditApi(() => this.#ctx);
+        this.volumes = new VolumesApi(() => this.#ctx);
+        this.#ctx = {
+            http: new HttpClient({ baseUrl: opts.baseUrl ?? 'https://api.shardflux.dev', fetch: f, userAgent, timeoutMs: opts.timeoutMs ?? 30_000, maxRetries: opts.maxRetries ?? 2, source: 'api', sleep }),
+            authorization: `Bearer ${opts.apiKey}`,
+            fetch: f,
+            userAgent,
+            sleep,
+            workspaces: this.workspaces,
+        };
+    }
+    /** The authenticated principal (the API key, its organization and project). */
+    me() {
+        return this.#ctx.http.json('GET', '/v1/me', {}, this.#ctx.authorization);
+    }
+    entitlements(organizationId) {
+        return this.#ctx.http.json('GET', `/v1/organizations/${encodeURIComponent(organizationId)}/entitlements`, {}, this.#ctx.authorization);
+    }
+    /** Raw access to any /v1 endpoint with the SDK's authentication and error handling. */
+    request(method, path, init = {}) {
+        return this.#ctx.http.json(method, path, init, this.#ctx.authorization);
+    }
+}
+export { ShardfluxApiError };

package/dist/egress.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Egress (outbound network) policies over the application API (/v1). Types are
+ * written by hand.
+ *
+ * Policies are stored and versioned by the API; the host enforces them. Always
+ * check `enforcement.state` on a workspace: `not_enforced` until the cell/host
+ * acknowledges the current effective version for the workspace's current
+ * ownership epoch. Pass `ifMatch` (the `version` you read) to avoid overwriting
+ * a concurrent change; a mismatch throws ShardfluxApiError 409 `conflict` with
+ * details.reason = 'version_mismatch'.
+ */
+import type { ClientContext, Page } from './client.js';
+export type EgressMode = 'allow_all' | 'allowlist' | 'deny_all';
+export interface EgressRuleInput {
+    /** Exact FQDN or `*.` + FQDN (one extra label). IP literals and localhost-like names are rejected. */
+    host: string;
+    /** Default [443]. */
+    ports?: number[];
+    /** Only 'tcp' (default); udp/quic are rejected. */
+    protocols?: Array<'tcp'>;
+}
+export interface EgressPolicyInput {
+    mode: EgressMode;
+    /** allowlist only; at most 256. */
+    rules?: EgressRuleInput[];
+    /** allowlist only; public ranges only; at most 64. */
+    cidrs?: string[];
+}
+export interface EgressRule {
+    host: string;
+    ports: number[];
+    protocols: Array<'tcp'>;
+}
+export interface EgressPolicyVersion {
+    id: string;
+    scope: 'project' | 'workspace';
+    project_id: string;
+    workspace_id: string | null;
+    version: number;
+    /** cleared: the workspace override was removed. */
+    kind: 'policy' | 'cleared';
+    mode: EgressMode | null;
+    rules: EgressRule[];
+    cidrs: string[];
+    policy_sha256: string | null;
+    created_by: {
+        type: 'user' | 'api_key';
+        id: string;
+    };
+    created_at: string;
+}
+export interface EffectiveEgressPolicy {
+    /** organization: an organization egress override (contracts §18) wins over every policy (mode deny_all, no version). */
+    source: 'organization' | 'workspace' | 'project' | 'platform_default';
+    policy_version_id: string | null;
+    policy_version: number | null;
+    mode: EgressMode;
+    rules: EgressRule[];
+    cidrs: string[];
+    policy_sha256: string;
+}
+/**
+ * Active organization egress override (contracts §18): the organization used its whole outbound transfer allowance,
+ * so outbound internet traffic of every workspace is blocked until `lifts_at` (period end) or an upgrade/purchase.
+ * Stored policies are kept and apply again when it lifts.
+ */
+export interface OrganizationEgressOverride {
+    mode: 'deny_all';
+    reason: 'transfer_allowance_exhausted';
+    set_at: string;
+    lifts_at: string;
+}
+export interface EgressEnforcement {
+    state: 'not_enforced' | 'pending' | 'enforced' | 'failed';
+    reason: 'not_acknowledged' | 'other_version_acknowledged' | 'stale_epoch' | null;
+    /** Version number of the policy the cell/host last acknowledged for this workspace (null: none, or the platform default). */
+    applied_version: number | null;
+    /** Version number of the current effective policy (null: platform default). */
+    effective_version: number | null;
+    acknowledged: {
+        policy_version_id: string | null;
+        policy_version: number | null;
+        policy_sha256: string;
+        ownership_epoch: number;
+        state: 'pending' | 'enforced' | 'failed';
+        host_id: string | null;
+        error_code: string | null;
+        result: Record<string, unknown>;
+        acknowledged_at: string;
+        applied_at: string | null;
+        updated_at: string;
+    } | null;
+}
+export interface ProjectEgressPolicy {
+    organization_id: string;
+    project_id: string;
+    /** Send as ifMatch (0 = no project policy yet). */
+    version: number;
+    policy: EgressPolicyVersion | null;
+    effective: EffectiveEgressPolicy;
+    /** Active organization override (null: none). */
+    organization_override: OrganizationEgressOverride | null;
+    /** How far the cell has applied the current project policy to the live workspaces inheriting it. */
+    propagation: {
+        workspaces: number;
+        enforced: number;
+        pending: number;
+        failed: number;
+        not_enforced: number;
+        truncated: boolean;
+    };
+}
+export interface WorkspaceEgressPolicy {
+    organization_id: string;
+    project_id: string;
+    workspace_id: string;
+    /** Version of the workspace override history; send as ifMatch. */
+    version: number;
+    override: EgressPolicyVersion | null;
+    project_policy: EgressPolicyVersion | null;
+    effective: EffectiveEgressPolicy;
+    /** Active organization override (null: none); when set, `effective.source` is 'organization'. */
+    organization_override: OrganizationEgressOverride | null;
+    enforcement: EgressEnforcement;
+}
+export declare class EgressPolicyApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    getProject(projectId: string): Promise<ProjectEgressPolicy>;
+    /** Replaces the project policy (new immutable version). */
+    putProject(projectId: string, policy: EgressPolicyInput, opts?: {
+        ifMatch?: number | '*';
+    }): Promise<ProjectEgressPolicy>;
+    projectVersions(projectId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<EgressPolicyVersion>>;
+    /** Effective policy (workspace > project > platform default) and its enforcement state. */
+    getWorkspace(workspaceId: string): Promise<WorkspaceEgressPolicy>;
+    /** Sets the workspace override (new immutable version). */
+    putWorkspace(workspaceId: string, policy: EgressPolicyInput, opts?: {
+        ifMatch?: number | '*';
+    }): Promise<WorkspaceEgressPolicy>;
+    /** Removes the workspace override (falls back to the project policy). */
+    clearWorkspace(workspaceId: string, opts?: {
+        ifMatch?: number | '*';
+    }): Promise<void>;
+    workspaceVersions(workspaceId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<EgressPolicyVersion>>;
+}

package/dist/egress.js

@@ -0,0 +1,37 @@
+const ifMatchHeader = (ifMatch) => ifMatch === undefined ? {} : { 'if-match': ifMatch === '*' ? '*' : `"${ifMatch}"` };
+export class EgressPolicyApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    get #auth() {
+        return this.#ctx().authorization;
+    }
+    getProject(projectId) {
+        return this.#ctx().http.json('GET', `/v1/projects/${encodeURIComponent(projectId)}/egress-policy`, {}, this.#auth);
+    }
+    /** Replaces the project policy (new immutable version). */
+    putProject(projectId, policy, opts = {}) {
+        return this.#ctx().http.json('PUT', `/v1/projects/${encodeURIComponent(projectId)}/egress-policy`, { json: policy, headers: ifMatchHeader(opts.ifMatch) }, this.#auth);
+    }
+    async projectVersions(projectId, opts = {}) {
+        const raw = await this.#ctx().http.json('GET', `/v1/projects/${encodeURIComponent(projectId)}/egress-policy/versions`, { query: { limit: opts.limit, cursor: opts.cursor } }, this.#auth);
+        return { data: raw.data, nextCursor: raw.next_cursor };
+    }
+    /** Effective policy (workspace > project > platform default) and its enforcement state. */
+    getWorkspace(workspaceId) {
+        return this.#ctx().http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}/egress-policy`, {}, this.#auth);
+    }
+    /** Sets the workspace override (new immutable version). */
+    putWorkspace(workspaceId, policy, opts = {}) {
+        return this.#ctx().http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/egress-policy`, { json: policy, headers: ifMatchHeader(opts.ifMatch) }, this.#auth);
+    }
+    /** Removes the workspace override (falls back to the project policy). */
+    async clearWorkspace(workspaceId, opts = {}) {
+        await this.#ctx().http.json('DELETE', `/v1/workspaces/${encodeURIComponent(workspaceId)}/egress-policy`, { headers: ifMatchHeader(opts.ifMatch) }, this.#auth);
+    }
+    async workspaceVersions(workspaceId, opts = {}) {
+        const raw = await this.#ctx().http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}/egress-policy/versions`, { query: { limit: opts.limit, cursor: opts.cursor } }, this.#auth);
+        return { data: raw.data, nextCursor: raw.next_cursor };
+    }
+}