@alienplatform/ai-gateway 3.3.0-dev.0d4f932037814a854d56a7e4e82a8a34cc2e35cb

package/dist/binding.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Parsing for the `ALIEN_<NAME>_BINDING` env var an `ai` resource projects. The client only
+ * routes on the binding: a BYO-key (`external`) binding is validated strictly here because the
+ * client itself uses its fields, while every other service tag — the ambient variants, including
+ * ones added to the platform after this SDK shipped — is passed through for the Rust gateway to
+ * validate and serve. Mirrors the Rust `AiBinding` (serde tag "service", lowercase, camelCase
+ * fields).
+ */
+import * as z from "zod/v4";
+declare const externalAiBindingSchema: z.ZodObject<{
+    service: z.ZodLiteral<"external">;
+    provider: z.ZodString;
+    apiKey: z.ZodString;
+}, z.core.$strict>;
+export type ExternalAiBinding = z.infer<typeof externalAiBindingSchema>;
+/** A binding served by the gateway; `service` may be a variant this SDK predates. */
+export interface AmbientAiBinding {
+    service: string;
+    [key: string]: unknown;
+}
+export type AiBinding = ExternalAiBinding | AmbientAiBinding;
+/** Narrow an `AiBinding` to the BYO-key variant the client handles itself. */
+export declare function isExternalAiBinding(binding: AiBinding): binding is ExternalAiBinding;
+/** The env var an `ai` binding is projected into: `ALIEN_<NAME>_BINDING` (uppercased, `-`→`_`). */
+export declare function aiBindingEnvVarName(name: string): string;
+/** Parse `ALIEN_<NAME>_BINDING`, or `undefined` if it is not set. Throws on malformed content. */
+export declare function parseAiBinding(name: string): Promise<AiBinding | undefined>;
+export {};
+//# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAA;AAI3B,QAAA,MAAM,uBAAuB;;;;kBAMlB,CAAA;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,MAAM,SAAS,GAAG,iBAAiB,GAAG,gBAAgB,CAAA;AAE5D,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,IAAI,iBAAiB,CAEpF;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,kGAAkG;AAClG,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAgCjF"}

package/dist/client.d.ts

@@ -0,0 +1,132 @@
+/**
+ * AI binding — a thin OpenAI-compatible client to the workload's AI gateway.
+ *
+ * For an ambient-cloud binding the gateway process is started on the first call; for a
+ * BYO-key (External) binding the client talks to the provider directly. Either way the client
+ * only forwards OpenAI-shaped requests and streams responses back — it holds no ambient
+ * credentials and rewrites nothing (the gateway rewrites the model id and injects the
+ * credential).
+ */
+import type { ChatCompletion, ChatCompletionChunk } from "openai/resources/chat/completions";
+import type { Response as OpenAIResponse, ResponseStreamEvent } from "openai/resources/responses/responses";
+import type { Gateway } from "./gateway.js";
+export interface ChatCompletionCreateParams {
+    model: string;
+    messages: Array<{
+        role: string;
+        content: string | object;
+    }>;
+    stream?: boolean;
+    [key: string]: unknown;
+}
+export interface ResponseCreateParams {
+    model: string;
+    input: string | Array<{
+        role: string;
+        content: string;
+    }>;
+    stream?: boolean;
+    [key: string]: unknown;
+}
+/** One model the gateway exposes for this binding's cloud. */
+export interface AiModel {
+    /** The id passed to `chat.completions.create` / `responses.create`. */
+    id: string;
+    /** The model's publisher, e.g. "openai", "anthropic", "google". */
+    provider: string;
+    /** A human label for a model picker, e.g. "Claude Opus 4.8". */
+    displayName: string;
+}
+/**
+ * OpenAI-compatible chat-completions surface, typed so a non-streaming call
+ * resolves to a full {@link ChatCompletion} and a streaming call to an
+ * async-iterable of {@link ChatCompletionChunk}; the caller reads
+ * `.choices[0].message.content` (or iterates chunks) with no cast.
+ */
+export interface ChatCompletionsApi {
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }): Promise<ChatCompletion>;
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }): Promise<AsyncIterable<ChatCompletionChunk>>;
+}
+/** OpenAI-compatible Responses surface (the API Codex speaks), typed like above. */
+export interface ResponsesApi {
+    create(params: ResponseCreateParams & {
+        stream?: false;
+    }): Promise<OpenAIResponse>;
+    create(params: ResponseCreateParams & {
+        stream: true;
+    }): Promise<AsyncIterable<ResponseStreamEvent>>;
+}
+/** Resolution shared by `ai()` and `getAiConnection()`. `baseUrl` is the root (no `/v1`);
+ * `apiKey`/`staticModels` are set only for a BYO-key (External) provider. */
+export interface ResolvedAiBinding {
+    baseUrl: string;
+    apiKey?: string;
+    staticModels?: AiModel[];
+}
+/**
+ * Resolve `ALIEN_<NAME>_BINDING` to a connection target. External -> the provider directly with
+ * the projected key. Any other service tag (the ambient variants, including ones this SDK
+ * predates) -> the in-process Rust gateway, started here on demand, which validates the binding
+ * and injects the ambient cloud credential. Backs both `ai()` and `getAiConnection()`.
+ *
+ * The returned `baseUrl` is the root without `/v1` — the gateway serves
+ * `/<segment>/v1/...`, and the client appends the versioned paths itself.
+ */
+export declare function resolveAiBinding(gateway: Gateway, name: string): Promise<ResolvedAiBinding>;
+/**
+ * Constructed by the `ai(name)` factory; resolves the binding (and starts the
+ * gateway, for ambient) once on first use.
+ *
+ * @example
+ * ```typescript
+ * import { ai } from "@alienplatform/sdk"
+ *
+ * const llm = ai("my-llm")
+ * const response = await llm.chat.completions.create({
+ *   model: "claude-opus-4.8",
+ *   messages: [{ role: "user", content: "Hello!" }],
+ * })
+ * ```
+ */
+export declare class Ai {
+    private readonly resolve;
+    private connectionPromise;
+    /** OpenAI-compatible chat namespace. */
+    readonly chat: {
+        completions: ChatCompletionsApi;
+    };
+    /** OpenAI-compatible Responses API namespace (the surface Codex speaks). */
+    readonly responses: ResponsesApi;
+    constructor(resolve: () => Promise<ResolvedAiBinding>);
+    private connection;
+    /** List the models the gateway exposes for this binding's cloud. */
+    getAvailableModels(): Promise<AiModel[]>;
+    private _chatCompletionsCreate;
+    private _responsesCreate;
+    private _postSurface;
+    private _fetch;
+}
+/**
+ * A resolved AI connection for a plain OpenAI-compatible client: the base URL, plus an
+ * optional bearer key. `apiKey` is set for a BYO-key (External) provider and omitted for
+ * ambient-cloud bindings, where the embedded gateway injects the credential.
+ */
+export interface AiConnection {
+    baseURL: string;
+    apiKey?: string;
+}
+/** The app-facing AI client surface, shared by the lazy-loading and static-embed entries. */
+export interface AiClient {
+    ai(name: string): Ai;
+    getAiConnection(name: string): Promise<AiConnection>;
+}
+/**
+ * Build the `ai()` / `getAiConnection()` pair over a gateway. Mirrors `createGateway`:
+ * each entry wires its own addon acquisition and shares this implementation.
+ */
+export declare function createAiClient(gateway: Gateway): AiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Typed errors for the AI client surface (`ai()` / `getAiConnection`).
+ *
+ * Defined here rather than in `@alienplatform/bindings` because the AI binding
+ * resolves through this package's gateway process, not the bindings native addon.
+ */
+import * as z from "zod/v4";
+export { BindingNotFoundError, InvalidBindingConfigError } from "@alienplatform/core";
+/**
+ * Error thrown when an upstream LLM endpoint returns a non-2xx response.
+ *
+ * Marked internal because the response body and upstream URL may contain
+ * provider-specific infra detail not intended for external clients.
+ * Retryability is derived per-call from the HTTP status code.
+ */
+export declare const AiUpstreamError: {
+    metadata: import("@alienplatform/core").AlienErrorMetadata<z.ZodObject<{
+        url: z.ZodString;
+        status: z.ZodNumber;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+    contextSchema: z.ZodObject<{
+        url: z.ZodString;
+        status: z.ZodNumber;
+        message: z.ZodString;
+    }, z.core.$strip>;
+    create: (context: {
+        url: string;
+        status: number;
+        message: string;
+    }) => import("@alienplatform/core").AlienErrorDefinition<z.ZodObject<{
+        url: z.ZodString;
+        status: z.ZodNumber;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+};
+/**
+ * Error thrown when a network-level failure occurs before or after an
+ * upstream LLM request (fetch threw, or the success body was not parseable JSON).
+ * These are always transient and safe to retry.
+ */
+export declare const AiTransportError: {
+    metadata: import("@alienplatform/core").AlienErrorMetadata<z.ZodObject<{
+        url: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    contextSchema: z.ZodObject<{
+        url: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>;
+    create: (context: {
+        url: string;
+        reason: string;
+    }) => import("@alienplatform/core").AlienErrorDefinition<z.ZodObject<{
+        url: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+};
+/**
+ * Error thrown when a BYO-key binding names a provider the client has no base URL for.
+ * External (the developer set a bad `provider` tag) and not retryable — failing closed
+ * here stops the projected BYO key from being shipped to the wrong provider's endpoint.
+ */
+export declare const UnsupportedProviderError: {
+    metadata: import("@alienplatform/core").AlienErrorMetadata<z.ZodObject<{
+        provider: z.ZodString;
+        supported: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    contextSchema: z.ZodObject<{
+        provider: z.ZodString;
+        supported: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    create: (context: {
+        provider: string;
+        supported: string[];
+    }) => import("@alienplatform/core").AlienErrorDefinition<z.ZodObject<{
+        provider: z.ZodString;
+        supported: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+};
+/**
+ * Error thrown when a binding's upstream serves chat/completions but not the OpenAI Responses
+ * API. Anthropic's OpenAI-compatible host is the case in point: `/v1/chat/completions` works,
+ * `/v1/responses` 404s. External (a caller usage error), not retryable.
+ */
+export declare const ResponsesApiUnsupportedError: {
+    metadata: import("@alienplatform/core").AlienErrorMetadata<z.ZodObject<{
+        provider: z.ZodString;
+    }, z.core.$strip>>;
+    contextSchema: z.ZodObject<{
+        provider: z.ZodString;
+    }, z.core.$strip>;
+    create: (context: {
+        provider: string;
+    }) => import("@alienplatform/core").AlienErrorDefinition<z.ZodObject<{
+        provider: z.ZodString;
+    }, z.core.$strip>>;
+};
+/**
+ * Error thrown when this platform/architecture has no prebuilt gateway binary.
+ */
+export declare const UnsupportedPlatformError: {
+    metadata: import("@alienplatform/core").AlienErrorMetadata<z.ZodObject<{
+        platform: z.ZodString;
+        arch: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    contextSchema: z.ZodObject<{
+        platform: z.ZodString;
+        arch: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    create: (context: {
+        platform: string;
+        arch: string;
+        reason?: string | undefined;
+    }) => import("@alienplatform/core").AlienErrorDefinition<z.ZodObject<{
+        platform: z.ZodString;
+        arch: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};
+/**
+ * Error thrown when the `alien-ai-gateway` executable cannot be located (or, for a
+ * compiled Worker, extracted) for this platform. Internal because the context
+ * carries filesystem paths.
+ */
+export declare const GatewayBinaryUnavailableError: {
+    metadata: import("@alienplatform/core").AlienErrorMetadata<z.ZodObject<{
+        triple: z.ZodString;
+        reason: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    contextSchema: z.ZodObject<{
+        triple: z.ZodString;
+        reason: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    create: (context: {
+        triple: string;
+        reason: string;
+        path?: string | undefined;
+    }) => import("@alienplatform/core").AlienErrorDefinition<z.ZodObject<{
+        triple: z.ZodString;
+        reason: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+};
+/**
+ * Error thrown when the spawned `alien-ai-gateway` process failed to report a
+ * ready URL: it exited early or errored on startup. Retryable because the common
+ * cause (an ambient cloud credential not yet resolvable) is transient.
+ */
+export declare const GatewayStartFailedError: {
+    metadata: import("@alienplatform/core").AlienErrorMetadata<z.ZodObject<{
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    contextSchema: z.ZodObject<{
+        reason: z.ZodString;
+    }, z.core.$strip>;
+    create: (context: {
+        reason: string;
+    }) => import("@alienplatform/core").AlienErrorDefinition<z.ZodObject<{
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAA;AAG3B,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAA;AAErF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;CAY1B,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;CAU3B,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;CAWnC,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;CAUvC,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;CAYnC,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;CAaxC,CAAA;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;CASlC,CAAA"}

package/dist/gateway.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The gateway surface: obtain the loopback URL of the Alien AI gateway.
+ *
+ * Two paths, unified behind {@link Gateway.startAiGateway}:
+ *   - A container launcher already started the gateway out of band and exec'd the
+ *     app with `ALIEN_AI_GATEWAY_URL` set, so we use that URL directly.
+ *   - Otherwise (an SDK Worker) we spawn the `alien-ai-gateway` binary ourselves,
+ *     read the URL it prints, and keep the child alive for the process lifetime.
+ *
+ * Parameterized over how the binary is resolved so the lazy entry (`index.ts`) and
+ * the compiled-embed entry (`native.ts`) share one implementation.
+ */
+import { type RawAiGatewayHandle } from "./loader.js";
+export interface Gateway {
+    startAiGateway(): Promise<RawAiGatewayHandle>;
+}
+export declare function createGateway(resolveBinary: () => Promise<string>): Gateway;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAAE,KAAK,kBAAkB,EAAkB,MAAM,aAAa,CAAA;AAOrE,MAAM,WAAW,OAAO;IACtB,cAAc,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAC9C;AAED,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAqB3E"}