@aithos/sdk 0.1.0-alpha.5 → 0.1.0-alpha.51

package/dist/src/compute.d.ts

@@ -1,16 +1,32 @@
 import type { AithosAuth } from "./auth.js";
 import { type AithosSdkEndpoints } from "./endpoints.js";
+import { type LocalPendingEntry, type TranscribeDraftMeta, type TranscribeDraftRecord } from "./transcribe-resilience.js";
 export interface ComputeMessage {
     readonly role: "user" | "assistant";
     readonly content: string;
 }
 export interface InvokeBedrockArgs {
-    /** Mandate ID granting this app the right to spend the user's wallet. */
-    readonly mandateId: string;
+    /**
+     * Mandate ID under which this call should be attributed.
+     *
+     * - **Owner sessions**: optional. The SDK uses the owner's own DID
+     *   as a sentinel "self" mandate id — the proxy skips all
+     *   mandate-related checks (scope, allowed_models, caps) when the
+     *   envelope is owner-signed, so the value is informational only.
+     * - **Delegate sessions**: required. Must reference the imported
+     *   mandate bundle the SDK signs with (the proxy enforces
+     *   `compute.invoke` scope and any `allowed_models` filter).
+     */
+    readonly mandateId?: string;
     /**
      * Model id. Today the proxy accepts the canonical Aithos identifiers:
-     *   `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-7`.
+     *   `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-opus-4-6`.
      * The proxy maps these to Bedrock cross-region inference profiles.
+     *
+     * NOTE: `claude-opus-4-7` is also provisioned on the Bedrock account
+     * but commercial access is gated behind an AWS Sales unlock (as of
+     * May 2026) — InvokeModel returns AccessDeniedException pointing to
+     * AWS Sales. Stick with `claude-opus-4-6` until the unlock lands.
      */
     readonly model: string;
     /** Conversation messages (user / assistant turns). */
@@ -43,6 +59,301 @@ export interface InvokeBedrockResult {
     readonly walletBalance: number;
     /** Audit log id for traceability. */
     readonly auditId: string;
+    /**
+     * Which wallet was actually debited (draft §13.8, V0.1 sponsorship).
+     *   - `"sponsored"` — the app developer's wallet (free trial / promo).
+     *   - `"grant"`     — the user's grant bucket (Aithos-donated credits).
+     *   - `"purchase"`  — the user's own paid credits.
+     * Absent on legacy server responses (pre-2026-05-27).
+     */
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    /**
+     * If `fundedBy === "sponsored"`, the sponsor's DID (= the developer
+     * who pre-paid the pool). Absent otherwise.
+     */
+    readonly sponsoredBy?: string;
+    /**
+     * If sponsored, the signed `ConsumptionReceipt` id (`rcpt_…`) the
+     * authority issued for this debit. The receipt itself can be fetched
+     * later via the receipts API (V0.2). Present on every signed call
+     * when the authority is configured, regardless of `fundedBy`.
+     */
+    readonly receiptId?: string;
+    /**
+     * If sponsored, remaining microcredits for THIS consumer in this
+     * sponsorship pool. Useful for displaying "X free calls remaining"
+     * without an extra round-trip. May be `0` even when the user can
+     * still consume — when the authority can't compute the remainder
+     * cheaply (e.g. windowed caps), the SDK gets a conservative 0 and
+     * the SPA should fall back to calling `sdk.apps.getSponsorshipStatusForUser`
+     * (V0.2).
+     */
+    readonly sponsoredRemainingForUser?: number;
+}
+/**
+ * Stable cross-provider image model ids supported by the Aithos compute
+ * proxy. New models can be added on the server side without an SDK
+ * release — but tagging the namespaced literal here gives consumers
+ * autocomplete + type-checking.
+ *
+ * The `image:` prefix is part of the wire contract: the server uses it
+ * to disambiguate text and image dispatch when a mandate's
+ * `allowed_models` mixes both.
+ */
+export type ImageModelId = "image:flux-schnell" | "image:flux-dev" | "image:flux-pro-1.1" | "image:flux-pro-1.1-ultra" | "image:imagen-3" | "image:imagen-4" | "image:nano-banana";
+/** Aspect ratios accepted by `invokeImage`. */
+export type ImageAspectRatio = "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "21:9";
+export interface InvokeImageArgs {
+    /**
+     * Mandate ID under which this call should be attributed.
+     *
+     * - **Owner sessions**: optional. The SDK uses the owner's own DID
+     *   as a sentinel "self" mandate id — the proxy skips all
+     *   mandate-related checks when the envelope is owner-signed.
+     * - **Delegate sessions**: required. Must reference the imported
+     *   mandate bundle the SDK signs with.
+     */
+    readonly mandateId?: string;
+    /**
+     * Image model id. Defaults to `"image:flux-pro-1.1"` on the SDK side
+     * if omitted — the server allowlist is the source of truth for which
+     * ones actually work.
+     */
+    readonly model?: ImageModelId;
+    /** What to draw. */
+    readonly prompt: string;
+    /** Optional comma-separated list of things to avoid (e.g. "blurry, watermark"). */
+    readonly negativePrompt?: string;
+    /** Default 1:1. */
+    readonly aspectRatio?: ImageAspectRatio;
+    /** Deterministic seed (re-rolls). Omit for random. */
+    readonly seed?: number;
+    /** Number of images to generate. Default 1, max 4. */
+    readonly numberOfImages?: number;
+    /** Idempotency key for retries (generated if omitted). */
+    readonly idempotencyKey?: string;
+    /** Abort signal to cancel the request (network + provider call). */
+    readonly signal?: AbortSignal;
+}
+export interface InvokeImageImage {
+    /** Base64-encoded image bytes (raw, no data: URI prefix). */
+    readonly base64: string;
+    /** "image/png" | "image/jpeg". */
+    readonly contentType: string;
+    readonly width: number;
+    readonly height: number;
+}
+export interface InvokeImageResult {
+    readonly images: readonly InvokeImageImage[];
+    /** Seed actually used by the provider (echoed back even when caller didn't set one). */
+    readonly seed: number;
+    /** Microcredits debited from the wallet (exact — no reconcile path for images). */
+    readonly creditsCharged: number;
+    /** Wallet balance after debit. */
+    readonly walletBalance: number;
+    /** Audit log id for traceability. */
+    readonly auditId: string;
+}
+export interface InvokeBedrockVisionArgs {
+    readonly mandateId?: string;
+    /**
+     * Model id. Sonnet 4.6 is the default — it's vision-capable and
+     * returns reliable structured JSON when prompted.
+     */
+    readonly model?: string;
+    /** Source image — Blob (recommended) or raw base64. */
+    readonly image: Blob | {
+        readonly base64: string;
+        readonly contentType: string;
+    };
+    /** Text prompt accompanying the image. */
+    readonly prompt: string;
+    /** Optional system prompt. */
+    readonly system?: string;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface InvokeBedrockVisionResult {
+    readonly content: string;
+    readonly stopReason: StopReason;
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+}
+export interface InvokeSegmentationArgs {
+    /** Mandate id (optional for owner sessions — see InvokeImageArgs). */
+    readonly mandateId?: string;
+    /** Source image. Blob (recommended) or raw base64. */
+    readonly image: Blob | {
+        readonly base64: string;
+        readonly contentType: string;
+    };
+    /**
+     * Text phrase describing what to segment. Florence-2 is robust with
+     * natural-language descriptions: "the torso of the robot", "the
+     * dog's head", "the chest of the character".
+     */
+    readonly textInput: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface SegmentPolygon {
+    readonly points: ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+    }>;
+}
+export interface InvokeSegmentationResult {
+    /** All polygons Florence-2 returned (typically 1, sometimes a few when the prompt matches multiple regions). */
+    readonly polygons: readonly SegmentPolygon[];
+    /** Bbox of the first polygon for callers that only need a coarse target. */
+    readonly bbox: {
+        readonly left: number;
+        readonly top: number;
+        readonly right: number;
+        readonly bottom: number;
+    } | null;
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+}
+/**
+ * Stable cross-provider transcription model ids. The `transcribe:` prefix
+ * is part of the wire contract (mirrors `image:` for image models). New
+ * models can be added server-side without an SDK release; the union here
+ * gives autocomplete + type-checking for the common ones.
+ */
+export type TranscribeModelId = "transcribe:aws-fr-standard" | "transcribe:aws-en-standard";
+/** Progress callback states emitted by {@link ComputeNamespace.invokeTranscribe}. */
+export type TranscribeProgressState = {
+    readonly phase: "queued";
+} | {
+    readonly phase: "uploading";
+    readonly bytesUploaded: number;
+    readonly totalBytes: number;
+} | {
+    readonly phase: "starting";
+} | {
+    readonly phase: "processing";
+    readonly elapsedSec: number;
+} | {
+    readonly phase: "completed";
+};
+export interface TranscribeSegment {
+    readonly start_sec: number;
+    readonly end_sec: number;
+    readonly text: string;
+    readonly speaker_label?: string;
+}
+export interface TranscribeWord {
+    readonly start_sec: number;
+    readonly end_sec: number;
+    readonly content: string;
+    readonly confidence: number;
+}
+/** High-level args for the one-call {@link ComputeNamespace.invokeTranscribe}. */
+export interface InvokeTranscribeArgs {
+    /** Mandate id — optional for owner sessions, required for delegate sessions. */
+    readonly mandateId?: string;
+    /** The audio to transcribe. `Blob` is supported in both Node 18+ and browsers. */
+    readonly audio: Blob;
+    /** Model alias. Default `"transcribe:aws-fr-standard"`. */
+    readonly model?: TranscribeModelId;
+    /** AWS language code override (e.g. `"fr-FR"`). Defaults to the model alias's language. */
+    readonly languageCode?: string;
+    /** Speaker diarization. Default `false`. */
+    readonly diarization?: boolean;
+    /**
+     * Audio duration in seconds. REQUIRED on backends / non-browser runtimes
+     * (used for the wallet pre-debit estimate). In a browser it is probed
+     * automatically from the Blob when omitted; if probing fails the SDK
+     * falls back to a server-reconciled estimate of 0.
+     */
+    readonly durationSecOverride?: number;
+    /** Idempotency key for replay-safe retries (generated if omitted). */
+    readonly idempotencyKey?: string;
+    /** Progress callback (upload bytes, processing elapsed, …). */
+    readonly onProgress?: (state: TranscribeProgressState) => void;
+    /** Abort signal — cancels upload + polling. */
+    readonly signal?: AbortSignal;
+    /**
+     * Polling cadence override (ms) for the status loop. Defaults to an
+     * exponential backoff 2s → 15s. Mainly for tests.
+     */
+    readonly pollIntervalMs?: number;
+}
+export interface InvokeTranscribeResult {
+    readonly text: string;
+    readonly segments: readonly TranscribeSegment[];
+    readonly words: readonly TranscribeWord[];
+    readonly durationSec: number;
+    readonly languageCode: string;
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+    readonly jobId: string;
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    readonly sponsoredBy?: string;
+    readonly receiptId?: string;
+}
+export interface PrepareTranscribeArgs {
+    readonly contentType: string;
+    readonly durationSecEstimate?: number;
+    /** Selects the delegate signer for delegate sessions (not sent on the wire). */
+    readonly mandateId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface PrepareTranscribeResult {
+    readonly jobId: string;
+    readonly uploadUrl: string;
+    readonly s3ObjectKey: string;
+    readonly expiresAt: number;
+}
+export interface StartTranscribeArgs {
+    readonly jobId: string;
+    readonly mandateId?: string;
+    readonly model: TranscribeModelId | string;
+    readonly durationSec: number;
+    readonly languageCode?: string;
+    readonly diarization?: boolean;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface StartTranscribeResult {
+    readonly jobId: string;
+    readonly status: "running";
+    readonly estimatedCredits: number;
+    readonly walletBalance: number;
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    readonly receiptId?: string;
+}
+export type TranscribeStatusResult = {
+    readonly jobId: string;
+    readonly status: "running";
+    readonly elapsedSec: number;
+} | ({
+    readonly jobId: string;
+    readonly status: "completed";
+} & InvokeTranscribeResult) | {
+    readonly jobId: string;
+    readonly status: "failed";
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export interface TranscribeJobSummary {
+    readonly jobId: string;
+    readonly status: "prepared" | "running" | "completed" | "failed";
+    readonly createdAt: number;
+    readonly estimatedCredits?: number;
+    readonly creditsCharged?: number;
 }
 export interface ComputeNamespaceDeps {
     readonly auth: AithosAuth;
@@ -63,11 +374,158 @@ export declare class ComputeNamespace {
      * Invoke a Bedrock model through the compute proxy. See
      * {@link InvokeBedrockArgs} and {@link InvokeBedrockResult}.
      *
+     * Two signer paths are supported:
+     *
+     *   - **Owner**: when the caller is signed in as an owner, the
+     *     envelope is signed with the owner's `#public` sphere key and
+     *     no mandate is attached (the proxy resolves the mandate
+     *     server-side from `params.mandate_id`).
+     *   - **Delegate**: when the caller is delegate-only (mandate
+     *     imported via `auth.importMandate`), the envelope is signed
+     *     with the delegate's bound keypair and the full SignedMandate
+     *     is attached so the proxy can verify both signature and
+     *     authorisation in one pass. The mandate must carry the
+     *     `compute.invoke` scope and the proxy enforces its constraints
+     *     (caps, allowed models, …) at server-side.
+     *
+     * Owner takes precedence: if a session has BOTH an owner and a
+     * matching delegate session, we use the owner key (more flexible —
+     * the mandate is dereferenced via `mandate_id` and there's no
+     * lifetime cliff if the delegate seed has been wiped).
+     *
      * @throws {AithosSDKError} on protocol errors. The `code` field is one of
-     *   `sdk_no_owner`, `network`, `http`, `empty`, or any code returned by
-     *   the proxy (`quota_exceeded`, `mandate_revoked`, `insufficient_credits`,
-     *   …).
+     *   `sdk_no_signer`, `sdk_no_delegate_for_mandate`, `network`, `http`,
+     *   `empty`, or any code returned by the proxy (`quota_exceeded`,
+     *   `mandate_revoked`, `insufficient_credits`, …).
      */
     invokeBedrock(args: InvokeBedrockArgs): Promise<InvokeBedrockResult>;
+    /**
+     * Multimodal Bedrock invoke — image + text → text response.
+     * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).
+     *
+     * Use when you need a VLM to reason about an image: locating
+     * features, structured extraction, semantic Q&A. Prompt the model
+     * to return JSON if you need structured output (the API itself is
+     * unstructured).
+     */
+    invokeBedrockVision(args: InvokeBedrockVisionArgs): Promise<InvokeBedrockVisionResult>;
+    /**
+     * Generate one or more images through the Aithos compute proxy
+     * (currently powered by fal.ai FLUX models). Spec mirror of
+     * {@link invokeBedrock}: same envelope, same wallet path, same
+     * mandate-scope gate (`compute.invoke` + `allowed_models`). The
+     * separation at the JSON-RPC method level (`aithos.compute_invoke_image`
+     * vs `aithos.compute_invoke`) commits each envelope to a specific
+     * modality so a stolen text-invoke envelope cannot be replayed
+     * against the image endpoint.
+     *
+     * Default model: `"image:flux-pro-1.1"`. Default aspect ratio: 1:1.
+     * Default count: 1 image.
+     *
+     * Pricing is per image and deterministic (no token-based reconcile):
+     *   - flux-schnell:        3 000 mc + fee per image
+     *   - flux-dev:           25 000 mc + fee per image
+     *   - flux-pro-1.1:       40 000 mc + fee per image
+     *   - flux-pro-1.1-ultra: 60 000 mc + fee per image
+     */
+    invokeImage(args: InvokeImageArgs): Promise<InvokeImageResult>;
+    /**
+     * Run text-prompted segmentation (Florence-2 referring-expression)
+     * on a source image. Returns one or more polygons hugging the
+     * region matching the text prompt.
+     *
+     * Use cases: locate the chest/torso area of a generated mascot
+     * for logo compositing, find the face zone for a thumbnail crop,
+     * extract a product from a marketing shot — anything that needs
+     * a precise mask + bbox from natural-language description.
+     *
+     * Pricing: flat 5 000 mc per call (~$0.005 — Florence-2 is cheap).
+     */
+    invokeSegmentation(args: InvokeSegmentationArgs): Promise<InvokeSegmentationResult>;
+    /**
+     * Provision a transcription job and get a pre-signed S3 URL to PUT the
+     * audio to. No wallet debit. `mandateId` only selects the delegate
+     * signer (it is not part of the wire params for prepare).
+     */
+    prepareTranscribe(args: PrepareTranscribeArgs): Promise<PrepareTranscribeResult>;
+    /**
+     * Verify the uploaded audio, pre-debit the wallet, and launch the AWS
+     * Transcribe job. Returns immediately with `status: "running"`.
+     */
+    startTranscribe(args: StartTranscribeArgs): Promise<StartTranscribeResult>;
+    /**
+     * Poll a job's status. On completion the server finalises (reconcile +
+     * audit) and returns the transcript; a resumed poll after reconnect
+     * re-reads the transcript while it's still in the 24h output window.
+     */
+    getTranscribeStatus(args: {
+        readonly jobId: string;
+        readonly mandateId?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<TranscribeStatusResult>;
+    /**
+     * List the caller's transcription jobs. Excludes terminal `completed`
+     * jobs unless `includeCompleted` is set — the resilience "what's still
+     * pending server-side" query.
+     */
+    listPendingTranscribes(args?: {
+        readonly includeCompleted?: boolean;
+        readonly mandateId?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly jobs: readonly TranscribeJobSummary[];
+    }>;
+    /**
+     * Transcribe an audio Blob to text in one call. Composes the four
+     * low-level methods: prepare → direct S3 upload → start → poll. Returns
+     * the transcript and stores NOTHING server-side beyond the ephemeral
+     * job — the consumer decides what to do with the result.
+     *
+     * Isomorphic: depends only on `Blob`, `fetch`/`XMLHttpRequest` and
+     * timers. On a backend, pass `durationSecOverride` (no Blob duration
+     * probing is possible without a DOM); in a browser the duration is
+     * probed automatically when omitted.
+     *
+     * Resilience: the job id is recorded in a localStorage tracker (browser)
+     * before upload, so `listLocalPendingTranscribes()` / `resumeTranscribe()`
+     * can recover a job whose result never arrived. In Node the tracker is a
+     * harmless in-memory no-op.
+     */
+    invokeTranscribe(args: InvokeTranscribeArgs): Promise<InvokeTranscribeResult>;
+    /**
+     * Resume polling an in-flight job by id — for recovery after a reload or
+     * crash. Returns the final result and clears the job from the local
+     * pending tracker. Throws if the job has already failed.
+     */
+    resumeTranscribe(jobId: string, opts?: {
+        readonly mandateId?: string;
+        readonly onProgress?: (state: TranscribeProgressState) => void;
+        readonly signal?: AbortSignal;
+        readonly pollIntervalMs?: number;
+    }): Promise<InvokeTranscribeResult>;
+    /** Snapshot of locally-tracked in-flight jobs (stable ref between mutations). */
+    listLocalPendingTranscribes(): readonly LocalPendingEntry[];
+    /** Stable snapshot for `useSyncExternalStore`-style consumers. */
+    getLocalPendingTranscribesSnapshot(): readonly LocalPendingEntry[];
+    /**
+     * Subscribe to changes in the local pending-jobs registry. Returns an
+     * unsubscribe function. Framework-agnostic: wrap it in a React
+     * `useSyncExternalStore`, a Vue effect, a Svelte store, etc.
+     */
+    subscribeLocalPendingTranscribes(listener: () => void): () => void;
+    /**
+     * IndexedDB-backed draft queue: persist a recording before any network
+     * call, upload it when the user confirms. Browser-only (methods reject
+     * with TranscribeDraftUnavailableError when IndexedDB is absent).
+     */
+    get transcribeDraft(): {
+        readonly save: (blob: Blob, meta?: TranscribeDraftMeta) => Promise<{
+            readonly draftId: string;
+        }>;
+        readonly list: () => Promise<readonly TranscribeDraftRecord[]>;
+        readonly get: (draftId: string) => Promise<TranscribeDraftRecord | null>;
+        readonly delete: (draftId: string) => Promise<void>;
+        readonly upload: (draftId: string, args: Omit<InvokeTranscribeArgs, "audio">) => Promise<InvokeTranscribeResult>;
+    };
 }
 //# sourceMappingURL=compute.d.ts.map