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

package/tests/integration.test.ts

@@ -0,0 +1,497 @@
+/**
+ * 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 {
+  ParameterType,
+  registerResource,
+  registerTool,
+  tool,
+  ToolsService,
+  UI,
+} 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("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"),
+        },
+      },
+      async (params) => {
+        return {
+          content: UI.Document({
+            appName: "Task Manager",
+            body: UI.Text({ children: `Task: ${params.title}` }),
+            title: "Create Task",
+          }),
+        };
+      },
+    );
+
+    // 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("resource endpoint returns correct content via POST /resources/read", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerResource(
+      "test-form",
+      {
+        description: "A test form",
+        mimeType: "application/vnd.opal.proteus+json",
+        uri: "ui://test-app/form",
+      },
+      async () => {
+        return JSON.stringify({
+          fields: [{ name: "title", type: "text" }],
+          type: "form",
+        });
+      },
+    );
+
+    // Call the POST /resources/read endpoint
+    const response = await request(app)
+      .post("/resources/read")
+      .send({ uri: "ui://test-app/form" });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({
+      mimeType: "application/vnd.opal.proteus+json",
+      text: JSON.stringify({
+        fields: [{ name: "title", type: "text" }],
+        type: "form",
+      }),
+      uri: "ui://test-app/form",
+    });
+  });
+
+  test("tool with uiResource reference", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerResource(
+      "create-form",
+      {
+        description: "Form for creating items",
+        mimeType: "application/vnd.opal.proteus+json",
+        uri: "ui://test-app/create-form",
+      },
+      async () => {
+        return "{}";
+      },
+    );
+
+    registerTool(
+      "create_item",
+      {
+        description: "Create a new item",
+        inputSchema: {
+          title: z.string().describe("The title"),
+        },
+        uiResource: "ui://test-app/create-form",
+      },
+      async (params) => {
+        return { id: "item-123", title: params.title };
+      },
+    );
+
+    // Call discovery endpoint
+    const response = await request(app).get("/discovery");
+
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({
+      functions: [
+        {
+          description: "Create a new item",
+          endpoint: "/tools/create-item",
+          http_method: "POST",
+          name: "create_item",
+          parameters: [
+            {
+              description: "The title",
+              name: "title",
+              required: true,
+              type: "string",
+            },
+          ],
+          ui_resource: "ui://test-app/create-form",
+        },
+      ],
+    });
+  });
+
+  test("POST /resources/read with missing URI returns 400", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerResource(
+      "minimal-resource",
+      {
+        uri: "ui://test-app/minimal",
+      },
+      async () => {
+        return "minimal";
+      },
+    );
+
+    // Call without URI
+    const response = await request(app).post("/resources/read").send({});
+
+    expect(response.status).toBe(400);
+    expect(response.body.error).toBe("Missing required field: uri");
+  });
+
+  test("POST /resources/read with unknown URI returns 404", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    // Call with unknown URI
+    const response = await request(app)
+      .post("/resources/read")
+      .send({ uri: "ui://unknown/resource" });
+
+    expect(response.status).toBe(404);
+    expect(response.body.error).toBe(
+      "Resource not found: ui://unknown/resource",
+    );
+  });
+
+  test("POST /resources/read with non-string handler result returns 500", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerResource(
+      "invalid-resource",
+      {
+        uri: "ui://test-app/invalid",
+      },
+      // @ts-expect-error - intentionally returning wrong type for test
+      async () => {
+        return { invalid: "object" };
+      },
+    );
+
+    // Call the resource
+    const response = await request(app)
+      .post("/resources/read")
+      .send({ uri: "ui://test-app/invalid" });
+
+    expect(response.status).toBe(500);
+    expect(response.body.error).toContain(
+      "Resource handler for 'ui://test-app/invalid' must return a string or ProteusDocument",
+    );
+    expect(response.body.error).toContain("but returned object");
+  });
+
+  test("resource with ProteusDocument return is auto-serialized", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerResource(
+      "dynamic-form",
+      {
+        description: "A dynamic form using UI.Document",
+        uri: "ui://test-app/dynamic-form",
+      },
+      async () => {
+        return UI.Document({
+          actions: [
+            UI.Action({ appearance: "primary", children: "Save" }),
+            UI.CancelAction({ children: "Cancel" }),
+          ],
+          appName: "Item Manager",
+          body: [
+            UI.Heading({ children: "Create Item" }),
+            UI.Field({
+              children: UI.Input({
+                name: "item_name",
+                placeholder: "Enter item name",
+              }),
+              label: "Item Name",
+            }),
+            UI.Field({
+              children: UI.Textarea({
+                name: "description",
+                placeholder: "Enter description",
+              }),
+              label: "Description",
+            }),
+          ],
+          title: "Create New Item",
+        });
+      },
+    );
+
+    // Call the resource endpoint
+    const response = await request(app)
+      .post("/resources/read")
+      .send({ uri: "ui://test-app/dynamic-form" });
+
+    expect(response.status).toBe(200);
+
+    // Verify URI
+    expect(response.body.uri).toBe("ui://test-app/dynamic-form");
+
+    // Verify MIME type was auto-set
+    expect(response.body.mimeType).toBe("application/vnd.opal.proteus+json");
+
+    // Verify the text is a serialized ProteusDocument
+    const parsedDoc = JSON.parse(response.body.text);
+    expect(parsedDoc.$type).toBe("Document");
+    expect(parsedDoc.appName).toBe("Item Manager");
+    expect(parsedDoc.title).toBe("Create New Item");
+    expect(parsedDoc.body).toHaveLength(3);
+    expect(parsedDoc.body[0].$type).toBe("Heading");
+    expect(parsedDoc.body[0].children).toBe("Create Item");
+    expect(parsedDoc.body[1].$type).toBe("Field");
+    expect(parsedDoc.body[1].label).toBe("Item Name");
+    expect(parsedDoc.actions).toHaveLength(2);
+    expect(parsedDoc.actions[0].$type).toBe("Action");
+    expect(parsedDoc.actions[1].$type).toBe("CancelAction");
+  });
+
+  test("resource with ProteusDocument and explicit MIME type preserves MIME type", async () => {
+    const app = express();
+    app.use(express.json());
+    new ToolsService(app);
+
+    registerResource(
+      "custom-mime",
+      {
+        description: "ProteusDocument with custom MIME type",
+        mimeType: "application/custom+json",
+        uri: "ui://test-app/custom-mime",
+      },
+      async () => {
+        return UI.Document({
+          appName: "Test App",
+          body: [UI.Text({ children: "Test" })],
+          title: "Test Document",
+        });
+      },
+    );
+
+    // Call the resource endpoint
+    const response = await request(app)
+      .post("/resources/read")
+      .send({ uri: "ui://test-app/custom-mime" });
+
+    expect(response.status).toBe(200);
+
+    // Verify explicit MIME type is preserved (not auto-set)
+    expect(response.body.mimeType).toBe("application/custom+json");
+  });
+});

package/tests/proteus.test.ts

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

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