@wtfalch/ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @wtfalch/ai
+
+Public client SDK and API types for the AI service. Requires Node 22+ or a
+browser with Fetch and AbortSignal.timeout support. The client has no runtime
+package dependencies. It is an ES module package; use `import` in Node.js.
+The optional `@wtfalch/ai/webhooks` entrypoint requires Node.js.
+
+```sh
+npm install @wtfalch/ai
+```
+
+```ts
+import { createAiClient, ApiError } from '@wtfalch/ai';
+
+const ai = createAiClient({
+  organisationId: 'your-organisation-id',
+  url: serviceOrigin,
+  credential: () => serviceKey,
+});
+
+const run = await ai.submit({
+  source: { mode: 'offering', id: offeringId },
+  input: { prompt: 'Hello', maxOutputTokens: 256 },
+  requestId: crypto.randomUUID(),
+});
+const status = await ai.get(run.id);
+```
+
+Use the deployed service's HTTPS origin and a scoped service credential. The
+credential callback runs for every request, so rotation does not require a new
+client. The client refuses redirects and omits browser cookies. An HTTP origin
+is accepted only for localhost development. Do not embed a privileged service
+credential in public browser code.
+
+Requests require current service permissions and configured budgets. A retry
+of the same operation should retain its request ID. API failures throw
+`ApiError` with `status` and `code`; the SDK does not expose raw upstream error
+bodies. A 202 AI response means queued, not completed.
+
+`submit(input, { wait })` waits up to `wait` seconds (integer, 1-60) for the
+run to finish before responding: HTTP 200 with the finished `RunView` if it
+settles in time, HTTP 202 with the run's current state (usually still
+`queued`) if `wait` elapses first. Either way the SDK returns the same
+`RunView` `get` returns, so check `state` to tell the two apart. Execution
+keeps going after the deadline even if the caller did not wait for it.
+Without `wait`, `submit` returns as soon as the run is queued, as before.
+
+A fal image offering (seedream-v4, seedream-v4-edit, birefnet) settles the same way and
+returns its files in `output.files`:
+
+```ts
+const run = await ai.submit(
+  {
+    source: { mode: 'offering', id: falOfferingId },
+    input: { prompt: 'a red cube' },
+    requestId: crypto.randomUUID(),
+  },
+  { wait: 60 },
+);
+if (run.state === 'succeeded') {
+  for (const file of (run.output as { files: { url: string }[] }).files) console.log(file.url);
+}
+```
+
+Each file's `url` is an https URL fal itself serves; the SDK neither downloads nor re-hosts it.
+
+For a text model that supports streaming, `stream` returns an async iterable:
+
+```ts
+for await (const event of ai.stream({
+  source: { mode: 'offering', id: textOfferingId },
+  input: { prompt: 'Hello', maxOutputTokens: 256 },
+  requestId: crypto.randomUUID(),
+})) {
+  if (event.type === 'delta') console.log(event.text);
+  else console.log(event.run.state);
+}
+```
+
+Pass `{ signal: controller.signal }` as the second argument to abort a stream,
+or break out of the loop to disconnect. A normal stream ends with a `done`
+event carrying the final run. A disconnect may prevent receipt of that event;
+use `get` when the run ID is known to check its state. Disconnecting does not
+guarantee cancellation or prevent charges for work already performed. Use
+`stream` instead of passing `stream: true` to `submit`, which expects JSON.
+
+Webhook receivers can verify the `x-wtfalch-signature` header using the separate
+Node.js entrypoint. Verify the exact raw request body before parsing JSON:
+
+```ts
+import { verifyWebhookSignature } from '@wtfalch/ai/webhooks';
+
+const rawBody = await request.text();
+const valid = verifyWebhookSignature(
+  request.headers.get('x-wtfalch-signature') ?? '',
+  [webhookSecret],
+  rawBody,
+  Math.floor(Date.now() / 1000),
+);
+if (!valid) throw new Error('Invalid webhook signature');
+const event = JSON.parse(rawBody);
+```
+
+Timestamps are Unix seconds, with a default tolerance of 300 seconds. During
+secret rotation, include the previous secret only while its overlap window is
+valid. `signWebhookPayload` and `SIGNATURE_TOLERANCE_SECONDS` are also exported
+from `/webhooks`. Signature verification does not deduplicate deliveries;
+receivers should handle repeated events idempotently.
+
+`listConnections`, `listRuns`, `listOfferings`, `listBudgets` and `listUsage`
+each take an optional `{ after, limit }` page (limit 1–100, default 50) and
+return only the rows the credential's grants allow in the selected
+organisation. Connections and offerings page by id; runs and usage page
+newest first, `after` being the last id seen. Budgets page by key id and
+cover the current period only, with a null key id for the organisation-wide
+row. On `listRuns` and `listUsage`, an `after` id the credential cannot read,
+or one that does not exist, throws `ApiError` with `status: 400`.
+
+`updateBudget({ keyId, limitMicros })` sets the organisation's cap (`keyId: null`) or one
+key's, needing `ai.budgets:update` reaching whichever it targets; zero blocks spending, and
+no caller can remove a cap. `exportUsage({ from, to })` returns usage as CSV text (ISO
+timestamps, at most 92 days), needing an `ai.usage:export` grant that itself reaches the
+organisation — an owner- or key-scoped grant throws `403`; use `listUsage` instead.
+`createOffering`, `updateOffering`, `disableOffering` and `setOfferingAccess` administer
+platform offerings and need `ai.offerings:create`/`:update`/`:disable`, platform-boundary
+permissions no customer organisation's grants can reach. `createOffering` throws
+`ApiError` with `status: 503` while the host has no provider key store configured.
+
+The root export provides the client and public request/response types.
+`@wtfalch/ai/client` is also supported. There are no server, database,
+migration, provider-adapter or authorization-engine exports. The service
+implementation is maintained in a private repository.
+
+The first 0.1.0 SDK targets the new service API. Production migration from Valet
+is a separate rollout; installing the SDK does not migrate accounts or files.

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+import { type ClientOptions } from './transport.js';
+import type { BalanceReadingView, BudgetView, ConnectionView, CreateConnection, CreateOffering, OfferingAccessView, OfferingAdminView, OfferingView, RunRequest, RunStreamEvent, RunView, SetOfferingAccess, SetWebhookAddress, UpdateBudget, UpdateOffering, UsageCostView, UsageView, WebhookDeliveryView, WebhookView } from './types.js';
+export { ApiError, type ClientOptions } from './transport.js';
+export declare function createAiClient(options: ClientOptions): {
+    createConnection: (input: CreateConnection) => Promise<ConnectionView>;
+    getConnection: (id: string) => Promise<ConnectionView>;
+    rotateConnection: (id: string, input: {
+        revision: number;
+        credential: string;
+    }) => Promise<ConnectionView>;
+    disableConnection: (id: string, revision: number) => Promise<ConnectionView>;
+    listConnections: (page?: {
+        after?: string;
+        limit?: number;
+    }) => Promise<ConnectionView[]>;
+    submit: (input: RunRequest, options?: {
+        wait?: number;
+    }) => Promise<RunView>;
+    /** Reads `POST /v1/runs` as server-sent events instead of one JSON body: yields
+     * a `delta` per piece of text the provider streamed, then exactly one `done`
+     * carrying the run's final view, however the stream ended. Stop iterating
+     * (`break`, or abort `options.signal`) to disconnect - the server still settles
+     * whatever was streamed before that. */
+    stream: (input: RunRequest, options?: {
+        signal?: AbortSignal;
+    }) => AsyncGenerator<RunStreamEvent, void, undefined>;
+    get: (id: string) => Promise<RunView>;
+    cancel: (id: string) => Promise<RunView>;
+    listRuns: (page?: {
+        after?: string;
+        limit?: number;
+    }) => Promise<RunView[]>;
+    listOfferings: (page?: {
+        after?: string;
+        limit?: number;
+    }) => Promise<OfferingView[]>;
+    createOffering: (input: CreateOffering) => Promise<OfferingAdminView>;
+    updateOffering: (id: string, input: UpdateOffering) => Promise<OfferingAdminView>;
+    disableOffering: (id: string, revision: number) => Promise<OfferingAdminView>;
+    setOfferingAccess: (id: string, input: SetOfferingAccess) => Promise<OfferingAccessView>;
+    listBudgets: (page?: {
+        after?: string;
+        limit?: number;
+    }) => Promise<BudgetView[]>;
+    updateBudget: (input: UpdateBudget) => Promise<BudgetView>;
+    listUsage: (page?: {
+        after?: string;
+        limit?: number;
+    }) => Promise<UsageView[]>;
+    listCostUsage: (page?: {
+        after?: string;
+        limit?: number;
+    }) => Promise<UsageCostView[]>;
+    exportUsage: (range: {
+        from: string;
+        to: string;
+    }) => Promise<string>;
+    listBalances: (page?: {
+        limit?: number;
+    }) => Promise<BalanceReadingView[]>;
+    getWebhook: () => Promise<WebhookView>;
+    setWebhookAddress: (input: SetWebhookAddress) => Promise<WebhookView>;
+    rotateWebhookSecret: (revision: number) => Promise<WebhookView>;
+    listWebhookDeliveries: (page?: {
+        after?: string;
+        limit?: number;
+    }) => Promise<WebhookDeliveryView[]>;
+};

package/dist/client.js

@@ -0,0 +1,50 @@
+import { clientCall, clientStream } from './transport.js';
+export { ApiError } from './transport.js';
+const pageQuery = (page) => new URLSearchParams({
+    ...(page.after ? { after: page.after } : {}),
+    ...(page.limit !== undefined ? { limit: String(page.limit) } : {}),
+});
+export function createAiClient(options) {
+    const call = clientCall(options);
+    const stream = clientStream(options);
+    return {
+        createConnection: (input) => call('POST', '/v1/connections', input),
+        getConnection: (id) => call('GET', `/v1/connections/${encodeURIComponent(id)}`),
+        rotateConnection: (id, input) => call('POST', `/v1/connections/${encodeURIComponent(id)}/rotate`, input),
+        disableConnection: (id, revision) => call('POST', `/v1/connections/${encodeURIComponent(id)}/disable`, {
+            revision,
+        }),
+        listConnections: (page = {}) => call('GET', `/v1/connections?${pageQuery(page)}`),
+        submit: (input, options = {}) => call('POST', options.wait === undefined
+            ? '/v1/runs'
+            : `/v1/runs?${new URLSearchParams({ wait: String(options.wait) })}`, input, 'json', 
+        // The server may hold the request for the whole wait.
+        30000 + (options.wait ?? 0) * 1000),
+        /** Reads `POST /v1/runs` as server-sent events instead of one JSON body: yields
+         * a `delta` per piece of text the provider streamed, then exactly one `done`
+         * carrying the run's final view, however the stream ended. Stop iterating
+         * (`break`, or abort `options.signal`) to disconnect - the server still settles
+         * whatever was streamed before that. */
+        stream: (input, options = {}) => stream('/v1/runs', { ...input, stream: true }, options.signal),
+        get: (id) => call('GET', `/v1/runs/${encodeURIComponent(id)}`),
+        cancel: (id) => call('POST', `/v1/runs/${encodeURIComponent(id)}/cancel`),
+        listRuns: (page = {}) => call('GET', `/v1/runs?${pageQuery(page)}`),
+        listOfferings: (page = {}) => call('GET', `/v1/offerings?${pageQuery(page)}`),
+        createOffering: (input) => call('POST', '/v1/offerings', input),
+        updateOffering: (id, input) => call('PATCH', `/v1/offerings/${encodeURIComponent(id)}`, input),
+        disableOffering: (id, revision) => call('POST', `/v1/offerings/${encodeURIComponent(id)}/disable`, {
+            revision,
+        }),
+        setOfferingAccess: (id, input) => call('PUT', `/v1/offerings/${encodeURIComponent(id)}/access`, input),
+        listBudgets: (page = {}) => call('GET', `/v1/budgets?${pageQuery(page)}`),
+        updateBudget: (input) => call('PUT', '/v1/budgets', input),
+        listUsage: (page = {}) => call('GET', `/v1/usage?${pageQuery(page)}`),
+        listCostUsage: (page = {}) => call('GET', `/v1/usage/cost?${pageQuery(page)}`),
+        exportUsage: (range) => call('GET', `/v1/usage/export?${new URLSearchParams(range)}`, undefined, 'text'),
+        listBalances: (page = {}) => call('GET', `/v1/balances?${pageQuery(page)}`),
+        getWebhook: () => call('GET', '/v1/webhooks'),
+        setWebhookAddress: (input) => call('PUT', '/v1/webhooks', input),
+        rotateWebhookSecret: (revision) => call('POST', '/v1/webhooks/rotate', { revision }),
+        listWebhookDeliveries: (page = {}) => call('GET', `/v1/webhooks/deliveries?${pageQuery(page)}`),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './client.js';

package/dist/transport.d.ts

@@ -0,0 +1,19 @@
+import type { RunStreamEvent } from './types.js';
+export interface ClientOptions {
+    url: string;
+    organisationId?: string;
+    credential: () => string | Promise<string>;
+    fetch?: typeof fetch;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+export declare function clientCall(options: ClientOptions): <T>(method: string, path: string, input?: unknown, format?: "json" | "text", timeoutMs?: number) => Promise<T>;
+/** Reads one SSE frame stream (`event:`/`data:` lines, blank-line separated) off a
+ * response body and turns it into `RunStreamEvent`s, for `POST /v1/runs` with
+ * `stream: true`. Web-standard APIs only, so this stays reachable from the SDK's
+ * main entry with zero runtime dependencies (`pnpm check:package`).
+ */
+export declare function clientStream(options: ClientOptions): (path: string, input: unknown, signal?: AbortSignal) => AsyncGenerator<RunStreamEvent, void, undefined>;

package/dist/transport.js

@@ -0,0 +1,140 @@
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.status = status;
+        this.code = code;
+    }
+}
+function validatedBase(url) {
+    const base = new URL(url);
+    if (base.username ||
+        base.password ||
+        base.search ||
+        base.hash ||
+        base.pathname !== '/' ||
+        (base.protocol !== 'https:' &&
+            !(base.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(base.hostname))))
+        throw new Error('Use an HTTPS service origin (HTTP is allowed only for localhost)');
+    return base;
+}
+function errorCode(value) {
+    return typeof value === 'object' &&
+        value !== null &&
+        'error' in value &&
+        typeof value.error === 'object' &&
+        value.error !== null &&
+        'code' in value.error &&
+        typeof value.error.code === 'string'
+        ? value.error.code
+        : 'request_failed';
+}
+export function clientCall(options) {
+    const base = validatedBase(options.url);
+    return async (method, path, input, format = 'json', timeoutMs = 30000) => {
+        const response = await (options.fetch ?? fetch)(new URL(path, base), {
+            method,
+            redirect: 'error',
+            credentials: 'omit',
+            headers: {
+                ...(options.organisationId ? { 'x-organisation-id': options.organisationId } : {}),
+                authorization: `Bearer ${await options.credential()}`,
+                ...(input === undefined ? {} : { 'content-type': 'application/json' }),
+            },
+            body: input === undefined ? undefined : JSON.stringify(input),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (response.status === 204)
+            return undefined;
+        if (format === 'text' && response.ok)
+            return (await response.text());
+        let value;
+        try {
+            value = await response.json();
+        }
+        catch {
+            throw new ApiError(response.status, 'invalid_response');
+        }
+        if (!response.ok)
+            throw new ApiError(response.status, errorCode(value));
+        if (!value || typeof value !== 'object' || !('data' in value))
+            throw new ApiError(response.status, 'invalid_response');
+        return value.data;
+    };
+}
+/** Reads one SSE frame stream (`event:`/`data:` lines, blank-line separated) off a
+ * response body and turns it into `RunStreamEvent`s, for `POST /v1/runs` with
+ * `stream: true`. Web-standard APIs only, so this stays reachable from the SDK's
+ * main entry with zero runtime dependencies (`pnpm check:package`).
+ */
+export function clientStream(options) {
+    const base = validatedBase(options.url);
+    return async function* (path, input, signal) {
+        const response = await (options.fetch ?? fetch)(new URL(path, base), {
+            method: 'POST',
+            redirect: 'error',
+            credentials: 'omit',
+            headers: {
+                ...(options.organisationId ? { 'x-organisation-id': options.organisationId } : {}),
+                authorization: `Bearer ${await options.credential()}`,
+                'content-type': 'application/json',
+                accept: 'text/event-stream',
+            },
+            body: JSON.stringify(input),
+            signal,
+        });
+        if (!response.ok || !response.body) {
+            let value;
+            try {
+                value = await response.json();
+            }
+            catch {
+                throw new ApiError(response.status, 'invalid_response');
+            }
+            throw new ApiError(response.status, errorCode(value));
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let index;
+                // biome-ignore lint/suspicious/noAssignInExpressions: tight SSE frame loop
+                while ((index = buffer.indexOf('\n\n')) !== -1) {
+                    const raw = buffer.slice(0, index);
+                    buffer = buffer.slice(index + 2);
+                    let event = 'message';
+                    const dataLines = [];
+                    for (const line of raw.split('\n')) {
+                        if (line.startsWith('event:'))
+                            event = line.slice(6).trim();
+                        else if (line.startsWith('data:'))
+                            dataLines.push(line.slice(5).trim());
+                    }
+                    if (!dataLines.length)
+                        continue;
+                    const data = JSON.parse(dataLines.join('\n'));
+                    if (event === 'delta' &&
+                        typeof data === 'object' &&
+                        data !== null &&
+                        'text' in data &&
+                        typeof data.text === 'string')
+                        yield { type: 'delta', text: data.text };
+                    else if (event === 'done')
+                        yield { type: 'done', run: data };
+                }
+            }
+        }
+        finally {
+            // A consumer that stops iterating early (e.g. `break`s the `for await`) drives
+            // this via the generator's implicit `return()`: cancelling here is what tells
+            // the server the client disconnected.
+            await reader.cancel().catch(() => { });
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,195 @@
+/** Public HTTP contracts. No service implementation or database types. */
+export interface RunRequest {
+    source: {
+        mode: 'connection';
+        id: string;
+        model: string;
+    } | {
+        mode: 'offering';
+        id: string;
+    };
+    input: unknown;
+    requestId: string;
+    attributionRef?: string;
+    /** `POST /v1/runs` responds with server-sent events instead of one JSON body.
+     * Refused before anything is reserved if the resolved model cannot stream. */
+    stream?: boolean;
+}
+export interface RunView {
+    id: string;
+    state: 'queued' | 'running' | 'succeeded' | 'failed' | 'unknown' | 'cancelled';
+    model: string;
+    output: unknown;
+    error: string | null;
+    createdAt: string;
+    /** A short, human-readable progress update while the run is in flight (e.g. fal's queue
+     * position), and when it was last observed. Null before the first update, and cleared
+     * back to null once the run reaches a terminal state, so a finished run never keeps
+     * showing a stale message. */
+    progress: {
+        message: string;
+        at: string;
+    } | null;
+}
+/** One event of a `stream: true` run, as `AiClient.stream` yields them: `delta` for
+ * each piece of text the provider produced, and exactly one terminal `done` carrying
+ * the same view `GET /v1/runs/:id` would show once the stream ends, however it ends
+ * (full completion, a disconnect that still settled, or a provider error mid-stream). */
+export type RunStreamEvent = {
+    type: 'delta';
+    text: string;
+} | {
+    type: 'done';
+    run: RunView;
+};
+export interface CreateConnection {
+    name: string;
+    provider: string;
+    models: string[];
+    credential: string;
+}
+export interface ConnectionView {
+    id: string;
+    name: string;
+    provider: string;
+    models: string[];
+    enabled: boolean;
+    revision: number;
+}
+export interface OfferingView {
+    id: string;
+    name: string;
+    model: string;
+    rateVersion: string;
+    rates: Record<string, {
+        micros: string;
+        perUnits: string;
+    }>;
+    /** JSON Schema for this model's input, generated from the adapter's own validation -
+     * never hand-written, so it cannot drift from what a run against this offering
+     * actually accepts or rejects. */
+    inputSchema: Record<string, unknown>;
+}
+export interface CreateOffering {
+    name: string;
+    model: string;
+    provider: string;
+    providerModel: string;
+    rateVersion: string;
+    rates: Record<string, {
+        micros: string;
+        perUnits: string;
+    }>;
+    /** What the provider charges us. NULL/omitted means the same as `rates`. Operator-only. */
+    upstreamRates?: Record<string, {
+        micros: string;
+        perUnits: string;
+    }>;
+    credential: string;
+}
+export interface UpdateOffering {
+    revision: number;
+    name?: string;
+    model?: string;
+    providerModel?: string;
+    rateVersion?: string;
+    rates?: Record<string, {
+        micros: string;
+        perUnits: string;
+    }>;
+    /** Omit to leave unchanged; null clears it back to "the same as rates". */
+    upstreamRates?: Record<string, {
+        micros: string;
+        perUnits: string;
+    }> | null;
+}
+export interface OfferingAdminView {
+    id: string;
+    name: string;
+    model: string;
+    provider: string;
+    providerModel: string;
+    rateVersion: string;
+    rates: Record<string, {
+        micros: string;
+        perUnits: string;
+    }>;
+    upstreamRates: Record<string, {
+        micros: string;
+        perUnits: string;
+    }> | null;
+    enabled: boolean;
+    revision: number;
+}
+export interface SetOfferingAccess {
+    organisationId: string;
+    enabled: boolean;
+}
+export interface OfferingAccessView {
+    offeringId: string;
+    organisationId: string;
+    enabled: boolean;
+}
+export interface UpdateBudget {
+    keyId: string | null;
+    limitMicros: string;
+}
+export interface BudgetView {
+    keyId: string | null;
+    periodStart: string;
+    periodEnd: string;
+    limitMicros: string | null;
+    spentMicros: string;
+    reservedMicros: string;
+    /** limit minus spent minus reserved, clamped at "0"; null when the row has no limit.
+     * For a key's own row this is the lower of its own remaining and its organisation's,
+     * since a run spends against both budgets at once. */
+    remainingMicros: string | null;
+}
+export interface UsageView {
+    id: string;
+    keyId: string | null;
+    amountMicros: string;
+    createdAt: string;
+}
+/** Operator-only: what a run cost us upstream, next to what it charged the customer.
+ * Never appears on `UsageView`, a customer's usage export, a run view or offering view. */
+export interface UsageCostView {
+    id: string;
+    keyId: string | null;
+    amountMicros: string;
+    upstreamMicros: string | null;
+    createdAt: string;
+}
+/** Operator-only: what our own account holds at a provider we pay. `amountMicros` is
+ * set only for `kind: 'amount'`; `reason` explains an `'unknown'` (the read failed) or
+ * `'not_applicable'` (nothing to read, or no admin key configured) reading. Never
+ * appears on any customer-facing view. */
+export interface BalanceReadingView {
+    id: string;
+    provider: string;
+    kind: 'amount' | 'unknown' | 'not_applicable';
+    amountMicros: string | null;
+    reason: string | null;
+    observedAt: string;
+}
+export interface SetWebhookAddress {
+    address: string;
+}
+export interface WebhookView {
+    address: string;
+    revision: number;
+    secretRotatedAt: string;
+    previousSecretValidUntil: string | null;
+}
+export interface WebhookDeliveryView {
+    id: string;
+    runId: string;
+    eventType: string;
+    status: 'pending' | 'delivered' | 'dead';
+    attempts: number;
+    lastStatusCode: number | null;
+    lastError: string | null;
+    createdAt: string;
+    deliveredAt: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhook-signing.d.ts

@@ -0,0 +1,11 @@
+/** Valet's exact scheme (Valet `src/lib/webhooks/sign.ts:44-68`): a header of
+ * `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">`, 300-second tolerance.
+ * A new receiver needs nothing but this header name to verify against a fresh secret.
+ */
+export declare const SIGNATURE_TOLERANCE_SECONDS = 300;
+export declare function signWebhookPayload(secret: string, body: string, timestamp: number): string;
+/** Verifies a signature header against every currently-valid secret (the active one,
+ * plus a rotated-out one still inside its overlap window), so a receiver mid-deploy
+ * on either secret is accepted. Each candidate is compared in constant time.
+ */
+export declare function verifyWebhookSignature(header: string, secrets: readonly string[], body: string, now: number, toleranceSeconds?: number): boolean;

package/dist/webhook-signing.js

@@ -0,0 +1,30 @@
+/// <reference types="node" />
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** Valet's exact scheme (Valet `src/lib/webhooks/sign.ts:44-68`): a header of
+ * `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">`, 300-second tolerance.
+ * A new receiver needs nothing but this header name to verify against a fresh secret.
+ */
+export const SIGNATURE_TOLERANCE_SECONDS = 300;
+export function signWebhookPayload(secret, body, timestamp) {
+    const mac = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
+    return `t=${timestamp},v1=${mac}`;
+}
+const HEADER_PATTERN = /^t=(\d+),v1=([0-9a-f]{64})$/;
+/** Verifies a signature header against every currently-valid secret (the active one,
+ * plus a rotated-out one still inside its overlap window), so a receiver mid-deploy
+ * on either secret is accepted. Each candidate is compared in constant time.
+ */
+export function verifyWebhookSignature(header, secrets, body, now, toleranceSeconds = SIGNATURE_TOLERANCE_SECONDS) {
+    const match = HEADER_PATTERN.exec(header);
+    if (!match)
+        return false;
+    const [, timestampText, signatureHex] = match;
+    const timestamp = Number(timestampText);
+    if (!Number.isSafeInteger(timestamp) || Math.abs(now - timestamp) > toleranceSeconds)
+        return false;
+    const provided = Buffer.from(signatureHex, 'hex');
+    return secrets.some((secret) => {
+        const expected = Buffer.from(createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex'), 'hex');
+        return provided.length === expected.length && timingSafeEqual(provided, expected);
+    });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@wtfalch/ai",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "description": "Public client SDK and API types for the AI service.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wtfalch/ai.git",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/client.js",
+    "dist/client.d.ts",
+    "dist/transport.js",
+    "dist/transport.d.ts",
+    "dist/types.js",
+    "dist/types.d.ts",
+    "dist/webhook-signing.js",
+    "dist/webhook-signing.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./webhooks": {
+      "types": "./dist/webhook-signing.d.ts",
+      "default": "./dist/webhook-signing.js"
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm --workspace-root check:sdk"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.6"
+  }
+}