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

package/dist/models.js

@@ -1,48 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IslandResponse = exports.IslandResponseConfig = exports.IslandConfig = exports.IslandAction = exports.IslandField = exports.Function = exports.AuthRequirement = exports.Parameter = exports.ParameterType = void 0;
+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
  */
 var ParameterType;
 (function (ParameterType) {
-    ParameterType["String"] = "string";
-    ParameterType["Integer"] = "integer";
-    ParameterType["Number"] = "number";
     ParameterType["Boolean"] = "boolean";
-    ParameterType["List"] = "array";
     ParameterType["Dictionary"] = "object";
+    ParameterType["Integer"] = "integer";
+    ParameterType["List"] = "array";
+    ParameterType["Number"] = "number";
+    ParameterType["String"] = "string";
 })(ParameterType || (exports.ParameterType = ParameterType = {}));
-/**
- * Parameter definition for an Opal tool
- */
-class Parameter {
-    /**
-     * 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, type, description, required) {
-        this.name = name;
-        this.type = type;
-        this.description = description;
-        this.required = required;
-    }
-    /**
-     * Convert to JSON for the discovery endpoint
-     */
-    toJSON() {
-        return {
-            name: this.name,
-            type: this.type,
-            description: this.description,
-            required: this.required
-        };
-    }
-}
-exports.Parameter = Parameter;
 /**
  * Authentication requirements for an Opal tool
  */
@@ -64,8 +34,8 @@ class AuthRequirement {
     toJSON() {
         return {
             provider: this.provider,
+            required: this.required,
             scope_bundle: this.scopeBundle,
-            required: this.required
         };
     }
 }
@@ -91,95 +61,96 @@ class Function {
         /**
          * HTTP method for the endpoint (default: POST)
          */
-        this.httpMethod = 'POST';
+        this.httpMethod = "POST";
     }
     /**
      * Convert to JSON for the discovery endpoint
      */
     toJSON() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const result = {
-            name: this.name,
             description: this.description,
-            parameters: this.parameters.map(p => p.toJSON()),
             endpoint: this.endpoint,
-            http_method: this.httpMethod
+            http_method: this.httpMethod,
+            name: this.name,
+            parameters: this.parameters.map((p) => p.toJSON()),
         };
         if (this.authRequirements && this.authRequirements.length > 0) {
-            result.auth_requirements = this.authRequirements.map(auth => auth.toJSON());
+            result.auth_requirements = this.authRequirements.map((auth) => auth.toJSON());
         }
         return result;
     }
 }
 exports.Function = Function;
 /**
- * Island field definition for interactive UI components
+ * Island action definition for interactive UI components
  */
-class IslandField {
+class IslandAction {
     /**
-     * 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
+     * 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, value = "", hidden = false, options = []) {
+    constructor(name, label, type, endpoint, operation = "create") {
         this.name = name;
         this.label = label;
         this.type = type;
-        this.value = value;
-        this.hidden = hidden;
-        this.options = options;
+        this.endpoint = endpoint;
+        this.operation = operation;
     }
     /**
      * Convert to JSON for the discovery endpoint
      */
     toJSON() {
         return {
-            name: this.name,
+            endpoint: this.endpoint,
             label: this.label,
+            name: this.name,
+            operation: this.operation,
             type: this.type,
-            value: this.value,
-            hidden: this.hidden,
-            options: this.options,
         };
     }
 }
-exports.IslandField = IslandField;
+exports.IslandAction = IslandAction;
 /**
- * Island action definition for interactive UI components
+ * Island field definition for interactive UI components
  */
-class IslandAction {
+class IslandField {
     /**
-     * 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
+     * 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, endpoint, operation = "create") {
+    constructor(name, label, type, value = "", hidden = false, options = []) {
         this.name = name;
         this.label = label;
         this.type = type;
-        this.endpoint = endpoint;
-        this.operation = operation;
+        this.value = value;
+        this.hidden = hidden;
+        this.options = options;
     }
     /**
      * Convert to JSON for the discovery endpoint
      */
     toJSON() {
         return {
-            name: this.name,
+            hidden: this.hidden,
             label: this.label,
+            name: this.name,
+            options: this.options,
             type: this.type,
-            endpoint: this.endpoint,
-            operation: this.operation,
+            value: this.value,
         };
     }
 }
-exports.IslandAction = IslandAction;
+exports.IslandField = IslandField;
 /**
  * Island configuration for interactive UI components
  */
@@ -188,24 +159,28 @@ class IslandConfig {
      * Create a new island configuration
      * @param fields List of island fields
      * @param actions List of island actions
+     * @param type Optional island type
+     * @param icon Optional island icon
      */
-    constructor(fields, actions) {
+    constructor(fields, actions, type, icon) {
         this.fields = fields;
         this.actions = actions;
+        this.type = type;
+        this.icon = icon;
     }
     /**
      * Convert to JSON for the discovery endpoint
      */
     toJSON() {
         return {
-            fields: this.fields.map((field) => field.toJSON()),
             actions: this.actions.map((action) => action.toJSON()),
+            fields: this.fields.map((field) => field.toJSON()),
         };
     }
 }
 exports.IslandConfig = IslandConfig;
-IslandConfig.Field = IslandField;
 IslandConfig.Action = IslandAction;
+IslandConfig.Field = IslandField;
 /**
  * Island response configuration
  */
@@ -234,18 +209,21 @@ class IslandResponse {
     /**
      * Create a new island response
      * @param config Response configuration
+     * @param message Optional message for the island response
      */
-    constructor(config) {
+    constructor(config, message) {
         this.config = config;
+        this.message = message;
         this.type = "island";
     }
     /**
      * Create an island response with a list of islands
      * @param islands List of island configurations
+     * @param message Optional message for the island response
      * @returns New IslandResponse instance
      */
-    static create(islands) {
-        return new IslandResponse(new IslandResponseConfig(islands));
+    static create(islands, message) {
+        return new IslandResponse(new IslandResponseConfig(islands), message);
     }
     /**
      * Convert to JSON for the discovery endpoint
@@ -258,3 +236,33 @@ class IslandResponse {
 }
 exports.IslandResponse = IslandResponse;
 IslandResponse.ResponseConfig = IslandResponseConfig;
+/**
+ * Parameter definition for an Opal tool
+ */
+class Parameter {
+    /**
+     * 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, type, description, required) {
+        this.name = name;
+        this.type = type;
+        this.description = description;
+        this.required = required;
+    }
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON() {
+        return {
+            description: this.description,
+            name: this.name,
+            required: this.required,
+            type: this.type,
+        };
+    }
+}
+exports.Parameter = Parameter;

package/dist/registerTool.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod/v4";
+import type { BlockResponse } from "./block";
+import { Credentials } from "./models";
+/**
+ * Extra context passed to tool handlers
+ */
+export type RequestHandlerExtra = {
+    /** Authentication data if provided */
+    auth?: {
+        credentials: Credentials;
+        provider: string;
+    };
+    /** Execution mode: 'headless' for non-interactive, 'interactive' for user interaction (defaults to 'headless') */
+    mode: "headless" | "interactive";
+};
+type ToolOptions<TSchema extends Record<string, z.ZodTypeAny>, TType extends "block" | "json" = "json"> = {
+    authRequirements?: {
+        provider: string;
+        required?: boolean;
+        scopeBundle: string;
+    };
+    description: string;
+    inputSchema: TSchema;
+    type?: TType;
+};
+/**
+ * Register a function as an Opal tool
+ *
+ * @example
+ * ```typescript
+ * const greetTool = registerTool('greet', {
+ *   description: 'Greet a user',
+ *   inputSchema: {
+ *     name: z.string().describe('The name to greet')
+ *   }
+ * }, async (params) => {
+ *   // params is automatically typed as { name: string }
+ *   return `Hello, ${params.name}!`;
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With auth and execution mode
+ * const fetchTool = registerTool('fetch_data', {
+ *   description: 'Fetch data from API',
+ *   inputSchema: {
+ *     url: z.string().describe('URL to fetch')
+ *   },
+ *   authRequirements: {
+ *     provider: 'api-service',
+ *     scopeBundle: 'read'
+ *   }
+ * }, async (params, extra) => {
+ *   // extra.mode: 'headless' | 'interactive'
+ *   // extra.auth: { provider, credentials }
+ *   const headers = extra?.auth ? { Authorization: extra.auth.credentials.token } : {};
+ *   return fetch(params.url, { headers });
+ * });
+ * ```
+ */
+export declare function registerTool<TSchema extends Record<string, z.ZodTypeAny>>(name: string, options: ToolOptions<TSchema, "block">, handler: (params: {
+    [K in keyof TSchema]: z.infer<TSchema[K]>;
+}, extra?: RequestHandlerExtra) => BlockResponse | Promise<BlockResponse>): typeof handler;
+export declare function registerTool<TSchema extends Record<string, z.ZodTypeAny>>(name: string, options: Omit<ToolOptions<TSchema>, "type"> | ToolOptions<TSchema, "json">, handler: (params: {
+    [K in keyof TSchema]: z.infer<TSchema[K]>;
+}, extra?: RequestHandlerExtra) => Promise<unknown> | unknown): typeof handler;
+export {};

package/dist/registerTool.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTool = registerTool;
+const v4_1 = require("zod/v4");
+const models_1 = require("./models");
+const registry_1 = require("./registry");
+// Implementation
+function registerTool(name, options, handler) {
+    // Register the tool with all services
+    const responseType = options.type || "json";
+    for (const service of registry_1.registry.services) {
+        service.registerTool(name, options.description, handler, jsonSchemaToParameters(v4_1.z.toJSONSchema(v4_1.z.object(options.inputSchema))), `/tools/${name.replace(/_/g, "-")}`, options.authRequirements
+            ? [
+                new models_1.AuthRequirement(options.authRequirements.provider, options.authRequirements.scopeBundle, options.authRequirements.required ?? true),
+            ]
+            : undefined, responseType, true);
+    }
+    return handler;
+}
+/**
+ * Convert JSON Schema to Parameter definitions
+ * This converts the output of z.toJSONSchema() back to the Parameter[] format
+ * expected by the legacy discovery endpoint
+ */
+function jsonSchemaToParameters(jsonSchema) {
+    const parameters = [];
+    if (!jsonSchema.properties) {
+        return parameters;
+    }
+    const required = jsonSchema.required || [];
+    for (const [key, value] of Object.entries(jsonSchema.properties)) {
+        const prop = value;
+        parameters.push(new models_1.Parameter(key, jsonSchemaTypeToParameterType(prop.type || "string"), prop.description || "", required.includes(key)));
+    }
+    return parameters;
+}
+/**
+ * Map JSON Schema type to ParameterType
+ */
+function jsonSchemaTypeToParameterType(jsonType) {
+    switch (jsonType) {
+        case "array":
+            return models_1.ParameterType.List;
+        case "boolean":
+            return models_1.ParameterType.Boolean;
+        case "integer":
+            return models_1.ParameterType.Integer;
+        case "number":
+            return models_1.ParameterType.Number;
+        case "object":
+            return models_1.ParameterType.Dictionary;
+        case "string":
+            return models_1.ParameterType.String;
+        default:
+            return models_1.ParameterType.String;
+    }
+}

package/dist/registry.d.ts

@@ -1,4 +1,4 @@
-import { ToolsService } from './service';
+import { ToolsService } from "./service";
 /**
  * Internal registry for ToolsService instances
  */

package/dist/registry.js

@@ -5,5 +5,5 @@ exports.registry = void 0;
  * Internal registry for ToolsService instances
  */
 exports.registry = {
-    services: []
+    services: [],
 };

package/dist/service.d.ts

@@ -1,18 +1,14 @@
-import { Express } from 'express';
-import { AuthRequirement, Parameter } from './models';
+import { Express } from "express";
+import { AuthRequirement, Parameter } from "./models";
 export declare class ToolsService {
     private app;
-    private router;
     private functions;
+    private router;
     /**
      * Initialize a new tools service
      * @param app Express application
      */
     constructor(app: Express);
-    /**
-     * Initialize the discovery endpoint
-     */
-    private initRoutes;
     /**
      * Register a tool function
      * @param name Tool name
@@ -21,7 +17,13 @@ export declare class ToolsService {
      * @param parameters List of parameters for the tool
      * @param endpoint API endpoint for the tool
      * @param authRequirements Authentication requirements (optional)
+     * @param responseType Response type - 'json' (default) or 'block'
+     * @param isNewStyle Whether this is a new-style tool (registerTool) vs legacy decorator
      */
     registerTool(name: string, description: string, handler: any, // Changed from Function to any to avoid confusion with built-in Function type
-    parameters: Parameter[], endpoint: string, authRequirements?: AuthRequirement[]): void;
+    parameters: Parameter[], endpoint: string, authRequirements?: AuthRequirement[], responseType?: "block" | "json", isNewStyle?: boolean): void;
+    /**
+     * Initialize the discovery endpoint
+     */
+    private initRoutes;
 }

package/dist/service.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolsService = void 0;
 const express_1 = __importDefault(require("express"));
+const block_1 = require("./block");
 const models_1 = require("./models");
 const registry_1 = require("./registry");
 class ToolsService {
@@ -20,15 +21,6 @@ class ToolsService {
         // Register this service in the global registry
         registry_1.registry.services.push(this);
     }
-    /**
-     * Initialize the discovery endpoint
-     */
-    initRoutes() {
-        this.router.get('/discovery', (req, res) => {
-            res.json({ functions: this.functions.map(f => f.toJSON()) });
-        });
-        this.app.use(this.router);
-    }
     /**
      * Register a tool function
      * @param name Tool name
@@ -37,11 +29,17 @@ class ToolsService {
      * @param parameters List of parameters for the tool
      * @param endpoint API endpoint for the tool
      * @param authRequirements Authentication requirements (optional)
+     * @param responseType Response type - 'json' (default) or 'block'
+     * @param isNewStyle Whether this is a new-style tool (registerTool) vs legacy decorator
      */
-    registerTool(name, description, handler, // Changed from Function to any to avoid confusion with built-in Function type
-    parameters, endpoint, authRequirements) {
+    registerTool(name, description, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler, // Changed from Function to any to avoid confusion with built-in Function type
+    parameters, endpoint, authRequirements, responseType = "json", isNewStyle = false) {
         const func = new models_1.Function(name, description, parameters, endpoint, authRequirements);
         this.functions.push(func);
+        // Determine if this is a block tool
+        const isBlockTool = responseType === "block";
         // Register the actual endpoint
         this.router.post(endpoint, async (req, res) => {
             try {
@@ -61,28 +59,58 @@ class ToolsService {
                 // Extract auth data if available
                 const authData = req.body && req.body.auth;
                 if (authData) {
-                    console.log(`Auth data provided for provider: ${authData.provider || 'unknown'}`);
+                    console.log(`Auth data provided for provider: ${authData.provider || "unknown"}`);
                 }
-                // Call the handler with extracted parameters and auth data
-                // Check if handler accepts auth as third parameter
-                const handlerParamCount = handler.length;
+                // Call the handler with extracted parameters
                 let result;
-                if (handlerParamCount >= 2) {
-                    // Handler accepts auth data
-                    result = await handler(params, authData);
+                if (isNewStyle) {
+                    result = await handler(params, {
+                        mode: (req.body && req.body.execution_mode) || "headless",
+                        ...(authData && { auth: authData }),
+                    });
                 }
                 else {
-                    // Handler doesn't accept auth data
-                    result = await handler(params);
+                    // Check if handler accepts auth as third parameter
+                    const handlerParamCount = handler.length;
+                    if (handlerParamCount >= 2) {
+                        // Handler accepts auth data
+                        result = await handler(params, authData);
+                    }
+                    else {
+                        // Handler doesn't accept auth data
+                        result = await handler(params);
+                    }
                 }
                 console.log(`Tool ${name} returned:`, result);
-                res.json(result);
+                // Return with appropriate content-type header
+                if (isBlockTool) {
+                    // Validate that block tools return a BlockResponse
+                    if (!(0, block_1.isBlockResponse)(result)) {
+                        throw new Error(`Block tool '${name}' must return a BlockResponse object, but returned ${typeof result}`);
+                    }
+                    res.set("Content-Type", "application/vnd.opal.block+json");
+                    res.json(result);
+                }
+                else {
+                    res.json(result);
+                }
             }
             catch (error) {
                 console.error(`Error in tool ${name}:`, error);
-                res.status(500).json({ error: error.message || 'Unknown error' });
+                res.status(500).json({
+                    error: error instanceof Error ? error.message : "Unknown error",
+                });
             }
         });
     }
+    /**
+     * Initialize the discovery endpoint
+     */
+    initRoutes() {
+        this.router.get("/discovery", (req, res) => {
+            res.json({ functions: this.functions.map((f) => f.toJSON()) });
+        });
+        this.app.use(this.router);
+    }
 }
 exports.ToolsService = ToolsService;

package/eslint.config.js

@@ -0,0 +1,20 @@
+const typescript = require("typescript-eslint");
+const perfectionist = require("eslint-plugin-perfectionist");
+
+module.exports = typescript.config(
+  {
+    ignores: ["dist/**", "node_modules/**", "*.config.js"],
+  },
+  ...typescript.configs.recommended,
+  perfectionist.configs["recommended-natural"],
+  {
+    files: ["**/*.ts"],
+    ignores: ["*.config.ts"],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: __dirname,
+      },
+    },
+  },
+);

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@optimizely-opal/opal-tools-sdk",
-  "version": "0.1.3-dev",
+  "version": "0.1.6-dev",
   "description": "SDK for creating Opal-compatible tools services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "tsc",
-    "test": "jest",
-    "prepublishOnly": "npm run build"
+    "build": "tsc -p tsconfig.build.json",
+    "generate:block": "ts-node scripts/generate-block.ts",
+    "lint": "bash scripts/lint.sh",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
   },
   "keywords": [
     "opal",
@@ -19,20 +21,27 @@
   "author": "Optimizely",
   "license": "MIT",
   "dependencies": {
-    "express": "^4.18.2",
-    "axios": "^1.6.0",
     "reflect-metadata": "^0.1.13"
   },
   "devDependencies": {
-    "@types/express": "^4.17.17",
-    "@types/jest": "^29.5.3",
     "@types/node": "^20.4.5",
-    "jest": "^29.6.2",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.1.6"
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.39.2",
+    "eslint-plugin-perfectionist": "^5.4.0",
+    "json-schema-to-typescript": "^13.1.1",
+    "prettier": "^3.8.1",
+    "supertest": "^7.0.0",
+    "ts-node": "^10.9.2",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^1.2.0"
   },
   "peerDependencies": {
-    "express": "^4.18.2"
+    "@types/express": "^4.17.17",
+    "@types/node": "^20.4.5",
+    "axios": "^1.6.0",
+    "express": "^4.18.2",
+    "typescript": "^5.1.6",
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "repository": {
     "type": "git",