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

package/src/registry.ts

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

package/src/service.ts

@@ -1,11 +1,13 @@
-import express, { Express, Request, Response, Router } from 'express';
-import { Function, AuthRequirement, Parameter } from './models';
-import { registry } from './registry';
+import express, { Express, Request, Response, Router } from "express";
+
+import { isBlockResponse } from "./block";
+import { AuthRequirement, Function, Parameter } from "./models";
+import { registry } from "./registry";
 
 export class ToolsService {
   private app: Express;
-  private router: Router;
   private functions: Function[] = [];
+  private router: Router;
 
   /**
    * Initialize a new tools service
@@ -15,22 +17,11 @@ export class ToolsService {
     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
@@ -39,23 +30,37 @@ export 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,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     handler: any, // Changed from Function to any to avoid confusion with built-in Function type
     parameters: Parameter[],
     endpoint: string,
-    authRequirements?: AuthRequirement[]
+    authRequirements?: AuthRequirement[],
+    responseType: "block" | "json" = "json",
+    isNewStyle: boolean = false,
   ): void {
-    const func = new Function(name, description, parameters, endpoint, authRequirements);
+    const func = new 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: 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) {
@@ -64,35 +69,73 @@ export class ToolsService {
           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.`);
+          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'}`);
+          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);
-      } catch (error: any) {
+
+        // Return with appropriate content-type header
+        if (isBlockTool) {
+          // Validate that block tools return a BlockResponse
+          if (!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
+   */
+  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);
+  }
 }

package/tests/block.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for Adaptive Block components
+ */
+
+import { describe, expect, test } from "vitest";
+
+import type { BlockResponse } from "../src";
+
+import { Block } from "../src";
+
+describe("Block Components", () => {
+  test("Block.Heading with children", () => {
+    const heading = Block.Heading({ children: "Test Heading" });
+    expect(heading.$type).toBe("Block.Heading");
+
+    const response: BlockResponse = {
+      content: Block.Document({ children: heading }),
+    };
+    expect(response).toEqual({
+      content: {
+        $type: "Block.Document",
+        children: { $type: "Block.Heading", children: "Test Heading" },
+      },
+    });
+  });
+
+  test("Block.Text with children", () => {
+    const text = Block.Text({ children: "Test text content" });
+    expect(text.$type).toBe("Block.Text");
+
+    const response: BlockResponse = {
+      content: Block.Document({ children: text }),
+    };
+    expect(response).toEqual({
+      content: {
+        $type: "Block.Document",
+        children: { $type: "Block.Text", children: "Test text content" },
+      },
+    });
+  });
+
+  test("Block.Heading with additional properties", () => {
+    const heading = Block.Heading({
+      children: "Styled Heading",
+      fontSize: "md",
+      fontWeight: "600",
+      level: "2",
+    });
+
+    const response: BlockResponse = {
+      content: Block.Document({ children: heading }),
+    };
+    expect(response).toEqual({
+      content: {
+        $type: "Block.Document",
+        children: {
+          $type: "Block.Heading",
+          children: "Styled Heading",
+          fontSize: "md",
+          fontWeight: "600",
+          level: "2",
+        },
+      },
+    });
+  });
+
+  test("Block.Group with children array", () => {
+    const group = Block.Group({
+      children: [
+        Block.Text({ children: "First item" }),
+        Block.Text({ children: "Second item" }),
+      ],
+      flexDirection: "column",
+      gap: "16",
+    });
+
+    const response: BlockResponse = {
+      content: Block.Document({ children: group }),
+    };
+    expect(response).toEqual({
+      content: {
+        $type: "Block.Document",
+        children: {
+          $type: "Block.Group",
+          children: [
+            { $type: "Block.Text", children: "First item" },
+            { $type: "Block.Text", children: "Second item" },
+          ],
+          flexDirection: "column",
+          gap: "16",
+        },
+      },
+    });
+  });
+
+  test("Block.Document", () => {
+    const doc = Block.Document({
+      children: [
+        Block.Heading({ children: "Title", level: "2" }),
+        Block.Text({ children: "Description" }),
+      ],
+    });
+
+    const response: BlockResponse = { content: doc };
+    expect(response).toEqual({
+      content: {
+        $type: "Block.Document",
+        children: [
+          { $type: "Block.Heading", children: "Title", level: "2" },
+          { $type: "Block.Text", children: "Description" },
+        ],
+      },
+    });
+  });
+});

package/tests/integration.test.ts

@@ -0,0 +1,318 @@
+/**
+ * Tests for Express integration with the registerTool() function
+ */
+
+import express from "express";
+import request from "supertest";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod/v4";
+
+import { Block, ParameterType, registerTool, tool, ToolsService } from "../src";
+import { registry } from "../src/registry";
+
+// Clear registry before each test
+beforeEach(() => {
+  registry.services = [];
+});
+
+afterEach(() => {
+  registry.services = [];
+});
+
+describe("Integration Tests", () => {
+  test("simple tool endpoint", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerTool(
+      "greet",
+      {
+        description: "Greet a user",
+        inputSchema: {
+          name: z.string().describe("The name to greet"),
+        },
+      },
+      async (params) => {
+        return `Hello, ${params.name}!`;
+      },
+    );
+
+    // Call the endpoint
+    const response = await request(app)
+      .post("/tools/greet")
+      .send({ parameters: { name: "Alice" } });
+
+    expect(response.status).toBe(200);
+    // Verify correct content-type header for regular tools
+    expect(response.headers["content-type"]).toMatch(/application\/json/);
+    expect(response.body).toBe("Hello, Alice!");
+  });
+
+  test("block tool endpoint correctly serializes all fields", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerTool(
+      "create_task",
+      {
+        description: "Create a task",
+        inputSchema: {
+          name: z.string().describe("Task name"),
+        },
+        type: "block",
+      },
+      async (params) => {
+        return {
+          artifact: {
+            data: { name: params.name },
+            id: "task-123",
+            type: "task",
+          },
+          content: Block.Document({
+            children: Block.Text({ children: `Created task: ${params.name}` }),
+          }),
+          data: { created_at: "2024-01-01T00:00:00Z" },
+          rollback: {
+            config: { endpoint: "/api/tasks/task-123", method: "DELETE" },
+            label: "Delete Task",
+            type: "endpoint",
+          },
+        };
+      },
+    );
+
+    const response = await request(app)
+      .post("/tools/create-task")
+      .send({ parameters: { name: "My Task" } });
+
+    expect(response.status).toBe(200);
+    expect(response.headers["content-type"]).toBe(
+      "application/vnd.opal.block+json; charset=utf-8",
+    );
+    expect(response.body).toEqual({
+      artifact: { data: { name: "My Task" }, id: "task-123", type: "task" },
+      content: {
+        $type: "Block.Document",
+        children: { $type: "Block.Text", children: "Created task: My Task" },
+      },
+      data: { created_at: "2024-01-01T00:00:00Z" },
+      rollback: {
+        config: { endpoint: "/api/tasks/task-123", method: "DELETE" },
+        label: "Delete Task",
+        type: "endpoint",
+      },
+    });
+  });
+
+  test("environment parameter is correctly passed to tool", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerTool(
+      "check_env",
+      {
+        description: "Check environment",
+        inputSchema: {
+          name: z.string().describe("Name parameter"),
+        },
+      },
+      async (params, extra) => {
+        return {
+          has_environment: extra !== undefined,
+          param_name: params.name,
+        };
+      },
+    );
+
+    const response = await request(app)
+      .post("/tools/check-env")
+      .send({ parameters: { name: "Test" } });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({
+      has_environment: true,
+      param_name: "Test",
+    });
+  });
+
+  test("invalid parameters return proper error", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerTool(
+      "validate_params",
+      {
+        description: "Validate parameters",
+        inputSchema: {
+          name: z.string().describe("Required name"),
+        },
+      },
+      async (params) => {
+        if (!params.name) {
+          throw new Error("Name is required");
+        }
+        return `Valid: ${params.name}`;
+      },
+    );
+
+    // Call with missing required parameter
+    const response = await request(app)
+      .post("/tools/validate-params")
+      .send({ parameters: {} });
+
+    expect(response.status).toBe(500);
+    expect(response.body).toHaveProperty("error");
+  });
+
+  test("multiple tools on same service and discovery endpoint", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    // Use legacy @tool decorator for first tool by calling it as a function
+    const getWeatherHandler = async () => {
+      return { condition: "sunny", temperature: 22 };
+    };
+
+    tool({
+      description: "Gets current weather for a location",
+      name: "get_weather",
+      parameters: [
+        {
+          description: "City name or location",
+          name: "location",
+          required: true,
+          type: ParameterType.String,
+        },
+        {
+          description: "Temperature units",
+          name: "units",
+          required: false,
+          type: ParameterType.String,
+        },
+      ],
+    })(getWeatherHandler);
+
+    // Use modern registerTool for second tool
+    registerTool(
+      "create_task",
+      {
+        authRequirements: {
+          provider: "google",
+          required: true,
+          scopeBundle: "tasks",
+        },
+        description: "Create a new task",
+        inputSchema: {
+          title: z.string().describe("Task title"),
+        },
+        type: "block",
+      },
+      async (params) => {
+        return {
+          content: Block.Document({
+            children: Block.Text({ children: `Task: ${params.title}` }),
+          }),
+        };
+      },
+    );
+
+    // Test both tool endpoints work
+    const weatherResponse = await request(app)
+      .post("/tools/get-weather")
+      .send({ parameters: { location: "San Francisco" } });
+    const taskResponse = await request(app)
+      .post("/tools/create-task")
+      .send({ parameters: { title: "My Task" } });
+
+    expect(weatherResponse.status).toBe(200);
+    expect(taskResponse.status).toBe(200);
+
+    // Test discovery endpoint
+    const discoveryResponse = await request(app).get("/discovery");
+
+    expect(discoveryResponse.status).toBe(200);
+    expect(discoveryResponse.headers["content-type"]).toMatch(
+      /application\/json/,
+    );
+    expect(discoveryResponse.body).toEqual({
+      functions: [
+        {
+          description: "Gets current weather for a location",
+          endpoint: "/tools/get-weather",
+          http_method: "POST",
+          name: "get_weather",
+          parameters: [
+            {
+              description: "City name or location",
+              name: "location",
+              required: true,
+              type: "string",
+            },
+            {
+              description: "Temperature units",
+              name: "units",
+              required: false,
+              type: "string",
+            },
+          ],
+        },
+        {
+          auth_requirements: [
+            {
+              provider: "google",
+              required: true,
+              scope_bundle: "tasks",
+            },
+          ],
+          description: "Create a new task",
+          endpoint: "/tools/create-task",
+          http_method: "POST",
+          name: "create_task",
+          parameters: [
+            {
+              description: "Task title",
+              name: "title",
+              required: true,
+              type: "string",
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("block tool without BlockResponse throws error", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    // @ts-expect-error - Testing runtime validation of invalid block tool return type
+    registerTool(
+      "invalid_block",
+      {
+        description: "Block tool that returns wrong type",
+        inputSchema: {
+          name: z.string().describe("Name"),
+        },
+        type: "block",
+      },
+      async (params) => {
+        // This should fail - block tools must return BlockResponse
+        return `This should fail: ${params.name}`;
+      },
+    );
+
+    const response = await request(app)
+      .post("/tools/invalid-block")
+      .send({ parameters: { name: "Test" } });
+
+    // Should return 500 error because block tools must return BlockResponse
+    expect(response.status).toBe(500);
+    expect(response.body.error).toContain("must return a BlockResponse object");
+  });
+});

package/tsconfig.build.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}

package/tsconfig.json

@@ -11,6 +11,6 @@
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true
   },
-  "include": ["src"],
-  "exclude": ["node_modules", "**/*.test.ts"]
-}
+  "include": ["scripts", "src", "tests"],
+  "exclude": ["node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+});