optio-api 0.1.0

package/dist/sse-options.js

@@ -0,0 +1,82 @@
+/**
+ * Shared query-parsing helper for SSE / poller routes.
+ *
+ * Each adapter (fastify, express, nextjs-app, nextjs-pages) historically
+ * duplicated the same SSE/poller query-parsing block:
+ *   - reject legacy `metadata.*` keys with a 400
+ *   - parse the `metadataFilter` JSON via parseMetadataFilterQuery
+ *   - coerce `maxDepth` from string to number
+ *   - pass `database` / `prefix` through to resolveDb
+ *
+ * `parseSseOptions(rawQuery)` returns the parsed shape; it throws on bad
+ * `metadataFilter` JSON or bad `maxDepth` so adapters can map to a 400.
+ *
+ * `checkLegacyMetadataParams(rawQuery)` throws `LegacyMetadataParamError`
+ * when legacy `metadata.*` keys are present; adapters catch and emit 400.
+ *
+ * Database resolution stays in the adapter (a single
+ * `resolveDb(dbOpts, sseOpts)` line), per Task 5 / commit A4 of
+ * docs/2026-05-08-engine-rpc-migration-phase-3-design.md §3.
+ */
+import { parseMetadataFilterQuery, detectLegacyMetadataParams, formatLegacyMetadataMessage, } from './metadata-filter-query.js';
+export class LegacyMetadataParamError extends Error {
+    keys;
+    constructor(keys) {
+        super(formatLegacyMetadataMessage(keys));
+        this.name = 'LegacyMetadataParamError';
+        this.keys = keys;
+    }
+}
+/**
+ * Parse SSE/poller query parameters into a typed shape. Throws Error on
+ * invalid `metadataFilter` JSON or on a non-finite/negative `maxDepth`;
+ * adapters should map a thrown Error to a 400 response.
+ *
+ * Does NOT inspect legacy `metadata.*` keys — call
+ * `checkLegacyMetadataParams` separately for that, since adapters want to
+ * distinguish the two error cases.
+ */
+export function parseSseOptions(rawQuery) {
+    const out = {};
+    if (typeof rawQuery.database === 'string')
+        out.database = rawQuery.database;
+    if (typeof rawQuery.prefix === 'string')
+        out.prefix = rawQuery.prefix;
+    // metadataFilter — parseMetadataFilterQuery returns a discriminated union
+    // { ok: true, value } | { ok: false, error }. We only forward the parsed
+    // object on success; on failure we throw so the adapter maps to a 400.
+    const mfRaw = rawQuery.metadataFilter;
+    if (mfRaw !== undefined && mfRaw !== null && mfRaw !== '') {
+        const parsed = parseMetadataFilterQuery(typeof mfRaw === 'string' ? mfRaw : undefined);
+        if (!parsed.ok) {
+            throw new Error(parsed.error);
+        }
+        out.metadataFilter = parsed.value;
+    }
+    // maxDepth — coerce string to int. parseInt returns NaN on garbage, which
+    // !Number.isFinite catches. Negative depths are also invalid.
+    const maxDepthRaw = rawQuery.maxDepth;
+    if (typeof maxDepthRaw === 'string' && maxDepthRaw.length > 0) {
+        const n = parseInt(maxDepthRaw, 10);
+        if (!Number.isFinite(n) || n < 0) {
+            throw new Error(`Invalid maxDepth: ${maxDepthRaw}`);
+        }
+        out.maxDepth = n;
+    }
+    else if (typeof maxDepthRaw === 'number' && Number.isFinite(maxDepthRaw) && maxDepthRaw >= 0) {
+        out.maxDepth = maxDepthRaw;
+    }
+    return out;
+}
+/**
+ * Throws `LegacyMetadataParamError` if the raw query contains any legacy
+ * `metadata.*` keys (a removed pre-`metadataFilter` API). Adapters catch
+ * this and emit a 400 with the formatted migration message.
+ */
+export function checkLegacyMetadataParams(rawQuery) {
+    const legacyKeys = detectLegacyMetadataParams(rawQuery);
+    if (legacyKeys.length > 0) {
+        throw new LegacyMetadataParamError(legacyKeys);
+    }
+}
+//# sourceMappingURL=sse-options.js.map

package/dist/sse-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-options.js","sourceRoot":"","sources":["../src/sse-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,4BAA4B,CAAC;AAGpC,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjC,IAAI,CAAW;IAC/B,YAAY,IAAc;QACxB,KAAK,CAAC,2BAA2B,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAiC;IAEjC,MAAM,GAAG,GAAqB,EAAE,CAAC;IAEjC,IAAI,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ;QAAE,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;IAC5E,IAAI,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ;QAAE,GAAG,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAEtE,0EAA0E;IAC1E,yEAAyE;IACzE,uEAAuE;IACvE,MAAM,KAAK,GAAG,QAAQ,CAAC,cAAc,CAAC;IACtC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,wBAAwB,CACrC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAC9C,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,GAAG,CAAC,cAAc,GAAG,MAAM,CAAC,KAAK,CAAC;IACpC,CAAC;IAED,0EAA0E;IAC1E,8DAA8D;IAC9D,MAAM,WAAW,GAAG,QAAQ,CAAC,QAAQ,CAAC;IACtC,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9D,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC;IACnB,CAAC;SAAM,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QAC/F,GAAG,CAAC,QAAQ,GAAG,WAAW,CAAC;IAC7B,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAiC;IAEjC,MAAM,UAAU,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACxD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,wBAAwB,CAAC,UAAU,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/stream-poller.d.ts

@@ -0,0 +1,21 @@
+import { type Db } from 'mongodb';
+import type { ProcessMetadataFilter } from 'optio-contracts';
+export interface StreamPollerOptions {
+    db: Db;
+    prefix: string;
+    sendEvent: (data: unknown) => void;
+    onError: () => void;
+    metadataFilter?: ProcessMetadataFilter;
+}
+export interface ListPollerHandle {
+    start(): void;
+    stop(): void;
+}
+export declare function createListPoller(opts: StreamPollerOptions): ListPollerHandle;
+export interface TreePollerOptions extends Omit<StreamPollerOptions, 'metadataFilter'> {
+    rootId: string;
+    baseDepth: number;
+    maxDepth?: number;
+}
+export declare function createTreePoller(opts: TreePollerOptions): ListPollerHandle;
+//# sourceMappingURL=stream-poller.d.ts.map

package/dist/stream-poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-poller.d.ts","sourceRoot":"","sources":["../src/stream-poller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,EAAE,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7D,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,EAAE,CAAC;IACP,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,mBAAmB,GAAG,gBAAgB,CA2D5E;AAED,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,mBAAmB,EAAE,gBAAgB,CAAC;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CAqG1E"}

package/dist/stream-poller.js

@@ -0,0 +1,146 @@
+import { ObjectId } from 'mongodb';
+import { metadataFilterToMongo } from './metadata-filter-query.js';
+export function createListPoller(opts) {
+    const { db, prefix, sendEvent, onError, metadataFilter } = opts;
+    const col = db.collection(`${prefix}_processes`);
+    const filter = metadataFilterToMongo(metadataFilter);
+    let interval = null;
+    let lastSnapshot = '';
+    async function poll() {
+        try {
+            const allProcs = await col.find(filter).sort({ depth: 1, order: 1, _id: 1 }).toArray();
+            const snapshot = JSON.stringify(allProcs.map((p) => ({
+                id: p._id,
+                state: p.status?.state,
+                percent: p.progress?.percent,
+                message: p.progress?.message,
+                supportsResume: p.supportsResume ?? false,
+                hasSavedState: p.hasSavedState ?? false,
+            })));
+            if (snapshot !== lastSnapshot) {
+                lastSnapshot = snapshot;
+                sendEvent({
+                    type: 'update',
+                    processes: allProcs.map((p) => ({
+                        _id: p._id.toString(),
+                        processId: p.processId,
+                        name: p.name,
+                        status: p.status,
+                        progress: p.progress,
+                        cancellable: p.cancellable,
+                        special: p.special,
+                        warning: p.warning,
+                        metadata: p.metadata,
+                        depth: p.depth ?? 0,
+                        supportsResume: p.supportsResume ?? false,
+                        hasSavedState: p.hasSavedState ?? false,
+                    })),
+                });
+            }
+        }
+        catch {
+            stop();
+            onError();
+        }
+    }
+    function start() {
+        interval = setInterval(poll, 1000);
+    }
+    function stop() {
+        if (interval) {
+            clearInterval(interval);
+            interval = null;
+        }
+    }
+    return { start, stop };
+}
+export function createTreePoller(opts) {
+    const { db, prefix, sendEvent, onError, rootId, baseDepth, maxDepth } = opts;
+    const col = db.collection(`${prefix}_processes`);
+    let interval = null;
+    let lastSnapshot = '';
+    const lastLogCounts = new Map();
+    let firstPoll = true;
+    async function poll() {
+        try {
+            const filter = { rootId: new ObjectId(rootId) };
+            if (maxDepth !== undefined) {
+                filter.depth = { $lte: baseDepth + maxDepth };
+            }
+            const allProcs = await col.find(filter).sort({ depth: 1, order: 1 }).toArray();
+            const snapshot = JSON.stringify(allProcs.map((p) => ({
+                id: p._id, status: p.status, progress: p.progress,
+                widgetData: p.widgetData, uiWidget: p.uiWidget,
+                supportsResume: p.supportsResume ?? false,
+                hasSavedState: p.hasSavedState ?? false,
+            })));
+            if (snapshot !== lastSnapshot) {
+                lastSnapshot = snapshot;
+                sendEvent({
+                    type: 'update',
+                    processes: allProcs.map((p) => ({
+                        _id: p._id.toString(),
+                        parentId: p.parentId?.toString() ?? null,
+                        name: p.name,
+                        status: p.status,
+                        progress: p.progress,
+                        cancellable: p.cancellable ?? false,
+                        depth: p.depth,
+                        order: p.order,
+                        widgetData: p.widgetData,
+                        uiWidget: p.uiWidget,
+                        supportsResume: p.supportsResume ?? false,
+                        hasSavedState: p.hasSavedState ?? false,
+                    })),
+                });
+            }
+            // Detect log changes
+            let logCleared = false;
+            const newLogEntries = [];
+            for (const p of allProcs) {
+                const pid = p._id.toString();
+                const logLen = (p.log ?? []).length;
+                const lastLen = lastLogCounts.get(pid) ?? 0;
+                if (logLen < lastLen) {
+                    logCleared = true;
+                    lastLogCounts.set(pid, 0);
+                }
+                const effectiveLastLen = lastLogCounts.get(pid) ?? 0;
+                if (logLen > effectiveLastLen) {
+                    const entries = (p.log ?? []).slice(firstPoll ? 0 : effectiveLastLen);
+                    for (const entry of entries) {
+                        newLogEntries.push({
+                            ...entry,
+                            processId: pid,
+                            processLabel: p.name,
+                        });
+                    }
+                    lastLogCounts.set(pid, logLen);
+                }
+            }
+            firstPoll = false;
+            if (logCleared) {
+                sendEvent({ type: 'log-clear' });
+            }
+            if (newLogEntries.length > 0) {
+                newLogEntries.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+                sendEvent({ type: 'log', entries: newLogEntries });
+            }
+        }
+        catch {
+            stop();
+            onError();
+        }
+    }
+    function start() {
+        interval = setInterval(poll, 1000);
+    }
+    function stop() {
+        if (interval) {
+            clearInterval(interval);
+            interval = null;
+        }
+    }
+    return { start, stop };
+}
+//# sourceMappingURL=stream-poller.js.map

package/dist/stream-poller.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export type { ProcessMetadataFilter } from 'optio-contracts';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types.js

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

package/dist/types.js.map

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

package/dist/widget-proxy-core.d.ts

@@ -0,0 +1,7 @@
+import { type Db } from 'mongodb';
+import type { InnerAuthDoc, WidgetUpstreamRegistry, WidgetUpstreamValue } from './widget-upstream-registry.js';
+export declare function resolveWidgetUpstream(db: Db, prefix: string, registry: WidgetUpstreamRegistry, processId: string): Promise<WidgetUpstreamValue | null>;
+export declare function applyInnerAuthHeaders(innerAuth: InnerAuthDoc | null, headers: Record<string, string | string[] | undefined>): Record<string, string | string[] | undefined>;
+export declare function applyInnerAuthQuery(innerAuth: InnerAuthDoc | null, url: string): string;
+export declare function isWriteMethod(method: string): boolean;
+//# sourceMappingURL=widget-proxy-core.d.ts.map

package/dist/widget-proxy-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-proxy-core.d.ts","sourceRoot":"","sources":["../src/widget-proxy-core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,EAAE,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAE/G,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAkCrC;AAED,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,YAAY,GAAG,IAAI,EAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GACrD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAc/C;AAED,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,YAAY,GAAG,IAAI,EAC9B,GAAG,EAAE,MAAM,GACV,MAAM,CAKR;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGrD"}

package/dist/widget-proxy-core.js

@@ -0,0 +1,56 @@
+import { ObjectId } from 'mongodb';
+export async function resolveWidgetUpstream(db, prefix, registry, processId) {
+    // Scope the cache by (database, prefix, processId) so the same ObjectId
+    // used in two different databases does not collide.
+    const cacheKey = `${db.databaseName}/${prefix}/${processId}`;
+    if (registry.has(cacheKey)) {
+        return registry.get(cacheKey) ?? null;
+    }
+    let oid;
+    try {
+        oid = new ObjectId(processId);
+    }
+    catch {
+        // Don't cache: a malformed processId is a one-off URL and caching
+        // the negative would waste an entry; the 404 is cheap to re-derive.
+        return null;
+    }
+    const doc = await db.collection(`${prefix}_processes`).findOne({ _id: oid }, { projection: { widgetUpstream: 1 } });
+    const upstream = (doc?.widgetUpstream ?? null);
+    // Only cache positive lookups.  A null (no widgetUpstream registered yet
+    // or just cleared at teardown) must NOT stick in the cache: when the
+    // worker subsequently calls set_widget_upstream, the dashboard's first
+    // iframe load would otherwise see a stale negative entry and 404 until
+    // the TTL expired.  The design spec calls for tree-poller-based
+    // invalidation to handle this; until that's wired, skipping the negative
+    // cache is the minimal correct behavior.
+    if (upstream !== null) {
+        registry.set(cacheKey, upstream);
+    }
+    return upstream;
+}
+export function applyInnerAuthHeaders(innerAuth, headers) {
+    if (!innerAuth)
+        return headers;
+    if (innerAuth.kind === 'basic') {
+        const encoded = Buffer.from(`${innerAuth.username}:${innerAuth.password}`).toString('base64');
+        return { ...headers, authorization: `Basic ${encoded}` };
+    }
+    if (innerAuth.kind === 'header') {
+        return { ...headers, [innerAuth.name.toLowerCase()]: innerAuth.value };
+    }
+    // query auth does not touch headers
+    return headers;
+}
+export function applyInnerAuthQuery(innerAuth, url) {
+    if (!innerAuth || innerAuth.kind !== 'query')
+        return url;
+    const separator = url.includes('?') ? '&' : '?';
+    const encodedValue = encodeURIComponent(innerAuth.value);
+    return `${url}${separator}${innerAuth.name}=${encodedValue}`;
+}
+export function isWriteMethod(method) {
+    const m = method.toUpperCase();
+    return m !== 'GET' && m !== 'HEAD' && m !== 'OPTIONS';
+}
+//# sourceMappingURL=widget-proxy-core.js.map

package/dist/widget-proxy-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-proxy-core.js","sourceRoot":"","sources":["../src/widget-proxy-core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAW,MAAM,SAAS,CAAC;AAG5C,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,EAAM,EACN,MAAc,EACd,QAAgC,EAChC,SAAiB;IAEjB,wEAAwE;IACxE,oDAAoD;IACpD,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,YAAY,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;IAE7D,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,OAAO,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC;IACxC,CAAC;IAED,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;QAClE,oEAAoE;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,GAAG,MAAM,YAAY,CAAC,CAAC,OAAO,CAC5D,EAAE,GAAG,EAAE,GAAG,EAAE,EACZ,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,CACtC,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,cAAc,IAAI,IAAI,CAA+B,CAAC;IAC7E,yEAAyE;IACzE,qEAAqE;IACrE,uEAAuE;IACvE,uEAAuE;IACvE,gEAAgE;IAChE,yEAAyE;IACzE,yCAAyC;IACzC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,SAA8B,EAC9B,OAAsD;IAEtD,IAAI,CAAC,SAAS;QAAE,OAAO,OAAO,CAAC;IAE/B,IAAI,SAAS,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,QAAQ,IAAI,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC9F,OAAO,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,SAAS,OAAO,EAAE,EAAE,CAAC;IAC3D,CAAC;IAED,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;IACzE,CAAC;IAED,oCAAoC;IACpC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,SAA8B,EAC9B,GAAW;IAEX,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,GAAG,CAAC;IACzD,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,MAAM,YAAY,GAAG,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACzD,OAAO,GAAG,GAAG,GAAG,SAAS,GAAG,SAAS,CAAC,IAAI,IAAI,YAAY,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAC/B,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,SAAS,CAAC;AACxD,CAAC"}

package/dist/widget-upstream-registry.d.ts

@@ -0,0 +1,27 @@
+export interface WidgetUpstreamValue {
+    url: string;
+    innerAuth: InnerAuthDoc | null;
+}
+export type InnerAuthDoc = {
+    kind: 'basic';
+    username: string;
+    password: string;
+} | {
+    kind: 'query';
+    name: string;
+    value: string;
+} | {
+    kind: 'header';
+    name: string;
+    value: string;
+};
+export interface WidgetUpstreamRegistry {
+    get(processId: string): WidgetUpstreamValue | null | undefined;
+    has(processId: string): boolean;
+    set(processId: string, value: WidgetUpstreamValue | null): void;
+    invalidate(processId: string): void;
+}
+export declare function createWidgetUpstreamRegistry(opts: {
+    ttlMs: number;
+}): WidgetUpstreamRegistry;
+//# sourceMappingURL=widget-upstream-registry.d.ts.map

package/dist/widget-upstream-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-upstream-registry.d.ts","sourceRoot":"","sources":["../src/widget-upstream-registry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/D,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI,GAAG,IAAI,CAAC;IAChE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAOD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,sBAAsB,CA2B5F"}

package/dist/widget-upstream-registry.js

@@ -0,0 +1,28 @@
+export function createWidgetUpstreamRegistry(opts) {
+    const cache = new Map();
+    function getEntry(processId) {
+        const entry = cache.get(processId);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            cache.delete(processId);
+            return undefined;
+        }
+        return entry;
+    }
+    return {
+        get(processId) {
+            return getEntry(processId)?.value;
+        },
+        has(processId) {
+            return getEntry(processId) !== undefined;
+        },
+        set(processId, value) {
+            cache.set(processId, { value, expiresAt: Date.now() + opts.ttlMs });
+        },
+        invalidate(processId) {
+            cache.delete(processId);
+        },
+    };
+}
+//# sourceMappingURL=widget-upstream-registry.js.map

package/dist/widget-upstream-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-upstream-registry.js","sourceRoot":"","sources":["../src/widget-upstream-registry.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,4BAA4B,CAAC,IAAuB;IAClE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE7C,SAAS,QAAQ,CAAC,SAAiB;QACjC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO;QACL,GAAG,CAAC,SAAS;YACX,OAAO,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;QACpC,CAAC;QACD,GAAG,CAAC,SAAS;YACX,OAAO,QAAQ,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC;QAC3C,CAAC;QACD,GAAG,CAAC,SAAS,EAAE,KAAK;YAClB,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,UAAU,CAAC,SAAS;YAClB,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "optio-api",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Server-side optio API with Fastify, Express, and Next.js adapters.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deai-network/optio.git",
+    "directory": "packages/optio-api"
+  },
+  "homepage": "https://github.com/deai-network/optio/tree/main/packages/optio-api#readme",
+  "bugs": {
+    "url": "https://github.com/deai-network/optio/issues"
+  },
+  "author": "Kristof Csillag <kristof.csillag@deai-labs.com>",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./fastify": {
+      "import": "./dist/adapters/fastify.js",
+      "types": "./dist/adapters/fastify.d.ts"
+    },
+    "./express": {
+      "import": "./dist/adapters/express.js",
+      "types": "./dist/adapters/express.d.ts"
+    },
+    "./nextjs/pages": {
+      "import": "./dist/adapters/nextjs-pages.js",
+      "types": "./dist/adapters/nextjs-pages.d.ts"
+    },
+    "./nextjs/app": {
+      "import": "./dist/adapters/nextjs-app.js",
+      "types": "./dist/adapters/nextjs-app.d.ts"
+    }
+  },
+  "dependencies": {
+    "@clamator/over-redis": "^0.1.9",
+    "@clamator/protocol": "^0.1.9",
+    "@fastify/http-proxy": "^11.0.0",
+    "@ts-rest/core": "^3.51.0",
+    "ioredis": "^5.4.0",
+    "mongodb": "^6.12.0",
+    "zod": "^3",
+    "optio-contracts": "0.1.0"
+  },
+  "optionalDependencies": {
+    "@ts-rest/fastify": "^3.51.0"
+  },
+  "peerDependencies": {
+    "express": "^4.21.0 || ^5.0.0",
+    "fastify": "^5.2.0",
+    "next": "^13.0.0 || ^14.0.0 || ^15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "fastify": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ts-rest/express": "^3.52.1",
+    "@ts-rest/next": "^3.52.1",
+    "@ts-rest/serverless": "^3.52.1",
+    "@types/express": "^5.0.6",
+    "@types/ioredis-mock": "^8.2.7",
+    "@types/supertest": "^7.2.0",
+    "@types/ws": "^8.5.0",
+    "eslint": "^10.3.0",
+    "express": "^5.2.1",
+    "ioredis-mock": "^8.13.1",
+    "mongodb-memory-server": "^11.0.1",
+    "next": "^16.2.1",
+    "node-mocks-http": "^1.17.2",
+    "supertest": "^7.2.2",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.59.3",
+    "vitest": "^3.0.0",
+    "ws": "^8.18.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --max-warnings=0"
+  }
+}