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

package/src/decorators.ts

@@ -1,70 +1,25 @@
-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[];
 }
 
 /**
@@ -84,24 +39,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 +73,8 @@ export function tool(options: ToolOptions) {
         new AuthRequirement(
           options.authRequirements.provider,
           options.authRequirements.scopeBundle,
-          options.authRequirements.required ?? true
-        )
+          options.authRequirements.required ?? true,
+        ),
       ];
     }
 
@@ -125,7 +86,7 @@ export function tool(options: ToolOptions) {
         handler,
         parameters,
         endpoint,
-        authRequirements
+        authRequirements,
       );
     }
 

package/src/index.ts

@@ -1,6 +1,10 @@
-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 { Block, isBlockResponse } from "./block";
+export type * from "./block";
+export { tool } from "./decorators";
+export * from "./models";
+export { registerTool } from "./registerTool";
+export type { RequestHandlerExtra } from "./registerTool";
+export { ToolsService } from "./service";

package/src/models.ts

@@ -2,44 +2,39 @@
  * Types of parameters supported by Opal tools
  */
 export enum ParameterType {
-  String = 'string',
-  Integer = 'integer',
-  Number = 'number',
-  Boolean = 'boolean',
-  List = 'array',
-  Dictionary = 'object'
+  Boolean = "boolean",
+  Dictionary = "object",
+  Integer = "integer",
+  List = "array",
+  Number = "number",
+  String = "string",
 }
 
 /**
- * Parameter definition for an Opal tool
+ * Authentication data 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
-  ) {}
+export type AuthData = {
+  credentials: Credentials;
+  provider: string;
+};
 
-  /**
-   * Convert to JSON for the discovery endpoint
-   */
-  toJSON() {
-    return {
-      name: this.name,
-      type: this.type,
-      description: this.description,
-      required: this.required
-    };
-  }
-}
+/**
+ * Authentication credentials structure
+ */
+export type Credentials = {
+  access_token: string;
+  customer_id: string;
+  instance_id: string;
+  org_sso_id?: string;
+  product_sku: string;
+};
+
+/**
+ * Execution environment for an Opal tool
+ */
+export type Environment = {
+  execution_mode: "headless" | "interactive";
+};
 
 /**
  * Authentication requirements for an Opal tool
@@ -54,7 +49,7 @@ export class AuthRequirement {
   constructor(
     public provider: string,
     public scopeBundle: string,
-    public required: boolean = true
+    public required: boolean = true,
   ) {}
 
   /**
@@ -63,8 +58,8 @@ export class AuthRequirement {
   toJSON() {
     return {
       provider: this.provider,
+      required: this.required,
       scope_bundle: this.scopeBundle,
-      required: this.required
     };
   }
 }
@@ -76,7 +71,7 @@ export class Function {
   /**
    * HTTP method for the endpoint (default: POST)
    */
-  public httpMethod: string = 'POST';
+  public httpMethod: string = "POST";
 
   /**
    * Create a new function definition
@@ -91,23 +86,26 @@ export class Function {
     public description: string,
     public parameters: Parameter[],
     public endpoint: string,
-    public authRequirements?: AuthRequirement[]
+    public authRequirements?: AuthRequirement[],
   ) {}
 
   /**
    * Convert to JSON for the discovery endpoint
    */
   toJSON() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const result: any = {
-      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;
@@ -115,51 +113,23 @@ export class Function {
 }
 
 /**
- * Authentication credentials structure
- */
-export type Credentials ={
-  access_token: string;
-  org_sso_id?: string;
-  customer_id: string;
-  instance_id: string;
-  product_sku: string;
-}
-
-/**
- * Authentication data for an Opal tool
- */
-export type AuthData = {
-  provider: string;
-  credentials: Credentials;
-}
-
-/**
- * Execution environment for an Opal tool
- */
-export type Environment = {
-  execution_mode: "headless" | "interactive";
-}
-
-/**
- * Island field definition for interactive UI components
+ * Island action definition for interactive UI components
  */
-export class IslandField {
+export 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(
     public name: string,
     public label: string,
-    public type: "string" | "boolean" | "json",
-    public value: string = "",
-    public hidden: boolean = false,
-    public options: string[] = []
+    public type: string,
+    public endpoint: string,
+    public operation: string = "create",
   ) {}
 
   /**
@@ -167,34 +137,35 @@ export class IslandField {
    */
   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,
     };
   }
 }
 
 /**
- * Island action definition for interactive UI components
+ * Island field definition for interactive UI components
  */
-export class IslandAction {
+export 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(
     public name: string,
     public label: string,
-    public type: string,
-    public endpoint: string,
-    public operation: string = "create"
+    public type: "boolean" | "json" | "string",
+    public value: string = "",
+    public hidden: boolean = false,
+    public options: string[] = [],
   ) {}
 
   /**
@@ -202,11 +173,12 @@ export class IslandAction {
    */
   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,
     };
   }
 }
@@ -215,8 +187,8 @@ export class IslandAction {
  * Island configuration for interactive UI components
  */
 export class IslandConfig {
-  static Field = IslandField;
   static Action = IslandAction;
+  static Field = IslandField;
 
   /**
    * Create a new island configuration
@@ -229,7 +201,7 @@ export class IslandConfig {
     public fields: IslandField[],
     public actions: IslandAction[],
     public type?: string,
-    public icon?: string
+    public icon?: string,
   ) {}
 
   /**
@@ -237,8 +209,8 @@ export class IslandConfig {
    */
   toJSON() {
     return {
-      fields: this.fields.map((field) => field.toJSON()),
       actions: this.actions.map((action) => action.toJSON()),
+      fields: this.fields.map((field) => field.toJSON()),
     };
   }
 }
@@ -269,7 +241,7 @@ export class IslandResponseConfig {
 export class IslandResponse {
   static ResponseConfig = IslandResponseConfig;
 
-  public type: "island" = "island";
+  public type = "island" as const;
 
   /**
    * Create a new island response
@@ -278,7 +250,7 @@ export class IslandResponse {
    */
   constructor(
     public config: IslandResponseConfig,
-    public message?: string
+    public message?: string,
   ) {}
 
   /**
@@ -300,3 +272,34 @@ export class IslandResponse {
     };
   }
 }
+
+/**
+ * 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 {
+      description: this.description,
+      name: this.name,
+      required: this.required,
+      type: this.type,
+    };
+  }
+}

package/src/registerTool.ts

@@ -0,0 +1,181 @@
+import { z } from "zod/v4";
+
+import type { BlockResponse } from "./block";
+
+import {
+  AuthRequirement,
+  Credentials,
+  Parameter,
+  ParameterType,
+} from "./models";
+import { registry } from "./registry";
+
+/**
+ * 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 });
+ * });
+ * ```
+ */
+// Overload for block tools
+export 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;
+// Overload for JSON tools (or when type is omitted)
+export 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;
+// Implementation
+export function registerTool<TSchema extends Record<string, z.ZodTypeAny>>(
+  name: string,
+  options: ToolOptions<TSchema, "block" | "json">,
+  handler: (
+    params: { [K in keyof TSchema]: z.infer<TSchema[K]> },
+    extra?: RequestHandlerExtra,
+  ) => Promise<unknown> | unknown,
+): typeof handler {
+  // Register the tool with all services
+  const responseType = options.type || "json";
+  for (const service of registry.services) {
+    service.registerTool(
+      name,
+      options.description,
+      handler,
+      jsonSchemaToParameters(z.toJSONSchema(z.object(options.inputSchema))),
+      `/tools/${name.replace(/_/g, "-")}`,
+      options.authRequirements
+        ? [
+            new 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: {
+  properties?: Record<string, unknown>;
+  required?: string[];
+}): Parameter[] {
+  const parameters: Parameter[] = [];
+
+  if (!jsonSchema.properties) {
+    return parameters;
+  }
+
+  const required = jsonSchema.required || [];
+
+  for (const [key, value] of Object.entries(jsonSchema.properties)) {
+    const prop = value as { description?: string; type?: string };
+    parameters.push(
+      new Parameter(
+        key,
+        jsonSchemaTypeToParameterType(prop.type || "string"),
+        prop.description || "",
+        required.includes(key),
+      ),
+    );
+  }
+
+  return parameters;
+}
+
+/**
+ * Map JSON Schema type to ParameterType
+ */
+function jsonSchemaTypeToParameterType(jsonType: string): ParameterType {
+  switch (jsonType) {
+    case "array":
+      return ParameterType.List;
+    case "boolean":
+      return ParameterType.Boolean;
+    case "integer":
+      return ParameterType.Integer;
+    case "number":
+      return ParameterType.Number;
+    case "object":
+      return ParameterType.Dictionary;
+    case "string":
+      return ParameterType.String;
+    default:
+      return ParameterType.String;
+  }
+}

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[],
 };