@prodact.ai/sdk 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Viam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @viam/sdk
+
+Interactive SDK for Viam - AI-powered UI interactions triggered by chat.
+
+## Installation
+
+```bash
+npm install @viam/sdk
+```
+
+## Quick Start
+
+### React
+
+```tsx
+import { ViamProvider, ViamChat, useViamAction } from '@viam/sdk/react';
+
+function App() {
+  return (
+    <ViamProvider
+      config={{
+        guiderId: 'your-guider-id',
+        apiUrl: 'https://api.viam.io/api/v1', // optional
+      }}
+    >
+      <MyApp />
+      <ViamChat position="bottom-right" />
+    </ViamProvider>
+  );
+}
+
+function ContactButton() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  // Register action - when user asks "open contact modal", this triggers
+  useViamAction('act_contact_xyz123', () => {
+    setIsOpen(true);
+  });
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Contact Us</button>
+      {isOpen && <ContactModal onClose={() => setIsOpen(false)} />}
+    </>
+  );
+}
+```
+
+### Using ViamTarget
+
+Wrap elements to auto-highlight and scroll when triggered:
+
+```tsx
+import { ViamTarget } from '@viam/sdk/react';
+
+function PricingSection() {
+  return (
+    <ViamTarget
+      actionKey="act_pricing_abc123"
+      onTrigger={() => console.log('User was directed to pricing!')}
+    >
+      <div className="pricing-section">
+        <h2>Pricing</h2>
+        {/* ... */}
+      </div>
+    </ViamTarget>
+  );
+}
+```
+
+### Vanilla JavaScript
+
+```javascript
+import { createViam } from '@viam/sdk';
+
+const viam = createViam({
+  guiderId: 'your-guider-id',
+});
+
+// Initialize
+await viam.init();
+
+// Register actions
+viam.register('act_contact_xyz123', (payload) => {
+  document.getElementById('contact-modal').classList.add('open');
+});
+
+// Send a message
+const response = await viam.sendMessage('How do I contact support?');
+// If message matches "contact" action, it will trigger automatically
+```
+
+## API Reference
+
+### ViamProvider Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config.guiderId` | `string` | Your Viam guider ID (required) |
+| `config.apiUrl` | `string` | API URL (default: `http://localhost:4001/api/v1`) |
+| `onAction` | `(key, payload) => void` | Called when any action is triggered |
+| `onError` | `(error) => void` | Called on errors |
+
+### ViamChat Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `'bottom-right' \| 'bottom-left' \| 'inline'` | `'bottom-right'` | Chat widget position |
+| `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
+| `primaryColor` | `string` | `'#f97316'` | Primary accent color |
+| `title` | `string` | `'Chat Assistant'` | Chat header title |
+| `placeholder` | `string` | `'Ask a question...'` | Input placeholder |
+
+### Hooks
+
+#### `useViam()`
+Returns the full Viam context with SDK instance, messages, and methods.
+
+#### `useViamAction(actionKey, handler, deps?)`
+Register an action handler that fires when the AI triggers this action.
+
+#### `useViamMessages()`
+Returns `{ messages, isLoading, sendMessage }` for building custom chat UIs.
+
+#### `useViamReady()`
+Returns `boolean` indicating if SDK is initialized.
+
+### ViamTarget Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `actionKey` | `string` | The action key to respond to (required) |
+| `onTrigger` | `(payload) => void` | Called when action is triggered |
+| `highlightStyle` | `CSSProperties` | Custom highlight styles |
+| `highlightDuration` | `number` | How long to highlight (ms, default: 3000) |
+| `scrollIntoView` | `boolean` | Auto-scroll to element (default: true) |
+
+## Setting Up Actions
+
+1. Go to your Viam dashboard
+2. Navigate to your Guider → SDK tab
+3. Enable SDK integration
+4. Create actions with trigger prompts:
+   - Name: "Open Contact Modal"
+   - Prompts: "contact support", "get in touch", "talk to someone"
+5. Copy the generated action key (e.g., `act_contact_x7y8z9`)
+6. Use the key in your code with `useViamAction` or `viam.register()`
+
+## How It Works
+
+1. User types a message in the chat
+2. AI analyzes if message matches any configured SDK action
+3. If matched, the registered handler is called
+4. Chat displays a response confirming the action
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,135 @@
+interface ProduckConfig {
+    guiderId?: string;
+    sdkKey?: string;
+    apiUrl?: string;
+    onAction?: (actionKey: string, action: ActionPayload) => void;
+    onMessage?: (message: ChatMessage) => void;
+    onError?: (error: Error) => void;
+    onFlowStart?: (flow: FlowPayload) => void;
+    onFlowStepComplete?: (step: FlowStepResult, flow: FlowPayload) => void;
+    onFlowComplete?: (result: FlowResult) => void;
+}
+interface ActionPayload {
+    actionKey: string;
+    name: string;
+    actionType: string;
+    actionConfig: Record<string, any>;
+    responseMessage?: string;
+}
+interface FlowStep {
+    operationId: string;
+    order: number;
+    condition?: Record<string, any>;
+    inputMapping?: Record<string, any>;
+}
+interface FlowPayload {
+    flowId: string;
+    name: string;
+    description: string;
+    steps: FlowStep[];
+}
+interface FlowStepResult {
+    operationId: string;
+    order: number;
+    success: boolean;
+    data?: any;
+    error?: string;
+}
+interface FlowResult {
+    flowId: string;
+    name: string;
+    steps: FlowStepResult[];
+    completed: boolean;
+    totalSteps: number;
+    successfulSteps: number;
+}
+interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    action?: ActionPayload;
+    flow?: FlowPayload;
+    flowResult?: FlowResult;
+}
+interface ActionHandler {
+    (payload: ActionPayload): void | Promise<void>;
+}
+interface RegisteredAction {
+    key: string;
+    handler: ActionHandler;
+}
+type ProduckEventType = 'action' | 'message' | 'error' | 'ready' | 'flowStart' | 'flowStepComplete' | 'flowComplete';
+interface ProduckEvent {
+    type: ProduckEventType;
+    data: any;
+}
+declare class ProduckSDK {
+    private config;
+    private actions;
+    private eventListeners;
+    private sessionToken;
+    private isReady;
+    constructor(config: ProduckConfig);
+    /**
+     * Initialize the SDK and create a chat session
+     */
+    init(): Promise<void>;
+    /**
+     * Register an action handler
+     */
+    register(actionKey: string, handler: ActionHandler): void;
+    /**
+     * Unregister an action handler
+     */
+    unregister(actionKey: string): void;
+    /**
+     * Send a message and handle potential action or flow triggers
+     */
+    sendMessage(message: string): Promise<ChatMessage>;
+    /**
+     * Execute a flow by running each step's operation sequentially
+     */
+    executeFlow(flow: FlowPayload): Promise<FlowResult>;
+    /**
+     * Send log data to backend for analytics
+     */
+    private sendLogToBackend;
+    /**
+     * Send detailed log to backend
+     */
+    private log;
+    /**
+     * Execute a registered action
+     */
+    private executeAction;
+    /**
+     * Add event listener
+     */
+    on(event: ProduckEventType, callback: Function): void;
+    /**
+     * Remove event listener
+     */
+    off(event: ProduckEventType, callback: Function): void;
+    /**
+     * Emit event
+     */
+    private emit;
+    /**
+     * Get session token
+     */
+    getSessionToken(): string | null;
+    /**
+     * Check if SDK is ready
+     */
+    getIsReady(): boolean;
+    /**
+     * Get registered action keys
+     */
+    getRegisteredActions(): string[];
+    /**
+     * Destroy the SDK instance
+     */
+    destroy(): void;
+}
+declare function createProduck(config: ProduckConfig): ProduckSDK;
+
+export { type ActionHandler, type ActionPayload, type ChatMessage, type FlowPayload, type FlowResult, type FlowStep, type FlowStepResult, type ProduckConfig, type ProduckEvent, type ProduckEventType, ProduckSDK, type RegisteredAction, createProduck };

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+interface ProduckConfig {
+    guiderId?: string;
+    sdkKey?: string;
+    apiUrl?: string;
+    onAction?: (actionKey: string, action: ActionPayload) => void;
+    onMessage?: (message: ChatMessage) => void;
+    onError?: (error: Error) => void;
+    onFlowStart?: (flow: FlowPayload) => void;
+    onFlowStepComplete?: (step: FlowStepResult, flow: FlowPayload) => void;
+    onFlowComplete?: (result: FlowResult) => void;
+}
+interface ActionPayload {
+    actionKey: string;
+    name: string;
+    actionType: string;
+    actionConfig: Record<string, any>;
+    responseMessage?: string;
+}
+interface FlowStep {
+    operationId: string;
+    order: number;
+    condition?: Record<string, any>;
+    inputMapping?: Record<string, any>;
+}
+interface FlowPayload {
+    flowId: string;
+    name: string;
+    description: string;
+    steps: FlowStep[];
+}
+interface FlowStepResult {
+    operationId: string;
+    order: number;
+    success: boolean;
+    data?: any;
+    error?: string;
+}
+interface FlowResult {
+    flowId: string;
+    name: string;
+    steps: FlowStepResult[];
+    completed: boolean;
+    totalSteps: number;
+    successfulSteps: number;
+}
+interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    action?: ActionPayload;
+    flow?: FlowPayload;
+    flowResult?: FlowResult;
+}
+interface ActionHandler {
+    (payload: ActionPayload): void | Promise<void>;
+}
+interface RegisteredAction {
+    key: string;
+    handler: ActionHandler;
+}
+type ProduckEventType = 'action' | 'message' | 'error' | 'ready' | 'flowStart' | 'flowStepComplete' | 'flowComplete';
+interface ProduckEvent {
+    type: ProduckEventType;
+    data: any;
+}
+declare class ProduckSDK {
+    private config;
+    private actions;
+    private eventListeners;
+    private sessionToken;
+    private isReady;
+    constructor(config: ProduckConfig);
+    /**
+     * Initialize the SDK and create a chat session
+     */
+    init(): Promise<void>;
+    /**
+     * Register an action handler
+     */
+    register(actionKey: string, handler: ActionHandler): void;
+    /**
+     * Unregister an action handler
+     */
+    unregister(actionKey: string): void;
+    /**
+     * Send a message and handle potential action or flow triggers
+     */
+    sendMessage(message: string): Promise<ChatMessage>;
+    /**
+     * Execute a flow by running each step's operation sequentially
+     */
+    executeFlow(flow: FlowPayload): Promise<FlowResult>;
+    /**
+     * Send log data to backend for analytics
+     */
+    private sendLogToBackend;
+    /**
+     * Send detailed log to backend
+     */
+    private log;
+    /**
+     * Execute a registered action
+     */
+    private executeAction;
+    /**
+     * Add event listener
+     */
+    on(event: ProduckEventType, callback: Function): void;
+    /**
+     * Remove event listener
+     */
+    off(event: ProduckEventType, callback: Function): void;
+    /**
+     * Emit event
+     */
+    private emit;
+    /**
+     * Get session token
+     */
+    getSessionToken(): string | null;
+    /**
+     * Check if SDK is ready
+     */
+    getIsReady(): boolean;
+    /**
+     * Get registered action keys
+     */
+    getRegisteredActions(): string[];
+    /**
+     * Destroy the SDK instance
+     */
+    destroy(): void;
+}
+declare function createProduck(config: ProduckConfig): ProduckSDK;
+
+export { type ActionHandler, type ActionPayload, type ChatMessage, type FlowPayload, type FlowResult, type FlowStep, type FlowStepResult, type ProduckConfig, type ProduckEvent, type ProduckEventType, ProduckSDK, type RegisteredAction, createProduck };