@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterface2Conversion/MyCustomCallable.cls

@@ -0,0 +1,74 @@
+/**
+ * @description Callable implementation for calculateTotal (converted from VlocityOpenInterface2).
+ *              Accepts price and quantity from inputMap, returns total in response envelope.
+ *              Original: MyCustomRemoteClass implements omnistudio.VlocityOpenInterface2.
+ * @author      building-omnistudio-callable-apex
+ */
+public with sharing class MyCustomCallable implements System.Callable {
+
+    public Object call(String action, Map<String, Object> args) {
+        Map<String, Object> inputMap = (args != null && args.containsKey('inputMap'))
+            ? (Map<String, Object>) args.get('inputMap') : (args != null ? args : new Map<String, Object>());
+        Map<String, Object> options  = (args != null && args.containsKey('options'))
+            ? (Map<String, Object>) args.get('options')  : new Map<String, Object>();
+        if (inputMap == null) { inputMap = new Map<String, Object>(); }
+        if (options  == null) { options  = new Map<String, Object>(); }
+
+        switch on action {
+            when 'calculateTotal' {
+                return calculateTotal(inputMap, options);
+            }
+            when else {
+                throw new IndustriesCallableException('Unsupported action: ' + action);
+            }
+        }
+    }
+
+    private Map<String, Object> calculateTotal(Map<String, Object> inputMap, Map<String, Object> options) {
+        Decimal price = toDecimal(inputMap.get('price'));
+        Integer qty   = toInteger(inputMap.get('quantity'));
+
+        if (price == null || qty == null) {
+            return new Map<String, Object>{
+                'success' => false,
+                'data'    => new Map<String, Object>(),
+                'errors'  => new List<Map<String, Object>>{
+                    new Map<String, Object>{
+                        'code'    => 'INVALID_INPUT',
+                        'message' => 'price and quantity are required and must be numeric'
+                    }
+                }
+            };
+        }
+
+        Decimal total = price * qty;
+
+        return new Map<String, Object>{
+            'success' => true,
+            'data'    => new Map<String, Object>{ 'total' => total },
+            'errors'  => new List<Map<String, Object>>()
+        };
+    }
+
+    private Decimal toDecimal(Object o) {
+        if (o == null) return null;
+        if (o instanceof Decimal) return (Decimal) o;
+        if (o instanceof Integer) return Decimal.valueOf((Integer) o);
+        if (o instanceof Double)  return Decimal.valueOf((Double) o);
+        if (o instanceof String) {
+            try { return Decimal.valueOf((String) o); } catch (TypeException e) { return null; }
+        }
+        return null;
+    }
+
+    private Integer toInteger(Object o) {
+        if (o == null) return null;
+        if (o instanceof Integer) return (Integer) o;
+        if (o instanceof Long)    return ((Long) o).intValue();
+        if (o instanceof Decimal) return ((Decimal) o).intValue();
+        if (o instanceof String) {
+            try { return Integer.valueOf((String) o); } catch (TypeException e) { return null; }
+        }
+        return null;
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterface2Conversion/MyCustomCallableTest.cls

@@ -0,0 +1,146 @@
+/**
+ * @description Test class for MyCustomCallable (converted from MyCustomRemoteClass VlocityOpenInterface2).
+ *              Covers positive, negative, contract, and unsupported action scenarios.
+ * @author      building-omnistudio-callable-apex
+ */
+@IsTest
+private class MyCustomCallableTest {
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // POSITIVE TESTS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Tests calculateTotal returns total with inputMap/options format
+     */
+    @IsTest
+    static void testCalculateTotal_Success() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>{
+                'price'    => 10.50,
+                'quantity' => 3
+            },
+            'options'  => new Map<String, Object>()
+        };
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+        Test.stopTest();
+
+        Assert.isTrue((Boolean) result.get('success'), 'Should succeed');
+        Map<String, Object> data = (Map<String, Object>) result.get('data');
+        Assert.areEqual(31.50, (Decimal) data.get('total'), 'total should be 10.50 * 3');
+    }
+
+    /**
+     * @description Tests calculateTotal with flat args (backward compatibility)
+     */
+    @IsTest
+    static void testCalculateTotal_FlatArgs_Success() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'price'    => 100,
+            'quantity' => 5
+        };
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+        Test.stopTest();
+
+        Assert.isTrue((Boolean) result.get('success'), 'Should succeed');
+        Map<String, Object> data = (Map<String, Object>) result.get('data');
+        Assert.areEqual(500, (Decimal) data.get('total'), 'total should be 100 * 5');
+    }
+
+    /**
+     * @description Tests calculateTotal with string inputs (type coercion from OmniScript)
+     */
+    @IsTest
+    static void testCalculateTotal_StringInputs_Success() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>{
+                'price'    => '25.00',
+                'quantity' => '4'
+            },
+            'options'  => new Map<String, Object>()
+        };
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+
+        Assert.isTrue((Boolean) result.get('success'), 'Should succeed');
+        Map<String, Object> data = (Map<String, Object>) result.get('data');
+        Assert.areEqual(100, (Decimal) data.get('total'), 'total should be 25 * 4');
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // NEGATIVE / CONTRACT TESTS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Tests unsupported action throws IndustriesCallableException
+     */
+    @IsTest
+    static void testUnsupportedAction_Throws() {
+        try {
+            System.Callable svc = new MyCustomCallable();
+            svc.call('unknownAction', new Map<String, Object>{
+                'inputMap' => new Map<String, Object>(),
+                'options'  => new Map<String, Object>()
+            });
+            Assert.fail('Expected IndustriesCallableException');
+        } catch (IndustriesCallableException e) {
+            Assert.isTrue(e.getMessage().contains('Unsupported action'), 'Message should mention unsupported action');
+        }
+    }
+
+    /**
+     * @description Tests missing price returns error envelope
+     */
+    @IsTest
+    static void testCalculateTotal_MissingPrice_ReturnsError() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>{ 'quantity' => 2 },
+            'options'  => new Map<String, Object>()
+        };
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+
+        Assert.isFalse((Boolean) result.get('success'), 'Should fail');
+        List<Object> errors = (List<Object>) result.get('errors');
+        Assert.isNotNull(errors, 'errors should not be null');
+        Assert.areEqual(1, errors.size(), 'Should have one error');
+    }
+
+    /**
+     * @description Tests missing quantity returns error envelope
+     */
+    @IsTest
+    static void testCalculateTotal_MissingQuantity_ReturnsError() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>{ 'price' => 50 },
+            'options'  => new Map<String, Object>()
+        };
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+
+        Assert.isFalse((Boolean) result.get('success'), 'Should fail');
+        List<Object> errors = (List<Object>) result.get('errors');
+        Assert.isNotNull(errors, 'errors should not be null');
+    }
+
+    /**
+     * @description Tests null args handled gracefully
+     */
+    @IsTest
+    static void testCalculateTotal_NullArgs_ReturnsError() {
+        System.Callable svc = new MyCustomCallable();
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', null);
+
+        Assert.isFalse((Boolean) result.get('success'), 'Should fail with null inputMap');
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterface2Conversion/MyCustomRemoteClass.cls

@@ -0,0 +1,16 @@
+global with sharing class MyCustomRemoteClass implements omnistudio.VlocityOpenInterface2 {
+    
+    global Boolean invokeMethod(String methodName, Map<String,Object> inputMap, Map<String,Object> outputMap, Map<String,Object> options) {
+        if (methodName.equals('calculateTotal')) {
+            calculateTotal(inputMap, outputMap);
+            return true;
+        }
+        return false;
+    }
+
+    private void calculateTotal(Map<String,Object> inputMap, Map<String,Object> outputMap) {
+        Decimal price = (Decimal)inputMap.get('price');
+        Decimal qty = (Decimal)inputMap.get('quantity');
+        outputMap.put('total', price * qty);
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterface2Conversion/TRANSCRIPT.md

@@ -0,0 +1,120 @@
+# Reasoning Transcript: VlocityOpenInterface2 → Callable Conversion (MyCustomRemoteClass)
+
+This document records the reasoning process and skills used to convert `MyCustomRemoteClass.cls` (VlocityOpenInterface2) to `MyCustomCallable.cls` and create `MyCustomCallableTest.cls`.
+
+---
+
+## Task Summary
+
+Convert a VlocityOpenInterface2 implementation (`MyCustomRemoteClass`) to `System.Callable`, add a test class, and document reasoning and skills used.
+
+---
+
+## Source Analysis
+
+**Original class:** `MyCustomRemoteClass.cls`
+
+- **Implements:** `omnistudio.VlocityOpenInterface2`
+- **Action:** `calculateTotal`
+- **Input contract:** `inputMap` with keys `price` (Decimal), `quantity` (Decimal)
+- **Output contract:** `outputMap.put('total', price * qty)`
+- **Behavior:** Single action; returns `true` on success, `false` for unsupported methods
+
+---
+
+## Skills Applied
+
+### 1. **building-omnistudio-callable-apex** (Primary)
+
+**Path:** `skills/building-omnistudio-callable-apex/SKILL.md`  
+**Trigger:** Callable implementations, VlocityOpenInterface, migration to System.Callable
+
+**Application:**
+
+- **Migration guidance (SKILL § Migration: VlocityOpenInterface to System.Callable):**
+  - Preserved action name: `calculateTotal` → `action` in `call()`
+  - Pass `inputMap` and `options` as keys in `args`: `{ 'inputMap' => inputMap, 'options' => options }`
+  - Return response envelope instead of mutating `outputMap`
+  - Keep `call()` thin; delegate to `calculateTotal(inputMap, options)`
+  - Backward compatibility: if `args` lacks `inputMap`, treat `args` as `inputMap`
+
+- **Callable skeleton (SKILL § Phase 3 – Callable skeleton):**
+  - Extracted `inputMap` and `options` from `args` with null guards
+  - `switch on action` with `when else` throwing `IndustriesCallableException`
+
+- **Response envelope:**
+  ```
+  { success, data: { total }, errors }
+  ```
+
+- **Input validation:** Added `toDecimal()` and `toInteger()` type coercion (OmniScript often passes strings); return error envelope when `price` or `quantity` is null or invalid.
+
+- **Contract & Dispatch:** Explicit action list; typed exception for unsupported actions.
+
+---
+
+### 2. **generating-apex** (Reference)
+
+**Path:** `~/.claude/skills/generating-apex/SKILL.md`  
+**Trigger:** Apex classes, code quality
+
+**Application:**
+
+- ApexDoc on class and key methods
+- `with sharing` on the callable class
+- Null-safe input handling; no direct casts without validation
+- Naming: `MyCustomCallable` (callable pattern; preserves "MyCustom" from source)
+
+---
+
+### 3. **running-apex-tests** (Reference)
+
+**Path:** `~/.claude/skills/running-apex-tests/SKILL.md`  
+**Trigger:** Apex tests
+
+**Application:**
+
+- **Positive:** Success with `inputMap`/`options`, flat args, and string inputs (type coercion)
+- **Contract:** Missing `price`, missing `quantity`, null args → error envelope
+- **Negative:** Unsupported action throws `IndustriesCallableException`
+- GIVEN/WHEN/THEN implied via clear assertions and method names
+
+---
+
+## Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **Preserve lowercase keys** (`price`, `quantity`, `total`) | Original `MyCustomRemoteClass` used lowercase; maintains contract for existing Integration Procedures / OmniScripts |
+| **Response envelope** | Aligns with Industries pattern; callers get consistent `success`, `data`, `errors` shape |
+| **Error envelope for validation** | Return structured errors instead of throwing; callers can handle without try/catch |
+| **Exception for unsupported action** | Skill pattern; `IndustriesCallableException` makes misuse explicit |
+| **Type coercion helpers** | OmniScript/Integration Procedures often pass strings; `toDecimal`/`toInteger` allow `'25.00'`, `'4'` etc. |
+| **Flat args fallback** | When `args` lacks `inputMap`, treat `args` as `inputMap` for backward compatibility |
+
+---
+
+## Artifacts Produced
+
+1. **IndustriesCallableException.cls** – Custom exception for unsupported actions  
+2. **MyCustomCallable.cls** – Callable implementation (converted from MyCustomRemoteClass)  
+3. **MyCustomCallableTest.cls** – Test class (7 methods)  
+4. **TRANSCRIPT.md** – This reasoning transcript  
+
+---
+
+## Contract Mapping (Before → After)
+
+| VlocityOpenInterface2 | System.Callable |
+|----------------------|-----------------|
+| `methodName` = `'calculateTotal'` | `action` = `'calculateTotal'` |
+| `inputMap.get('price')`, `inputMap.get('quantity')` | Same keys in `args.inputMap` or flat `args` |
+| `outputMap.put('total', ...)` | `return { success => true, data => { total => ... } }` |
+| `return false` for unsupported | `throw IndustriesCallableException` |
+| `options` (unused in original) | Passed through for future use |
+
+---
+
+## Deployment Notes
+
+Copy the `.cls` files into your Salesforce project under `force-app/main/default/classes/` and add the corresponding `-meta.xml` files. No SOQL/DML; no special API version requirements.

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterfaceConversion/IndustriesCallableException.cls

@@ -0,0 +1,7 @@
+/**
+ * @description Custom exception for Industries callable implementations.
+ *              Thrown when an unsupported or invalid action is requested.
+ * @author      building-omnistudio-callable-apex
+ */
+public class IndustriesCallableException extends Exception {
+}

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterfaceConversion/MyCustomCallable.cls

@@ -0,0 +1,73 @@
+/**
+ * @description Callable implementation for calculateTotal (converted from VlocityOpenInterface).
+ *              Accepts Price and Quantity, returns TotalAmount in response envelope.
+ * @author      building-omnistudio-callable-apex
+ */
+public with sharing class MyCustomCallable implements System.Callable {
+
+    public Object call(String action, Map<String, Object> args) {
+        Map<String, Object> inputMap = (args != null && args.containsKey('inputMap'))
+            ? (Map<String, Object>) args.get('inputMap') : (args != null ? args : new Map<String, Object>());
+        Map<String, Object> options  = (args != null && args.containsKey('options'))
+            ? (Map<String, Object>) args.get('options')  : new Map<String, Object>();
+        if (inputMap == null) { inputMap = new Map<String, Object>(); }
+        if (options  == null) { options  = new Map<String, Object>(); }
+
+        switch on action {
+            when 'calculateTotal' {
+                return calculateTotal(inputMap, options);
+            }
+            when else {
+                throw new IndustriesCallableException('Unsupported action: ' + action);
+            }
+        }
+    }
+
+    private Map<String, Object> calculateTotal(Map<String, Object> inputMap, Map<String, Object> options) {
+        Decimal price = toDecimal(inputMap.get('Price'));
+        Integer qty   = toInteger(inputMap.get('Quantity'));
+
+        if (price == null || qty == null) {
+            return new Map<String, Object>{
+                'success' => false,
+                'data'    => new Map<String, Object>(),
+                'errors'  => new List<Map<String, Object>>{
+                    new Map<String, Object>{
+                        'code'    => 'INVALID_INPUT',
+                        'message' => 'Price and Quantity are required and must be numeric'
+                    }
+                }
+            };
+        }
+
+        Decimal total = price * qty;
+
+        return new Map<String, Object>{
+            'success' => true,
+            'data'    => new Map<String, Object>{ 'TotalAmount' => total },
+            'errors'  => new List<Map<String, Object>>()
+        };
+    }
+
+    private Decimal toDecimal(Object o) {
+        if (o == null) return null;
+        if (o instanceof Decimal) return (Decimal) o;
+        if (o instanceof Integer) return Decimal.valueOf((Integer) o);
+        if (o instanceof Double)  return Decimal.valueOf((Double) o);
+        if (o instanceof String) {
+            try { return Decimal.valueOf((String) o); } catch (TypeException e) { return null; }
+        }
+        return null;
+    }
+
+    private Integer toInteger(Object o) {
+        if (o == null) return null;
+        if (o instanceof Integer) return (Integer) o;
+        if (o instanceof Long)    return ((Long) o).intValue();
+        if (o instanceof Decimal) return ((Decimal) o).intValue();
+        if (o instanceof String) {
+            try { return Integer.valueOf((String) o); } catch (TypeException e) { return null; }
+        }
+        return null;
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterfaceConversion/MyCustomCallableTest.cls

@@ -0,0 +1,128 @@
+/**
+ * @description Test class for MyCustomCallable.
+ *              Covers positive, negative, contract, and unsupported action scenarios.
+ * @author      building-omnistudio-callable-apex
+ */
+@IsTest
+private class MyCustomCallableTest {
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // POSITIVE TESTS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Tests calculateTotal returns TotalAmount with inputMap/options format
+     */
+    @IsTest
+    static void testCalculateTotal_Success() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>{
+                'Price'    => 10.50,
+                'Quantity' => 3
+            },
+            'options'  => new Map<String, Object>()
+        };
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+        Test.stopTest();
+
+        Assert.isTrue((Boolean) result.get('success'), 'Should succeed');
+        Map<String, Object> data = (Map<String, Object>) result.get('data');
+        Assert.areEqual(31.50, (Decimal) data.get('TotalAmount'), 'TotalAmount should be 10.50 * 3');
+    }
+
+    /**
+     * @description Tests calculateTotal with flat args (backward compatibility)
+     */
+    @IsTest
+    static void testCalculateTotal_FlatArgs_Success() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'Price'    => 100,
+            'Quantity' => 5
+        };
+
+        Test.startTest();
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+        Test.stopTest();
+
+        Assert.isTrue((Boolean) result.get('success'), 'Should succeed');
+        Map<String, Object> data = (Map<String, Object>) result.get('data');
+        Assert.areEqual(500, (Decimal) data.get('TotalAmount'), 'TotalAmount should be 100 * 5');
+    }
+
+    /**
+     * @description Tests calculateTotal with string inputs (type coercion from OmniScript)
+     */
+    @IsTest
+    static void testCalculateTotal_StringInputs_Success() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>{
+                'Price'    => '25.00',
+                'Quantity' => '4'
+            },
+            'options'  => new Map<String, Object>()
+        };
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+
+        Assert.isTrue((Boolean) result.get('success'), 'Should succeed');
+        Map<String, Object> data = (Map<String, Object>) result.get('data');
+        Assert.areEqual(100, (Decimal) data.get('TotalAmount'), 'TotalAmount should be 25 * 4');
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // NEGATIVE / CONTRACT TESTS
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    /**
+     * @description Tests unsupported action throws IndustriesCallableException
+     */
+    @IsTest
+    static void testUnsupportedAction_Throws() {
+        try {
+            System.Callable svc = new MyCustomCallable();
+            svc.call('unknownAction', new Map<String, Object>{
+                'inputMap' => new Map<String, Object>(),
+                'options'  => new Map<String, Object>()
+            });
+            Assert.fail('Expected IndustriesCallableException');
+        } catch (IndustriesCallableException e) {
+            Assert.isTrue(e.getMessage().contains('Unsupported action'), 'Message should mention unsupported action');
+        }
+    }
+
+    /**
+     * @description Tests missing Price returns error envelope
+     */
+    @IsTest
+    static void testCalculateTotal_MissingPrice_ReturnsError() {
+        System.Callable svc = new MyCustomCallable();
+        Map<String, Object> args = new Map<String, Object>{
+            'inputMap' => new Map<String, Object>{ 'Quantity' => 2 },
+            'options'  => new Map<String, Object>()
+        };
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', args);
+
+        Assert.isFalse((Boolean) result.get('success'), 'Should fail');
+        List<Object> errors = (List<Object>) result.get('errors');
+        Assert.isNotNull(errors, 'errors should not be null');
+        Assert.areEqual(1, errors.size(), 'Should have one error');
+    }
+
+    /**
+     * @description Tests null args handled gracefully
+     */
+    @IsTest
+    static void testCalculateTotal_NullArgs_ReturnsError() {
+        System.Callable svc = new MyCustomCallable();
+
+        Map<String, Object> result = (Map<String, Object>) svc.call('calculateTotal', null);
+
+        Assert.isFalse((Boolean) result.get('success'), 'Should fail with null inputMap');
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterfaceConversion/MyCustomVlocityOpenInterface2.cls

@@ -0,0 +1,23 @@
+global class MyCustomClass implements vlocity_cmt.VlocityOpenInterface {
+    
+    global Boolean invokeMethod(String methodName, Map<String, Object> inputs, 
+                                Map<String, Object> output, Map<String, Object> options) {
+        
+        if (methodName == 'calculateTotal') {
+            calculateTotal(inputs, output);
+        }
+        return true;
+    }
+
+    private void calculateTotal(Map<String, Object> inputs, Map<String, Object> output) {
+        // Retrieve inputs from OmniScript/IP
+        Decimal price = (Decimal)inputs.get('Price');
+        Integer qty = (Integer)inputs.get('Quantity');
+        
+        // Perform calculation
+        Decimal total = price * qty;
+        
+        // Return result to JSON
+        output.put('TotalAmount', total);
+    }
+}

package/skills/building-omnistudio-callable-apex/examples/Test_VlocityOpenInterfaceConversion/TRANSCRIPT.md

@@ -0,0 +1,75 @@
+# TRANSCRIPT: VlocityOpenInterface → System.Callable Conversion
+
+## Task
+
+Convert `MyCustomVlocityOpenInterface2.cls` (VlocityOpenInterface) to System.Callable and create a test class. Keep a transcript of reasoning and skills used.
+
+---
+
+## Skills Used
+
+| Skill | Purpose |
+|-------|---------|
+| **building-omnistudio-callable-apex** | Migration pattern, response envelope, action dispatch, inputMap/options contract, test patterns |
+| **generating-apex** (implicit) | ApexDoc, type coercion, null safety, exception handling |
+
+---
+
+## Reasoning
+
+### 1. Source Analysis
+
+**Original class**: `MyCustomClass` implements `vlocity_cmt.VlocityOpenInterface`
+
+- **Action**: `calculateTotal`
+- **Inputs**: `Price` (Decimal), `Quantity` (Integer) from `inputs` map
+- **Output**: Mutates `output` map with `TotalAmount`
+- **Observation**: Original returns `true` for all method names (no unsupported-action handling)
+
+### 2. Design Decisions
+
+| Decision | Rationale |
+|----------|------------|
+| **Open Interface–compatible args** | Use `inputMap` and `options` keys per skill Phase 3 so OmniScript/IP callers can pass the same structure |
+| **Flat args fallback** | Skill allows flat args when `inputMap` is absent; supports both calling styles |
+| **Response envelope** | Return `{ success, data, errors }` instead of mutating `outputMap` per migration guidance |
+| **Input validation** | Skill requires null-safe type coercion; OmniScript can send numbers as String |
+| **Unsupported action** | Skill: use `switch on action` and throw `IndustriesCallableException` |
+| **`with sharing`** | Skill guardrail: enforce sharing on callable classes |
+
+### 3. Implementation Pattern
+
+- **Entry point**: Extract `inputMap` and `options` from `args` (or treat flat `args` as `inputMap`)
+- **Action dispatch**: `switch on action` with `when 'calculateTotal'` and `when else` throwing
+- **Business logic**: `calculateTotal(inputMap, options)` returns envelope
+- **Type coercion**: `toDecimal()` and `toInteger()` handle Decimal, Integer, Long, String (OmniScript casts)
+- **Error envelope**: Missing/invalid inputs → `success: false` with `INVALID_INPUT` error code
+
+### 4. Test Coverage (Phase 4)
+
+| Test | Category | Purpose |
+|------|----------|---------|
+| `testCalculateTotal_Success` | Positive | InputMap/options format, validates TotalAmount |
+| `testCalculateTotal_FlatArgs_Success` | Positive | Flat args backward compatibility |
+| `testCalculateTotal_StringInputs_Success` | Contract | String coercion from OmniScript |
+| `testUnsupportedAction_Throws` | Negative | Unsupported action throws `IndustriesCallableException` |
+| `testCalculateTotal_MissingPrice_ReturnsError` | Contract | Missing required key returns error envelope |
+| `testCalculateTotal_NullArgs_ReturnsError` | Contract | Null args handled without NPE |
+
+### 5. Files Produced
+
+| File | Role |
+|------|------|
+| `MyCustomCallable.cls` | Converted System.Callable |
+| `MyCustomCallableTest.cls` | Test class |
+| `IndustriesCallableException.cls` | Custom exception (skill pattern) |
+| `TRANSCRIPT.md` | This transcript |
+
+---
+
+## Skill References
+
+- **Phase 2 (Design)**: Contract mapping (`methodName`→`action`, `inputMap`/`options`→`args`)
+- **Phase 3 (Implementation)**: Callable skeleton (inputMap/options), implementation rules (validate early, null-safe)
+- **Phase 4 (Testing)**: Positive, negative, contract tests
+- **Migration**: Preserve action names, return envelope instead of mutating output

package/skills/building-omnistudio-datamapper/CREDITS.md

@@ -0,0 +1,5 @@
+# Credits & Acknowledgments
+
+This skill reflects the collective knowledge and conventions of the Salesforce OmniStudio ecosystem.
+
+---