@aithos/sdk 0.1.0-alpha.14 → 0.1.0-alpha.17

package/dist/src/compute.d.ts

@@ -5,8 +5,18 @@ export interface ComputeMessage {
     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`.
@@ -44,6 +54,70 @@ export interface InvokeBedrockResult {
     /** Audit log id for traceability. */
     readonly auditId: string;
 }
+/**
+ * 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 ComputeNamespaceDeps {
     readonly auth: AithosAuth;
     readonly appDid: string;
@@ -88,5 +162,25 @@ export declare class ComputeNamespace {
      *   `mandate_revoked`, `insufficient_credits`, …).
      */
     invokeBedrock(args: InvokeBedrockArgs): Promise<InvokeBedrockResult>;
+    /**
+     * 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>;
 }
 //# sourceMappingURL=compute.d.ts.map

package/dist/src/compute.js

@@ -60,46 +60,13 @@ export class ComputeNamespace {
      *   `mandate_revoked`, `insufficient_credits`, …).
      */
     async invokeBedrock(args) {
-        const { auth, appDid, endpoints, fetch: fetchImpl } = this.#deps;
-        const owner = auth._getOwnerSigners();
-        const ownerLoaded = owner !== null && !owner.destroyed;
-        let choice;
-        if (ownerLoaded) {
-            const publicKp = ownerKeyPair(owner, "public");
-            choice = {
-                kind: "owner",
-                iss: owner.did,
-                verificationMethod: `${owner.did}#public`,
-                signer: publicKp,
-                mandate: undefined,
-            };
-        }
-        else {
-            // Delegate-only path. Find a session whose mandate id matches.
-            const actor = auth._getDelegateActor(args.mandateId);
-            if (!actor || actor.destroyed) {
-                throw new AithosSDKError("sdk_no_delegate_for_mandate", `no owner signed in and no imported delegate mandate matches '${args.mandateId}'. Sign in as an owner, or import a delegate bundle for that mandate via auth.importMandate.`);
-            }
-            const kp = delegateKeyPair(actor);
-            choice = {
-                kind: "delegate",
-                iss: actor.subjectDid,
-                verificationMethod: actor.granteePubkeyMultibase,
-                signer: kp,
-                // The DelegateActor stores the SignedMandate as a structurally
-                // opaque object so the SDK doesn't have to import the
-                // protocol-client type at the storage boundary. Round-trip
-                // through `unknown` for the TS cast — at runtime the bytes are
-                // the canonical SignedMandate the bundle parser already
-                // validated.
-                mandate: actor.mandate,
-            };
-        }
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
         const url = computeInvokeUrl(endpoints);
         const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
         const params = {
-            app_did: appDid,
-            mandate_id: args.mandateId,
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
             model: args.model,
             messages: args.messages,
             idempotency_key: idempotencyKey,
@@ -110,10 +77,152 @@ export class ComputeNamespace {
             params.max_tokens = args.maxTokens;
         if (args.temperature !== undefined)
             params.temperature = args.temperature;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * 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
+     */
+    async invokeImage(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        // Default is Imagen 4 since alpha.17 — flat-illustration style is
+        // the right match for brand-mascot use cases. FLUX Pro 1.1 remains
+        // available via explicit `model: "image:flux-pro-1.1"`.
+        const model = args.model ?? "image:imagen-4";
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            model,
+            prompt: args.prompt,
+            idempotency_key: idempotencyKey,
+        };
+        if (args.negativePrompt !== undefined)
+            params.negative_prompt = args.negativePrompt;
+        if (args.aspectRatio !== undefined)
+            params.aspect_ratio = args.aspectRatio;
+        if (args.seed !== undefined)
+            params.seed = args.seed;
+        if (args.numberOfImages !== undefined)
+            params.number_of_images = args.numberOfImages;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_invoke_image",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
+    /**
+     * Resolve the active signer (owner takes precedence over delegate).
+     *
+     * - When an owner is signed in: returns the owner-signer regardless
+     *   of `mandateId` (the proxy ignores params.mandate_id on
+     *   owner-signed envelopes, so owners can omit it).
+     * - When delegate-only: requires `mandateId` to find the matching
+     *   imported bundle. Throws `sdk_no_delegate_for_mandate` if absent
+     *   or no match.
+     */
+    #resolveSigner(mandateId) {
+        const { auth } = this.#deps;
+        const owner = auth._getOwnerSigners();
+        const ownerLoaded = owner !== null && !owner.destroyed;
+        if (ownerLoaded) {
+            const publicKp = ownerKeyPair(owner, "public");
+            return {
+                kind: "owner",
+                iss: owner.did,
+                verificationMethod: `${owner.did}#public`,
+                signer: publicKp,
+                mandate: undefined,
+            };
+        }
+        if (mandateId === undefined || mandateId.length === 0) {
+            throw new AithosSDKError("sdk_no_signer", "no owner signed in and no mandateId provided — pass a mandateId for a delegate session, or sign in as an owner first.");
+        }
+        const actor = auth._getDelegateActor(mandateId);
+        if (!actor || actor.destroyed) {
+            throw new AithosSDKError("sdk_no_delegate_for_mandate", `no owner signed in and no imported delegate mandate matches '${mandateId}'. Sign in as an owner, or import a delegate bundle for that mandate via auth.importMandate.`);
+        }
+        const kp = delegateKeyPair(actor);
+        return {
+            kind: "delegate",
+            iss: actor.subjectDid,
+            verificationMethod: actor.granteePubkeyMultibase,
+            signer: kp,
+            // The DelegateActor stores the SignedMandate as a structurally
+            // opaque object so the SDK doesn't have to import the
+            // protocol-client type at the storage boundary. Round-trip
+            // through `unknown` for the TS cast — at runtime the bytes are
+            // the canonical SignedMandate the bundle parser already
+            // validated.
+            mandate: actor.mandate,
+        };
+    }
+    /**
+     * Resolve the `mandate_id` value the SDK writes into the JSON-RPC
+     * params for the wire. The proxy requires this field to be a
+     * non-empty string but only consults it for the delegate path —
+     * for owner-signed envelopes it's audit-log metadata, with no
+     * security implication.
+     *
+     * Strategy:
+     *   - Caller-provided id always wins (owner who wants to attribute
+     *     to a specific minted mandate can still pass it).
+     *   - Delegate path: the choice carries the real mandate.id — use it
+     *     so a delegate cannot accidentally lie about which mandate
+     *     it claims to spend under.
+     *   - Owner path with no explicit id: use the owner DID followed
+     *     by `#self` — a stable sentinel that's unambiguously not a
+     *     real mandate id (mandate ids are ULIDs).
+     */
+    #resolveMandateIdForWire(explicit, choice) {
+        if (explicit && explicit.length > 0)
+            return explicit;
+        if (choice.kind === "delegate")
+            return choice.mandate.id;
+        // Owner-direct sentinel. The proxy never inspects this value
+        // beyond non-empty-string validation when no mandate is attached.
+        return `${choice.iss}#self`;
+    }
+    /**
+     * Sign the params with the resolved signer and POST a JSON-RPC
+     * request. Shared between `invokeBedrock` and `invokeImage` — the
+     * only difference between those two is the method name and the
+     * params shape; the envelope construction + transport + error
+     * mapping is identical.
+     */
+    async #signAndPost(opts) {
+        const { url, method, params, choice, fetchImpl, signal } = opts;
         const envelope = buildSignedEnvelope({
             iss: choice.iss,
             aud: url,
-            method: "aithos.compute_invoke",
+            method,
             verificationMethod: choice.verificationMethod,
             params,
             signer: choice.signer,
@@ -126,11 +235,11 @@ export class ComputeNamespace {
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({
                     jsonrpc: "2.0",
-                    id: "aithos.compute_invoke",
-                    method: "aithos.compute_invoke",
+                    id: method,
+                    method,
                     params: { ...params, _envelope: envelope },
                 }),
-                ...(args.signal ? { signal: args.signal } : {}),
+                ...(signal ? { signal } : {}),
             });
         }
         catch (e) {

package/dist/src/index.d.ts

@@ -1,11 +1,11 @@
-export declare const VERSION = "0.1.0-alpha.5";
+export declare const VERSION = "0.1.0-alpha.17";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
 export { AithosRpcError } from "@aithos/protocol-client";
 export type { AithosSdkEndpoints } from "./endpoints.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
-export type { ComputeMessage, InvokeBedrockArgs, InvokeBedrockResult, StopReason, } from "./compute.js";
+export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs, InvokeBedrockResult, InvokeImageArgs, InvokeImageImage, InvokeImageResult, StopReason, } from "./compute.js";
 export { ComputeNamespace } from "./compute.js";
 export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
 export { WalletNamespace } from "./wallet.js";

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.5";
+export const VERSION = "0.1.0-alpha.17";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.17",
   "description": "Aithos SDK — high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",
@@ -39,15 +39,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc",
-    "build:test": "tsc -p tsconfig.test.json",
-    "check-types": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
-    "test": "npm run clean && npm run build && npm run build:test && cd dist && node --test",
-    "test:watch": "cd dist && node --test --watch",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build && npm test"
-  },
   "engines": {
     "node": ">=20"
   },
@@ -63,5 +54,13 @@
   "publishConfig": {
     "access": "public",
     "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "check-types": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "npm run clean && npm run build && npm run build:test && cd dist && node --test",
+    "test:watch": "cd dist && node --test --watch",
+    "clean": "rm -rf dist"
   }
-}
+}