@drakkar.software/octobot-client 0.4.0

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

@@ -0,0 +1,90 @@
+import type { StarfishCapProvider, StarfishClient } from '@drakkar.software/starfish-client';
+import type { Encryptor } from '@drakkar.software/starfish-protocol';
+import { type KeyDerivation } from '../../identity/capProvider.js';
+import type { NodeEndpoint } from '../../transport/urls.js';
+import type { NodeCredentials } from '../../transport/rest.js';
+import { type NodeCollectionKey } from '../../collections/nodeCollections.js';
+/** What `ClientSession.capProvider` needs beyond the bare `StarfishCapProvider`
+ *  the sync client itself requires — `connect.ts`'s `finalize()` also reads
+ *  `getUserId()` off it. `WalletCapProvider` satisfies this; so does the
+ *  installed-credential adapter `connectReadOnlyDevice()` builds — a
+ *  read-only session never derives a root key at all, so it can't be a real
+ *  `WalletCapProvider`. */
+export interface SessionCapProvider extends StarfishCapProvider {
+    getUserId(): Promise<string>;
+}
+/** Everything a `client/*.ts` API module (`accounts.ts`, `automations.ts`,
+ *  `strategies.ts`, `settings.ts`, `actionHandle.ts`, `documents.ts`) closes
+ *  over. Both a full-wallet session (`createSession`) and a read-only
+ *  pairing session (`createReadOnlySession`) satisfy this — the two differ
+ *  only in what `collectionEncryptor` can do, which is exactly the point:
+ *  it is the single place collection-scope enforcement lives.
+ *
+ *  `seed`/`derivation`/`address` are deliberately NOT here — they belong to
+ *  `WalletClientSession` below, read only by `connect.ts`. If a shared API
+ *  module ever needs one of those fields, that is a sign it leaked a
+ *  wallet-only assumption into code the read-only path also runs. */
+export type ClientSession = {
+    readonly origin: string;
+    readonly node: NodeEndpoint;
+    readonly userId: string;
+    readonly fetch: typeof fetch;
+    readonly defaultTimeoutMs: number;
+    readonly basicAuth?: NodeCredentials;
+    readonly capProvider: SessionCapProvider;
+    readonly syncClient: StarfishClient;
+    /** Resolve the `Encryptor` for one node collection. A full-wallet session
+     *  can derive this for any collection on demand; a read-only session can
+     *  only do so for the collections its pairing grant actually covers, and
+     *  throws `OctoBotScopeError` for anything else. See `OctoBotScopeError`'s
+     *  doc comment for why this client-side check currently matters more than
+     *  it should. */
+    collectionEncryptor(collection: NodeCollectionKey): Promise<Encryptor>;
+    /** Drops whatever derived-key state this session holds. Does not touch
+     *  in-flight requests. */
+    close(): void;
+};
+/** The full-wallet session `connect.ts` builds, on top of `ClientSession`.
+ *  `address`/`derivation`/`seed`/`walletAddress()` are read only inside
+ *  `connect.ts` itself (to re-derive the wallet address after the cap
+ *  provider resolves `userId`, and to surface `OctoBotClient.address`) —
+ *  nothing in the shared `client/*.ts` API modules touches them. */
+export type WalletClientSession = ClientSession & {
+    readonly address: string;
+    readonly derivation: KeyDerivation;
+    readonly seed: string;
+    /** The EVM address `seed` derives to under `derivation`. Backed by the
+     *  same derived-key cache `collectionEncryptor` uses internally — kept off
+     *  the shared `ClientSession` surface so a read-only session (which has no
+     *  such cache) never needs to fake it. */
+    walletAddress(): Promise<string>;
+};
+export declare function createSession(opts: {
+    origin: string;
+    node: NodeEndpoint;
+    address: string;
+    userId: string;
+    derivation: KeyDerivation;
+    seed: string;
+    fetch: typeof fetch;
+    defaultTimeoutMs: number;
+    basicAuth?: NodeCredentials;
+}): WalletClientSession;
+/** Builds a `ClientSession` for an installed read-only pairing credential —
+ *  no seed, no root key, no `WalletCapProvider`. `capProvider` is a thin
+ *  inline adapter over the already-signed cap-cert the pairing payload
+ *  carries. `collectionKeys` is the payload's per-collection subkey map
+ *  (see `identity/pairing.ts`'s `ReadOnlyPairingPayload.collectionKeys` and
+ *  `crypto/collectionKeys.ts`) — each key decrypts exactly one collection,
+ *  derived one-way from the wallet secret, so this session can never
+ *  reconstruct that secret or decrypt a collection outside the grant. */
+export declare function createReadOnlySession(opts: {
+    origin: string;
+    node: NodeEndpoint;
+    userId: string;
+    fetch: typeof fetch;
+    defaultTimeoutMs: number;
+    capProvider: SessionCapProvider;
+    collectionKeys: Partial<Record<NodeCollectionKey, string>>;
+}): ClientSession;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/client/core/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAA;AAC5F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAA;AACpE,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAGrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAK9D,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAG/F;;;;;2BAK2B;AAC3B,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7B;AAED;;;;;;;;;;qEAUqE;AACrE,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAA;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAA;IACnC;;;;;qBAKiB;IACjB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IACtE;8BAC0B;IAC1B,KAAK,IAAI,IAAI,CAAA;CACd,CAAA;AAED;;;;oEAIoE;AACpE,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;8CAG0C;IAC1C,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACjC,CAAA;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,YAAY,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,aAAa,CAAA;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;CAC5B,GAAG,mBAAmB,CA6BtB;AAED;;;;;;;yEAOyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,YAAY,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,kBAAkB,CAAA;IAC/B,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAA;CAC3D,GAAG,aAAa,CAwBhB"}

package/dist/client/core/session.js

@@ -0,0 +1,72 @@
+import { WalletCapProvider } from '../../identity/capProvider.js';
+import { createKeyCache } from '../../identity/keys.js';
+import { createSyncClient } from '../../transport/syncClient.js';
+import { SYNC_FETCH_TIMEOUT_MS } from '../../crypto/wireConstants.js';
+import { STARFISH_ENCRYPTION_SALT } from '../../crypto/wireConstants.js';
+import { createSecretEncryptor, createRawKeyEncryptor } from '../../crypto/secretEncryptor.js';
+import { decodeCollectionKey } from '../../crypto/collectionKeys.js';
+import { NODE_COLLECTIONS } from '../../collections/nodeCollections.js';
+import { OctoBotScopeError } from './errors.js';
+export function createSession(opts) {
+    const capProvider = new WalletCapProvider(opts.seed, opts.derivation);
+    const keyCache = createKeyCache();
+    const syncClient = createSyncClient({
+        origin: opts.origin,
+        capProvider,
+        fetch: opts.fetch,
+        timeoutMs: opts.defaultTimeoutMs || SYNC_FETCH_TIMEOUT_MS,
+    });
+    return {
+        origin: opts.origin,
+        node: opts.node,
+        address: opts.address,
+        userId: opts.userId,
+        derivation: opts.derivation,
+        seed: opts.seed,
+        fetch: opts.fetch,
+        defaultTimeoutMs: opts.defaultTimeoutMs,
+        basicAuth: opts.basicAuth,
+        capProvider,
+        syncClient,
+        async collectionEncryptor(collection) {
+            const secret = await keyCache.getEncryptionKey(opts.seed, opts.derivation);
+            return createSecretEncryptor(secret, STARFISH_ENCRYPTION_SALT, NODE_COLLECTIONS[collection].encryptionInfo);
+        },
+        walletAddress: () => keyCache.getWalletAddress(opts.seed, opts.derivation),
+        close: () => keyCache.clear(),
+    };
+}
+/** Builds a `ClientSession` for an installed read-only pairing credential —
+ *  no seed, no root key, no `WalletCapProvider`. `capProvider` is a thin
+ *  inline adapter over the already-signed cap-cert the pairing payload
+ *  carries. `collectionKeys` is the payload's per-collection subkey map
+ *  (see `identity/pairing.ts`'s `ReadOnlyPairingPayload.collectionKeys` and
+ *  `crypto/collectionKeys.ts`) — each key decrypts exactly one collection,
+ *  derived one-way from the wallet secret, so this session can never
+ *  reconstruct that secret or decrypt a collection outside the grant. */
+export function createReadOnlySession(opts) {
+    const syncClient = createSyncClient({
+        origin: opts.origin,
+        capProvider: opts.capProvider,
+        fetch: opts.fetch,
+        timeoutMs: opts.defaultTimeoutMs || SYNC_FETCH_TIMEOUT_MS,
+    });
+    return {
+        origin: opts.origin,
+        node: opts.node,
+        userId: opts.userId,
+        fetch: opts.fetch,
+        defaultTimeoutMs: opts.defaultTimeoutMs,
+        capProvider: opts.capProvider,
+        syncClient,
+        async collectionEncryptor(collection) {
+            const key = opts.collectionKeys[collection];
+            if (key === undefined)
+                throw new OctoBotScopeError(collection);
+            return createRawKeyEncryptor(decodeCollectionKey(key));
+        },
+        // No derived-key cache on this path — nothing to drop.
+        close: () => { },
+    };
+}
+//# sourceMappingURL=session.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/client/core/session.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAsB,MAAM,+BAA+B,CAAA;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAGhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AACrE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACxE,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAC9F,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,EAAE,gBAAgB,EAA0B,MAAM,sCAAsC,CAAA;AAC/F,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AA4D/C,MAAM,UAAU,aAAa,CAAC,IAU7B;IACC,MAAM,WAAW,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;IACrE,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAA;IACjC,MAAM,UAAU,GAAG,gBAAgB,CAAC;QAClC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,WAAW;QACX,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,gBAAgB,IAAI,qBAAqB;KAC1D,CAAC,CAAA;IAEF,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,WAAW;QACX,UAAU;QACV,KAAK,CAAC,mBAAmB,CAAC,UAAU;YAClC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;YAC1E,OAAO,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC,cAAc,CAAC,CAAA;QAC7G,CAAC;QACD,aAAa,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC;QAC1E,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE;KAC9B,CAAA;AACH,CAAC;AAED;;;;;;;yEAOyE;AACzE,MAAM,UAAU,qBAAqB,CAAC,IAQrC;IACC,MAAM,UAAU,GAAG,gBAAgB,CAAC;QAClC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,gBAAgB,IAAI,qBAAqB;KAC1D,CAAC,CAAA;IAEF,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU;QACV,KAAK,CAAC,mBAAmB,CAAC,UAAU;YAClC,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,CAAA;YAC3C,IAAI,GAAG,KAAK,SAAS;gBAAE,MAAM,IAAI,iBAAiB,CAAC,UAAU,CAAC,CAAA;YAC9D,OAAO,qBAAqB,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAA;QACxD,CAAC;QACD,uDAAuD;QACvD,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;KAChB,CAAA;AACH,CAAC"}

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

@@ -0,0 +1,40 @@
+import type { Account as ProtocolAccount, ExchangeConfig, AutomationState, UserAction } from '@drakkar.software/octobot-protocol';
+import { type AutomationRunStatus, type Holding } from '../../protocol/state.js';
+export type { Holding };
+export type AccountKind = 'exchange' | 'wallet' | 'generic';
+/** A friendlier read of a node-reported account. `raw` is the untouched
+ *  protocol record — nothing here is hidden or lossy, this just saves every
+ *  caller from re-deriving the same handful of fields. */
+export type AccountView = {
+    id: string;
+    name: string;
+    type: AccountKind;
+    /** Resolved through `exchange_configs` — undefined for non-exchange kinds. */
+    exchange?: string;
+    simulated: boolean;
+    /** `false` when the node's own validation marked this account invalid
+     *  (bad credentials, unreachable venue, …). */
+    connected: boolean;
+    holdings: Holding[];
+    raw: ProtocolAccount;
+};
+export declare function accountViewOf(na: ProtocolAccount, exchangeConfigs: ExchangeConfig[]): AccountView;
+/** A friendlier read of a node-reported automation. `raw` is the untouched
+ *  protocol record. `strategy` is recovered from the action history — the
+ *  node's own `AutomationState` carries no strategy reference. */
+export type AutomationView = {
+    id: string;
+    name: string;
+    status: AutomationRunStatus;
+    /** Every exchange account this automation trades through. */
+    accountIds: string[];
+    strategy: {
+        id: string;
+        version?: string;
+    } | null;
+    error: string | null;
+    assets: Holding[];
+    raw: AutomationState;
+};
+export declare function automationViewOf(state: AutomationState, actions: UserAction[]): AutomationView;
+//# sourceMappingURL=views.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../../src/client/core/views.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,IAAI,eAAe,EAC1B,cAAc,EACd,eAAe,EACf,UAAU,EACX,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EAML,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAA;AAEhC,YAAY,EAAE,OAAO,EAAE,CAAA;AAEvB,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE3D;;0DAE0D;AAC1D,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;IACjB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,OAAO,CAAA;IAClB;mDAC+C;IAC/C,SAAS,EAAE,OAAO,CAAA;IAClB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,GAAG,EAAE,eAAe,CAAA;CACrB,CAAA;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,GAAG,WAAW,CAkBjG;AAED;;kEAEkE;AAClE,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,mBAAmB,CAAA;IAC3B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACjD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,EAAE,OAAO,EAAE,CAAA;IACjB,GAAG,EAAE,eAAe,CAAA;CACrB,CAAA;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,cAAc,CAW9F"}

package/dist/client/core/views.js

@@ -0,0 +1,32 @@
+import { accountHoldingsFromNodeState, workflowStatusToAutomationStatus, automationErrorOf, automationHoldings, automationStrategyRefOf, } from '../../protocol/state.js';
+export function accountViewOf(na, exchangeConfigs) {
+    const specifics = na.specifics;
+    const type = specifics?.account_type === 'exchange' ? 'exchange' :
+        specifics?.account_type === 'blockchain' ? 'wallet' :
+            'generic';
+    const cfgId = specifics?.exchange_config_ids?.[0];
+    const exchange = cfgId ? exchangeConfigs.find((c) => c.id === cfgId)?.exchange : undefined;
+    return {
+        id: na.id,
+        name: na.name || na.id,
+        type,
+        exchange,
+        simulated: na.is_simulated ?? false,
+        connected: na.state?.status !== 'invalid',
+        holdings: accountHoldingsFromNodeState(na),
+        raw: na,
+    };
+}
+export function automationViewOf(state, actions) {
+    return {
+        id: state.id,
+        name: state.metadata?.name || state.id,
+        status: workflowStatusToAutomationStatus(state.status),
+        accountIds: state.exchange_account_ids ?? [],
+        strategy: automationStrategyRefOf(actions, state.id),
+        error: automationErrorOf(state),
+        assets: automationHoldings(state).map((a) => ({ symbol: a.symbol, total: a.total, free: a.available, used: Math.max(0, a.total - a.available) })),
+        raw: state,
+    };
+}
+//# sourceMappingURL=views.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../../../src/client/core/views.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,EAChC,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,GAGxB,MAAM,yBAAyB,CAAA;AAuBhC,MAAM,UAAU,aAAa,CAAC,EAAmB,EAAE,eAAiC;IAClF,MAAM,SAAS,GAAG,EAAE,CAAC,SAAkF,CAAA;IACvG,MAAM,IAAI,GACR,SAAS,EAAE,YAAY,KAAK,UAAU,CAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QACvD,SAAS,EAAE,YAAY,KAAK,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YACrD,SAAS,CAAA;IACX,MAAM,KAAK,GAAG,SAAS,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,CAAA;IACjD,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1F,OAAO;QACL,EAAE,EAAE,EAAE,CAAC,EAAE;QACT,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE;QACtB,IAAI;QACJ,QAAQ;QACR,SAAS,EAAE,EAAE,CAAC,YAAY,IAAI,KAAK;QACnC,SAAS,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS;QACzC,QAAQ,EAAE,4BAA4B,CAAC,EAAE,CAAC;QAC1C,GAAG,EAAE,EAAE;KACR,CAAA;AACH,CAAC;AAiBD,MAAM,UAAU,gBAAgB,CAAC,KAAsB,EAAE,OAAqB;IAC5E,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,IAAI,KAAK,CAAC,EAAE;QACtC,MAAM,EAAE,gCAAgC,CAAC,KAAK,CAAC,MAAM,CAAC;QACtD,UAAU,EAAE,KAAK,CAAC,oBAAoB,IAAI,EAAE;QAC5C,QAAQ,EAAE,uBAAuB,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QACpD,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC;QAC/B,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACjJ,GAAG,EAAE,KAAK;KACX,CAAA;AACH,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,16 @@
+export { connectOctoBot, type OctoBotClient, type ConnectOptions, type SeedDerivation, type CallOptions, } from './connect/connect.js';
+export { connectReadOnlyDevice, type ConnectReadOnlyOptions, type ReadOnlyOctoBotClient, type ReadOnlyAccountsApi, type ReadOnlyAutomationsApi, type ReadOnlyStrategiesApi, type ProposedAction, } from './connect/readOnly.js';
+export { type AccountsApi, type AccountInput } from './adapters/accounts.js';
+export { type AutomationsApi, type CreateAutomationInput, type CreateAutomationProgress } from './adapters/automations.js';
+export { type StrategiesApi } from './adapters/strategies.js';
+export { type SettingsApi } from './adapters/settings.js';
+export { type NodeApi } from './adapters/nodeApi.js';
+export { type DocumentsApi, type ReadOnlyDocumentsApi } from './adapters/documents.js';
+export { type ActionHandle } from './adapters/actionHandle.js';
+export { type AccountView, type AccountKind, type AutomationView, type Holding, accountViewOf, automationViewOf } from './core/views.js';
+export { startPairingRequest, fetchPairingRequestByCode, type StartPairingRequestOptions, type PairingRequestSession, type PairingRequestLookup, } from './pairing/pairingRequest.js';
+export { buildJoinRequestJson, mintPairingGrant, revokePairingGrant, NothingToShareError, type MintedPairingGrant, } from './pairing/mirrorGrant.js';
+export { parseMirrorGrantBundle, readMirrorCollections, attemptDirectMirrorWrite, type MirrorGrantBundle, type MirrorGrantNodeRef, type ReadMirrorCollectionsOptions, type AttemptDirectMirrorWriteOptions, } from './pairing/mirrorReader.js';
+export { publishPairingGrant, clearPairingGrant, fetchPairingGrant, awaitPairingGrant, type UnsealedPairingGrant, } from './pairing/pairingGrantExchange.js';
+export { OctoBotError, OctoBotConfigError, OctoBotConnectionError, OctoBotAuthError, OctoBotHttpError, OctoBotConflictError, OctoBotActionError, OctoBotTimeoutError, OctoBotScopeError, isOctoBotError, type OctoBotErrorCode, } from './core/errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,GACjB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAC5E,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAC1H,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AACtF,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACxI,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,kBAAkB,GACxB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,GACrC,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,oBAAoB,GAC1B,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAA"}

package/dist/client/index.js

@@ -0,0 +1,9 @@
+export { connectOctoBot, } from './connect/connect.js';
+export { connectReadOnlyDevice, } from './connect/readOnly.js';
+export { accountViewOf, automationViewOf } from './core/views.js';
+export { startPairingRequest, fetchPairingRequestByCode, } from './pairing/pairingRequest.js';
+export { buildJoinRequestJson, mintPairingGrant, revokePairingGrant, NothingToShareError, } from './pairing/mirrorGrant.js';
+export { parseMirrorGrantBundle, readMirrorCollections, attemptDirectMirrorWrite, } from './pairing/mirrorReader.js';
+export { publishPairingGrant, clearPairingGrant, fetchPairingGrant, awaitPairingGrant, } from './pairing/pairingGrantExchange.js';
+export { OctoBotError, OctoBotConfigError, OctoBotConnectionError, OctoBotAuthError, OctoBotHttpError, OctoBotConflictError, OctoBotActionError, OctoBotTimeoutError, OctoBotScopeError, isOctoBotError, } from './core/errors.js';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAKf,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,qBAAqB,GAOtB,MAAM,uBAAuB,CAAA;AAQ9B,OAAO,EAAyE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACxI,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAI1B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GAEpB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,GAKzB,MAAM,2BAA2B,CAAA;AAClC,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,GAEf,MAAM,kBAAkB,CAAA"}

package/dist/client/mirror/collections.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Node collections the space-mirror can offer — the canonical definition this
+ * feature's per-platform copies (mobile2's `cloudSyncCollections.ts`, the node
+ * web UI's `cloud-sync-collections.ts`) are meant to eventually source from
+ * instead of duplicating. Ids are the SAME wire collection names the node's own
+ * sync layer uses (`wire-contract.md`'s `Collections` enum values).
+ *
+ * `visibility` is who can ever reach a collection's mirrored copy:
+ *
+ * - `"private"` — the wallet's own devices only. A pairing grant can never
+ *   include it, no matter what the user enables.
+ * - `"shared"` — E2EE under the node's OWN keyring, reachable by a per-node
+ *   pairing grant the user hands out (the website-pairing flow).
+ * - `"public"` — world-readable plaintext. Nothing is `"public"` today.
+ *
+ * `user-accounts-auth` (exchange credentials) is intentionally absent: never a
+ * configurable mirror-eligible option, at any layer.
+ *
+ * See `docs/content/client-sdk/website-pairing.md` for the access model.
+ */
+export type MirrorVisibility = 'private' | 'shared' | 'public';
+export interface MirrorCollection {
+    id: string;
+    defaultEnabled: boolean;
+    visibility: MirrorVisibility;
+}
+export declare const MIRROR_COLLECTIONS: readonly MirrorCollection[];
+export type MirrorCollectionId = (typeof MIRROR_COLLECTIONS)[number]['id'];
+export declare const DEFAULT_MIRROR_COLLECTIONS: MirrorCollectionId[];
+export declare const THIRD_PARTY_ELIGIBLE_MIRROR_COLLECTIONS: MirrorCollectionId[];
+export declare function isKnownMirrorCollection(id: string): id is MirrorCollectionId;
+/** An UNKNOWN id resolves to `"private"` — the safe end of the enum, so a
+ *  typo'd or stale id can never read as grant-reachable or world-readable. */
+export declare function mirrorVisibilityFor(id: string): MirrorVisibility;
+/** DERIVED from `visibility`: "can a pairing grant ever reach this". */
+export declare function isThirdPartyEligible(id: string): boolean;
+export declare function isPublicMirrorCollection(id: string): boolean;
+/** Whether a collection's node is sealed under its own per-node keyring — the
+ *  grantable ones. Drives both the writer's tier and the grant minting. */
+export declare function isIsolatedMirrorCollection(id: string): boolean;
+/** `SpaceMirrorTier` as `starfish-replica/space` spells it: the storage axes a
+ *  node is created under. `"shared"` maps to `"isolated"` rather than getting
+ *  its own tier name — upstream names the access model, not our audience. */
+export type MirrorStorageTier = 'private' | 'isolated' | 'public';
+/**
+ * Everything one `visibility` decides, as ONE table rather than ternaries
+ * scattered across this module and the writer. Every row is a security
+ * decision, so they are stated together where they can be tested against each
+ * other.
+ *
+ * - `tier` — the storage axes handed to `createSpaceMirrorChannel`.
+ * - `storage` — which content collection the node's document lives in:
+ *   `docs` (`objdoc`, space-keyring E2EE), `invite` (`objinv`, per-node-keyring
+ *   E2EE, cap-readable), `pub` (`objpub`, world-readable plaintext).
+ * - `opaqueTitle` — whether the node's title must NOT name the collection,
+ *   because Infra republishes a public node's title world-readable.
+ */
+export interface MirrorVisibilityRouting {
+    tier: MirrorStorageTier;
+    storage: 'docs' | 'invite' | 'pub';
+    opaqueTitle: boolean;
+}
+export declare const MIRROR_ROUTING_BY_VISIBILITY: Readonly<Record<MirrorVisibility, MirrorVisibilityRouting>>;
+/**
+ * ONE space per wallet, holding every mirrored collection whatever its
+ * visibility. Found by name in the wallet's own space registry (`readSpaces()`)
+ * — `starfish-spaces`' `Space` has no `meta`/`kind` field, so the name is the
+ * marker; `createSpace` mints the id.
+ *
+ * This used to be three spaces, one per visibility, because a space keyring is
+ * space-wide and a `space:member` grant reaches every enc node in the space —
+ * so the only way to keep `user-settings` out of a website grant was to put it
+ * in a different space. Per-node keyrings (`tier: "isolated"`) make that
+ * unnecessary: a grant now reaches exactly one node. See
+ * `docs/content/client-sdk/website-pairing.md`.
+ */
+export declare const MIRROR_SPACE_NAME = "octobot-mirror";
+/** Every routing decision for one collection, via its `visibility`. An unknown
+ *  id inherits `mirrorVisibilityFor`'s safe `"private"` fallback. */
+export declare function mirrorRoutingFor(collectionId: string): MirrorVisibilityRouting;
+/** The `SpaceMirrorTier` a collection's node is created under. */
+export declare function mirrorTierFor(collectionId: string): MirrorStorageTier;
+/**
+ * The node's content path. The collection id comes FIRST because that is the
+ * shape `starfish-replica/space` widened both `SpaceMirrorChannel.docPath` and
+ * `readIsolatedSpaceMirror.docPath` to — one function literal shared by the writer and
+ * the website-side reader, so a tier can never be written to one path and read
+ * from another.
+ *
+ * `objinv` is the odd shape (`objects/n/{nodeId}/content`, not
+ * `objects/{seg}/{nodeId}`) because it is per-node-scoped server-side: its
+ * read roles are `space:member` OR `cap:read:objinv`, which is exactly what
+ * lets a per-node grant holder fetch it without space membership. `objdoc`
+ * has no cap fallback at all, which is why the isolated tier cannot use it.
+ */
+export declare function mirrorDocPath(collectionId: string, spaceId: string, nodeId: string): string;
+/** The visibility-level primitive `mirrorDocPath` is a lookup in front of.
+ *  Exported so the `"public"` branch is exercisable NOW — no collection has
+ *  `visibility:"public"` yet, and the half that would leak is the one left
+ *  unproven until someone flips a collection. */
+export declare function mirrorDocPathForVisibility(visibility: MirrorVisibility, spaceId: string, nodeId: string): string;
+export declare function mirrorDocPullPath(collectionId: string, spaceId: string, nodeId: string): string;
+export declare function mirrorDocPushPath(collectionId: string, spaceId: string, nodeId: string): string;
+/**
+ * The title a newly-created PUBLIC mirror node is given, in place of the
+ * collection id `starfish-replica/space` would otherwise default to.
+ *
+ * `_project_objindex_public` republishes a public node's `title` into the
+ * world-readable projection, so a descriptive one ("user-strategies") tells any
+ * anonymous reader exactly what a wallet publishes. One constant shared by
+ * every public collection carries zero bits about which collection a node
+ * holds. Private and isolated titles live only in `objindex`, which is
+ * `space:member` and unreachable by a per-node grant holder.
+ */
+export declare const MIRROR_PUBLIC_NODE_TITLE = "public";
+/** Title for a newly-created mirror node: opaque for public collections, the
+ *  collection id (upstream's default) otherwise. */
+export declare function mirrorNodeTitleFor(collectionId: string): string;
+/** The visibility-level primitive behind `mirrorNodeTitleFor`, exported for the
+ *  same reason as `mirrorDocPathForVisibility`. */
+export declare function mirrorNodeTitleForVisibility(visibility: MirrorVisibility, collectionId: string): string;
+/** `ObjectNode.type` for a mirror node is the collection id itself — one
+ *  identifier space, nothing extra to keep in sync (see the module doc). */
+export type MirrorNodeType = MirrorCollectionId;
+//# sourceMappingURL=collections.d.ts.map

package/dist/client/mirror/collections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collections.d.ts","sourceRoot":"","sources":["../../../src/client/mirror/collections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,cAAc,EAAE,OAAO,CAAA;IACvB,UAAU,EAAE,gBAAgB,CAAA;CAC7B;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAMhD,CAAA;AAEV,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAA;AAE1E,eAAO,MAAM,0BAA0B,EAAE,kBAAkB,EAExC,CAAA;AAEnB,eAAO,MAAM,uCAAuC,EAAE,kBAAkB,EAErD,CAAA;AAEnB,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,kBAAkB,CAE5E;AAED;8EAC8E;AAC9E,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,CAEhE;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;2EAC2E;AAC3E,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;6EAE6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAA;AAEjE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,iBAAiB,CAAA;IACvB,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;IAClC,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CACjD,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAKzC,CAAA;AAEV;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,mBAAmB,CAAA;AAEjD;qEACqE;AACrE,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,uBAAuB,CAE9E;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,iBAAiB,CAErE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED;;;iDAGiD;AACjD,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,CAKR;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/F;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/F;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,WAAW,CAAA;AAEhD;oDACoD;AACpD,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;mDACmD;AACnD,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,gBAAgB,EAC5B,YAAY,EAAE,MAAM,GACnB,MAAM,CAIR;AAED;4EAC4E;AAC5E,MAAM,MAAM,cAAc,GAAG,kBAAkB,CAAA"}

package/dist/client/mirror/collections.js

@@ -0,0 +1,118 @@
+export const MIRROR_COLLECTIONS = [
+    { id: 'user-accounts', defaultEnabled: true, visibility: 'shared' },
+    { id: 'user-data', defaultEnabled: true, visibility: 'shared' },
+    { id: 'user-strategies', defaultEnabled: true, visibility: 'shared' },
+    { id: 'user-accounts-trading', defaultEnabled: false, visibility: 'shared' },
+    { id: 'user-settings', defaultEnabled: false, visibility: 'private' },
+];
+export const DEFAULT_MIRROR_COLLECTIONS = MIRROR_COLLECTIONS
+    .filter((c) => c.defaultEnabled)
+    .map((c) => c.id);
+export const THIRD_PARTY_ELIGIBLE_MIRROR_COLLECTIONS = MIRROR_COLLECTIONS
+    .filter((c) => c.visibility !== 'private')
+    .map((c) => c.id);
+export function isKnownMirrorCollection(id) {
+    return MIRROR_COLLECTIONS.some((c) => c.id === id);
+}
+/** An UNKNOWN id resolves to `"private"` — the safe end of the enum, so a
+ *  typo'd or stale id can never read as grant-reachable or world-readable. */
+export function mirrorVisibilityFor(id) {
+    return MIRROR_COLLECTIONS.find((c) => c.id === id)?.visibility ?? 'private';
+}
+/** DERIVED from `visibility`: "can a pairing grant ever reach this". */
+export function isThirdPartyEligible(id) {
+    return mirrorVisibilityFor(id) !== 'private';
+}
+export function isPublicMirrorCollection(id) {
+    return mirrorVisibilityFor(id) === 'public';
+}
+/** Whether a collection's node is sealed under its own per-node keyring — the
+ *  grantable ones. Drives both the writer's tier and the grant minting. */
+export function isIsolatedMirrorCollection(id) {
+    return mirrorVisibilityFor(id) === 'shared';
+}
+export const MIRROR_ROUTING_BY_VISIBILITY = {
+    private: { tier: 'private', storage: 'docs', opaqueTitle: false },
+    shared: { tier: 'isolated', storage: 'invite', opaqueTitle: false },
+    public: { tier: 'public', storage: 'pub', opaqueTitle: true },
+};
+/**
+ * ONE space per wallet, holding every mirrored collection whatever its
+ * visibility. Found by name in the wallet's own space registry (`readSpaces()`)
+ * — `starfish-spaces`' `Space` has no `meta`/`kind` field, so the name is the
+ * marker; `createSpace` mints the id.
+ *
+ * This used to be three spaces, one per visibility, because a space keyring is
+ * space-wide and a `space:member` grant reaches every enc node in the space —
+ * so the only way to keep `user-settings` out of a website grant was to put it
+ * in a different space. Per-node keyrings (`tier: "isolated"`) make that
+ * unnecessary: a grant now reaches exactly one node. See
+ * `docs/content/client-sdk/website-pairing.md`.
+ */
+export const MIRROR_SPACE_NAME = 'octobot-mirror';
+/** Every routing decision for one collection, via its `visibility`. An unknown
+ *  id inherits `mirrorVisibilityFor`'s safe `"private"` fallback. */
+export function mirrorRoutingFor(collectionId) {
+    return MIRROR_ROUTING_BY_VISIBILITY[mirrorVisibilityFor(collectionId)];
+}
+/** The `SpaceMirrorTier` a collection's node is created under. */
+export function mirrorTierFor(collectionId) {
+    return mirrorRoutingFor(collectionId).tier;
+}
+/**
+ * The node's content path. The collection id comes FIRST because that is the
+ * shape `starfish-replica/space` widened both `SpaceMirrorChannel.docPath` and
+ * `readIsolatedSpaceMirror.docPath` to — one function literal shared by the writer and
+ * the website-side reader, so a tier can never be written to one path and read
+ * from another.
+ *
+ * `objinv` is the odd shape (`objects/n/{nodeId}/content`, not
+ * `objects/{seg}/{nodeId}`) because it is per-node-scoped server-side: its
+ * read roles are `space:member` OR `cap:read:objinv`, which is exactly what
+ * lets a per-node grant holder fetch it without space membership. `objdoc`
+ * has no cap fallback at all, which is why the isolated tier cannot use it.
+ */
+export function mirrorDocPath(collectionId, spaceId, nodeId) {
+    return mirrorDocPathForVisibility(mirrorVisibilityFor(collectionId), spaceId, nodeId);
+}
+/** The visibility-level primitive `mirrorDocPath` is a lookup in front of.
+ *  Exported so the `"public"` branch is exercisable NOW — no collection has
+ *  `visibility:"public"` yet, and the half that would leak is the one left
+ *  unproven until someone flips a collection. */
+export function mirrorDocPathForVisibility(visibility, spaceId, nodeId) {
+    const { storage } = MIRROR_ROUTING_BY_VISIBILITY[visibility];
+    return storage === 'invite'
+        ? `spaces/${spaceId}/objects/n/${nodeId}/content`
+        : `spaces/${spaceId}/objects/${storage}/${nodeId}`;
+}
+export function mirrorDocPullPath(collectionId, spaceId, nodeId) {
+    return `/pull/${mirrorDocPath(collectionId, spaceId, nodeId)}`;
+}
+export function mirrorDocPushPath(collectionId, spaceId, nodeId) {
+    return `/push/${mirrorDocPath(collectionId, spaceId, nodeId)}`;
+}
+/**
+ * The title a newly-created PUBLIC mirror node is given, in place of the
+ * collection id `starfish-replica/space` would otherwise default to.
+ *
+ * `_project_objindex_public` republishes a public node's `title` into the
+ * world-readable projection, so a descriptive one ("user-strategies") tells any
+ * anonymous reader exactly what a wallet publishes. One constant shared by
+ * every public collection carries zero bits about which collection a node
+ * holds. Private and isolated titles live only in `objindex`, which is
+ * `space:member` and unreachable by a per-node grant holder.
+ */
+export const MIRROR_PUBLIC_NODE_TITLE = 'public';
+/** Title for a newly-created mirror node: opaque for public collections, the
+ *  collection id (upstream's default) otherwise. */
+export function mirrorNodeTitleFor(collectionId) {
+    return mirrorNodeTitleForVisibility(mirrorVisibilityFor(collectionId), collectionId);
+}
+/** The visibility-level primitive behind `mirrorNodeTitleFor`, exported for the
+ *  same reason as `mirrorDocPathForVisibility`. */
+export function mirrorNodeTitleForVisibility(visibility, collectionId) {
+    return MIRROR_ROUTING_BY_VISIBILITY[visibility].opaqueTitle
+        ? MIRROR_PUBLIC_NODE_TITLE
+        : collectionId;
+}
+//# sourceMappingURL=collections.js.map

package/dist/client/mirror/collections.js.map

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

package/dist/client/mirror/index.d.ts

@@ -0,0 +1,4 @@
+export { MIRROR_COLLECTIONS, DEFAULT_MIRROR_COLLECTIONS, THIRD_PARTY_ELIGIBLE_MIRROR_COLLECTIONS, MIRROR_SPACE_NAME, MIRROR_PUBLIC_NODE_TITLE, MIRROR_ROUTING_BY_VISIBILITY, isIsolatedMirrorCollection, isKnownMirrorCollection, isPublicMirrorCollection, isThirdPartyEligible, mirrorDocPath, mirrorDocPathForVisibility, mirrorDocPullPath, mirrorDocPushPath, mirrorNodeTitleFor, mirrorNodeTitleForVisibility, mirrorRoutingFor, mirrorTierFor, mirrorVisibilityFor, type MirrorCollection, type MirrorCollectionId, type MirrorNodeType, type MirrorStorageTier, type MirrorVisibility, type MirrorVisibilityRouting, } from './collections.js';
+export { findOrCreateSpace as findOrCreateMirrorSpace } from '@drakkar.software/starfish-replica/space';
+export { syncCloudMirror, type SyncCloudMirrorOptions, type SyncCloudMirrorResult, } from './writer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/mirror/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/mirror/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,uCAAuC,EACvC,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,aAAa,EACb,0BAA0B,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,4BAA4B,EAC5B,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,iBAAiB,IAAI,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AACvG,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAA"}

package/dist/client/mirror/index.js

@@ -0,0 +1,4 @@
+export { MIRROR_COLLECTIONS, DEFAULT_MIRROR_COLLECTIONS, THIRD_PARTY_ELIGIBLE_MIRROR_COLLECTIONS, MIRROR_SPACE_NAME, MIRROR_PUBLIC_NODE_TITLE, MIRROR_ROUTING_BY_VISIBILITY, isIsolatedMirrorCollection, isKnownMirrorCollection, isPublicMirrorCollection, isThirdPartyEligible, mirrorDocPath, mirrorDocPathForVisibility, mirrorDocPullPath, mirrorDocPushPath, mirrorNodeTitleFor, mirrorNodeTitleForVisibility, mirrorRoutingFor, mirrorTierFor, mirrorVisibilityFor, } from './collections.js';
+export { findOrCreateSpace as findOrCreateMirrorSpace } from '@drakkar.software/starfish-replica/space';
+export { syncCloudMirror, } from './writer.js';
+//# sourceMappingURL=index.js.map

package/dist/client/mirror/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/mirror/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,uCAAuC,EACvC,iBAAiB,EACjB,wBAAwB,EACxB,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,aAAa,EACb,0BAA0B,EAC1B,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,4BAA4B,EAC5B,gBAAgB,EAChB,aAAa,EACb,mBAAmB,GAOpB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,iBAAiB,IAAI,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AACvG,OAAO,EACL,eAAe,GAGhB,MAAM,aAAa,CAAA"}

package/dist/client/mirror/writer.d.ts

@@ -0,0 +1,39 @@
+import type { Session } from '@drakkar.software/starfish-spaces';
+import { type MirrorCollectionId } from './collections.js';
+export interface SyncCloudMirrorOptions {
+    session: Session;
+    /** Collection ids the user has currently enabled (`cloudSyncCollections`).
+     *  Unknown ids are silently ignored — this function is not the place a
+     *  malformed setting gets rejected, the settings layer already owns that. */
+    enabledCollectionIds: readonly string[];
+    /** Pull the CURRENT raw document for one enabled collection from its real
+     *  source (the node, or a local store in the no-node case) — this
+     *  function's caller owns how, `starfish-replica/space` owns only the
+     *  CAS-write into the mirror space. Called once per collection being
+     *  written, never for a collection being cleared. */
+    readSourceCollection: (collectionId: MirrorCollectionId) => Promise<unknown>;
+}
+export interface SyncCloudMirrorResult {
+    /** `null` when the space was never created (nothing has ever been enabled)
+     *  — not an error, just "nothing to report". */
+    spaceId: string | null;
+    created: MirrorCollectionId[];
+    written: MirrorCollectionId[];
+    cleared: MirrorCollectionId[];
+}
+/**
+ * One full cloud-mirror sync cycle: find-or-create the wallet's mirror space,
+ * plan what changed since last cycle, create any newly-enabled collections'
+ * nodes, write every currently-enabled collection's projection, and clear any
+ * collection the user just disabled.
+ *
+ * The space/node mechanics live in `starfish-replica/space`'s
+ * `createSpaceMirrorChannel` — this is a thin adapter wiring the
+ * `MIRROR_COLLECTIONS` registry and its tier routing into it.
+ *
+ * Callers (the node's writer, the mobile no-node writer) gate this behind the
+ * `cloudSyncEnabled` setting themselves; this function assumes it was only
+ * called because the setting is on.
+ */
+export declare function syncCloudMirror(options: SyncCloudMirrorOptions): Promise<SyncCloudMirrorResult>;
+//# sourceMappingURL=writer.d.ts.map

package/dist/client/mirror/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../src/client/mirror/writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAA;AAEhE,OAAO,EAML,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAA;AAEzB,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB;;iFAE6E;IAC7E,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC;;;;yDAIqD;IACrD,oBAAoB,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC7E;AAED,MAAM,WAAW,qBAAqB;IACpC;oDACgD;IAChD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,OAAO,EAAE,kBAAkB,EAAE,CAAA;IAC7B,OAAO,EAAE,kBAAkB,EAAE,CAAA;IAC7B,OAAO,EAAE,kBAAkB,EAAE,CAAA;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAkChC"}