@optimizely-opal/opal-tools-sdk 0.1.0-dev → 0.1.3-dev

package/README.md

@@ -4,11 +4,12 @@ This SDK simplifies the creation of tools services compatible with the Opal Tool
 
 ## Features
 
-- Type definitions for tools and parameters
-- Express middleware for discovery endpoints
-- Decorators for tool registration
-- Parameter validation
+- 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
 
@@ -18,8 +19,152 @@ npm install @optimizely-opal/opal-tools-sdk
 
 ## Usage
 
+```typescript
+import { ToolsService, tool, IslandResponse, IslandConfig } from '@optimizely-opal/opal-tools-sdk';
+import express from 'express';
+
+const app = express();
+const toolsService = new ToolsService(app);
+
+interface WeatherParameters {
+  location: string;
+  units: string;
+}
+
+@tool({
+  name: 'get_weather',
+  description: 'Gets current weather for a location'
+})
+async function getWeather(parameters: WeatherParameters) {
+  // Implementation...
+  return { temperature: 22, condition: 'sunny' };
+}
+
+// Discovery endpoint is automatically created at /discovery
+```
+
+## Authentication
+
+The SDK provides two ways to require authentication for your tools:
+
+### 1. Using the `@requiresAuth` decorator
+
 ```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 };
+}
+```
+
+### 2. Specifying auth requirements in the `@tool` decorator
+
+```typescript
+interface EmailParameters {
+  limit?: number;
+  folder?: string;
+}
+
+@tool({
+  name: 'get_email',
+  description: 'Gets emails from the user\'s inbox',
+  authRequirements: {
+    provider: 'google',
+    scopeBundle: 'gmail',
+    required: true
+  }
+})
+async function getEmail(parameters: EmailParameters, authData?: any) {
+  // Implementation...
+  return { emails: ['Email 1', 'Email 2'] };
+}
+```
+
+## Authentication
+
+The SDK provides authentication support for tools that require user credentials:
+
+```typescript
+import { ToolsService, tool, requiresAuth, AuthData } from '@optimizely-opal/opal-tools-sdk';
+import express from 'express';
+
+interface CalendarParameters {
+  date: string;
+  timezone?: string;
+}
+
+const app = express();
+const toolsService = new ToolsService(app);
+
+@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'] };
+}
+```
+
+## Island Components
+
+The SDK includes Island components for creating interactive UI responses:
+
+```typescript
+import { 
+  ToolsService, 
+  tool, 
+  IslandResponse, 
+  IslandConfig
+} from '@optimizely-opal/opal-tools-sdk';
 import express from 'express';
 
 interface WeatherParameters {
@@ -35,14 +180,93 @@ const toolsService = new ToolsService(app);
   description: 'Gets current weather for a location'
 })
 async function getWeather(parameters: WeatherParameters) {
-  // Implementation...
-  return { temperature: 22, condition: 'sunny' };
+  // 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'
+      )
+    ]
+  );
+  
+  return IslandResponse.create([island]);
 }
-
-// Discovery endpoint is automatically created at /discovery
-app.listen(3000);
 ```
 
+### 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
+
+#### IslandResponse
+The response wrapper for islands:
+- Use `IslandResponse.create([islands])` to create responses
+- Supports multiple islands per response
+
+## 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'`)
+
+### 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.
+
 ## Documentation
 
 See full documentation for more examples and configuration options.

package/dist/models.d.ts

@@ -6,7 +6,7 @@ export declare enum ParameterType {
     Integer = "integer",
     Number = "number",
     Boolean = "boolean",
-    List = "list",
+    List = "array",
     Dictionary = "object"
 }
 /**
@@ -85,3 +85,198 @@ export declare class Function {
      */
     toJSON(): any;
 }
+/**
+ * Authentication credentials structure
+ */
+export type Credentials = {
+    access_token: string;
+    org_sso_id?: string;
+    customer_id: string;
+    instance_id: string;
+    product_sku: string;
+};
+/**
+ * Authentication data for an Opal tool
+ */
+export type AuthData = {
+    provider: string;
+    credentials: Credentials;
+};
+/**
+ * Execution environment for an Opal tool
+ */
+export type Environment = {
+    execution_mode: "headless" | "interactive";
+};
+/**
+ * Island field definition for interactive UI components
+ */
+export declare class IslandField {
+    name: string;
+    label: string;
+    type: "string" | "boolean" | "json";
+    value: string;
+    hidden: boolean;
+    options: string[];
+    /**
+     * Create a new island field
+     * @param name Programmatic field identifier
+     * @param label Human-readable label
+     * @param type Field type
+     * @param value Current field value
+     * @param hidden Whether to hide from user
+     * @param options Available options for selection
+     */
+    constructor(name: string, label: string, type: "string" | "boolean" | "json", value?: string, hidden?: boolean, options?: string[]);
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON(): {
+        name: string;
+        label: string;
+        type: "string" | "boolean" | "json";
+        value: string;
+        hidden: boolean;
+        options: string[];
+    };
+}
+/**
+ * Island action definition for interactive UI components
+ */
+export declare class IslandAction {
+    name: string;
+    label: string;
+    type: string;
+    endpoint: string;
+    operation: string;
+    /**
+     * Create a new island action
+     * @param name Programmatic action identifier
+     * @param label Human-readable button label
+     * @param type UI element type
+     * @param endpoint API endpoint to call
+     * @param operation Operation type
+     */
+    constructor(name: string, label: string, type: string, endpoint: string, operation?: string);
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON(): {
+        name: string;
+        label: string;
+        type: string;
+        endpoint: string;
+        operation: string;
+    };
+}
+/**
+ * Island configuration for interactive UI components
+ */
+export declare class IslandConfig {
+    fields: IslandField[];
+    actions: IslandAction[];
+    static Field: typeof IslandField;
+    static Action: typeof IslandAction;
+    /**
+     * Create a new island configuration
+     * @param fields List of island fields
+     * @param actions List of island actions
+     */
+    constructor(fields: IslandField[], actions: IslandAction[]);
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON(): {
+        fields: {
+            name: string;
+            label: string;
+            type: "string" | "boolean" | "json";
+            value: string;
+            hidden: boolean;
+            options: string[];
+        }[];
+        actions: {
+            name: string;
+            label: string;
+            type: string;
+            endpoint: string;
+            operation: string;
+        }[];
+    };
+}
+/**
+ * Island response configuration
+ */
+export declare class IslandResponseConfig {
+    islands: IslandConfig[];
+    /**
+     * Create a new island response configuration
+     * @param islands List of island configurations
+     */
+    constructor(islands: IslandConfig[]);
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON(): {
+        islands: {
+            fields: {
+                name: string;
+                label: string;
+                type: "string" | "boolean" | "json";
+                value: string;
+                hidden: boolean;
+                options: string[];
+            }[];
+            actions: {
+                name: string;
+                label: string;
+                type: string;
+                endpoint: string;
+                operation: string;
+            }[];
+        }[];
+    };
+}
+/**
+ * Island response wrapper for interactive UI components
+ */
+export declare class IslandResponse {
+    config: IslandResponseConfig;
+    static ResponseConfig: typeof IslandResponseConfig;
+    type: "island";
+    /**
+     * Create a new island response
+     * @param config Response configuration
+     */
+    constructor(config: IslandResponseConfig);
+    /**
+     * Create an island response with a list of islands
+     * @param islands List of island configurations
+     * @returns New IslandResponse instance
+     */
+    static create(islands: IslandConfig[]): IslandResponse;
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON(): {
+        config: {
+            islands: {
+                fields: {
+                    name: string;
+                    label: string;
+                    type: "string" | "boolean" | "json";
+                    value: string;
+                    hidden: boolean;
+                    options: string[];
+                }[];
+                actions: {
+                    name: string;
+                    label: string;
+                    type: string;
+                    endpoint: string;
+                    operation: string;
+                }[];
+            }[];
+        };
+    };
+}

package/dist/models.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Function = exports.AuthRequirement = exports.Parameter = exports.ParameterType = void 0;
+exports.IslandResponse = exports.IslandResponseConfig = exports.IslandConfig = exports.IslandAction = exports.IslandField = exports.Function = exports.AuthRequirement = exports.Parameter = exports.ParameterType = void 0;
 /**
  * Types of parameters supported by Opal tools
  */
@@ -10,7 +10,7 @@ var ParameterType;
     ParameterType["Integer"] = "integer";
     ParameterType["Number"] = "number";
     ParameterType["Boolean"] = "boolean";
-    ParameterType["List"] = "list";
+    ParameterType["List"] = "array";
     ParameterType["Dictionary"] = "object";
 })(ParameterType || (exports.ParameterType = ParameterType = {}));
 /**
@@ -111,3 +111,150 @@ class Function {
     }
 }
 exports.Function = Function;
+/**
+ * Island field definition for interactive UI components
+ */
+class IslandField {
+    /**
+     * Create a new island field
+     * @param name Programmatic field identifier
+     * @param label Human-readable label
+     * @param type Field type
+     * @param value Current field value
+     * @param hidden Whether to hide from user
+     * @param options Available options for selection
+     */
+    constructor(name, label, type, value = "", hidden = false, options = []) {
+        this.name = name;
+        this.label = label;
+        this.type = type;
+        this.value = value;
+        this.hidden = hidden;
+        this.options = options;
+    }
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            label: this.label,
+            type: this.type,
+            value: this.value,
+            hidden: this.hidden,
+            options: this.options,
+        };
+    }
+}
+exports.IslandField = IslandField;
+/**
+ * Island action definition for interactive UI components
+ */
+class IslandAction {
+    /**
+     * Create a new island action
+     * @param name Programmatic action identifier
+     * @param label Human-readable button label
+     * @param type UI element type
+     * @param endpoint API endpoint to call
+     * @param operation Operation type
+     */
+    constructor(name, label, type, endpoint, operation = "create") {
+        this.name = name;
+        this.label = label;
+        this.type = type;
+        this.endpoint = endpoint;
+        this.operation = operation;
+    }
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            label: this.label,
+            type: this.type,
+            endpoint: this.endpoint,
+            operation: this.operation,
+        };
+    }
+}
+exports.IslandAction = IslandAction;
+/**
+ * Island configuration for interactive UI components
+ */
+class IslandConfig {
+    /**
+     * Create a new island configuration
+     * @param fields List of island fields
+     * @param actions List of island actions
+     */
+    constructor(fields, actions) {
+        this.fields = fields;
+        this.actions = actions;
+    }
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON() {
+        return {
+            fields: this.fields.map((field) => field.toJSON()),
+            actions: this.actions.map((action) => action.toJSON()),
+        };
+    }
+}
+exports.IslandConfig = IslandConfig;
+IslandConfig.Field = IslandField;
+IslandConfig.Action = IslandAction;
+/**
+ * Island response configuration
+ */
+class IslandResponseConfig {
+    /**
+     * Create a new island response configuration
+     * @param islands List of island configurations
+     */
+    constructor(islands) {
+        this.islands = islands;
+    }
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON() {
+        return {
+            islands: this.islands.map((island) => island.toJSON()),
+        };
+    }
+}
+exports.IslandResponseConfig = IslandResponseConfig;
+/**
+ * Island response wrapper for interactive UI components
+ */
+class IslandResponse {
+    /**
+     * Create a new island response
+     * @param config Response configuration
+     */
+    constructor(config) {
+        this.config = config;
+        this.type = "island";
+    }
+    /**
+     * Create an island response with a list of islands
+     * @param islands List of island configurations
+     * @returns New IslandResponse instance
+     */
+    static create(islands) {
+        return new IslandResponse(new IslandResponseConfig(islands));
+    }
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON() {
+        return {
+            config: this.config.toJSON(),
+        };
+    }
+}
+exports.IslandResponse = IslandResponse;
+IslandResponse.ResponseConfig = IslandResponseConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optimizely-opal/opal-tools-sdk",
-  "version": "0.1.0-dev",
+  "version": "0.1.3-dev",
   "description": "SDK for creating Opal-compatible tools services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/decorators.ts

@@ -36,7 +36,7 @@ function mapTypeToParameterType(type: any): ParameterType {
   } else if (type === Object || type.name === 'Object') {
     return ParameterType.Dictionary;
   }
-  
+
   // Default to string
   return ParameterType.String;
 }
@@ -47,14 +47,14 @@ function mapTypeToParameterType(type: any): ParameterType {
  */
 function extractParameters(paramType: any): Parameter[] {
   const parameters: Parameter[] = [];
-  
+
   // This is very basic and doesn't handle complex types
   // For production use, this would need to be more sophisticated
   for (const key in paramType) {
     if (paramType.hasOwnProperty(key)) {
       const type = typeof paramType[key] === 'undefined' ? String : paramType[key].constructor;
       const required = true; // In a real implementation, we'd detect optional parameters
-      
+
       parameters.push(new Parameter(
         key,
         mapTypeToParameterType(type),
@@ -63,7 +63,7 @@ function extractParameters(paramType: any): Parameter[] {
       ));
     }
   }
-  
+
   return parameters;
 }
 
@@ -72,10 +72,10 @@ function extractParameters(paramType: any): Parameter[] {
  * @param options Tool options including:
  *   - name: Name of the tool
  *   - description: Description of the tool
- *   - authRequirements: (Optional) Authentication requirements 
+ *   - authRequirements: (Optional) Authentication requirements
  *     Format: { provider: "oauth_provider", scopeBundle: "permissions_scope", required: true }
  *     Example: { provider: "google", scopeBundle: "calendar", required: true }
- * 
+ *
  * Note: If your tool requires authentication, define your handler function with two parameters:
  * ```
  * async function myTool(parameters: ParameterInterface, authData?: any): Promise<any> {
@@ -87,10 +87,10 @@ export function tool(options: ToolOptions) {
   return function(target: any, propertyKey?: string, descriptor?: PropertyDescriptor) {
     const isMethod = propertyKey && descriptor;
     const handler = isMethod ? descriptor.value : target;
-    
+
     // Generate endpoint from name - ensure hyphens instead of underscores
     const endpoint = `/tools/${options.name.replace(/_/g, '-')}`;
-    
+
     // Convert parameter definitions to Parameter objects
     const parameters: Parameter[] = [];
     if (options.parameters && options.parameters.length > 0) {
@@ -104,7 +104,7 @@ export function tool(options: ToolOptions) {
         ));
       }
     }
-    
+
     // Create auth requirements if specified
     let authRequirements: AuthRequirement[] | undefined;
     if (options.authRequirements) {
@@ -116,7 +116,7 @@ export function tool(options: ToolOptions) {
         )
       ];
     }
-    
+
     // Register the tool with all services
     for (const service of registry.services) {
       service.registerTool(
@@ -128,7 +128,7 @@ export function tool(options: ToolOptions) {
         authRequirements
       );
     }
-    
+
     return isMethod ? descriptor : target;
   };
 }

package/src/models.ts

@@ -6,7 +6,7 @@ export enum ParameterType {
   Integer = 'integer',
   Number = 'number',
   Boolean = 'boolean',
-  List = 'list',
+  List = 'array',
   Dictionary = 'object'
 }
 
@@ -113,3 +113,181 @@ export class Function {
     return result;
   }
 }
+
+/**
+ * Authentication credentials structure
+ */
+export type Credentials ={
+  access_token: string;
+  org_sso_id?: string;
+  customer_id: string;
+  instance_id: string;
+  product_sku: string;
+}
+
+/**
+ * Authentication data for an Opal tool
+ */
+export type AuthData = {
+  provider: string;
+  credentials: Credentials;
+}
+
+/**
+ * Execution environment for an Opal tool
+ */
+export type Environment = {
+  execution_mode: "headless" | "interactive";
+}
+
+/**
+ * Island field definition for interactive UI components
+ */
+export class IslandField {
+  /**
+   * Create a new island field
+   * @param name Programmatic field identifier
+   * @param label Human-readable label
+   * @param type Field type
+   * @param value Current field value
+   * @param hidden Whether to hide from user
+   * @param options Available options for selection
+   */
+  constructor(
+    public name: string,
+    public label: string,
+    public type: "string" | "boolean" | "json",
+    public value: string = "",
+    public hidden: boolean = false,
+    public options: string[] = []
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      label: this.label,
+      type: this.type,
+      value: this.value,
+      hidden: this.hidden,
+      options: this.options,
+    };
+  }
+}
+
+/**
+ * Island action definition for interactive UI components
+ */
+export class IslandAction {
+  /**
+   * Create a new island action
+   * @param name Programmatic action identifier
+   * @param label Human-readable button label
+   * @param type UI element type
+   * @param endpoint API endpoint to call
+   * @param operation Operation type
+   */
+  constructor(
+    public name: string,
+    public label: string,
+    public type: string,
+    public endpoint: string,
+    public operation: string = "create"
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      label: this.label,
+      type: this.type,
+      endpoint: this.endpoint,
+      operation: this.operation,
+    };
+  }
+}
+
+/**
+ * Island configuration for interactive UI components
+ */
+export class IslandConfig {
+  static Field = IslandField;
+  static Action = IslandAction;
+
+  /**
+   * Create a new island configuration
+   * @param fields List of island fields
+   * @param actions List of island actions
+   */
+  constructor(
+    public fields: IslandField[],
+    public actions: IslandAction[]
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  toJSON() {
+    return {
+      fields: this.fields.map((field) => field.toJSON()),
+      actions: this.actions.map((action) => action.toJSON()),
+    };
+  }
+}
+
+/**
+ * Island response configuration
+ */
+export class IslandResponseConfig {
+  /**
+   * Create a new island response configuration
+   * @param islands List of island configurations
+   */
+  constructor(public islands: IslandConfig[]) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  toJSON() {
+    return {
+      islands: this.islands.map((island) => island.toJSON()),
+    };
+  }
+}
+
+/**
+ * Island response wrapper for interactive UI components
+ */
+export class IslandResponse {
+  static ResponseConfig = IslandResponseConfig;
+
+  public type: "island" = "island";
+
+  /**
+   * Create a new island response
+   * @param config Response configuration
+   */
+  constructor(public config: IslandResponseConfig) {}
+
+  /**
+   * Create an island response with a list of islands
+   * @param islands List of island configurations
+   * @returns New IslandResponse instance
+   */
+  static create(islands: IslandConfig[]): IslandResponse {
+    return new IslandResponse(new IslandResponseConfig(islands));
+  }
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  toJSON() {
+    return {
+      config: this.config.toJSON(),
+    };
+  }
+}