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

package/scripts/generate-block.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env ts-node
+/**
+ * Generate Adaptive Block Document types from JSON schema.
+ *
+ * This script uses json-schema-to-typescript to generate TypeScript interfaces
+ * from the block-document-spec.json schema. The generated types will replace the
+ * manual Block builders once we're ready to switch over.
+ *
+ * Usage:
+ *   npm run generate:block
+ */
+
+import type { JSONSchema7 } from "json-schema";
+
+import * as fs from "fs";
+import { compile } from "json-schema-to-typescript";
+import * as path from "path";
+
+/**
+ * Generate builder functions and BlockResponse class.
+ *
+ * The generated TypeScript interfaces are great for validation, but we want to
+ * keep the builder API (Block.Document(), etc.) for ease of use.
+ */
+function generateBuilderCode(schema: JSONSchema7): string {
+  // Extract all Block components from definitions
+  const blockComponents: Array<{ fullName: string; shortName: string }> = [];
+  const skipTypes = new Set(["BlockElement", "BlockNode"]);
+
+  if (schema.definitions) {
+    for (const componentName of Object.keys(schema.definitions)) {
+      if (componentName.startsWith("Block") && !skipTypes.has(componentName)) {
+        // Extract the short name (e.g., "Document" from "BlockDocument")
+        const shortName = componentName.substring(5); // Remove "Block" prefix
+        blockComponents.push({ fullName: componentName, shortName });
+      }
+    }
+  }
+
+  // Sort components for consistent output
+  blockComponents.sort((a, b) => a.shortName.localeCompare(b.shortName));
+
+  // Generate factory functions that return properly typed objects
+  const builderMethods = blockComponents
+    .map(
+      ({ fullName, shortName }) =>
+        `  ${shortName}: (props: Omit<${fullName}, '$type'>): ${fullName} => ({ $type: 'Block.${shortName}' as const, ...props }),`,
+    )
+    .join("\n");
+
+  return `
+/**
+ * Builder namespace for Adaptive Block Document components.
+ *
+ * Usage:
+ *   Block.Document({ children: [...] })
+ *   Block.Heading({ children: "Title", level: "2" })
+ *   Block.Input({ name: "field_name", placeholder: "Enter..." })
+ */
+export const Block = {
+${builderMethods}
+};
+
+/**
+ * Response type for Adaptive Block Documents.
+ *
+ * A Block response is a structured tool return value with up to five optional fields:
+ * - content: UI representation (BlockDocument)
+ * - data: Extra context for LLM (optional, use only when needed beyond artifact/error)
+ * - artifact: Object that was impacted (optional)
+ * - rollback: Undo operation (optional)
+ * - error: Error information (optional)
+ */
+export type BlockResponse = {
+  content?: BlockDocument;
+  data?: Record<string, unknown>;
+  artifact?: {
+    type: string;
+    id: string;
+    data: Record<string, unknown>;
+  };
+  rollback?: {
+    type: 'endpoint' | 'tool';
+    config: Record<string, unknown>;
+    label?: string;
+  };
+  error?: {
+    message: string;
+    code?: string;
+    details?: Record<string, unknown>;
+  };
+};
+
+/**
+ * Type guard to check if a value is a BlockResponse.
+ */
+export function isBlockResponse(value: unknown): value is BlockResponse {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    ('content' in value || 'data' in value || 'artifact' in value || 'rollback' in value || 'error' in value)
+  );
+}
+`;
+}
+
+async function main() {
+  // Paths
+  const scriptDir = __dirname;
+  const sdkRoot = path.join(scriptDir, "..");
+  const schemaFile = path.join(sdkRoot, "..", "block-document-spec.json");
+  const outputFile = path.join(sdkRoot, "src", "block.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("Block"))
+        .map((key) => ({ $ref: `#/definitions/${key}` })),
+    };
+
+    // Generate TypeScript types
+    const ts = await compile(schemaWithExports, "BlockDocumentSchema", {
+      bannerComment: `/**
+ * Generated by json-schema-to-typescript
+ * DO NOT MODIFY - This file is auto-generated from block-document-spec.json
+ * Run 'npm run generate:block' to regenerate
+ */`,
+      declareExternallyReferenced: true,
+      strictIndexSignatures: true,
+      style: {
+        semi: true,
+        singleQuote: true,
+      },
+      unknownAny: false,
+      unreachableDefinitions: false,
+    });
+
+    // Post-process to add builder functions and BlockResponse
+    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;
   };
 }