@econ-v1/app-sdk 5.24.0 → 5.26.0

package/dist/llm/ApiStoreClient.d.ts

@@ -0,0 +1,57 @@
+/**
+ * TypeScript consumer SDK client for the public api-store LLM endpoint
+ * (feature 472).
+ *
+ * Wraps the host's `/api/v2/public/api_store/llm/{call,stream}` endpoints
+ * with a typed surface that threads the `route` field (LlmRoute) through
+ * every call method and surfaces the structured 400 body as typed errors.
+ *
+ * This client is dependency-injection-friendly: the constructor takes a
+ * `fetcher` callback so applications can plug in their existing `apiClient`
+ * singleton (which already handles JWT auth, token refresh, and L402
+ * payment cycles) without the SDK reaching into application HTTP plumbing
+ * directly.
+ *
+ * **Honest framing reminder** (S5/U4): `route: "private"` isolates the
+ * upstream provider's API credentials and routes egress through a separate
+ * device — it does NOT mask prompt contents from the upstream provider or
+ * anonymize the user.
+ */
+import { PrivateUnavailableError, InvalidRouteModeCombinationError } from "./errors";
+import type { ExecuteBestModelRequest, ExecuteChatRequest, ExecuteChatResponse, ExecuteRequest, LlmRoute, StreamChatChunk, StreamChatRequest } from "./types";
+/**
+ * Minimal fetcher interface — narrow enough that the project's existing
+ * `apiClient` satisfies it directly. The fetcher MUST throw for non-2xx
+ * responses with the raw body attached as `error.body` so the SDK can
+ * decode the structured 400 shapes.
+ */
+export interface ApiStoreFetcher {
+    post<TIn, TOut>(path: string, body: TIn): Promise<TOut>;
+    /**
+     * Streaming POST — returns an async iterable of parsed chunks. The
+     * fetcher owns the SSE parser; the SDK only orchestrates request shape
+     * + error mapping.
+     */
+    postStream<TIn>(path: string, body: TIn): AsyncIterable<StreamChatChunk>;
+}
+/** Consumer client for the public api-store LLM endpoint. */
+export declare class ApiStoreClient {
+    private readonly fetcher;
+    constructor(fetcher: ApiStoreFetcher);
+    /** Unary execute call (single-message). */
+    execute(request: ExecuteRequest): Promise<ExecuteChatResponse>;
+    /** Unary execute_chat call. */
+    executeChat(request: ExecuteChatRequest): Promise<ExecuteChatResponse>;
+    /** Unary execute_best_model call. */
+    executeBestModel(request: ExecuteBestModelRequest): Promise<ExecuteChatResponse>;
+    /**
+     * Streaming chat call. Yields chunks in order; the final chunk is always
+     * either an `end` event (carrying execution_route + token usage + cost) or
+     * an `error` event (FR-016 / S3 invariant — no silent fallback to direct
+     * provider). Consumers MUST handle the `error` variant explicitly.
+     */
+    streamChat(request: StreamChatRequest): AsyncGenerator<StreamChatChunk, void, void>;
+    private callWithRoute;
+}
+export { PrivateUnavailableError, InvalidRouteModeCombinationError };
+export type { ExecuteBestModelRequest, ExecuteChatRequest, ExecuteChatResponse, ExecuteRequest, LlmRoute, StreamChatChunk, StreamChatRequest, };

package/dist/llm/errors.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Typed errors for the public api-store LLM endpoint (feature 472).
+ *
+ * Resolves UI finding U1: applications need a typed, pattern-matchable error
+ * for the structured 400 body produced when `route: "private"` cannot be
+ * honoured on the selected executor.
+ *
+ * The host emits the canonical body shape (see OpenAPI contract):
+ *   {
+ *     "code": "api_store.private_unavailable",
+ *     "requested_route": "private",
+ *     "reason": "no_esp32_endpoint" | "firmware_upgrade_required" | …,
+ *     "fallback_available": true | false
+ *   }
+ *
+ * `apiClient` errors with `code === "api_store.private_unavailable"` are
+ * mapped to a [[PrivateUnavailableError]] instance via [[mapApiErrorBody]].
+ */
+import type { LlmRoute, PrivateUnavailableReason } from "./types";
+/** Wire shape of the structured 400 body. */
+export interface PrivateUnavailableBody {
+    code: "api_store.private_unavailable";
+    requested_route: "private";
+    reason: PrivateUnavailableReason;
+    fallback_available: boolean;
+}
+/** Wire shape of the route_mode + execution_preference rejection body. */
+export interface InvalidRouteModeCombinationBody {
+    code: "api_store.invalid_route_mode_combination";
+    route_mode: LlmRoute;
+    execution_preference?: string;
+    hint: string;
+}
+/**
+ * Thrown by the SDK when the host rejects a `route: "private"` request
+ * because the selected executor has no custodial-hardware path (or its
+ * firmware is too old, the peer is offline, or the platform is not enabled
+ * by the operator).
+ *
+ * Catch this specifically to either:
+ *  - retry with `route: "auto"` (the `fallback_available` field is true when
+ *    the host believes a public-path fallback would succeed), or
+ *  - surface a precise message to the user explaining which condition
+ *    blocked the private path.
+ *
+ * **Honest framing reminder**: Even when the call succeeds with
+ * `route: "private"`, the prompt contents are not masked from the upstream
+ * provider — privacy is about credential isolation and egress device, not
+ * payload secrecy.
+ */
+export declare class PrivateUnavailableError extends Error {
+    readonly code: "api_store.private_unavailable";
+    readonly reason: PrivateUnavailableReason;
+    readonly fallback_available: boolean;
+    constructor(body: PrivateUnavailableBody);
+}
+/**
+ * Thrown by the SDK when `route` + `execution_preference` form a rejected
+ * combination per the Routing Truth Table in `data-model.md §4`.
+ */
+export declare class InvalidRouteModeCombinationError extends Error {
+    readonly code: "api_store.invalid_route_mode_combination";
+    readonly route_mode: LlmRoute;
+    readonly execution_preference?: string;
+    readonly hint: string;
+    constructor(body: InvalidRouteModeCombinationBody);
+}
+/**
+ * Map a 400 response body (already JSON-parsed) into the typed SDK error
+ * variant, or return `null` to let the caller fall through to the generic
+ * `ApiError` path.
+ *
+ * Used by [[ApiStoreClient]] inside its 400 branch so applications can
+ * `catch (e) { if (e instanceof PrivateUnavailableError) … }` without
+ * having to introspect the wire body themselves.
+ */
+export declare function mapApiErrorBody(body: unknown): Error | null;

package/dist/llm/types.d.ts

@@ -0,0 +1,158 @@
+/**
+ * TypeScript consumer SDK types for the public api-store LLM endpoint
+ * (feature 472 — public/private LLM proxy routing).
+ *
+ * These types intentionally cover ONLY the surface introduced by feature 472:
+ * the `LlmRoute` enum, the `route` / `executionRoute` / `viaNodeId` fields, and
+ * the corresponding additions to the four LLM request/response shapes. They
+ * are exported so applications consuming the api-store endpoint can stay
+ * type-safe end-to-end.
+ *
+ * The wire form follows the OpenAPI contract at
+ * `specs/472-public-private-llm-proxy/contracts/public_api_store_llm.yaml`:
+ *
+ *   request:  { …, "route_mode": "auto" | "public" | "private" }
+ *   response: { …, "execution_route": "public" | "private", "via_node_id": "…" }
+ *
+ * Existing snake_case fields are preserved; in TypeScript-land we map them to
+ * the snake_case names used over the wire (no auto-camelCasing in the SDK).
+ *
+ * **Honest framing** (security finding S5 / U4, surfaced via JSDoc on
+ * `LlmRoute`): Private mode isolates the upstream provider's API credentials
+ * on the peer's host and routes egress through a separate device; it does NOT
+ * mask prompt contents from the upstream provider or anonymize the user.
+ */
+/**
+ * Consumer-expressed routing intent for an LLM call.
+ *
+ * - `"public"` — force direct provider execution; skip the custodial-hardware
+ *   hop even on peers that have it configured.
+ * - `"private"` — force routing through the custodial-hardware path. Returns
+ *   a typed `PrivateUnavailableError` when no hardware path is available on
+ *   the selected executor.
+ * - `"auto"` — default; pick the more-isolated path when available, never
+ *   hard-fail because of routing.
+ *
+ * **Honest framing**: Private mode isolates the upstream provider's API
+ * credentials on the peer's host and routes egress through a separate device;
+ * it does NOT mask prompt contents from the upstream provider or anonymize
+ * the user.
+ */
+export type LlmRoute = "auto" | "public" | "private";
+/**
+ * Truthful echo of what actually executed the call. Never `"auto"` — the
+ * service resolves auto-intent at the endpoint layer and reports the
+ * concrete path used in the response.
+ */
+export type ExecutionRoute = "public" | "private";
+/**
+ * Reason the peer rejected a `route_mode=private` request. Surfaced via
+ * `PrivateUnavailableError.reason` in `./errors.ts`.
+ */
+export type PrivateUnavailableReason = "no_esp32_endpoint" | "firmware_upgrade_required" | "peer_offline" | "platform_not_enabled";
+/**
+ * Local-vs-network preference. Composes with `route` per the Routing Truth
+ * Table in `data-model.md §4`.
+ */
+export type ExecutionPreference = "prefer_local" | "local_only" | "network_only";
+/**
+ * Shared shape carried by every public api-store LLM call/stream request.
+ * Applications wrap their own input shape around this and submit it via
+ * `ApiStoreClient` — see `./ApiStoreClient.ts`.
+ *
+ * **JSDoc honest-framing reminder**: `route: "private"` does NOT mask prompt
+ * contents from the upstream provider — it only changes which device's
+ * credentials issue the egress call. Document this in your application UI.
+ */
+export interface ExecuteChatRequest {
+    /** The prompt or chat-style messages. Application-specific shape. */
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    /** Platform name, e.g. "OpenAI", "Anthropic". */
+    platform?: string;
+    /** Model name, e.g. "gpt-4o", "claude-3-5-sonnet-20240620". */
+    model?: string;
+    /**
+     * Consumer-expressed routing intent. Omit (or set to `"auto"`) to keep the
+     * default behaviour — the peer picks the more-isolated path when available
+     * and falls back to public when not.
+     *
+     * Setting `"private"` MAY return a `PrivateUnavailableError` when the
+     * selected executor has no custodial-hardware path; check
+     * `.fallback_available` on the error and decide whether to retry with
+     * `route: "auto"`.
+     *
+     * **Honest framing**: Private mode isolates the upstream provider's API
+     * credentials on the peer's host and routes egress through a separate
+     * device; it does NOT mask prompt contents from the upstream provider or
+     * anonymize the user.
+     */
+    route?: LlmRoute;
+    /**
+     * Local-vs-network executor preference. Composes with `route` per the
+     * Routing Truth Table.
+     */
+    execution_preference?: ExecutionPreference;
+    /** Correlation id for logs / audit (allowlisted log field per S4). */
+    correlation_id?: string;
+    /** Optional cap on output tokens. */
+    max_output_tokens?: number;
+    /** Optional tool specs (OpenAI-style). Opaque to the SDK. */
+    tools?: unknown;
+    /** Optional tool_choice directive. Opaque to the SDK. */
+    tool_choice?: unknown;
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Optional response_format (e.g., `json_schema`). Opaque to the SDK. */
+    response_format?: unknown;
+}
+/** Streaming variant of [[ExecuteChatRequest]] — structurally identical. */
+export type StreamChatRequest = ExecuteChatRequest;
+/** "best-model" variant — model resolution happens server-side. */
+export interface ExecuteBestModelRequest extends Omit<ExecuteChatRequest, "model"> {
+}
+/** Single-message execute variant. */
+export interface ExecuteRequest extends ExecuteChatRequest {
+}
+/**
+ * Common echo fields appended to every successful public api-store LLM
+ * response. Carries the truthful execution path so the consumer can log it,
+ * retry under different intent, or shape downstream behaviour.
+ */
+export interface RouteExecutionEcho {
+    /**
+     * Truthful echo of which path actually executed the call. Always
+     * `"public"` or `"private"`, never `"auto"`.
+     */
+    execution_route: ExecutionRoute;
+    /** Identifier of the node that executed the call (self or peer). */
+    via_node_id: string;
+}
+/** Unary call response. */
+export interface ExecuteChatResponse extends RouteExecutionEcho {
+    response_text: string;
+    platform: string;
+    model: string;
+    prompt_tokens: number;
+    completion_tokens: number;
+    cost_sats: number;
+    correlation_id?: string;
+}
+/** Streaming chunk. The final chunk MUST carry `RouteExecutionEcho`. */
+export type StreamChatChunk = {
+    type: "delta";
+    text: string;
+} | ({
+    type: "end";
+} & RouteExecutionEcho & {
+    prompt_tokens: number;
+    completion_tokens: number;
+    cost_sats: number;
+    correlation_id?: string;
+}) | {
+    type: "error";
+    code: string;
+    message: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@econ-v1/app-sdk",
-  "version": "5.24.0",
+  "version": "5.26.0",
   "description": "TypeScript SDK for building Node mini-app plugins (Bun runtime) on the Lightning-powered marketplace daemon",
   "license": "MIT OR Apache-2.0",
   "author": "Node contributors",