@tangle-network/sandbox 0.0.3

package/dist/errors-WHP1v4xn.d.ts

@@ -0,0 +1,449 @@
+import { Et as SecretsManager, Rt as UsageInfo, W as ListSandboxOptions, b as CreateSandboxOptions, d as BatchEvent, f as BatchOptions, gt as SandboxEnvironment, jt as SubscriptionInfo, m as BatchTask, mt as SandboxClientConfig, n as SandboxInstance, p as BatchResult, t as HttpClient } from "./sandbox-D-1E98ow.js";
+
+//#region src/client.d.ts
+/**
+ * Client for the Tangle Sandbox platform.
+ *
+ * @example
+ * ```typescript
+ * import { Sandbox } from "@tangle-network/sandbox";
+ *
+ * const client = new Sandbox({
+ *   apiKey: "sk_sandbox_...",
+ *   baseUrl: "https://your-sandbox-api.example.com",
+ * });
+ *
+ * // Create a sandbox
+ * const box = await client.create({
+ *   name: "my-project",
+ *   sshEnabled: true,
+ * });
+ *
+ * // Execute commands
+ * const result = await box.exec("npm install");
+ *
+ * // Clean up
+ * await box.delete();
+ * ```
+ */
+declare class SandboxClient implements HttpClient {
+  private readonly baseUrl;
+  private readonly apiKey;
+  private readonly timeoutMs;
+  private _secrets;
+  constructor(config: SandboxClientConfig);
+  /**
+   * Access the secrets manager for storing and retrieving encrypted secrets.
+   *
+   * @example
+   * ```typescript
+   * // Create a secret
+   * await client.secrets.create("HF_TOKEN", "hf_xxx");
+   *
+   * // List secrets (names only)
+   * const secrets = await client.secrets.list();
+   *
+   * // Get secret value
+   * const value = await client.secrets.get("HF_TOKEN");
+   *
+   * // Update secret
+   * await client.secrets.update("HF_TOKEN", "hf_new_value");
+   *
+   * // Delete secret
+   * await client.secrets.delete("HF_TOKEN");
+   * ```
+   */
+  get secrets(): SecretsManager;
+  private _environments;
+  /**
+   * Access available development environments.
+   *
+   * @example
+   * ```typescript
+   * const envs = await client.environments.list();
+   * // → [{ id: "universal", description: "Universal environment with all toolchains via Nix", ... }]
+   *
+   * const sandbox = await client.create({ environment: "universal" });
+   * ```
+   */
+  get environments(): EnvironmentsClient;
+  private _teams;
+  /**
+   * Access team management (collaboration groups, invitations,
+   * member roles). Teams scope shared sandboxes — pass `teamId` to
+   * `client.create()` to create a sandbox accessible to a team's
+   * members.
+   *
+   * @example
+   * ```typescript
+   * const teams = await client.teams.list();
+   * const invite = await client.teams.invite(teams[0].id, {
+   *   email: "alice@example.com",
+   *   role: "member",
+   * });
+   * ```
+   */
+  get teams(): TeamsClient;
+  /**
+   * Create a new sandbox.
+   *
+   * @param options - Configuration for the new sandbox
+   * @returns A SandboxInstance representing the created sandbox
+   *
+   * @example
+   * ```typescript
+   * const box = await client.create({
+   *   name: "my-project",
+   *   environment: "universal",
+   *   sshEnabled: true,
+   *   env: { NODE_ENV: "development" },
+   * });
+   * ```
+   */
+  create(options?: CreateSandboxOptions): Promise<SandboxInstance>;
+  /**
+   * List all sandboxes.
+   *
+   * @param options - Filtering and pagination options
+   * @returns Array of SandboxInstance objects
+   *
+   * @example
+   * ```typescript
+   * // List all running sandboxes
+   * const running = await client.list({ status: "running" });
+   *
+   * // List with pagination
+   * const page = await client.list({ limit: 10, offset: 0 });
+   * ```
+   */
+  list(options?: ListSandboxOptions): Promise<SandboxInstance[]>;
+  /**
+   * Get a sandbox by ID.
+   *
+   * @param id - The sandbox ID
+   * @returns A SandboxInstance or null if not found
+   *
+   * @example
+   * ```typescript
+   * const box = await client.get("sandbox_abc123");
+   * if (box) {
+   *   console.log(box.status);
+   * }
+   * ```
+   */
+  get(id: string): Promise<SandboxInstance | null>;
+  /**
+   * Get usage information for the account.
+   *
+   * @returns Usage statistics for the current billing period
+   *
+   * @example
+   * ```typescript
+   * const usage = await client.usage();
+   * console.log(`Active sandboxes: ${usage.activeSandboxes}`);
+   * console.log(`Compute minutes: ${usage.computeMinutes}`);
+   * ```
+   */
+  usage(): Promise<UsageInfo>;
+  /**
+   * Get subscription and billing information for the account.
+   *
+   * @returns Subscription details including plan, credits, and limits
+   *
+   * @example
+   * ```typescript
+   * const sub = await client.subscription();
+   * console.log(`Plan: ${sub.plan}`);
+   * console.log(`Credits: $${sub.creditsAvailableUsd.toFixed(2)}`);
+   * ```
+   */
+  subscription(): Promise<SubscriptionInfo>;
+  /**
+   * Check if the Sandbox API is available.
+   *
+   * @returns true if the API is healthy, false otherwise
+   */
+  health(): Promise<boolean>;
+  /**
+   * Check if CRIU checkpointing is available on the platform.
+   *
+   * CRIU enables memory preservation for true pause/resume and fork operations.
+   * It requires specific host configuration.
+   *
+   * @returns CRIU availability status
+   *
+   * @example
+   * ```typescript
+   * const status = await client.criuStatus();
+   * if (status.available) {
+   *   console.log(`CRIU ${status.criuVersion} available`);
+   * } else {
+   *   console.log(`CRIU not available: ${status.reason}`);
+   * }
+   * ```
+   */
+  criuStatus(): Promise<{
+    available: boolean;
+    criuVersion?: string;
+    reason?: string;
+    requirements?: {
+      kernel: boolean;
+      criu: boolean;
+      storageDriver: boolean;
+      experimental: boolean;
+    };
+  }>;
+  /**
+   * Run multiple tasks in parallel across sandboxes.
+   * Returns the aggregated results after all tasks complete.
+   *
+   * @param tasks - Array of tasks to execute
+   * @param options - Batch execution options
+   * @returns Aggregated batch results
+   *
+   * @throws {@link TimeoutError} if the server hasn't begun responding
+   *   before the deadline (pre-stream timeout).
+   * @throws {@link ValidationError} / {@link QuotaError} / other typed
+   *   SDK errors if the server rejects the request before streaming.
+   * @throws `DOMException` with `name === "AbortError"` if
+   *   `options.signal` fires OR the safety-valve deadline fires
+   *   AFTER streaming has begun — parseSSEStream can't distinguish
+   *   the source mid-stream. Callers that need to tell cancel from
+   *   timeout should check `options.signal?.aborted` in their catch.
+   * @throws `Error` with the server message if the stream emits a
+   *   `batch.failed` event.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.runBatch([
+   *   { id: "task-1", message: "Analyze this file" },
+   *   { id: "task-2", message: "Generate a summary" },
+   * ]);
+   * console.log(`Success rate: ${result.successRate}%`);
+   * ```
+   */
+  runBatch(tasks: BatchTask[], options?: BatchOptions): Promise<BatchResult>;
+  /**
+   * Stream events from a batch execution.
+   * Use this for real-time progress updates during batch processing.
+   *
+   * @param tasks - Array of tasks to execute
+   * @param options - Batch execution options
+   *
+   * @throws {@link TimeoutError} if the server hasn't begun responding
+   *   before the deadline (pre-stream timeout).
+   * @throws {@link ValidationError} / {@link QuotaError} / other typed
+   *   SDK errors if the server rejects the request before streaming.
+   * @throws `DOMException` with `name === "AbortError"` if
+   *   `options.signal` fires OR the safety-valve deadline fires
+   *   AFTER streaming has begun. Distinguish via
+   *   `options.signal?.aborted` in the consumer's catch.
+   *
+   * @example
+   * ```typescript
+   * for await (const event of client.streamBatch(tasks)) {
+   *   if (event.type === "task.completed") {
+   *     console.log(`Task ${event.data.taskId} completed`);
+   *   }
+   * }
+   * ```
+   */
+  streamBatch(tasks: BatchTask[], options?: BatchOptions): AsyncGenerator<BatchEvent>;
+  /**
+   * Make an authenticated HTTP request to the API.
+   * This is exposed for use by SandboxInstance.
+   */
+  fetch(path: string, options?: RequestInit): Promise<Response>;
+  private parseInfo;
+}
+/**
+ * Client for browsing available development environments.
+ */
+declare class EnvironmentsClient {
+  private readonly client;
+  constructor(client: SandboxClient);
+  /**
+   * List available development environments.
+   *
+   * @returns Array of available environments with metadata
+   *
+   * @example
+   * ```typescript
+   * const envs = await client.environments.list();
+   * for (const env of envs) {
+   *   console.log(`${env.id}: ${env.description}`);
+   * }
+   * ```
+   */
+  list(): Promise<SandboxEnvironment[]>;
+  /**
+   * Get details for a specific environment.
+   *
+   * @param id - Environment identifier (e.g., "universal")
+   */
+  get(id: string): Promise<SandboxEnvironment | null>;
+}
+/**
+ * Team (collaboration group) record as returned from the API.
+ */
+interface Team {
+  id: string;
+  name: string;
+  ownerCustomerId: string;
+  orgId: string | null;
+  memberCount: number;
+  currentUserRole: "owner" | "admin" | "member" | "viewer";
+  createdAt: string;
+  updatedAt: string;
+}
+interface TeamMember {
+  id: string;
+  teamId: string;
+  customerId: string;
+  customerEmail: string;
+  customerName: string | null;
+  role: "owner" | "admin" | "member" | "viewer";
+  status: "active" | "pending" | "removed";
+  joinedAt: string | null;
+  createdAt: string;
+}
+interface TeamInvitation {
+  id: string;
+  teamId: string;
+  email: string;
+  invitedBy: string;
+  invitedByEmail: string | null;
+  role: "admin" | "member" | "viewer";
+  token: string;
+  status: "pending" | "accepted" | "expired" | "revoked";
+  expiresAt: string;
+  createdAt: string;
+}
+interface CreateTeamOptions {
+  name: string;
+  orgId?: string;
+}
+interface InviteTeamMemberOptions {
+  email: string;
+  role: "admin" | "member" | "viewer";
+  /** Lifetime of the invitation in hours (default 168 = 7 days). */
+  ttlHours?: number;
+}
+/**
+ * Client for managing teams and team-scoped sharing.
+ *
+ * Team resources are scoped to the authenticated user's membership —
+ * the client never needs to pass an org id explicitly.
+ */
+declare class TeamsClient {
+  private readonly client;
+  constructor(client: SandboxClient);
+  list(): Promise<Team[]>;
+  create(options: CreateTeamOptions): Promise<Team>;
+  get(teamId: string): Promise<Team>;
+  update(teamId: string, updates: {
+    name?: string;
+  }): Promise<Team>;
+  delete(teamId: string): Promise<void>;
+  leave(teamId: string): Promise<void>;
+  listMembers(teamId: string): Promise<TeamMember[]>;
+  updateMember(teamId: string, memberId: string, updates: {
+    role?: "admin" | "member" | "viewer";
+    status?: "active" | "removed";
+  }): Promise<TeamMember>;
+  removeMember(teamId: string, memberId: string): Promise<void>;
+  listInvitations(teamId: string): Promise<TeamInvitation[]>;
+  invite(teamId: string, options: InviteTeamMemberOptions): Promise<TeamInvitation>;
+  revokeInvitation(invitationId: string): Promise<void>;
+  acceptInvitation(token: string): Promise<TeamMember>;
+}
+/**
+ * Alias for SandboxClient for cleaner imports.
+ */
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Sandbox SDK Errors
+ *
+ * Error classes for the Sandbox client SDK.
+ */
+/**
+ * Base error class for all Sandbox SDK errors.
+ */
+declare class SandboxError extends Error {
+  /** HTTP status code if applicable */
+  readonly status?: number;
+  /** Error code for programmatic handling */
+  readonly code: string;
+  constructor(message: string, code: string, status?: number);
+}
+/**
+ * Authentication failed or API key is invalid.
+ */
+declare class AuthError extends SandboxError {
+  constructor(message?: string);
+}
+/**
+ * The requested resource was not found.
+ */
+declare class NotFoundError extends SandboxError {
+  /** The resource type that was not found */
+  readonly resourceType: string;
+  /** The resource ID that was not found */
+  readonly resourceId: string;
+  constructor(resourceType: string, resourceId: string);
+}
+/**
+ * Account quota or rate limit exceeded.
+ */
+declare class QuotaError extends SandboxError {
+  /** The type of quota that was exceeded */
+  readonly quotaType: string;
+  /** Current usage */
+  readonly current?: number;
+  /** Maximum allowed */
+  readonly limit?: number;
+  constructor(quotaType: string, message?: string, current?: number, limit?: number);
+}
+/**
+ * The request was invalid or malformed.
+ */
+declare class ValidationError extends SandboxError {
+  /** Field-level validation errors */
+  readonly fields?: Record<string, string>;
+  constructor(message: string, fields?: Record<string, string>);
+}
+/**
+ * The sandbox is not in a valid state for the requested operation.
+ */
+declare class StateError extends SandboxError {
+  /** Current state of the sandbox */
+  readonly currentState: string;
+  /** Required state for the operation */
+  readonly requiredState?: string;
+  constructor(message: string, currentState: string, requiredState?: string);
+}
+/**
+ * The request timed out.
+ */
+declare class TimeoutError extends SandboxError {
+  /** Timeout duration in milliseconds */
+  readonly timeoutMs: number;
+  constructor(timeoutMs: number, message?: string);
+}
+/**
+ * A network or connection error occurred.
+ */
+declare class NetworkError extends SandboxError {
+  /** The underlying error */
+  readonly cause?: Error;
+  constructor(message: string, cause?: Error);
+}
+/**
+ * The server returned an unexpected error.
+ */
+declare class ServerError extends SandboxError {
+  constructor(message: string, status?: number);
+}
+//#endregion
+export { SandboxError as a, TimeoutError as c, InviteTeamMemberOptions as d, SandboxClient as f, TeamMember as h, QuotaError as i, ValidationError as l, TeamInvitation as m, NetworkError as n, ServerError as o, Team as p, NotFoundError as r, StateError as s, AuthError as t, CreateTeamOptions as u };

package/dist/index-A6QuCBt3.d.ts

@@ -0,0 +1,189 @@
+//#region src/auth/types.d.ts
+/**
+ * Auth Types
+ *
+ * Self-contained type definitions for token issuance.
+ * No external dependencies (no zod, no internal packages).
+ */
+/**
+ * Token scope types for multi-tenant access control.
+ *
+ * - "session": Access to a single session (requires sid)
+ * - "project": Access to all sessions within a project (requires projectId)
+ * - "batch": Access to multiple projects (requires projectIds array)
+ * - "collaboration": Access to a single collaborative document
+ */
+type TokenScope = "session" | "project" | "batch" | "collaboration";
+/**
+ * Base token payload fields (common across all scopes).
+ */
+interface BaseTokenPayload {
+  /** Subject: User ID */
+  sub: string;
+  /** Product ID (used to look up signing secret) */
+  pid: string;
+  /** Sandbox runtime ID (optional, for direct routing) */
+  cid?: string;
+  /** Issued at (Unix timestamp, seconds) */
+  iat: number;
+  /** Expires at (Unix timestamp, seconds) */
+  exp: number;
+}
+interface ReadBaseTokenPayload extends BaseTokenPayload {
+  /** Token type for session/project/batch event subscriptions */
+  typ: "read";
+}
+/**
+ * Session-scoped token payload.
+ * Grants access to a single session's events.
+ */
+interface SessionScopedTokenPayload extends ReadBaseTokenPayload {
+  /** Session ID */
+  sid: string;
+  projectId?: undefined;
+  projectIds?: undefined;
+}
+/**
+ * Project-scoped token payload.
+ * Grants access to all sessions within a single project.
+ */
+interface ProjectScopedTokenPayload extends ReadBaseTokenPayload {
+  sid?: undefined;
+  /** Project ID */
+  projectId: string;
+  projectIds?: undefined;
+}
+/**
+ * Batch-scoped token payload.
+ * Grants access to multiple projects (organization-level access).
+ */
+interface BatchScopedTokenPayload extends ReadBaseTokenPayload {
+  sid?: undefined;
+  projectId?: undefined;
+  /** Project IDs */
+  projectIds: string[];
+}
+type CollaborationAccess = "read" | "write";
+/**
+ * Collaboration-scoped token payload.
+ * Grants access to a single collaborative document in one project.
+ */
+interface CollaborationTokenPayload extends BaseTokenPayload {
+  typ: "collaboration";
+  sid: string;
+  projectId: string;
+  documentId: string;
+  access: CollaborationAccess;
+}
+interface IssueCollaborationTokenOptions {
+  sessionId: string;
+  projectId: string;
+  documentId: string;
+  access: CollaborationAccess;
+  userId: string;
+  productId: string;
+  sandboxId?: string;
+}
+/**
+ * Union of all token payload types.
+ */
+type ReadTokenPayload = SessionScopedTokenPayload | ProjectScopedTokenPayload | BatchScopedTokenPayload;
+type AnyTokenPayload = ReadTokenPayload | CollaborationTokenPayload;
+//#endregion
+//#region src/auth/tokens.d.ts
+/**
+ * Issue a read token (JWT) for WebSocket authentication.
+ *
+ * @param signingSecret - The product's signing secret
+ * @param payload - Token payload (without iat/exp/typ, those are added)
+ * @param ttlMinutes - Token TTL in minutes
+ */
+declare function issueReadToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a session-scoped token (JWT) for WebSocket authentication.
+ * Grants access to a single session's events.
+ */
+declare function issueSessionScopedToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a project-scoped token (JWT) for WebSocket authentication.
+ * Grants access to all sessions within a single project.
+ */
+declare function issueProjectScopedToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a batch-scoped token (JWT) for WebSocket authentication.
+ * Grants access to multiple projects (organization-level access).
+ */
+declare function issueBatchScopedToken(signingSecret: string, payload: Omit<ReadTokenPayload, "iat" | "exp" | "typ">, ttlMinutes: number): string;
+/**
+ * Issue a collaboration-scoped token (JWT) for collaborative document access.
+ * Grants read or write access to a single document in one project.
+ */
+declare function issueCollaborationToken(signingSecret: string, payload: IssueCollaborationTokenOptions, ttlMinutes: number): string;
+/**
+ * Decode a JWT without verification (to extract claims for lookup).
+ * Returns null if the token is malformed.
+ */
+declare function decodeToken(token: string): AnyTokenPayload | null;
+/**
+ * Get time until token expires (in seconds).
+ * Returns negative if expired.
+ */
+declare function getTokenTTL(payload: AnyTokenPayload): number;
+/**
+ * Check if token is expiring soon (within buffer seconds).
+ */
+declare function isTokenExpiringSoon(payload: AnyTokenPayload, bufferSeconds?: number): boolean;
+//#endregion
+//#region src/auth/index.d.ts
+/**
+ * Token issuer for application backend services.
+ *
+ * Use this in your backend to issue read tokens for WebSocket connections.
+ */
+declare class ProductTokenIssuer {
+  private readonly productId;
+  private readonly signingSecret;
+  private readonly ttlMinutes;
+  constructor(config: {
+    productId: string;
+    signingSecret: string; /** TTL in minutes for each tier (default: { free: 15, pro: 240 }) */
+    ttlMinutes?: {
+      free?: number;
+      pro?: number;
+      enterprise?: number;
+    };
+  });
+  /**
+   * Issue a read token for a user session.
+   */
+  issue(params: {
+    userId: string;
+    sessionId: string;
+    tier?: "free" | "pro" | "enterprise";
+    sandboxId?: string;
+  }): {
+    token: string;
+    expiresAt: number;
+  };
+  /**
+   * Issue a collaboration token for a single document.
+   */
+  issueCollaboration(params: {
+    userId: string;
+    sessionId: string;
+    projectId: string;
+    documentId: string;
+    access: "read" | "write";
+    tier?: "free" | "pro" | "enterprise";
+    sandboxId?: string;
+  }): {
+    token: string;
+    expiresAt: number;
+  };
+  /**
+   * Get the TTL in minutes for a tier.
+   */
+  getTtlMinutes(tier?: "free" | "pro" | "enterprise"): number;
+}
+//#endregion
+export { SessionScopedTokenPayload as _, issueBatchScopedToken as a, issueReadToken as c, BatchScopedTokenPayload as d, CollaborationAccess as f, ReadTokenPayload as g, ProjectScopedTokenPayload as h, isTokenExpiringSoon as i, issueSessionScopedToken as l, IssueCollaborationTokenOptions as m, decodeToken as n, issueCollaborationToken as o, CollaborationTokenPayload as p, getTokenTTL as r, issueProjectScopedToken as s, ProductTokenIssuer as t, AnyTokenPayload as u, TokenScope as v };