@drakkar.software/octobot-client 0.4.0

package/dist/client/connect/readOnly.d.ts

@@ -0,0 +1,97 @@
+import type { Strategy as ProtocolStrategy, UserActionConfiguration } from '@drakkar.software/octobot-protocol';
+import { type ClientSession } from '../core/session.js';
+import type { CallOptions } from '../core/options.js';
+import type { AccountInput } from '../adapters/accounts.js';
+import type { CreateAutomationInput } from '../adapters/automations.js';
+import type { AccountView, AutomationView } from '../core/views.js';
+import { type ReadOnlyDocumentsApi } from '../adapters/documents.js';
+export type { AccountView, AccountKind, AutomationView, Holding } from '../core/views.js';
+export type { AccountInput } from '../adapters/accounts.js';
+export type { CreateAutomationInput } from '../adapters/automations.js';
+/** A write call built its action(s) but never sent them — the session has no
+ *  append rights. `payload` is the QR-encodable `ActionProposal`; a
+ *  privileged client (real append rights) scans/decodes it and executes it
+ *  after a human confirms. See `protocol/proposal.ts`. */
+export interface ProposedAction {
+    actions: UserActionConfiguration[];
+    payload: string;
+}
+/** A session with no append rights (`ops` never includes `'write'`, enforced
+ *  by the node) built from `connectReadOnlyDevice()`. Every write method
+ *  that would normally return an `ActionHandle` returns a `ProposedAction`
+ *  instead — same method names, so a caller migrating between the two client
+ *  kinds doesn't rename anything, just changes what it does with the
+ *  result. */
+export interface ReadOnlyAccountsApi {
+    list(opts?: CallOptions): Promise<AccountView[]>;
+    get(id: string, opts?: CallOptions): Promise<AccountView | null>;
+    create(input: AccountInput, opts?: CallOptions): Promise<ProposedAction>;
+    update(id: string, input: AccountInput, opts?: CallOptions): Promise<ProposedAction>;
+    delete(id: string, opts?: CallOptions): Promise<ProposedAction>;
+    refresh(ids?: string[], opts?: CallOptions): Promise<ProposedAction>;
+}
+export interface ReadOnlyAutomationsApi {
+    list(opts?: CallOptions): Promise<AutomationView[]>;
+    get(id: string, opts?: CallOptions): Promise<AutomationView | null>;
+    create(input: CreateAutomationInput, opts?: CallOptions): Promise<ProposedAction>;
+    update(id: string, input: CreateAutomationInput, opts?: CallOptions): Promise<ProposedAction>;
+    stop(id: string, opts?: CallOptions): Promise<ProposedAction>;
+}
+export interface ReadOnlyStrategiesApi {
+    list(opts?: CallOptions): Promise<ProtocolStrategy[]>;
+    get(id: string, version?: string, opts?: CallOptions): Promise<ProtocolStrategy | null>;
+    create(strategy: ProtocolStrategy, opts?: CallOptions): Promise<ProposedAction>;
+    update(strategy: ProtocolStrategy, opts?: CallOptions): Promise<ProposedAction>;
+    delete(id: string, opts?: CallOptions): Promise<ProposedAction>;
+}
+export type ReadOnlyOctoBotClient = {
+    readonly url: string;
+    readonly userId: string;
+    readonly accounts: ReadOnlyAccountsApi;
+    readonly automations: ReadOnlyAutomationsApi;
+    readonly strategies: ReadOnlyStrategiesApi;
+    /** Escape hatch: `pull` only, and only for a granted collection — an
+     *  ungranted collection throws `OctoBotScopeError` before any network
+     *  request, since this session was never given the key to decrypt it.
+     *  No `push`/`append`: this client has no append rights by design (see
+     *  the accounts/automations/strategies APIs above, which propose instead
+     *  of appending), and `settings`/`node` are not exposed here at all —
+     *  `settings` because the default grant never covers that collection, and
+     *  `node`'s REST endpoints need `basicAuth`, which a pairing payload never
+     *  carries. */
+    readonly documents: ReadOnlyDocumentsApi;
+    close(): void;
+};
+export declare function createReadOnlyOctoBotClient(session: ClientSession): ReadOnlyOctoBotClient;
+export type ConnectReadOnlyOptions = {
+    /** Injected fetch — proxies, mTLS, React Native polyfills, test stubs.
+     *  Default: `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Default per-request timeout, ms. Default 10_000. */
+    timeoutMs?: number;
+};
+/**
+ * Connect to a self-hosted OctoBot node using a read-only pairing payload —
+ * a bearer credential a privileged device minted with `createReadOnlyPairing()`
+ * (`@drakkar.software/octobot-client/identity`), NOT a wallet seed. There is
+ * no seed anywhere on this path.
+ *
+ * The returned client's write methods (`accounts.create/update/delete`,
+ * `automations.create/update/stop`, `strategies.create/update/delete`) never
+ * append anything — this package never calls the node's append endpoint on
+ * this session's behalf. (The node does not yet enforce a cap's `ops` scope
+ * itself — every collection currently grants `self` role by identity alone,
+ * regardless of `ops` — so this is presently a client-side guarantee, not a
+ * node-enforced one; see `OctoBotScopeError`.) Instead they build the
+ * action(s) and return a `ProposedAction`: the built configuration(s) plus a
+ * QR-encodable payload for a privileged device to scan, review, and execute.
+ *
+ * ```ts
+ * const octobot = await connectReadOnlyDevice(pairingPayload)
+ * const accounts = await octobot.accounts.list()                    // works
+ * const proposed = await octobot.automations.stop(automationId)     // builds, doesn't send
+ * console.log(proposed.payload)                                     // render this as a QR
+ * ```
+ */
+export declare function connectReadOnlyDevice(pairingPayload: string, opts?: ConnectReadOnlyOptions): Promise<ReadOnlyOctoBotClient>;
+//# sourceMappingURL=readOnly.d.ts.map

package/dist/client/connect/readOnly.d.ts.map

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

package/dist/client/connect/readOnly.js

@@ -0,0 +1,167 @@
+import { parseReadOnlyPairing } from '../../identity/pairing.js';
+import { SYNC_FETCH_TIMEOUT_MS } from '../../crypto/wireConstants.js';
+import { createReadOnlySession } from '../core/session.js';
+import { createAccountsApi, toAccountGraph, pullAccountsDocument } from '../adapters/accounts.js';
+import { createAutomationsApi } from '../adapters/automations.js';
+import { createStrategiesApi } from '../adapters/strategies.js';
+import { createReadOnlyDocumentsApi } from '../adapters/documents.js';
+import { OctoBotConfigError, rethrowAsOctoBotError } from '../core/errors.js';
+import { accountAuthIdFor, exchangeConfigIdFor, buildCreateAccountConfig, buildEditAccountConfig, buildDeleteAccountConfig, buildRefreshAccountsConfig, buildCreateAccountAuthConfig, buildEditAccountAuthConfig, buildDeleteAccountAuthConfig, buildCreateExchangeConfigConfig, buildEditExchangeConfigConfig, buildDeleteExchangeConfigConfig, buildCreateStrategyConfig, buildEditStrategyConfig, buildDeleteStrategyConfig, buildCreateAutomationConfig, buildEditAutomationConfig, buildStopAutomationConfig, } from '../../protocol/actions.js';
+import { encodeActionProposal } from '../../protocol/proposal.js';
+function proposalOf(actions, label) {
+    return { actions: actions.map((a) => a.configuration), payload: encodeActionProposal(actions, { label }) };
+}
+const neverAppend = () => {
+    throw new Error('read-only client: this session has no append rights, this should never be called');
+};
+function createReadOnlyAccountsApi(session) {
+    const base = createAccountsApi(session, neverAppend);
+    return {
+        list: base.list,
+        get: base.get,
+        async create(input) {
+            const { account, auth, exchangeConfig } = toAccountGraph(input);
+            const entries = [];
+            if (auth)
+                entries.push({ configuration: buildCreateAccountAuthConfig(auth) });
+            if (exchangeConfig)
+                entries.push({ configuration: buildCreateExchangeConfigConfig(exchangeConfig) });
+            entries.push({ configuration: buildCreateAccountConfig(account) });
+            return proposalOf(entries, `Create account "${input.name}"`);
+        },
+        async update(id, input) {
+            const { account, auth, exchangeConfig } = toAccountGraph({ ...input, id });
+            const existing = await pullAccountsDocument(session)
+                .then(({ data }) => (data.accounts ?? []).find((a) => a.id === id))
+                .catch(() => undefined);
+            if (existing?.created_at)
+                account.created_at = existing.created_at;
+            const entries = [];
+            if (auth)
+                entries.push({ configuration: buildEditAccountAuthConfig(auth) });
+            if (exchangeConfig)
+                entries.push({ configuration: buildEditExchangeConfigConfig(exchangeConfig) });
+            entries.push({ configuration: buildEditAccountConfig(id, account) });
+            return proposalOf(entries, `Update account "${input.name}"`);
+        },
+        async delete(id) {
+            return proposalOf([
+                { configuration: buildDeleteAccountConfig(id) },
+                { configuration: buildDeleteAccountAuthConfig(accountAuthIdFor(id)) },
+                { configuration: buildDeleteExchangeConfigConfig(exchangeConfigIdFor(id)) },
+            ], `Delete account ${id}`);
+        },
+        async refresh(accountIds) {
+            return proposalOf([{ configuration: buildRefreshAccountsConfig(accountIds) }], 'Refresh account balances');
+        },
+    };
+}
+function createReadOnlyAutomationsApi(session) {
+    const base = createAutomationsApi(session, neverAppend);
+    return {
+        list: base.list,
+        get: base.get,
+        async create(input) {
+            // Same node-side race `runCreateAutomation` sequences around: the node
+            // resolves `automation_create`'s strategy by (id, version) against its
+            // StrategyProvider, which only the confirmed `strategy_create` fills.
+            // This session can't poll for that confirmation itself (no append
+            // rights) — the executing side must, before appending the second entry.
+            return proposalOf([
+                { configuration: buildCreateStrategyConfig(input.strategy) },
+                { configuration: buildCreateAutomationConfig(input), after: 'previous-confirmed' },
+            ], `Create automation "${input.name}"`);
+        },
+        async update(id, input) {
+            return proposalOf([
+                { configuration: buildEditStrategyConfig(input.strategy) },
+                { configuration: buildEditAutomationConfig({ ...input, automationId: id }) },
+            ], `Update automation "${input.name}"`);
+        },
+        async stop(id) {
+            return proposalOf([{ configuration: buildStopAutomationConfig(id) }], `Stop automation ${id}`);
+        },
+    };
+}
+function createReadOnlyStrategiesApi(session) {
+    const base = createStrategiesApi(session, neverAppend);
+    return {
+        list: base.list,
+        get: base.get,
+        async create(strategy) {
+            return proposalOf([{ configuration: buildCreateStrategyConfig(strategy) }], `Create strategy "${strategy.name}"`);
+        },
+        async update(strategy) {
+            return proposalOf([{ configuration: buildEditStrategyConfig(strategy) }], `Update strategy "${strategy.name}"`);
+        },
+        async delete(id) {
+            return proposalOf([{ configuration: buildDeleteStrategyConfig(id) }], `Delete strategy ${id}`);
+        },
+    };
+}
+export function createReadOnlyOctoBotClient(session) {
+    return {
+        url: session.origin,
+        userId: session.userId,
+        accounts: createReadOnlyAccountsApi(session),
+        automations: createReadOnlyAutomationsApi(session),
+        strategies: createReadOnlyStrategiesApi(session),
+        documents: createReadOnlyDocumentsApi(session),
+        close: () => session.close(),
+    };
+}
+/**
+ * Connect to a self-hosted OctoBot node using a read-only pairing payload —
+ * a bearer credential a privileged device minted with `createReadOnlyPairing()`
+ * (`@drakkar.software/octobot-client/identity`), NOT a wallet seed. There is
+ * no seed anywhere on this path.
+ *
+ * The returned client's write methods (`accounts.create/update/delete`,
+ * `automations.create/update/stop`, `strategies.create/update/delete`) never
+ * append anything — this package never calls the node's append endpoint on
+ * this session's behalf. (The node does not yet enforce a cap's `ops` scope
+ * itself — every collection currently grants `self` role by identity alone,
+ * regardless of `ops` — so this is presently a client-side guarantee, not a
+ * node-enforced one; see `OctoBotScopeError`.) Instead they build the
+ * action(s) and return a `ProposedAction`: the built configuration(s) plus a
+ * QR-encodable payload for a privileged device to scan, review, and execute.
+ *
+ * ```ts
+ * const octobot = await connectReadOnlyDevice(pairingPayload)
+ * const accounts = await octobot.accounts.list()                    // works
+ * const proposed = await octobot.automations.stop(automationId)     // builds, doesn't send
+ * console.log(proposed.payload)                                     // render this as a QR
+ * ```
+ */
+export async function connectReadOnlyDevice(pairingPayload, opts = {}) {
+    let parsed;
+    try {
+        parsed = parseReadOnlyPairing(pairingPayload);
+    }
+    catch (err) {
+        throw new OctoBotConfigError(`invalid read-only pairing payload: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const defaultTimeoutMs = opts.timeoutMs ?? SYNC_FETCH_TIMEOUT_MS;
+    const origin = `${parsed.node.secure ? 'https' : 'http'}://${parsed.node.host}:${parsed.node.port}`;
+    const capProvider = {
+        getCap: async () => ({ cap: parsed.cap, devEdPrivHex: parsed.device.edPriv }),
+        getUserId: async () => parsed.userId,
+    };
+    try {
+        const session = createReadOnlySession({
+            origin,
+            node: parsed.node,
+            userId: parsed.userId,
+            fetch: fetchImpl,
+            defaultTimeoutMs,
+            capProvider,
+            collectionKeys: parsed.collectionKeys,
+        });
+        return createReadOnlyOctoBotClient(session);
+    }
+    catch (err) {
+        rethrowAsOctoBotError(err);
+    }
+}
+//# sourceMappingURL=readOnly.js.map

package/dist/client/connect/readOnly.js.map

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

package/dist/client/core/errors.d.ts

@@ -0,0 +1,80 @@
+import type { SeedDerivation } from './options.js';
+export type OctoBotErrorCode = 'config' | 'unreachable' | 'timeout' | 'unauthorized' | 'http' | 'conflict' | 'action_failed' | 'action_timeout' | 'aborted' | 'forbidden_collection';
+/** Base class for every error this package throws. Every method that can
+ *  fail throws one of these (or lets an `AbortError` DOMException through
+ *  unwrapped, per the platform convention). Switch on `code` rather than
+ *  `instanceof` when the check has to survive across a duplicated package
+ *  instance (a monorepo hoisting quirk, a bundler that doesn't dedupe). */
+export declare class OctoBotError extends Error {
+    readonly code: OctoBotErrorCode;
+    readonly cause?: unknown;
+    constructor(code: OctoBotErrorCode, message: string, cause?: unknown);
+}
+/** Bad `ConnectOptions` — an unparseable `url`, or a `node.*` call made
+ *  without the `basicAuth` credentials it requires. */
+export declare class OctoBotConfigError extends OctoBotError {
+    constructor(message: string);
+}
+/** The node could not be reached at all — offline, wrong port, timed out, or
+ *  the connect-time abort fired. */
+export declare class OctoBotConnectionError extends OctoBotError {
+    constructor(code: 'unreachable' | 'timeout' | 'aborted', message: string, cause?: unknown);
+}
+/** The node answered, but did not authorize this wallet. Carries what the
+ *  seed actually derived to, so the message can name the mismatch instead of
+ *  just saying "unauthorized". */
+export declare class OctoBotAuthError extends OctoBotError {
+    readonly address: string;
+    readonly userId: string;
+    readonly derivation: SeedDerivation;
+    constructor(address: string, userId: string, derivation: SeedDerivation);
+}
+/** A node REST call (`client.node.*`) answered with a non-2xx status. */
+export declare class OctoBotHttpError extends OctoBotError {
+    readonly status: number;
+    constructor(status: number, cause?: unknown);
+}
+/** A document push raced another writer's push — the `baseHash` you pushed
+ *  against is no longer the server's current hash. Pull again and retry. */
+export declare class OctoBotConflictError extends OctoBotError {
+    readonly serverHash: string | null;
+    constructor(serverHash: string | null, cause?: unknown, message?: string);
+}
+/** The node executed a queued action and rejected it. Not retriable by
+ *  resubmitting the same configuration unchanged. */
+export declare class OctoBotActionError extends OctoBotError {
+    readonly phase?: string;
+    readonly detail: string | null;
+    constructor(detail: string | null, phase?: string, cause?: unknown);
+}
+/** `ActionHandle.settled()` gave up waiting — the node never confirmed
+ *  within the timeout budget. Not necessarily a failure; the action may
+ *  still complete. */
+export declare class OctoBotTimeoutError extends OctoBotError {
+    readonly phase?: string;
+    constructor(phase?: string, cause?: unknown);
+}
+/** A read-only session tried to read/write a collection its pairing grant
+ *  doesn't cover — thrown client-side, before any network request, by
+ *  `ClientSession.collectionEncryptor()`. This is not merely a courtesy: the
+ *  node does not yet enforce a cap's collection scope itself (every
+ *  collection is currently `readRoles=["self"], writeRoles=["self"]`, which
+ *  a device cap always satisfies regardless of its `scope`), so this
+ *  client-side check is presently the ONLY thing keeping a read-only session
+ *  inside its granted collections. */
+export declare class OctoBotScopeError extends OctoBotError {
+    readonly collection: string;
+    constructor(collection: string);
+}
+export declare function isOctoBotError(e: unknown): e is OctoBotError;
+/** Translate a raw transport/orchestration error into the public
+ *  `OctoBotError` hierarchy. Does NOT touch an `AbortError` — see
+ *  `rethrowAsOctoBotError` below, which every `client.*` method's catch
+ *  actually calls. */
+export declare function toOctoBotError(err: unknown): OctoBotError;
+/** What every `client.*` method's `catch` block calls. Lets an `AbortError`
+ *  DOMException through unwrapped (the platform convention a caller's own
+ *  `signal` handling already expects) and wraps everything else as an
+ *  `OctoBotError`. */
+export declare function rethrowAsOctoBotError(err: unknown): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/client/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/client/core/errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,aAAa,GACb,SAAS,GACT,cAAc,GACd,MAAM,GACN,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,SAAS,GACT,sBAAsB,CAAA;AAE1B;;;;2EAI2E;AAC3E,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAA;gBACrB,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMrE;AAED;uDACuD;AACvD,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED;oCACoC;AACpC,qBAAa,sBAAuB,SAAQ,YAAY;gBAC1C,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAI1F;AAED;;kCAEkC;AAClC,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAA;gBACvB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc;CAYxE;AAED,yEAAyE;AACzE,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;gBACX,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK5C;AAED;4EAC4E;AAC5E,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;gBACtB,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,SAAiE;CAKjI;AAED;qDACqD;AACrD,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;gBAClB,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMnE;AAED;;sBAEsB;AACtB,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;gBACX,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK5C;AAED;;;;;;;sCAOsC;AACtC,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;gBACf,UAAU,EAAE,MAAM;CAK/B;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,YAAY,CAE5D;AAED;;;sBAGsB;AACtB,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAuBzD;AAED;;;sBAGsB;AACtB,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAGzD"}

package/dist/client/core/errors.js

@@ -0,0 +1,154 @@
+import { StarfishHttpError, ConflictError } from '@drakkar.software/starfish-client';
+import { NodeHttpError } from '../../transport/rest.js';
+import { AutomationActionFailedError, AutomationTimeoutError } from '../../protocol/orchestration/createAutomation.js';
+/** Base class for every error this package throws. Every method that can
+ *  fail throws one of these (or lets an `AbortError` DOMException through
+ *  unwrapped, per the platform convention). Switch on `code` rather than
+ *  `instanceof` when the check has to survive across a duplicated package
+ *  instance (a monorepo hoisting quirk, a bundler that doesn't dedupe). */
+export class OctoBotError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'OctoBotError';
+        this.code = code;
+        this.cause = cause;
+    }
+}
+/** Bad `ConnectOptions` — an unparseable `url`, or a `node.*` call made
+ *  without the `basicAuth` credentials it requires. */
+export class OctoBotConfigError extends OctoBotError {
+    constructor(message) {
+        super('config', message);
+        this.name = 'OctoBotConfigError';
+    }
+}
+/** The node could not be reached at all — offline, wrong port, timed out, or
+ *  the connect-time abort fired. */
+export class OctoBotConnectionError extends OctoBotError {
+    constructor(code, message, cause) {
+        super(code, message, cause);
+        this.name = 'OctoBotConnectionError';
+    }
+}
+/** The node answered, but did not authorize this wallet. Carries what the
+ *  seed actually derived to, so the message can name the mismatch instead of
+ *  just saying "unauthorized". */
+export class OctoBotAuthError extends OctoBotError {
+    address;
+    userId;
+    derivation;
+    constructor(address, userId, derivation) {
+        super('unauthorized', `the node did not authorize ${address} (derived under '${derivation}'). ` +
+            `If this seed phrase was generated by an app using a non-standard derivation, ` +
+            `try seedDerivation: 'auto' or the other explicit value.`);
+        this.name = 'OctoBotAuthError';
+        this.address = address;
+        this.userId = userId;
+        this.derivation = derivation;
+    }
+}
+/** A node REST call (`client.node.*`) answered with a non-2xx status. */
+export class OctoBotHttpError extends OctoBotError {
+    status;
+    constructor(status, cause) {
+        super('http', `Node request failed: HTTP ${status}`, cause);
+        this.name = 'OctoBotHttpError';
+        this.status = status;
+    }
+}
+/** A document push raced another writer's push — the `baseHash` you pushed
+ *  against is no longer the server's current hash. Pull again and retry. */
+export class OctoBotConflictError extends OctoBotError {
+    serverHash;
+    constructor(serverHash, cause, message = 'push conflict: the document changed since it was last pulled') {
+        super('conflict', message, cause);
+        this.name = 'OctoBotConflictError';
+        this.serverHash = serverHash;
+    }
+}
+/** The node executed a queued action and rejected it. Not retriable by
+ *  resubmitting the same configuration unchanged. */
+export class OctoBotActionError extends OctoBotError {
+    phase;
+    detail;
+    constructor(detail, phase, cause) {
+        super('action_failed', `action failed${detail ? `: ${detail}` : ''}`, cause);
+        this.name = 'OctoBotActionError';
+        this.phase = phase;
+        this.detail = detail;
+    }
+}
+/** `ActionHandle.settled()` gave up waiting — the node never confirmed
+ *  within the timeout budget. Not necessarily a failure; the action may
+ *  still complete. */
+export class OctoBotTimeoutError extends OctoBotError {
+    phase;
+    constructor(phase, cause) {
+        super('action_timeout', 'timed out waiting for the node to confirm', cause);
+        this.name = 'OctoBotTimeoutError';
+        this.phase = phase;
+    }
+}
+/** A read-only session tried to read/write a collection its pairing grant
+ *  doesn't cover — thrown client-side, before any network request, by
+ *  `ClientSession.collectionEncryptor()`. This is not merely a courtesy: the
+ *  node does not yet enforce a cap's collection scope itself (every
+ *  collection is currently `readRoles=["self"], writeRoles=["self"]`, which
+ *  a device cap always satisfies regardless of its `scope`), so this
+ *  client-side check is presently the ONLY thing keeping a read-only session
+ *  inside its granted collections. */
+export class OctoBotScopeError extends OctoBotError {
+    collection;
+    constructor(collection) {
+        super('forbidden_collection', `read-only session: no key granted for collection "${collection}"`);
+        this.name = 'OctoBotScopeError';
+        this.collection = collection;
+    }
+}
+export function isOctoBotError(e) {
+    return e instanceof OctoBotError;
+}
+/** Translate a raw transport/orchestration error into the public
+ *  `OctoBotError` hierarchy. Does NOT touch an `AbortError` — see
+ *  `rethrowAsOctoBotError` below, which every `client.*` method's catch
+ *  actually calls. */
+export function toOctoBotError(err) {
+    if (err instanceof OctoBotError)
+        return err;
+    if (err instanceof AutomationActionFailedError)
+        return new OctoBotActionError(err.detail, err.phase, err);
+    if (err instanceof AutomationTimeoutError)
+        return new OctoBotTimeoutError(err.phase, err);
+    if (err instanceof ConflictError) {
+        // The shipped starfish-client exposes the server's authoritative hash
+        // as `.currentHash`, not `.serverHash` — reading the wrong field name
+        // meant `OctoBotConflictError.serverHash`, the documented retry hint,
+        // was silently always null.
+        return new OctoBotConflictError(err.currentHash || null, err);
+    }
+    if (err instanceof StarfishHttpError) {
+        if (err.status === 401 || err.status === 403) {
+            return new OctoBotError('unauthorized', `sync request rejected: HTTP ${err.status}`, err);
+        }
+        return new OctoBotError('http', `sync request failed: HTTP ${err.status}`, err);
+    }
+    if (err instanceof NodeHttpError)
+        return new OctoBotHttpError(err.status, err);
+    // A base OctoBotError here would make `instanceof OctoBotConnectionError`
+    // false on the path most callers actually hit (anything that isn't a
+    // recognized typed error, i.e. "could not reach the node at all") —
+    // README.md documents that class for exactly this case.
+    return new OctoBotConnectionError('unreachable', err instanceof Error ? err.message : String(err), err);
+}
+/** What every `client.*` method's `catch` block calls. Lets an `AbortError`
+ *  DOMException through unwrapped (the platform convention a caller's own
+ *  `signal` handling already expects) and wraps everything else as an
+ *  `OctoBotError`. */
+export function rethrowAsOctoBotError(err) {
+    if (err instanceof DOMException && err.name === 'AbortError')
+        throw err;
+    throw toOctoBotError(err);
+}
+//# sourceMappingURL=errors.js.map

package/dist/client/core/errors.js.map

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

package/dist/client/core/options.d.ts

@@ -0,0 +1,44 @@
+/** A `DerivationScheme.id` (see `identity/derivationSchemes.ts`) or `'auto'`. */
+export type SeedDerivation = string;
+export type ConnectOptions = {
+    /** Node origin: `'http://192.168.1.10:5001'`, `'https://mybot.example.com'`.
+     *  A bare `host` / `host:port` is also accepted (parsed the same way the
+     *  node-pairing flow parses one). */
+    url: string;
+    /** BIP39 seed phrase, or a 0x-prefixed secp256k1 private key. */
+    seed: string;
+    /** Which derivation turns the phrase into the wallet.
+     *  - `'bip44'` (default) — the standard `m/44'/60'/0'/0/0` path, what a
+     *    node's own pairing QR carries. The only scheme this package ships;
+     *    register another via `registerDerivationScheme` for a different
+     *    wallet type and pass its id here.
+     *  - `'auto'` — try every registered scheme, probe the node, keep whichever
+     *    it authorizes. Costs one extra round-trip per scheme; only meaningful
+     *    with `verify: true` (the default). */
+    seedDerivation?: SeedDerivation;
+    /** HTTP Basic credentials for the node's `/api/v1` REST surface. Only a
+     *  node paired by an older QR has these — without them `client.node.wallet`,
+     *  `.dslKeywords` and `.exportWallet`/`.createGenericProcessBot` throw
+     *  `OctoBotConfigError`. */
+    basicAuth?: {
+        address: string;
+        password: string;
+    };
+    /** Injected fetch — proxies, mTLS, React Native polyfills, test stubs.
+     *  Default: `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Default per-request timeout, ms. Default 10_000. */
+    timeoutMs?: number;
+    /** Aborts the connect handshake only — not the returned client. */
+    signal?: AbortSignal;
+    /** Probe the node and the sync auth before resolving. Default `true`.
+     *  `false` skips all I/O in `connectOctoBot()` — the first real call
+     *  surfaces any problem instead. */
+    verify?: boolean;
+};
+/** Every method that does I/O takes these last. */
+export type CallOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+//# sourceMappingURL=options.d.ts.map

package/dist/client/core/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/client/core/options.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAA;AAEnC,MAAM,MAAM,cAAc,GAAG;IAC3B;;yCAEqC;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;+CAO2C;IAC3C,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B;;;gCAG4B;IAC5B,SAAS,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IACjD;uCACmC;IACnC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;wCAEoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA"}

package/dist/client/core/options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=options.js.map

package/dist/client/core/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/client/core/options.ts"],"names":[],"mappings":""}