@ggui-ai/protocol 0.1.0-rc.1

package/dist/types/data-bindings.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Client-side data-binding subsystem for React Native controllers.
+ *
+ * **NOT to be confused with {@link ClientCapabilitiesSpec} on
+ * `DataContract.clientCapabilities`.** These types describe the
+ * data-RESOLVER toolkit consumed by `@ggui-ai/ggui-react-native`
+ * (`fetch` / `auth` / `storage` / `subscription` / `voice` / `camera` /
+ * `chain` / `transform` / `merge`) — the controllers wire one of these
+ * tool configs onto a binding name and the runtime resolves the value
+ * at render time.
+ *
+ * `clientCapabilities.gadgets` is the wire-level declaration that the
+ * UI calls a browser-capability hook (`useMicrophone` /
+ * `useGeolocation` / `useClipboardWrite` / …); those hooks are
+ * implemented in `@ggui-ai/gadgets` and surfaced into the
+ * agent only when the UI threads their value into a `contextSpec` slot
+ * or an `actionSpec` payload.
+ *
+ * The shared word "tool" is historical:
+ *
+ *   - `ClientToolName` here = a runtime data-resolver identifier.
+ *   - `clientCapabilities.gadgets` = a package-keyed wire map
+ *     (`Record<package, Record<exportName, GadgetExportUse>>`); the
+ *     export name is the inner map key, not a field.
+ *   - `agentCapabilities.tools` = MCP tool catalog.
+ *
+ * All three are distinct namespaces.
+ */
+import type { JsonObject, JsonValue } from './data-contract';
+import type { EndUserIdentity } from './auth';
+/**
+ * Available client-side tools
+ */
+export type ClientToolName = 'fetch' | 'auth' | 'storage' | 'subscription' | 'voice' | 'camera' | 'chain' | 'transform' | 'merge';
+/**
+ * Base configuration for all tools.
+ * Extends {@link JsonObject} for JSON serialization compatibility.
+ * Generic `TConfig` defaults to {@link JsonObject} for the tool-specific configuration shape.
+ */
+export interface ClientToolConfig<TConfig extends JsonObject = JsonObject> extends JsonObject {
+    tool: ClientToolName;
+    config: TConfig;
+    /**
+     * Other bindings this depends on (resolved first in topological order)
+     * Example: ['user'] means this tool waits for 'user' binding to resolve
+     */
+    dependsOn?: string[];
+}
+/**
+ * Fetch tool - HTTP requests with interpolation support
+ *
+ * Example:
+ * ```
+ * { tool: 'fetch', config: { endpoint: '/api/users/{user.id}' } }
+ * ```
+ */
+export interface FetchToolConfig extends ClientToolConfig {
+    tool: 'fetch';
+    config: {
+        /**
+         * Endpoint with optional interpolation: '/api/users/{user.id}'
+         * Values in braces are replaced from resolved dependencies
+         */
+        endpoint: string;
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+        headers?: Record<string, string>;
+        /** Request body. Typed as {@link JsonValue} (any JSON-safe value). */
+        body?: JsonValue;
+        /**
+         * Cache configuration
+         */
+        cache?: {
+            /** Time-to-live in milliseconds */
+            ttl: number;
+            /** Cache key (defaults to endpoint) */
+            key?: string;
+        };
+        /**
+         * Transform response before returning
+         * Dot path to extract: 'data.users' extracts response.data.users
+         */
+        extract?: string;
+    };
+}
+/**
+ * Auth tool - Access authentication context
+ *
+ * Example:
+ * ```
+ * { tool: 'auth', config: { field: 'currentUser' } }
+ * ```
+ */
+export interface AuthToolConfig extends ClientToolConfig {
+    tool: 'auth';
+    config: {
+        /**
+         * Field to extract from auth context
+         * - 'currentUser': Full user object
+         * - 'userId': Just the user ID
+         * - 'token': Access token
+         * - 'isAuthenticated': Boolean
+         */
+        field: 'currentUser' | 'userId' | 'token' | 'isAuthenticated' | string;
+    };
+}
+/**
+ * Storage tool - localStorage/sessionStorage access
+ *
+ * Example:
+ * ```
+ * { tool: 'storage', config: { key: 'userPrefs', storage: 'local' } }
+ * ```
+ */
+export interface StorageToolConfig extends ClientToolConfig {
+    tool: 'storage';
+    config: {
+        key: string;
+        storage?: 'local' | 'session';
+        /** Default value if key doesn't exist. Typed as {@link JsonValue}. */
+        defaultValue?: JsonValue;
+        /** Parse as JSON (default: true) */
+        parse?: boolean;
+    };
+}
+/**
+ * Subscription tool - Real-time data subscriptions
+ *
+ * Example:
+ * ```
+ * { tool: 'subscription', config: { channel: 'notifications/{user.id}' } }
+ * ```
+ */
+export interface SubscriptionToolConfig extends ClientToolConfig {
+    tool: 'subscription';
+    config: {
+        /** Channel/topic with optional interpolation */
+        channel: string;
+        /** Protocol type */
+        type?: 'websocket' | 'sse' | 'polling';
+        /** Polling interval in ms (for polling type) */
+        interval?: number;
+        /** Initial data before first message. Typed as {@link JsonValue}. */
+        initialData?: JsonValue;
+    };
+}
+/**
+ * Voice tool - Voice input/output
+ */
+export interface VoiceToolConfig extends ClientToolConfig {
+    tool: 'voice';
+    config: {
+        mode: 'input' | 'output' | 'both';
+        language?: string;
+        continuous?: boolean;
+    };
+}
+/**
+ * Camera tool - Camera access
+ */
+export interface CameraToolConfig extends ClientToolConfig {
+    tool: 'camera';
+    config: {
+        mode: 'photo' | 'video' | 'stream';
+        facing?: 'user' | 'environment';
+        resolution?: {
+            width: number;
+            height: number;
+        };
+    };
+}
+/**
+ * Chain tool - Sequential execution of tools
+ * Each step receives previous result as {prev}
+ *
+ * Example:
+ * ```
+ * {
+ *   tool: 'chain',
+ *   config: {
+ *     steps: [
+ *       { tool: 'auth', config: { field: 'currentUser' } },
+ *       { tool: 'fetch', config: { endpoint: '/api/dashboard/{prev.id}' } },
+ *       { tool: 'transform', config: { pick: ['stats', 'notifications'] } }
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+export interface ChainToolConfig extends ClientToolConfig {
+    tool: 'chain';
+    config: {
+        /** Sequential tool steps, each receives previous result as {prev} */
+        steps: ClientToolConfig[];
+    };
+}
+/**
+ * Transform tool - Data transformation
+ *
+ * Example:
+ * ```
+ * { tool: 'transform', config: { pick: ['name', 'email'], rename: { email: 'contactEmail' } } }
+ * ```
+ */
+export interface TransformToolConfig<TDefaults extends JsonObject = JsonObject> extends ClientToolConfig {
+    tool: 'transform';
+    config: {
+        /** Pick specific fields from data */
+        pick?: string[];
+        /** Omit specific fields from data */
+        omit?: string[];
+        /** Rename fields: { oldName: 'newName' } */
+        rename?: Record<string, string>;
+        /** Map array items through a transformation */
+        mapArray?: {
+            /** Field containing array */
+            field?: string;
+            /** Fields to pick from each item */
+            pick?: string[];
+            /** Fields to rename in each item */
+            rename?: Record<string, string>;
+        };
+        /** Flatten nested object: 'user.profile' moves profile fields to top level */
+        flatten?: string;
+        /** Default values for missing fields */
+        defaults?: TDefaults;
+    };
+}
+/**
+ * Merge tool - Combine multiple data sources
+ *
+ * Example:
+ * ```
+ * {
+ *   tool: 'merge',
+ *   config: { sources: ['user', 'profile', 'settings'] },
+ *   dependsOn: ['user', 'profile', 'settings']
+ * }
+ * ```
+ */
+export interface MergeToolConfig extends ClientToolConfig {
+    tool: 'merge';
+    config: {
+        /** Binding names to merge (must be in dependsOn) */
+        sources: string[];
+        /** How to handle conflicts */
+        strategy?: 'first' | 'last' | 'deep';
+        /** Rename sources in merged result */
+        rename?: Record<string, string>;
+    };
+}
+/**
+ * Type-safe tool config union
+ */
+export type TypedToolConfig = FetchToolConfig | AuthToolConfig | StorageToolConfig | SubscriptionToolConfig | VoiceToolConfig | CameraToolConfig | ChainToolConfig | TransformToolConfig | MergeToolConfig;
+/**
+ * Data bindings - map of binding names to tool configurations
+ *
+ * Example:
+ * ```
+ * const bindings: DataBindings = {
+ *   user: { tool: 'auth', config: { field: 'currentUser' } },
+ *   profile: {
+ *     tool: 'fetch',
+ *     config: { endpoint: '/api/users/{user.id}/profile' },
+ *     dependsOn: ['user']
+ *   }
+ * };
+ * ```
+ */
+export type DataBindings = Record<string, TypedToolConfig>;
+/**
+ * Context provided to tool execution.
+ * Generic `TResolved` defaults to {@link JsonObject} for the resolved dependency values.
+ */
+export interface ToolContext<TResolved = JsonObject> {
+    /** Resolved values from previous bindings */
+    resolved: TResolved;
+    /** Auth context (user, token, etc.) */
+    auth?: {
+        currentUser?: EndUserIdentity;
+        userId?: string;
+        token?: string;
+        isAuthenticated: boolean;
+    };
+    /** App configuration */
+    appId: string;
+    sessionId: string;
+    /** Base URL for API calls */
+    apiBaseUrl?: string;
+}
+/**
+ * Result from tool execution
+ */
+export interface ToolResult<T = unknown> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Tool implementation interface
+ */
+export interface ClientTool<TConfig extends ClientToolConfig = ClientToolConfig> {
+    name: ClientToolName;
+    /**
+     * Execute the tool with given config and context
+     */
+    execute(config: TConfig['config'], context: ToolContext): Promise<unknown>;
+}
+/**
+ * Controller metadata - describes what props a controller expects
+ * Note: Actual controller components receive children as ReactNode,
+ * but we use 'unknown' here to avoid React dependency in shared package.
+ */
+export interface ControllerPropSpec {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    required: boolean;
+    description: string;
+    /** Default value for this prop. Typed as {@link JsonValue}. */
+    defaultValue?: JsonValue;
+}
+//# sourceMappingURL=data-bindings.d.ts.map

package/dist/types/data-bindings.d.ts.map

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

package/dist/types/data-bindings.js

@@ -0,0 +1,29 @@
+/**
+ * Client-side data-binding subsystem for React Native controllers.
+ *
+ * **NOT to be confused with {@link ClientCapabilitiesSpec} on
+ * `DataContract.clientCapabilities`.** These types describe the
+ * data-RESOLVER toolkit consumed by `@ggui-ai/ggui-react-native`
+ * (`fetch` / `auth` / `storage` / `subscription` / `voice` / `camera` /
+ * `chain` / `transform` / `merge`) — the controllers wire one of these
+ * tool configs onto a binding name and the runtime resolves the value
+ * at render time.
+ *
+ * `clientCapabilities.gadgets` is the wire-level declaration that the
+ * UI calls a browser-capability hook (`useMicrophone` /
+ * `useGeolocation` / `useClipboardWrite` / …); those hooks are
+ * implemented in `@ggui-ai/gadgets` and surfaced into the
+ * agent only when the UI threads their value into a `contextSpec` slot
+ * or an `actionSpec` payload.
+ *
+ * The shared word "tool" is historical:
+ *
+ *   - `ClientToolName` here = a runtime data-resolver identifier.
+ *   - `clientCapabilities.gadgets` = a package-keyed wire map
+ *     (`Record<package, Record<exportName, GadgetExportUse>>`); the
+ *     export name is the inner map key, not a field.
+ *   - `agentCapabilities.tools` = MCP tool catalog.
+ *
+ * All three are distinct namespaces.
+ */
+export {};