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

package/.prettierignore

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

package/.prettierrc

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

package/README.md

@@ -71,10 +71,10 @@ interface CalendarParameters {
 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'] };
 }
 
@@ -88,13 +88,13 @@ async function getCalendarEvents(parameters: CalendarParameters, authData?: any)
 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 };
 }
 ```
@@ -159,10 +159,10 @@ async function getCalendarEvents(parameters: CalendarParameters, authData?: Auth
 The SDK includes Island components for creating interactive UI responses:
 
 ```typescript
-import { 
-  ToolsService, 
-  tool, 
-  IslandResponse, 
+import {
+  ToolsService,
+  tool,
+  IslandResponse,
   IslandConfig
 } from '@optimizely-opal/opal-tools-sdk';
 import express from 'express';
@@ -182,7 +182,7 @@ const toolsService = new ToolsService(app);
 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(
     [
@@ -219,7 +219,7 @@ async function getWeather(parameters: WeatherParameters) {
     'button',  // Optional island type
     'plus'     // Optional island icon
   );
-  
+
   return IslandResponse.create([island]);
 }
 ```
@@ -227,7 +227,9 @@ async function getWeather(parameters: WeatherParameters) {
 ### 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'`)
@@ -236,7 +238,9 @@ Fields represent data inputs in the UI:
 - `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'`)
@@ -244,14 +248,18 @@ Actions represent buttons or operations:
 - `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
 
@@ -260,11 +268,13 @@ The response wrapper for islands:
 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

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);
             };

package/dist/decorators.d.ts

@@ -1,20 +1,21 @@
-import 'reflect-metadata';
-import { ParameterType } from './models';
+import "reflect-metadata";
+import { ParameterType } from "./models";
 interface ParameterDefinition {
-    name: string;
-    type: ParameterType;
     description: string;
+    name: string;
     required: boolean;
+    type: ParameterType;
 }
 interface ToolOptions {
-    name: string;
-    description: string;
-    parameters?: ParameterDefinition[];
     authRequirements?: {
         provider: string;
-        scopeBundle: string;
         required?: boolean;
+        scopeBundle: string;
     };
+    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

@@ -1,50 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tool = tool;
+/* eslint-disable @typescript-eslint/no-explicit-any */
 require("reflect-metadata");
 const models_1 = require("./models");
 const registry_1 = require("./registry");
-/**
- * Map a TypeScript type to a ParameterType
- * @param type TypeScript type
- */
-function mapTypeToParameterType(type) {
-    if (type === String || type.name === 'String') {
-        return models_1.ParameterType.String;
-    }
-    else if (type === Number || type.name === 'Number') {
-        return models_1.ParameterType.Number;
-    }
-    else if (type === Boolean || type.name === 'Boolean') {
-        return models_1.ParameterType.Boolean;
-    }
-    else if (type === Array || type.name === 'Array') {
-        return models_1.ParameterType.List;
-    }
-    else if (type === Object || type.name === 'Object') {
-        return models_1.ParameterType.Dictionary;
-    }
-    // Default to string
-    return models_1.ParameterType.String;
-}
-/**
- * Extract parameters from a TypeScript interface
- * @param paramType Parameter type object
- */
-function extractParameters(paramType) {
-    const parameters = [];
-    // 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 models_1.Parameter(key, mapTypeToParameterType(type), '', // Description - in a real impl we'd use TypeDoc or similar
-            required));
-        }
-    }
-    return parameters;
-}
 /**
  * Decorator to register a function as an Opal tool
  * @param options Tool options including:
@@ -53,6 +13,7 @@ function extractParameters(paramType) {
  *   - 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:
  * ```
@@ -66,7 +27,7 @@ function tool(options) {
         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, '-')}`;
+        const endpoint = `/tools/${options.name.replace(/_/g, "-")}`;
         // Convert parameter definitions to Parameter objects
         const parameters = [];
         if (options.parameters && options.parameters.length > 0) {
@@ -79,12 +40,12 @@ function tool(options) {
         let authRequirements;
         if (options.authRequirements) {
             authRequirements = [
-                new models_1.AuthRequirement(options.authRequirements.provider, options.authRequirements.scopeBundle, options.authRequirements.required ?? true)
+                new models_1.AuthRequirement(options.authRequirements.provider, options.authRequirements.scopeBundle, options.authRequirements.required ?? true),
             ];
         }
         // 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,5 +1,10 @@
-import 'reflect-metadata';
-export { ToolsService } from './service';
-export { tool } from './decorators';
-export { requiresAuth } from './auth';
-export * from './models';
+import "reflect-metadata";
+export { requiresAuth } from "./auth";
+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,12 +14,18 @@ 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.requiresAuth = exports.tool = exports.ToolsService = void 0;
+exports.ToolsService = exports.registerTool = exports.registerResource = exports.UI = exports.tool = exports.requiresAuth = void 0;
 require("reflect-metadata");
-var service_1 = require("./service");
-Object.defineProperty(exports, "ToolsService", { enumerable: true, get: function () { return service_1.ToolsService; } });
-var decorators_1 = require("./decorators");
-Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return decorators_1.tool; } });
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "requiresAuth", { enumerable: true, get: function () { return auth_1.requiresAuth; } });
+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");
+Object.defineProperty(exports, "ToolsService", { enumerable: true, get: function () { return service_1.ToolsService; } });

package/dist/models.d.ts

@@ -2,39 +2,36 @@
  * Types of parameters supported by Opal tools
  */
 export declare enum ParameterType {
-    String = "string",
-    Integer = "integer",
-    Number = "number",
     Boolean = "boolean",
+    Dictionary = "object",
+    Integer = "integer",
     List = "array",
-    Dictionary = "object"
+    Number = "number",
+    String = "string"
 }
 /**
- * Parameter definition for an Opal tool
+ * Authentication data for an Opal tool
  */
-export declare class Parameter {
-    name: string;
-    type: ParameterType;
-    description: string;
-    required: boolean;
-    /**
-     * Create a new parameter definition
-     * @param name Parameter name
-     * @param type Parameter type
-     * @param description Parameter description
-     * @param required Whether the parameter is required
-     */
-    constructor(name: string, type: ParameterType, description: string, required: boolean);
-    /**
-     * Convert to JSON for the discovery endpoint
-     */
-    toJSON(): {
-        name: string;
-        type: ParameterType;
-        description: string;
-        required: boolean;
-    };
-}
+export type AuthData = {
+    credentials: Credentials;
+    provider: string;
+};
+/**
+ * Authentication credentials structure
+ */
+export type Credentials = {
+    access_token: string;
+    customer_id: string;
+    instance_id: string;
+    org_sso_id?: string;
+    product_sku: string;
+};
+/**
+ * Execution environment for an Opal tool
+ */
+export type Environment = {
+    execution_mode: "headless" | "interactive";
+};
 /**
  * Authentication requirements for an Opal tool
  */
@@ -54,8 +51,8 @@ export declare class AuthRequirement {
      */
     toJSON(): {
         provider: string;
-        scope_bundle: string;
         required: boolean;
+        scope_bundle: string;
     };
 }
 /**
@@ -67,6 +64,7 @@ export declare class Function {
     parameters: Parameter[];
     endpoint: string;
     authRequirements?: AuthRequirement[] | undefined;
+    uiResource?: string | undefined;
     /**
      * HTTP method for the endpoint (default: POST)
      */
@@ -78,43 +76,50 @@ 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
      */
     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
+ * Island action definition for interactive UI components
  */
-export type Environment = {
-    execution_mode: "headless" | "interactive";
-};
+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(): {
+        endpoint: string;
+        label: string;
+        name: string;
+        operation: string;
+        type: string;
+    };
+}
 /**
  * Island field definition for interactive UI components
  */
 export declare class IslandField {
     name: string;
     label: string;
-    type: "string" | "boolean" | "json";
+    type: "boolean" | "json" | "string";
     value: string;
     hidden: boolean;
     options: string[];
@@ -127,46 +132,17 @@ export declare class IslandField {
      * @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[]);
+    constructor(name: string, label: string, type: "boolean" | "json" | "string", value?: string, hidden?: boolean, options?: string[]);
     /**
      * Convert to JSON for the discovery endpoint
      */
     toJSON(): {
-        name: string;
+        hidden: boolean;
         label: string;
+        name: string;
+        options: 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;
     };
 }
 /**
@@ -177,8 +153,8 @@ export declare class IslandConfig {
     actions: IslandAction[];
     type?: string | undefined;
     icon?: string | undefined;
-    static Field: typeof IslandField;
     static Action: typeof IslandAction;
+    static Field: typeof IslandField;
     /**
      * Create a new island configuration
      * @param fields List of island fields
@@ -191,20 +167,20 @@ export declare class IslandConfig {
      * Convert to JSON for the discovery endpoint
      */
     toJSON(): {
-        fields: {
+        actions: {
+            endpoint: string;
+            label: string;
             name: string;
+            operation: string;
+            type: string;
+        }[];
+        fields: {
+            hidden: boolean;
             label: string;
+            name: string;
+            options: string[];
             type: "string" | "boolean" | "json";
             value: string;
-            hidden: boolean;
-            options: string[];
-        }[];
-        actions: {
-            name: string;
-            label: string;
-            type: string;
-            endpoint: string;
-            operation: string;
         }[];
     };
 }
@@ -223,20 +199,20 @@ export declare class IslandResponseConfig {
      */
     toJSON(): {
         islands: {
-            fields: {
+            actions: {
+                endpoint: string;
+                label: string;
                 name: string;
+                operation: string;
+                type: string;
+            }[];
+            fields: {
+                hidden: boolean;
                 label: string;
+                name: string;
+                options: string[];
                 type: "string" | "boolean" | "json";
                 value: string;
-                hidden: boolean;
-                options: string[];
-            }[];
-            actions: {
-                name: string;
-                label: string;
-                type: string;
-                endpoint: string;
-                operation: string;
             }[];
         }[];
     };
@@ -268,22 +244,67 @@ export declare class IslandResponse {
     toJSON(): {
         config: {
             islands: {
-                fields: {
+                actions: {
+                    endpoint: string;
+                    label: string;
                     name: string;
+                    operation: string;
+                    type: string;
+                }[];
+                fields: {
+                    hidden: boolean;
                     label: string;
+                    name: string;
+                    options: string[];
                     type: "string" | "boolean" | "json";
                     value: string;
-                    hidden: boolean;
-                    options: string[];
-                }[];
-                actions: {
-                    name: string;
-                    label: string;
-                    type: string;
-                    endpoint: string;
-                    operation: string;
                 }[];
             }[];
         };
     };
 }
+/**
+ * Parameter definition for an Opal tool
+ */
+export declare class Parameter {
+    name: string;
+    type: ParameterType;
+    description: string;
+    required: boolean;
+    /**
+     * Create a new parameter definition
+     * @param name Parameter name
+     * @param type Parameter type
+     * @param description Parameter description
+     * @param required Whether the parameter is required
+     */
+    constructor(name: string, type: ParameterType, description: string, required: boolean);
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON(): {
+        description: string;
+        name: string;
+        required: boolean;
+        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);
+}