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

package/README.md

@@ -4,83 +4,36 @@ This SDK simplifies the creation of tools services compatible with the Opal Tool
 
 ## Features
 
-- 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
+- Easy definition of tool functions with decorators
+- Automatic generation of discovery endpoints
+- Parameter validation and type checking
 - Authentication helpers
 - Express integration
+- Island components for interactive UI responses
 
 ## Installation
 
 ```bash
-npm install @optimizely-opal/opal-tools-sdk express zod
+npm install @optimizely-opal/opal-tools-sdk
 ```
 
-## Quick Start
-
-### `registerTool`
+## Usage
 
 ```typescript
-import express from "express";
-import { z } from "zod";
-import { ToolsService, registerTool } from "@optimizely-opal/opal-tools-sdk";
+import { ToolsService, tool, IslandResponse, IslandConfig } from '@optimizely-opal/opal-tools-sdk';
+import express from 'express';
 
 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',
-  parameters: [
-    {
-      name: 'location',
-      type: ParameterType.String,
-      description: 'City name or location',
-      required: true,
-    },
-    {
-      name: 'units',
-      type: ParameterType.String,
-      description: 'Temperature units',
-      required: false,
-    },
-  ],
+  description: 'Gets current weather for a location'
 })
 async function getWeather(parameters: WeatherParameters) {
   // Implementation...
@@ -92,210 +45,242 @@ async function getWeather(parameters: WeatherParameters) {
 
 ## Authentication
 
-Both APIs support authentication. The second parameter of your handler receives the extra context object containing auth data.
+The SDK provides two ways to require authentication for your tools:
 
-### With `registerTool`
+### 1. Using the `@requiresAuth` decorator
 
 ```typescript
-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"] };
-  },
-);
+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 };
+}
 ```
 
-### With `@tool` Decorator
+### 2. Specifying auth requirements in the `@tool` decorator
 
 ```typescript
+interface EmailParameters {
+  limit?: number;
+  folder?: string;
+}
+
 @tool({
-  name: 'get_calendar_events',
-  description: 'Gets calendar events',
-  parameters: [
-    {
-      name: 'date',
-      type: ParameterType.String,
-      description: 'Date in YYYY-MM-DD format',
-      required: true,
-    },
-  ],
+  name: 'get_email',
+  description: 'Gets emails from the user\'s inbox',
   authRequirements: {
     provider: 'google',
-    scopeBundle: 'calendar',
-    required: true,
-  },
+    scopeBundle: 'gmail',
+    required: true
+  }
 })
-async function getCalendarEvents(params: any, environment?: any) {
-  const token = environment?.auth?.credentials?.access_token;
-  return { events: [] };
+async function getEmail(parameters: EmailParameters, authData?: any) {
+  // Implementation...
+  return { emails: ['Email 1', 'Email 2'] };
 }
 ```
 
-## Adaptive Block Documents
-
-Adaptive Block Documents enable rich, interactive UI responses with forms, buttons, and dynamic content.
+## Authentication
 
-### Creating Adaptive Block Responses
+The SDK provides authentication support for tools that require user credentials:
 
 ```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 },
-      },
-    };
-  },
-);
-```
+import { ToolsService, tool, requiresAuth, AuthData } from '@optimizely-opal/opal-tools-sdk';
+import express from 'express';
 
-### Adaptive Block Components
-
-The SDK provides a type-safe `Block` namespace with factory functions for all components:
+interface CalendarParameters {
+  date: string;
+  timezone?: string;
+}
 
-- `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...
+const app = express();
+const toolsService = new ToolsService(app);
 
-See the generated [src/block.ts](./src/block.ts) for the complete list and TypeScript types.
+@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'] };
+}
+```
 
-### Regenerating Adaptive Block Types
+## Island Components
 
-The Adaptive Block types are auto-generated from the JSON schema. To regenerate:
+The SDK includes Island components for creating interactive UI responses:
 
-```bash
-npm run generate:block
-```
+```typescript
+import {
+  ToolsService,
+  tool,
+  IslandResponse,
+  IslandConfig
+} from '@optimizely-opal/opal-tools-sdk';
+import express from 'express';
 
-This reads `block-document-spec.json` and generates TypeScript interfaces and factory functions in [src/block.ts](./src/block.ts).
+interface WeatherParameters {
+  location: string;
+  units?: string;
+}
 
-**Note:** Don't edit `src/block.ts` manually - it will be overwritten on regeneration.
+const app = express();
+const toolsService = new ToolsService(app);
 
-## Type Definitions
+@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 SDK provides comprehensive TypeScript type definitions:
+### Island Components
 
-### Authentication Types
+#### IslandConfig.Field
 
-- `AuthData` - Provider and credentials information
-- `Credentials` - Access tokens and org details
-- `Environment` - Execution context with auth data
+Fields represent data inputs in the UI:
 
-### Parameter Types
+- `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)
 
-- `ParameterType` - Enum for parameter types (String, Number, Boolean, List, Dictionary)
-- `Parameter` - Tool parameter definitions
-- `Function` - Complete tool function definitions
+#### IslandConfig.Action
 
-### Block Types
+Actions represent buttons or operations:
 
-All Block Document components have full TypeScript interfaces with type checking and IDE autocomplete.
+- `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'`)
 
-## API Reference
+#### IslandConfig
 
-### `registerTool<TSchema, TReturn>(name, options, handler)`
+Contains the complete island configuration:
 
-Modern API for defining tools with Zod schemas.
+- `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)
 
-**Parameters:**
+#### IslandResponse
 
-- `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
+The response wrapper for islands:
 
-**Returns:** The handler function with full type inference
+- Use `IslandResponse.create([islands])` to create responses
+- Supports multiple islands per response
 
-### `@tool(options)`
+## Type Definitions
 
-Legacy decorator for defining tools.
+The SDK provides comprehensive TypeScript type definitions:
 
-**Options:**
+### Authentication Types
 
-- `name: string` - Tool name
-- `description: string` - Tool description
-- `parameters: ParameterDefinition[]` - Parameter definitions
-- `authRequirements?` - Authentication requirements
+- `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'`)
 
-### `ToolsService`
+### Parameter Types
 
-Express service that manages tool registration and creates discovery endpoints.
+- `ParameterType`: Enum for supported parameter types
+- `Parameter`: Class for tool parameter definitions
+- `Function`: Class for complete tool function definitions
 
-```typescript
-const toolsService = new ToolsService(app);
-// Automatically creates /discovery endpoint
-```
+These types provide full IDE support and compile-time type checking for better development experience.
 
-## License
+## Documentation
 
-MIT
+See full documentation for more examples and configuration options.

package/dist/decorators.d.ts

@@ -15,6 +15,7 @@ interface ToolOptions {
     description: string;
     name: string;
     parameters?: ParameterDefinition[];
+    uiResource?: string;
 }
 /**
  * Decorator to register a function as an Opal tool
@@ -24,6 +25,7 @@ interface ToolOptions {
  *   - authRequirements: (Optional) Authentication requirements
  *     Format: { provider: "oauth_provider", scopeBundle: "permissions_scope", required: true }
  *     Example: { provider: "google", scopeBundle: "calendar", required: true }
+ *   - uiResource: (Optional) URI of associated UI resource for dynamic rendering (e.g., "ui://my-app/create-form")
  *
  * Note: If your tool requires authentication, define your handler function with two parameters:
  * ```

package/dist/decorators.js

@@ -13,6 +13,7 @@ const registry_1 = require("./registry");
  *   - authRequirements: (Optional) Authentication requirements
  *     Format: { provider: "oauth_provider", scopeBundle: "permissions_scope", required: true }
  *     Example: { provider: "google", scopeBundle: "calendar", required: true }
+ *   - uiResource: (Optional) URI of associated UI resource for dynamic rendering (e.g., "ui://my-app/create-form")
  *
  * Note: If your tool requires authentication, define your handler function with two parameters:
  * ```
@@ -44,7 +45,7 @@ function tool(options) {
         }
         // Register the tool with all services
         for (const service of registry_1.registry.services) {
-            service.registerTool(options.name, options.description, handler, parameters, endpoint, authRequirements);
+            service.registerTool(options.name, options.description, handler, parameters, endpoint, authRequirements, false, options.uiResource);
         }
         return isMethod ? descriptor : target;
     };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import "reflect-metadata";
 export { requiresAuth } from "./auth";
-export { Block, isBlockResponse } from "./block";
-export type * from "./block";
 export { tool } from "./decorators";
 export * from "./models";
+export { UI } from "./proteus";
+export type * from "./proteus";
+export { registerResource } from "./registerResource";
 export { registerTool } from "./registerTool";
 export type { RequestHandlerExtra } from "./registerTool";
 export { ToolsService } from "./service";

package/dist/index.js

@@ -14,16 +14,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolsService = exports.registerTool = exports.tool = exports.isBlockResponse = exports.Block = exports.requiresAuth = void 0;
+exports.ToolsService = exports.registerTool = exports.registerResource = exports.UI = exports.tool = exports.requiresAuth = void 0;
 require("reflect-metadata");
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "requiresAuth", { enumerable: true, get: function () { return auth_1.requiresAuth; } });
-var block_1 = require("./block");
-Object.defineProperty(exports, "Block", { enumerable: true, get: function () { return block_1.Block; } });
-Object.defineProperty(exports, "isBlockResponse", { enumerable: true, get: function () { return block_1.isBlockResponse; } });
 var decorators_1 = require("./decorators");
 Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return decorators_1.tool; } });
 __exportStar(require("./models"), exports);
+var proteus_1 = require("./proteus");
+Object.defineProperty(exports, "UI", { enumerable: true, get: function () { return proteus_1.UI; } });
+var registerResource_1 = require("./registerResource");
+Object.defineProperty(exports, "registerResource", { enumerable: true, get: function () { return registerResource_1.registerResource; } });
 var registerTool_1 = require("./registerTool");
 Object.defineProperty(exports, "registerTool", { enumerable: true, get: function () { return registerTool_1.registerTool; } });
 var service_1 = require("./service");

package/dist/models.d.ts

@@ -64,6 +64,7 @@ export declare class Function {
     parameters: Parameter[];
     endpoint: string;
     authRequirements?: AuthRequirement[] | undefined;
+    uiResource?: string | undefined;
     /**
      * HTTP method for the endpoint (default: POST)
      */
@@ -75,8 +76,9 @@ export declare class Function {
      * @param parameters Function parameters
      * @param endpoint API endpoint
      * @param authRequirements Authentication requirements (optional)
+     * @param uiResource URI of associated UI resource for dynamic rendering (optional)
      */
-    constructor(name: string, description: string, parameters: Parameter[], endpoint: string, authRequirements?: AuthRequirement[] | undefined);
+    constructor(name: string, description: string, parameters: Parameter[], endpoint: string, authRequirements?: AuthRequirement[] | undefined, uiResource?: string | undefined);
     /**
      * Convert to JSON for the discovery endpoint
      */
@@ -287,3 +289,22 @@ export declare class Parameter {
         type: ParameterType;
     };
 }
+/**
+ * Resource definition for MCP resources
+ */
+export declare class Resource {
+    uri: string;
+    name: string;
+    description?: string | undefined;
+    mimeType?: string | undefined;
+    title?: string | undefined;
+    /**
+     * Create a new resource definition
+     * @param uri The unique URI for this resource (e.g., "ui://my-app/create-form")
+     * @param name Name of the resource
+     * @param description Description of the resource (optional)
+     * @param mimeType MIME type of the resource content (optional)
+     * @param title Human-readable title for the resource (optional)
+     */
+    constructor(uri: string, name: string, description?: string | undefined, mimeType?: string | undefined, title?: string | undefined);
+}

package/dist/models.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Parameter = exports.IslandResponse = exports.IslandResponseConfig = exports.IslandConfig = exports.IslandField = exports.IslandAction = exports.Function = exports.AuthRequirement = exports.ParameterType = void 0;
+exports.Resource = exports.Parameter = exports.IslandResponse = exports.IslandResponseConfig = exports.IslandConfig = exports.IslandField = exports.IslandAction = exports.Function = exports.AuthRequirement = exports.ParameterType = void 0;
 /**
  * Types of parameters supported by Opal tools
  */
@@ -51,13 +51,15 @@ class Function {
      * @param parameters Function parameters
      * @param endpoint API endpoint
      * @param authRequirements Authentication requirements (optional)
+     * @param uiResource URI of associated UI resource for dynamic rendering (optional)
      */
-    constructor(name, description, parameters, endpoint, authRequirements) {
+    constructor(name, description, parameters, endpoint, authRequirements, uiResource) {
         this.name = name;
         this.description = description;
         this.parameters = parameters;
         this.endpoint = endpoint;
         this.authRequirements = authRequirements;
+        this.uiResource = uiResource;
         /**
          * HTTP method for the endpoint (default: POST)
          */
@@ -78,6 +80,9 @@ class Function {
         if (this.authRequirements && this.authRequirements.length > 0) {
             result.auth_requirements = this.authRequirements.map((auth) => auth.toJSON());
         }
+        if (this.uiResource !== undefined) {
+            result.ui_resource = this.uiResource;
+        }
         return result;
     }
 }
@@ -266,3 +271,24 @@ class Parameter {
     }
 }
 exports.Parameter = Parameter;
+/**
+ * Resource definition for MCP resources
+ */
+class Resource {
+    /**
+     * Create a new resource definition
+     * @param uri The unique URI for this resource (e.g., "ui://my-app/create-form")
+     * @param name Name of the resource
+     * @param description Description of the resource (optional)
+     * @param mimeType MIME type of the resource content (optional)
+     * @param title Human-readable title for the resource (optional)
+     */
+    constructor(uri, name, description, mimeType, title) {
+        this.uri = uri;
+        this.name = name;
+        this.description = description;
+        this.mimeType = mimeType;
+        this.title = title;
+    }
+}
+exports.Resource = Resource;