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

package/README.md

@@ -0,0 +1,48 @@
+# Opal Tools SDK for TypeScript
+
+This SDK simplifies the creation of tools services compatible with the Opal Tools Management Service.
+
+## Features
+
+- Type definitions for tools and parameters
+- Express middleware for discovery endpoints
+- Decorators for tool registration
+- Parameter validation
+- Authentication helpers
+
+## Installation
+
+```bash
+npm install @optimizely-opal/opal-tools-sdk
+```
+
+## Usage
+
+```typescript
+import { ToolsService, tool } from '@optimizely-opal/opal-tools-sdk';
+import express from 'express';
+
+interface WeatherParameters {
+  location: string;
+  units?: string;
+}
+
+const app = express();
+const toolsService = new ToolsService(app);
+
+@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
+app.listen(3000);
+```
+
+## Documentation
+
+See full documentation for more examples and configuration options.

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Middleware to handle authentication requirements
+ * @param req Express request
+ * @param res Express response
+ * @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
+ */
+export declare function requiresAuth(options: AuthOptions): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+export {};

package/dist/auth.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authMiddleware = authMiddleware;
+exports.requiresAuth = requiresAuth;
+/**
+ * Middleware to handle authentication requirements
+ * @param req Express request
+ * @param res Express response
+ * @param next Express next function
+ */
+function authMiddleware(req, res, next) {
+    const authHeader = req.headers.authorization;
+    if (!authHeader && req.authRequired) {
+        return res.status(401).json({ error: 'Authentication required' });
+    }
+    // The Tools Management Service will provide the appropriate token
+    // in the Authorization header
+    next();
+}
+/**
+ * Decorator to indicate that a tool requires authentication
+ * @param options Authentication options
+ */
+function requiresAuth(options) {
+    return function (target, propertyKey, descriptor) {
+        const isMethod = propertyKey && descriptor;
+        if (isMethod && descriptor) {
+            const originalMethod = descriptor.value;
+            descriptor.value = function (...args) {
+                // Store auth requirements in function metadata
+                const fn = originalMethod;
+                fn.__authRequirements__ = {
+                    provider: options.provider,
+                    scopeBundle: options.scopeBundle,
+                    required: options.required ?? true
+                };
+                return originalMethod.apply(this, args);
+            };
+            return descriptor;
+        }
+        return target;
+    };
+}

package/dist/decorators.d.ts

@@ -0,0 +1,36 @@
+import 'reflect-metadata';
+import { ParameterType } from './models';
+interface ParameterDefinition {
+    name: string;
+    type: ParameterType;
+    description: string;
+    required: boolean;
+}
+interface ToolOptions {
+    name: string;
+    description: string;
+    parameters?: ParameterDefinition[];
+    authRequirements?: {
+        provider: string;
+        scopeBundle: string;
+        required?: boolean;
+    };
+}
+/**
+ * Decorator to register a function as an Opal tool
+ * @param options Tool options including:
+ *   - name: Name of the tool
+ *   - description: Description of the tool
+ *   - 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> {
+ *   // Your tool implementation
+ * }
+ * ```
+ */
+export declare function tool(options: ToolOptions): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+export {};

package/dist/decorators.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tool = tool;
+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:
+ *   - name: Name of the tool
+ *   - description: Description of the tool
+ *   - 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> {
+ *   // Your tool implementation
+ * }
+ * ```
+ */
+function tool(options) {
+    return function (target, propertyKey, descriptor) {
+        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 = [];
+        if (options.parameters && options.parameters.length > 0) {
+            // Use the explicitly provided parameter definitions
+            for (const paramDef of options.parameters) {
+                parameters.push(new models_1.Parameter(paramDef.name, paramDef.type, paramDef.description, paramDef.required));
+            }
+        }
+        // Create auth requirements if specified
+        let authRequirements;
+        if (options.authRequirements) {
+            authRequirements = [
+                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);
+        }
+        return isMethod ? descriptor : target;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import 'reflect-metadata';
+export { ToolsService } from './service';
+export { tool } from './decorators';
+export { requiresAuth } from './auth';
+export * from './models';

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+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; } });
+__exportStar(require("./models"), exports);

package/dist/models.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Types of parameters supported by Opal tools
+ */
+export declare enum ParameterType {
+    String = "string",
+    Integer = "integer",
+    Number = "number",
+    Boolean = "boolean",
+    List = "list",
+    Dictionary = "object"
+}
+/**
+ * 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(): {
+        name: string;
+        type: ParameterType;
+        description: string;
+        required: boolean;
+    };
+}
+/**
+ * Authentication requirements for an Opal tool
+ */
+export declare class AuthRequirement {
+    provider: string;
+    scopeBundle: string;
+    required: boolean;
+    /**
+     * Create a new authentication requirement
+     * @param provider Auth provider (e.g., "google", "microsoft")
+     * @param scopeBundle Scope bundle (e.g., "calendar", "drive")
+     * @param required Whether authentication is required
+     */
+    constructor(provider: string, scopeBundle: string, required?: boolean);
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON(): {
+        provider: string;
+        scope_bundle: string;
+        required: boolean;
+    };
+}
+/**
+ * Function definition for an Opal tool
+ */
+export declare class Function {
+    name: string;
+    description: string;
+    parameters: Parameter[];
+    endpoint: string;
+    authRequirements?: AuthRequirement[] | undefined;
+    /**
+     * HTTP method for the endpoint (default: POST)
+     */
+    httpMethod: string;
+    /**
+     * Create a new function definition
+     * @param name Function name
+     * @param description Function description
+     * @param parameters Function parameters
+     * @param endpoint API endpoint
+     * @param authRequirements Authentication requirements (optional)
+     */
+    constructor(name: string, description: string, parameters: Parameter[], endpoint: string, authRequirements?: AuthRequirement[] | undefined);
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON(): any;
+}

package/dist/models.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Function = exports.AuthRequirement = exports.Parameter = 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"] = "list";
+    ParameterType["Dictionary"] = "object";
+})(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
+ */
+class AuthRequirement {
+    /**
+     * Create a new authentication requirement
+     * @param provider Auth provider (e.g., "google", "microsoft")
+     * @param scopeBundle Scope bundle (e.g., "calendar", "drive")
+     * @param required Whether authentication is required
+     */
+    constructor(provider, scopeBundle, required = true) {
+        this.provider = provider;
+        this.scopeBundle = scopeBundle;
+        this.required = required;
+    }
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON() {
+        return {
+            provider: this.provider,
+            scope_bundle: this.scopeBundle,
+            required: this.required
+        };
+    }
+}
+exports.AuthRequirement = AuthRequirement;
+/**
+ * Function definition for an Opal tool
+ */
+class Function {
+    /**
+     * Create a new function definition
+     * @param name Function name
+     * @param description Function description
+     * @param parameters Function parameters
+     * @param endpoint API endpoint
+     * @param authRequirements Authentication requirements (optional)
+     */
+    constructor(name, description, parameters, endpoint, authRequirements) {
+        this.name = name;
+        this.description = description;
+        this.parameters = parameters;
+        this.endpoint = endpoint;
+        this.authRequirements = authRequirements;
+        /**
+         * HTTP method for the endpoint (default: POST)
+         */
+        this.httpMethod = 'POST';
+    }
+    /**
+     * Convert to JSON for the discovery endpoint
+     */
+    toJSON() {
+        const result = {
+            name: this.name,
+            description: this.description,
+            parameters: this.parameters.map(p => p.toJSON()),
+            endpoint: this.endpoint,
+            http_method: this.httpMethod
+        };
+        if (this.authRequirements && this.authRequirements.length > 0) {
+            result.auth_requirements = this.authRequirements.map(auth => auth.toJSON());
+        }
+        return result;
+    }
+}
+exports.Function = Function;

package/dist/registry.d.ts

@@ -0,0 +1,7 @@
+import { ToolsService } from './service';
+/**
+ * Internal registry for ToolsService instances
+ */
+export declare const registry: {
+    services: ToolsService[];
+};

package/dist/registry.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registry = void 0;
+/**
+ * Internal registry for ToolsService instances
+ */
+exports.registry = {
+    services: []
+};

package/dist/service.d.ts

@@ -0,0 +1,27 @@
+import { Express } from 'express';
+import { AuthRequirement, Parameter } from './models';
+export declare class ToolsService {
+    private app;
+    private router;
+    private functions;
+    /**
+     * 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
+     * @param description Tool description
+     * @param handler Function implementing the tool
+     * @param parameters List of parameters for the tool
+     * @param endpoint API endpoint for the tool
+     * @param authRequirements Authentication requirements (optional)
+     */
+    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;
+}

package/dist/service.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolsService = void 0;
+const express_1 = __importDefault(require("express"));
+const models_1 = require("./models");
+const registry_1 = require("./registry");
+class ToolsService {
+    /**
+     * Initialize a new tools service
+     * @param app Express application
+     */
+    constructor(app) {
+        this.functions = [];
+        this.app = app;
+        this.router = express_1.default.Router();
+        this.initRoutes();
+        // 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
+     * @param description Tool description
+     * @param handler Function implementing the tool
+     * @param parameters List of parameters for the tool
+     * @param endpoint API endpoint for the tool
+     * @param authRequirements Authentication requirements (optional)
+     */
+    registerTool(name, description, handler, // Changed from Function to any to avoid confusion with built-in Function type
+    parameters, endpoint, authRequirements) {
+        const func = new models_1.Function(name, description, parameters, endpoint, authRequirements);
+        this.functions.push(func);
+        // Register the actual endpoint
+        this.router.post(endpoint, async (req, res) => {
+            try {
+                console.log(`Received request for ${endpoint}:`, req.body);
+                // Extract parameters from the request body
+                let params;
+                if (req.body && req.body.parameters) {
+                    // Standard format: { "parameters": { ... } }
+                    params = req.body.parameters;
+                    console.log(`Extracted parameters from 'parameters' key:`, params);
+                }
+                else {
+                    // Fallback for direct testing: { "name": "value" }
+                    console.log(`Warning: 'parameters' key not found in request body. Using body directly.`);
+                    params = req.body;
+                }
+                // Extract auth data if available
+                const authData = req.body && req.body.auth;
+                if (authData) {
+                    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;
+                let result;
+                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);
+            }
+            catch (error) {
+                console.error(`Error in tool ${name}:`, error);
+                res.status(500).json({ error: error.message || 'Unknown error' });
+            }
+        });
+    }
+}
+exports.ToolsService = ToolsService;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@optimizely-opal/opal-tools-sdk",
+  "version": "0.1.0-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"
+  },
+  "keywords": [
+    "opal",
+    "tools",
+    "sdk",
+    "ai",
+    "llm"
+  ],
+  "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"
+  },
+  "peerDependencies": {
+    "express": "^4.18.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/optimizely/opal-tools-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/optimizely/opal-tools-sdk/issues"
+  },
+  "homepage": "https://github.com/optimizely/opal-tools-sdk#readme"
+}

package/src/auth.ts

@@ -0,0 +1,52 @@
+/**
+ * Middleware to handle authentication requirements
+ * @param req Express request
+ * @param res Express response
+ * @param next Express next function
+ */
+export function authMiddleware(req: any, res: any, next: any) {
+  const authHeader = req.headers.authorization;
+  if (!authHeader && req.authRequired) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+  
+  // The Tools Management Service will provide the appropriate token
+  // in the Authorization header
+  next();
+}
+
+interface AuthOptions {
+  provider: string;
+  scopeBundle: string;
+  required?: boolean;
+}
+
+/**
+ * Decorator to indicate that a tool requires authentication
+ * @param options Authentication options
+ */
+export function requiresAuth(options: AuthOptions) {
+  return function(target: any, propertyKey?: string, descriptor?: PropertyDescriptor) {
+    const isMethod = propertyKey && descriptor;
+    
+    if (isMethod && descriptor) {
+      const originalMethod = descriptor.value;
+      
+      descriptor.value = function(...args: any[]) {
+        // Store auth requirements in function metadata
+        const fn = originalMethod as any;
+        fn.__authRequirements__ = {
+          provider: options.provider,
+          scopeBundle: options.scopeBundle,
+          required: options.required ?? true
+        };
+        
+        return originalMethod.apply(this, args);
+      };
+      
+      return descriptor;
+    }
+    
+    return target;
+  };
+}

package/src/decorators.ts

@@ -0,0 +1,134 @@
+import 'reflect-metadata';
+import { ParameterType, Parameter, AuthRequirement } from './models';
+import { registry } from './registry';
+
+interface ParameterDefinition {
+  name: string;
+  type: ParameterType;
+  description: string;
+  required: boolean;
+}
+
+interface ToolOptions {
+  name: string;
+  description: string;
+  parameters?: ParameterDefinition[];
+  authRequirements?: {
+    provider: string;
+    scopeBundle: string;
+    required?: boolean;
+  };
+}
+
+/**
+ * Map a TypeScript type to a ParameterType
+ * @param type TypeScript type
+ */
+function mapTypeToParameterType(type: any): ParameterType {
+  if (type === String || type.name === 'String') {
+    return ParameterType.String;
+  } else if (type === Number || type.name === 'Number') {
+    return ParameterType.Number;
+  } else if (type === Boolean || type.name === 'Boolean') {
+    return ParameterType.Boolean;
+  } else if (type === Array || type.name === 'Array') {
+    return ParameterType.List;
+  } else if (type === Object || type.name === 'Object') {
+    return ParameterType.Dictionary;
+  }
+  
+  // Default to string
+  return ParameterType.String;
+}
+
+/**
+ * Extract parameters from a TypeScript interface
+ * @param paramType Parameter type object
+ */
+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),
+        '', // 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:
+ *   - name: Name of the tool
+ *   - description: Description of the tool
+ *   - 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> {
+ *   // Your tool implementation
+ * }
+ * ```
+ */
+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) {
+      // Use the explicitly provided parameter definitions
+      for (const paramDef of options.parameters) {
+        parameters.push(new Parameter(
+          paramDef.name,
+          paramDef.type,
+          paramDef.description,
+          paramDef.required
+        ));
+      }
+    }
+    
+    // Create auth requirements if specified
+    let authRequirements: AuthRequirement[] | undefined;
+    if (options.authRequirements) {
+      authRequirements = [
+        new AuthRequirement(
+          options.authRequirements.provider,
+          options.authRequirements.scopeBundle,
+          options.authRequirements.required ?? true
+        )
+      ];
+    }
+    
+    // Register the tool with all services
+    for (const service of registry.services) {
+      service.registerTool(
+        options.name,
+        options.description,
+        handler,
+        parameters,
+        endpoint,
+        authRequirements
+      );
+    }
+    
+    return isMethod ? descriptor : target;
+  };
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import 'reflect-metadata';
+
+export { ToolsService } from './service';
+export { tool } from './decorators';
+export { requiresAuth } from './auth';
+export * from './models';

package/src/models.ts

@@ -0,0 +1,115 @@
+/**
+ * Types of parameters supported by Opal tools
+ */
+export enum ParameterType {
+  String = 'string',
+  Integer = 'integer',
+  Number = 'number',
+  Boolean = 'boolean',
+  List = 'list',
+  Dictionary = 'object'
+}
+
+/**
+ * Parameter definition for an Opal tool
+ */
+export 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(
+    public name: string,
+    public type: ParameterType,
+    public description: string,
+    public required: boolean
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      type: this.type,
+      description: this.description,
+      required: this.required
+    };
+  }
+}
+
+/**
+ * Authentication requirements for an Opal tool
+ */
+export class AuthRequirement {
+  /**
+   * Create a new authentication requirement
+   * @param provider Auth provider (e.g., "google", "microsoft")
+   * @param scopeBundle Scope bundle (e.g., "calendar", "drive")
+   * @param required Whether authentication is required
+   */
+  constructor(
+    public provider: string,
+    public scopeBundle: string,
+    public required: boolean = true
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  toJSON() {
+    return {
+      provider: this.provider,
+      scope_bundle: this.scopeBundle,
+      required: this.required
+    };
+  }
+}
+
+/**
+ * Function definition for an Opal tool
+ */
+export class Function {
+  /**
+   * HTTP method for the endpoint (default: POST)
+   */
+  public httpMethod: string = 'POST';
+
+  /**
+   * Create a new function definition
+   * @param name Function name
+   * @param description Function description
+   * @param parameters Function parameters
+   * @param endpoint API endpoint
+   * @param authRequirements Authentication requirements (optional)
+   */
+  constructor(
+    public name: string,
+    public description: string,
+    public parameters: Parameter[],
+    public endpoint: string,
+    public authRequirements?: AuthRequirement[]
+  ) {}
+
+  /**
+   * Convert to JSON for the discovery endpoint
+   */
+  toJSON() {
+    const result: any = {
+      name: this.name,
+      description: this.description,
+      parameters: this.parameters.map(p => p.toJSON()),
+      endpoint: this.endpoint,
+      http_method: this.httpMethod
+    };
+
+    if (this.authRequirements && this.authRequirements.length > 0) {
+      result.auth_requirements = this.authRequirements.map(auth => auth.toJSON());
+    }
+
+    return result;
+  }
+}

package/src/registry.ts

@@ -0,0 +1,8 @@
+import { ToolsService } from './service';
+
+/**
+ * Internal registry for ToolsService instances
+ */
+export const registry = {
+  services: [] as ToolsService[]
+};

package/src/service.ts

@@ -0,0 +1,98 @@
+import express, { Express, Request, Response, Router } from 'express';
+import { Function, AuthRequirement, Parameter } from './models';
+import { registry } from './registry';
+
+export class ToolsService {
+  private app: Express;
+  private router: Router;
+  private functions: Function[] = [];
+
+  /**
+   * Initialize a new tools service
+   * @param app Express application
+   */
+  constructor(app: Express) {
+    this.app = app;
+    this.router = express.Router();
+    this.initRoutes();
+    
+    // Register this service in the global registry
+    registry.services.push(this);
+  }
+
+  /**
+   * Initialize the discovery endpoint
+   */
+  private initRoutes(): void {
+    this.router.get('/discovery', (req: Request, res: Response) => {
+      res.json({ functions: this.functions.map(f => f.toJSON()) });
+    });
+
+    this.app.use(this.router);
+  }
+
+  /**
+   * Register a tool function
+   * @param name Tool name
+   * @param description Tool description
+   * @param handler Function implementing the tool
+   * @param parameters List of parameters for the tool
+   * @param endpoint API endpoint for the tool
+   * @param authRequirements Authentication requirements (optional)
+   */
+  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 {
+    const func = new Function(name, description, parameters, endpoint, authRequirements);
+    this.functions.push(func);
+    
+    // Register the actual endpoint
+    this.router.post(endpoint, async (req: Request, res: Response) => {
+      try {
+        console.log(`Received request for ${endpoint}:`, req.body);
+        
+        // Extract parameters from the request body
+        let params;
+        if (req.body && req.body.parameters) {
+          // Standard format: { "parameters": { ... } }
+          params = req.body.parameters;
+          console.log(`Extracted parameters from 'parameters' key:`, params);
+        } else {
+          // Fallback for direct testing: { "name": "value" }
+          console.log(`Warning: 'parameters' key not found in request body. Using body directly.`);
+          params = req.body;
+        }
+        
+        // Extract auth data if available
+        const authData = req.body && req.body.auth;
+        if (authData) {
+          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;
+        let result;
+        
+        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);
+      } catch (error: any) {
+        console.error(`Error in tool ${name}:`, error);
+        res.status(500).json({ error: error.message || 'Unknown error' });
+      }
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}