@aippy/runtime 0.2.6 → 0.2.7-dev.1

package/README.md

@@ -87,12 +87,46 @@ button.onclick = async () => {
 };
 ```
 
+### AI (Backend Proxy Adapter)
+
+```typescript
+// Default base URL: https://api.aippy.dev/api/aisdk/v1
+
+import { streamText, experimental_generateImage as generateImage } from 'ai';
+import { aippy } from '@aippy/runtime/ai';
+
+// Create provider (reads from env vars automatically)
+const provider = aippy();
+
+// Or override with config
+// const provider = aippy({ baseUrl: '...', userToken: '...' });
+
+// Streaming text generation (uses Vercel AI SDK)
+const result = await streamText({
+  model: provider('gpt'),
+  prompt: 'Write a haiku about TypeScript.',
+});
+
+for await (const chunk of result.textStream) {
+  console.log(chunk);
+}
+
+// Image generation
+const image = await generateImage({
+  model: provider.image('dall-e-3'),
+  prompt: 'A sunset over mountains',
+});
+
+console.log(image.image?.base64);
+```
+
 ## Packages
 
 - `@aippy/runtime/core` - Core types and configuration
 - `@aippy/runtime/device` - Device APIs (camera, geolocation, sensors, file system)
 - `@aippy/runtime/utils` - Platform detection, performance monitoring, PWA utilities
 - `@aippy/runtime/audio` - iOS-compatible Web Audio API wrapper
+- `@aippy/runtime/ai` - AI SDK adapter wrapping `ai` package, routes through backend proxy
 
 ## Publishing
 

package/dist/ai/config/bridge.d.ts

@@ -0,0 +1,23 @@
+import { AIConfig } from './types';
+/**
+ * Sends AI configuration to app container via postMessage
+ *
+ * Supports two scenarios:
+ * - iOS WebView: Uses `webkit.messageHandlers.aippyListener.postMessage()`
+ * - Iframe: Uses `window.parent.postMessage()`
+ *
+ * This is a one-way communication - we send the config but don't listen for updates
+ * because AI config is static (loaded at startup), not reactive like tweaks.
+ *
+ * @param config - The AI configuration to send
+ *
+ * @example
+ * ```ts
+ * import { sendAIConfigToContainer, loadAIConfig } from '@aippy/runtime/ai';
+ * import aiConfigJson from '@/config/aiConfig.json';
+ *
+ * const config = loadAIConfig(aiConfigJson);
+ * sendAIConfigToContainer(config);
+ * ```
+ */
+export declare function sendAIConfigToContainer(config: AIConfig): void;

package/dist/ai/config/helper.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AI Configuration helper functions
+ *
+ * Provides convenient utilities for loading and accessing AI configuration
+ * from aiConfig.json files generated by LLMs.
+ */
+/**
+ * Type for the values object returned by createAIConfig
+ * Provides direct property access to configuration values
+ */
+export interface AIConfigValues {
+    readonly [key: string]: unknown;
+}
+/**
+ * Creates an AI configuration helper that loads, validates, and provides
+ * convenient access to configuration values.
+ *
+ * This function:
+ * 1. Loads and validates the configuration
+ * 2. Sends it to the app container (for aippy app editing)
+ * 3. Returns an object with direct property access to config values
+ *
+ * **Recommended usage**: Call this once at app initialization and export
+ * the result for use throughout your app.
+ *
+ * @param configJson - The AI configuration JSON (usually from `import aiConfigJson from '@/config/aiConfig.json'`)
+ * @returns An object with direct property access to configuration values
+ *
+ * @example
+ * ```ts
+ * // app.tsx or main.tsx
+ * import aiConfigJson from '@/config/aiConfig.json';
+ * import { createAIConfig } from '@aippy/runtime/ai';
+ *
+ * export const aiConfig = createAIConfig(aiConfigJson);
+ *
+ * // In your AI code - direct property access
+ * import { aiConfig } from './app';
+ * const model = aiConfig.model; // string | undefined
+ * const temperature = aiConfig.temperature; // number | undefined
+ * ```
+ */
+export declare function createAIConfig(configJson: unknown): AIConfigValues;

package/dist/ai/config/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AI Configuration module
+ *
+ * Provides types, validation, and utilities for working with aiConfig.json
+ * files generated by LLMs when creating AI-powered applications.
+ */
+export type { AIConfig, AIConfigValue, AIConfigItem, NumberAIConfigItem, BooleanAIConfigItem, TextAIConfigItem, EnumAIConfigItem, AIConfigError, } from './types';
+export type { AIConfigValues } from './helper';
+export { AIConfigValidationError, validateAIConfig, parseAIConfig, loadAIConfig, getAIConfigValue, } from './parser';
+export { sendAIConfigToContainer } from './bridge';
+export { createAIConfig } from './helper';

package/dist/ai/config/parser.d.ts

@@ -0,0 +1,60 @@
+import { AIConfig, AIConfigError } from './types';
+/**
+ * Custom error class for AI configuration validation failures
+ */
+export declare class AIConfigValidationError extends Error {
+    readonly errors: AIConfigError[];
+    constructor(message: string, errors: AIConfigError[]);
+}
+/**
+ * Validates an AI configuration object
+ *
+ * @param config - The configuration object to validate
+ * @throws {AIConfigValidationError} If validation fails
+ */
+export declare function validateAIConfig(config: unknown): asserts config is AIConfig;
+/**
+ * Parses and validates AI configuration from a JSON string
+ *
+ * @param json - JSON string to parse
+ * @returns Validated AIConfig object
+ * @throws {AIConfigValidationError} If JSON is invalid or validation fails
+ *
+ * @example
+ * ```ts
+ * const json = '{"model": {"index": 0, "name": "Model", ...}}';
+ * const config = parseAIConfig(json);
+ * ```
+ */
+export declare function parseAIConfig(json: string): AIConfig;
+/**
+ * Loads and validates AI configuration from a configuration object
+ *
+ * Typically used with: `import aiConfig from '@/config/aiConfig.json'`
+ *
+ * @param config - Configuration object (usually from JSON import)
+ * @returns Validated AIConfig object
+ * @throws {AIConfigValidationError} If validation fails
+ *
+ * @example
+ * ```ts
+ * import aiConfigJson from '@/config/aiConfig.json';
+ * const config = loadAIConfig(aiConfigJson);
+ * ```
+ */
+export declare function loadAIConfig(config: unknown): AIConfig;
+/**
+ * Gets a configuration value by key
+ *
+ * @param config - The AIConfig object
+ * @param key - Configuration key to retrieve
+ * @returns The value of the configuration item
+ * @throws {Error} If the key is not found
+ *
+ * @example
+ * ```ts
+ * const model = getAIConfigValue<string>(config, 'model');
+ * const temperature = getAIConfigValue<number>(config, 'temperature');
+ * ```
+ */
+export declare function getAIConfigValue<T = unknown>(config: AIConfig, key: string): T;

package/dist/ai/config/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * AI Configuration types for aiConfig.json
+ *
+ * These types define the structure of the AI configuration file that LLMs
+ * generate when creating AI-powered applications.
+ */
+/**
+ * Base interface for all AI configuration items
+ */
+export interface AIConfigItem {
+    /** Display order (lower index = higher priority) */
+    index: number;
+    /** User-friendly display name */
+    name: string;
+    /** Description of the parameter */
+    description: string;
+    /** Optional group name for organizing related parameters */
+    group?: string;
+    /** Type of the configuration item */
+    type: 'number' | 'boolean' | 'text' | 'enum';
+    /** Current value */
+    value: number | string | boolean;
+}
+/**
+ * Number type configuration item
+ */
+export interface NumberAIConfigItem extends AIConfigItem {
+    type: 'number';
+    /** Minimum allowed value */
+    min?: number;
+    /** Maximum allowed value */
+    max?: number;
+    /** Step size for adjustments */
+    step?: number;
+    value: number;
+}
+/**
+ * Boolean type configuration item
+ */
+export interface BooleanAIConfigItem extends AIConfigItem {
+    type: 'boolean';
+    value: boolean;
+}
+/**
+ * Text type configuration item
+ */
+export interface TextAIConfigItem extends AIConfigItem {
+    type: 'text';
+    value: string;
+}
+/**
+ * Enum type configuration item
+ * Used for parameters with a fixed set of valid values (e.g., model names, image sizes)
+ */
+export interface EnumAIConfigItem extends AIConfigItem {
+    type: 'enum';
+    /** Array of valid option values */
+    options: string[];
+    value: string;
+}
+/**
+ * Union type of all possible AI configuration item types
+ */
+export type AIConfigValue = NumberAIConfigItem | BooleanAIConfigItem | TextAIConfigItem | EnumAIConfigItem;
+/**
+ * AI Configuration object structure
+ * Maps configuration keys to their respective configuration items
+ */
+export interface AIConfig {
+    [key: string]: AIConfigValue;
+}
+/**
+ * Validation error information
+ */
+export interface AIConfigError {
+    /** Configuration key that has the error */
+    key: string;
+    /** Error message describing the issue */
+    message: string;
+}

package/dist/ai/errors.d.ts

@@ -0,0 +1,25 @@
+import { AISDKError } from 'ai';
+/**
+ * Normalizes a backend error response into an AISDKError.
+ *
+ * If the backend error response includes container message data (e.g., `appMessage` field),
+ * it will be automatically sent to the app container for user-facing UI (e.g., payment dialog,
+ * error popup, success notification).
+ */
+export declare function normalizeError(response: Response, body?: unknown): AISDKError;
+/**
+ * Creates an error for missing user token.
+ */
+export declare function missingTokenError(): AISDKError;
+/**
+ * Creates an error for aborted requests.
+ */
+export declare function abortedError(): AISDKError;
+/**
+ * Creates an error for network failures.
+ */
+export declare function networkError(cause?: unknown): AISDKError;
+/**
+ * Creates an error for parse failures.
+ */
+export declare function parseError(message: string): AISDKError;

package/dist/ai/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @aippy/runtime/ai - AI module for Aippy Runtime SDK
+ *
+ * This module provides two integration paths with Vercel AI SDK:
+ *
+ * ## Path 1: OpenAI-Compatible Provider (AI SDK Core)
+ *
+ * Use `aippyAIProvider()` provider with AI SDK Core functions:
+ * - generateText / streamText
+ * - generateObject / streamObject
+ * - embed / embedMany
+ * - generateImage
+ *
+ * ```ts
+ * import { streamText } from 'ai';
+ * import { aippyAIProvider } from '@aippy/runtime/ai';
+ *
+ * const provider = aippyAIProvider();
+ * const result = await streamText({
+ *   model: provider('gpt-5'),
+ *   prompt: 'Hello!',
+ * });
+ * ```
+ *
+ * ## Path 2: Data Stream Protocol (AI SDK UI / @ai-sdk/react)
+ *
+ * Use config builders with @ai-sdk/react hooks:
+ * - useChat → aippyChatConfig()
+ *
+ * ```tsx
+ * import { useChat } from '@ai-sdk/react';
+ * import { aippyChatConfig } from '@aippy/runtime/ai';
+ *
+ * const { messages, handleSubmit } = useChat(aippyChatConfig());
+ * ```
+ *
+ * @module
+ */
+export { aippyAIProvider, type AippyProvider } from './openai';
+export type { AippyOpenAIConfig } from './openai';
+/** @deprecated Use aippyAIProvider() instead */
+export { aippyAIProvider as aippy } from './openai';
+export { aippyChatConfig, type AippyUseChatOptions, type AippyUIConfig, type AippyChatConfig, UI_CHAT_ENDPOINT, } from './ui';
+export { DEFAULT_BASE_URL, DEFAULT_UI_BASE_URL, DEFAULT_CHAT_MODEL, DEFAULT_CHAT_SYSTEM, } from './shared';
+export { normalizeError, missingTokenError, abortedError, networkError, parseError, } from './errors';
+export { type AIConfig, type AIConfigValue, type AIConfigItem, type NumberAIConfigItem, type BooleanAIConfigItem, type TextAIConfigItem, type EnumAIConfigItem, type AIConfigError, type AIConfigValues, AIConfigValidationError, validateAIConfig, parseAIConfig, loadAIConfig, getAIConfigValue, sendAIConfigToContainer, createAIConfig, } from './config';

package/dist/ai/index.js

@@ -0,0 +1,25 @@
+import { A as i, D as A, d as n, e, c as E, U as C, f as p, a as g, a as t, b as I, j as T, i as _, l as f, m as U, g as d, n as D, h as L, p as l, s as m, v as F } from "../helper-CRGxnlsu.js";
+import "react";
+import "../bridge-D2d8hnO_.js";
+export {
+  i as AIConfigValidationError,
+  A as DEFAULT_BASE_URL,
+  n as DEFAULT_CHAT_MODEL,
+  e as DEFAULT_CHAT_SYSTEM,
+  E as DEFAULT_UI_BASE_URL,
+  C as UI_CHAT_ENDPOINT,
+  p as abortedError,
+  g as aippy,
+  t as aippyAIProvider,
+  I as aippyChatConfig,
+  T as createAIConfig,
+  _ as getAIConfigValue,
+  f as loadAIConfig,
+  U as missingTokenError,
+  d as networkError,
+  D as normalizeError,
+  L as parseAIConfig,
+  l as parseError,
+  m as sendAIConfigToContainer,
+  F as validateAIConfig
+};

package/dist/ai/openai/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OpenAI-compatible module for Aippy AI SDK.
+ *
+ * Provides the `aippyAIProvider()` provider factory for use with AI SDK Core functions:
+ * - generateText / streamText
+ * - generateObject / streamObject
+ * - embed / embedMany
+ * - generateImage
+ */
+export { aippyAIProvider, type AippyProvider } from './provider';
+export type { AippyOpenAIConfig } from '../shared/config';

package/dist/ai/openai/provider.d.ts

@@ -0,0 +1,51 @@
+import { OpenAICompatibleProvider } from '@ai-sdk/openai-compatible';
+import { AippyOpenAIConfig } from '../shared';
+/**
+ * The Aippy provider type - an OpenAI-compatible provider.
+ */
+export type AippyProvider = OpenAICompatibleProvider<string, string, string, string>;
+/**
+ * Creates an Aippy AI provider that routes requests through the backend proxy.
+ *
+ * This provider is for use with AI SDK Core functions:
+ * - `generateText` / `streamText` - Text generation
+ * - `generateObject` / `streamObject` - Structured object generation
+ * - `embed` / `embedMany` - Text embeddings
+ * - `generateImage` - Image generation
+ *
+ * @param config - Optional configuration to override defaults
+ * @returns An AI SDK Core compatible provider
+ *
+ * @example
+ * ```ts
+ * import { generateText, streamText, embed, generateImage } from 'ai';
+ * import { aippyAIProvider } from '@aippy/runtime/ai';
+ *
+ * const provider = aippyAIProvider();
+ *
+ * // Text generation
+ * const text = await generateText({
+ *   model: provider('gpt-5-nano'),
+ *   prompt: 'Hello!',
+ * });
+ *
+ * // Streaming
+ * const stream = await streamText({
+ *   model: provider('gpt-5-nano'),
+ *   prompt: 'Tell me a story.',
+ * });
+ *
+ * // Embeddings
+ * const embedding = await embed({
+ *   model: provider.embeddingModel('text-embedding-3-small'),
+ *   value: 'Hello world',
+ * });
+ *
+ * // Image generation
+ * const image = await generateImage({
+ *   model: provider.imageModel('gpt-image-1-mini'),
+ *   prompt: 'A cat',
+ * });
+ * ```
+ */
+export declare function aippyAIProvider(config?: AippyOpenAIConfig): AippyProvider;

package/dist/ai/shared/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared configuration for Aippy AI SDK.
+ * Used by both OpenAI-compatible (Core) and Data Stream Protocol (UI) paths.
+ */
+/** Default backend base URL for OpenAI-compatible endpoints */
+export declare const DEFAULT_BASE_URL: string;
+/** Default backend base URL for UI (Data Stream Protocol) endpoints */
+export declare const DEFAULT_UI_BASE_URL: string;
+/**
+ * Configuration for OpenAI-compatible provider (AI SDK Core).
+ */
+export interface AippyOpenAIConfig {
+    /** Backend proxy URL for OpenAI-compatible endpoints (defaults to DEFAULT_BASE_URL) */
+    baseUrl?: string;
+}
+/**
+ * Configuration for Data Stream Protocol endpoints (AI SDK UI).
+ */
+export interface AippyUIConfig {
+    /** Backend proxy URL for UI endpoints (defaults to DEFAULT_UI_BASE_URL) */
+    baseUrl?: string;
+}
+/**
+ * Configuration for useChat hook with model and system prompt.
+ */
+export interface AippyChatConfig extends AippyUIConfig {
+    /**
+     * Optional API endpoint override for useChat.
+     * Useful for local dev proxies (e.g. Vite) to avoid cross-origin streaming.
+     *
+     * If not provided, we use `${baseUrl}/chat`.
+     */
+    api?: string;
+    /** Model identifier (defaults to 'gpt-5-nano') */
+    model?: string;
+    /** System prompt for the conversation (defaults to empty string) */
+    system?: string;
+}
+/** Default model for chat */
+export declare const DEFAULT_CHAT_MODEL = "gpt-5-nano";
+/** Default model for image generation */
+export declare const DEFAULT_IMAGE_MODEL = "gpt-image-1-mini";
+/** Default model for embeddings */
+export declare const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+/** Default system prompt for chat */
+export declare const DEFAULT_CHAT_SYSTEM = "";
+/**
+ * Resolves OpenAI-compatible configuration with defaults.
+ */
+export declare function resolveOpenAIConfig(config?: AippyOpenAIConfig): Required<AippyOpenAIConfig>;
+/**
+ * Resolves UI (Data Stream Protocol) configuration with defaults.
+ */
+export declare function resolveUIConfig(config?: AippyUIConfig): Required<AippyUIConfig>;

package/dist/ai/shared/fetch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared fetch utilities for Aippy AI SDK.
+ * Used by both OpenAI-compatible (Core) and Data Stream Protocol (UI) paths.
+ */
+/**
+ * Joins a base URL with a path segment.
+ * Uses native URL API for reliable URL resolution.
+ *
+ * @param baseUrl - The base URL (e.g., 'https://api.aippy.dev/api/aisdk/v1/ui/')
+ * @param path - The path segment to append (e.g., '/chat' or 'chat')
+ * @returns The joined URL string
+ *
+ * @example
+ * joinUrl('https://api.aippy.dev/api/aisdk/v1/ui/', '/chat')
+ * // => 'https://api.aippy.dev/api/aisdk/v1/ui/chat'
+ */
+export declare function joinUrl(baseUrl: string, path: string): string;
+/**
+ * Creates a fetch wrapper that injects Authorization header with a fresh token.
+ * Token is fetched asynchronously on every request to ensure it's always current.
+ *
+ * @returns A fetch function compatible with globalThis.fetch signature
+ *
+ * @example
+ * const authFetch = createAuthFetch();
+ * const response = await authFetch('https://api.example.com/endpoint', { method: 'POST' });
+ */
+export declare function createAuthFetch(): typeof globalThis.fetch;

package/dist/ai/shared/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared utilities for Aippy AI SDK.
+ * Re-exports config and fetch utilities used by both protocol paths.
+ */
+export { DEFAULT_BASE_URL, DEFAULT_UI_BASE_URL, DEFAULT_CHAT_MODEL, DEFAULT_CHAT_SYSTEM, resolveOpenAIConfig, resolveUIConfig, type AippyOpenAIConfig, type AippyUIConfig, type AippyChatConfig, } from './config';
+export { joinUrl, createAuthFetch } from './fetch';

package/dist/ai/ui/config.d.ts

@@ -0,0 +1,25 @@
+import { AippyChatConfig } from '../shared';
+import { AippyUseChatOptions } from './types';
+/**
+ * Creates configuration for the useChat hook.
+ *
+ * @param config - Optional configuration to override defaults
+ * @returns Promise resolving to configuration object to spread into useChat()
+ *
+ * @example
+ * ```tsx
+ * import { useChat } from '@ai-sdk/react';
+ * import { aippyChatConfig } from '@aippy/runtime/ai';
+ *
+ * const chatConfig = await aippyChatConfig();
+ * const { messages, input, handleSubmit } = useChat(chatConfig);
+ *
+ * // With custom model and system prompt
+ * const config = await aippyChatConfig({
+ *   model: 'claude-3',
+ *   system: 'You are a helpful assistant.',
+ * });
+ * const { messages } = useChat(config);
+ * ```
+ */
+export declare function aippyChatConfig(config?: AippyChatConfig): AippyUseChatOptions;

package/dist/ai/ui/endpoints.d.ts

@@ -0,0 +1,12 @@
+/**
+ * UI endpoint path constants for Data Stream Protocol.
+ *
+ * These endpoints are served by the Aippy backend and return
+ * responses in AI SDK Data Stream Protocol format.
+ *
+ * Required response headers from backend:
+ * - Content-Type: text/event-stream
+ * - x-vercel-ai-ui-message-stream: v1
+ */
+/** Endpoint for useChat hook */
+export declare const UI_CHAT_ENDPOINT = "/chat";

package/dist/ai/ui/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AI SDK UI module for Aippy AI SDK.
+ *
+ * Provides configuration builders for @ai-sdk/react hooks:
+ * - useChat → aippyChatConfig()
+ *
+ * These hooks communicate with the Aippy backend using
+ * AI SDK Data Stream Protocol (SSE with x-vercel-ai-ui-message-stream: v1).
+ */
+export { aippyChatConfig } from './config';
+export type { AippyUseChatOptions } from './types';
+export { UI_CHAT_ENDPOINT } from './endpoints';
+export type { AippyUIConfig, AippyChatConfig } from '../shared/config';

package/dist/ai/ui/types.d.ts

@@ -0,0 +1,21 @@
+import { ChatTransport, UIMessage } from 'ai';
+/**
+ * Body parameters for useChat requests (internal use).
+ */
+interface UseChatBody {
+    /** Model identifier (e.g., 'gpt-5', 'claude-3') */
+    model: string;
+    /** System prompt for the conversation */
+    system: string;
+}
+/**
+ * Configuration options for useChat hook with Aippy transport.
+ *
+ * This is a minimal wrapper around ChatTransport for type safety.
+ * Users can also directly use ChatTransport from 'ai' package.
+ */
+export interface AippyUseChatOptions<UI_MESSAGE extends UIMessage = UIMessage> {
+    /** Transport for custom API communication */
+    transport: ChatTransport<UI_MESSAGE>;
+}
+export type { UseChatBody };

package/dist/ai.d.ts

@@ -0,0 +1,2 @@
+export * from './ai/index'
+export {}