@arcaresearch/sdk 0.0.2 → 0.0.4

package/dist/arca.d.ts

@@ -1,3 +1,4 @@
+import { OperationHandle, OrderHandle } from './operation-handle';
 import { ArcaConfig, ArcaObject, ArcaObjectBrowseResponse, ArcaObjectDetailResponse, ArcaObjectListResponse, ArcaObjectVersionsResponse, ArcaBalance, AggregationSourceDto, BrowseObjectsOptions, CreateArcaObjectResponse, CreateArcaOptions, CreateDenominatedArcaOptions, CreateWatchResponse, DeleteArcaObjectResponse, DepositOptions, EnsureDeletedOptions, WithdrawalOptions, InitiateWithdrawalResponse, EventCallback, EventDetailResponse, EventSubscription, EventSubscriptionOptions, ExplorerSummary, InitiateDepositResponse, ListObjectsOptions, ListEventsOptions, ListOperationsOptions, EventListResponse, NonceResponse, Operation, OperationDetailResponse, OperationListResponse, OrderOperationResponse, PathAggregation, PnlResponse, EquityHistoryResponse, ReconciliationStateListResponse, SnapshotBalancesResponse, StateDeltaListResponse, TransferOptions, TransferResponse, CancelOrderOptions, CreatePerpsExchangeOptions, PlaceOrderOptions, UpdateLeverageOptions, UpdateLeverageResponse, LeverageSetting, ExchangeState, SimOrder, SimOrderWithFills, SimPosition, SimMetaResponse, SimMidsResponse, SimBookResponse, InvariantCheckResponse, ActiveAssetData, CandleInterval, CandlesResponse, CreatePaymentLinkOptions, CreatePaymentLinkResponse, ListPaymentLinksOptions, PaymentLinkListResponse } from './types';
 import { WebSocketManager } from './websocket';
 /**
@@ -52,29 +53,28 @@ export declare class Arca {
      * If one already exists with matching type/denomination, it is returned.
      * Otherwise a new one is created.
      *
-     * Pass `operationPath` (from the nonce API with separator ":") for
-     * explicit operation-level idempotency, especially when delete+recreate
-     * scenarios are expected.
+     * `await` waits for the object to be fully created (operation completed).
+     * Use `.submitted` to access the HTTP response before the operation settles.
      */
-    createDenominatedArca(opts: CreateDenominatedArcaOptions): Promise<CreateArcaObjectResponse>;
+    createDenominatedArca(opts: CreateDenominatedArcaOptions): OperationHandle<CreateArcaObjectResponse>;
     /**
      * Create an Arca object of any type at the given path (idempotent).
      *
-     * Pass `operationPath` (from the nonce API with separator ":") for
-     * explicit operation-level idempotency.
+     * `await` waits for the object to be fully created (operation completed).
+     * Use `.submitted` to access the HTTP response before the operation settles.
      */
-    createArca(opts: CreateArcaOptions): Promise<CreateArcaObjectResponse>;
+    createArca(opts: CreateArcaOptions): OperationHandle<CreateArcaObjectResponse>;
     /** @deprecated Use createDenominatedArca instead */
-    ensureDenominatedArca(opts: CreateDenominatedArcaOptions): Promise<CreateArcaObjectResponse>;
+    ensureDenominatedArca(opts: CreateDenominatedArcaOptions): OperationHandle<CreateArcaObjectResponse>;
     /** @deprecated Use createArca instead */
-    ensureArca(opts: CreateArcaOptions): Promise<CreateArcaObjectResponse>;
+    ensureArca(opts: CreateArcaOptions): OperationHandle<CreateArcaObjectResponse>;
     /**
      * Delete an Arca object by path. If sweepTo is provided, remaining funds
      * are transferred to that Arca before deletion.
      *
      * If the object is already deleted, returns the existing state.
      */
-    ensureDeleted(opts: EnsureDeletedOptions): Promise<DeleteArcaObjectResponse>;
+    ensureDeleted(opts: EnsureDeletedOptions): OperationHandle<DeleteArcaObjectResponse>;
     /**
      * Get an Arca object by path.
      */
@@ -111,22 +111,25 @@ export declare class Arca {
     getSnapshotBalances(objectId: string, asOf: string): Promise<SnapshotBalancesResponse>;
     /**
      * Execute a transfer between two Arca objects.
-     * Settlement is immediate for denominated targets, or async for
-     * targets that require a receiver workflow (e.g. exchange objects).
+     * Settlement is immediate for denominated targets (await resolves instantly),
+     * or async for exchange targets (await waits for settlement).
      * The operation path serves as the idempotency key.
      */
-    transfer(opts: TransferOptions): Promise<TransferResponse>;
+    transfer(opts: TransferOptions): OperationHandle<TransferResponse>;
     /**
      * Initiate a deposit to a denominated Arca object.
      * In demo realms, deposits are simulated with a configurable delay.
+     *
+     * `await` waits for deposit settlement. Use `.submitted` to access
+     * the poolAddress and other response data before settlement.
      */
-    deposit(opts: DepositOptions): Promise<InitiateDepositResponse>;
+    deposit(opts: DepositOptions): OperationHandle<InitiateDepositResponse>;
     /**
      * Initiate a withdrawal from a denominated Arca object to an on-chain address.
      * Requires custody service (on-chain mode) to be active.
      */
-    withdrawal(opts: WithdrawalOptions): Promise<InitiateWithdrawalResponse>;
-    createPaymentLink(opts: CreatePaymentLinkOptions): Promise<CreatePaymentLinkResponse>;
+    withdrawal(opts: WithdrawalOptions): OperationHandle<InitiateWithdrawalResponse>;
+    createPaymentLink(opts: CreatePaymentLinkOptions): OperationHandle<CreatePaymentLinkResponse>;
     listPaymentLinks(opts?: ListPaymentLinksOptions): Promise<PaymentLinkListResponse>;
     /**
      * Get operation detail by ID (includes correlated events and deltas).
@@ -208,7 +211,7 @@ export declare class Arca {
      * Create a Perps Exchange Arca object.
      * Automatically sets type=exchange, denomination=USD, and exchangeType metadata.
      */
-    createPerpsExchange(opts: CreatePerpsExchangeOptions): Promise<CreateArcaObjectResponse>;
+    createPerpsExchange(opts: CreatePerpsExchangeOptions): OperationHandle<CreateArcaObjectResponse>;
     /**
      * Get exchange account state (equity, margin, positions, orders).
      */
@@ -238,8 +241,11 @@ export declare class Arca {
     /**
      * Place an order on an exchange Arca object.
      * The operation path serves as the idempotency key.
+     *
+     * Returns an OrderHandle: `await` waits for placement. Use `.filled()`,
+     * `.onFill()`, `.fills()` for fill lifecycle, and `.cancel()` to cancel.
      */
-    placeOrder(opts: PlaceOrderOptions): Promise<OrderOperationResponse>;
+    placeOrder(opts: PlaceOrderOptions): OrderHandle;
     /**
      * List orders for an exchange Arca object.
      */
@@ -252,7 +258,7 @@ export declare class Arca {
      * Cancel an order on an exchange Arca object.
      * The operation path serves as the idempotency key.
      */
-    cancelOrder(opts: CancelOrderOptions): Promise<OrderOperationResponse>;
+    cancelOrder(opts: CancelOrderOptions): OperationHandle<OrderOperationResponse>;
     /**
      * List positions for an exchange Arca object.
      */
@@ -282,11 +288,11 @@ export declare class Arca {
      */
     checkInvariants(limit?: number): Promise<InvariantCheckResponse>;
     /**
-     * Poll until all operations in the realm have reached a terminal state.
-     * Useful after a batch of async operations (deposits, exchange transfers)
-     * to wait for settlement before running invariant checks.
+     * Wait until all operations in the realm have reached a terminal state.
+     * Uses WebSocket events to react to completions instantly, with periodic
+     * HTTP polls as a safety net.
      *
-     * @param opts.intervalMs - Polling interval in ms (default: 1000)
+     * @param opts.intervalMs - Safety-net poll interval in ms (default: 5000)
      * @param opts.timeoutMs - Max wait time in ms (default: 120000)
      * @param opts.onPoll - Optional callback with the current pending count
      * @returns The number of polls performed
@@ -298,11 +304,17 @@ export declare class Arca {
     }): Promise<number>;
     /**
      * Wait for a specific operation to reach a terminal state.
-     * Uses WebSocket events to resolve immediately when the operation updates.
+     * Auto-connects the WebSocket and subscribes to the operations channel
+     * so callers don't need to manage the connection manually.
      * If the WS event arrives without embedded operation data (enrichment failure),
      * fetches the operation via HTTP as a fallback.
      */
     waitForOperation(operationId: string, timeoutMs?: number): Promise<Operation>;
+    /**
+     * Wrap a mutation HTTP call in an OperationHandle.
+     * Defers ready() + throwIfOperationFailed into the promise chain.
+     */
+    private op;
     private realmId;
     private throwIfOperationFailed;
     private resolveRealm;

package/dist/arca.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arca.d.ts","sourceRoot":"","sources":["../src/arca.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"arca.d.ts","sourceRoot":"","sources":["../src/arca.ts"],"names":[],"mappings":"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"}

package/dist/arca.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Arca = void 0;
 const client_1 = require("./client");
 const errors_1 = require("./errors");
+const operation_handle_1 = require("./operation-handle");
 const types_1 = require("./types");
 const websocket_1 = require("./websocket");
 const DEFAULT_BASE_URL = 'https://api.arcaos.io';
@@ -146,44 +147,41 @@ class Arca {
      * If one already exists with matching type/denomination, it is returned.
      * Otherwise a new one is created.
      *
-     * Pass `operationPath` (from the nonce API with separator ":") for
-     * explicit operation-level idempotency, especially when delete+recreate
-     * scenarios are expected.
+     * `await` waits for the object to be fully created (operation completed).
+     * Use `.submitted` to access the HTTP response before the operation settles.
      */
-    async createDenominatedArca(opts) {
-        await this.ready();
-        return this.client.post('/objects', {
+    createDenominatedArca(opts) {
+        return this.op(() => this.client.post('/objects', {
             realmId: this.realmId(),
             path: opts.ref,
             type: 'denominated',
             denomination: opts.denomination,
             metadata: opts.metadata ?? null,
             operationPath: opts.operationPath ?? null,
-        });
+        }));
     }
     /**
      * Create an Arca object of any type at the given path (idempotent).
      *
-     * Pass `operationPath` (from the nonce API with separator ":") for
-     * explicit operation-level idempotency.
+     * `await` waits for the object to be fully created (operation completed).
+     * Use `.submitted` to access the HTTP response before the operation settles.
      */
-    async createArca(opts) {
-        await this.ready();
-        return this.client.post('/objects', {
+    createArca(opts) {
+        return this.op(() => this.client.post('/objects', {
             realmId: this.realmId(),
             path: opts.ref,
             type: opts.type,
             denomination: opts.denomination ?? null,
             metadata: opts.metadata ?? null,
             operationPath: opts.operationPath ?? null,
-        });
+        }));
     }
     /** @deprecated Use createDenominatedArca instead */
-    async ensureDenominatedArca(opts) {
+    ensureDenominatedArca(opts) {
         return this.createDenominatedArca(opts);
     }
     /** @deprecated Use createArca instead */
-    async ensureArca(opts) {
+    ensureArca(opts) {
         return this.createArca(opts);
     }
     /**
@@ -192,15 +190,14 @@ class Arca {
      *
      * If the object is already deleted, returns the existing state.
      */
-    async ensureDeleted(opts) {
-        await this.ready();
-        return this.client.post('/objects/delete', {
+    ensureDeleted(opts) {
+        return this.op(() => this.client.post('/objects/delete', {
             realmId: this.realmId(),
             path: opts.ref,
             sweepToPath: opts.sweepTo ?? null,
             liquidatePositions: opts.liquidatePositions ?? false,
             operationPath: opts.operationPath ?? null,
-        });
+        }));
     }
     /**
      * Get an Arca object by path.
@@ -281,60 +278,55 @@ class Arca {
     // ---- Transfers ----
     /**
      * Execute a transfer between two Arca objects.
-     * Settlement is immediate for denominated targets, or async for
-     * targets that require a receiver workflow (e.g. exchange objects).
+     * Settlement is immediate for denominated targets (await resolves instantly),
+     * or async for exchange targets (await waits for settlement).
      * The operation path serves as the idempotency key.
      */
-    async transfer(opts) {
-        await this.ready();
-        const response = await this.client.post('/transfer', {
+    transfer(opts) {
+        return this.op(() => this.client.post('/transfer', {
             realmId: this.realmId(),
             path: opts.path,
             sourceArcaPath: opts.from,
             targetArcaPath: opts.to,
             amount: opts.amount,
-        });
-        this.throwIfOperationFailed(response.operation);
-        return response;
+        }));
     }
     // ---- Deposits ----
     /**
      * Initiate a deposit to a denominated Arca object.
      * In demo realms, deposits are simulated with a configurable delay.
+     *
+     * `await` waits for deposit settlement. Use `.submitted` to access
+     * the poolAddress and other response data before settlement.
      */
-    async deposit(opts) {
-        await this.ready();
-        const response = await this.client.post('/deposit', {
+    deposit(opts) {
+        return this.op(() => this.client.post('/deposit', {
             realmId: this.realmId(),
             arcaPath: opts.arcaRef,
             amount: opts.amount,
             path: opts.path ?? null,
             senderAddress: opts.senderAddress ?? null,
-        });
-        this.throwIfOperationFailed(response.operation);
-        return response;
+            durationSeconds: opts.durationSeconds ?? null,
+            willSucceed: opts.willSucceed ?? null,
+        }));
     }
     // ---- Withdrawals ----
     /**
      * Initiate a withdrawal from a denominated Arca object to an on-chain address.
      * Requires custody service (on-chain mode) to be active.
      */
-    async withdrawal(opts) {
-        await this.ready();
-        const response = await this.client.post('/withdrawal', {
+    withdrawal(opts) {
+        return this.op(() => this.client.post('/withdrawal', {
             realmId: this.realmId(),
             arcaPath: opts.arcaPath,
             amount: opts.amount,
             destinationAddress: opts.destinationAddress ?? '',
             path: opts.path ?? null,
-        });
-        this.throwIfOperationFailed(response.operation);
-        return response;
+        }));
     }
     // ---- Payment Links ----
-    async createPaymentLink(opts) {
-        await this.ready();
-        return this.client.post('/payment-links', {
+    createPaymentLink(opts) {
+        return this.op(() => this.client.post('/payment-links', {
             realmId: this.realmId(),
             type: opts.type,
             arcaPath: opts.arcaRef,
@@ -342,7 +334,7 @@ class Arca {
             returnUrl: opts.returnUrl ?? null,
             expiresInMinutes: opts.expiresInMinutes ?? null,
             metadata: opts.metadata ? JSON.stringify(opts.metadata) : null,
-        });
+        }));
     }
     async listPaymentLinks(opts) {
         await this.ready();
@@ -526,16 +518,15 @@ class Arca {
      * Create a Perps Exchange Arca object.
      * Automatically sets type=exchange, denomination=USD, and exchangeType metadata.
      */
-    async createPerpsExchange(opts) {
-        await this.ready();
-        return this.client.post('/objects', {
+    createPerpsExchange(opts) {
+        return this.op(() => this.client.post('/objects', {
             realmId: this.realmId(),
             path: opts.ref,
             type: 'exchange',
             denomination: 'USD',
             metadata: JSON.stringify({ exchangeType: opts.exchangeType || 'hyperliquid' }),
             operationPath: opts.operationPath,
-        });
+        }));
     }
     /**
      * Get exchange account state (equity, margin, positions, orders).
@@ -590,10 +581,12 @@ class Arca {
     /**
      * Place an order on an exchange Arca object.
      * The operation path serves as the idempotency key.
+     *
+     * Returns an OrderHandle: `await` waits for placement. Use `.filled()`,
+     * `.onFill()`, `.fills()` for fill lifecycle, and `.cancel()` to cancel.
      */
-    async placeOrder(opts) {
-        await this.ready();
-        const response = await this.client.post(`/objects/${opts.objectId}/exchange/orders`, {
+    placeOrder(opts) {
+        const httpCall = this.ready().then(() => this.client.post(`/objects/${opts.objectId}/exchange/orders`, {
             realmId: this.realmId(),
             path: opts.path,
             coin: opts.coin,
@@ -607,9 +600,21 @@ class Arca {
             timeInForce: opts.timeInForce ?? 'GTC',
             ...(opts.builderFeeBps != null && { builderFeeBps: opts.builderFeeBps }),
             ...(opts.feeTargets != null && { feeTargets: opts.feeTargets }),
+        })).then(response => {
+            this.throwIfOperationFailed(response.operation);
+            return response;
         });
-        this.throwIfOperationFailed(response.operation);
-        return response;
+        const deps = {
+            getOrder: (objectId, orderId) => this.getOrder(objectId, orderId),
+            onFillEvent: (handler) => {
+                this.ws.ensureConnected();
+                this.ws.subscribe(['exchange']);
+                this.ws.on(types_1.EventType.ExchangeFill, handler);
+                return () => this.ws.off(types_1.EventType.ExchangeFill, handler);
+            },
+            cancelOrder: (cancelOpts) => this.cancelOrder(cancelOpts),
+        };
+        return new operation_handle_1.OrderHandle(httpCall, (id, timeout) => this.waitForOperation(id, timeout), opts.objectId, opts.path, deps);
     }
     /**
      * List orders for an exchange Arca object.
@@ -632,15 +637,14 @@ class Arca {
      * Cancel an order on an exchange Arca object.
      * The operation path serves as the idempotency key.
      */
-    async cancelOrder(opts) {
-        await this.ready();
-        const params = new URLSearchParams({
-            realmId: this.realmId(),
-            path: opts.path,
+    cancelOrder(opts) {
+        return this.op(() => {
+            const params = new URLSearchParams({
+                realmId: this.realmId(),
+                path: opts.path,
+            });
+            return this.client.delete(`/objects/${opts.objectId}/exchange/orders/${opts.orderId}?${params.toString()}`);
         });
-        const response = await this.client.delete(`/objects/${opts.objectId}/exchange/orders/${opts.orderId}?${params.toString()}`);
-        this.throwIfOperationFailed(response.operation);
-        return response;
     }
     /**
      * List positions for an exchange Arca object.
@@ -695,43 +699,89 @@ class Arca {
         return this.client.get('/internal/invariant-check', params);
     }
     /**
-     * Poll until all operations in the realm have reached a terminal state.
-     * Useful after a batch of async operations (deposits, exchange transfers)
-     * to wait for settlement before running invariant checks.
+     * Wait until all operations in the realm have reached a terminal state.
+     * Uses WebSocket events to react to completions instantly, with periodic
+     * HTTP polls as a safety net.
      *
-     * @param opts.intervalMs - Polling interval in ms (default: 1000)
+     * @param opts.intervalMs - Safety-net poll interval in ms (default: 5000)
      * @param opts.timeoutMs - Max wait time in ms (default: 120000)
      * @param opts.onPoll - Optional callback with the current pending count
      * @returns The number of polls performed
      */
     async waitForQuiescence(opts) {
         await this.ready();
-        const interval = opts?.intervalMs ?? 1000;
+        const interval = opts?.intervalMs ?? 5000;
         const timeout = opts?.timeoutMs ?? 120_000;
         const start = Date.now();
         let polls = 0;
-        while (true) {
+        this.ws.ensureConnected();
+        this.ws.subscribe(['operations']);
+        const checkPending = async () => {
             const res = await this.listOperations();
-            const pending = res.operations.filter(op => op.state === 'pending');
             polls++;
+            const pending = res.operations.filter(op => op.state === 'pending');
             opts?.onPoll?.(pending.length);
-            if (pending.length === 0)
-                return polls;
+            return pending.length;
+        };
+        let pendingCount = await checkPending();
+        if (pendingCount === 0)
+            return polls;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error(`Timed out waiting for quiescence after ${timeout}ms. ` +
+                    `${pendingCount} operations still pending.`));
+            }, timeout);
+            const safetyPoll = setInterval(async () => {
+                if (settled)
+                    return;
+                try {
+                    pendingCount = await checkPending();
+                    if (pendingCount === 0) {
+                        cleanup();
+                        resolve(polls);
+                    }
+                }
+                catch { /* ignore, will retry */ }
+            }, interval);
+            const cleanup = () => {
+                settled = true;
+                clearTimeout(timer);
+                clearInterval(safetyPoll);
+                this.ws.off(types_1.EventType.OperationUpdated, handler);
+            };
+            const handler = async () => {
+                if (settled)
+                    return;
+                try {
+                    pendingCount = await checkPending();
+                    if (pendingCount === 0) {
+                        cleanup();
+                        resolve(polls);
+                    }
+                }
+                catch { /* ignore */ }
+            };
+            this.ws.on(types_1.EventType.OperationUpdated, handler);
             if (Date.now() - start > timeout) {
-                throw new Error(`Timed out waiting for quiescence after ${timeout}ms. ` +
-                    `${pending.length} operations still pending.`);
+                cleanup();
+                reject(new Error(`Timed out waiting for quiescence after ${timeout}ms. ` +
+                    `${pendingCount} operations still pending.`));
             }
-            await new Promise(r => setTimeout(r, interval));
-        }
+        });
     }
     /**
      * Wait for a specific operation to reach a terminal state.
-     * Uses WebSocket events to resolve immediately when the operation updates.
+     * Auto-connects the WebSocket and subscribes to the operations channel
+     * so callers don't need to manage the connection manually.
      * If the WS event arrives without embedded operation data (enrichment failure),
      * fetches the operation via HTTP as a fallback.
      */
     async waitForOperation(operationId, timeoutMs = 30000) {
         await this.ready();
+        this.ws.ensureConnected();
+        this.ws.subscribe(['operations']);
         return new Promise((resolve, reject) => {
             let settled = false;
             const timeout = setTimeout(() => {
@@ -785,6 +835,17 @@ class Arca {
         });
     }
     // ---- Internal ----
+    /**
+     * Wrap a mutation HTTP call in an OperationHandle.
+     * Defers ready() + throwIfOperationFailed into the promise chain.
+     */
+    op(httpCall) {
+        const call = this.ready().then(() => httpCall()).then(response => {
+            this.throwIfOperationFailed(response.operation);
+            return response;
+        });
+        return new operation_handle_1.OperationHandle(call, (id, timeout) => this.waitForOperation(id, timeout));
+    }
     realmId() {
         if (!this.resolvedRealmId) {
             throw new Error('Arca SDK not initialized. Call await arca.ready() first.');