@drakkar.software/octobot-client 0.4.0

package/dist/client/pairing/pairingGrantExchange.js

@@ -0,0 +1,186 @@
+import { seal, unseal } from '@drakkar.software/starfish-keyring';
+import { ConflictError } from '@drakkar.software/starfish-client';
+import { createRendezvousClient, pullRendezvousDoc, pushRendezvousDoc, clearRendezvousDoc, joinSessionPath, } from '../../transport/rendezvous.js';
+import { pollDelay } from '../../protocol/poll.js';
+import { abortableSleep } from './pairingRequest.js';
+import { OctoBotConnectionError, OctoBotConflictError, rethrowAsOctoBotError } from '../core/errors.js';
+import { readMirrorCollections, parseMirrorGrantBundle, } from './mirrorReader.js';
+/**
+ * Website↔phone exchange for the read-only-device grant this package mints
+ * against the space-mirror (see `mirrorGrant.ts`). This replaced an older
+ * sealed data-snapshot exchange, which has since been deleted.
+ *
+ * Request and grant now share ONE rendezvous address, `joinSessionPath(code)`
+ * (the `joinsessions` collection — see `transport/rendezvous.ts`), not two
+ * separate collections. `startPairingRequest`/`fetchPairingRequestByCode`
+ * publish/read the "request" phase there; this file's `publishPairingGrant`
+ * OVERWRITES that same doc with the "grant" phase once the phone approves.
+ * The sealing mechanism itself is unchanged (`starfish-keyring`'s
+ * `seal`/`unseal`, sealed to the website's ephemeral KEM key, signed by the
+ * wallet's own root key) — what's new is the OUTER wire envelope
+ * (`v`/`kind`/`sealed`, see `JoinSessionGrantDoc` below) wrapping the sealed
+ * blob, so a poller can tell "still just a request" from "a grant has been
+ * published" by reading one unsealed field, without attempting `unseal()`
+ * on a doc that might not even be sealed yet.
+ */
+const GRANT_ENVELOPE_KIND = 'octobot-pairing-grant';
+const GRANT_ENVELOPE_VERSION = 1;
+/** Phone side, step 2: seal and publish the minted grant to the request's
+ *  `code` slot — this OVERWRITES the request doc still published there,
+ *  since request and grant now share one address.
+ *
+ *  `rendezvous` is the caller's OWN trusted server config — the same one it
+ *  used to look up `request` via `fetchPairingRequestByCode` — never
+ *  `request.rendezvous`. That field rides inside a document anyone can
+ *  publish to the public `joinsessions` collection, so trusting it here
+ *  would let a malicious "website" party point this phone's outbound POST at
+ *  an arbitrary host of its choosing.
+ *
+ *  `baseHash` MUST be the `hash` `fetchPairingRequestByCode` returned
+ *  alongside `request` — this is what makes "claim this specific, exact
+ *  request" atomic: the push only succeeds if the slot still holds exactly
+ *  the request doc this caller read, so a request that was swapped or
+ *  already claimed by someone else between the read and this write is
+ *  detected as a conflict rather than silently overwritten. There is no
+ *  longer a meaningful "first publish, baseHash: null" case the way the
+ *  retired sessionId-keyed design had one — the slot is never empty by the
+ *  time a caller reaches this function, it already holds the request. A
+ *  caller legitimately RE-publishing later (a refresh) must pass back the
+ *  hash THIS function returned from its own previous call. Returns the
+ *  resulting hash for exactly that purpose. */
+export async function publishPairingGrant(opts) {
+    const client = createRendezvousClient({
+        baseUrl: opts.rendezvous.baseUrl,
+        namespace: opts.rendezvous.namespace,
+        fetch: opts.fetch,
+        timeoutMs: opts.timeoutMs,
+    });
+    try {
+        const envelope = {
+            v: GRANT_ENVELOPE_VERSION,
+            kind: GRANT_ENVELOPE_KIND,
+            bundle: opts.grant.bundle,
+        };
+        const plaintext = new TextEncoder().encode(JSON.stringify(envelope));
+        const sealed = await seal(plaintext, opts.request.devKemPub, opts.sealer, opts.request.code);
+        const doc = { v: GRANT_ENVELOPE_VERSION, kind: GRANT_ENVELOPE_KIND, sealed };
+        return await pushRendezvousDoc(client, joinSessionPath(opts.request.code), doc, opts.baseHash);
+    }
+    catch (err) {
+        if (err instanceof ConflictError) {
+            throw new OctoBotConflictError(err.currentHash || null, err, 'pairing request slot was modified since it was read — this pairing may be compromised, or someone else already claimed it');
+        }
+        rethrowAsOctoBotError(err);
+    }
+}
+/** Phone side: stop publishing and clear the current slot — since request
+ *  and grant share one address, this clears BOTH together (there is no way
+ *  to clear one but keep the other). It stops future reads but cannot
+ *  recall a grant a website already fetched — with this design, "cannot
+ *  recall" is narrow: the grant itself only proves space membership, and
+ *  `removeSpaceMember`-based revocation (real, immediate, checked live on
+ *  every request) is the actual unpair mechanism a caller should use
+ *  ALONGSIDE this, not instead of it — this only stops the CODE from
+ *  resolving to a usable grant again, it does not by itself revoke a grant
+ *  already handed out. */
+export async function clearPairingGrant(opts) {
+    const client = createRendezvousClient({
+        baseUrl: opts.rendezvous.baseUrl,
+        namespace: opts.rendezvous.namespace,
+        fetch: opts.fetch,
+        timeoutMs: opts.timeoutMs,
+    });
+    try {
+        return await clearRendezvousDoc(client, joinSessionPath(opts.request.code));
+    }
+    catch (err) {
+        rethrowAsOctoBotError(err);
+    }
+}
+/** Website side: read whatever is currently published at this session's
+ *  slot. Three outcomes:
+ *  - nothing published (wrong/expired code) → `null`, "keep waiting".
+ *  - still `kind: 'octobot-pairing-request'` (the phone hasn't approved
+ *    yet) → also `null`, "keep waiting" — this is the normal, expected
+ *    state for most of the polling loop's life, NOT an error.
+ *  - `kind: 'octobot-pairing-grant'` → unseal it and immediately do a live
+ *    read of every mirror collection it covers.
+ *  Anything else (an unrecognized `kind`, or a `kind: 'octobot-pairing-grant'`
+ *  doc whose `sealed` field isn't actually a sealed blob) throws — that's a
+ *  genuine malformed-document case, not a wait state. */
+export async function fetchPairingGrant(session, opts = {}) {
+    const client = createRendezvousClient({
+        baseUrl: session.rendezvous.baseUrl,
+        namespace: session.rendezvous.namespace,
+        fetch: opts.fetch,
+        timeoutMs: opts.timeoutMs,
+    });
+    const doc = await pullRendezvousDoc(client, joinSessionPath(session.code));
+    if (!doc)
+        return null;
+    const data = doc.data;
+    if (data.kind === 'octobot-pairing-request')
+        return null;
+    if (data.v !== GRANT_ENVELOPE_VERSION || data.kind !== GRANT_ENVELOPE_KIND) {
+        throw new Error('pairing grant: unrecognized document at this code\'s slot');
+    }
+    if (typeof data.sealed !== 'object' || data.sealed === null || typeof data.sealed.entry !== 'object' || data.sealed.entry === null) {
+        throw new Error('pairing grant: malformed sealed blob at this code\'s slot');
+    }
+    const sealed = data.sealed;
+    const plaintext = await unseal(sealed, session.device.kemPriv, {
+        aad: session.code,
+        ...(opts.expectedSealer !== undefined ? { requireSealer: opts.expectedSealer } : {}),
+    });
+    const envelopeRaw = JSON.parse(new TextDecoder().decode(plaintext));
+    if (typeof envelopeRaw !== 'object' || envelopeRaw === null
+        || envelopeRaw.v !== GRANT_ENVELOPE_VERSION
+        || envelopeRaw.kind !== GRANT_ENVELOPE_KIND
+        || typeof envelopeRaw.bundle !== 'string') {
+        throw new Error('pairing grant: malformed grant envelope');
+    }
+    const { spaceId, nodes } = parseMirrorGrantBundle(envelopeRaw.bundle);
+    const sealedBy = sealed.entry.addedBy;
+    const collections = await readMirrorCollections({
+        rendezvous: session.rendezvous,
+        spaceId,
+        nodes,
+        devEdPrivHex: session.device.edPriv,
+        devKemPrivHex: session.device.kemPriv,
+        fetch: opts.fetch,
+        timeoutMs: opts.timeoutMs,
+    });
+    return { spaceId, collections, sealedBy, nodes };
+}
+/** Website side: poll until the phone's FIRST approval publishes a grant,
+ *  or `timeoutMs` elapses. This is the initial-approval wait, not an ongoing
+ *  refresh loop — for later refreshes call `readMirrorCollections` directly.
+ *
+ *  A `fetchPairingGrant` failure (a network blip, a transient server error)
+ *  does NOT end the wait — it's swallowed and retried on the next tick, same
+ *  as `fetchPairingGrant` returning `null` for "nothing published yet". Only
+ *  reaching `deadline` ends it: with the last error if there was one (more
+ *  informative than a bare timeout), else the generic timeout. */
+export async function awaitPairingGrant(session, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 5 * 60 * 1000);
+    let lastErr;
+    for (let attempt = 0;; attempt++) {
+        if (opts.signal?.aborted)
+            throw new DOMException('aborted', 'AbortError');
+        try {
+            const result = await fetchPairingGrant(session, { fetch: opts.fetch });
+            if (result)
+                return result;
+        }
+        catch (err) {
+            lastErr = err;
+        }
+        if (Date.now() >= deadline) {
+            if (lastErr)
+                rethrowAsOctoBotError(lastErr);
+            throw new OctoBotConnectionError('timeout', 'timed out waiting for the pairing to be approved');
+        }
+        await abortableSleep(pollDelay(attempt), opts.signal);
+    }
+}
+//# sourceMappingURL=pairingGrantExchange.js.map

package/dist/client/pairing/pairingGrantExchange.js.map

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

package/dist/client/pairing/pairingRequest.d.ts

@@ -0,0 +1,82 @@
+import type { GeneratedDeviceKeys } from '@drakkar.software/starfish-identities';
+import { type PairingRequestPayload } from '../../identity/pairingRequest.js';
+import type { NodeCollectionKey } from '../../collections/nodeCollections.js';
+export type StartPairingRequestOptions = {
+    origin: string;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+    label?: string;
+    requestedCollections?: NodeCollectionKey[];
+    ttlSec?: number;
+    /** See `PairingRequestPayload.requesterKind`. Defaults to `'website'`. */
+    requesterKind?: 'website' | 'device';
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
+/** A website's own end of a device-code pairing: its request record plus
+ *  everything needed to publish it and later unseal the phone's response.
+ *  `code` is what the site displays for the user to type into their OctoBot
+ *  app — this package never renders it, just returns the string. Carries its
+ *  own `rendezvous` (the same value passed to `startPairingRequest`) so
+ *  `awaitPairingGrant`/`fetchPairingGrant` can take the session directly,
+ *  with no re-spreading required at the call site. */
+export interface PairingRequestSession {
+    request: PairingRequestPayload;
+    device: GeneratedDeviceKeys;
+    code: string;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+    /** Publish (or re-publish) the request record to the rendezvous. */
+    publish(): Promise<void>;
+}
+/**
+ * Website side, step 1: create and publish a pairing request.
+ *
+ * ```ts
+ * const rendezvous = { baseUrl: 'https://sync.drakkar.software/sync', namespace: 'dk' }
+ * const session = await startPairingRequest({ origin: 'https://myapp.example', rendezvous })
+ * await session.publish()
+ * showCodeToUser(session.code)
+ * const grant = await awaitPairingGrant(session)
+ * ```
+ */
+export declare function startPairingRequest(opts: StartPairingRequestOptions): Promise<PairingRequestSession>;
+/** The result of a request lookup: the parsed request plus the pulled
+ *  document's `hash`. The hash matters — it's what the phone must pass as
+ *  `baseHash` when it later mints and publishes a grant, so that write is a
+ *  compare-and-swap against the EXACT request doc it read, not a blind
+ *  overwrite. See `client/pairing/pairingGrantExchange.ts`'s
+ *  `publishPairingGrant`. */
+export interface PairingRequestLookup {
+    request: PairingRequestPayload;
+    hash: string;
+}
+/** Phone side, step 1: look up a request by the code the user typed. Returns
+ *  `null` only when nothing is published under that code at all (wrong code,
+ *  or the rendezvous slot's own TTL already reclaimed it). A request that IS
+ *  still present but past its own `expiresAt` does NOT return `null` — it
+ *  throws (via `parsePairingRequest`), so the caller can tell "wrong code"
+ *  apart from "right code, but it expired" and say so accurately. If the
+ *  slot has ALREADY moved past the request phase (a grant is published
+ *  there — `kind === 'octobot-pairing-grant'`, detectable without unsealing
+ *  anything, see `pairingGrantExchange.ts`), this throws a distinct
+ *  `OctoBotConflictError` rather than a generic parse failure, so a caller
+ *  re-checking an already-approved code gets an accurate "already used"
+ *  signal instead of "malformed pairing request payload". */
+export declare function fetchPairingRequestByCode(opts: {
+    code: string;
+    rendezvous: {
+        baseUrl: string;
+        namespace: string;
+    };
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<PairingRequestLookup | null>;
+/** Shared by `pairingGrantExchange.ts`'s polling loops — keep the
+ *  abort/timeout/cleanup semantics in exactly one place. */
+export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=pairingRequest.d.ts.map

package/dist/client/pairing/pairingRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairingRequest.d.ts","sourceRoot":"","sources":["../../../src/client/pairing/pairingRequest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAA;AAChF,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,kCAAkC,CAAA;AAQzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAE7E,MAAM,MAAM,0BAA0B,GAAG;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oBAAoB,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0EAA0E;IAC1E,aAAa,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IACpC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;sDAMsD;AACtD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,qBAAqB,CAAA;IAC9B,MAAM,EAAE,mBAAmB,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,oEAAoE;IACpE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA2D1G;AAED;;;;;6BAK6B;AAC7B,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,qBAAqB,CAAA;IAC9B,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;6DAW6D;AAC7D,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAmBvC;AAED;4DAC4D;AAC5D,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9E"}

package/dist/client/pairing/pairingRequest.js

@@ -0,0 +1,120 @@
+import { ConflictError } from '@drakkar.software/starfish-client';
+import { createPairingRequest, parsePairingRequest, } from '../../identity/pairingRequest.js';
+import { createRendezvousClient, pullRendezvousDoc, pushRendezvousDoc, joinSessionPath, } from '../../transport/rendezvous.js';
+import { OctoBotConflictError, rethrowAsOctoBotError } from '../core/errors.js';
+/**
+ * Website side, step 1: create and publish a pairing request.
+ *
+ * ```ts
+ * const rendezvous = { baseUrl: 'https://sync.drakkar.software/sync', namespace: 'dk' }
+ * const session = await startPairingRequest({ origin: 'https://myapp.example', rendezvous })
+ * await session.publish()
+ * showCodeToUser(session.code)
+ * const grant = await awaitPairingGrant(session)
+ * ```
+ */
+export async function startPairingRequest(opts) {
+    const { request, device, code } = await createPairingRequest(opts);
+    const client = createRendezvousClient({
+        baseUrl: opts.rendezvous.baseUrl,
+        namespace: opts.rendezvous.namespace,
+        fetch: opts.fetch,
+        timeoutMs: opts.timeoutMs,
+    });
+    // This session's own remembered hash from its last successful publish —
+    // starts null (a fresh code has nothing published under it yet, so the
+    // FIRST publish() is create-only: it fails rather than silently adopting
+    // whatever's already occupying the slot). Every later publish() call uses
+    // its own remembered hash instead of re-pulling and trusting whatever the
+    // server currently reports, so a hostile overwrite between two publish()
+    // calls surfaces as a loud conflict instead of silently becoming this
+    // session's new baseline.
+    let lastHash = null;
+    // Serializes overlapping publish() calls on the SAME session — without
+    // this, two calls in flight at once both read the same lastHash before
+    // either awaits, so the one the server processes second gets a real
+    // ConflictError caused only by this session's own overlapping write, not
+    // third-party tampering, yet (post-own-write-CAS) it hits the exact same
+    // "treat this code as compromised" error a genuine hijack would.
+    let queue = Promise.resolve();
+    async function doPublish() {
+        try {
+            const result = await pushRendezvousDoc(client, joinSessionPath(code), request, lastHash);
+            lastHash = result.hash;
+        }
+        catch (err) {
+            if (err instanceof ConflictError) {
+                // Thrown as OctoBotConflictError directly (not wrapped in a plain
+                // Error then run through rethrowAsOctoBotError) so `code === 'conflict'`
+                // and `instanceof OctoBotConflictError` survive — the documented
+                // "switch on code" convention callers rely on to distinguish a
+                // tampered slot from a generic unreachable-node failure.
+                throw new OctoBotConflictError(err.currentHash || null, err, 'pairing request was modified by another party — treat this code as compromised');
+            }
+            rethrowAsOctoBotError(err);
+        }
+    }
+    return {
+        request,
+        device,
+        code,
+        rendezvous: opts.rendezvous,
+        publish() {
+            const run = queue.then(() => doPublish());
+            // Swallow so a failed publish() doesn't permanently wedge the queue
+            // for the NEXT caller's publish() — each call still observes its own
+            // rejection via the returned promise.
+            queue = run.catch(() => { });
+            return run;
+        },
+    };
+}
+/** Phone side, step 1: look up a request by the code the user typed. Returns
+ *  `null` only when nothing is published under that code at all (wrong code,
+ *  or the rendezvous slot's own TTL already reclaimed it). A request that IS
+ *  still present but past its own `expiresAt` does NOT return `null` — it
+ *  throws (via `parsePairingRequest`), so the caller can tell "wrong code"
+ *  apart from "right code, but it expired" and say so accurately. If the
+ *  slot has ALREADY moved past the request phase (a grant is published
+ *  there — `kind === 'octobot-pairing-grant'`, detectable without unsealing
+ *  anything, see `pairingGrantExchange.ts`), this throws a distinct
+ *  `OctoBotConflictError` rather than a generic parse failure, so a caller
+ *  re-checking an already-approved code gets an accurate "already used"
+ *  signal instead of "malformed pairing request payload". */
+export async function fetchPairingRequestByCode(opts) {
+    const client = createRendezvousClient({
+        baseUrl: opts.rendezvous.baseUrl,
+        namespace: opts.rendezvous.namespace,
+        fetch: opts.fetch,
+        timeoutMs: opts.timeoutMs,
+    });
+    try {
+        const doc = await pullRendezvousDoc(client, joinSessionPath(opts.code));
+        if (!doc)
+            return null;
+        if (doc.data.kind === 'octobot-pairing-grant') {
+            throw new OctoBotConflictError(doc.hash, undefined, 'this code has already been used to complete a pairing');
+        }
+        const request = parsePairingRequest(JSON.stringify(doc.data), opts.code);
+        return { request, hash: doc.hash };
+    }
+    catch (err) {
+        if (err instanceof OctoBotConflictError)
+            throw err;
+        rethrowAsOctoBotError(err);
+    }
+}
+/** Shared by `pairingGrantExchange.ts`'s polling loops — keep the
+ *  abort/timeout/cleanup semantics in exactly one place. */
+export function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new DOMException('aborted', 'AbortError'));
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new DOMException('aborted', 'AbortError'));
+        });
+    });
+}
+//# sourceMappingURL=pairingRequest.js.map

package/dist/client/pairing/pairingRequest.js.map

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

package/dist/client/strategy.d.ts

@@ -0,0 +1,36 @@
+import type { Strategy as ProtocolStrategy } from '@drakkar.software/octobot-protocol';
+import { type BuildStrategyOptions, type StrategyInput, type MmInput, type GridInput, type DcaInput, type IndexInput, type CopyInput, type SignalInput, type StrategyInputPatch } from '../protocol/strategy/index.js';
+/** Pure, synchronous(-ish — everything here is actually sync, `Promise`-free),
+ *  zero-I/O strategy builders. Needs no connection: build a strategy, then
+ *  pass it to `client.automations.create()` or `client.strategies.create()`. */
+export interface StrategyBuilders {
+    dca(input: DcaInput, opts?: BuildStrategyOptions): ProtocolStrategy;
+    grid(input: GridInput, opts?: BuildStrategyOptions): ProtocolStrategy;
+    index(input: IndexInput, opts?: BuildStrategyOptions): ProtocolStrategy;
+    marketMaking(input: MmInput, opts?: BuildStrategyOptions): ProtocolStrategy;
+    copy(input: CopyInput, opts?: BuildStrategyOptions): ProtocolStrategy;
+    signal(input: SignalInput, opts?: BuildStrategyOptions): ProtocolStrategy;
+    genericProcess(opts?: BuildStrategyOptions): ProtocolStrategy;
+    /** The discriminated-union entry point (`{ kind: 'dca', dca: {...} }`),
+     *  for callers that already have a `StrategyInput` rather than picking a
+     *  kind-specific method. */
+    build(input: StrategyInput, opts?: BuildStrategyOptions): ProtocolStrategy;
+    /** Recover an editable input from a strategy the node returned — the
+     *  inverse of every builder above. Feed the result's fields into a new
+     *  `strategy.dca(...)`/etc call (with `bumpVersion` applied) to edit it. */
+    toInput(existing: ProtocolStrategy): StrategyInputPatch;
+    /** Bump a `MAJOR.MINOR.PATCH` version string's patch component by one. */
+    bumpVersion(version: string): string;
+}
+/** Needs no `ClientSession` — unlike every other `create*Api` in
+ *  `client/adapters/`, these builders do no I/O and touch no connection,
+ *  so there is nothing to construct them from. Kept as a factory anyway, for
+ *  the same reason those are: `strategy` below is just `createStrategyBuilders()`
+ *  called once, so the object literal isn't duplicated between this module's
+ *  own export and a hypothetical future caller that wants its own instance. */
+export declare function createStrategyBuilders(): StrategyBuilders;
+/** The public entry point every caller uses — `strategy.dca(...)`, etc. A
+ *  single shared instance, since these builders carry no state and creating
+ *  a fresh one per call would be pointless. */
+export declare const strategy: StrategyBuilders;
+//# sourceMappingURL=strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/client/strategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,oCAAoC,CAAA;AACtF,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,WAAW,EAGhB,KAAK,kBAAkB,EACxB,MAAM,+BAA+B,CAAA;AAEtC;;gFAEgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IACnE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IACrE,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IACvE,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IAC3E,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IACrE,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IACzE,cAAc,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IAC7D;;gCAE4B;IAC5B,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IAC1E;;gFAE4E;IAC5E,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,CAAA;IACvD,0EAA0E;IAC1E,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CACrC;AAED;;;;;+EAK+E;AAC/E,wBAAgB,sBAAsB,IAAI,gBAAgB,CAazD;AAED;;+CAE+C;AAC/C,eAAO,MAAM,QAAQ,EAAE,gBAA2C,CAAA"}

package/dist/client/strategy.js

@@ -0,0 +1,26 @@
+import { buildStrategy, protocolStrategyToInput, bumpStrategyPatchVersion, } from '../protocol/strategy/index.js';
+/** Needs no `ClientSession` — unlike every other `create*Api` in
+ *  `client/adapters/`, these builders do no I/O and touch no connection,
+ *  so there is nothing to construct them from. Kept as a factory anyway, for
+ *  the same reason those are: `strategy` below is just `createStrategyBuilders()`
+ *  called once, so the object literal isn't duplicated between this module's
+ *  own export and a hypothetical future caller that wants its own instance. */
+export function createStrategyBuilders() {
+    return {
+        dca: (input, opts) => buildStrategy({ kind: 'dca', dca: input }, opts),
+        grid: (input, opts) => buildStrategy({ kind: 'grid', grid: input }, opts),
+        index: (input, opts) => buildStrategy({ kind: 'basket', basket: input }, opts),
+        marketMaking: (input, opts) => buildStrategy({ kind: 'mm', mm: input }, opts),
+        copy: (input, opts) => buildStrategy({ kind: 'copy', copy: input }, opts),
+        signal: (input, opts) => buildStrategy({ kind: 'signal', signal: input }, opts),
+        genericProcess: (opts) => buildStrategy({ kind: 'custom' }, opts),
+        build: (input, opts) => buildStrategy(input, opts),
+        toInput: (existing) => protocolStrategyToInput(existing),
+        bumpVersion: (version) => bumpStrategyPatchVersion(version),
+    };
+}
+/** The public entry point every caller uses — `strategy.dca(...)`, etc. A
+ *  single shared instance, since these builders carry no state and creating
+ *  a fresh one per call would be pointless. */
+export const strategy = createStrategyBuilders();
+//# sourceMappingURL=strategy.js.map

package/dist/client/strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../src/client/strategy.ts"],"names":[],"mappings":"AACA,OAAO,EACL,aAAa,EASb,uBAAuB,EACvB,wBAAwB,GAEzB,MAAM,+BAA+B,CAAA;AAyBtC;;;;;+EAK+E;AAC/E,MAAM,UAAU,sBAAsB;IACpC,OAAO;QACL,GAAG,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;QACtE,IAAI,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;QACzE,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;QAC9E,YAAY,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;QAC7E,IAAI,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;QACzE,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC;QAC/E,cAAc,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC;QACjE,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC;QAClD,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,uBAAuB,CAAC,QAAQ,CAAC;QACxD,WAAW,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,wBAAwB,CAAC,OAAO,CAAC;KAC5D,CAAA;AACH,CAAC;AAED;;+CAE+C;AAC/C,MAAM,CAAC,MAAM,QAAQ,GAAqB,sBAAsB,EAAE,CAAA"}

package/dist/collections/index.d.ts

@@ -0,0 +1,3 @@
+export { resolveStoragePath, pullPath, pushPath } from './paths.js';
+export { NODE_COLLECTIONS, type NodeCollectionInfo, type NodeCollectionKey } from './nodeCollections.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/collections/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/collections/index.js

@@ -0,0 +1,3 @@
+export { resolveStoragePath, pullPath, pushPath } from './paths.js';
+export { NODE_COLLECTIONS } from './nodeCollections.js';
+//# sourceMappingURL=index.js.map

package/dist/collections/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/collections/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAmD,MAAM,sBAAsB,CAAA"}

package/dist/collections/nodeCollections.d.ts

@@ -0,0 +1,57 @@
+/** The collections a self-hosted OctoBot node actually serves under
+ *  `users/{identity}/...`. Each `encryptionInfo` is the HKDF `info` string the
+ *  node derives its per-collection key from — it MUST equal
+ *  `'octobot-sync-' + <node's own Collections enum value>`.
+ *  @see packages/sync/octobot_sync/enums.py — Collections
+ *  @see packages/sync/octobot_sync/crypto.py */
+export type NodeCollectionInfo = {
+    name: string;
+    storagePath: string;
+    encryptionInfo: string;
+    /** Node never accepts a push for this collection — pull only. */
+    pullOnly?: boolean;
+    /** Append-only, push-only: each push publishes ONE queue element the node
+     *  consumes and executes. Re-sending an element is re-executing it. */
+    appendOnly?: boolean;
+};
+export declare const NODE_COLLECTIONS: {
+    /** Bundles the node-computed `automations`/`user_actions` fields alongside
+     *  whatever else a higher-level client stores in the same document. */
+    readonly userData: {
+        readonly name: "user-data";
+        readonly storagePath: "users/{identity}/data";
+        readonly encryptionInfo: "octobot-sync-user-data";
+    };
+    readonly accounts: {
+        readonly name: "accounts";
+        readonly storagePath: "users/{identity}/accounts";
+        readonly encryptionInfo: "octobot-sync-user-accounts";
+    };
+    /** The node stores this encrypted and opaque — it never reads a field. */
+    readonly settings: {
+        readonly name: "settings";
+        readonly storagePath: "users/{identity}/settings";
+        readonly encryptionInfo: "octobot-sync-user-settings";
+    };
+    readonly strategies: {
+        readonly name: "strategies";
+        readonly storagePath: "users/{identity}/strategies";
+        readonly encryptionInfo: "octobot-sync-user-strategies";
+    };
+    readonly actions: {
+        readonly name: "actions";
+        readonly storagePath: "users/{identity}/actions";
+        readonly encryptionInfo: "octobot-sync-user-actions";
+        readonly appendOnly: true;
+    };
+    /** One document per exchange account — fan out over `{accountId}` yourself;
+     *  there is no single "list all trading docs" pull. */
+    readonly accountTrading: {
+        readonly name: "user-accounts-trading";
+        readonly storagePath: "users/{identity}/accounts/{accountId}/trading";
+        readonly encryptionInfo: "octobot-sync-user-accounts-trading";
+        readonly pullOnly: true;
+    };
+};
+export type NodeCollectionKey = keyof typeof NODE_COLLECTIONS;
+//# sourceMappingURL=nodeCollections.d.ts.map

package/dist/collections/nodeCollections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeCollections.d.ts","sourceRoot":"","sources":["../../src/collections/nodeCollections.ts"],"names":[],"mappings":"AAAA;;;;;gDAKgD;AAChD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;2EACuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED,eAAO,MAAM,gBAAgB;IAC3B;2EACuE;;;;;;;;;;;IAWvE,0EAA0E;;;;;;;;;;;;;;;;;IAiB1E;2DACuD;;;;;;;CAOF,CAAA;AAEvD,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,gBAAgB,CAAA"}

package/dist/collections/nodeCollections.js

@@ -0,0 +1,40 @@
+export const NODE_COLLECTIONS = {
+    /** Bundles the node-computed `automations`/`user_actions` fields alongside
+     *  whatever else a higher-level client stores in the same document. */
+    userData: {
+        name: 'user-data',
+        storagePath: 'users/{identity}/data',
+        encryptionInfo: 'octobot-sync-user-data',
+    },
+    accounts: {
+        name: 'accounts',
+        storagePath: 'users/{identity}/accounts',
+        encryptionInfo: 'octobot-sync-user-accounts',
+    },
+    /** The node stores this encrypted and opaque — it never reads a field. */
+    settings: {
+        name: 'settings',
+        storagePath: 'users/{identity}/settings',
+        encryptionInfo: 'octobot-sync-user-settings',
+    },
+    strategies: {
+        name: 'strategies',
+        storagePath: 'users/{identity}/strategies',
+        encryptionInfo: 'octobot-sync-user-strategies',
+    },
+    actions: {
+        name: 'actions',
+        storagePath: 'users/{identity}/actions',
+        encryptionInfo: 'octobot-sync-user-actions',
+        appendOnly: true,
+    },
+    /** One document per exchange account — fan out over `{accountId}` yourself;
+     *  there is no single "list all trading docs" pull. */
+    accountTrading: {
+        name: 'user-accounts-trading',
+        storagePath: 'users/{identity}/accounts/{accountId}/trading',
+        encryptionInfo: 'octobot-sync-user-accounts-trading',
+        pullOnly: true,
+    },
+};
+//# sourceMappingURL=nodeCollections.js.map

package/dist/collections/nodeCollections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeCollections.js","sourceRoot":"","sources":["../../src/collections/nodeCollections.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B;2EACuE;IACvE,QAAQ,EAAE;QACR,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,uBAAuB;QACpC,cAAc,EAAE,wBAAwB;KACzC;IACD,QAAQ,EAAE;QACR,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,2BAA2B;QACxC,cAAc,EAAE,4BAA4B;KAC7C;IACD,0EAA0E;IAC1E,QAAQ,EAAE;QACR,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,2BAA2B;QACxC,cAAc,EAAE,4BAA4B;KAC7C;IACD,UAAU,EAAE;QACV,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,6BAA6B;QAC1C,cAAc,EAAE,8BAA8B;KAC/C;IACD,OAAO,EAAE;QACP,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,0BAA0B;QACvC,cAAc,EAAE,2BAA2B;QAC3C,UAAU,EAAE,IAAI;KACjB;IACD;2DACuD;IACvD,cAAc,EAAE;QACd,IAAI,EAAE,uBAAuB;QAC7B,WAAW,EAAE,+CAA+C;QAC5D,cAAc,EAAE,oCAAoC;QACpD,QAAQ,EAAE,IAAI;KACf;CACoD,CAAA"}

package/dist/collections/paths.d.ts

@@ -0,0 +1,7 @@
+/** Substitutes `{key}` placeholders in a storage-path template, e.g.
+ *  `resolveStoragePath('users/{identity}/accounts', { identity: userId })`.
+ *  Generic — carries no product knowledge of which collections exist. */
+export declare function resolveStoragePath(storagePath: string, params: Record<string, string>): string;
+export declare function pullPath(storagePath: string, params: Record<string, string>): string;
+export declare function pushPath(storagePath: string, params: Record<string, string>): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/collections/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/collections/paths.ts"],"names":[],"mappings":"AAAA;;yEAEyE;AACzE,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAK9F;AAED,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEpF;AAED,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEpF"}

package/dist/collections/paths.js

@@ -0,0 +1,13 @@
+/** Substitutes `{key}` placeholders in a storage-path template, e.g.
+ *  `resolveStoragePath('users/{identity}/accounts', { identity: userId })`.
+ *  Generic — carries no product knowledge of which collections exist. */
+export function resolveStoragePath(storagePath, params) {
+    return Object.entries(params).reduce((path, [key, value]) => path.replaceAll(`{${key}}`, encodeURIComponent(value)), storagePath);
+}
+export function pullPath(storagePath, params) {
+    return `/pull/${resolveStoragePath(storagePath, params)}`;
+}
+export function pushPath(storagePath, params) {
+    return `/push/${resolveStoragePath(storagePath, params)}`;
+}
+//# sourceMappingURL=paths.js.map