@chaoschain/sdk 0.3.1 → 0.3.3

package/dist/index-CL0fidQs.d.ts

@@ -0,0 +1,223 @@
+import { G as GatewayClientConfig, $ as GatewayHealthResponse, g as WorkflowStatus, h as ScoreSubmissionMode, s as PendingWorkResponse, t as WorkEvidenceResponse, q as WorkflowError } from './types-C0Ay90UI.js';
+
+declare class GatewayClient {
+    private gatewayUrl;
+    private timeout;
+    private maxPollTime;
+    private pollInterval;
+    private defaultHeaders?;
+    private auth?;
+    private retryConfig?;
+    constructor(config: GatewayClientConfig);
+    private _resolveTimeout;
+    private _resolveAuthMode;
+    private _buildHeaders;
+    private _classifyStatusCode;
+    private _normalizeError;
+    private _getRetryDelayMs;
+    private _sleep;
+    /**
+     * Make HTTP request to Gateway.
+     * Handles errors and transforms them to Gateway exceptions.
+     */
+    private _request;
+    /**
+     * Parse workflow status from API response.
+     */
+    private _parseWorkflowStatus;
+    healthCheck(): Promise<GatewayHealthResponse>;
+    isHealthy(): Promise<boolean>;
+    /**
+     * Create a work submission workflow.
+     * POST /workflows/work-submission
+     *
+     * SDK prepares inputs; Gateway handles:
+     * - Evidence upload to Arweave
+     * - Transaction submission
+     * - Confirmation waiting
+     *
+     * @param studioAddress - Ethereum address of the studio
+     * @param epoch - Epoch number
+     * @param agentAddress - Ethereum address of the submitting agent
+     * @param dataHash - Bytes32 hash of the work (as hex string)
+     * @param threadRoot - Bytes32 DKG thread root (as hex string)
+     * @param evidenceRoot - Bytes32 evidence Merkle root (as hex string)
+     * @param evidenceContent - Raw evidence bytes (will be base64 encoded)
+     * @param signerAddress - Ethereum address of the signer (must be registered in Gateway)
+     * @returns WorkflowStatus - Initial status of the created workflow
+     */
+    submitWork(studioAddress: string, epoch: number, agentAddress: string, dataHash: string, threadRoot: string, evidenceRoot: string, evidenceContent: Buffer | string, signerAddress: string): Promise<WorkflowStatus>;
+    /**
+     * Create a score submission workflow.
+     * POST /workflows/score-submission
+     *
+     * Supports two modes:
+     * - DIRECT (default): Simple direct scoring, requires workerAddress
+     * - COMMIT_REVEAL: Commit-reveal pattern, requires salt
+     *
+     * @param studioAddress - Ethereum address of the studio
+     * @param epoch - Epoch number
+     * @param validatorAddress - Ethereum address of the validator
+     * @param dataHash - Bytes32 hash of the work being scored (as hex string)
+     * @param scores - Array of dimension scores (0-10000 basis points)
+     * @param signerAddress - Ethereum address of the signer
+     * @param options - Additional options (workerAddress, salt, mode)
+     */
+    submitScore(studioAddress: string, epoch: number, validatorAddress: string, dataHash: string, scores: number[], signerAddress: string, options?: {
+        workerAddress?: string;
+        salt?: string;
+        mode?: ScoreSubmissionMode;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Create a close epoch workflow.
+     * POST /workflows/close-epoch
+     *
+     * This is economically final — cannot be undone.
+     *
+     * @param studioAddress - Ethereum address of the studio
+     * @param epoch - Epoch number to close
+     * @param signerAddress - Ethereum address of the signer
+     */
+    closeEpoch(studioAddress: string, epoch: number, signerAddress: string): Promise<WorkflowStatus>;
+    /**
+     * Get workflow status by ID.
+     * GET /workflows/{id}
+     */
+    getWorkflow(workflowId: string): Promise<WorkflowStatus>;
+    /**
+     * List workflows with optional filters.
+     * GET /workflows?studio=&state=&type=
+     */
+    listWorkflows(options?: {
+        studio?: string;
+        state?: string;
+        workflowType?: string;
+    }): Promise<WorkflowStatus[]>;
+    /**
+     * Poll workflow until it reaches a terminal state.
+     *
+     * @param workflowId - UUID of the workflow
+     * @param options - Polling options
+     * @throws WorkflowFailedError - If workflow reaches FAILED state
+     * @throws GatewayTimeoutError - If maxWait exceeded
+     */
+    waitForCompletion(workflowId: string, options?: {
+        maxWait?: number;
+        pollInterval?: number;
+        onProgress?: (status: WorkflowStatus) => void;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Submit work and wait for completion.
+     */
+    submitWorkAndWait(studioAddress: string, epoch: number, agentAddress: string, dataHash: string, threadRoot: string, evidenceRoot: string, evidenceContent: Buffer | string, signerAddress: string, options?: {
+        onProgress?: (status: WorkflowStatus) => void;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Submit score and wait for completion.
+     */
+    submitScoreAndWait(studioAddress: string, epoch: number, validatorAddress: string, dataHash: string, scores: number[], signerAddress: string, options?: {
+        workerAddress?: string;
+        workAddress?: string;
+        salt?: string;
+        mode?: ScoreSubmissionMode;
+        onProgress?: (status: WorkflowStatus) => void;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Close epoch and wait for completion.
+     */
+    closeEpochAndWait(studioAddress: string, epoch: number, signerAddress: string, options?: {
+        onProgress?: (status: WorkflowStatus) => void;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Fetch pending (unfinalized) work for a studio from the gateway.
+     *
+     * @param studioAddress - 0x-prefixed studio contract address
+     * @param options - Optional limit/offset for pagination
+     * @returns Typed pending work response
+     */
+    getPendingWork(studioAddress: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PendingWorkResponse>;
+    /**
+     * Fetch full evidence graph for a work submission.
+     * Endpoint: GET /v1/work/{hash}/evidence
+     */
+    getWorkEvidence(workHash: string): Promise<WorkEvidenceResponse>;
+}
+
+/**
+ * Exception classes for the ChaosChain SDK.
+ *
+ * This module defines all custom exceptions used throughout the SDK
+ * to provide clear error handling and debugging information.
+ */
+declare class ChaosChainSDKError extends Error {
+    details: Record<string, any>;
+    constructor(message: string, details?: Record<string, any>);
+    toString(): string;
+}
+declare class AgentRegistrationError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class PaymentError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class StorageError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class IntegrityVerificationError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class ContractError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class ValidationError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class ConfigurationError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Options passed when constructing a GatewayError (statusCode, response, category, retryable).
+ */
+interface GatewayErrorDetails {
+    statusCode?: number;
+    response?: Record<string, any>;
+    category?: 'transient' | 'permanent' | 'auth' | 'unknown';
+    retryable?: boolean;
+}
+/**
+ * Base error from Gateway API.
+ */
+declare class GatewayError extends ChaosChainSDKError {
+    readonly statusCode?: number;
+    readonly response?: Record<string, any>;
+    readonly category?: 'transient' | 'permanent' | 'auth' | 'unknown';
+    readonly retryable?: boolean;
+    constructor(message: string, details?: GatewayErrorDetails);
+}
+/**
+ * Failed to connect to Gateway.
+ */
+declare class GatewayConnectionError extends GatewayError {
+    constructor(message: string);
+}
+/**
+ * Gateway request or polling timed out.
+ */
+declare class GatewayTimeoutError extends GatewayError {
+    readonly workflowId: string;
+    readonly lastStatus?: WorkflowStatus;
+    constructor(workflowId: string, message: string, lastStatus?: WorkflowStatus);
+}
+/**
+ * Workflow reached FAILED state.
+ */
+declare class WorkflowFailedError extends GatewayError {
+    readonly workflowId: string;
+    readonly workflowError: WorkflowError;
+    constructor(workflowId: string, error: WorkflowError);
+}
+
+export { AgentRegistrationError as A, ChaosChainSDKError as C, GatewayClient as G, IntegrityVerificationError as I, PaymentError as P, StorageError as S, ValidationError as V, WorkflowFailedError as W, ContractError as a, ConfigurationError as b, GatewayError as c, GatewayConnectionError as d, GatewayTimeoutError as e };

package/dist/index-iUO5l1VD.d.cts

@@ -0,0 +1,223 @@
+import { G as GatewayClientConfig, $ as GatewayHealthResponse, g as WorkflowStatus, h as ScoreSubmissionMode, s as PendingWorkResponse, t as WorkEvidenceResponse, q as WorkflowError } from './types-C0Ay90UI.cjs';
+
+declare class GatewayClient {
+    private gatewayUrl;
+    private timeout;
+    private maxPollTime;
+    private pollInterval;
+    private defaultHeaders?;
+    private auth?;
+    private retryConfig?;
+    constructor(config: GatewayClientConfig);
+    private _resolveTimeout;
+    private _resolveAuthMode;
+    private _buildHeaders;
+    private _classifyStatusCode;
+    private _normalizeError;
+    private _getRetryDelayMs;
+    private _sleep;
+    /**
+     * Make HTTP request to Gateway.
+     * Handles errors and transforms them to Gateway exceptions.
+     */
+    private _request;
+    /**
+     * Parse workflow status from API response.
+     */
+    private _parseWorkflowStatus;
+    healthCheck(): Promise<GatewayHealthResponse>;
+    isHealthy(): Promise<boolean>;
+    /**
+     * Create a work submission workflow.
+     * POST /workflows/work-submission
+     *
+     * SDK prepares inputs; Gateway handles:
+     * - Evidence upload to Arweave
+     * - Transaction submission
+     * - Confirmation waiting
+     *
+     * @param studioAddress - Ethereum address of the studio
+     * @param epoch - Epoch number
+     * @param agentAddress - Ethereum address of the submitting agent
+     * @param dataHash - Bytes32 hash of the work (as hex string)
+     * @param threadRoot - Bytes32 DKG thread root (as hex string)
+     * @param evidenceRoot - Bytes32 evidence Merkle root (as hex string)
+     * @param evidenceContent - Raw evidence bytes (will be base64 encoded)
+     * @param signerAddress - Ethereum address of the signer (must be registered in Gateway)
+     * @returns WorkflowStatus - Initial status of the created workflow
+     */
+    submitWork(studioAddress: string, epoch: number, agentAddress: string, dataHash: string, threadRoot: string, evidenceRoot: string, evidenceContent: Buffer | string, signerAddress: string): Promise<WorkflowStatus>;
+    /**
+     * Create a score submission workflow.
+     * POST /workflows/score-submission
+     *
+     * Supports two modes:
+     * - DIRECT (default): Simple direct scoring, requires workerAddress
+     * - COMMIT_REVEAL: Commit-reveal pattern, requires salt
+     *
+     * @param studioAddress - Ethereum address of the studio
+     * @param epoch - Epoch number
+     * @param validatorAddress - Ethereum address of the validator
+     * @param dataHash - Bytes32 hash of the work being scored (as hex string)
+     * @param scores - Array of dimension scores (0-10000 basis points)
+     * @param signerAddress - Ethereum address of the signer
+     * @param options - Additional options (workerAddress, salt, mode)
+     */
+    submitScore(studioAddress: string, epoch: number, validatorAddress: string, dataHash: string, scores: number[], signerAddress: string, options?: {
+        workerAddress?: string;
+        salt?: string;
+        mode?: ScoreSubmissionMode;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Create a close epoch workflow.
+     * POST /workflows/close-epoch
+     *
+     * This is economically final — cannot be undone.
+     *
+     * @param studioAddress - Ethereum address of the studio
+     * @param epoch - Epoch number to close
+     * @param signerAddress - Ethereum address of the signer
+     */
+    closeEpoch(studioAddress: string, epoch: number, signerAddress: string): Promise<WorkflowStatus>;
+    /**
+     * Get workflow status by ID.
+     * GET /workflows/{id}
+     */
+    getWorkflow(workflowId: string): Promise<WorkflowStatus>;
+    /**
+     * List workflows with optional filters.
+     * GET /workflows?studio=&state=&type=
+     */
+    listWorkflows(options?: {
+        studio?: string;
+        state?: string;
+        workflowType?: string;
+    }): Promise<WorkflowStatus[]>;
+    /**
+     * Poll workflow until it reaches a terminal state.
+     *
+     * @param workflowId - UUID of the workflow
+     * @param options - Polling options
+     * @throws WorkflowFailedError - If workflow reaches FAILED state
+     * @throws GatewayTimeoutError - If maxWait exceeded
+     */
+    waitForCompletion(workflowId: string, options?: {
+        maxWait?: number;
+        pollInterval?: number;
+        onProgress?: (status: WorkflowStatus) => void;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Submit work and wait for completion.
+     */
+    submitWorkAndWait(studioAddress: string, epoch: number, agentAddress: string, dataHash: string, threadRoot: string, evidenceRoot: string, evidenceContent: Buffer | string, signerAddress: string, options?: {
+        onProgress?: (status: WorkflowStatus) => void;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Submit score and wait for completion.
+     */
+    submitScoreAndWait(studioAddress: string, epoch: number, validatorAddress: string, dataHash: string, scores: number[], signerAddress: string, options?: {
+        workerAddress?: string;
+        workAddress?: string;
+        salt?: string;
+        mode?: ScoreSubmissionMode;
+        onProgress?: (status: WorkflowStatus) => void;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Close epoch and wait for completion.
+     */
+    closeEpochAndWait(studioAddress: string, epoch: number, signerAddress: string, options?: {
+        onProgress?: (status: WorkflowStatus) => void;
+    }): Promise<WorkflowStatus>;
+    /**
+     * Fetch pending (unfinalized) work for a studio from the gateway.
+     *
+     * @param studioAddress - 0x-prefixed studio contract address
+     * @param options - Optional limit/offset for pagination
+     * @returns Typed pending work response
+     */
+    getPendingWork(studioAddress: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PendingWorkResponse>;
+    /**
+     * Fetch full evidence graph for a work submission.
+     * Endpoint: GET /v1/work/{hash}/evidence
+     */
+    getWorkEvidence(workHash: string): Promise<WorkEvidenceResponse>;
+}
+
+/**
+ * Exception classes for the ChaosChain SDK.
+ *
+ * This module defines all custom exceptions used throughout the SDK
+ * to provide clear error handling and debugging information.
+ */
+declare class ChaosChainSDKError extends Error {
+    details: Record<string, any>;
+    constructor(message: string, details?: Record<string, any>);
+    toString(): string;
+}
+declare class AgentRegistrationError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class PaymentError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class StorageError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class IntegrityVerificationError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class ContractError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class ValidationError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+declare class ConfigurationError extends ChaosChainSDKError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Options passed when constructing a GatewayError (statusCode, response, category, retryable).
+ */
+interface GatewayErrorDetails {
+    statusCode?: number;
+    response?: Record<string, any>;
+    category?: 'transient' | 'permanent' | 'auth' | 'unknown';
+    retryable?: boolean;
+}
+/**
+ * Base error from Gateway API.
+ */
+declare class GatewayError extends ChaosChainSDKError {
+    readonly statusCode?: number;
+    readonly response?: Record<string, any>;
+    readonly category?: 'transient' | 'permanent' | 'auth' | 'unknown';
+    readonly retryable?: boolean;
+    constructor(message: string, details?: GatewayErrorDetails);
+}
+/**
+ * Failed to connect to Gateway.
+ */
+declare class GatewayConnectionError extends GatewayError {
+    constructor(message: string);
+}
+/**
+ * Gateway request or polling timed out.
+ */
+declare class GatewayTimeoutError extends GatewayError {
+    readonly workflowId: string;
+    readonly lastStatus?: WorkflowStatus;
+    constructor(workflowId: string, message: string, lastStatus?: WorkflowStatus);
+}
+/**
+ * Workflow reached FAILED state.
+ */
+declare class WorkflowFailedError extends GatewayError {
+    readonly workflowId: string;
+    readonly workflowError: WorkflowError;
+    constructor(workflowId: string, error: WorkflowError);
+}
+
+export { AgentRegistrationError as A, ChaosChainSDKError as C, GatewayClient as G, IntegrityVerificationError as I, PaymentError as P, StorageError as S, ValidationError as V, WorkflowFailedError as W, ContractError as a, ConfigurationError as b, GatewayError as c, GatewayConnectionError as d, GatewayTimeoutError as e };

package/dist/index.cjs

@@ -15403,10 +15403,16 @@ var STEP_TYPE_MAP = {
 var Session = class {
   /** Session ID returned by the gateway. */
   sessionId;
-  gatewayUrl;
-  apiKey;
+  /** Epoch number returned by the gateway. */
+  epoch;
+  /** Studio contract address for this session. */
   studioAddress;
+  /** Default agent wallet address for this session. */
   agentAddress;
+  /** URL to view this session's Evidence DAG in the browser. */
+  viewerUrl;
+  gatewayUrl;
+  apiKey;
   studioPolicyVersion;
   workMandateId;
   taskType;
@@ -15414,6 +15420,8 @@ var Session = class {
   /** @internal — use {@link SessionClient.start} to create instances. */
   constructor(opts) {
     this.sessionId = opts.sessionId;
+    this.epoch = opts.epoch;
+    this.viewerUrl = `${opts.gatewayUrl}/v1/sessions/${opts.sessionId}/viewer`;
     this.gatewayUrl = opts.gatewayUrl;
     this.apiKey = opts.apiKey;
     this.lastEventId = opts.lastEventId ?? null;
@@ -15429,7 +15437,12 @@ var Session = class {
    * Automatically generates `event_id`, `timestamp`, and chains `parent_event_ids`
    * from the previous event so the gateway can build a causal DAG.
    *
-   * @param opts - Event details. Only `summary` is required.
+   * @param opts.summary - Human-readable description of what happened (required).
+   * @param opts.event_type - Canonical event type (default: `"artifact_created"`).
+   * @param opts.metadata - Arbitrary key-value metadata attached to the event.
+   * @param opts.agent - Override the session-level agent for this event.
+   *   Pass `{ agent_address, role? }` to emit the event from a different agent.
+   *   Valid roles: `"worker"`, `"verifier"`, `"collaborator"`. Defaults to `"worker"`.
    * @throws Error if the gateway returns a non-2xx status.
    */
   async log(opts) {
@@ -15472,8 +15485,9 @@ var Session = class {
    *
    * Unknown step types fall back to `artifact_created`.
    *
-   * @param stepType - Friendly step name.
+   * @param stepType - Friendly step name (`"planning"`, `"implementing"`, `"testing"`, `"debugging"`, `"completing"`).
    * @param summary - What happened in this step.
+   * @param agent - Optional agent override for this event. Same as `log({ agent })`.
    */
   async step(stepType, summary, agent) {
     const eventType = STEP_TYPE_MAP[stepType] ?? "artifact_created";
@@ -15483,11 +15497,13 @@ var Session = class {
    * Complete the session.
    *
    * Triggers the on-chain WorkSubmission workflow (if the gateway is configured for it)
-   * and returns `workflow_id` + `data_hash` for downstream verification/scoring.
+   * and returns the session result.
    *
-   * @param opts - Optional status (`"completed"` | `"failed"`) and summary.
-   * @returns `{ workflow_id, data_hash }` — both may be `null` if the gateway
-   *          workflow engine is not configured.
+   * @param opts.status - `"completed"` or `"failed"` (default: `"completed"`).
+   * @param opts.summary - Human-readable summary of the session outcome.
+   * @returns `{ workflow_id, data_hash, epoch }` — `workflow_id` and `data_hash`
+   *          may be `null` if the gateway workflow engine is not configured.
+   *          `epoch` is the epoch this session belongs to.
    * @throws Error if the gateway returns a non-2xx status.
    */
   async complete(opts) {
@@ -15497,7 +15513,8 @@ var Session = class {
     const data = await this.post(`/v1/sessions/${this.sessionId}/complete`, body);
     return {
       workflow_id: data.data?.workflow_id ?? null,
-      data_hash: data.data?.data_hash ?? null
+      data_hash: data.data?.data_hash ?? null,
+      epoch: data.data.epoch
     };
   }
   // ---------------------------------------------------------------------------
@@ -15534,8 +15551,16 @@ var SessionClient = class {
    * and complete the session. The gateway persists all events and constructs the
    * Evidence DAG automatically.
    *
-   * @param opts - Session creation parameters.
-   * @returns A live {@link Session} bound to the newly created session ID.
+   * The returned session exposes `session.sessionId`, `session.epoch`,
+   * `session.studioAddress`, and `session.agentAddress`.
+   *
+   * @param opts.studio_address - Studio contract address (required).
+   * @param opts.agent_address - Worker agent wallet address (required).
+   * @param opts.task_type - Task classification: `"feature"`, `"bugfix"`, `"refactor"`, etc. (default: `"general"`).
+   * @param opts.work_mandate_id - Work mandate identifier (default: `"generic-task"`).
+   * @param opts.studio_policy_version - Studio policy version (default: `"engineering-studio-default-v1"`).
+   * @param opts.session_id - Client-provided session ID. Server generates one if omitted.
+   * @returns A live {@link Session} bound to the newly created session ID and epoch.
    * @throws Error if the gateway returns a non-2xx status.
    */
   async start(opts) {
@@ -15572,7 +15597,8 @@ var SessionClient = class {
       agentAddress: opts.agent_address,
       studioPolicyVersion: opts.studio_policy_version ?? "engineering-studio-default-v1",
       workMandateId: opts.work_mandate_id ?? "generic-task",
-      taskType: opts.task_type ?? "general"
+      taskType: opts.task_type ?? "general",
+      epoch: data.data.epoch
     });
   }
 };
@@ -16185,7 +16211,7 @@ var ChaosChainSDK = class _ChaosChainSDK {
    * Get SDK version
    */
   getVersion() {
-    return "0.3.1";
+    return "0.3.3";
   }
   /**
    * Get SDK capabilities summary
@@ -16983,7 +17009,7 @@ function verifyWorkEvidence(evidence, context) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.3.1";
+var SDK_VERSION = "0.3.3";
 var ERC8004_VERSION = "1.0";
 var X402_VERSION = "1.0";
 var src_default = ChaosChainSDK;