@optimizely-opal/opal-tools-sdk 0.1.5-dev → 0.1.6-dev

package/.prettierignore

@@ -0,0 +1,5 @@
+.changeset/pre.json
+dist
+lib
+out
+package-lock.json

package/.prettierrc

@@ -0,0 +1 @@
+{}

package/README.md

@@ -4,36 +4,83 @@ This SDK simplifies the creation of tools services compatible with the Opal Tool
 
 ## Features
 
-- Easy definition of tool functions with decorators
-- Automatic generation of discovery endpoints
-- Parameter validation and type checking
+- Modern `registerTool` API with Zod schemas for type-safe tool definitions
+- Legacy `@tool` decorator API for backwards compatibility
+- Automatic type inference with Zod (registerTool only)
+- Adaptive Block Document support for rich interactive UIs
+- Runtime validation with Zod (registerTool only)
+- Automatic discovery endpoint generation
 - Authentication helpers
 - Express integration
-- Island components for interactive UI responses
 
 ## Installation
 
 ```bash
-npm install @optimizely-opal/opal-tools-sdk
+npm install @optimizely-opal/opal-tools-sdk express zod
 ```
 
-## Usage
+## Quick Start
+
+### `registerTool`
 
 ```typescript
-import { ToolsService, tool, IslandResponse, IslandConfig } from '@optimizely-opal/opal-tools-sdk';
-import express from 'express';
+import express from "express";
+import { z } from "zod";
+import { ToolsService, registerTool } from "@optimizely-opal/opal-tools-sdk";
 
 const app = express();
 const toolsService = new ToolsService(app);
 
+// ✨ Types are automatically inferred from the inputSchema!
+const getWeather = registerTool(
+  "get_weather",
+  {
+    description: "Gets current weather for a location",
+    inputSchema: {
+      location: z.string().describe("City name or location"),
+      units: z
+        .enum(["metric", "imperial"])
+        .optional()
+        .describe("Temperature units"),
+    },
+  },
+  async (params) => {
+    // params.location is typed as string
+    // params.units is typed as 'metric' | 'imperial' | undefined
+    return { temperature: 22, condition: "sunny" };
+  },
+);
+
+app.listen(3000);
+```
+
+### Legacy `@tool` Decorator API
+
+```typescript
+import { ToolsService, tool, ParameterType } from '@optimizely-opal/opal-tools-sdk';
+
 interface WeatherParameters {
   location: string;
-  units: string;
+  units?: string;
 }
 
 @tool({
   name: 'get_weather',
-  description: 'Gets current weather for a location'
+  description: 'Gets current weather for a location',
+  parameters: [
+    {
+      name: 'location',
+      type: ParameterType.String,
+      description: 'City name or location',
+      required: true,
+    },
+    {
+      name: 'units',
+      type: ParameterType.String,
+      description: 'Temperature units',
+      required: false,
+    },
+  ],
 })
 async function getWeather(parameters: WeatherParameters) {
   // Implementation...
@@ -45,232 +92,210 @@ async function getWeather(parameters: WeatherParameters) {
 
 ## Authentication
 
-The SDK provides two ways to require authentication for your tools:
+Both APIs support authentication. The second parameter of your handler receives the extra context object containing auth data.
 
-### 1. Using the `@requiresAuth` decorator
+### With `registerTool`
 
 ```typescript
-import { ToolsService, tool } from '@optimizely-opal/opal-tools-sdk';
-import { requiresAuth } from '@optimizely-opal/opal-tools-sdk/auth';
-import express from 'express';
-
-const app = express();
-const toolsService = new ToolsService(app);
-
-interface CalendarParameters {
-  date: string;
-  timezone?: string;
-}
-
-// Single authentication requirement
-@requiresAuth({ provider: 'google', scopeBundle: 'calendar', required: true })
-@tool({
-  name: 'get_calendar_events',
-  description: 'Gets calendar events for a date'
-})
-async function getCalendarEvents(parameters: CalendarParameters, authData?: any) {
-  // The authData parameter contains authentication information
-  const token = authData?.credentials?.token || '';
-  
-  // Use the token to make authenticated requests
-  // ...
-  
-  return { events: ['Meeting at 10:00', 'Lunch at 12:00'] };
-}
-
-// Multiple authentication requirements (tool can work with either provider)
-@requiresAuth({ provider: 'google', scopeBundle: 'calendar', required: true })
-@requiresAuth({ provider: 'microsoft', scopeBundle: 'outlook', required: true })
-@tool({
-  name: 'get_calendar_availability',
-  description: 'Check calendar availability'
-})
-async function getCalendarAvailability(parameters: CalendarParameters, authData?: any) {
-  const provider = authData?.provider || '';
-  const token = authData?.credentials?.token || '';
-  
-  if (provider === 'google') {
-    // Use Google Calendar API
-  } else if (provider === 'microsoft') {
-    // Use Microsoft Outlook API
-  }
-  
-  return { available: true, provider_used: provider };
-}
+import { z } from "zod";
+
+const getCalendarEvents = registerTool(
+  "get_calendar_events",
+  {
+    description: "Gets calendar events for a date",
+    inputSchema: {
+      date: z.string().describe("Date in YYYY-MM-DD format"),
+    },
+    authRequirements: {
+      provider: "google",
+      scopeBundle: "calendar",
+      required: true,
+    },
+  },
+  async (params, extra) => {
+    // Access auth data from extra context
+    const token = extra?.auth?.credentials?.access_token;
+    // Check execution mode if needed
+    const mode = extra?.mode; // 'headless' | 'interactive'
+
+    // Use token to make authenticated requests
+    return { events: ["Meeting at 10:00", "Lunch at 12:00"] };
+  },
+);
 ```
 
-### 2. Specifying auth requirements in the `@tool` decorator
+### With `@tool` Decorator
 
 ```typescript
-interface EmailParameters {
-  limit?: number;
-  folder?: string;
-}
-
 @tool({
-  name: 'get_email',
-  description: 'Gets emails from the user\'s inbox',
+  name: 'get_calendar_events',
+  description: 'Gets calendar events',
+  parameters: [
+    {
+      name: 'date',
+      type: ParameterType.String,
+      description: 'Date in YYYY-MM-DD format',
+      required: true,
+    },
+  ],
   authRequirements: {
     provider: 'google',
-    scopeBundle: 'gmail',
-    required: true
-  }
+    scopeBundle: 'calendar',
+    required: true,
+  },
 })
-async function getEmail(parameters: EmailParameters, authData?: any) {
-  // Implementation...
-  return { emails: ['Email 1', 'Email 2'] };
+async function getCalendarEvents(params: any, environment?: any) {
+  const token = environment?.auth?.credentials?.access_token;
+  return { events: [] };
 }
 ```
 
-## Authentication
-
-The SDK provides authentication support for tools that require user credentials:
+## Adaptive Block Documents
 
-```typescript
-import { ToolsService, tool, requiresAuth, AuthData } from '@optimizely-opal/opal-tools-sdk';
-import express from 'express';
-
-interface CalendarParameters {
-  date: string;
-  timezone?: string;
-}
+Adaptive Block Documents enable rich, interactive UI responses with forms, buttons, and dynamic content.
 
-const app = express();
-const toolsService = new ToolsService(app);
+### Creating Adaptive Block Responses
 
-@requiresAuth({ provider: 'google', scopeBundle: 'calendar', required: true })
-@tool({
-  name: 'get_calendar_events',
-  description: 'Gets calendar events for a date'
-})
-async function getCalendarEvents(parameters: CalendarParameters, authData?: AuthData) {
-  // The authData parameter contains authentication information
-  if (authData) {
-    const token = authData.credentials.access_token;
-    // Use the token to make authenticated requests
-  }
-
-  return { events: ['Meeting at 10:00', 'Lunch at 12:00'] };
-}
+```typescript
+import { z } from "zod";
+import { registerTool, Block } from "@optimizely-opal/opal-tools-sdk";
+
+const createTask = registerTool(
+  "create_task",
+  {
+    description: "Create a new task",
+    type: "block", // Specify this is an Adaptive Block tool
+    inputSchema: {
+      title: z.string().describe("Task title"),
+      description: z.string().optional().describe("Task description"),
+    },
+  },
+  async (params) => {
+    // Return a BlockResponse (plain object with content/data/artifact/etc)
+    return {
+      content: Block.Document({
+        children: [
+          Block.Heading({ children: "Task Created!", level: "1" }),
+          Block.Text({ children: `Created: ${params.title}` }),
+          Block.Input({
+            name: "notes",
+            placeholder: "Add notes...",
+            value: params.description || "",
+          }),
+        ],
+        actions: [
+          Block.Action({ name: "save", children: "Save Changes" }),
+          Block.Action({
+            name: "delete",
+            children: "Delete",
+            variant: "danger",
+          }),
+        ],
+      }),
+      data: { task_id: "123", created_at: new Date().toISOString() },
+      artifact: {
+        type: "task",
+        id: "task-123",
+        data: { title: params.title },
+      },
+    };
+  },
+);
 ```
 
-## Island Components
+### Adaptive Block Components
 
-The SDK includes Island components for creating interactive UI responses:
+The SDK provides a type-safe `Block` namespace with factory functions for all components:
 
-```typescript
-import { 
-  ToolsService, 
-  tool, 
-  IslandResponse, 
-  IslandConfig
-} from '@optimizely-opal/opal-tools-sdk';
-import express from 'express';
+- `Block.Document()` - Root container with children and actions
+- `Block.Heading()` - Headings with levels 1-6
+- `Block.Text()` - Text content
+- `Block.Input()` - Text input fields
+- `Block.Textarea()` - Multi-line text areas
+- `Block.Checkbox()` - Checkbox inputs
+- `Block.Select()` - Dropdown selects
+- `Block.Button()` - Action buttons
+- `Block.Action()` - Document-level actions
+- `Block.List()` - Ordered/unordered lists
+- `Block.Table()` - Data tables
+- And more...
 
-interface WeatherParameters {
-  location: string;
-  units?: string;
-}
+See the generated [src/block.ts](./src/block.ts) for the complete list and TypeScript types.
 
-const app = express();
-const toolsService = new ToolsService(app);
+### Regenerating Adaptive Block Types
 
-@tool({
-  name: 'get_weather',
-  description: 'Gets current weather for a location'
-})
-async function getWeather(parameters: WeatherParameters) {
-  // Get weather data (implementation details omitted)
-  const weatherData = { temperature: 22, condition: 'sunny', humidity: 65 };
-  
-  // Create an interactive island for weather settings
-  const island = new IslandConfig(
-    [
-      new IslandConfig.Field(
-        'location',
-        'Location',
-        'string',
-        parameters.location
-      ),
-      new IslandConfig.Field(
-        'units',
-        'Temperature Units',
-        'string',
-        parameters.units || 'metric',
-        false,
-        ['metric', 'imperial', 'kelvin']
-      ),
-      new IslandConfig.Field(
-        'current_temp',
-        'Current Temperature',
-        'string',
-        `${weatherData.temperature}°${parameters.units === 'metric' ? 'C' : 'F'}`
-      )
-    ],
-    [
-      new IslandConfig.Action(
-        'refresh_weather',
-        'Refresh Weather',
-        'button',
-        '/tools/get_weather',
-        'update'
-      )
-    ],
-    'button',  // Optional island type
-    'plus'     // Optional island icon
-  );
-  
-  return IslandResponse.create([island]);
-}
+The Adaptive Block types are auto-generated from the JSON schema. To regenerate:
+
+```bash
+npm run generate:block
 ```
 
-### Island Components
-
-#### IslandConfig.Field
-Fields represent data inputs in the UI:
-- `name`: Programmatic field identifier
-- `label`: Human-readable label
-- `type`: Field type (`'string'`, `'boolean'`, `'json'`)
-- `value`: Current field value (optional)
-- `hidden`: Whether to hide from user (optional, default: false)
-- `options`: Available options for selection (optional)
-
-#### IslandConfig.Action
-Actions represent buttons or operations:
-- `name`: Programmatic action identifier
-- `label`: Human-readable button label
-- `type`: UI element type (typically `'button'`)
-- `endpoint`: API endpoint to call
-- `operation`: Operation type (default: `'create'`)
-
-#### IslandConfig
-Contains the complete island configuration:
-- `fields`: Array of IslandConfig.Field objects
-- `actions`: Array of IslandConfig.Action objects
-- `type`: Optional island type for custom rendering (optional)
-- `icon`: Optional icon identifier for the island (optional)
-
-#### IslandResponse
-The response wrapper for islands:
-- Use `IslandResponse.create([islands])` to create responses
-- Supports multiple islands per response
+This reads `block-document-spec.json` and generates TypeScript interfaces and factory functions in [src/block.ts](./src/block.ts).
+
+**Note:** Don't edit `src/block.ts` manually - it will be overwritten on regeneration.
 
 ## Type Definitions
 
 The SDK provides comprehensive TypeScript type definitions:
 
 ### Authentication Types
-- `AuthData`: Interface containing provider and credentials information
-- `Credentials`: Interface with access_token, org_sso_id, customer_id, instance_id, and product_sku
-- `Environment`: Interface specifying execution mode (`'headless'` or `'interactive'`)
+
+- `AuthData` - Provider and credentials information
+- `Credentials` - Access tokens and org details
+- `Environment` - Execution context with auth data
 
 ### Parameter Types
-- `ParameterType`: Enum for supported parameter types
-- `Parameter`: Class for tool parameter definitions
-- `Function`: Class for complete tool function definitions
 
-These types provide full IDE support and compile-time type checking for better development experience.
+- `ParameterType` - Enum for parameter types (String, Number, Boolean, List, Dictionary)
+- `Parameter` - Tool parameter definitions
+- `Function` - Complete tool function definitions
+
+### Block Types
+
+All Block Document components have full TypeScript interfaces with type checking and IDE autocomplete.
+
+## API Reference
+
+### `registerTool<TSchema, TReturn>(name, options, handler)`
+
+Modern API for defining tools with Zod schemas.
+
+**Parameters:**
+
+- `name: string` - Tool name (required)
+- `options: ToolOptions` - Configuration object
+  - `description: string` - Tool description (required)
+  - `inputSchema: Record<string, z.ZodTypeAny>` - Zod schema for parameters (required)
+  - `type?: 'json' | 'block'` - Response type (default: 'json')
+  - `authRequirements?` - Authentication requirements
+- `handler: (params, extra?) => Result` - Tool implementation
+  - `params` - Validated input parameters (typed from schema)
+  - `extra?` - Optional extra context
+    - `mode: 'headless' | 'interactive'` - Execution mode
+    - `auth?: { provider, credentials }` - Auth data if provided
+
+**Returns:** The handler function with full type inference
+
+### `@tool(options)`
+
+Legacy decorator for defining tools.
+
+**Options:**
+
+- `name: string` - Tool name
+- `description: string` - Tool description
+- `parameters: ParameterDefinition[]` - Parameter definitions
+- `authRequirements?` - Authentication requirements
+
+### `ToolsService`
+
+Express service that manages tool registration and creates discovery endpoints.
+
+```typescript
+const toolsService = new ToolsService(app);
+// Automatically creates /discovery endpoint
+```
 
-## Documentation
+## License
 
-See full documentation for more examples and configuration options.
+MIT

package/dist/auth.d.ts

@@ -1,3 +1,8 @@
+interface AuthOptions {
+    provider: string;
+    required?: boolean;
+    scopeBundle: string;
+}
 /**
  * Middleware to handle authentication requirements
  * @param req Express request
@@ -5,11 +10,6 @@
  * @param next Express next function
  */
 export declare function authMiddleware(req: any, res: any, next: any): any;
-interface AuthOptions {
-    provider: string;
-    scopeBundle: string;
-    required?: boolean;
-}
 /**
  * Decorator to indicate that a tool requires authentication
  * @param options Authentication options

package/dist/auth.js

@@ -11,7 +11,7 @@ exports.requiresAuth = requiresAuth;
 function authMiddleware(req, res, next) {
     const authHeader = req.headers.authorization;
     if (!authHeader && req.authRequired) {
-        return res.status(401).json({ error: 'Authentication required' });
+        return res.status(401).json({ error: "Authentication required" });
     }
     // The Tools Management Service will provide the appropriate token
     // in the Authorization header
@@ -31,8 +31,8 @@ function requiresAuth(options) {
                 const fn = originalMethod;
                 fn.__authRequirements__ = {
                     provider: options.provider,
+                    required: options.required ?? true,
                     scopeBundle: options.scopeBundle,
-                    required: options.required ?? true
                 };
                 return originalMethod.apply(this, args);
             };