@sudobility/shapeshyft_engine 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,812 @@
+/**
+ * @sudobility/shapeshyft_engine/types
+ * Product-neutral domain types shared by ShapeShyft and ShapeRouter.
+ *
+ * No runtime imports: frontend packages re-export this module.
+ */
+export type { ApiResponse, BaseResponse, NetworkClient, Optional, PaginatedResponse, PaginationInfo, PaginationOptions, } from '@sudobility/types';
+import type { Optional, BaseResponse } from '@sudobility/types';
+export type LlmProvider = 'openai' | 'anthropic' | 'gemini' | 'mistral' | 'cohere' | 'groq' | 'xai' | 'deepseek' | 'perplexity' | 'lm_studio';
+export type HttpMethod = 'GET' | 'POST';
+/**
+ * Media type for multimodal content
+ */
+export type MediaType = 'image' | 'audio' | 'video';
+/** OpenAI model options (verified 2026-08-18) */
+export type OpenAiModel = 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.5' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-4o' | 'gpt-4o-mini';
+/** Anthropic model options (verified 2026-08-18) */
+export type AnthropicModel = 'claude-fable-5' | 'claude-opus-5' | 'claude-sonnet-5' | 'claude-haiku-4-5' | 'claude-opus-4-8' | 'claude-opus-4-7' | 'claude-opus-4-6' | 'claude-sonnet-4-6' | 'claude-opus-4-5-20251101' | 'claude-sonnet-4-5-20250929';
+/** Google Gemini model options (verified 2026-08-18) */
+export type GeminiModel = 'gemini-3.7-flash' | 'gemini-3.6-flash' | 'gemini-3.5-flash' | 'gemini-3.5-flash-lite' | 'gemini-3.1-flash-lite' | 'gemini-3.1-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-flash-image' | 'gemini-3.1-flash-lite-image' | 'gemini-3-pro-image' | 'gemini-2.5-pro' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-2.5-flash-image' | 'gemini-2.5-flash-native-audio-preview-12-2025' | 'veo-3.1-generate-preview' | 'veo-3.1-lite-generate-preview';
+/** Mistral AI model options (verified 2026-08-18) */
+export type MistralModel = 'mistral-large-latest' | 'mistral-large-2512' | 'mistral-medium-latest' | 'mistral-small-latest' | 'mistral-small-2603' | 'ministral-14b-2512' | 'ministral-8b-2512' | 'ministral-3b-2512' | 'codestral-latest' | 'codestral-2508' | 'mistral-ocr-latest';
+/** Cohere model options (verified 2026-08-18) */
+export type CohereModel = 'command-a-plus-05-2026' | 'command-a-03-2025' | 'command-a-reasoning-08-2025' | 'command-a-vision-07-2025' | 'command-a-translate-08-2025' | 'command-r7b-12-2024' | 'command-r-plus-08-2024' | 'command-r-08-2024';
+/** Groq model options (verified 2026-08-18) */
+export type GroqModel = 'openai/gpt-oss-120b' | 'openai/gpt-oss-20b' | 'qwen/qwen3.6-27b' | 'minimaxai/minimax-m2.7' | 'groq/compound' | 'groq/compound-mini' | 'whisper-large-v3' | 'whisper-large-v3-turbo';
+/** xAI (Grok) model options (verified 2026-08-18) */
+export type XaiModel = 'grok-4.6' | 'grok-4.5' | 'grok-4.3' | 'grok-4.20-0309-reasoning' | 'grok-4.20-0309-non-reasoning' | 'grok-4.20-multi-agent-0309' | 'grok-build-0.1';
+/** DeepSeek model options (verified 2026-08-18) */
+export type DeepSeekModel = 'deepseek-v4-pro' | 'deepseek-v4-flash';
+/** Perplexity model options (verified 2026-08-18) */
+export type PerplexityModel = 'sonar' | 'sonar-pro' | 'sonar-pro-search' | 'sonar-reasoning-pro' | 'sonar-deep-research';
+/** Custom LLM server models (suggested options; any string is valid) */
+export type LlmServerModel = 'qwen3-8b' | 'qwen3-14b' | 'qwen3-30b-a3b' | 'qwen2.5-coder-14b-instruct' | 'mistral-7b-instruct-v0.3' | 'deepseek-r1-distill-qwen-7b' | 'gemma-3-4b-it' | 'gemma-3-12b-it' | 'gemma-3-27b-it' | 'qwen2.5-vl-3b-instruct' | 'qwen2.5-vl-7b-instruct' | 'qwen2.5-vl-32b-instruct' | 'qwen2.5-vl-72b-instruct' | 'glm-4v-9b' | 'pixtral-12b-2409' | 'olmocr-2-7b-1025' | 'janus-pro-7b' | string;
+/** Union of all model types */
+export type LlmModel = OpenAiModel | AnthropicModel | GeminiModel | MistralModel | CohereModel | GroqModel | XaiModel | DeepSeekModel | PerplexityModel | LlmServerModel;
+/** List of available providers */
+export declare const LLM_PROVIDERS: LlmProvider[];
+/**
+ * Mapping of each LLM provider to its known valid model IDs.
+ * Useful for both server-side validation and client-side form validation.
+ *
+ * Note: `lm_studio` has an empty list because it accepts arbitrary
+ * user-supplied model names (any string is valid).
+ */
+export declare const PROVIDER_MODELS: Record<LlmProvider, readonly string[]>;
+/**
+ * Check whether a model ID is valid for the given provider.
+ * For `lm_studio`, any string is valid (returns true) since users
+ * can run arbitrary models on their local server.
+ *
+ * @param provider - The LLM provider to validate against
+ * @param model - The model ID string to check
+ * @returns true if the model is a known valid model for the provider
+ */
+export declare function isValidModelForProvider(provider: LlmProvider, model: string): boolean;
+/**
+ * Supported media input formats for different providers/models.
+ * - url: HTTP/HTTPS URLs to media files
+ * - base64: Base64-encoded binary data (data URLs)
+ * - gcs: Google Cloud Storage URIs (gs://bucket/path)
+ * - s3: AWS S3 URIs (s3://bucket/key)
+ * - file: Direct file upload (multipart form data)
+ */
+export type MediaInputFormat = 'url' | 'base64' | 'gcs' | 's3' | 'file';
+/**
+ * Media format support configuration for a model.
+ * Specifies which input formats are supported for each media type.
+ */
+export interface MediaFormatSupport {
+    /** Supported formats for image input */
+    imageFormats?: MediaInputFormat[];
+    /** Supported formats for audio input */
+    audioFormats?: MediaInputFormat[];
+    /** Supported formats for video input */
+    videoFormats?: MediaInputFormat[];
+}
+/**
+ * Capabilities for a model's input and output modalities.
+ * undefined = unknown (user's responsibility to verify)
+ * true = supported
+ * false = not supported
+ */
+export interface ModelCapabilities {
+    visionInput?: boolean;
+    audioInput?: boolean;
+    videoInput?: boolean;
+    imageOutput?: boolean;
+    audioOutput?: boolean;
+    videoOutput?: boolean;
+    webSearch?: boolean;
+    mediaFormats?: MediaFormatSupport;
+}
+/**
+ * Media content for LLM input (images, audio, video).
+ * Used to pass media to multimodal models.
+ */
+export interface MediaContent {
+    /** Type of media */
+    type: MediaType;
+    /** Format of the data */
+    format: 'base64' | 'url';
+    /** MIME type (e.g., "image/png", "audio/mp3", "video/mp4") */
+    mimeType: string;
+    /** Base64 data (without prefix) or URL */
+    data: string;
+    /** Original field name from input (for debugging/logging) */
+    fieldName?: string;
+}
+/**
+ * Generated media from LLM output (Imagen, Veo, GPT-4o audio).
+ * Returned when models generate images, audio, or video.
+ */
+export interface GeneratedMedia {
+    /** Type of generated media */
+    type: MediaType;
+    /** MIME type of the generated media */
+    mimeType: string;
+    /** Base64 data or URL depending on output format configuration */
+    data: string;
+}
+/**
+ * Required capabilities detected from a schema
+ */
+export interface RequiredCapabilities {
+    visionInput?: boolean;
+    audioInput?: boolean;
+    videoInput?: boolean;
+    imageOutput?: boolean;
+    audioOutput?: boolean;
+    videoOutput?: boolean;
+}
+/**
+ * Detect required capabilities from input and output schemas.
+ * Returns which media capabilities are required.
+ */
+export declare function detectRequiredCapabilities(inputSchema?: Record<string, unknown> | null, outputSchema?: Record<string, unknown> | null): RequiredCapabilities;
+/**
+ * Model pricing structure with multimodal support.
+ * All costs are in cents.
+ *
+ * Text costs: per 1M tokens
+ * Image costs: per image
+ * Audio costs: per minute
+ * Video costs: per minute
+ */
+export interface ModelPricing {
+    input: number;
+    output: number;
+    imageInput?: number;
+    imageOutput?: number;
+    audioInput?: number;
+    audioOutput?: number;
+    videoInput?: number;
+    videoOutput?: number;
+}
+/**
+ * Multimodal usage input for cost estimation
+ */
+export interface MultimodalUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    imagesInput?: number;
+    imagesOutput?: number;
+    audioInputMinutes?: number;
+    audioOutputMinutes?: number;
+    videoInputMinutes?: number;
+    videoOutputMinutes?: number;
+}
+/**
+ * Estimate cost in cents for token usage (text only)
+ * @param pricing - Model pricing configuration
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ */
+export declare function estimateCost(pricing: ModelPricing, inputTokens: number, outputTokens: number): number;
+/**
+ * Estimate cost in cents for multimodal usage
+ * @param pricing - Model pricing configuration
+ * @param usage - Multimodal usage details
+ */
+export declare function estimateMultimodalCost(pricing: ModelPricing, usage: MultimodalUsage): number;
+/**
+ * Format cost in cents to a readable string (e.g., "$0.0015" or "$1.50")
+ */
+export declare function formatCost(costCents: number): string;
+/**
+ * Format cost per million tokens for display
+ */
+export declare function formatCostPerMillion(pricing: ModelPricing): string;
+export interface JsonSchema {
+    type?: string;
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    description?: string;
+    enum?: (string | number | boolean)[];
+    default?: unknown;
+    format?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    additionalProperties?: boolean | JsonSchema;
+    [key: string]: unknown;
+}
+/**
+ * @description ShapeShyft user account, linked to Firebase Authentication.
+ * Created on first login and referenced by entity membership for multi-tenant access.
+ */
+export interface User {
+    /** Internal database identifier */
+    id: string;
+    /** Firebase Authentication UID -- the primary external identity used to authenticate API requests */
+    firebase_uid: string;
+    /** User email address from Firebase Auth profile (may be null if auth provider omits it) */
+    email: string | null;
+    /** User display name from Firebase Auth profile */
+    display_name: string | null;
+    /** Timestamp when the user record was first created */
+    created_at: Date | null;
+    /** Timestamp of the most recent profile update */
+    updated_at: Date | null;
+}
+/**
+ * @description A ShapeShyft project that groups endpoints under a single API key.
+ * Projects are scoped to an entity and serve as the top-level organizational unit
+ * for managing AI endpoints.
+ */
+export interface Project {
+    /** Unique identifier for this project */
+    uuid: string;
+    /** Entity (organization/personal) that owns this project */
+    entity_id: string;
+    /** URL-safe slug used in API paths (e.g., "my-project") */
+    project_name: string;
+    /** Human-readable project title shown in the UI */
+    display_name: string;
+    /** Optional description of the project's purpose */
+    description: string | null;
+    /** Whether this project is enabled; null treated as true */
+    is_active: boolean | null;
+    /** Truncated prefix of the project API key for display (e.g., "shyft_live_ab..."). Full key is never returned in Project responses. */
+    api_key_prefix: string | null;
+    /** Timestamp when the project API key was last generated or refreshed */
+    api_key_created_at: Date | null;
+    /** Timestamp when this project was created */
+    created_at: Date | null;
+    /** Timestamp of the most recent project update */
+    updated_at: Date | null;
+}
+/**
+ * Configuration for expected media output from an endpoint.
+ * Used to configure models like GPT-4o (audio), Imagen (images), Veo (video).
+ */
+export interface MediaOutputConfig {
+    /** Whether the endpoint expects audio output */
+    audio?: boolean;
+    /** Whether the endpoint expects image output */
+    image?: boolean;
+    /** Whether the endpoint expects video output */
+    video?: boolean;
+}
+/**
+ * @description Endpoint fields common to every product. Products add their provider binding.
+ * Each endpoint defines a specific LLM interaction within a {@link Project}:
+ * the model, schemas, instructions, and access controls. Callers invoke
+ * endpoints via the project's API key.
+ */
+export interface EndpointBase {
+    /** Unique identifier for this endpoint */
+    uuid: string;
+    /** Parent project UUID */
+    project_id: string;
+    /** URL-safe slug used in API paths (e.g., "analyze-text") */
+    endpoint_name: string;
+    /** Human-readable endpoint title shown in the UI */
+    display_name: string;
+    /** HTTP method accepted by this endpoint (GET for simple queries, POST for input payloads) */
+    http_method: HttpMethod;
+    /** LLM model identifier override; null uses the provider's default model */
+    model: string | null;
+    /** JSON Schema defining the expected input payload structure */
+    input_schema: JsonSchema | null;
+    /** JSON Schema defining the expected LLM output structure */
+    output_schema: JsonSchema | null;
+    /** System-level instructions prepended to the LLM prompt */
+    instructions: string | null;
+    /** Additional context appended to the LLM prompt for grounding */
+    context: string | null;
+    /** Whether this endpoint is enabled; null treated as true */
+    is_active: boolean | null;
+    /** Array of allowed IPv4 addresses. When null, all IPs are permitted (no restriction). */
+    ip_allowlist: string[] | null;
+    /** Declares which media types this endpoint is expected to generate (images, audio, video). Null means text-only output. */
+    expects_media_output: MediaOutputConfig | null;
+    /** Format for returning generated media: "base64" embeds data inline, "url" stores in cloud and returns a signed URL. Null means no media output. */
+    output_media_format: 'base64' | 'url' | null;
+    /** For audio/transcription endpoints (e.g., Whisper): the model used to extract structured data from the raw transcription text. Null means no post-processing. */
+    transcription_extraction_model: string | null;
+    /** Whether this endpoint uses web search for supported providers (OpenAI Responses API). */
+    web_search: boolean;
+    /**
+     * Sampling temperature for this endpoint's model.
+     *
+     * `null` means **say nothing**, which is what every endpoint did before this
+     * field existed, and the providers disagree about what that implies: OpenAI,
+     * Gemini and Groq apply their own default of 0, while Anthropic omits the
+     * parameter entirely because Opus 4.7+ and Sonnet 5 reject it outright. A 0
+     * stored here is therefore a real choice — repeatable answers — and not the
+     * same as leaving it unset.
+     *
+     * 0 to 2 is OpenAI's and Gemini's range; Anthropic's is 0 to 1.
+     */
+    temperature: number | null;
+    /**
+     * Ceiling on how many tokens the model may generate for one invocation.
+     *
+     * `null` means **no protection**: the generation runs until the model stops or
+     * the provider severs the connection, and the caller pays for everything
+     * produced on the way. Endpoints created before this field existed are null.
+     *
+     * A caller may lower this per invocation, never raise it -- see
+     * {@link AiExecutionRequest}.
+     */
+    max_output_tokens: number | null;
+    /** Lifetime number of invocations, counting both successes and failures. Incremented by the API on each call. */
+    call_count: number;
+    /** Timestamp when this endpoint was created */
+    created_at: Date | null;
+    /** Timestamp of the most recent endpoint update */
+    updated_at: Date | null;
+}
+/**
+ * @description A single API request log entry for usage tracking and billing.
+ * One record is created per endpoint invocation, capturing token counts,
+ * latency, cost, and caller metadata for analytics dashboards.
+ */
+export interface UsageAnalytics {
+    /** Unique identifier for this analytics record */
+    uuid: string;
+    /** UUID of the endpoint that was invoked */
+    endpoint_id: string;
+    /** Timestamp when the request was received */
+    timestamp: Date;
+    /** Whether the LLM request completed successfully */
+    success: boolean;
+    /** Error message if the request failed; null on success */
+    error_message: string | null;
+    /** Number of input/prompt tokens consumed */
+    tokens_input: number | null;
+    /** Number of output/completion tokens generated */
+    tokens_output: number | null;
+    /** End-to-end request latency in milliseconds */
+    latency_ms: number | null;
+    /** Estimated cost of this request in cents (USD) */
+    estimated_cost_cents: number | null;
+    /** Arbitrary caller-supplied metadata (e.g., user_agent, ip, custom trace IDs). Stored as JSON and available for filtering in analytics queries. */
+    request_metadata: Record<string, unknown> | null;
+}
+export type StorageProvider = 'gcs' | 's3';
+/**
+ * Storage configuration for an entity (safe version without credentials).
+ * Used for cloud storage of generated media.
+ */
+export interface EntityStorageConfig {
+    uuid: string;
+    entity_id: string;
+    provider: StorageProvider;
+    bucket: string;
+    path_prefix: string | null;
+    created_at: Date | null;
+    updated_at: Date | null;
+}
+/**
+ * GCS service account credentials
+ */
+export interface GCSCredentials {
+    type: 'service_account';
+    project_id: string;
+    private_key_id: string;
+    private_key: string;
+    client_email: string;
+    client_id: string;
+    auth_uri?: string;
+    token_uri?: string;
+    auth_provider_x509_cert_url?: string;
+    client_x509_cert_url?: string;
+}
+/**
+ * AWS S3 credentials
+ */
+export interface S3Credentials {
+    access_key_id: string;
+    secret_access_key: string;
+    region: string;
+}
+export type StorageCredentials = GCSCredentials | S3Credentials;
+/**
+ * Request to create or update storage configuration
+ */
+export interface StorageConfigCreateRequest {
+    provider: StorageProvider;
+    bucket: string;
+    path_prefix?: string;
+    credentials: StorageCredentials;
+}
+export interface StorageConfigUpdateRequest {
+    bucket?: string;
+    path_prefix?: string | null;
+    credentials?: StorageCredentials;
+}
+/**
+ * @description User-level settings and organization preferences.
+ * Every authenticated user has settings; if none have been saved yet,
+ * the API returns auto-generated defaults with `is_default: true`.
+ */
+export interface UserSettings {
+    /** Database row ID; null when settings are auto-generated defaults not yet persisted */
+    id: string | null;
+    /** Firebase Authentication UID linking these settings to a {@link User} */
+    firebase_uid: string;
+    /** Display name of the user's organization; null if not set */
+    organization_name: string | null;
+    /** URL-safe organization path used in routing (auto-generated from UID if not customized) */
+    organization_path: string;
+    /** Computed field (not stored in DB): true if settings are auto-generated defaults */
+    is_default: boolean;
+    /** Timestamp when these settings were first saved */
+    created_at: Date | null;
+    /** Timestamp of the most recent settings update */
+    updated_at: Date | null;
+}
+/**
+ * @description A personal API key that authenticates its owner against the
+ * admin routes, as an alternative to a Firebase ID token. A user may hold
+ * several. The secret itself is never present on this type -- see
+ * {@link UserApiKeyCreated} and {@link UserApiKeyRevealed} for the two responses
+ * that carry it.
+ *
+ * Not to be confused with a *project* API key (`sk_live_...`), which
+ * authenticates callers of a published AI endpoint. Personal keys are prefixed
+ * `shyft_`.
+ */
+export interface UserApiKey {
+    /** Unique identifier for this key record */
+    uuid: string;
+    /** Firebase UID of the owner */
+    firebase_uid: string;
+    /** Human-readable label, e.g. "CLI on my laptop" */
+    key_name: string;
+    /** First characters of the key, for display (e.g. "shyft_ab12cd") */
+    key_prefix: string;
+    /** Whether the key is accepted; a deactivated key fails authentication */
+    is_active: boolean;
+    /** ISO 8601 timestamp of the most recent authenticated request, or null if unused */
+    last_used_at: string | null;
+    /** ISO 8601 timestamp when the key was created */
+    created_at: string | null;
+    /** ISO 8601 timestamp of the most recent update */
+    updated_at: string | null;
+}
+/**
+ * @description Response from creating a personal API key. This is the only
+ * response that returns the secret without being asked, and the value cannot be
+ * derived from any other endpoint except {@link UserApiKeyRevealed}.
+ */
+export interface UserApiKeyCreated extends UserApiKey {
+    /** The full `shyft_...` key */
+    api_key: string;
+}
+/** @description Response from revealing an existing personal API key. */
+export interface UserApiKeyRevealed {
+    /** The full `shyft_...` key */
+    api_key: string;
+}
+/**
+ * @description Identity of the authenticated caller, from `GET /users/me`.
+ * The only way an API-key client can learn its own Firebase UID, which the
+ * `/users/:userId/*` routes require.
+ */
+export interface CurrentUser {
+    /** Firebase UID of the caller */
+    firebase_uid: string;
+    /** Caller's email, or null when unavailable */
+    email: string | null;
+    /** Whether the caller is a site admin */
+    siteAdmin: boolean;
+    /** Which credential authenticated this request */
+    auth_method: 'firebase' | 'api_key';
+    /** Display name from the Firebase profile, or null */
+    display_name: string | null;
+}
+export interface UserCreateRequest {
+    firebase_uid: string;
+    email: Optional<string>;
+    display_name: Optional<string>;
+}
+export interface UserUpdateRequest {
+    email: Optional<string>;
+    display_name: Optional<string>;
+}
+export interface UserApiKeyCreateRequest {
+    key_name: string;
+}
+export interface UserApiKeyUpdateRequest {
+    key_name: Optional<string>;
+    is_active: Optional<boolean>;
+}
+export interface UserSettingsUpdateRequest {
+    organization_name: Optional<string>;
+    organization_path: Optional<string>;
+}
+export interface ProjectCreateRequest {
+    project_name: string;
+    display_name: string;
+    description: Optional<string>;
+}
+export interface ProjectUpdateRequest {
+    project_name: Optional<string>;
+    display_name: Optional<string>;
+    description: Optional<string>;
+    is_active: Optional<boolean>;
+}
+export interface EndpointCreateRequestBase {
+    endpoint_name: string;
+    display_name: string;
+    http_method: Optional<HttpMethod>;
+    model: Optional<string>;
+    input_schema: Optional<JsonSchema>;
+    output_schema: Optional<JsonSchema>;
+    instructions: Optional<string>;
+    context: Optional<string>;
+    expects_media_output?: Optional<MediaOutputConfig>;
+    output_media_format?: Optional<'base64' | 'url'>;
+    transcription_extraction_model?: Optional<string>;
+    web_search?: Optional<boolean>;
+    /** Sampling temperature (0-2). Omit or pass null to leave it to the provider. */
+    temperature?: Optional<number>;
+    /**
+     * Output ceiling for this endpoint. Omit to receive
+     * {@link DEFAULT_MAX_OUTPUT_TOKENS}; pass `null` to explicitly opt out of
+     * runaway protection.
+     */
+    max_output_tokens?: Optional<number>;
+}
+export interface EndpointUpdateRequestBase {
+    endpoint_name?: Optional<string>;
+    display_name?: Optional<string>;
+    http_method?: Optional<HttpMethod>;
+    model?: Optional<string>;
+    input_schema?: Optional<JsonSchema>;
+    output_schema?: Optional<JsonSchema>;
+    instructions?: Optional<string>;
+    context?: Optional<string>;
+    is_active?: Optional<boolean>;
+    ip_allowlist?: Optional<string[]>;
+    expects_media_output?: Optional<MediaOutputConfig>;
+    output_media_format?: Optional<'base64' | 'url'>;
+    transcription_extraction_model?: Optional<string>;
+    web_search?: Optional<boolean>;
+    /** Sampling temperature (0-2). `null` clears it, leaving sampling to the provider. */
+    temperature?: Optional<number>;
+    /**
+     * Output ceiling for this endpoint. Omit to leave unchanged; pass `null` to
+     * remove the ceiling.
+     */
+    max_output_tokens?: Optional<number>;
+}
+/**
+ * Utility type for boolean-like query string parameters.
+ * URL query params are always strings, so boolean values are represented
+ * as the literal strings `'true'` or `'false'`, or `undefined` when absent.
+ */
+export type BooleanQueryParam = 'true' | 'false' | undefined;
+export interface ProjectQueryParams {
+    is_active: BooleanQueryParam;
+}
+export interface EndpointQueryParams {
+    is_active: BooleanQueryParam;
+}
+export interface UsageAnalyticsQueryParams {
+    endpoint_id: Optional<string>;
+    project_id: Optional<string>;
+    start_date: Optional<string>;
+    end_date: Optional<string>;
+    success: BooleanQueryParam;
+}
+export interface UsageAggregate {
+    total_requests: number;
+    successful_requests: number;
+    failed_requests: number;
+    total_tokens_input: number;
+    total_tokens_output: number;
+    total_estimated_cost_cents: number;
+    average_latency_ms: number;
+}
+export interface UsageByEndpoint extends UsageAggregate {
+    endpoint_id: string;
+    endpoint_name: string;
+}
+export interface UsageByDate extends UsageAggregate {
+    date: string;
+}
+/** Compound response from analytics API endpoint */
+export interface AnalyticsResponse {
+    aggregate: UsageAggregate;
+    by_endpoint: UsageByEndpoint[];
+}
+export interface LlmRequest {
+    prompt: string;
+    system_prompt: Optional<string>;
+    output_schema: JsonSchema;
+    model: Optional<string>;
+    temperature: Optional<number>;
+    max_tokens: Optional<number>;
+}
+export interface LlmResponse {
+    content: unknown;
+    raw_response: string;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    model: string;
+    provider: LlmProvider;
+}
+/**
+ * Why the model stopped generating, normalized across providers.
+ *
+ * Providers spell this differently -- OpenAI `finish_reason`, Anthropic
+ * `stop_reason`, Gemini `finishReason` -- and use different vocabularies. These
+ * are the normalized values ShapeShyft reports.
+ */
+export declare const FINISH_REASONS: readonly ["stop", "length", "content_filter", "tool_calls", "other"];
+/** Why the model stopped generating. See {@link FINISH_REASONS}. */
+export type FinishReason = (typeof FINISH_REASONS)[number];
+/**
+ * Output ceiling applied to newly created endpoints when none is supplied.
+ *
+ * Chosen to be comfortably above a normal structured answer while still turning
+ * a runaway generation into a failure measured in seconds rather than the
+ * ~15 minutes a provider timeout takes. Endpoints may raise it, lower it, or set
+ * it to `null` to opt out entirely.
+ *
+ * This is a default for *new* endpoints only. It is never applied retroactively:
+ * an endpoint whose `max_output_tokens` is already `null` stays unprotected.
+ */
+export declare const DEFAULT_MAX_OUTPUT_TOKENS = 8000;
+export interface AiExecutionRequest {
+    input: unknown;
+    /**
+     * Lower the endpoint's output ceiling for this one call.
+     *
+     * Clamped to the endpoint's own ceiling, so this can only ever ask for
+     * *fewer* tokens -- it is not a way to escape an operator's limit. Ignored
+     * when the endpoint has no ceiling of its own.
+     */
+    max_output_tokens?: Optional<number>;
+}
+export interface AiExecutionResponse {
+    output: unknown;
+    usage: {
+        tokens_input: number;
+        tokens_output: number;
+        latency_ms: number;
+        estimated_cost_cents: number;
+        /**
+         * Why the model stopped. Absent when the provider did not report one.
+         * `'length'` means the answer was cut off at the ceiling, which is the
+         * difference between "the model ran away" and "the model returned
+         * something unparseable" -- different faults with different correct fixes.
+         */
+        finish_reason?: FinishReason;
+    };
+    /**
+     * True when generation stopped at a token ceiling. `output` is then a
+     * truncated answer that will usually fail schema validation.
+     */
+    truncated?: boolean;
+    /** Generated media (images, audio, video) from generative models */
+    generated_media?: GeneratedMedia[];
+}
+/** Response from /prompt endpoint - returns just the generated prompt */
+export interface AiPromptResponse {
+    prompt: string;
+}
+/** Response when refreshing/generating a project API key */
+export interface RefreshApiKeyResponse {
+    /** Full API key (only returned on generation/refresh) */
+    api_key: string;
+    /** Key prefix for display (e.g., "sk_live_ab...") */
+    api_key_prefix: string;
+    /** When the key was created/refreshed */
+    api_key_created_at: string;
+}
+/** Response when fetching the full API key */
+export interface GetApiKeyResponse {
+    /** Full decrypted API key */
+    api_key: string;
+}
+/** Input for ApiHelper.prompt() */
+export interface PromptInput {
+    inputData: unknown;
+    outputSchema: JsonSchema | null;
+    instructions: string | null;
+    context: string | null;
+    provider: LlmProvider;
+}
+/** Input for ApiHelper.request() */
+export interface ApiHelperRequestInput {
+    prompt: string;
+    outputSchema: JsonSchema;
+    provider: LlmProvider;
+    providerConfig: {
+        apiKey?: string;
+        endpointUrl?: string;
+        model?: string;
+    };
+    options?: {
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    };
+}
+/** Output from ApiHelper.request() */
+export interface ApiHelperRequestOutput {
+    apiPayload: Record<string, unknown>;
+    endpointUrl: string;
+    provider: LlmProvider;
+}
+/**
+ * Create a typed success response wrapping the given data.
+ *
+ * @example
+ * ```typescript
+ * import { successResponse, type Project } from './index.js';
+ *
+ * const project: Project = { uuid: '...', entity_id: '...', project_name: 'my-project', display_name: 'My Project', description: null, is_active: true, api_key_prefix: null, api_key_created_at: null, created_at: new Date(), updated_at: new Date() };
+ * const response = successResponse<Project>(project);
+ * // { success: true, data: { uuid: '...', project_name: 'my-project', ... }, timestamp: '2026-01-15T...' }
+ * ```
+ */
+export declare function successResponse<T>(data: T): BaseResponse<T>;
+/**
+ * Create a typed error response with the given error message.
+ *
+ * @example
+ * ```typescript
+ * import { errorResponse } from './index.js';
+ *
+ * const response = errorResponse('Project not found');
+ * // { success: false, error: 'Project not found', timestamp: '2026-01-15T...' }
+ *
+ * // In an API handler:
+ * if (!project) {
+ *   return c.json(errorResponse('Project not found'), 404);
+ * }
+ * ```
+ */
+export declare function errorResponse(error: string): BaseResponse<never>;
+export type ProjectListResponse = BaseResponse<Project[]>;
+export type ProjectResponse = BaseResponse<Project>;
+export type UserSettingsResponse = BaseResponse<UserSettings>;
+export type AnalyticsApiResponse = BaseResponse<AnalyticsResponse>;
+export type AiExecutionApiResponse = BaseResponse<AiExecutionResponse>;
+export type AiPromptApiResponse = BaseResponse<AiPromptResponse>;
+export type RefreshApiKeyApiResponse = BaseResponse<RefreshApiKeyResponse>;
+export type GetApiKeyApiResponse = BaseResponse<GetApiKeyResponse>;
+export type UserApiKeyListResponse = BaseResponse<UserApiKey[]>;
+export type UserApiKeyResponse = BaseResponse<UserApiKey>;
+export type UserApiKeyCreatedResponse = BaseResponse<UserApiKeyCreated>;
+export type UserApiKeyRevealedResponse = BaseResponse<UserApiKeyRevealed>;
+export type CurrentUserResponse = BaseResponse<CurrentUser>;
+export type HealthCheckResponse = BaseResponse<HealthCheckData>;
+export interface HealthCheckData {
+    name: string;
+    version: string;
+    status: string;
+}
+/**
+ * Provider configuration returned from the API
+ */
+export interface ProviderConfig {
+    id: LlmProvider;
+    name: string;
+    description: string;
+    allowsCustomModel: boolean;
+    defaultModel: string;
+    requiresEndpointUrl: boolean;
+}
+/**
+ * Model information with capabilities and pricing
+ */
+export interface ModelInfo {
+    id: string;
+    capabilities: ModelCapabilities;
+    pricing: ModelPricing;
+}
+/**
+ * Response from GET /providers/:provider/models
+ */
+export interface ProviderModelsResponse {
+    provider: ProviderConfig;
+    models: ModelInfo[];
+}
+export type ProviderListResponse = BaseResponse<ProviderConfig[]>;
+export type ProviderResponse = BaseResponse<ProviderConfig>;
+export type ProviderModelsApiResponse = BaseResponse<ProviderModelsResponse>;
+//# sourceMappingURL=index.d.ts.map