@soundbi/sound-connect 0.1.0

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAID,qEAAqE;AACrE,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,GAAG,CAAC,EAAE,MAAM;CAIzB;AAED,0DAA0D;AAC1D,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAKxC;AAED,gDAAgD;AAChD,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,YAAY,CAAC,EAAE,MAAM;CAQlC;AAED,iDAAiD;AACjD,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAIzC;AAED,2EAA2E;AAC3E,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,MAAM,EAAE,MAAM;CAI3B;AA4FD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,WAAW,EAAE,CAAC,CA6BxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,iBAAiB,CAAC,CA2C5B"}

package/dist/proxy.js

@@ -0,0 +1,217 @@
+/**
+ * Backend proxy module for the Sound Connect bridge (STORY-008, ADR-002, ADR-003).
+ *
+ * Implements two operations against the backend `/mcp/:slug` endpoint:
+ *   1. fetchBackendTools — issues a `tools/list` JSON-RPC call and returns the tool list.
+ *   2. callBackendTool   — issues a `tools/call` JSON-RPC call and returns the result.
+ *
+ * Both operations authenticate via `Authorization: Bearer <token>` (ADR-003).
+ * The backend uses StreamableHTTPServerTransport in stateless mode — every call is an
+ * independent HTTP POST; no session handshake is required.
+ *
+ * ADR-011 error handling:
+ *   - 401 → BackendAuthError (token invalid / expired — user must re-login)
+ *   - 403 → BackendForbiddenError (peer not a member of this client)
+ *   - 429 → BackendRateLimitError (back off and retry)
+ *   - 5xx → BackendUnavailableError (backend unreachable / internal error)
+ *   - JSON parse failure → BackendProtocolError (unexpected response shape)
+ *
+ * These are surfaced as MCP tool errors in tools.ts — never as silent failures.
+ */
+// ── Typed error classes (ADR-011) ─────────────────────────────────────────────
+/** The bearer token was rejected (401). Peer must re-run `login`. */
+export class BackendAuthError extends Error {
+    constructor(msg) {
+        super(msg ?? 'Bearer token rejected by backend — run `npx @soundbi/sound-connect login` to re-authenticate.');
+        this.name = 'BackendAuthError';
+    }
+}
+/** Peer is not a member of the requested client (403). */
+export class BackendForbiddenError extends Error {
+    constructor(slug, hint) {
+        const base = `Access denied to client "${slug}".`;
+        super(hint ? `${base} ${hint}` : `${base} Verify your Sound Connect membership.`);
+        this.name = 'BackendForbiddenError';
+    }
+}
+/** Backend is rate-limiting this peer (429). */
+export class BackendRateLimitError extends Error {
+    constructor(retryAfterMs) {
+        super(retryAfterMs !== undefined
+            ? `Rate limited by backend. Retry after ${Math.ceil(retryAfterMs / 1000)} seconds.`
+            : 'Rate limited by backend. Wait a moment and try again.');
+        this.name = 'BackendRateLimitError';
+    }
+}
+/** Backend returned a 5xx or was unreachable. */
+export class BackendUnavailableError extends Error {
+    constructor(status, msg) {
+        super(msg ?? `Backend returned HTTP ${status}. The server may be temporarily unavailable — try again.`);
+        this.name = 'BackendUnavailableError';
+    }
+}
+/** The backend response did not conform to the expected JSON-RPC shape. */
+export class BackendProtocolError extends Error {
+    constructor(detail) {
+        super(`Unexpected backend response: ${detail}`);
+        this.name = 'BackendProtocolError';
+    }
+}
+// ── JSON-RPC helpers ───────────────────────────────────────────────────────────
+let _rpcId = 1;
+function makeRpcId() {
+    return _rpcId++;
+}
+function buildHeaders(token) {
+    return {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json, text/event-stream',
+        'Authorization': `Bearer ${token}`,
+    };
+}
+function mcpUrl(backendUrl, slug) {
+    return `${backendUrl}/mcp/${encodeURIComponent(slug)}`;
+}
+// ── HTTP error classification (ADR-011) ───────────────────────────────────────
+async function throwForStatus(res, slug) {
+    if (res.ok)
+        return;
+    let bodyText = '';
+    try {
+        bodyText = await res.text();
+    }
+    catch { /* ignore body read failure */ }
+    let hint;
+    try {
+        const parsed = JSON.parse(bodyText);
+        hint = (parsed['hint'] ?? parsed['error']);
+    }
+    catch { /* body was not JSON */ }
+    switch (res.status) {
+        case 401:
+            throw new BackendAuthError(hint);
+        case 403:
+            throw new BackendForbiddenError(slug, hint);
+        case 429: {
+            const retryHeader = res.headers.get('retry-after') ?? res.headers.get('x-retry-after');
+            const retryMs = retryHeader ? parseInt(retryHeader, 10) * 1000 : (() => {
+                try {
+                    return JSON.parse(bodyText)['retry_after_ms'];
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            throw new BackendRateLimitError(retryMs);
+        }
+        default:
+            if (res.status >= 500) {
+                throw new BackendUnavailableError(res.status, hint);
+            }
+            throw new BackendProtocolError(`HTTP ${res.status}: ${bodyText.slice(0, 200)}`);
+    }
+}
+// ── SSE / JSON response parsing ───────────────────────────────────────────────
+async function parseRpcResponse(res) {
+    const contentType = res.headers.get('content-type') ?? '';
+    if (contentType.includes('text/event-stream')) {
+        const text = await res.text();
+        for (const line of text.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith('data:')) {
+                const json = trimmed.slice(5).trim();
+                if (json) {
+                    try {
+                        return JSON.parse(json);
+                    }
+                    catch { /* try next line */ }
+                }
+            }
+        }
+        throw new BackendProtocolError('SSE stream contained no parseable data line');
+    }
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new BackendProtocolError(`Non-JSON response body: ${text.slice(0, 200)}`);
+    }
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Fetch the backend's tool list for the bound client.
+ *
+ * Sends `tools/list` JSON-RPC to `/mcp/:slug` with the peer's bearer token.
+ * Returns the tool array from the response; throws a typed BackendXxxError on failure.
+ *
+ * STORY-008 AC1: bridge fetches the backend tool list for the bound client.
+ */
+export async function fetchBackendTools(backendUrl, slug, token) {
+    const url = mcpUrl(backendUrl, slug);
+    const body = JSON.stringify({
+        jsonrpc: '2.0',
+        id: makeRpcId(),
+        method: 'tools/list',
+        params: {},
+    });
+    let res;
+    try {
+        res = await fetch(url, { method: 'POST', headers: buildHeaders(token), body });
+    }
+    catch (err) {
+        throw new BackendUnavailableError(0, `Backend unreachable at ${url}: ${err.message}`);
+    }
+    await throwForStatus(res, slug);
+    const rpc = await parseRpcResponse(res);
+    const result = rpc?.['result'] ?? rpc;
+    const tools = result?.['tools'];
+    if (!Array.isArray(tools)) {
+        throw new BackendProtocolError(`tools/list response missing "tools" array. Got: ${JSON.stringify(rpc).slice(0, 200)}`);
+    }
+    return tools;
+}
+/**
+ * Forward a tool call to the backend `/mcp/:slug` endpoint.
+ *
+ * Sends `tools/call` JSON-RPC with the provided arguments, authenticated via bearer token.
+ * Parses the result and returns it as a BackendToolResult.
+ *
+ * STORY-008 AC2: tool calls forwarded with Authorization: Bearer <token>.
+ * STORY-008 AC4: backend errors surface as MCP tool errors (isError: true), not exceptions.
+ */
+export async function callBackendTool(backendUrl, slug, token, toolName, toolArgs) {
+    const url = mcpUrl(backendUrl, slug);
+    const body = JSON.stringify({
+        jsonrpc: '2.0',
+        id: makeRpcId(),
+        method: 'tools/call',
+        params: {
+            name: toolName,
+            arguments: toolArgs,
+        },
+    });
+    let res;
+    try {
+        res = await fetch(url, { method: 'POST', headers: buildHeaders(token), body });
+    }
+    catch (err) {
+        throw new BackendUnavailableError(0, `Backend unreachable at ${url}: ${err.message}`);
+    }
+    await throwForStatus(res, slug);
+    const rpc = await parseRpcResponse(res);
+    const result = rpc?.['result'] ?? rpc;
+    if (!result || typeof result !== 'object') {
+        throw new BackendProtocolError(`tools/call response missing result. Got: ${JSON.stringify(rpc).slice(0, 200)}`);
+    }
+    const r = result;
+    const content = r['content'];
+    if (!Array.isArray(content)) {
+        throw new BackendProtocolError(`tools/call result missing "content" array. Got: ${JSON.stringify(result).slice(0, 200)}`);
+    }
+    return {
+        content: content,
+        isError: typeof r['isError'] === 'boolean' ? r['isError'] : false,
+    };
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

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

package/dist/retry-queue.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Local ingest retry queue — STORY-013, ADR-011.
+ *
+ * When the Sound Connect backend is briefly unreachable (network error or 5xx),
+ * failed /ingest POST chunks are written to a local file-based queue so they are
+ * not silently lost. A background retry worker drains the queue with exponential
+ * backoff; the ADR-004 sha256 idempotency key makes re-sends safe.
+ *
+ * Queue state machine per item:
+ *   pending  → retry attempts < MAX_RETRY_ATTEMPTS and no permanent 4xx failure
+ *   dead     → 4xx response from backend (auth/permission error — do not retry)
+ *
+ * Queue storage: OS temp dir / sound-connect-queue / <clientSlug> /
+ *   Each item is a JSON file: <enqueuedAt>-<sha256Prefix>.json
+ *   A dead item is renamed to: <name>.dead
+ *
+ * Restart resilience: items survive a bridge restart because they live on disk.
+ *   On startup, call loadQueue() to discover and resume pending items.
+ *
+ * Permanent failures (4xx): written to disk as .dead files and surfaced via
+ *   ingest_status so the user can see them. They are never silently retried.
+ *
+ * ADR-011: fail closed on auth (4xx → dead, not retried), safe retry on transient
+ *   outages, idempotency from ADR-004 makes retries harmless.
+ */
+/** Maximum number of retry attempts before giving up (and marking dead). */
+export declare const MAX_RETRY_ATTEMPTS = 8;
+/** Base delay in milliseconds for exponential backoff (doubles each attempt). */
+export declare const BACKOFF_BASE_MS = 1000;
+/** Maximum backoff cap in milliseconds (~2 minutes). */
+export declare const BACKOFF_MAX_MS = 120000;
+/** Interval in milliseconds between retry worker sweeps. */
+export declare const WORKER_INTERVAL_MS = 10000;
+/** The ingest payload stored in each queue item. */
+export interface QueuedIngestPayload {
+    source_type: 'markdown' | 'transcript';
+    filename: string;
+    content: string;
+    sha256: string;
+    timestamp: string;
+    author_email: string;
+    workstream_slug?: string;
+}
+/** A single queue item persisted to disk. */
+export interface QueueItem {
+    /** Unique ID (timestamp-sha256prefix). */
+    id: string;
+    /** Backend base URL at the time of enqueue. */
+    backendUrl: string;
+    /** Client slug (ADR-005: must match the bound instance slug). */
+    clientSlug: string;
+    /** ISO timestamp when the item was first enqueued. */
+    enqueuedAt: string;
+    /** Number of retry attempts so far (0 = never tried after enqueue). */
+    attempts: number;
+    /** ISO timestamp of the last retry attempt (undefined if never retried). */
+    lastAttemptAt?: string;
+    /** Last error message (for surfacing in ingest_status). */
+    lastError?: string;
+    /** The ingest payload to re-POST. */
+    payload: QueuedIngestPayload;
+}
+/** Summary of the current queue state (for ingest_status tool). */
+export interface QueueStatus {
+    /** Number of items waiting to be retried (pending). */
+    pending: number;
+    /** Number of permanently-failed items (4xx — need user action). */
+    dead: number;
+    /** Details of dead items for surfacing. */
+    deadItems: Array<{
+        id: string;
+        filename: string;
+        enqueuedAt: string;
+        lastError: string;
+    }>;
+    /** Details of pending items (oldest first). */
+    pendingItems: Array<{
+        id: string;
+        filename: string;
+        enqueuedAt: string;
+        attempts: number;
+        lastError?: string;
+    }>;
+}
+/**
+ * Returns the absolute path to the queue directory for a given client slug.
+ * Uses OS temp dir so the queue is writable without special permissions.
+ * Items survive bridge restarts as long as the OS does not clean temp on reboot.
+ *
+ * Overridable via SC_QUEUE_DIR env var for tests.
+ */
+export declare function queueDir(clientSlug: string): string;
+/**
+ * Enqueue a failed ingest chunk to the local retry queue.
+ *
+ * Writes a JSON file to the queue directory. The file is named by a unique ID
+ * derived from the enqueue time and the chunk's sha256 prefix (stable, not random —
+ * so if the same chunk is enqueued twice due to a crash, we don't duplicate items;
+ * but the timestamp disambiguates distinct enqueue events for the same content).
+ *
+ * @param backendUrl  Backend URL that was unreachable.
+ * @param clientSlug  Bound client slug.
+ * @param payload     The ingest payload that failed.
+ * @param lastError   The error message from the failed attempt.
+ * @returns The created QueueItem.
+ */
+export declare function enqueueFailedChunk(backendUrl: string, clientSlug: string, payload: QueuedIngestPayload, lastError: string): Promise<QueueItem>;
+/**
+ * Load all pending queue items from disk.
+ *
+ * Reads all .json files in the queue directory. Dead (.dead) files are NOT
+ * returned here — use loadDeadItems() for those.
+ *
+ * @param clientSlug  Bound client slug.
+ * @returns Array of pending QueueItems, sorted by enqueuedAt ascending.
+ */
+export declare function loadPendingItems(clientSlug: string): Promise<QueueItem[]>;
+/**
+ * Load all dead items from disk.
+ *
+ * Dead items are .dead files in the queue directory (4xx permanent failures).
+ *
+ * @param clientSlug  Bound client slug.
+ * @returns Array of dead QueueItems.
+ */
+export declare function loadDeadItems(clientSlug: string): Promise<QueueItem[]>;
+/**
+ * Returns a summary of the current queue state for the `ingest_status` MCP tool.
+ *
+ * STORY-013 AC3: reports pending/failed queue depth.
+ *
+ * @param clientSlug  Bound client slug.
+ */
+export declare function getQueueStatus(clientSlug: string): Promise<QueueStatus>;
+/**
+ * Compute the exponential backoff delay for a given attempt number.
+ *
+ * Attempt 1 → BACKOFF_BASE_MS (1s)
+ * Attempt 2 → 2s
+ * Attempt 3 → 4s
+ * ...capped at BACKOFF_MAX_MS.
+ */
+export declare function backoffMs(attempt: number): number;
+/**
+ * Returns true if an item is ready to retry based on its attempt count and the
+ * time of the last attempt.
+ *
+ * An item with 0 attempts is always ready (never tried yet after enqueue).
+ * An item that has been attempted is ready once the backoff window has elapsed.
+ */
+export declare function isReadyToRetry(item: QueueItem, now?: Date): boolean;
+/**
+ * Result of a single retry POST attempt.
+ */
+export type RetryAttemptResult = {
+    outcome: 'success';
+    deduped: boolean;
+} | {
+    outcome: 'transient';
+    error: string;
+} | {
+    outcome: 'permanent';
+    error: string;
+};
+/**
+ * Attempt to POST a queued ingest chunk to the backend.
+ *
+ * Distinguishes:
+ *   - success  (2xx)                → remove from queue
+ *   - transient (network / 5xx)    → increment attempts, retry later
+ *   - permanent (4xx)              → mark dead, surface to user (ADR-011)
+ *
+ * @param item   The queue item to retry.
+ * @param token  Current bearer token (acquired silently before calling).
+ */
+export declare function attemptRetry(item: QueueItem, token: string): Promise<RetryAttemptResult>;
+/** Callback type for acquiring a fresh token before each retry sweep. */
+export type TokenProvider = () => Promise<string | null>;
+/**
+ * Run one sweep of the retry worker:
+ *   1. Load all pending items.
+ *   2. For each item that is ready to retry (backoff elapsed):
+ *      a. Acquire a fresh token (silent).
+ *      b. Attempt the POST.
+ *      c. On success  → remove from disk.
+ *      d. On transient → increment attempts; if exhausted → mark dead.
+ *      e. On permanent → mark dead.
+ *
+ * @param clientSlug    Bound client slug.
+ * @param tokenProvider Async function that returns a fresh access token or null.
+ * @returns Summary of this sweep.
+ */
+export declare function runRetrySweep(clientSlug: string, tokenProvider: TokenProvider): Promise<{
+    delivered: number;
+    exhausted: number;
+    skipped: number;
+    tokenMissing: boolean;
+}>;
+/**
+ * Start the background retry worker.
+ *
+ * Runs runRetrySweep() every WORKER_INTERVAL_MS milliseconds.
+ * Safe to call multiple times — subsequent calls are no-ops if already running.
+ *
+ * STORY-013 AC2: The worker drains the queue with exponential backoff.
+ * STORY-013 AC4: Items survive restarts; the worker picks them up on next sweep.
+ *
+ * @param clientSlug    Bound client slug.
+ * @param tokenProvider Async function that returns a fresh access token or null.
+ */
+export declare function startRetryWorker(clientSlug: string, tokenProvider: TokenProvider): void;
+/**
+ * Stop the background retry worker.
+ * Called during tests or graceful shutdown.
+ */
+export declare function stopRetryWorker(): void;
+/**
+ * Remove all pending and dead items from the queue directory.
+ * Intended for test teardown only — do not call in production paths.
+ *
+ * @param clientSlug  Bound client slug.
+ */
+export declare function clearQueue(clientSlug: string): Promise<void>;
+/**
+ * Clear all dead items (permanent failures) from the queue.
+ * Useful after the user re-authenticates and wants to purge the dead letter list.
+ *
+ * @param clientSlug  Bound client slug.
+ */
+export declare function clearDeadItems(clientSlug: string): Promise<void>;
+/**
+ * Get the base filename of a queue item (without extension).
+ * Exported for use in tests.
+ */
+export declare function itemBasename(item: QueueItem): string;
+//# sourceMappingURL=retry-queue.d.ts.map

package/dist/retry-queue.d.ts.map

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