@onlineapps/conn-orch-cookbook 2.0.37 → 2.1.0

package/README.md

@@ -52,7 +52,6 @@ const cookbook = require('@onlineapps/conn-orch-cookbook');
 // Use specific modules
 const { CookbookExecutor } = cookbook.executor;
 const { CookbookRouter } = cookbook.router;
-const { CookbookGenerator } = cookbook.transformer;
 
 // Or use factory functions
 const processor = cookbook.createProcessor({
@@ -61,6 +60,11 @@ const processor = cookbook.createProcessor({
 });
 ```
 
+> NOTE: the legacy OpenAPI-to-cookbook transformer (`CookbookGenerator`,
+> `ApiSpecAnalyzer`, `StepTranslator`, `ResponseMapper`, `createTransformer`)
+> was removed in v2.1 together with the operations.json-first migration.
+> Cookbooks are authored against [`operations-registry-contract.md`](../../../docs/standards/operations-registry-contract.md) §3.
+
 ## 📚 Included Modules
 
 ### 1. Core Module (@onlineapps/cookbook-core)
@@ -75,13 +79,7 @@ const processor = cookbook.createProcessor({
 - Variable resolution ($api_input, $steps)
 - Step processing for all types
 
-### 3. Transformer Module (@onlineapps/cookbook-transformer)
-- OpenAPI to cookbook generation
-- API spec analysis
-- Response mapping
-- JSONPath transformations
-
-### 4. Router Module (@onlineapps/cookbook-router)
+### 3. Router Module (@onlineapps/cookbook-router)
 - Service discovery
 - Queue management
 - Retry with exponential backoff
@@ -149,21 +147,6 @@ class WorkflowLauncher {
 }
 ```
 
-### OpenAPI Integration
-
-```javascript
-const { CookbookGenerator } = require('@onlineapps/conn-orch-cookbook');
-
-const generator = new CookbookGenerator({
-  defaultTimeout: 10000,
-  defaultRetry: { maxAttempts: 3, delayMs: 2000 }
-});
-
-// Generate cookbook from OpenAPI spec
-const openApiSpec = require('./api-spec.json');
-const cookbook = generator.generate(openApiSpec);
-```
-
 ## 📖 Cookbook Structure
 
 ### Basic Example (v2.0 Schema)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onlineapps/conn-orch-cookbook",
-  "version": "2.0.37",
-  "description": "Complete cookbook toolkit for all services - unified wrapper including core, executor, transformer, and router functionality",
+  "version": "2.1.0",
+  "description": "Complete cookbook toolkit for all services - unified wrapper including core, executor, and router functionality (operations.json-first; legacy transformer removed)",
   "main": "src/index.js",
   "repository": {
     "type": "git",
@@ -48,9 +48,8 @@
   "dependencies": {
     "@onlineapps/cookbook-core": "2.1.16",
     "@onlineapps/cookbook-executor": "1.0.12",
-    "@onlineapps/cookbook-router": "1.0.32",
+    "@onlineapps/cookbook-router": "1.0.33",
     "@onlineapps/cookbook-template-helpers": "1.0.11",
-    "@onlineapps/cookbook-transformer": "1.1.5",
     "jsonpath": "1.1.1"
   },
   "devDependencies": {

package/src/index.js

@@ -4,24 +4,26 @@
  * @module @onlineapps/conn-orch-cookbook
  * @description Unified cookbook connector for service-wrapper integration.
  * This is a THIN WRAPPER around cookbook-* modules, providing a single
- * unified interface for all cookbook functionality.
+ * unified interface for cookbook parsing, validation, execution and routing.
  *
- * NO DUPLICATION: All implementation is in cookbook-* modules.
- * This connector only re-exports and provides compatibility layer.
+ * NO DUPLICATION: All implementation lives in cookbook-* modules.
+ * This connector only re-exports and wires them together.
  *
- * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-orch-cookbook|GitHub Repository}
+ * The legacy OpenAPI-to-cookbook `cookbook-transformer` module was removed
+ * together with the operations.json-first contract — cookbooks are now
+ * authored per biz-service against the operations contract.
+ *
+ * @see /api/docs/standards/operations-registry-contract.md §3
+ * @see /api/docs/architecture/connector.md
  * @author OA Drive Team
  * @license MIT
  * @since 2.0.0
  */
 
-// Import from shared cookbook modules - NO LOCAL IMPLEMENTATIONS!
 const cookbookCore = require('@onlineapps/cookbook-core');
 const cookbookExecutor = require('@onlineapps/cookbook-executor');
-const cookbookTransformer = require('@onlineapps/cookbook-transformer');
 const cookbookRouter = require('@onlineapps/cookbook-router');
 
-// Re-export all from cookbook-core (parser and validator)
 const {
   parseCookbookFromFile,
   parseCookbookFromFileSync,
@@ -37,7 +39,6 @@ const {
   loadSchema
 } = cookbookCore;
 
-// Re-export all from cookbook-executor
 const {
   CookbookExecutor,
   ContextManager,
@@ -45,16 +46,6 @@ const {
   VariableResolver
 } = cookbookExecutor;
 
-// Re-export all from cookbook-transformer
-const {
-  CookbookGenerator,
-  ApiSpecAnalyzer,
-  StepTranslator,
-  ResponseMapper,
-  createTransformer
-} = cookbookTransformer;
-
-// Re-export all from cookbook-router
 const {
   CookbookRouter,
   ServiceDiscovery,
@@ -63,33 +54,29 @@ const {
   createRouter
 } = cookbookRouter;
 
-// Re-export template helpers
-// NOTE: This package must be present as a dependency of conn-orch-cookbook.
+// NOTE: cookbook-template-helpers must be present as a dependency of conn-orch-cookbook.
 const templateHelpers = require('@onlineapps/cookbook-template-helpers');
 
 
 /**
  * Create a cookbook processor with all capabilities
- * Factory function that creates a processor with parser, validator, executor, and router
+ * Factory that wires parser + validator + executor + (optional) router.
  *
  * @function createProcessor
  * @param {Object} [config={}] - Processor configuration
  * @param {Object} [config.executor] - Executor configuration
  * @param {Object} [config.router] - Router configuration
- * @param {Object} [config.transformer] - Transformer configuration
  * @param {Object} [config.mqClient] - Message queue client for router
  * @param {Object} [config.registryClient] - Registry client for router
- * @returns {Object} Processor instance with process method
+ * @returns {Object} Processor with `process(cookbook, input)` + component accessors.
  *
  * @example
  * const processor = createProcessor({
  *   executor: { timeout: 30000 },
- *   router: { baseUrl: "http://api.example.com" },
- *   mqClient: mqConnector,
- *   registryClient: registryConnector
+ *   router:   { baseUrl: "http://api.example.com" },
+ *   mqClient, registryClient
  * });
- *
- * const result = await processor.process(cookbook);
+ * const result = await processor.process(cookbook, input);
  */
 function createProcessor(config = {}) {
   if (!config || typeof config !== 'object') {
@@ -99,17 +86,13 @@ function createProcessor(config = {}) {
   const router = config.mqClient && config.registryClient
     ? createRouter(config.mqClient, config.registryClient, config.router)
     : null;
-  const transformer = createTransformer(config.transformer);
-  const mapper = new ResponseMapper(config.transformer);
 
   /**
-   * NOTE:
-   * cookbook-executor validates the cookbook in its constructor.
-   * This connector therefore creates the executor lazily when a cookbook is provided.
+   * cookbook-executor validates the cookbook in its constructor, so it is
+   * created lazily when a cookbook is provided.
    *
-   * Also NOTE:
-   * cookbook-executor currently expects `step.id` internally. Our V2.1 format uses `step.step_id`.
-   * We add `id` = `step_id` ONLY for executor execution to keep runtime behavior predictable.
+   * cookbook-executor also expects `step.id` internally. Our V2.1 format
+   * uses `step.step_id`. We add `id = step_id` ONLY for execution.
    */
   const normalizeStepForExecutor = (step) => {
     if (!step || typeof step !== 'object') return step;
@@ -169,56 +152,30 @@ function createProcessor(config = {}) {
   };
 
   return {
-    /**
-     * Process a cookbook through the full pipeline
-     * @param {Object|string} cookbook - Cookbook object or file path
-     * @param {Object} [context={}] - Execution context
-     * @returns {Promise<Object>} Execution result
-     */
     async process(cookbook, input = {}) {
-      // Parse if string (file path)
       if (typeof cookbook === 'string') {
         cookbook = await parseCookbookFromFile(cookbook);
       }
 
-      // Validate
       validateCookbook(cookbook);
-
-      // Validate all references
       validateAllReferences(cookbook);
 
       const cookbookForExecutor = normalizeCookbookForExecutor(cookbook);
       const executor = new CookbookExecutor(cookbookForExecutor, config.executor || {});
 
-      // Execute
       return executor.execute(input);
     },
 
-    // Expose components for direct access
     executor: null,
-    router,
-    transformer,
-    mapper
+    router
   };
 }
 
 /**
- * Helper function to execute a single step
- * Convenience wrapper around CookbookExecutor
+ * Helper: execute a single step.
+ * Convenience wrapper around CookbookExecutor.
  *
  * @function executeStep
- * @param {Object} step - Step to execute
- * @param {Object} [context={}] - Execution context
- * @returns {Promise<Object>} Step execution result
- *
- * @example
- * const result = await executeStep({
- *   id: "step1",
- *   type: "task",
- *   service: "api",
- *   action: "GET",
- *   endpoint: "/users"
- * });
  */
 async function executeStep(step, context = {}) {
   if (!step || typeof step !== 'object') {
@@ -238,25 +195,15 @@ async function executeStep(step, context = {}) {
 }
 
 /**
- * Helper function to execute a complete workflow
- * Convenience wrapper around CookbookExecutor
+ * Helper: execute a complete workflow.
  *
  * @function executeWorkflow
- * @param {Object} cookbook - Cookbook to execute
- * @param {Object} [context={}] - Execution context
- * @returns {Promise<Object>} Workflow execution result
- *
- * @example
- * const result = await executeWorkflow(cookbook, {
- *   variables: { userId: 123 }
- * });
  */
 async function executeWorkflow(cookbook, context = {}) {
   const processor = createProcessor();
   return await processor.process(cookbook, context);
 }
 
-// Export everything as unified interface
 module.exports = {
   // Parser functions (from cookbook-core)
   parseCookbookFromFile,
@@ -284,13 +231,6 @@ module.exports = {
   StepProcessor,
   VariableResolver,
 
-  // Transformer classes (from cookbook-transformer)
-  CookbookGenerator,
-  ApiSpecAnalyzer,
-  StepTranslator,
-  ResponseMapper,
-  createTransformer,
-
   // Router classes (from cookbook-router)
   CookbookRouter,
   ServiceDiscovery,
@@ -298,10 +238,10 @@ module.exports = {
   RetryHandler,
   createRouter,
 
-  // Template helpers (from cookbook-template-helpers)
+  // Template helpers
   templateHelpers,
 
-  // Legacy classes (shims for backward compatibility)
+  // Legacy class shims (thin adapters — do not grow them)
   CookbookParser: class CookbookParser {
     parse(cookbook) {
       return parseCookbookFromObject(cookbook);
@@ -325,4 +265,4 @@ module.exports = {
   VERSION: '2.0.0',
   COMPATIBLE_CORE_VERSION: cookbookCore.VERSION,
   COMPATIBLE_SCHEMA_VERSION: cookbookCore.SCHEMA_VERSION
-};
+};

package/examples/basicUsage.js

@@ -1,89 +0,0 @@
-/**
- * basicUsage.js
- *
- * Example demonstrating full lifecycle of ServiceRegistryClient:
- * 1. Load environment variables
- * 2. Instantiate client
- * 3. Initialize (setup queues and start listening for requests)
- * 4. Register event listeners (apiDescriptionRequest, heartbeatSent, apiDescriptionSent, error)
- * 5. Start heartbeat loop
- * 6. Graceful shutdown on process signals
- */
-
-function requireEnv(name, description) {
-  const value = process.env[name];
-  if (!value || String(value).trim() === '') {
-    throw new Error(`[conn-orch-cookbook][example] Missing environment variable - ${name} is required. ${description || ''}`);
-  }
-  return String(value).trim();
-}
-
-const { ServiceRegistryClient, EVENTS } = require('agent-registry-client');
-
-// Step 1: Create a new ServiceRegistryClient instance
-const registryClient = new ServiceRegistryClient({
-  amqpUrl: requireEnv('AMQP_URL', 'RabbitMQ URL (IPv4-only recommended: amqp://user:pass@127.0.0.1:PORT)'),
-  serviceName: requireEnv('SERVICE_NAME', 'Service logical name'),
-  version: requireEnv('SERVICE_VERSION', 'Service version (SemVer)'),
-  heartbeatInterval: process.env.HEARTBEAT_INTERVAL ? parseInt(process.env.HEARTBEAT_INTERVAL, 10) : undefined,
-  apiQueue: process.env.API_QUEUE,
-  registryQueue: process.env.REGISTRY_QUEUE
-});
-
-// Step 2: Register event listeners
-registryClient.on(EVENTS.HEARTBEAT_SENT, (msg) => {
-  console.log(`[Heartbeat] Sent at ${msg.timestamp} for ${msg.serviceName}@${msg.version}`);
-});
-
-registryClient.on(EVENTS.API_DESCRIPTION_REQUEST, async (payload) => {
-  console.log(`[API Description Request] for ${payload.serviceName}@${payload.version}`);
-  // Load local API description (from file or in-memory)
-  const apiDesc = await loadLocalApiDescription();
-  await registryClient.sendApiDescription(apiDesc);
-});
-
-registryClient.on(EVENTS.API_DESCRIPTION_SENT, (msg) => {
-  console.log(`[API Description Sent] at ${msg.timestamp} for ${msg.serviceName}@${msg.version}`);
-});
-
-registryClient.on(EVENTS.ERROR, (err) => {
-  console.error('[RegistryClient Error]', err);
-});
-
-(async () => {
-  try {
-    // Step 3: Initialize client (setup queues and listeners)
-    await registryClient.init();
-    console.log('RegistryClient initialized: queues are ready.');
-
-    // Step 4: Start heartbeat loop
-    registryClient.startHeartbeat();
-    console.log('Heartbeat loop started.');
-
-    // Step 5: Graceful shutdown on SIGINT/SIGTERM
-    const shutdown = async () => {
-      console.log('Shutting down RegistryClient...');
-      await registryClient.close();
-      process.exit(0);
-    };
-    process.on('SIGINT', shutdown);
-    process.on('SIGTERM', shutdown);
-  } catch (err) {
-    console.error('Failed to initialize RegistryClient', err);
-    process.exit(1);
-  }
-})();
-
-/**
- * Helper: Load local API description
- * In a real application, this could read from a JSON file,
- * introspect OpenAPI spec, or build dynamically.
- */
-async function loadLocalApiDescription() {
-  return {
-    endpoints: [
-      { path: '/invoices', method: 'POST', description: 'Create a new invoice' },
-      { path: '/invoices/:id', method: 'GET', description: 'Retrieve invoice by ID' }
-    ]
-  };
-}