@arcaresearch/sdk 0.1.61 → 0.1.63

package/dist/arca.js

@@ -26,6 +26,18 @@ const DEFAULT_BASE_URL = 'https://api.arcaos.io';
 const REFRESH_BUFFER_MS = 30_000; // refresh 30s before expiry
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const TYPEID_RE = /^[a-z]{2,63}_[0-9a-hjkmnp-tv-z]{26}$/i;
+/**
+ * Validate that a path argument starts with '/'.
+ * Paths without a trailing slash target a single object.
+ * Paths with a trailing slash aggregate all objects under that prefix.
+ */
+function validatePath(path) {
+    if (!path.startsWith('/')) {
+        throw new Error(`Path must start with '/'. Got: "${path}". ` +
+            `Use a trailing slash for aggregation (e.g., '/users/alice/') ` +
+            `or an exact path for a single object (e.g., '/users/alice/main').`);
+    }
+}
 function isIdFormat(value) {
     return UUID_RE.test(value) || TYPEID_RE.test(value);
 }
@@ -310,13 +322,21 @@ class Arca {
         return this.client.get(`/objects/${objectId}`);
     }
     /**
-     * List Arca objects, optionally filtered by path prefix.
+     * List Arca objects, optionally filtered by path.
+     *
+     * @param opts.path - Object path or path prefix to filter by.
+     *   Exact path (no trailing slash): returns the single matching object.
+     *   Path prefix (trailing slash): returns all objects under that prefix.
+     *   Examples: '/users/alice/main' (single), '/users/alice/' (subtree)
      */
     async listObjects(opts) {
         await this.ready();
         const params = { realmId: this.realmId() };
-        if (opts?.prefix)
-            params.prefix = opts.prefix;
+        const p = opts?.path ?? opts?.prefix;
+        if (p) {
+            validatePath(p);
+            params.prefix = p;
+        }
         if (opts?.includeDeleted)
             params.includeDeleted = 'true';
         return this.client.get('/objects', params);
@@ -339,13 +359,17 @@ class Arca {
     }
     /**
      * Browse Arca objects in a folder-like structure.
-     * Returns folders (path prefixes) and objects at the given prefix.
+     * Returns folders (path segments) and objects at the given path.
+     *
+     * @param opts.path - Path prefix to browse (default: '/'). Must end with '/'.
      */
     async browseObjects(opts) {
         await this.ready();
+        const p = opts?.path ?? opts?.prefix ?? '/';
+        validatePath(p);
         const params = {
             realmId: this.realmId(),
-            prefix: opts?.prefix ?? '/',
+            prefix: p,
         };
         if (opts?.includeDeleted)
             params.includeDeleted = 'true';
@@ -543,16 +567,18 @@ class Arca {
      * inline inside an operation call, as each invocation produces a new
      * unique path and defeats idempotency.
      *
-     * @param prefix - Path prefix (e.g. '/op/transfer/fund')
-     * @param separator - Override separator between prefix and nonce number.
-     *   Default: '/' if prefix ends with '/', otherwise '-'.
+     * @param path - Path prefix for nonce generation (e.g. '/op/transfer/fund').
+     *   Always used as a prefix — the nonce number is appended.
+     * @param separator - Override separator between path and nonce number.
+     *   Default: '/' if path ends with '/', otherwise '-'.
      *   Use ':' for operation nonces (e.g. '/op/create/wallets/main:1').
      */
-    async nonce(prefix, separator) {
+    async nonce(path, separator) {
+        validatePath(path);
         await this.ready();
         const body = {
             realmId: this.realmId(),
-            prefix,
+            prefix: path,
         };
         if (separator !== undefined) {
             body.separator = separator;
@@ -571,47 +597,66 @@ class Arca {
     }
     // ---- Aggregation & P&L ----
     /**
-     * Get aggregated valuation for all objects under a path prefix.
-     * Pass `asOf` to get historical aggregation at a past timestamp.
-     */
-    async getPathAggregation(prefix, options) {
+     * Get aggregated valuation for objects at a path.
+     *
+     * @param path - Object path or path prefix.
+     *   Exact path (no trailing slash): returns valuation for a single object.
+     *   Path prefix (trailing slash): returns aggregated valuation for all objects under that prefix.
+     *   Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
+     * @param options.asOf - ISO timestamp for historical aggregation.
+     */
+    async getPathAggregation(path, options) {
+        validatePath(path);
         await this.ready();
         const params = {
             realmId: this.realmId(),
-            prefix,
+            prefix: path,
         };
         if (options?.asOf)
             params.asOf = options.asOf;
         return this.client.get('/objects/aggregate', params);
     }
     /**
-     * Get P&L (profit and loss) for objects under a path prefix over a time range.
-     * Returns starting/ending equity, net inflows/outflows, and calculated P&L.
-     */
-    async getPnl(prefix, from, to) {
+     * Get P&L (profit and loss) for objects at a path over a time range.
+     *
+     * @param path - Object path or path prefix.
+     *   Exact path (no trailing slash): returns P&L for a single object.
+     *   Path prefix (trailing slash): returns aggregated P&L for all objects under that prefix.
+     *   Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
+     * @param from - ISO timestamp for the start of the range.
+     * @param to - ISO timestamp for the end of the range.
+     */
+    async getPnl(path, from, to) {
+        validatePath(path);
         await this.ready();
         return this.client.get('/objects/pnl', {
             realmId: this.realmId(),
-            prefix,
+            prefix: path,
             from,
             to,
         });
     }
     /**
-     * Get P&L history (time-series) for objects under a path prefix.
-     * Returns P&L and equity values sampled evenly over the time range,
-     * adjusted for external flows (deposits/withdrawals).
-     * The `points` parameter controls how many samples (default 200, max 1000).
-     */
-    async getPnlHistory(prefix, from, to, points = 200) {
-        const key = (0, cache_1.buildCacheKey)('pnlHistory', { prefix, from, to, points: String(points) });
+     * Get P&L history (time-series) for objects at a path.
+     *
+     * @param path - Object path or path prefix.
+     *   Exact path (no trailing slash): returns P&L history for a single object.
+     *   Path prefix (trailing slash): returns aggregated P&L history for all objects under that prefix.
+     *   Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
+     * @param from - ISO timestamp for the start of the range.
+     * @param to - ISO timestamp for the end of the range.
+     * @param points - Number of samples (default 200, max 1000).
+     */
+    async getPnlHistory(path, from, to, points = 200) {
+        validatePath(path);
+        const key = (0, cache_1.buildCacheKey)('pnlHistory', { prefix: path, from, to, points: String(points) });
         const cached = this.historyCache.get(key);
         if (cached)
             return cached;
         await this.ready();
         const result = await this.client.get('/objects/pnl/history', {
             realmId: this.realmId(),
-            prefix,
+            prefix: path,
             from,
             to,
             points: String(points),
@@ -620,19 +665,26 @@ class Arca {
         return result;
     }
     /**
-     * Get equity history (time-series) for objects under a path prefix.
-     * Returns equity values sampled evenly over the time range.
-     * The `points` parameter controls how many samples (default 200, max 1000).
-     */
-    async getEquityHistory(prefix, from, to, points = 200) {
-        const key = (0, cache_1.buildCacheKey)('equityHistory', { prefix, from, to, points: String(points) });
+     * Get equity history (time-series) for objects at a path.
+     *
+     * @param path - Object path or path prefix.
+     *   Exact path (no trailing slash): returns equity history for a single object.
+     *   Path prefix (trailing slash): returns aggregated equity history for all objects under that prefix.
+     *   Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
+     * @param from - ISO timestamp for the start of the range.
+     * @param to - ISO timestamp for the end of the range.
+     * @param points - Number of samples (default 200, max 1000).
+     */
+    async getEquityHistory(path, from, to, points = 200) {
+        validatePath(path);
+        const key = (0, cache_1.buildCacheKey)('equityHistory', { prefix: path, from, to, points: String(points) });
         const cached = this.historyCache.get(key);
         if (cached)
             return cached;
         await this.ready();
         const result = await this.client.get('/objects/aggregate/history', {
             realmId: this.realmId(),
-            prefix,
+            prefix: path,
             from,
             to,
             points: String(points),
@@ -645,18 +697,24 @@ class Arca {
      * aggregation updates. The last point reflects the current live equity;
      * when the interval boundary crosses, the live point is promoted to
      * historical and a new live point starts.
+     *
+     * @param path - Object path or path prefix.
+     *   Exact path (no trailing slash): chart for a single object.
+     *   Path prefix (trailing slash): chart aggregated across all objects under that prefix.
+     *   Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
      */
-    async watchEquityChart(prefix, from, to, points = 200, options) {
+    async watchEquityChart(path, from, to, points = 200, options) {
+        validatePath(path);
         await this.ready();
         const exchange = options?.exchange ?? 'sim';
         let history;
         try {
-            history = await this.getEquityHistory(prefix, from, to, points);
+            history = await this.getEquityHistory(path, from, to, points);
         }
         catch {
             history = { equityPoints: [], resolution: undefined };
         }
-        const aggStream = await this.watchAggregation([{ type: 'prefix', value: prefix }], { exchange });
+        const aggStream = await this.watchAggregation([{ type: 'prefix', value: path }], { exchange });
         return new streams_1.EquityChartStream(history.equityPoints, aggStream, history.resolution);
     }
     /**
@@ -664,13 +722,19 @@ class Arca {
      * aggregation updates and operation events. The rightmost point updates on
      * each aggregation event. Operation events (deposits/transfers) update
      * cumulative flows client-side — zero additional server reads.
+     *
+     * @param path - Object path or path prefix.
+     *   Exact path (no trailing slash): P&L chart for a single object.
+     *   Path prefix (trailing slash): P&L chart aggregated across all objects under that prefix.
+     *   Examples: '/users/alice/main' (single object), '/users/alice/' (all of alice's objects)
      */
-    async watchPnlChart(prefix, from, to, points = 200, options) {
+    async watchPnlChart(path, from, to, points = 200, options) {
+        validatePath(path);
         await this.ready();
         const exchange = options?.exchange ?? 'sim';
-        const history = await this.getPnlHistory(prefix, from, to, points);
-        const aggStream = await this.watchAggregation([{ type: 'prefix', value: prefix }], { exchange });
-        return new streams_1.PnlChartStream(history.pnlPoints, history.externalFlows, history.startingEquityUsd, history.midPrices ?? {}, prefix, aggStream, this.ws, history.resolution);
+        const history = await this.getPnlHistory(path, from, to, points);
+        const aggStream = await this.watchAggregation([{ type: 'prefix', value: path }], { exchange });
+        return new streams_1.PnlChartStream(history.pnlPoints, history.externalFlows, history.startingEquityUsd, history.midPrices ?? {}, path, aggStream, this.ws, history.resolution);
     }
     /**
      * Create an aggregation watch that tracks a set of sources.
@@ -837,7 +901,6 @@ class Arca {
             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);
             },
@@ -933,7 +996,6 @@ class Arca {
             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);
             },
@@ -963,7 +1025,8 @@ class Arca {
     }
     /**
      * Watch fills (trade history) for an exchange Arca object.
-     * Returns a live-updating stream that combines an initial REST snapshot with
+     * Resolves the object path from `objectId`, creates a path-scoped watch,
+     * then combines an initial REST snapshot with live `exchange.fill` and
      * `fill.recorded` WebSocket events. Each update contains a platform-level
      * `Fill` with P&L, fee breakdown, direction, and resulting position.
      *
@@ -976,20 +1039,17 @@ class Arca {
      */
     async watchFills(objectId, opts) {
         await this.ready();
-        let objectPath;
-        try {
-            const obj = await this.getObject(objectId);
-            objectPath = obj.path;
-        }
-        catch { /* path matching is best-effort */ }
+        const obj = await this.getObject(objectId);
+        const objectPath = obj.path;
         const stream = new streams_1.FillWatchStream(this.ws, () => this.listFills(objectId, opts), objectId, objectPath);
         await stream.ready();
         return stream;
     }
     /**
-     * Subscribe to real-time funding payment events for an exchange Arca object.
-     * Each update includes the ``FundingPayment`` and its ``EventEnvelope``
-     * for correlation tracing.
+     * Watch real-time funding payment events for an exchange Arca object.
+     * Resolves the object path from `objectId`, creates a path-scoped watch,
+     * then streams `exchange.funding` events. Each update includes the
+     * `FundingPayment` and its `EventEnvelope` for correlation tracing.
      *
      * ```ts
      * const stream = await arca.watchFunding('obj_...');
@@ -1001,12 +1061,8 @@ class Arca {
      */
     async watchFunding(objectId) {
         await this.ready();
-        let objectPath;
-        try {
-            const obj = await this.getObject(objectId);
-            objectPath = obj.path;
-        }
-        catch { /* path matching is best-effort */ }
+        const obj = await this.getObject(objectId);
+        const objectPath = obj.path;
         const stream = new streams_1.FundingWatchStream(this.ws, objectId, objectPath);
         await stream.ready();
         return stream;
@@ -1129,30 +1185,33 @@ class Arca {
         return stream;
     }
     /**
-     * Subscribe to real-time operation events.
-     * Server sends an initial snapshot of recent operations, then streams
-     * creates and updates. Returns an {@link OperationWatchStream}.
-     * Call `.close()` when done.
+     * Watch real-time operation events under a path prefix.
+     * Creates a path-scoped watch; server sends a `watch_snapshot` with
+     * recent operations, then streams `operation.created` / `operation.updated`.
+     * Returns an {@link OperationWatchStream}. Call `.close()` when done.
+     *
+     * @param path - Arca path prefix to watch (default: "/" for all operations)
      */
-    async watchOperations() {
+    async watchOperations(path = '/') {
         await this.ready();
-        const stream = new streams_1.OperationWatchStream(this.ws, 'operations', async () => {
-            const res = await this.listOperations();
+        const stream = new streams_1.OperationWatchStream(this.ws, path, async () => {
+            const res = await this.listOperations(path !== '/' ? { path } : undefined);
             return res.operations;
         });
         await stream.ready();
         return stream;
     }
     /**
-     * Subscribe to real-time balance updates.
-     * Server sends an initial snapshot of all balances, then streams updates.
-     * Optionally filter by an Arca path prefix. Call `.close()` when done.
+     * Watch real-time balance updates under a path prefix.
+     * Creates a path-scoped watch; server sends a `watch_snapshot` with
+     * current balances (four-bucket summary), then streams `balance.updated`.
+     * Call `.close()` when done.
      *
-     * @param arcaRef - Optional path filter (e.g. "/wallets/main")
+     * @param path - Arca path prefix to watch (default: "/" for all balances)
      */
-    async watchBalances(arcaRef) {
+    async watchBalances(path = '/') {
         await this.ready();
-        const stream = new streams_1.BalanceWatchStream(this.ws, 'balances', arcaRef, (entityId) => this.getBalances(entityId));
+        const stream = new streams_1.BalanceWatchStream(this.ws, path, (entityId) => this.getBalances(entityId));
         await stream.ready();
         return stream;
     }
@@ -1168,9 +1227,13 @@ class Arca {
         });
     }
     /**
-     * Subscribe to real-time valuation updates for a single Arca object.
-     * Uses the same computation path as aggregation watches (Axiom 10).
-     * Call `.close()` when done.
+     * Watch real-time valuation updates for a single Arca object.
+     * Creates a path-scoped watch with an aggregation watch for valuation;
+     * server sends `watch_snapshot` with initial valuation, then streams
+     * `object.valuation` events. Uses the same computation path as
+     * aggregation watches (Axiom 10). Call `.close()` when done.
+     *
+     * @param path - Arca object path (e.g. "/users/alice/main")
      */
     async watchObject(path) {
         await this.ready();
@@ -1236,6 +1299,7 @@ class Arca {
     /**
      * Watch the exchange state for an exchange Arca object, including positions,
      * open orders, and pending intents (order operations in flight).
+     * Resolves the object path from `objectId` and creates a path-scoped watch.
      *
      * Pending intents are the exchange equivalent of transfer holds: they signal
      * that an order has been submitted but the venue hasn't confirmed it yet.
@@ -1243,7 +1307,9 @@ class Arca {
      */
     async watchExchangeState(objectId) {
         await this.ready();
-        return new streams_1.ExchangeWatchStream(this.ws, objectId, (id) => this.getExchangeState(id));
+        const obj = await this.getObject(objectId);
+        const objectPath = obj.path;
+        return new streams_1.ExchangeWatchStream(this.ws, objectPath, objectId, (id) => this.getExchangeState(id));
     }
     // ---- Auto-tracking ----
     _autoTrackOps;
@@ -1303,7 +1369,7 @@ class Arca {
         const start = Date.now();
         let polls = 0;
         this.ws.ensureConnected();
-        this.ws.subscribe(['operations']);
+        this.ws.watchPath('/').catch(() => { });
         const checkPending = async () => {
             const res = await this.listOperations();
             polls++;
@@ -1338,6 +1404,7 @@ class Arca {
                 clearTimeout(timer);
                 clearInterval(safetyPoll);
                 this.ws.off(types_1.EventType.OperationUpdated, handler);
+                this.ws.unwatchPath('/');
             };
             const handler = async () => {
                 if (settled)
@@ -1382,7 +1449,7 @@ class Arca {
     async waitForOperation(operationId, timeoutMs = 30000) {
         await this.ready();
         this.ws.ensureConnected();
-        this.ws.subscribe(['operations']);
+        this.ws.watchPath('/').catch(() => { });
         const RECONCILIATION_INTERVAL = 5000;
         return new Promise((resolve, reject) => {
             let settled = false;
@@ -1402,6 +1469,7 @@ class Arca {
                 clearTimeout(timeout);
                 clearInterval(reconciliationPoll);
                 this.ws.off(types_1.EventType.OperationUpdated, handler);
+                this.ws.unwatchPath('/');
             };
             const isTerminal = (s) => s !== 'pending';
             const tryResolve = (op) => {