@salesforce/b2c-tooling-sdk 0.3.0 → 0.4.1

package/data/scaffolds/custom-api/files/schema.yaml.ejs

@@ -0,0 +1,188 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: <%= apiName %>
+  description: <%= apiDescription %>
+components:
+  securitySchemes:
+<% if (apiType === 'shopper') { %>
+    ShopperToken:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
+          scopes:
+            c_<%= apiName.replace(/-/g, '_') %>: Access <%= apiName %> API
+<% } else { %>
+    AmOAuth2:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
+          scopes:
+            c_<%= apiName.replace(/-/g, '_') %>: Access <%= apiName %> API
+<% } %>
+<% if (includeExampleEndpoints) { %>
+paths:
+  /hello:
+    get:
+      summary: Returns a hello message
+      operationId: getHello
+<% if (apiType === 'shopper') { %>
+      parameters:
+        - in: query
+          name: siteId
+          required: true
+          schema:
+            type: string
+            minLength: 1
+<% } %>
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+      security:
+<% if (apiType === 'shopper') { %>
+        - ShopperToken: [c_<%= apiName.replace(/-/g, '_') %>]
+<% } else { %>
+        - AmOAuth2: [c_<%= apiName.replace(/-/g, '_') %>]
+<% } %>
+  /items:
+    get:
+      summary: Get a list of items
+      operationId: getItems
+      parameters:
+<% if (apiType === 'shopper') { %>
+        - in: query
+          name: siteId
+          required: true
+          schema:
+            type: string
+            minLength: 1
+<% } %>
+        - in: query
+          name: c_limit
+          required: false
+          schema:
+            type: integer
+            default: 10
+        - in: query
+          name: c_offset
+          required: false
+          schema:
+            type: integer
+            default: 0
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  count:
+                    type: integer
+                  total:
+                    type: integer
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        name:
+                          type: string
+      security:
+<% if (apiType === 'shopper') { %>
+        - ShopperToken: [c_<%= apiName.replace(/-/g, '_') %>]
+<% } else { %>
+        - AmOAuth2: [c_<%= apiName.replace(/-/g, '_') %>]
+<% } %>
+  /items/{itemId}:
+    get:
+      summary: Get a specific item by ID
+      operationId: getItem
+      parameters:
+<% if (apiType === 'shopper') { %>
+        - in: query
+          name: siteId
+          required: true
+          schema:
+            type: string
+            minLength: 1
+<% } %>
+        - in: path
+          name: itemId
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  name:
+                    type: string
+                  description:
+                    type: string
+        '404':
+          description: Item not found
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  type:
+                    type: string
+                  message:
+                    type: string
+      security:
+<% if (apiType === 'shopper') { %>
+        - ShopperToken: [c_<%= apiName.replace(/-/g, '_') %>]
+<% } else { %>
+        - AmOAuth2: [c_<%= apiName.replace(/-/g, '_') %>]
+<% } %>
+<% } else { %>
+paths:
+  /example:
+    get:
+      summary: Example endpoint
+      operationId: getExample
+<% if (apiType === 'shopper') { %>
+      parameters:
+        - in: query
+          name: siteId
+          required: true
+          schema:
+            type: string
+            minLength: 1
+<% } %>
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+      security:
+<% if (apiType === 'shopper') { %>
+        - ShopperToken: [c_<%= apiName.replace(/-/g, '_') %>]
+<% } else { %>
+        - AmOAuth2: [c_<%= apiName.replace(/-/g, '_') %>]
+<% } %>
+<% } %>

package/data/scaffolds/custom-api/files/script.js.ejs

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Custom SCAPI implementation for <%= apiName %>
+ *
+ * Each exported function corresponds to an operationId in schema.yaml.
+ * Functions must be marked as public: exports.functionName.public = true;
+ *
+ * Use RESTResponseMgr for proper SCAPI responses.
+ */
+
+var RESTResponseMgr = require('dw/system/RESTResponseMgr');
+
+<% if (includeExampleEndpoints) { %>
+/**
+ * GET /hello
+ * Returns a hello message
+ */
+exports.getHello = function () {
+    RESTResponseMgr
+        .createSuccess({
+            message: 'Hello from <%= apiName %>!'
+        })
+        .render();
+};
+exports.getHello.public = true;
+
+/**
+ * GET /items
+ * Get a list of items with pagination
+ */
+exports.getItems = function () {
+    var limit = request.httpParameterMap.get('c_limit').intValue || 10;
+    var offset = request.httpParameterMap.get('c_offset').intValue || 0;
+
+    // TODO: Replace with actual data retrieval logic
+    var allItems = [
+        { id: 'item-1', name: 'Example Item 1' },
+        { id: 'item-2', name: 'Example Item 2' },
+        { id: 'item-3', name: 'Example Item 3' }
+    ];
+
+    var items = allItems.slice(offset, offset + limit);
+
+    RESTResponseMgr
+        .createSuccess({
+            count: items.length,
+            total: allItems.length,
+            data: items
+        })
+        .render();
+};
+exports.getItems.public = true;
+
+/**
+ * GET /items/{itemId}
+ * Get a specific item by ID
+ */
+exports.getItem = function () {
+    var itemId = request.getSCAPIPathParameters().get('itemId');
+
+    // TODO: Replace with actual data retrieval logic
+    var items = {
+        'item-1': { id: 'item-1', name: 'Example Item 1', description: 'First example item' },
+        'item-2': { id: 'item-2', name: 'Example Item 2', description: 'Second example item' },
+        'item-3': { id: 'item-3', name: 'Example Item 3', description: 'Third example item' }
+    };
+
+    var item = items[itemId];
+
+    if (item) {
+        RESTResponseMgr
+            .createSuccess(item)
+            .render();
+    } else {
+        RESTResponseMgr
+            .createError(404, 'item-not-found', 'Item Not Found', 'The requested item was not found.')
+            .render();
+    }
+};
+exports.getItem.public = true;
+<% } else { %>
+/**
+ * GET /example
+ * Example endpoint - replace with your implementation
+ */
+exports.getExample = function () {
+    RESTResponseMgr
+        .createSuccess({
+            message: 'Hello from <%= apiName %>!'
+        })
+        .render();
+};
+exports.getExample.public = true;
+<% } %>

package/data/scaffolds/custom-api/scaffold.json

@@ -0,0 +1,65 @@
+{
+  "name": "custom-api",
+  "displayName": "Custom SCAPI",
+  "description": "Create a custom SCAPI endpoint with OAS 3.0 schema",
+  "category": "cartridge",
+  "parameters": [
+    {
+      "name": "apiName",
+      "prompt": "What is the API name?",
+      "type": "string",
+      "required": true,
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "validationMessage": "API name must be kebab-case (lowercase letters, numbers, hyphens)"
+    },
+    {
+      "name": "apiType",
+      "prompt": "What type of API is this?",
+      "type": "choice",
+      "required": true,
+      "default": "shopper",
+      "choices": [
+        { "value": "shopper", "label": "Shopper API (requires siteId, customer-facing)" },
+        { "value": "admin", "label": "Admin API (no siteId, administrative)" }
+      ]
+    },
+    {
+      "name": "apiDescription",
+      "prompt": "Describe your API:",
+      "type": "string",
+      "required": false,
+      "default": "A custom B2C Commerce API"
+    },
+    {
+      "name": "cartridgeName",
+      "prompt": "Which cartridge should contain this API?",
+      "type": "string",
+      "required": true,
+      "source": "cartridges",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "validationMessage": "Cartridge name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores"
+    },
+    {
+      "name": "includeExampleEndpoints",
+      "prompt": "Include example endpoints?",
+      "type": "boolean",
+      "required": false,
+      "default": true
+    }
+  ],
+  "files": [
+    {
+      "template": "schema.yaml.ejs",
+      "destination": "{{cartridgeNamePath}}/cartridge/rest-apis/{{apiName}}/schema.yaml"
+    },
+    {
+      "template": "api.json.ejs",
+      "destination": "{{cartridgeNamePath}}/cartridge/rest-apis/{{apiName}}/api.json"
+    },
+    {
+      "template": "script.js.ejs",
+      "destination": "{{cartridgeNamePath}}/cartridge/rest-apis/{{apiName}}/script.js"
+    }
+  ],
+  "postInstructions": "Custom API '<%= apiName %>' has been created in cartridge '<%= cartridgeName %>'.\n\nFiles created:\n- rest-apis/<%= apiName %>/schema.yaml (OAS 3.0 contract)\n- rest-apis/<%= apiName %>/api.json (endpoint mapping)\n- rest-apis/<%= apiName %>/script.js (implementation)\n\nNext steps:\n1. Deploy the cartridge to your instance\n2. Activate the code version to register the API\n3. The API will be available at:\n   https://{shortCode}.api.commercecloud.salesforce.com/custom/<%= apiName %>/v1/organizations/{organizationId}/...\n<% if (apiType === 'shopper') { %>\nNote: Shopper APIs require the siteId query parameter and ShopperToken authentication.\n<% } else { %>\nNote: Admin APIs use AmOAuth2 authentication. Add cartridge to Business Manager site's cartridge path.\n<% } %>"
+}

package/data/scaffolds/hook/files/hook.js.ejs

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * <%= hookName %> Hook Implementation
+ *
+ * Hook point: <%= hookPoint %>
+ *
+ * @module scripts/hooks/<%= hookName %>
+ */
+
+var Logger = require('dw/system/Logger');
+var Status = require('dw/system/Status');
+
+var log = Logger.getLogger('<%= hookName %>', '<%= cartridgeName %>');
+
+<% if (hookType === 'ocapi') { %>
+/**
+ * OCAPI Hook - Called before/after OCAPI operations
+ *
+ * @param {dw.order.Basket|dw.order.Order|Object} object - The object being processed
+ * @param {Object} doc - The OCAPI document
+ * @returns {dw.system.Status} - Status object
+ */
+exports.<%= hookName %> = function (object, doc) {
+    log.info('<%= hookName %> hook called');
+
+    try {
+        // TODO: Implement hook logic
+        // - Modify doc to add/change response fields
+        // - Validate/modify object before processing
+
+    } catch (e) {
+        log.error('<%= hookName %> hook error: ' + e.message);
+        return new Status(
+            Status.ERROR,
+            '<%= hookName.toUpperCase() %>_ERROR',
+            e.message
+        );
+    }
+
+    return new Status(Status.OK);
+};
+<% } else if (hookType === 'scapi') { %>
+/**
+ * SCAPI Hook - Called for Shopper API extensions
+ *
+ * @param {dw.order.Basket|dw.order.Order|Object} object - The object being processed
+ * @param {Object} scriptResponse - Response object to populate
+ * @returns {dw.system.Status} - Status object
+ */
+exports.<%= hookName %> = function (object, scriptResponse) {
+    log.info('<%= hookName %> SCAPI hook called');
+
+    try {
+        // TODO: Implement hook logic
+        // - Add custom properties to scriptResponse
+        // - Validate/enrich the response
+
+    } catch (e) {
+        log.error('<%= hookName %> hook error: ' + e.message);
+        return new Status(
+            Status.ERROR,
+            '<%= hookName.toUpperCase() %>_ERROR',
+            e.message
+        );
+    }
+
+    return new Status(Status.OK);
+};
+<% } else { %>
+/**
+ * System Hook Implementation
+ *
+ * @param {dw.order.Basket|dw.order.Order|dw.customer.Customer|Object} object - The object being processed
+ * @returns {dw.system.Status} - Status object
+ */
+exports.<%= hookName %> = function (object) {
+    log.info('<%= hookName %> system hook called');
+
+    try {
+        // TODO: Implement hook logic based on extension point
+        // Common extension points:
+        // - dw.order.calculate: Basket/order calculation
+        // - dw.order.createOrder: Order creation
+        // - dw.customer.registration: Customer registration
+        // - dw.extensions.applepay: Apple Pay processing
+
+    } catch (e) {
+        log.error('<%= hookName %> hook error: ' + e.message);
+        return new Status(
+            Status.ERROR,
+            '<%= hookName.toUpperCase() %>_ERROR',
+            e.message
+        );
+    }
+
+    return new Status(Status.OK);
+};
+<% } %>

package/data/scaffolds/hook/files/hooks-entry.json.ejs

@@ -0,0 +1,6 @@
+[
+  {
+    "name": "<%= hookPoint %>",
+    "script": "./scripts/hooks/<%= hookName %>"
+  }
+]

package/data/scaffolds/hook/scaffold.json

@@ -0,0 +1,60 @@
+{
+  "name": "hook",
+  "displayName": "Hook Implementation",
+  "description": "Create a hook implementation with hooks.json registration",
+  "category": "cartridge",
+  "parameters": [
+    {
+      "name": "hookName",
+      "prompt": "What is the hook script name?",
+      "type": "string",
+      "required": true,
+      "pattern": "^[a-z][a-zA-Z0-9]*$",
+      "validationMessage": "Hook name must be camelCase (start with lowercase letter)"
+    },
+    {
+      "name": "hookType",
+      "prompt": "What type of hook is this?",
+      "type": "choice",
+      "required": true,
+      "choices": [
+        { "value": "ocapi", "label": "OCAPI Hook (shop/data API extension)" },
+        { "value": "scapi", "label": "SCAPI Hook (shopper API extension)" },
+        { "value": "system", "label": "System Hook (order, basket, etc.)" }
+      ],
+      "default": "system"
+    },
+    {
+      "name": "hookPoint",
+      "prompt": "What is the hook extension point?",
+      "type": "string",
+      "required": true,
+      "source": "hook-points",
+      "validationMessage": "Hook point is required (e.g., dw.order.calculate, dw.ocapi.shop.order.beforePOST)"
+    },
+    {
+      "name": "cartridgeName",
+      "prompt": "Which cartridge should contain this hook?",
+      "type": "string",
+      "required": true,
+      "source": "cartridges",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "validationMessage": "Cartridge name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores"
+    }
+  ],
+  "files": [
+    {
+      "template": "hook.js.ejs",
+      "destination": "{{cartridgeNamePath}}/cartridge/scripts/hooks/{{hookName}}.js"
+    }
+  ],
+  "modifications": [
+    {
+      "target": "{{cartridgeNamePath}}/cartridge/hooks.json",
+      "type": "json-merge",
+      "contentTemplate": "hooks-entry.json.ejs",
+      "jsonPath": "hooks"
+    }
+  ],
+  "postInstructions": "Hook '<%= hookName %>' has been created in '<%= cartridgeName %>'.\n\nHook point: <%= hookPoint %>\n\nNext steps:\n1. Implement the hook logic in cartridge/scripts/hooks/<%= hookName %>.js\n2. Deploy the cartridge to your instance\n3. Ensure <%= cartridgeName %> is in your cartridge path"
+}

package/data/scaffolds/job-step/files/step-chunk.js.ejs

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * <%= stepId %> Job Step (Chunk-oriented)
+ *
+ * <%= stepDescription %>
+ *
+ * Chunk-oriented steps process data in batches with automatic
+ * transaction handling and checkpoint/restart capability.
+ *
+ * @module scripts/jobsteps/<%= camelCase(stepId) %>
+ */
+
+var Status = require('dw/system/Status');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('<%= camelCase(stepId) %>', 'job');
+
+/**
+ * Read the next item to process
+ *
+ * Called repeatedly until it returns null.
+ *
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ * @returns {Object|null} - The next item to process, or null when done
+ */
+exports.read = function (stepExecution, parameters) {
+    // TODO: Implement your read logic
+    // Examples:
+    // - Read next product from search results
+    // - Read next line from file
+    // - Read next record from database query
+
+    // Return null to signal end of data
+    return null;
+};
+
+/**
+ * Process a single item
+ *
+ * Called for each item returned by read().
+ * Processing happens within a transaction.
+ *
+ * @param {Object} item - The item to process (returned by read)
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ * @returns {Object} - The processed item (passed to write)
+ */
+exports.process = function (item, stepExecution, parameters) {
+    // TODO: Implement your processing logic
+    // Examples:
+    // - Transform product data
+    // - Validate and enrich records
+    // - Calculate values
+
+    return item;
+};
+
+/**
+ * Write processed items
+ *
+ * Called with a chunk of processed items.
+ * Chunk size is configured in steptypes.json.
+ *
+ * @param {dw.util.List} items - List of processed items
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ */
+exports.write = function (items, stepExecution, parameters) {
+    // TODO: Implement your write logic
+    // Examples:
+    // - Write records to database
+    // - Export to file
+    // - Send to external service
+
+    log.info('Wrote ' + items.size() + ' items');
+};
+
+/**
+ * Called before processing begins
+ *
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ */
+exports.beforeStep = function (stepExecution, parameters) {
+    log.info('<%= stepId %> chunk step started');
+    // TODO: Initialize resources (file handles, connections, etc.)
+};
+
+/**
+ * Called after all processing is complete
+ *
+ * @param {boolean} success - Whether the step completed successfully
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ */
+exports.afterStep = function (success, stepExecution, parameters) {
+    // TODO: Cleanup resources
+    log.info('<%= stepId %> chunk step ' + (success ? 'completed' : 'failed'));
+};
+
+/**
+ * Called before each chunk is processed
+ *
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ */
+exports.beforeChunk = function (stepExecution, parameters) {
+    // Optional: Pre-chunk initialization
+};
+
+/**
+ * Called after each chunk is processed
+ *
+ * @param {boolean} success - Whether the chunk completed successfully
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ */
+exports.afterChunk = function (success, stepExecution, parameters) {
+    // Optional: Post-chunk cleanup or logging
+};
+
+/**
+ * Get the total count of items to process (optional)
+ *
+ * Used for progress tracking in Business Manager.
+ *
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ * @returns {Number} - Total number of items to process
+ */
+exports.getTotalCount = function (stepExecution, parameters) {
+    // TODO: Return total count if known, -1 if unknown
+    return -1;
+};

package/data/scaffolds/job-step/files/step-task.js.ejs

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * <%= stepId %> Job Step (Task-oriented)
+ *
+ * <%= stepDescription %>
+ *
+ * @module scripts/jobsteps/<%= camelCase(stepId) %>
+ */
+
+var Status = require('dw/system/Status');
+var Logger = require('dw/system/Logger');
+
+var log = Logger.getLogger('<%= camelCase(stepId) %>', 'job');
+
+/**
+ * Execute the job step
+ *
+ * Task-oriented steps run once per job execution.
+ * Use for simple operations that don't need chunked processing.
+ *
+ * @param {dw.job.JobStepExecution} stepExecution - The step execution context
+ * @param {Object} parameters - Step parameters from job configuration
+ * @returns {dw.system.Status} - Execution status
+ */
+exports.execute = function (stepExecution, parameters) {
+    log.info('<%= stepId %> step started');
+
+    try {
+        // Access job parameters
+        // var myParam = parameters.get('MyParameter');
+
+        // TODO: Implement your step logic here
+        // Examples:
+        // - Export data to a file
+        // - Call an external service
+        // - Update records in bulk
+        // - Generate reports
+
+        log.info('<%= stepId %> step completed successfully');
+        return new Status(Status.OK);
+
+    } catch (e) {
+        log.error('<%= stepId %> step failed: ' + e.message);
+        return new Status(Status.ERROR, 'ERROR', e.message);
+    }
+};