@onlineapps/conn-orch-api-mapper 1.0.29 → 1.0.31

package/README.md

@@ -252,11 +252,24 @@ npm run test:component   # Component tests
 - `axios` - HTTP client
 - `openapi-validator` - Schema validation
 
+## Error Propagation
+
+When a downstream service returns an HTTP error, `_callViaHttp` preserves the full response body instead of discarding it. The thrown error carries:
+
+- `statusCode` -- HTTP status code (enables `ErrorClassifier` classification)
+- `errorCode` -- machine-readable code from the response (e.g. `RESOURCE_NOT_FOUND`)
+- `type` -- error type from the response (e.g. `BUSINESS`, `VALIDATION`)
+- `details` -- array of detail strings from the response
+- `service` / `operation` -- originating service and operation
+- `responseBody` -- raw response data for debugging
+
+This enables the WorkflowOrchestrator to classify errors accurately and skip retries for permanent failures (BUSINESS/VALIDATION). See [Error Handling Standard](/docs/standards/ERROR_HANDLING.md#business-service-error-standard).
+
 ## Related Documentation
 - [Service Wrapper](/shared/connector/service-wrapper/README.md) - Integration guide
 - [Registry System](/docs/modules/registry.md) - Service discovery
 - [Cookbook Connector](/shared/connector/conn-orch-cookbook/README.md) - Operation format
-- [API Standards](/docs/STANDARDS_OVERVIEW.md#api-structure) - Endpoint conventions
+- [Error Handling Standard](/docs/standards/ERROR_HANDLING.md) - Business error classes and response format
 
 ---
-*Version: 1.0.0 | License: MIT*
+*Version: 1.0.31 | License: MIT*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-api-mapper",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "API mapping connector for OA Drive - maps cookbook operations to HTTP endpoints",
   "main": "src/index.js",
   "scripts": {

package/src/ApiMapper.js

@@ -561,7 +561,6 @@ class ApiMapper {
           method: (operation.method || 'POST').toUpperCase(),
           path: operation.endpoint || `/${operationId}`,
           // Static headers from operations.json (e.g. x-validation-request).
-          // NOTE: account-id is controlled by workflow context (_system.account_id) and must not be overridden here.
           headers: operation.headers || null,
           // Store original operations.json input schema for type-driven descriptor handling
           input: operation.input || null,
@@ -687,7 +686,7 @@ class ApiMapper {
    * @private
    * @param {Object} operation - Operation definition
    * @param {Object} input - Resolved input
-   * @param {Object} context - Workflow context (may include _system.account_id)
+   * @param {Object} context - Workflow context (must include _system.tenant_id + _system.default_workspace_id)
    * @returns {Object} Request object
    */
   _buildRequest(operation, input, context = {}) {
@@ -703,9 +702,6 @@ class ApiMapper {
     if (operation && operation.headers && typeof operation.headers === 'object') {
       Object.entries(operation.headers).forEach(([k, v]) => {
         if (!k) return;
-        // Never allow operation-level config to override tenant header
-        if (String(k).toLowerCase() === 'account-id') return;
-
         // Optional: allow ${context.path} variable resolution (no env side-effects here).
         if (typeof v === 'string' && v.startsWith('${') && v.endsWith('}')) {
           const path = v.slice(2, -1);
@@ -761,24 +757,54 @@ class ApiMapper {
       }
     }
 
-    // Multitenancy: propagate account context from workflow _system into HTTP header.
-    // FAIL-FAST: _system.account_id is REQUIRED for all workflow requests.
-    // Gateway sets this, so missing value indicates configuration error.
     const sys = context && typeof context === 'object' ? context._system : null;
-    if (!sys || !Object.prototype.hasOwnProperty.call(sys, 'account_id')) {
+    if (!sys) {
       throw new Error(
-        '[ApiMapper][AccountContext] Missing account context - Expected context._system.account_id. ' +
-        'Fix: Gateway must set _system.account_id from account-id header.'
+        '[ApiMapper][TenantContext] Missing _system context - Expected context._system with tenant_id. ' +
+        'Fix: Gateway must set _system.tenant_id.'
       );
     }
-    const accountId = Number.parseInt(String(sys.account_id), 10);
-    if (!Number.isInteger(accountId) || accountId <= 0) {
+
+    if (sys.tenant_id === undefined) {
+      throw new Error(
+        '[ApiMapper][TenantContext] Missing tenant context - Expected _system.tenant_id'
+      );
+    }
+
+    const tenantId = Number.parseInt(String(sys.tenant_id), 10);
+    if (!Number.isInteger(tenantId) || tenantId <= 0) {
+      throw new Error(`[ApiMapper][TenantContext] Invalid tenant_id - Expected positive integer, got: ${sys.tenant_id}`);
+    }
+
+    // workspace_id: per-step override → cookbook default → error
+    // See: .cursor/rules/workspace-architecture.mdc
+    const stepDef = context._pointer?.currentStep || operation;
+    const rawStepWs = stepDef?.workspace_id;
+    const rawDefaultWs = sys.default_workspace_id;
+    const rawWorkspaceId = rawStepWs !== undefined && rawStepWs !== null ? rawStepWs : rawDefaultWs;
+
+    if (rawWorkspaceId === undefined || rawWorkspaceId === null) {
       throw new Error(
-        `[ApiMapper][AccountContext] Invalid account context - Expected context._system.account_id to be a positive integer, got: ${sys.account_id}`
+        '[ApiMapper][TenantContext] Missing workspace_id - set per-step workspace_id or cookbook defaults.workspace_id'
       );
     }
-    // Do not allow step input to override tenant header
-    request.headers['account-id'] = String(accountId);
+
+    const workspaceId = Number.parseInt(String(rawWorkspaceId), 10);
+    if (!Number.isInteger(workspaceId) || workspaceId <= 0) {
+      throw new Error(`[ApiMapper][TenantContext] Invalid workspace_id - Expected positive integer, got: ${rawWorkspaceId}`);
+    }
+
+    const personId = sys.person_id !== undefined && sys.person_id !== null
+      ? Number.parseInt(String(sys.person_id), 10)
+      : undefined;
+    if (personId === undefined || !Number.isInteger(personId) || personId <= 0) {
+      throw new Error(`[ApiMapper][TenantContext] Invalid person_id - Expected positive integer, got: ${sys.person_id}`);
+    }
+
+    // See: docs/standards/tenant-context-contract.md (§3 Data Flow)
+    request.headers['x-tenant-id'] = String(tenantId);
+    request.headers['x-workspace-id'] = String(workspaceId);
+    request.headers['x-person-id'] = String(personId);
 
     return request;
   }
@@ -842,11 +868,37 @@ class ApiMapper {
       return response;
     } catch (error) {
       if (error.response) {
-        // Server responded with error
-        throw new Error(`API returned ${error.response.status}: ${error.response.statusText}`);
+        const status = error.response.status;
+        const data = error.response.data;
+
+        const businessBody = data?.error || data;
+        const remoteCode = businessBody?.code || businessBody?.errorCode || null;
+        const remoteMessage = businessBody?.message || error.response.statusText;
+        const remoteDetails = businessBody?.details || [];
+        const remoteService = businessBody?.service || null;
+        const remoteOperation = businessBody?.operation || null;
+
+        const richMessage = remoteCode
+          ? `[${remoteService || 'service'}] ${remoteCode}: ${remoteMessage}`
+          : `API returned ${status}: ${remoteMessage}`;
+
+        const richError = new Error(richMessage);
+        richError.statusCode = status;
+        richError.errorCode = remoteCode;
+        richError.type = businessBody?.type || null;
+        richError.details = remoteDetails;
+        richError.service = remoteService;
+        richError.operation = remoteOperation;
+        richError.responseBody = data;
+        richError.requestUrl = request.url;
+
+        throw richError;
       } else if (error.request) {
-        // Request made but no response
-        throw new Error(`No response from service: ${request.url}`);
+        const noResponseError = new Error(`No response from service: ${request.url}`);
+        noResponseError.statusCode = 503;
+        noResponseError.type = 'TRANSIENT';
+        noResponseError.requestUrl = request.url;
+        throw noResponseError;
       } else {
         throw error;
       }