@fgv/ts-extras 5.1.0-16 → 5.1.0-17

package/lib/packlets/ai-assist/apiClient.d.ts

@@ -1,5 +1,5 @@
 import { type Logging, Result } from '@fgv/ts-utils';
-import { AiPrompt, type AiServerToolConfig, type IAiCompletionResponse, type IAiProviderDescriptor, type IChatMessage, type ModelSpec } from './model';
+import { AiPrompt, type AiModelCapability, type AiServerToolConfig, type IAiCompletionResponse, type IAiImageGenerationParams, type IAiImageGenerationResponse, type IAiModelCapabilityConfig, type IAiModelInfo, type IAiProviderDescriptor, type IChatMessage, type ModelSpec } from './model';
 /**
  * Parameters for a provider completion request.
  * @public
@@ -24,6 +24,8 @@ export interface IProviderCompletionParams {
     readonly logger?: Logging.ILogger;
     /** Server-side tools to include in the request. Overrides settings-level tool config when provided. */
     readonly tools?: ReadonlyArray<AiServerToolConfig>;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
 }
 /**
  * Calls the appropriate chat completion API for a given provider.
@@ -43,6 +45,86 @@ export interface IProviderCompletionParams {
  * @public
  */
 export declare function callProviderCompletion(params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
+/**
+ * Parameters for an image-generation request.
+ * @public
+ */
+export interface IProviderImageGenerationParams {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /** The image-generation request */
+    readonly params: IAiImageGenerationParams;
+    /** Optional model override — string or context-aware map (uses descriptor.defaultModel.image otherwise) */
+    readonly modelOverride?: ModelSpec;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Calls the appropriate image-generation API for a given provider.
+ *
+ * Routes based on `descriptor.imageApiFormat`:
+ * - `'openai-images'` for OpenAI (DALL-E, gpt-image-1)
+ * - `'xai-images'` for xAI Grok image models
+ * - `'gemini-imagen'` for Google Imagen
+ *
+ * Image-model selection reuses the existing `'image'` {@link ModelSpecKey}.
+ *
+ * @param params - Request parameters including descriptor, API key, and prompt
+ * @returns The generated images, or a failure
+ * @public
+ */
+export declare function callProviderImageGeneration(params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
+/**
+ * Parameters for a list-models request.
+ * @public
+ */
+export interface IProviderListModelsParams {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /** Optional capability filter; when set, only models declaring this capability are returned. */
+    readonly capability?: AiModelCapability;
+    /** Optional capability config override (defaults to {@link DEFAULT_MODEL_CAPABILITY_CONFIG}). */
+    readonly capabilityConfig?: IAiModelCapabilityConfig;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Lists models available from a provider, with capabilities resolved from
+ * native provider info (where supplied) and a configurable rule set.
+ *
+ * Routes based on `descriptor.apiFormat` — listing reuses the existing
+ * format dispatch and does not require a separate descriptor field.
+ *
+ * @param params - Request parameters including descriptor, API key, and optional capability filter
+ * @returns The resolved model list, or a failure
+ * @public
+ */
+export declare function callProviderListModels(params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
+/**
+ * Calls the model-listing endpoint on a proxy server.
+ *
+ * @remarks
+ * Proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/list-models`
+ * - Request body: `{providerId, apiKey, capability?}`. Capability config is
+ *   not forwarded — the proxy applies its own (typically the same default
+ *   the library ships).
+ * - Success response body: an `IAiModelInfo[]` (under key `models`) where
+ *   `capabilities` is serialized as a string array (not Set, which doesn't
+ *   round-trip through JSON).
+ * - Error response body: `{error: string}`, surfaced as `proxy: ${error}`.
+ *
+ * @public
+ */
+export declare function callProxiedListModels(proxyUrl: string, params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
 /**
  * Calls the AI completion endpoint on a proxy server instead of calling
  * the provider API directly from the browser.
@@ -57,4 +139,24 @@ export declare function callProviderCompletion(params: IProviderCompletionParams
  * @public
  */
 export declare function callProxiedCompletion(proxyUrl: string, params: IProviderCompletionParams): Promise<Result<IAiCompletionResponse>>;
+/**
+ * Calls the image-generation endpoint on a proxy server instead of calling
+ * the provider API directly from the browser.
+ *
+ * @remarks
+ * The proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/image-generation`
+ * - Request body: `{providerId, apiKey, params, modelOverride?}`
+ * - Success response body: an {@link IAiImageGenerationResponse}
+ * - Error response body: `{error: string}` (surfaced as `proxy: ${error}`)
+ *
+ * The proxy server is responsible for descriptor lookup, model resolution,
+ * provider dispatch, and response normalization.
+ *
+ * @param proxyUrl - Base URL of the proxy server (e.g. `http://localhost:3001`)
+ * @param params - Same parameters as {@link callProviderImageGeneration}
+ * @returns The generated images, or a failure
+ * @public
+ */
+export declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
 //# sourceMappingURL=apiClient.d.ts.map