@shardflux/sdk 0.5.0

package/dist/generated/cell-api.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/http.d.ts

@@ -0,0 +1,39 @@
+export declare const SDK_VERSION = "0.5.0";
+export interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined | null>;
+    json?: unknown;
+    body?: Uint8Array | string;
+    contentType?: string;
+    accept?: string;
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+    /** Override the client's default request timeout (ms); 0 disables it (streams). */
+    timeoutMs?: number;
+}
+export interface HttpOptions {
+    baseUrl: string;
+    fetch: typeof fetch;
+    userAgent: string;
+    timeoutMs: number;
+    maxRetries: number;
+    source: 'api' | 'cell';
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare const defaultSleep: (ms: number) => Promise<void>;
+export declare function buildUrl(base: string, path: string, query?: RequestOptions['query']): string;
+/** Turns a non-2xx response into a ShardfluxApiError (or a protocol error for undocumented bodies). */
+export declare function errorFrom(res: Response, source: 'api' | 'cell'): Promise<Error>;
+export declare class HttpClient {
+    readonly opts: HttpOptions;
+    constructor(opts: HttpOptions);
+    /** Performs the request and returns the raw Response (2xx), throwing structured errors otherwise. */
+    raw(method: string, path: string, init?: RequestOptions, authorization?: string): Promise<Response>;
+    json<T>(method: string, path: string, init?: RequestOptions, authorization?: string): Promise<T>;
+    /** Like json() but also returns the HTTP status (open() distinguishes 200 from 202). */
+    jsonWithStatus<T>(method: string, path: string, init?: RequestOptions, authorization?: string): Promise<{
+        status: number;
+        body: T;
+    }>;
+}
+export declare function randomId(prefix?: string): string;

package/dist/http.js

@@ -0,0 +1,121 @@
+/**
+ * Minimal HTTP layer shared by the application API client and the cell
+ * client: JSON in/out, structured errors, per-request timeout, and bounded
+ * retries only where a retry cannot duplicate an effect (safe methods, or
+ * requests carrying an Idempotency-Key).
+ */
+import { ShardfluxApiError, ShardfluxProtocolError, isErrorBody } from "./errors.js";
+export const SDK_VERSION = '0.5.0';
+export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function buildUrl(base, path, query) {
+    const u = new URL(base.replace(/\/+$/, '') + path);
+    for (const [k, v] of Object.entries(query ?? {})) {
+        if (v !== undefined && v !== null)
+            u.searchParams.set(k, String(v));
+    }
+    return u.toString();
+}
+function retryAfterSeconds(res) {
+    const v = res.headers.get('retry-after');
+    if (v === null)
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+/** Turns a non-2xx response into a ShardfluxApiError (or a protocol error for undocumented bodies). */
+export async function errorFrom(res, source) {
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text.length > 0 ? JSON.parse(text) : null;
+    }
+    catch {
+        parsed = null;
+    }
+    if (isErrorBody(parsed))
+        return new ShardfluxApiError(res.status, parsed, source, retryAfterSeconds(res));
+    return new ShardfluxProtocolError(`HTTP ${res.status} from ${source === 'api' ? 'the Shardflux API' : 'the cell gateway'} without an error body`, res.status);
+}
+export class HttpClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Performs the request and returns the raw Response (2xx), throwing structured errors otherwise. */
+    async raw(method, path, init = {}, authorization) {
+        const url = buildUrl(this.opts.baseUrl, path, init.query);
+        const safe = method === 'GET' || method === 'HEAD';
+        const retriable = safe || init.idempotencyKey !== undefined;
+        const sleep = this.opts.sleep ?? defaultSleep;
+        for (let attempt = 0;; attempt += 1) {
+            const headers = {
+                accept: init.accept ?? 'application/json',
+                'user-agent': this.opts.userAgent,
+                ...(authorization ? { authorization } : {}),
+                ...(init.idempotencyKey !== undefined ? { 'idempotency-key': init.idempotencyKey } : {}),
+                ...init.headers,
+            };
+            let body;
+            if (init.json !== undefined) {
+                body = JSON.stringify(init.json);
+                headers['content-type'] = 'application/json';
+            }
+            else if (init.body !== undefined) {
+                body = init.body;
+                headers['content-type'] = init.contentType ?? 'application/octet-stream';
+            }
+            const timeoutMs = init.timeoutMs ?? this.opts.timeoutMs;
+            const timeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+            const signal = timeout && init.signal ? AbortSignal.any([timeout, init.signal]) : (timeout ?? init.signal);
+            let res;
+            try {
+                res = await this.opts.fetch(url, { method, headers, ...(body === undefined ? {} : { body: body }), ...(signal ? { signal } : {}) });
+            }
+            catch (err) {
+                if (init.signal?.aborted)
+                    throw err;
+                if (!retriable || attempt >= this.opts.maxRetries)
+                    throw err;
+                await sleep(Math.min(2_000, 200 * 2 ** attempt));
+                continue;
+            }
+            if (res.ok)
+                return res;
+            const error = await errorFrom(res, this.opts.source);
+            const retryableStatus = res.status === 429 || res.status === 502 || res.status === 503 || res.status === 504;
+            const retryableError = error instanceof ShardfluxApiError ? error.retryable && retryableStatus : retryableStatus;
+            if (!retriable || !retryableError || attempt >= this.opts.maxRetries)
+                throw error;
+            const hinted = error instanceof ShardfluxApiError ? error.retryAfterSeconds : undefined;
+            await sleep(Math.min(5_000, hinted !== undefined ? hinted * 1000 : 200 * 2 ** attempt));
+        }
+    }
+    async json(method, path, init = {}, authorization) {
+        const res = await this.raw(method, path, init, authorization);
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        if (text.length === 0)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+        }
+    }
+    /** Like json() but also returns the HTTP status (open() distinguishes 200 from 202). */
+    async jsonWithStatus(method, path, init = {}, authorization) {
+        const res = await this.raw(method, path, init, authorization);
+        const text = await res.text();
+        try {
+            return { status: res.status, body: (text.length === 0 ? undefined : JSON.parse(text)) };
+        }
+        catch {
+            throw new ShardfluxProtocolError(`${method} ${path}: response is not JSON`, res.status);
+        }
+    }
+}
+export function randomId(prefix = '') {
+    return `${prefix}${crypto.randomUUID()}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @shardflux/sdk — TypeScript SDK for Shardflux persistent agent workspaces.
+ *
+ *   import { Shardflux, workspaceTools } from '@shardflux/sdk';
+ *   const cloud = new Shardflux({ apiKey: process.env.SHARDFLUX_API_KEY! });
+ *   const workspace = await cloud.workspaces.open({ key: `${customerId}/${projectId}`, template: 'python-node-browser' });
+ *   await agent.run({ input: userMessage, tools: workspaceTools(workspace) });
+ *
+ * Types come from the committed OpenAPI documents: application API
+ * and cell gateway.
+ */
+export type { components, operations, paths } from './generated/app-api.js';
+export type { components as CellComponents, paths as CellPaths } from './generated/cell-api.js';
+export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog } from './client.js';
+export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, Entitlements, Invoice, InvoicePage, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, ShardfluxOptions, WaitOptions, WorkspaceView, } from './client.js';
+export { UsageApi } from './usage.js';
+export type { Grants, Spend, SpendPolicy, UsageEstimate, UsageMeter, UsageSeries, UsageSeriesParams, UsageSummary } from './usage.js';
+export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplatesApi, buildSettled } from './templates.js';
+export type { BuilderAvailability, CreateTemplateBuildParams, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRegistrationState, TemplateBuildState, TemplateDetail, TemplateOwner, TemplateRecipe, TemplateSummary, TemplateVersion, TemplateVersionState, WaitForBuildOptions, } from './templates.js';
+export { SecretsApi } from './secrets.js';
+export type { CreateSecretParams, Secret, SecretPermissions, SecretScope, SecretVersion, UpdateSecretParams } from './secrets.js';
+export { EgressPolicyApi } from './egress.js';
+export type { EffectiveEgressPolicy, EgressEnforcement, EgressMode, EgressPolicyInput, EgressPolicyVersion, EgressRule, EgressRuleInput, OrganizationEgressOverride, ProjectEgressPolicy, WorkspaceEgressPolicy, } from './egress.js';
+export { VolumesApi } from './volumes.js';
+export type { AttachVolumeParams, AttachmentResult, CreateVolumeParams, DeleteVolumeParams, Volume, VolumeAttachment, VolumeAttachmentState, VolumeResult, VolumeState } from './volumes.js';
+export { AuditApi, auditQuery, parseAuditNdjson } from './audit.js';
+export type { AuditActorType, AuditEvent, AuditFilters, AuditListParams, AuditOutcome, AuditSource } from './audit.js';
+export { Workspace } from './workspace.js';
+export { CellClient, cellPath, ndjson } from './cell.js';
+export type { BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, FileInfo, FileList, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, RunOptions, RunResult, Signal, } from './cell.js';
+export { ToolTokenManager } from './tokens.js';
+export type { ToolName, ToolToken, ToolTokenOptions } from './tokens.js';
+export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from './tools.js';
+export type { JsonSchema, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from './errors.js';
+export type { AppErrorCode, CellErrorCode, ErrorCode } from './errors.js';
+export { SDK_VERSION } from './http.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog } from "./client.js";
+export { UsageApi } from "./usage.js";
+export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplatesApi, buildSettled } from "./templates.js";
+export { SecretsApi } from "./secrets.js";
+export { EgressPolicyApi } from "./egress.js";
+export { VolumesApi } from "./volumes.js";
+export { AuditApi, auditQuery, parseAuditNdjson } from "./audit.js";
+export { Workspace } from "./workspace.js";
+export { CellClient, cellPath, ndjson } from "./cell.js";
+export { ToolTokenManager } from "./tokens.js";
+export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from "./tools.js";
+export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+export { SDK_VERSION } from "./http.js";

package/dist/secrets.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Customer secrets over the application API (/v1). Types are written by hand.
+ *
+ * A project API key manages the secrets of its own project. Values are
+ * write-only: no method here returns one. The cell gateway obtains values at
+ * exec/PTY session start through POST /v1/internal/secret-resolutions with the
+ * caller's tool token; that endpoint is not part of the customer SDK.
+ * Organization-wide secrets and access logs are managed by owners/admins in the
+ * browser (/api/v1).
+ */
+import type { ClientContext, Page } from './client.js';
+import type { ToolName } from './tokens.js';
+export type SecretScope = 'organization' | 'project';
+export interface SecretPermissions {
+    /** Organization secrets only: null = every project, [] = none. Always null for project secrets. */
+    allowed_project_ids: string[] | null;
+    /** null = any workspace of the allowed projects. Forks do not inherit workspace-scoped permissions. */
+    allowed_workspace_ids: string[] | null;
+    /** Tools that may receive the value at session start (the tool token must carry the tool too). */
+    allowed_tools: ToolName[];
+}
+export interface Secret {
+    id: string;
+    organization_id: string;
+    project_id: string | null;
+    scope: SecretScope;
+    /** The environment variable name the value is injected as. */
+    name: string;
+    description: string;
+    current_version: number;
+    permissions: SecretPermissions;
+    created_by: {
+        type: 'user' | 'api_key';
+        id: string;
+    };
+    created_at: string;
+    updated_at: string;
+    rotated_at: string | null;
+    deleted_at: string | null;
+}
+export interface SecretVersion {
+    secret_id: string;
+    version: number;
+    state: 'current' | 'destroyed';
+    created_by: {
+        type: 'user' | 'api_key';
+        id: string;
+    };
+    created_at: string;
+    destroyed_at: string | null;
+    destroyed_reason: 'rotated' | 'deleted' | null;
+}
+export interface CreateSecretParams {
+    /** `^[A-Z_][A-Z0-9_]{0,127}$`, unique per project; `SHARDFLUX_` prefix reserved. */
+    name: string;
+    /** UTF-8 text up to 65536 bytes, no NUL. Never returned by the API. */
+    value: string;
+    description?: string;
+    /** Default null (any workspace of the project). */
+    allowedWorkspaceIds?: string[] | null;
+    /** Default ['exec', 'pty']. */
+    allowedTools?: ToolName[];
+    /** Defaults to a fresh key per call so transport retries replay instead of duplicating. */
+    idempotencyKey?: string;
+}
+export interface UpdateSecretParams {
+    description?: string;
+    allowedWorkspaceIds?: string[] | null;
+    allowedTools?: ToolName[];
+}
+export declare class SecretsApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    /** Creates a project secret (the key's own project). */
+    create(projectId: string, params: CreateSecretParams): Promise<Secret>;
+    /** Lists a project's secrets (metadata only). */
+    list(projectId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+        includeDeleted?: boolean;
+    }): Promise<Page<Secret>>;
+    /** Metadata of one secret (deleted secrets stay readable with deleted_at). */
+    get(secretId: string): Promise<Secret>;
+    /** Changes description or usage permissions; applies from the next session start. */
+    update(secretId: string, params: UpdateSecretParams): Promise<Secret>;
+    /** Stores a new value as the next version; older values are erased. Running processes keep what they read. */
+    rotate(secretId: string, value: string, opts?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        secret: Secret;
+        version: SecretVersion;
+    }>;
+    /** Version metadata, newest first. */
+    versions(secretId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<SecretVersion>>;
+    /** Deletes (tombstones) the secret and erases its values; resolution stops at once. */
+    delete(secretId: string): Promise<void>;
+}

package/dist/secrets.js

@@ -0,0 +1,56 @@
+import { randomId } from "./http.js";
+const toPage = (p) => ({ data: p.data, nextCursor: p.next_cursor });
+export class SecretsApi {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    get #auth() {
+        return this.#ctx().authorization;
+    }
+    /** Creates a project secret (the key's own project). */
+    async create(projectId, params) {
+        return this.#ctx().http.json('POST', `/v1/projects/${encodeURIComponent(projectId)}/secrets`, {
+            json: {
+                name: params.name,
+                value: params.value,
+                ...(params.description !== undefined ? { description: params.description } : {}),
+                ...(params.allowedWorkspaceIds !== undefined ? { allowed_workspace_ids: params.allowedWorkspaceIds } : {}),
+                ...(params.allowedTools !== undefined ? { allowed_tools: params.allowedTools } : {}),
+            },
+            idempotencyKey: params.idempotencyKey ?? randomId('sdk-secret-'),
+        }, this.#auth);
+    }
+    /** Lists a project's secrets (metadata only). */
+    async list(projectId, opts = {}) {
+        const raw = await this.#ctx().http.json('GET', `/v1/projects/${encodeURIComponent(projectId)}/secrets`, { query: { limit: opts.limit, cursor: opts.cursor, include_deleted: opts.includeDeleted } }, this.#auth);
+        return toPage(raw);
+    }
+    /** Metadata of one secret (deleted secrets stay readable with deleted_at). */
+    get(secretId) {
+        return this.#ctx().http.json('GET', `/v1/secrets/${encodeURIComponent(secretId)}`, {}, this.#auth);
+    }
+    /** Changes description or usage permissions; applies from the next session start. */
+    update(secretId, params) {
+        return this.#ctx().http.json('PATCH', `/v1/secrets/${encodeURIComponent(secretId)}`, {
+            json: {
+                ...(params.description !== undefined ? { description: params.description } : {}),
+                ...(params.allowedWorkspaceIds !== undefined ? { allowed_workspace_ids: params.allowedWorkspaceIds } : {}),
+                ...(params.allowedTools !== undefined ? { allowed_tools: params.allowedTools } : {}),
+            },
+        }, this.#auth);
+    }
+    /** Stores a new value as the next version; older values are erased. Running processes keep what they read. */
+    rotate(secretId, value, opts = {}) {
+        return this.#ctx().http.json('POST', `/v1/secrets/${encodeURIComponent(secretId)}/versions`, { json: { value }, idempotencyKey: opts.idempotencyKey ?? randomId('sdk-rotate-') }, this.#auth);
+    }
+    /** Version metadata, newest first. */
+    async versions(secretId, opts = {}) {
+        const raw = await this.#ctx().http.json('GET', `/v1/secrets/${encodeURIComponent(secretId)}/versions`, { query: { limit: opts.limit, cursor: opts.cursor } }, this.#auth);
+        return toPage(raw);
+    }
+    /** Deletes (tombstones) the secret and erases its values; resolution stops at once. */
+    async delete(secretId) {
+        await this.#ctx().http.json('DELETE', `/v1/secrets/${encodeURIComponent(secretId)}`, {}, this.#auth);
+    }
+}