@abloatai/ablo 0.25.0 → 0.26.0

package/dist/source/factory.js

@@ -0,0 +1,273 @@
+/**
+ * The `abloSource()` / `dataSource()` endpoint factory — the customer-owned
+ * Data Source handler. Takes the options (schema, apiKey, handlers or ORM
+ * adapter), verifies the signed request, enforces per-key scopes, and
+ * dispatches the four wire operations (`load`/`list`/`commit`/`events`) to
+ * the configured handlers.
+ *
+ * `AbloSourceOptions` lives here (not `types.ts`) because it references the
+ * ORM `DataSourceAdapter` — keeping it with the factory keeps `types.ts` a
+ * dependency-free leaf for `adapter.ts`/`contract.ts` to import from.
+ */
+import { changeSetSchema } from './contract.js';
+import { SourceSignatureError, verifyAbloSourceRequest, } from './signing.js';
+function json(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+/**
+ * Serve a request from an ORM `adapter`. Routes the four operations to the adapter
+ * interface (`read`/`commit`/`events`) and shapes the wire response. The adapter is the
+ * single point of dispatch — no per-model branching here.
+ */
+async function handleViaAdapter(adapter, body, scope) {
+    if (body.type === 'load') {
+        const rows = await adapter.read({
+            kind: 'load',
+            model: body.model,
+            id: body.id,
+            ...(scope ? { scope } : {}),
+        });
+        return json({ row: rows[0] ?? null });
+    }
+    if (body.type === 'list') {
+        const rows = await adapter.read({
+            kind: 'list',
+            model: body.model,
+            ...(body.query ? { query: body.query } : {}),
+            ...(scope ? { scope } : {}),
+        });
+        return json({ rows });
+    }
+    if (body.type === 'commit') {
+        if (!body.clientTxId) {
+            return json({ error: 'source_commit_requires_client_tx_id', message: 'commit requires a clientTxId for idempotency' }, 400);
+        }
+        const parsed = changeSetSchema.safeParse({
+            operations: body.operations,
+            clientTxId: body.clientTxId,
+        });
+        if (!parsed.success) {
+            return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
+        }
+        const result = await adapter.commit(parsed.data);
+        return json({ rows: result.rows });
+    }
+    if (body.type === 'events') {
+        const page = await adapter.events(body.cursor ?? null, body.limit ?? 100);
+        return json({
+            events: page.events.map((event) => ({
+                id: event.id,
+                model: event.model,
+                entityId: event.entityId,
+                type: event.type,
+                ...(event.data !== undefined && event.data !== null ? { data: event.data } : {}),
+                ...(event.organizationId ? { organizationId: event.organizationId } : {}),
+                ...(event.clientTxId ? { clientTxId: event.clientTxId } : {}),
+                ...(event.occurredAt !== undefined && event.occurredAt !== null
+                    ? { occurredAt: event.occurredAt }
+                    : {}),
+            })),
+            ...(page.nextCursor !== null ? { nextCursor: page.nextCursor } : {}),
+        });
+    }
+    return json({ error: 'unknown_source_request' }, 400);
+}
+async function readBody(request) {
+    if (typeof request.text === 'function') {
+        const rawBody = await request.text();
+        return { rawBody, body: JSON.parse(rawBody) };
+    }
+    const body = (await request.json());
+    return { rawBody: JSON.stringify(body), body };
+}
+async function resolveApiKey(apiKey, context) {
+    if (!apiKey)
+        return null;
+    return typeof apiKey === 'function' ? apiKey(context) : apiKey;
+}
+/**
+ * Map a wire request to its scope tag. Each request type corresponds
+ * to one scope, so the function is total and exhaustive — adding a
+ * new request type forces a new scope tag, which is the right design
+ * pressure for keeping the scope vocabulary in sync with the wire.
+ */
+function scopeFor(body) {
+    switch (body.type) {
+        case 'load':
+            return 'load';
+        case 'list':
+            return 'list';
+        case 'commit':
+            return 'commit';
+        case 'events':
+            return 'events';
+    }
+}
+function normalizeListResult(result) {
+    if (Array.isArray(result)) {
+        return { rows: result };
+    }
+    const page = result;
+    return page.nextCursor !== undefined
+        ? { rows: page.rows, nextCursor: page.nextCursor }
+        : { rows: page.rows };
+}
+function getModelHandlers(options, model) {
+    const grouped = options.models?.[model];
+    if (grouped)
+        return grouped;
+    const direct = options[model];
+    return direct;
+}
+function sameModel(operations) {
+    const first = operations[0]?.model;
+    if (!first)
+        return null;
+    return operations.every((op) => op.model === first) ? first : null;
+}
+/**
+ * Create a customer-owned data source endpoint.
+ *
+ * App code still talks to Ablo with `ablo.files.load/list/update`.
+ * This helper is only for customers who keep canonical rows in their own
+ * database and want Ablo Cloud to call a narrow, signed endpoint instead
+ * of receiving database credentials.
+ */
+export function abloSource(options) {
+    return async function handleAbloSource(request) {
+        if (request.method !== 'POST') {
+            return json({ error: 'method_not_allowed' }, 405);
+        }
+        let body;
+        let rawBody;
+        try {
+            const parsed = await readBody(request);
+            body = parsed.body;
+            rawBody = parsed.rawBody;
+        }
+        catch {
+            return json({ error: 'invalid_json' }, 400);
+        }
+        let signature = null;
+        try {
+            const apiKey = await resolveApiKey(options.apiKey, {
+                request,
+                body,
+                rawBody,
+            });
+            if (!apiKey) {
+                return json({
+                    error: 'source_api_key_missing',
+                    message: 'Data Source apiKey is required',
+                }, 401);
+            }
+            signature = await verifyAbloSourceRequest({
+                request,
+                body: rawBody,
+                apiKey,
+                toleranceMs: options.signatureToleranceMs,
+            });
+        }
+        catch (err) {
+            if (err instanceof SourceSignatureError) {
+                return json({ error: err.code, message: err.message }, 401);
+            }
+            throw err;
+        }
+        const auth = options.authorize
+            ? await options.authorize({ request, body, rawBody })
+            : undefined;
+        // Per-key permission scope check. When `resolveScopes` is set,
+        // the customer returns the operation set this key is allowed to
+        // invoke; we enforce before any model handler runs.
+        if (options.resolveScopes) {
+            const required = scopeFor(body);
+            const granted = await options.resolveScopes({ auth, request, body });
+            const grantedSet = granted instanceof Set ? granted : new Set(granted);
+            if (!grantedSet.has(required)) {
+                return json({
+                    error: 'source_forbidden',
+                    required,
+                    granted: Array.from(grantedSet),
+                }, 403);
+            }
+        }
+        const context = {
+            auth,
+            request,
+            messageId: signature?.messageId,
+            signedAt: signature?.signedAt,
+            ...(body.scope ? { scope: body.scope } : {}),
+        };
+        // Adapter path: when an ORM adapter is configured it serves every operation,
+        // consumed at this generic layer (rows are JSON on the wire), so no per-model
+        // handler lookup and no typed↔generic boundary.
+        if (options.adapter) {
+            return handleViaAdapter(options.adapter, body, context.scope);
+        }
+        if (body.type === 'load') {
+            const handlers = getModelHandlers(options, body.model);
+            if (!handlers?.load) {
+                return json({ error: 'source_load_not_configured', model: body.model }, 404);
+            }
+            const row = await handlers.load({ id: body.id, context });
+            return json({ row });
+        }
+        if (body.type === 'list') {
+            const handlers = getModelHandlers(options, body.model);
+            if (!handlers?.list) {
+                return json({ error: 'source_list_not_configured', model: body.model }, 404);
+            }
+            const result = await handlers.list({ query: body.query ?? {}, context });
+            const normalized = normalizeListResult(result);
+            return json(normalized);
+        }
+        if (body.type === 'commit') {
+            if (options.commit) {
+                const result = await options.commit({
+                    operations: body.operations,
+                    clientTxId: body.clientTxId,
+                    context,
+                });
+                return json(result);
+            }
+            const model = body.model ?? sameModel(body.operations);
+            if (!model) {
+                return json({ error: 'source_commit_requires_single_model' }, 400);
+            }
+            const handlers = getModelHandlers(options, model);
+            if (!handlers?.commit) {
+                return json({ error: 'source_commit_not_configured', model }, 404);
+            }
+            const result = await handlers.commit({
+                operations: body.operations,
+                clientTxId: body.clientTxId,
+                context,
+            });
+            return json(result);
+        }
+        if (body.type === 'events') {
+            if (!options.events) {
+                return json({ error: 'source_events_not_configured' }, 404);
+            }
+            const result = await options.events({
+                cursor: body.cursor,
+                limit: body.limit,
+                context,
+            });
+            return json({
+                events: result.events,
+                ...(result.nextCursor !== undefined
+                    ? { nextCursor: result.nextCursor }
+                    : {}),
+            });
+        }
+        return json({ error: 'unknown_source_request' }, 400);
+    };
+}
+export function dataSource(options) {
+    return abloSource(options);
+}