@abloatai/ablo 0.3.0

package/dist/client/ApiClient.js

@@ -0,0 +1,659 @@
+/**
+ * Stateless API client for `Ablo({ apiKey })`.
+ *
+ * This is the hosted-API product surface: no schema, no object pool, no
+ * IndexedDB, no WebSocket. It maps the public Resource / Intent / Commit
+ * nouns directly to HTTP routes on sync-server.
+ */
+import { AbloBusyError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, } from '../errors.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, } from './auth.js';
+import { toSeconds } from '../utils/duration.js';
+const DEFAULT_AGENT_LEASE = '10m';
+const DEFAULT_INTENT_LEASE = '2m';
+export function createProtocolClient(options) {
+    const env = readProcessEnv();
+    const authInput = { options, env };
+    const configuredApiKey = resolveApiKey(authInput);
+    const configuredAuthToken = resolveAuthToken(authInput);
+    assertBrowserSafety({
+        apiKey: configuredApiKey,
+        dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
+    });
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new AbloConnectionError('Ablo API client requires a fetch implementation. Pass `fetch` in Ablo({ ... }) for this runtime.', { code: 'fetch_unavailable' });
+    }
+    const url = resolveBaseURL(authInput);
+    const apiBaseUrl = resolveBootstrapBaseUrl({
+        url,
+        bootstrapBaseUrl: options.bootstrapBaseUrl,
+    }).replace(/\/+$/, '');
+    async function authHeaders() {
+        const apiKey = await resolveApiKeyValue(configuredApiKey);
+        const token = apiKey ?? configuredAuthToken;
+        if (!token) {
+            throw new AbloAuthenticationError('Ablo({ apiKey }) requires an API key. Pass `apiKey` or set ABLO_API_KEY.', { code: 'api_key_required' });
+        }
+        const headers = {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        };
+        for (const [key, value] of Object.entries(options.defaultHeaders ?? {})) {
+            if (value == null) {
+                delete headers[key];
+            }
+            else {
+                headers[key] = value;
+            }
+        }
+        return headers;
+    }
+    function endpoint(path) {
+        const target = new URL(`${apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`);
+        for (const [key, value] of Object.entries(options.defaultQuery ?? {})) {
+            if (value !== undefined)
+                target.searchParams.set(key, value);
+        }
+        return target.toString();
+    }
+    async function requestJson(path, init) {
+        const { idempotencyKey, ...requestInit } = init;
+        const headers = await authHeaders();
+        if (idempotencyKey)
+            headers['Idempotency-Key'] = idempotencyKey;
+        const res = await fetchImpl(endpoint(path), {
+            ...requestInit,
+            headers: {
+                ...headers,
+                ...requestInit.headers,
+            },
+        });
+        const bodyText = await res.text();
+        const body = parseBody(bodyText);
+        if (!res.ok) {
+            throw translateHttpError(res.status, body ?? `Ablo API request failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+        }
+        return body;
+    }
+    function createClientTxId(idempotencyKey) {
+        if (idempotencyKey && idempotencyKey.length > 0)
+            return idempotencyKey;
+        return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+            ? crypto.randomUUID()
+            : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    }
+    function createIntentId() {
+        return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+            ? `int_${crypto.randomUUID()}`
+            : `int_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    }
+    function createResourceId() {
+        return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+            ? crypto.randomUUID()
+            : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    }
+    function childClient(authToken) {
+        return createProtocolClient({
+            ...options,
+            apiKey: null,
+            authToken,
+            schema: null,
+        });
+    }
+    function createAgent(id, agentOptions) {
+        return {
+            id,
+            async run(runOptions, handler) {
+                if (runOptions.signal?.aborted) {
+                    return { status: 'cancelled' };
+                }
+                let capability = null;
+                let task = null;
+                try {
+                    const leaseOptions = agentOptions.leaseSeconds !== undefined
+                        ? { leaseSeconds: agentOptions.leaseSeconds }
+                        : { lease: agentOptions.lease ?? DEFAULT_AGENT_LEASE };
+                    capability = await capabilities.create({
+                        participantKind: 'agent',
+                        participantId: id,
+                        syncGroups: agentOptions.syncGroups ?? ['default'],
+                        operations: agentOptions.can,
+                        label: agentOptions.label ?? id,
+                        userMeta: agentOptions.userMeta,
+                        ...leaseOptions,
+                    });
+                    const agentClient = capability.client();
+                    task = await agentClient.tasks.create({
+                        prompt: runOptions.prompt,
+                        parentTaskId: runOptions.parentTaskId,
+                        surface: runOptions.surface ?? 'agent',
+                        metadata: runOptions.metadata,
+                    });
+                    const context = createAgentRunContext(agentClient, task);
+                    const value = await handler(context);
+                    await task.close({
+                        costInputTokens: runOptions.costInputTokens,
+                        costOutputTokens: runOptions.costOutputTokens,
+                        costComputeMs: runOptions.costComputeMs,
+                    });
+                    return { status: 'done', task, value };
+                }
+                catch (error) {
+                    if (task) {
+                        await task.close({
+                            costInputTokens: runOptions.costInputTokens,
+                            costOutputTokens: runOptions.costOutputTokens,
+                            costComputeMs: runOptions.costComputeMs,
+                        }).catch(() => { });
+                    }
+                    if (isAbortError(error) || runOptions.signal?.aborted) {
+                        return { status: 'cancelled', task: task ?? undefined, error };
+                    }
+                    return { status: 'failed', task: task ?? undefined, error };
+                }
+                finally {
+                    if (capability) {
+                        await capabilities.revoke(capability.id).catch(() => { });
+                    }
+                }
+            },
+        };
+    }
+    function createAgentRunContext(agentClient, task) {
+        return {
+            task,
+            ablo: agentClient,
+            resource(name) {
+                return createAgentResourceClient(agentClient, name);
+            },
+        };
+    }
+    function createAgentResourceClient(agentClient, name) {
+        const base = agentClient.resource(name);
+        return {
+            retrieve(id, options) {
+                return base.retrieve(id, withAgentBusyDefault(options));
+            },
+            create(data, mutationOptions) {
+                const id = mutationOptions?.id ?? createResourceId();
+                return withAgentIntent(agentClient, name, id, mutationOptions, (commitIntent) => base.create(data, {
+                    ...stripAgentRuntimeOptions(mutationOptions),
+                    id,
+                    intent: commitIntent,
+                }));
+            },
+            update(id, data, mutationOptions) {
+                return withAgentIntent(agentClient, name, id, mutationOptions, (commitIntent) => base.update(id, data, {
+                    ...stripAgentRuntimeOptions(mutationOptions),
+                    intent: commitIntent,
+                }));
+            },
+            delete(id, mutationOptions) {
+                return withAgentIntent(agentClient, name, id, mutationOptions, (commitIntent) => base.delete(id, {
+                    ...stripAgentRuntimeOptions(mutationOptions),
+                    intent: commitIntent,
+                }));
+            },
+        };
+    }
+    async function withAgentIntent(agentClient, resourceName, id, mutationOptions, commit) {
+        const intentInput = mutationOptions?.intent;
+        const targetOverride = intentInput != null && typeof intentInput === 'object' && !isIntentHandleRef(intentInput)
+            ? intentInput.target ?? {}
+            : {};
+        const target = {
+            ...targetOverride,
+            resource: targetOverride.resource ?? resourceName,
+            id: targetOverride.id ?? id,
+            ...(intentInput != null && typeof intentInput === 'object' && !isIntentHandleRef(intentInput) && intentInput.field
+                ? { field: intentInput.field }
+                : {}),
+        };
+        await applyBusyPolicy(target, withAgentBusyDefault(mutationOptions), 'wait');
+        if (intentInput == null || isIntentHandleRef(intentInput)) {
+            return commit(intentInput);
+        }
+        const action = typeof intentInput === 'string' ? intentInput : intentInput.action;
+        const intent = await agentClient.intents.create({
+            target,
+            action,
+            ttl: typeof intentInput === 'object'
+                ? intentInput.ttl ?? DEFAULT_INTENT_LEASE
+                : DEFAULT_INTENT_LEASE,
+        });
+        try {
+            return await commit(intent);
+        }
+        finally {
+            await intent.release().catch(() => { });
+        }
+    }
+    function normalizeCommitOperation(op, defaults) {
+        const resource = op.resource ?? op.target?.resource;
+        if (!resource) {
+            throw new AbloValidationError('Commit operation requires `resource` or `target.resource`.', { code: 'commit_operation_resource_required' });
+        }
+        const id = op.id ?? op.target?.id ?? null;
+        return {
+            action: op.action,
+            resource,
+            id,
+            data: op.data ?? null,
+            transactionId: op.transactionId ?? null,
+            readAt: op.readAt ?? defaults.readAt ?? null,
+            onStale: op.onStale ?? defaults.onStale ?? null,
+        };
+    }
+    function normalizeCommitOperations(commitOptions) {
+        if (commitOptions.operation && commitOptions.operations) {
+            throw new AbloValidationError('Pass either `operation` or `operations`, not both.', { code: 'commit_operations_ambiguous' });
+        }
+        const inputOperations = commitOptions.operation
+            ? [commitOptions.operation]
+            : commitOptions.operations ?? [];
+        if (inputOperations.length === 0) {
+            throw new AbloValidationError('Commit requires at least one operation.', { code: 'commit_operation_required' });
+        }
+        return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
+    }
+    async function listIntents(target) {
+        const params = new URLSearchParams();
+        if (target?.resource)
+            params.set('resource', target.resource);
+        if (target?.id)
+            params.set('id', target.id);
+        if (target?.field)
+            params.set('field', target.field);
+        const suffix = params.toString();
+        const body = await requestJson(`/v1/intents${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
+        return body.intents ?? [];
+    }
+    function busyError(target, intents, code) {
+        const label = [target.resource, target.id, target.field].filter(Boolean).join('/');
+        const holder = intents[0];
+        const suffix = holder
+            ? ` held by ${holder.actor} (${holder.action})`
+            : ' held by another participant';
+        return new AbloBusyError(`Resource is busy: ${label || 'target'}${suffix}.`, { code, intents });
+    }
+    function delay(ms, signal) {
+        if (signal?.aborted) {
+            return Promise.reject(new AbloConnectionError('Intent wait aborted.', {
+                code: 'intent_wait_aborted',
+                cause: signal.reason,
+            }));
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(done, ms);
+            function cleanup() {
+                clearTimeout(timeout);
+                signal?.removeEventListener('abort', onAbort);
+            }
+            function done() {
+                cleanup();
+                resolve();
+            }
+            function onAbort() {
+                cleanup();
+                reject(new AbloConnectionError('Intent wait aborted.', {
+                    code: 'intent_wait_aborted',
+                    cause: signal?.reason,
+                }));
+            }
+            signal?.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    async function waitForNoIntents(target, options) {
+        const startedAt = Date.now();
+        const pollInterval = options?.pollInterval;
+        for (;;) {
+            const intents = await listIntents(target);
+            if (intents.length === 0)
+                return;
+            if (pollInterval == null) {
+                throw new AbloValidationError('Cannot wait for intents over the schema-less HTTP client without `pollInterval`. ' +
+                    'Use the schema client for event-driven intent waits, pass `ifBusy: "return"`, ' +
+                    'or provide an explicit poll interval for this runtime.', { code: 'intent_wait_poll_interval_required' });
+            }
+            if (options?.timeout != null && Date.now() - startedAt >= options.timeout) {
+                throw busyError(target, intents, 'resource_busy_timeout');
+            }
+            const remaining = options?.timeout == null
+                ? pollInterval
+                : Math.max(0, Math.min(pollInterval, options.timeout - (Date.now() - startedAt)));
+            await delay(remaining, options?.signal);
+        }
+    }
+    async function applyBusyPolicy(target, options, defaultPolicy = 'return') {
+        const policy = options?.ifBusy ?? defaultPolicy;
+        if (policy === 'return')
+            return;
+        const intents = await listIntents(target);
+        if (intents.length === 0)
+            return;
+        if (policy === 'fail')
+            throw busyError(target, intents, 'resource_busy');
+        await waitForNoIntents(target, {
+            timeout: options?.busyTimeout,
+            pollInterval: options?.busyPollInterval,
+        });
+    }
+    const commits = {
+        async create(commitOptions) {
+            const clientTxId = createClientTxId(commitOptions.idempotencyKey);
+            const operations = normalizeCommitOperations(commitOptions);
+            const body = await requestJson('/v1/commits', {
+                method: 'POST',
+                idempotencyKey: clientTxId,
+                body: JSON.stringify({
+                    clientTxId,
+                    idempotencyKey: clientTxId,
+                    intent: normalizeIntentId(commitOptions.intent),
+                    operations,
+                }),
+            });
+            // `requestJson` throws via `translateHttpError` on any non-2xx,
+            // so reaching here implies success. Narrow `status` to the
+            // `CommitWait`-compatible subset; `'rejected'` only appears on
+            // the rejection body (already thrown).
+            const status = body.status === 'queued' ? 'queued' : 'confirmed';
+            return {
+                id: body.id ?? body.clientTxId ?? clientTxId,
+                status,
+                lastSyncId: body.lastSyncId,
+            };
+        },
+    };
+    const capabilities = {
+        async create(capabilityOptions) {
+            const ttlSeconds = capabilityOptions.ttlSeconds ??
+                capabilityOptions.leaseSeconds ??
+                toSeconds(capabilityOptions.ttl ?? capabilityOptions.lease ?? DEFAULT_AGENT_LEASE);
+            const body = await requestJson('/v1/capabilities', {
+                method: 'POST',
+                body: JSON.stringify({
+                    participantKind: capabilityOptions.participantKind ?? 'agent',
+                    participantId: capabilityOptions.participantId,
+                    syncGroups: capabilityOptions.syncGroups,
+                    operations: capabilityOptions.operations,
+                    ttlSeconds,
+                    label: capabilityOptions.label,
+                    wideScope: capabilityOptions.wideScope,
+                    userMeta: capabilityOptions.userMeta,
+                }),
+            });
+            const id = body.capabilityId ?? body.id;
+            if (!id) {
+                throw new AbloValidationError('Capability create response did not include an id.', { code: 'capability_id_missing' });
+            }
+            return {
+                id,
+                token: body.token,
+                expiresAt: body.expiresAt,
+                organizationId: body.organizationId,
+                scope: body.scope,
+                userMeta: body.userMeta,
+                client: () => childClient(body.token),
+            };
+        },
+        async retrieve(id) {
+            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}`, { method: 'GET' });
+            return {
+                id: body.capabilityId ?? body.id ?? id,
+                organizationId: body.organizationId,
+                participantKind: body.participantKind,
+                participantId: body.participantId,
+                label: body.label,
+                status: body.status,
+                issuedAt: body.issuedAt,
+                expiresAt: body.expiresAt,
+                revokedAt: body.revokedAt,
+                lastUsedAt: body.lastUsedAt,
+                operations: body.operations ?? [],
+                syncGroups: body.syncGroups ?? [],
+            };
+        },
+        async revoke(id) {
+            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}`, { method: 'DELETE' });
+            return {
+                id: body.capabilityId ?? body.id ?? id,
+                deleted: body.deleted ?? true,
+                activeSessionsClosed: body.activeSessionsClosed,
+            };
+        },
+        mint(options) {
+            return capabilities.create(options);
+        },
+    };
+    const tasks = {
+        async create(taskOptions) {
+            const body = await requestJson('/v1/tasks', {
+                method: 'POST',
+                body: JSON.stringify({
+                    prompt: taskOptions.prompt,
+                    parentTaskId: taskOptions.parentTaskId,
+                    surface: taskOptions.surface,
+                    metadata: taskOptions.metadata,
+                }),
+            });
+            const id = body.id ?? body.taskId ?? body.turnId;
+            if (!id) {
+                throw new AbloValidationError('Task create response did not include an id.', { code: 'task_id_missing' });
+            }
+            return {
+                id,
+                turnId: id,
+                promptHash: body.promptHash,
+                openedAt: body.openedAt,
+                close: (stats) => tasks.close(id, stats),
+            };
+        },
+        async close(id, stats) {
+            const body = await requestJson(`/v1/tasks/${encodeURIComponent(id)}/close`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    costInputTokens: stats?.costInputTokens ?? 0,
+                    costOutputTokens: stats?.costOutputTokens ?? 0,
+                    costComputeMs: stats?.costComputeMs ?? 0,
+                }),
+            });
+            const closedId = body.id ?? body.taskId ?? body.turnId ?? id;
+            return {
+                id: closedId,
+                turnId: closedId,
+                closed: body.closed ?? body.alreadyClosed ?? true,
+                alreadyClosed: body.alreadyClosed,
+                endedAt: body.endedAt,
+            };
+        },
+        open(options) {
+            return tasks.create(options);
+        },
+    };
+    const intents = {
+        async create(intentOptions) {
+            const intentId = createIntentId();
+            const body = await requestJson('/v1/intents', {
+                method: 'POST',
+                body: JSON.stringify({
+                    intentId,
+                    target: intentOptions.target,
+                    action: intentOptions.action,
+                    ttl: intentOptions.ttl,
+                }),
+            });
+            const id = body.intent?.id ?? intentId;
+            let released = false;
+            const release = async () => {
+                if (released)
+                    return;
+                released = true;
+                await requestJson(`/v1/intents/${encodeURIComponent(id)}`, { method: 'DELETE' });
+            };
+            return {
+                id,
+                release,
+                revoke: () => {
+                    void release().catch(() => { });
+                },
+                [Symbol.asyncDispose]: release,
+            };
+        },
+        list: listIntents,
+        waitFor(target, options) {
+            return waitForNoIntents(target, options);
+        },
+    };
+    async function retrieveResource(resourceName, id, options) {
+        await applyBusyPolicy({ resource: resourceName, id }, options);
+        const query = await requestJson(`/v1/resources/${encodeURIComponent(resourceName)}/${encodeURIComponent(id)}`, {
+            method: 'GET',
+        });
+        const data = query.data;
+        if (!data) {
+            throw new AbloValidationError(`Resource not found: ${resourceName}/${id}`, { code: 'resource_not_found' });
+        }
+        return {
+            data,
+            stamp: query.stamp ?? 0,
+            intents: query.intents ?? [],
+        };
+    }
+    function resource(name) {
+        return {
+            retrieve(id, options) {
+                return retrieveResource(name, id, options);
+            },
+            async create(data, mutationOptions) {
+                const id = mutationOptions?.id ?? createResourceId();
+                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                return commits.create({
+                    intent: mutationOptions?.intent,
+                    idempotencyKey: mutationOptions?.idempotencyKey,
+                    readAt: mutationOptions?.readAt,
+                    onStale: mutationOptions?.onStale,
+                    wait: mutationOptions?.wait,
+                    timeout: mutationOptions?.timeout,
+                    operations: [
+                        {
+                            action: 'create',
+                            resource: name,
+                            id,
+                            data,
+                        },
+                    ],
+                });
+            },
+            async update(id, data, mutationOptions) {
+                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                return commits.create({
+                    intent: mutationOptions?.intent,
+                    idempotencyKey: mutationOptions?.idempotencyKey,
+                    readAt: mutationOptions?.readAt,
+                    onStale: mutationOptions?.onStale,
+                    wait: mutationOptions?.wait,
+                    timeout: mutationOptions?.timeout,
+                    operations: [
+                        {
+                            action: 'update',
+                            resource: name,
+                            id,
+                            data,
+                        },
+                    ],
+                });
+            },
+            async delete(id, mutationOptions) {
+                await applyBusyPolicy({ resource: name, id }, mutationOptions);
+                return commits.create({
+                    intent: mutationOptions?.intent,
+                    idempotencyKey: mutationOptions?.idempotencyKey,
+                    readAt: mutationOptions?.readAt,
+                    onStale: mutationOptions?.onStale,
+                    wait: mutationOptions?.wait,
+                    timeout: mutationOptions?.timeout,
+                    operations: [
+                        {
+                            action: 'delete',
+                            resource: name,
+                            id,
+                        },
+                    ],
+                });
+            },
+        };
+    }
+    return {
+        async ready() { },
+        async waitForFlush() { },
+        async dispose() { },
+        async purge() { },
+        capabilities,
+        tasks,
+        intents,
+        commits,
+        resource,
+        agent: createAgent,
+        async beginTurn(turnOptions) {
+            const task = await tasks.create(turnOptions);
+            let closed = false;
+            const close = async (stats) => {
+                if (closed)
+                    return;
+                closed = true;
+                await task.close(stats);
+            };
+            const dispose = () => {
+                closed = true;
+            };
+            return {
+                turnId: task.id,
+                close,
+                dispose,
+                [Symbol.asyncDispose]: close,
+            };
+        },
+    };
+}
+function normalizeIntentId(intent) {
+    if (typeof intent === 'string')
+        return intent;
+    return intent?.id;
+}
+function withAgentBusyDefault(options) {
+    return {
+        ifBusy: 'fail',
+        ...(options ?? {}),
+    };
+}
+function stripAgentRuntimeOptions(options) {
+    if (!options)
+        return undefined;
+    const { intent: _intent, ifBusy: _ifBusy, busyTimeout: _busyTimeout, busyPollInterval: _busyPollInterval, ...rest } = options;
+    return rest;
+}
+function isIntentHandleRef(input) {
+    return (typeof input === 'object' &&
+        input !== null &&
+        'id' in input &&
+        typeof input.id === 'string' &&
+        !('action' in input));
+}
+function isAbortError(error) {
+    return (typeof DOMException !== 'undefined' &&
+        error instanceof DOMException &&
+        error.name === 'AbortError') || (typeof error === 'object' &&
+        error !== null &&
+        'name' in error &&
+        error.name === 'AbortError');
+}
+function parseBody(bodyText) {
+    if (bodyText.length === 0)
+        return null;
+    try {
+        return JSON.parse(bodyText);
+    }
+    catch {
+        return bodyText;
+    }
+}