@escro/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,170 @@
+import { TaskSpec, EscrowState, EscrowAccount } from '@escro/shared';
+export { AcceptanceCriterion, DeliverableFormat, DeliverableType, EscrowAccount, EscrowErrorCode, EscrowState, Network, TaskSpec, TaskType } from '@escro/shared';
+import { Keypair } from '@solana/web3.js';
+
+/** Constructor options for the {@link Escro} client. */
+interface EscroOptions {
+    /** Solana RPC endpoint URL. */
+    rpcUrl: string;
+    /** Escro REST API base URL (e.g. "https://api.escro.ai"). */
+    apiUrl: string;
+    /** Ed25519 keypair used to sign transactions and API requests. */
+    wallet: Keypair;
+}
+/** Parameters for creating a new escrow. */
+interface CreateEscrowParams {
+    /** Full task specification uploaded to IPFS. */
+    taskSpec: TaskSpec;
+    /** Payment amount in μUSDC (1 USDC = 1_000_000). Minimum: 5_000_000. */
+    amountUsdc: number;
+    /** Unix timestamp (seconds) at which the escrow deadline expires. */
+    deadlineSeconds: number;
+    /** Base-58 public key of the worker pre-assigned to this task. */
+    assignedWorker: string;
+}
+/** Return value from {@link Escro.createEscrow}. */
+interface CreateEscrowResult {
+    /** Task ID (32-char hex UUID without hyphens). Used internally by the API. */
+    escrowId: string;
+    /** Base-58 on-chain PDA address. Use this as the identifier for all subsequent calls. */
+    escrowPda: string;
+    /** Solana transaction signature. */
+    signature: string;
+}
+/** Parameters for submitting a deliverable. */
+interface SubmitDeliverableParams {
+    /** SHA-256 hex digest (or content-addressed hash) of the deliverable content. */
+    contentHash: string;
+    /** Optional URI pointing to the deliverable artifact (IPFS, Arweave, etc.). */
+    proofUri?: string;
+}
+/** Parameters for raising a dispute. */
+interface RaiseDisputeParams {
+    /** Human-readable reason for the dispute (max 200 chars). */
+    reason: string;
+    /** Optional URL to evidence supporting the dispute. */
+    evidence?: string;
+}
+/** Options for polling methods. */
+interface PollOptions {
+    /**
+     * Enable polling with exponential backoff.
+     * - 0–5 min: poll every 15 s
+     * - 5–30 min: poll every 30 s
+     * - 30 min–24 h: poll every 60 s
+     * - After 24 h: throws {@link EscrowTimeoutError}
+     * @default false
+     */
+    poll?: boolean;
+    /** Override the default 24-hour polling timeout (ms). */
+    timeoutMs?: number;
+}
+/** Pagination parameters for list queries. */
+interface ListOptions {
+    /** Maximum number of items to return. Default: 20, max: 100. */
+    limit?: number;
+    /** Zero-based offset for pagination. Default: 0. */
+    offset?: number;
+}
+/** Paginated response wrapper. */
+interface PaginatedResult<T> {
+    /** The requested page of items. */
+    items: T[];
+    /** Total number of items matching the query (ignoring pagination). */
+    total: number;
+    /** The effective limit applied to this response. */
+    limit: number;
+    /** The effective offset applied to this response. */
+    offset: number;
+}
+
+declare class Escro {
+    private readonly connection;
+    private readonly api;
+    private readonly options;
+    constructor(options: EscroOptions);
+    /**
+     * Create a new escrow: registers with the API, signs and submits the
+     * on-chain `create_escrow` transaction.
+     *
+     * @returns `{ escrowId, escrowPda, signature }` — use `escrowPda` for all subsequent calls.
+     */
+    createEscrow(params: CreateEscrowParams): Promise<CreateEscrowResult>;
+    /**
+     * Release payment to the worker. Buyer must be the wallet in the constructor.
+     * Updates API DB state, then builds and submits the `release_payment` on-chain tx.
+     *
+     * @returns Solana transaction signature.
+     */
+    releasePayment(address: string): Promise<string>;
+    /**
+     * Raise a dispute for an escrow. Either the buyer or the assigned worker
+     * may call this. Signs and submits the `raise_dispute` on-chain tx.
+     *
+     * @returns Solana transaction signature.
+     */
+    raiseDispute(address: string, params: RaiseDisputeParams): Promise<string>;
+    /**
+     * Cancel a funded escrow before any worker has claimed it.
+     * Buyer must be the wallet in the constructor. Only valid when state is `FUNDED`.
+     * Signs and submits the `cancel_escrow` on-chain tx; full USDC refund to buyer.
+     *
+     * @returns Solana transaction signature.
+     */
+    cancelEscrow(address: string): Promise<string>;
+    /**
+     * Claim an assigned task. Worker must be the wallet in the constructor.
+     * Signs and submits the `claim_task` on-chain tx.
+     *
+     * @returns Solana transaction signature.
+     */
+    claimTask(address: string): Promise<string>;
+    /**
+     * Submit a deliverable for oracle evaluation. Worker must be the wallet.
+     * Signs and submits the `submit_deliverable` on-chain tx.
+     *
+     * @returns Solana transaction signature.
+     */
+    submitDeliverable(address: string, params: SubmitDeliverableParams): Promise<string>;
+    /**
+     * List tasks assigned to the wallet's public key.
+     * Optionally filter by state(s) and paginate results.
+     *
+     * If `options.poll` is true, polls with exponential backoff until at least
+     * one task is returned.
+     *
+     * @param state   - Filter by one or more states (first state used as API filter).
+     * @param options - Polling, pagination (limit/offset).
+     */
+    getMyTasks(state?: EscrowState[], options?: PollOptions & ListOptions): Promise<PaginatedResult<EscrowAccount>>;
+    /**
+     * Fetch an escrow by its PDA address.
+     * If `options.poll` is true, polls with exponential backoff until the escrow
+     * appears (useful immediately after a create tx before the API DB syncs).
+     */
+    getEscrow(address: string, options?: PollOptions): Promise<EscrowAccount>;
+}
+
+/** Base class for all errors thrown by the @escro/sdk. */
+declare class EscroError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/** The requested escrow was not found (HTTP 404). */
+declare class EscrowNotFoundError extends EscroError {
+    constructor(address: string);
+}
+/** The operation is not valid for the escrow's current state (HTTP 409). */
+declare class EscrowStateError extends EscroError {
+    constructor(message: string);
+}
+/** Polling timed out after 24 hours without reaching the expected state. */
+declare class EscrowTimeoutError extends EscroError {
+    constructor(address: string);
+}
+/** The caller is not authorized to perform this action (HTTP 401/403). */
+declare class UnauthorizedError extends EscroError {
+    constructor(message?: string);
+}
+
+export { type CreateEscrowParams, type CreateEscrowResult, Escro, EscroError, type EscroOptions, EscrowNotFoundError, EscrowStateError, EscrowTimeoutError, type ListOptions, type PaginatedResult, type PollOptions, type RaiseDisputeParams, type SubmitDeliverableParams, UnauthorizedError };

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { TaskSpec, EscrowState, EscrowAccount } from '@escro/shared';
+export { AcceptanceCriterion, DeliverableFormat, DeliverableType, EscrowAccount, EscrowErrorCode, EscrowState, Network, TaskSpec, TaskType } from '@escro/shared';
+import { Keypair } from '@solana/web3.js';
+
+/** Constructor options for the {@link Escro} client. */
+interface EscroOptions {
+    /** Solana RPC endpoint URL. */
+    rpcUrl: string;
+    /** Escro REST API base URL (e.g. "https://api.escro.ai"). */
+    apiUrl: string;
+    /** Ed25519 keypair used to sign transactions and API requests. */
+    wallet: Keypair;
+}
+/** Parameters for creating a new escrow. */
+interface CreateEscrowParams {
+    /** Full task specification uploaded to IPFS. */
+    taskSpec: TaskSpec;
+    /** Payment amount in μUSDC (1 USDC = 1_000_000). Minimum: 5_000_000. */
+    amountUsdc: number;
+    /** Unix timestamp (seconds) at which the escrow deadline expires. */
+    deadlineSeconds: number;
+    /** Base-58 public key of the worker pre-assigned to this task. */
+    assignedWorker: string;
+}
+/** Return value from {@link Escro.createEscrow}. */
+interface CreateEscrowResult {
+    /** Task ID (32-char hex UUID without hyphens). Used internally by the API. */
+    escrowId: string;
+    /** Base-58 on-chain PDA address. Use this as the identifier for all subsequent calls. */
+    escrowPda: string;
+    /** Solana transaction signature. */
+    signature: string;
+}
+/** Parameters for submitting a deliverable. */
+interface SubmitDeliverableParams {
+    /** SHA-256 hex digest (or content-addressed hash) of the deliverable content. */
+    contentHash: string;
+    /** Optional URI pointing to the deliverable artifact (IPFS, Arweave, etc.). */
+    proofUri?: string;
+}
+/** Parameters for raising a dispute. */
+interface RaiseDisputeParams {
+    /** Human-readable reason for the dispute (max 200 chars). */
+    reason: string;
+    /** Optional URL to evidence supporting the dispute. */
+    evidence?: string;
+}
+/** Options for polling methods. */
+interface PollOptions {
+    /**
+     * Enable polling with exponential backoff.
+     * - 0–5 min: poll every 15 s
+     * - 5–30 min: poll every 30 s
+     * - 30 min–24 h: poll every 60 s
+     * - After 24 h: throws {@link EscrowTimeoutError}
+     * @default false
+     */
+    poll?: boolean;
+    /** Override the default 24-hour polling timeout (ms). */
+    timeoutMs?: number;
+}
+/** Pagination parameters for list queries. */
+interface ListOptions {
+    /** Maximum number of items to return. Default: 20, max: 100. */
+    limit?: number;
+    /** Zero-based offset for pagination. Default: 0. */
+    offset?: number;
+}
+/** Paginated response wrapper. */
+interface PaginatedResult<T> {
+    /** The requested page of items. */
+    items: T[];
+    /** Total number of items matching the query (ignoring pagination). */
+    total: number;
+    /** The effective limit applied to this response. */
+    limit: number;
+    /** The effective offset applied to this response. */
+    offset: number;
+}
+
+declare class Escro {
+    private readonly connection;
+    private readonly api;
+    private readonly options;
+    constructor(options: EscroOptions);
+    /**
+     * Create a new escrow: registers with the API, signs and submits the
+     * on-chain `create_escrow` transaction.
+     *
+     * @returns `{ escrowId, escrowPda, signature }` — use `escrowPda` for all subsequent calls.
+     */
+    createEscrow(params: CreateEscrowParams): Promise<CreateEscrowResult>;
+    /**
+     * Release payment to the worker. Buyer must be the wallet in the constructor.
+     * Updates API DB state, then builds and submits the `release_payment` on-chain tx.
+     *
+     * @returns Solana transaction signature.
+     */
+    releasePayment(address: string): Promise<string>;
+    /**
+     * Raise a dispute for an escrow. Either the buyer or the assigned worker
+     * may call this. Signs and submits the `raise_dispute` on-chain tx.
+     *
+     * @returns Solana transaction signature.
+     */
+    raiseDispute(address: string, params: RaiseDisputeParams): Promise<string>;
+    /**
+     * Cancel a funded escrow before any worker has claimed it.
+     * Buyer must be the wallet in the constructor. Only valid when state is `FUNDED`.
+     * Signs and submits the `cancel_escrow` on-chain tx; full USDC refund to buyer.
+     *
+     * @returns Solana transaction signature.
+     */
+    cancelEscrow(address: string): Promise<string>;
+    /**
+     * Claim an assigned task. Worker must be the wallet in the constructor.
+     * Signs and submits the `claim_task` on-chain tx.
+     *
+     * @returns Solana transaction signature.
+     */
+    claimTask(address: string): Promise<string>;
+    /**
+     * Submit a deliverable for oracle evaluation. Worker must be the wallet.
+     * Signs and submits the `submit_deliverable` on-chain tx.
+     *
+     * @returns Solana transaction signature.
+     */
+    submitDeliverable(address: string, params: SubmitDeliverableParams): Promise<string>;
+    /**
+     * List tasks assigned to the wallet's public key.
+     * Optionally filter by state(s) and paginate results.
+     *
+     * If `options.poll` is true, polls with exponential backoff until at least
+     * one task is returned.
+     *
+     * @param state   - Filter by one or more states (first state used as API filter).
+     * @param options - Polling, pagination (limit/offset).
+     */
+    getMyTasks(state?: EscrowState[], options?: PollOptions & ListOptions): Promise<PaginatedResult<EscrowAccount>>;
+    /**
+     * Fetch an escrow by its PDA address.
+     * If `options.poll` is true, polls with exponential backoff until the escrow
+     * appears (useful immediately after a create tx before the API DB syncs).
+     */
+    getEscrow(address: string, options?: PollOptions): Promise<EscrowAccount>;
+}
+
+/** Base class for all errors thrown by the @escro/sdk. */
+declare class EscroError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+/** The requested escrow was not found (HTTP 404). */
+declare class EscrowNotFoundError extends EscroError {
+    constructor(address: string);
+}
+/** The operation is not valid for the escrow's current state (HTTP 409). */
+declare class EscrowStateError extends EscroError {
+    constructor(message: string);
+}
+/** Polling timed out after 24 hours without reaching the expected state. */
+declare class EscrowTimeoutError extends EscroError {
+    constructor(address: string);
+}
+/** The caller is not authorized to perform this action (HTTP 401/403). */
+declare class UnauthorizedError extends EscroError {
+    constructor(message?: string);
+}
+
+export { type CreateEscrowParams, type CreateEscrowResult, Escro, EscroError, type EscroOptions, EscrowNotFoundError, EscrowStateError, EscrowTimeoutError, type ListOptions, type PaginatedResult, type PollOptions, type RaiseDisputeParams, type SubmitDeliverableParams, UnauthorizedError };