@wtfalch/ai 0.1.0 → 0.2.0

package/README.md

@@ -45,6 +45,13 @@ settles in time, HTTP 202 with the run's current state (usually still
 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.
 
+`submitBatch(runs)` queues up to 100 runs in one request (`POST /v1/runs/batch`).
+Each item is an ordinary queued submit with its own `requestId`, rate-limit slot
+and budget reservation. The result array is in request order, and each item is
+either `{ run }` or `{ error: { code, message } }`. A refused item does not affect
+the others, and resending the same batch replays the runs already created. Batch
+items cannot stream or `wait`, and the whole request body is capped at 256 KB.
+
 A fal image offering (seedream-v4, seedream-v4-edit, birefnet) settles the same way and
 returns its files in `output.files`:
 

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 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';
+import type { BalanceReadingView, BatchRunResult, BudgetView, ConnectionView, ConsumptionRecordView, CreateConnection, CreateOffering, OfferingAccessView, OfferingAdminView, OfferingView, RunRequest, RunStreamEvent, RunView, SetOfferingAccess, SetWebhookAddress, SetWebhookResult, UpdateBudget, UpdateOffering, UsageCostView, UsageView, WebhookDeliveryView, WebhookProvisioning, WebhookView } from './types.js';
 export { ApiError, type ClientOptions } from './transport.js';
 export declare function createAiClient(options: ClientOptions): {
     createConnection: (input: CreateConnection) => Promise<ConnectionView>;
@@ -16,6 +16,11 @@ export declare function createAiClient(options: ClientOptions): {
     submit: (input: RunRequest, options?: {
         wait?: number;
     }) => Promise<RunView>;
+    /** Submits up to 100 runs in one request. Each is an ordinary queued submit with
+     * its own `requestId`, so resending a batch replays the runs already created.
+     * Results are in request order; a refused item carries its error instead of a run.
+     * Streaming and `wait` are not available here. */
+    submitBatch: (runs: RunRequest[]) => Promise<BatchRunResult[]>;
     /** 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
@@ -47,6 +52,14 @@ export declare function createAiClient(options: ClientOptions): {
         after?: string;
         limit?: number;
     }) => Promise<UsageView[]>;
+    listConsumption: (page?: {
+        after?: string;
+        limit?: number;
+    }) => Promise<ConsumptionRecordView[]>;
+    exportConsumption: (range: {
+        from: string;
+        to: string;
+    }) => Promise<string>;
     listCostUsage: (page?: {
         after?: string;
         limit?: number;
@@ -59,8 +72,8 @@ export declare function createAiClient(options: ClientOptions): {
         limit?: number;
     }) => Promise<BalanceReadingView[]>;
     getWebhook: () => Promise<WebhookView>;
-    setWebhookAddress: (input: SetWebhookAddress) => Promise<WebhookView>;
-    rotateWebhookSecret: (revision: number) => Promise<WebhookView>;
+    setWebhookAddress: (input: SetWebhookAddress) => Promise<SetWebhookResult>;
+    rotateWebhookSecret: (revision: number) => Promise<WebhookProvisioning>;
     listWebhookDeliveries: (page?: {
         after?: string;
         limit?: number;

package/dist/client.js

@@ -20,6 +20,11 @@ export function createAiClient(options) {
             : `/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),
+        /** Submits up to 100 runs in one request. Each is an ordinary queued submit with
+         * its own `requestId`, so resending a batch replays the runs already created.
+         * Results are in request order; a refused item carries its error instead of a run.
+         * Streaming and `wait` are not available here. */
+        submitBatch: (runs) => call('POST', '/v1/runs/batch', { runs }),
         /** 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
@@ -39,6 +44,8 @@ export function createAiClient(options) {
         listBudgets: (page = {}) => call('GET', `/v1/budgets?${pageQuery(page)}`),
         updateBudget: (input) => call('PUT', '/v1/budgets', input),
         listUsage: (page = {}) => call('GET', `/v1/usage?${pageQuery(page)}`),
+        listConsumption: (page = {}) => call('GET', `/v1/consumption?${pageQuery(page)}`),
+        exportConsumption: (range) => call('GET', `/v1/consumption/export?${new URLSearchParams(range)}`, undefined, 'text'),
         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)}`),

package/dist/estimate.d.ts

@@ -0,0 +1,21 @@
+/** Local, network-free preview of spend before a run is submitted. Neither function is
+ * authoritative: the service still bounds real work by the model's own configured
+ * `maximumInputTokens`, and the real charge always comes from the provider's reported
+ * usage, settled through the service's own `costMicros`. These exist so a caller can
+ * preview spend before submitting, not to replace that settlement.
+ */
+/** A fast, provider-agnostic approximation - roughly 4 characters per token for English
+ * text, the same rule of thumb OpenAI and Anthropic publish for a rough estimate. It is
+ * not any provider's real tokenizer and can be off by a wide margin for other scripts,
+ * code, or unusual token boundaries. */
+export declare function estimateTokens(text: string): number;
+/** Estimated cost in micros for a set of token counts (or any other billed units) against
+ * an offering's or connection's own rates. Uses the exact same per-category round-up-then-
+ * sum arithmetic as the service's `costMicros` (`packages/service/src/provider.ts`), so a
+ * preview never reads as cheaper than what those same units would actually be charged.
+ * Throws on a unit with no rate, or a negative/non-integer/empty amount, exactly like the
+ * service does - never silently returns a wrong or negative estimate. */
+export declare function estimateCostMicros(units: Record<string, string>, rates: Record<string, {
+    micros: string;
+    perUnits: string;
+}>): string;

package/dist/estimate.js

@@ -0,0 +1,46 @@
+/** Local, network-free preview of spend before a run is submitted. Neither function is
+ * authoritative: the service still bounds real work by the model's own configured
+ * `maximumInputTokens`, and the real charge always comes from the provider's reported
+ * usage, settled through the service's own `costMicros`. These exist so a caller can
+ * preview spend before submitting, not to replace that settlement.
+ */
+/** A fast, provider-agnostic approximation - roughly 4 characters per token for English
+ * text, the same rule of thumb OpenAI and Anthropic publish for a rough estimate. It is
+ * not any provider's real tokenizer and can be off by a wide margin for other scripts,
+ * code, or unusual token boundaries. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// Same shape the service's own amountSchema requires (packages/service/src/money.ts):
+// digits only, no sign, no decimal point, no leading zero. `BigInt('-1')` and
+// `BigInt('1e5')` do not agree on that - the former silently parses to a negative
+// value and the latter throws only by luck of syntax - so every amount is checked
+// against this pattern before use rather than handed straight to `BigInt`.
+const amountPattern = /^(0|[1-9][0-9]*)$/;
+function amount(value, label) {
+    if (!amountPattern.test(value))
+        throw new Error(`Not a valid non-negative amount for ${label}: ${value}`);
+    return BigInt(value);
+}
+/** Estimated cost in micros for a set of token counts (or any other billed units) against
+ * an offering's or connection's own rates. Uses the exact same per-category round-up-then-
+ * sum arithmetic as the service's `costMicros` (`packages/service/src/provider.ts`), so a
+ * preview never reads as cheaper than what those same units would actually be charged.
+ * Throws on a unit with no rate, or a negative/non-integer/empty amount, exactly like the
+ * service does - never silently returns a wrong or negative estimate. */
+export function estimateCostMicros(units, rates) {
+    let total = 0n;
+    for (const [unit, quantity] of Object.entries(units)) {
+        const rate = rates[unit];
+        if (rate === undefined)
+            throw new Error(`Unpriced consumption unit: ${unit}`);
+        const numerator = amount(quantity, unit) * amount(rate.micros, `${unit}.micros`);
+        const denominator = amount(rate.perUnits, `${unit}.perUnits`);
+        if (denominator === 0n)
+            throw new Error(`Rate denominator must be positive: ${unit}`);
+        // Round each category up to one micro-dollar only after multiplication, same as the
+        // service, so the two never disagree by a rounding direction.
+        total += (numerator + denominator - 1n) / denominator;
+    }
+    return total.toString();
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/transport.d.ts

@@ -8,7 +8,17 @@ export interface ClientOptions {
 export declare class ApiError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(status: number, code: string);
+    /** Seconds until the caller may retry, read off the response's `Retry-After`
+     * header (service/http.ts sends it only on `rate_limited`). `undefined` when
+     * absent or not a plain positive integer of at most a week - this never retries
+     * on its own. */
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(status: number, code: string, 
+    /** Seconds until the caller may retry, read off the response's `Retry-After`
+     * header (service/http.ts sends it only on `rate_limited`). `undefined` when
+     * absent or not a plain positive integer of at most a week - this never retries
+     * on its own. */
+    retryAfterSeconds?: number | undefined);
 }
 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

package/dist/transport.js

@@ -1,12 +1,33 @@
 export class ApiError extends Error {
     status;
     code;
-    constructor(status, code) {
+    retryAfterSeconds;
+    constructor(status, code, 
+    /** Seconds until the caller may retry, read off the response's `Retry-After`
+     * header (service/http.ts sends it only on `rate_limited`). `undefined` when
+     * absent or not a plain positive integer of at most a week - this never retries
+     * on its own. */
+    retryAfterSeconds) {
         super(code);
         this.status = status;
         this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
     }
 }
+/** A week. A hint further out than this is not a delay a caller can wait for, so it
+ * is read as a broken header instead. */
+const maxRetryAfterSeconds = 604_800;
+/** A sane positive-integer `Retry-After` in seconds, or `undefined` for a missing,
+ * fractional, non-numeric, non-positive or implausibly distant value (never `NaN`).
+ * The header comes from whatever server the SDK is pointed at, so only plain decimal
+ * digits count: `Number` alone would read `0x2A` as 42 and twenty-five nines as 1e25. */
+function retryAfter(headers) {
+    const raw = headers.get('retry-after');
+    if (raw === null || !/^[0-9]+$/.test(raw))
+        return undefined;
+    const seconds = Number(raw);
+    return seconds > 0 && seconds <= maxRetryAfterSeconds ? seconds : undefined;
+}
 function validatedBase(url) {
     const base = new URL(url);
     if (base.username ||
@@ -19,6 +40,17 @@ function validatedBase(url) {
         throw new Error('Use an HTTPS service origin (HTTP is allowed only for localhost)');
     return base;
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Bounds for the SDK's own automatic retry, independent of the much larger
+ * `maxRetryAfterSeconds` sanity bound `retryAfter` validates against: a caller who
+ * gets `ApiError` back (because the server asked for a longer wait, or attempts ran
+ * out) can still retry by hand using `retryAfterSeconds`, exactly as before this
+ * existed. This only automates the short, common rate-limited case so every consumer
+ * stops hand-rolling that loop themselves. */
+const maxAutoRetries = 2;
+const maxAutoRetryDelaySeconds = 5;
 function errorCode(value) {
     return typeof value === 'object' &&
         value !== null &&
@@ -33,34 +65,47 @@ function errorCode(value) {
 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');
+        for (let retries = 0;; retries++) {
+            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', retryAfter(response.headers));
+            }
+            if (!response.ok) {
+                const wait = retryAfter(response.headers);
+                // Only a server-declared, short `Retry-After` auto-retries: the request is
+                // provably unprocessed (service/http.ts only sends this header on
+                // `rate_limited`), so replaying it is always safe, regardless of whether this
+                // particular call happens to be idempotent on its own. A longer wait, or a
+                // request with no such header, surfaces immediately - the caller decides.
+                if (wait !== undefined && wait <= maxAutoRetryDelaySeconds && retries < maxAutoRetries) {
+                    await sleep(wait * 1000);
+                    continue;
+                }
+                throw new ApiError(response.status, errorCode(value), wait);
+            }
+            if (!value || typeof value !== 'object' || !('data' in value))
+                throw new ApiError(response.status, 'invalid_response', retryAfter(response.headers));
+            return value.data;
         }
-        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
@@ -90,9 +135,9 @@ export function clientStream(options) {
                 value = await response.json();
             }
             catch {
-                throw new ApiError(response.status, 'invalid_response');
+                throw new ApiError(response.status, 'invalid_response', retryAfter(response.headers));
             }
-            throw new ApiError(response.status, errorCode(value));
+            throw new ApiError(response.status, errorCode(value), retryAfter(response.headers));
         }
         const reader = response.body.getReader();
         const decoder = new TextDecoder();

package/dist/types.d.ts

@@ -15,6 +15,22 @@ export interface RunRequest {
      * Refused before anything is reserved if the resolved model cannot stream. */
     stream?: boolean;
 }
+/** Observed consumption, independent of customer price or upstream cost. Omitted
+ * categories are unknown, not zero. A partial snapshot may contain lower bounds. */
+export interface ConsumptionView {
+    units: Record<string, string>;
+    status: 'complete' | 'partial' | 'unavailable';
+    source: 'provider_reported' | 'adapter_derived';
+}
+export interface ConsumptionRecordView {
+    runId: string;
+    keyId: string | null;
+    model: string;
+    attributionRef: string | null;
+    outcome: 'succeeded' | 'failed' | 'cancelled';
+    consumption: ConsumptionView;
+    recordedAt: string;
+}
 export interface RunView {
     id: string;
     state: 'queued' | 'running' | 'succeeded' | 'failed' | 'unknown' | 'cancelled';
@@ -30,11 +46,24 @@ export interface RunView {
         message: string;
         at: string;
     } | null;
+    /** Null before a measured result or for historical/uninstrumented adapters. */
+    consumption: ConsumptionView | 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). */
+/** One item of `POST /v1/runs/batch`, in request order: the submitted (queued or
+ * replayed) run, or the same `{ code, message }` a single `POST /v1/runs` would have
+ * failed with. One item's error never affects the others. */
+export type BatchRunResult = {
+    run: RunView;
+} | {
+    error: {
+        code: string;
+        message: string;
+    };
+};
 export type RunStreamEvent = {
     type: 'delta';
     text: string;
@@ -85,6 +114,9 @@ export interface CreateOffering {
         micros: string;
         perUnits: string;
     }>;
+    /** Platform-only forge binding selected by the operator. The binding's
+     * endpoint, account and transport secret are never part of this request. */
+    executionBindingId?: string;
     credential: string;
 }
 export interface UpdateOffering {
@@ -182,6 +214,13 @@ export interface WebhookView {
     secretRotatedAt: string;
     previousSecretValidUntil: string | null;
 }
+/** Only creation and rotation disclose a secret. Persist it in the receiver's
+ * secret store immediately; ordinary reads cannot recover it. */
+export interface WebhookProvisioning {
+    webhook: WebhookView;
+    secret: string;
+}
+export type SetWebhookResult = WebhookProvisioning | WebhookView;
 export interface WebhookDeliveryView {
     id: string;
     runId: string;

package/dist/webhook-signing.d.ts

@@ -3,7 +3,7 @@
  * 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;
+export declare function signWebhookPayload(secret: string | readonly 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.

package/dist/webhook-signing.js

@@ -6,25 +6,36 @@ import { createHmac, timingSafeEqual } from 'node:crypto';
  */
 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 secrets = typeof secret === 'string' ? [secret] : secret;
+    if (secrets.length === 0)
+        throw new Error('At least one signing secret is required');
+    const signatures = secrets.map((key) => `v1=${createHmac('sha256', key).update(`${timestamp}.${body}`).digest('hex')}`);
+    return `t=${timestamp},${signatures.join(',')}`;
 }
-const HEADER_PATTERN = /^t=(\d+),v1=([0-9a-f]{64})$/;
+// Require one timestamp and well-formed signatures, preserving repeated v1 keys.
+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)
+    if (!match || match[0] !== header)
         return false;
-    const [, timestampText, signatureHex] = match;
+    const [, timestampText, signatures] = match;
     const timestamp = Number(timestampText);
-    if (!Number.isSafeInteger(timestamp) || Math.abs(now - timestamp) > toleranceSeconds)
+    if (!Number.isSafeInteger(timestamp) ||
+        !Number.isFinite(now) ||
+        !Number.isFinite(toleranceSeconds) ||
+        toleranceSeconds < 0 ||
+        Math.abs(now - timestamp) > toleranceSeconds)
         return false;
-    const provided = Buffer.from(signatureHex, 'hex');
+    const provided = signatures
+        .slice(1)
+        .split(',')
+        .map((part) => Buffer.from(part.slice(3), '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);
+        return provided.some((candidate) => timingSafeEqual(candidate, expected));
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/ai",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,6 +16,8 @@
     "dist/index.d.ts",
     "dist/client.js",
     "dist/client.d.ts",
+    "dist/estimate.js",
+    "dist/estimate.d.ts",
     "dist/transport.js",
     "dist/transport.d.ts",
     "dist/types.js",