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

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@optimizely-opal/opal-tools-sdk",
-  "version": "0.1.5-dev",
+  "version": "0.1.8-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:proteus": "ts-node scripts/generate-proteus.ts",
+    "lint": "bash scripts/lint.sh",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
   },
   "keywords": [
     "opal",
@@ -22,16 +24,24 @@
     "reflect-metadata": "^0.1.13"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.3",
-    "jest": "^29.6.2",
-    "ts-jest": "^29.1.1"
+    "@types/node": "^20.4.5",
+    "@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": {
-    "typescript": "^5.1.6",
-    "@types/node": "^20.4.5",
     "@types/express": "^4.17.17",
+    "@types/node": "^20.4.5",
     "axios": "^1.6.0",
-    "express": "^4.18.2"
+    "express": "^4.18.2",
+    "typescript": "^5.1.6",
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "repository": {
     "type": "git",

package/scripts/generate-proteus.ts

@@ -0,0 +1,135 @@
+#!/usr/bin/env ts-node
+/**
+ * Generate Adaptive Proteus Document types from JSON schema.
+ *
+ * This script uses json-schema-to-typescript to generate TypeScript interfaces
+ * from the proteus-document-spec.json schema. The generated types will replace the
+ * manual Proteus builders once we're ready to switch over.
+ *
+ * Usage:
+ *   npm run generate:proteus
+ */
+
+import * as fs from "fs";
+import { compile } from "json-schema-to-typescript";
+import * as path from "path";
+
+/**
+ * Generate builder functions and ProteusResponse class.
+ *
+ * The generated TypeScript interfaces are great for validation, but we want to
+ * keep the builder API (UI.Document(), etc.) for ease of use.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function generateBuilderCode(schema: any): string {
+  // Extract all Proteus components from definitions
+  const proteusComponents: Array<{ fullName: string; shortName: string }> = [];
+  const skipTypes = new Set([
+    "ProteusAtomicCondition",
+    "ProteusCondition",
+    "ProteusElement",
+    "ProteusEventHandler",
+    "ProteusNode",
+  ]);
+
+  if (schema.definitions) {
+    for (const componentName of Object.keys(schema.definitions)) {
+      if (
+        componentName.startsWith("Proteus") &&
+        !skipTypes.has(componentName)
+      ) {
+        // Extract the short name (e.g., "Document" from "ProteusDocument")
+        const shortName = componentName.substring(7); // Remove "Proteus" prefix
+        proteusComponents.push({ fullName: componentName, shortName });
+      }
+    }
+  }
+
+  // Sort components for consistent output
+  proteusComponents.sort((a, b) => a.shortName.localeCompare(b.shortName));
+
+  // Generate factory functions that return properly typed objects
+  const builderMethods = proteusComponents
+    .map(
+      ({ fullName, shortName }) =>
+        `  ${shortName}: (props: Omit<${fullName}, '$type'>): ${fullName} => ({ $type: '${shortName}' as const, ...props }),`,
+    )
+    .join("\n");
+
+  return `
+/**
+ * Builder namespace for Adaptive UI Document components.
+ *
+ * Usage:
+ *   UI.Document({ children: [...] })
+ *   UI.Heading({ children: "Title", level: "2" })
+ *   UI.Input({ name: "field_name", placeholder: "Enter..." })
+ */
+export const UI = {
+  MIME_TYPE: "application/vnd.opal.proteus+json" as const,
+${builderMethods}
+};
+`;
+}
+
+async function main() {
+  // Paths
+  const scriptDir = __dirname;
+  const sdkRoot = path.join(scriptDir, "..");
+  const schemaFile = path.join(sdkRoot, "..", "proteus-document-spec.json");
+  const outputFile = path.join(sdkRoot, "src", "proteus.ts");
+
+  if (!fs.existsSync(schemaFile)) {
+    console.error(`Error: Schema file not found at ${schemaFile}`);
+    process.exit(1);
+  }
+
+  try {
+    // Read the schema
+    const schema = JSON.parse(fs.readFileSync(schemaFile, "utf-8"));
+
+    // Create a new schema that references all definitions to force their generation
+    const schemaWithExports = {
+      ...schema,
+      definitions: schema.definitions,
+      // Export each definition by creating a oneOf at the root
+      oneOf: Object.keys(schema.definitions || {})
+        .filter((key) => key.startsWith("Proteus"))
+        .map((key) => ({ $ref: `#/definitions/${key}` })),
+    };
+
+    // Generate TypeScript types
+    const ts = await compile(schemaWithExports, "ProteusDocumentSchema", {
+      bannerComment: `/**
+ * Generated by json-schema-to-typescript
+ * DO NOT MODIFY - This file is auto-generated from proteus-document-spec.json
+ * Run 'npm run generate:proteus' to regenerate
+ */`,
+      declareExternallyReferenced: true,
+      strictIndexSignatures: true,
+      style: {
+        semi: true,
+        singleQuote: true,
+      },
+      unknownAny: true,
+      unreachableDefinitions: false,
+    });
+
+    // Post-process to add builder functions
+    const finalContent = ts + "\n" + generateBuilderCode(schema);
+
+    // Write the output file
+    fs.writeFileSync(outputFile, finalContent, "utf-8");
+
+    console.log(`Generated: ${outputFile}`);
+  } catch (error) {
+    console.error("Error: Generation failed");
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/scripts/lint.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+if [[ "$*" == *"--no-fix"* ]]; then
+  prettier --check . && eslint . && tsc --noEmit
+else
+  prettier --write . && eslint --fix . && tsc --noEmit
+fi

package/src/auth.ts

@@ -1,3 +1,10 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+interface AuthOptions {
+  provider: string;
+  required?: boolean;
+  scopeBundle: string;
+}
+
 /**
  * Middleware to handle authentication requirements
  * @param req Express request
@@ -7,46 +14,44 @@
 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' });
+    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) {
+  return function (
+    target: any,
+    propertyKey?: string,
+    descriptor?: PropertyDescriptor,
+  ) {
     const isMethod = propertyKey && descriptor;
-    
+
     if (isMethod && descriptor) {
       const originalMethod = descriptor.value;
-      
-      descriptor.value = function(...args: any[]) {
+
+      descriptor.value = function (...args: any[]) {
         // Store auth requirements in function metadata
         const fn = originalMethod as any;
         fn.__authRequirements__ = {
           provider: options.provider,
+          required: options.required ?? true,
           scopeBundle: options.scopeBundle,
-          required: options.required ?? true
         };
-        
+
         return originalMethod.apply(this, args);
       };
-      
+
       return descriptor;
     }
-    
+
     return target;
   };
 }

package/src/decorators.ts

@@ -1,70 +1,26 @@
-import 'reflect-metadata';
-import { ParameterType, Parameter, AuthRequirement } from './models';
-import { registry } from './registry';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import "reflect-metadata";
+
+import { AuthRequirement, Parameter, ParameterType } from "./models";
+import { registry } from "./registry";
 
 interface ParameterDefinition {
-  name: string;
-  type: ParameterType;
   description: string;
+  name: string;
   required: boolean;
+  type: ParameterType;
 }
 
 interface ToolOptions {
-  name: string;
-  description: string;
-  parameters?: ParameterDefinition[];
   authRequirements?: {
     provider: string;
-    scopeBundle: string;
     required?: boolean;
+    scopeBundle: string;
   };
-}
-
-/**
- * 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;
+  description: string;
+  name: string;
+  parameters?: ParameterDefinition[];
+  uiResource?: string;
 }
 
 /**
@@ -75,6 +31,7 @@ function extractParameters(paramType: any): Parameter[] {
  *   - authRequirements: (Optional) Authentication requirements
  *     Format: { provider: "oauth_provider", scopeBundle: "permissions_scope", required: true }
  *     Example: { provider: "google", scopeBundle: "calendar", required: true }
+ *   - uiResource: (Optional) URI of associated UI resource for dynamic rendering (e.g., "ui://my-app/create-form")
  *
  * Note: If your tool requires authentication, define your handler function with two parameters:
  * ```
@@ -84,24 +41,30 @@ function extractParameters(paramType: any): Parameter[] {
  * ```
  */
 export function tool(options: ToolOptions) {
-  return function(target: any, propertyKey?: string, descriptor?: PropertyDescriptor) {
+  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, '-')}`;
+    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
-        ));
+        parameters.push(
+          new Parameter(
+            paramDef.name,
+            paramDef.type,
+            paramDef.description,
+            paramDef.required,
+          ),
+        );
       }
     }
 
@@ -112,8 +75,8 @@ export function tool(options: ToolOptions) {
         new AuthRequirement(
           options.authRequirements.provider,
           options.authRequirements.scopeBundle,
-          options.authRequirements.required ?? true
-        )
+          options.authRequirements.required ?? true,
+        ),
       ];
     }
 
@@ -125,7 +88,9 @@ export function tool(options: ToolOptions) {
         handler,
         parameters,
         endpoint,
-        authRequirements
+        authRequirements,
+        false,
+        options.uiResource,
       );
     }
 

package/src/index.ts

@@ -1,6 +1,11 @@
-import 'reflect-metadata';
+import "reflect-metadata";
 
-export { ToolsService } from './service';
-export { tool } from './decorators';
-export { requiresAuth } from './auth';
-export * from './models';
+export { requiresAuth } from "./auth";
+export { tool } from "./decorators";
+export * from "./models";
+export { UI } from "./proteus";
+export type * from "./proteus";
+export { registerResource } from "./registerResource";
+export { registerTool } from "./registerTool";
+export type { RequestHandlerExtra } from "./registerTool";
+export { ToolsService } from "./service";