@llmnative/react 0.1.1 → 1.1.0

package/dist/types/src/providers/ProviderConfiguration.d.ts

@@ -6,6 +6,12 @@ export interface ProviderConfigurationState {
 export interface ProviderConfigurable {
     isConfigured?(): boolean;
     getConfigurationState?(): ProviderConfigurationState;
+    /**
+     * Optional teardown hook. Called by setProvider() before an adapter is replaced
+     * in the registry — e.g. unsubscribe realtime listeners, sign out, close connections.
+     * Never called on unmount; only on explicit replacement.
+     */
+    dispose?(): Promise<void> | void;
 }
 export declare const getMissingKeys: (config: Record<string, unknown> | undefined, keys: string[], prefix?: string) => string[];
 export declare const createConfigurationState: (provider: string, missingKeys: string[]) => ProviderConfigurationState;

package/dist/types/src/providers/ProviderDescriptor.d.ts

@@ -0,0 +1,18 @@
+export type ProviderCredentialField = {
+    key: string;
+    label: string;
+    type: 'text' | 'password' | 'textarea';
+    placeholder?: string;
+};
+export type ProviderDescriptor = {
+    id: string;
+    label: string;
+    description: string;
+    credentialFields: ProviderCredentialField[];
+    /** Where to go find/generate this credential (the provider's own dashboard/API keys page). */
+    credentialsUrl?: string;
+    /** Short guidance on where in that dashboard to look, when the URL alone isn't obvious. */
+    credentialsHint?: string;
+    /** Numbered walkthrough for setups too involved for a one-line hint (e.g. multi-console flows). Rendered instead of credentialsHint when present. */
+    credentialsSteps?: string[];
+};

package/dist/types/src/providers/ProviderRegistryContext.d.ts

@@ -0,0 +1,51 @@
+import React from 'react';
+import type { DataProviderAdapter } from './data/DataProvider';
+import type { StorageProviderAdapter } from './storage/StorageProvider';
+import type { AuthProviderAdapter } from './auth/AuthProvider';
+import type { EmailProviderAdapter } from './email/EmailProvider';
+import type { AIProviderAdapter } from './ai/AIProvider';
+import type { CredentialsAdapter } from './credentials/CredentialsProvider';
+export type ProviderAdapterMap = {
+    data: DataProviderAdapter;
+    storage: StorageProviderAdapter;
+    auth: AuthProviderAdapter;
+    email: EmailProviderAdapter;
+    ai: AIProviderAdapter;
+    credentials: CredentialsAdapter;
+};
+/** The 6 categories the framework ships out of the box. Any other string is a valid category too — see customCategories on <App>. */
+export type ProviderService = keyof ProviderAdapterMap;
+export type ProviderRegistrySnapshot = Record<string, {
+    registry: Record<string, unknown>;
+    defaultKey: string;
+}>;
+/**
+ * Replaces a single named adapter in a provider registry at runtime, in ANY
+ * category — one of the 6 built-in ones (typed) or an arbitrary custom one a
+ * vertical registered (string). Calls the previous adapter's dispose() (if
+ * defined) before swapping it in, then propagates the new registry to every
+ * useXProvider()/useProvider() consumer. If `category` didn't exist yet, it's
+ * created — categories can be registered after bootstrap, not only via <App providers>.
+ */
+export type SetProviderFn = {
+    <S extends ProviderService>(category: S, key: string, adapter: ProviderAdapterMap[S]): Promise<void>;
+    (category: string, key: string, adapter: unknown): Promise<void>;
+};
+type ProviderRegistryContextValue = {
+    registries: ProviderRegistrySnapshot;
+    setProvider: SetProviderFn;
+};
+declare const ProviderRegistryContext: React.Context<ProviderRegistryContextValue | null>;
+export declare const ProviderRegistryProvider: ({ registries, setProvider, children, }: ProviderRegistryContextValue & {
+    children: React.ReactNode;
+}) => React.JSX.Element;
+/** Imperatively swap a provider adapter at runtime (e.g. reconnect data/storage to a different backend). */
+export declare const useSetProvider: () => SetProviderFn;
+/**
+ * Generic read access to any provider category — built-in or custom. Prefer the
+ * typed useDataProvider()/useStorageProvider()/... for the 6 built-ins; reach for
+ * this when consuming a category the framework doesn't know about (registered via
+ * providers.customCategories or a runtime setProvider() call).
+ */
+export declare const useProvider: <T = unknown>(category: string, key?: string) => T;
+export default ProviderRegistryContext;

package/dist/types/src/providers/ProviderSession.d.ts

@@ -0,0 +1,68 @@
+import type { SetProviderFn } from './ProviderRegistryContext';
+/**
+ * Generic multi-backend session switch — no domain vocabulary (tenant, workspace, ...).
+ * Given an endpoint that returns which backend project to connect to (per category —
+ * data, storage, or any custom category a vertical registered) and a scoped credential
+ * for it, resolves the right adapter and swaps it in via setProvider().
+ *
+ * A vertical app (e.g. a CMS with tenants) wraps this in its own thin, named provider
+ * (e.g. TenantProvider, mounted via <App contextProviders>) that knows what a "session"
+ * means for that app — this hook only knows how to connect to a backend and get out
+ * of the way.
+ */
+export type ProviderSessionCredential = {
+    type: string;
+} & Record<string, unknown>;
+export type ProviderSessionAssignment = {
+    /**
+     * Matched against the factory registry below — 'firebase'/'supabase'/'mock' are
+     * built in, a vertical can register more with registerProviderSessionFactory().
+     * An assignment whose (category, type) has no registered factory is discarded,
+     * not an error — a session response can describe categories/types this particular
+     * app build doesn't know about without breaking the switch for the ones it does.
+     */
+    type: string;
+    /** Client-safe config for this provider's project — never a secret. */
+    publicConfig: Record<string, unknown>;
+    /** Scoped, short-lived credential resolved server-side. Absent = anonymous/public access. */
+    credential?: ProviderSessionCredential;
+};
+/** category (data, storage, or any custom one) → assignment. Open-ended on purpose. */
+export type ProviderSessionResponse = {
+    providers: Record<string, ProviderSessionAssignment>;
+};
+export type ProviderSessionFactory = (assignment: ProviderSessionAssignment) => unknown | Promise<unknown>;
+/**
+ * Registers how to turn a ProviderSessionAssignment into a live adapter for a given
+ * (category, type) pair. Callable anytime — at module load, or later once a feature
+ * that needs it is loaded — not only at <App> bootstrap.
+ */
+export declare const registerProviderSessionFactory: (category: string, type: string, factory: ProviderSessionFactory) => void;
+export type ProviderSessionSwitchOptions = {
+    fetchOptions?: RequestInit;
+    /**
+     * Inspect or transform the raw response before it's applied — e.g. inject an extra
+     * category, filter one out, forward it to an audit log. Whatever this returns
+     * (defaults to the untouched response) is what actually gets applied.
+     */
+    onResponse?: (response: ProviderSessionResponse) => ProviderSessionResponse | Promise<ProviderSessionResponse>;
+};
+/** Which (category, type) pairs were actually applied vs had no matching factory. */
+export type ProviderSessionSwitchResult = {
+    applied: string[];
+    skipped: {
+        category: string;
+        type: string;
+    }[];
+};
+/**
+ * Either a URL to fetch (real backend) or a resolver function that produces the same
+ * response shape directly (e.g. a mock backend, or any non-HTTP source). Everything
+ * downstream of "here's the response body" is identical either way — only the transport
+ * differs, so swapping a mock resolver for a real endpoint later touches no other code.
+ */
+export type SwitchProviderSessionFn = (source: string | (() => Promise<ProviderSessionResponse>), options?: ProviderSessionSwitchOptions) => Promise<ProviderSessionSwitchResult>;
+export declare const useProviderSession: () => {
+    switchSession: SwitchProviderSessionFn;
+    setProvider: SetProviderFn;
+};

package/dist/types/src/providers/ai/AIProvider.d.ts

@@ -0,0 +1,57 @@
+import type { PromptVariables } from '../../conf/Prompt';
+import type { ProviderConfigurable } from '../ProviderConfiguration';
+export interface AIModelDescriptor {
+    id: string;
+    provider: string;
+    model: string;
+    label: string;
+    deprecated?: boolean;
+}
+export interface AIProviderCapabilities {
+    models: AIModelDescriptor[];
+    supportsTemperature?: boolean;
+    supportsVision?: boolean;
+    supportsDocuments?: boolean;
+}
+export interface AIAttachment {
+    mimeType: string;
+    base64: string;
+    name?: string;
+}
+export interface AIRequestOptions {
+    language?: string;
+    voice?: string;
+    style?: string;
+    role?: string;
+    model?: string;
+    temperature?: number;
+    attachments?: AIAttachment[];
+}
+export interface AICompleteRequest extends AIRequestOptions {
+    prompt: string;
+    data?: PromptVariables;
+}
+export interface AIKeyValidationResult {
+    valid: boolean;
+    /** Human-readable error from the provider API (e.g. "Incorrect API key provided"). */
+    error?: string;
+    /** URL to the provider's API key management page, for showing in UI. */
+    dashboardUrl?: string;
+}
+export interface AIProviderAdapter extends ProviderConfigurable {
+    id: string;
+    label: string;
+    defaultModel: string;
+    /** URL to the provider's API key management page. */
+    dashboardUrl?: string;
+    getCapabilities(forceRefresh?: boolean): Promise<AIProviderCapabilities>;
+    complete(request: AICompleteRequest): Promise<string | null>;
+    /** Makes a live API call to verify the key is accepted. Never uses cache. */
+    validateApiKey(): Promise<AIKeyValidationResult>;
+}
+export interface AIModelRef {
+    provider: string;
+    model: string;
+}
+export declare const formatAIModelRef: (provider: string, model: string) => string;
+export declare const parseAIModelRef: (value?: string | null) => AIModelRef | null;

package/dist/types/src/providers/ai/AIProviderContext.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { AIProviderAdapter } from './AIProvider';
+type AIProviderContextValue = {
+    registry: Record<string, AIProviderAdapter>;
+    defaultKey: string;
+};
+declare const AIProviderContext: React.Context<AIProviderContextValue | null>;
+export declare const AIProvider: ({ registry, defaultKey, children, }: AIProviderContextValue & {
+    children: React.ReactNode;
+}) => React.JSX.Element;
+export declare const useAIProvider: (name?: string) => AIProviderAdapter | null;
+export declare const useAIProviderRegistry: () => AIProviderContextValue | null;
+export default AIProviderContext;

package/dist/types/src/providers/ai/anthropic.d.ts

@@ -0,0 +1,2 @@
+import type { AIProviderDefinition } from './shared';
+export declare const ANTHROPIC_PROVIDER_DEFINITION: AIProviderDefinition;

package/dist/types/src/providers/ai/deepseek.d.ts

@@ -0,0 +1 @@
+export declare const DEEPSEEK_PROVIDER_DEFINITION: import("./shared").AIProviderDefinition;

package/dist/types/src/providers/ai/gemini.d.ts

@@ -0,0 +1,2 @@
+import type { AIProviderDefinition } from './shared';
+export declare const GEMINI_PROVIDER_DEFINITION: AIProviderDefinition;

package/dist/types/src/providers/ai/glm.d.ts

@@ -0,0 +1 @@
+export declare const GLM_PROVIDER_DEFINITION: import("./shared").AIProviderDefinition;

package/dist/types/src/providers/ai/index.d.ts

@@ -1,134 +1,20 @@
-import { Prompt, PROMPTS } from "../../conf/Prompt";
-import { type ProviderConfigurationState } from "../ProviderConfiguration";
-import { PromptVariables } from "../../conf/Prompt";
-export default function fetchAI(provider?: string): (prompt: string, options?: {
-    model?: string;
-    temperature?: number;
-}, strategy?: keyof typeof PROMPTS | undefined) => Promise<any>;
-interface AIProvider {
-    name: string;
-    url: string;
-    model: string;
-    models: string[];
-    framework?: string;
-    frameworks?: string[];
-    temperature: number;
-    parseHeaders: () => Record<string, string>;
-    parseBody: (prompt: string, role: string, options: AIOptions) => Record<string, any>;
-    parseResponse: (response: any) => any;
-}
-interface AIOptions {
-    language?: string;
-    voice?: string;
-    style?: string;
-    role?: string;
-    model?: string;
-    temperature?: number;
-}
-export interface AIFetchConfig extends AIOptions {
-    provider?: keyof typeof PROVIDERS;
-}
-export declare const getAIProviderConfigurationState: (provider?: keyof typeof PROVIDERS) => ProviderConfigurationState;
-declare const PROVIDERS: {
-    openai: {
-        name: string;
-        url: string;
-        model: string;
-        models: string[];
-        framework: string;
-        frameworks: string[];
-        temperature: number;
-        parseHeaders: () => {
-            'Content-Type': string;
-            Authorization: string;
-        };
-        parseBody: (prompt: string, role: string, options: AIOptions) => {
-            model: string;
-            messages: {
-                role: string;
-                content: string;
-            }[];
-            temperature: number;
-        };
-        parseResponse: (response: any) => any;
-    };
-    gemini: {
-        name: string;
-        url: string;
-        model: string;
-        models: string[];
-        temperature: number;
-        parseHeaders: () => {
-            'Content-Type': string;
-            Authorization: string;
-        };
-        parseBody: (prompt: string, role: string, options: AIOptions) => {
-            model: string;
-            instances: {
-                content: string;
-            }[];
-            temperature: number;
-        };
-        parseResponse: (response: any) => any;
-    };
-    anthropic: {
-        name: string;
-        url: string;
-        model: string;
-        models: string[];
-        temperature: number;
-        parseHeaders: () => {
-            'Content-Type': string;
-            Authorization: string;
-        };
-        parseBody: (prompt: string, role: string, options: AIOptions) => {
-            model: string;
-            messages: {
-                role: string;
-                content: string;
-            }[];
-            temperature: number;
-        };
-        parseResponse: (response: any) => any;
-    };
-    mistral: {
-        name: string;
-        url: string;
-        model: string;
-        models: string[];
-        temperature: number;
-        parseHeaders: () => {
-            'Content-Type': string;
-            Authorization: string;
-        };
-        parseBody: (prompt: string, role: string, options: AIOptions) => {
-            model: string;
-            messages: {
-                role: string;
-                content: string;
-            }[];
-            temperature: number;
-        };
-        parseResponse: (response: any) => any;
-    };
-};
-export declare class AI extends Prompt {
-    config: AIProvider;
-    options: AIOptions;
-    data?: PromptVariables;
-    static fetch(prompt: string, config: AIFetchConfig, data?: PromptVariables): Promise<any>;
-    static getModels(provider?: keyof typeof PROVIDERS): string[];
-    constructor(provider?: keyof typeof PROVIDERS);
-    setOptions(options: AIOptions): this;
-    setData(data?: PromptVariables): this;
-    static defaults(): {
-        model: string;
-        role: string;
-        language: string;
-        country: string;
-        voice: string;
-        style: string;
-    };
-    fetchAPI(prompt: string): Promise<any>;
-}
-export {};
+import type { AIConfig } from '../../Config';
+import type { ProviderDescriptor } from '../ProviderDescriptor';
+import type { AIProviderAdapter } from './AIProvider';
+import { type AIProviderDefinition } from './shared';
+export type { AIProviderAdapter, AIKeyValidationResult, AIModelDescriptor, AIProviderCapabilities, AIRequestOptions, AIAttachment } from './AIProvider';
+export { formatAIModelRef, parseAIModelRef } from './AIProvider';
+export type { AIModelCatalog, AIProviderDefinition } from './shared';
+export { getAIModelCatalog } from './shared';
+export declare const AI_PROVIDER_DEFINITIONS: AIProviderDefinition[];
+/** Generic "connect this provider" view of an AIProviderDefinition — the shape a CMS/admin
+ * UI needs (label, description, credential fields, where to find them), independent of the
+ * runtime completion contract (discoverModels/complete) it also carries. */
+export declare const toProviderDescriptor: (definition: AIProviderDefinition) => ProviderDescriptor;
+export declare const AI_PROVIDER_DESCRIPTORS: ProviderDescriptor[];
+/** The user-configurable "bring your own endpoint" slot — metadata-only counterpart of the
+ * dynamic definition getDynamicAIProviderDefinitions() builds once a baseUrl is actually
+ * known. Not part of AI_PROVIDER_DEFINITIONS (there's nothing to build a working adapter
+ * from until the user supplies that URL), but a "connect" UI still needs to offer it. */
+export declare const OPENAI_COMPATIBLE_PROVIDER_DESCRIPTOR: ProviderDescriptor;
+export declare const createAIProviderRegistry: (aiConfig?: AIConfig) => Record<string, AIProviderAdapter>;

package/dist/types/src/providers/ai/mistral.d.ts

@@ -0,0 +1 @@
+export declare const MISTRAL_PROVIDER_DEFINITION: import("./shared").AIProviderDefinition;

package/dist/types/src/providers/ai/openai.d.ts

@@ -0,0 +1 @@
+export declare const OPENAI_PROVIDER_DEFINITION: import("./shared").AIProviderDefinition;

package/dist/types/src/providers/ai/openaiCompatible.d.ts

@@ -0,0 +1,19 @@
+import type { AIProviderDefinition, BuiltInAIProviderId } from './shared';
+type OpenAICompatibleDefinitionOptions = {
+    id: BuiltInAIProviderId;
+    label: string;
+    description: string;
+    configKey: string;
+    requiredConfigKeys?: string[];
+    defaultModel: string;
+    fallbackModels: string[];
+    baseUrl: string;
+    modelsUrl?: string;
+    chatCompletionsUrl?: string;
+    dashboardUrl?: string;
+    credentialsHint?: string;
+    /** Override the default validateApiKey when the models endpoint is public or uses a non-standard error format. */
+    validateApiKey?: AIProviderDefinition['validateApiKey'];
+};
+export declare const createOpenAICompatibleProviderDefinition: ({ id, label, description, configKey, requiredConfigKeys, defaultModel, fallbackModels, baseUrl, modelsUrl, chatCompletionsUrl, dashboardUrl, credentialsHint, validateApiKey: validateApiKeyOverride, }: OpenAICompatibleDefinitionOptions) => AIProviderDefinition;
+export {};

package/dist/types/src/providers/ai/opencode.d.ts

@@ -0,0 +1,2 @@
+import type { AIProviderDefinition } from './shared';
+export declare const OPENCODE_PROVIDER_DEFINITION: AIProviderDefinition;

package/dist/types/src/providers/ai/openrouter.d.ts

@@ -0,0 +1 @@
+export declare const OPENROUTER_PROVIDER_DEFINITION: import("./shared").AIProviderDefinition;

package/dist/types/src/providers/ai/shared.d.ts

@@ -0,0 +1,55 @@
+import { type ProviderConfigurationState } from '../ProviderConfiguration';
+import type { ProviderCredentialField } from '../ProviderDescriptor';
+import type { AICompleteRequest, AIKeyValidationResult, AIModelDescriptor, AIProviderAdapter, AIProviderCapabilities, AIRequestOptions } from './AIProvider';
+export type BuiltInAIProviderId = 'openai' | 'openrouter' | 'opencode' | 'openai-compatible' | 'deepseek' | 'gemini' | 'anthropic' | 'mistral' | 'glm';
+export type AIProviderDefinition = {
+    id: BuiltInAIProviderId;
+    label: string;
+    /** One-line description shown in a "connect this provider" UI. */
+    description?: string;
+    configKey?: string;
+    requiredConfigKeys?: string[];
+    defaultModel: string;
+    fallbackModels: string[];
+    /** URL to the provider's API key management page (shown in UI on validation error, and
+     * surfaced as ProviderDescriptor.credentialsUrl via toProviderDescriptor()). */
+    dashboardUrl?: string;
+    /** Credential fields a "connect" UI should collect (defaults to a single apiKey field
+     * when omitted — see toProviderDescriptor() in ./index.ts). */
+    credentialFields?: ProviderCredentialField[];
+    /** Short guidance on where in the dashboard to find the credential. */
+    credentialsHint?: string;
+    capabilities?: Omit<AIProviderCapabilities, 'models'>;
+    discoverModels: (apiKey: string) => Promise<string[]>;
+    complete: (apiKey: string, request: Required<Pick<AICompleteRequest, 'prompt' | 'model'>> & AIRequestOptions) => Promise<string | null>;
+    /**
+     * Per-provider auth check. When omitted, the default implementation in
+     * RuntimeAIProvider calls discoverModels() live (no cache) and treats any
+     * thrown error as invalid. Providers whose error format is non-standard or
+     * whose models endpoint is public MUST provide their own implementation.
+     */
+    validateApiKey?: (apiKey: string) => Promise<Omit<AIKeyValidationResult, 'dashboardUrl'>>;
+};
+export type AIModelCatalog = {
+    models: AIModelDescriptor[];
+    modelsByProvider: Record<string, AIModelDescriptor[]>;
+    capabilitiesByProvider: Record<string, AIProviderCapabilities>;
+};
+export declare const extractProviderError: (err: unknown) => string;
+export declare const createBrowserTransportError: (label: string) => Error;
+export declare const parseTextResponse: (value: unknown) => string | null;
+export declare const getAIModelCatalog: (registry: Record<string, AIProviderAdapter>, forceRefresh?: boolean) => Promise<AIModelCatalog>;
+export declare class RuntimeAIProvider implements AIProviderAdapter {
+    id: BuiltInAIProviderId;
+    label: string;
+    defaultModel: string;
+    dashboardUrl?: string;
+    private readonly definition;
+    private readonly apiKey;
+    constructor(definition: AIProviderDefinition, apiKey: string);
+    isConfigured(): boolean;
+    getConfigurationState(): ProviderConfigurationState;
+    getCapabilities(forceRefresh?: boolean): Promise<AIProviderCapabilities>;
+    complete(request: AICompleteRequest): Promise<string | null>;
+    validateApiKey(): Promise<AIKeyValidationResult>;
+}

package/dist/types/src/providers/api/ApiProvider.d.ts

@@ -0,0 +1,43 @@
+import type { ProviderConfigurable } from '../ProviderConfiguration';
+/**
+ * "api" — a real provider category (docs/24-tenant-platform.md, Service Gateway), same
+ * registry/lifecycle as data/storage/etc. Registers a third-party REST integration (Brevo,
+ * a payments API, a non-streaming AI provider, ...) once — base URL, fixed header/query/body
+ * fields (where a secret usually lives) — and exposes one generic call:
+ *
+ *   setProvider('api', 'payments', new DirectApiProviderAdapter({
+ *       baseUrl: 'https://payments.acme.com/api',
+ *       header: { Authorization: 'Bearer <secret>' },
+ *   }));
+ *
+ *   useApiProvider('payments').fetch({ path: '/charges', method: 'post', body: { amount: 1000 } });
+ *
+ * Registered/fixed fields always win over a matching key the caller passes — same
+ * authoritative-merge rule as the tenant-session handshake.
+ *
+ * Other category adapters (an EmailProviderAdapter for Brevo, an AIProviderAdapter for a
+ * REST-only model) call an ApiProviderAdapter internally instead of fetch()/proxyFetch()
+ * directly — a vendor adapter is just a few lines of normal code, no framework-provided bridge.
+ *
+ * Adapters (same interface, different execution context — mirrors DataProviderAdapter's
+ * Firebase/Supabase/Mock split), one file each like data/storage:
+ * - direct.ts   — DirectApiProviderAdapter, client-resident, via proxyFetch (CORS-safe). The
+ *   secret IS visible to the browser here — a dev/personal key, or a no-backend deploy, never
+ *   a real shared tenant secret.
+ * - firebase.ts — FirebaseApiProviderAdapter, routes through a Firebase Callable Function;
+ *   the secret lives server-side, resolved there from the real tenant/user registration.
+ * - supabase.ts — SupabaseApiProviderAdapter, same idea via a Supabase Edge Function.
+ * - mock.ts     — MockApiProviderAdapter, resolves via a local function, no network. Dev/tests.
+ */
+export type ApiProviderRequest = {
+    path: string;
+    /** Default: 'POST'. */
+    method?: string;
+    query?: Record<string, string>;
+    body?: unknown;
+};
+export interface ApiProviderAdapter extends ProviderConfigurable {
+    fetch(request: ApiProviderRequest): Promise<unknown>;
+}
+/** Convenience wrapper over useProvider('api', name) — same registry, just the ergonomic one-arg form. */
+export declare const useApiProvider: (name: string) => ApiProviderAdapter;

package/dist/types/src/providers/api/direct.d.ts

@@ -0,0 +1,14 @@
+import type { ApiProviderAdapter, ApiProviderRequest } from './ApiProvider';
+export type DirectApiProviderConfig = {
+    baseUrl: string;
+    /** Fixed fields merged into every call — this is where a secret normally lives. Always wins over a matching key in the request. */
+    header?: Record<string, string>;
+    query?: Record<string, string>;
+    body?: Record<string, unknown>;
+};
+/** Client-resident: calls the target directly via proxyFetch (CORS-safe). Secret visible to the browser — dev/personal key or no-backend deploy only. */
+export declare class DirectApiProviderAdapter implements ApiProviderAdapter {
+    private config;
+    constructor(config: DirectApiProviderConfig);
+    fetch(request: ApiProviderRequest): Promise<unknown>;
+}

package/dist/types/src/providers/api/firebase.d.ts

@@ -0,0 +1,14 @@
+import type { ApiProviderAdapter, ApiProviderRequest } from './ApiProvider';
+export type FirebaseApiProviderConfig = {
+    /** Name of the Callable Function that receives { provider, request } and does the real, secret-bearing call server-side. */
+    functionName: string;
+    /** The registered provider's own name — sent alongside the request so the function knows which registration to resolve. */
+    providerName: string;
+    region?: string;
+};
+/** Routes through a Firebase Callable Function — the secret lives server-side, resolved there from the real tenant/user registration. */
+export declare class FirebaseApiProviderAdapter implements ApiProviderAdapter {
+    private config;
+    constructor(config: FirebaseApiProviderConfig);
+    fetch(request: ApiProviderRequest): Promise<unknown>;
+}

package/dist/types/src/providers/api/mock.d.ts

@@ -0,0 +1,7 @@
+import type { ApiProviderAdapter, ApiProviderRequest } from './ApiProvider';
+/** Resolves via a local function, no network. Dev/tests. */
+export declare class MockApiProviderAdapter implements ApiProviderAdapter {
+    private resolver;
+    constructor(resolver: (request: ApiProviderRequest) => unknown | Promise<unknown>);
+    fetch(request: ApiProviderRequest): Promise<unknown>;
+}

package/dist/types/src/providers/api/supabase.d.ts

@@ -0,0 +1,14 @@
+import type { ApiProviderAdapter, ApiProviderRequest } from './ApiProvider';
+export type SupabaseApiProviderConfig = {
+    url: string;
+    anonKey: string;
+    /** Name of the Edge Function that receives { provider, request } and does the real, secret-bearing call server-side. */
+    functionName: string;
+    providerName: string;
+};
+/** Routes through a Supabase Edge Function — the secret lives server-side, resolved there from the real tenant/user registration. */
+export declare class SupabaseApiProviderAdapter implements ApiProviderAdapter {
+    private config;
+    constructor(config: SupabaseApiProviderConfig);
+    fetch(request: ApiProviderRequest): Promise<unknown>;
+}

package/dist/types/src/providers/auth/AuthProvider.d.ts

@@ -4,13 +4,13 @@ export interface UserProfile {
     email?: string;
     displayName?: string;
     photoURL?: string;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export type AuthIntent = 'signIn' | 'connect' | 'signOut' | 'disconnect' | 'reauthorize';
 export interface AuthSignInOptions {
     scopes?: string[];
     intent?: AuthIntent;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export interface AuthProviderAdapter extends ProviderConfigurable {
     getUser(): UserProfile | null;
@@ -19,4 +19,12 @@ export interface AuthProviderAdapter extends ProviderConfigurable {
     onAuthChange(callback: (user: UserProfile | null) => void): () => void;
     getAccessToken?(scopes?: string[]): Promise<string>;
     isAuthenticated?(): boolean;
+    /**
+     * Custom claims embedded in the current session's token (e.g. a JWT's payload),
+     * for providers backed by one — Firebase custom claims, a Supabase JWT, etc.
+     * Optional: providers with no token-claims concept (e.g. plain OAuth) omit it.
+     * Read-only/UI convenience — never a security boundary, the server always
+     * re-verifies the raw token itself rather than trusting client-read claims.
+     */
+    getIdTokenClaims?(): Promise<Record<string, unknown> | null>;
 }