@salesforce/b2c-tooling-sdk 0.3.0 → 0.4.0

package/README.md

@@ -125,23 +125,190 @@ const result = await waitForJob(instance, 'my-job-id', execution.id);
 await siteArchiveImport(instance, './site-data.zip');
 ```
 
+### Account Manager User Management
+
+```typescript
+import {
+  getUserByLogin,
+  listUsers,
+  createUser,
+  updateUser,
+  deleteUser,
+  resetUser,
+  grantRole,
+  revokeRole,
+} from '@salesforce/b2c-tooling-sdk/operations/users';
+import {createAccountManagerUsersClient} from '@salesforce/b2c-tooling-sdk/clients';
+import {OAuthStrategy} from '@salesforce/b2c-tooling-sdk/auth';
+
+const auth = new OAuthStrategy({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+
+const client = createAccountManagerUsersClient({}, auth);
+
+// List users with pagination
+const users = await listUsers(client, {size: 25, page: 0});
+
+// Get user by email
+const user = await getUserByLogin(client, 'user@example.com');
+
+// Create a new user
+const newUser = await createUser(client, {
+  user: {
+    mail: 'newuser@example.com',
+    firstName: 'John',
+    lastName: 'Doe',
+    organizations: ['org-id'],
+    primaryOrganization: 'org-id',
+  },
+});
+
+// Update a user
+await updateUser(client, {
+  userId: user.id!,
+  changes: {firstName: 'Jane'},
+});
+
+// Grant a role to a user
+await grantRole(client, {
+  userId: user.id!,
+  role: 'bm-admin',
+  scope: 'tenant1,tenant2', // Optional tenant filter
+});
+
+// Reset user to INITIAL state
+await resetUser(client, user.id!);
+```
+
+### Account Manager Role Management
+
+```typescript
+import {getRole, listRoles} from '@salesforce/b2c-tooling-sdk/operations/roles';
+import {createAccountManagerRolesClient} from '@salesforce/b2c-tooling-sdk/clients';
+import {OAuthStrategy} from '@salesforce/b2c-tooling-sdk/auth';
+
+const auth = new OAuthStrategy({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+
+const client = createAccountManagerRolesClient({}, auth);
+
+// Get role details by ID
+const role = await getRole(client, 'bm-admin');
+
+// List all roles with pagination
+const roles = await listRoles(client, {size: 25, page: 0});
+
+// List roles filtered by target type
+const userRoles = await listRoles(client, {
+  size: 25,
+  page: 0,
+  roleTargetType: 'User',
+});
+```
+
+### Account Manager Organization Management
+
+```typescript
+import {getOrg, getOrgByName, listOrgs, getOrgAuditLogs} from '@salesforce/b2c-tooling-sdk/operations/orgs';
+import {createAccountManagerOrgsClient} from '@salesforce/b2c-tooling-sdk/clients';
+import {OAuthStrategy} from '@salesforce/b2c-tooling-sdk/auth';
+
+const auth = new OAuthStrategy({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+
+const client = createAccountManagerOrgsClient({}, auth);
+
+// Get organization by ID
+const org = await getOrg(client, 'org-123');
+
+// Get organization by name
+const orgByName = await getOrgByName(client, 'My Organization');
+
+// List organizations with pagination
+const orgs = await listOrgs(client, {size: 25, page: 0});
+
+// List all organizations (uses max page size of 5000)
+const allOrgs = await listOrgs(client, {all: true});
+
+// Get audit logs for an organization
+const auditLogs = await getOrgAuditLogs(client, 'org-123');
+```
+
+### Account Manager API Client Management
+
+Manage Account Manager API clients (OAuth client credentials used for API access) via the unified Account Manager client:
+
+```typescript
+import {
+  createAccountManagerClient,
+  type APIClientCreate,
+  type APIClientUpdate,
+} from '@salesforce/b2c-tooling-sdk/clients';
+import {OAuthStrategy} from '@salesforce/b2c-tooling-sdk/auth';
+
+const auth = new OAuthStrategy({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+
+const client = createAccountManagerClient({}, auth);
+
+// List API clients with pagination
+const apiClients = await client.listApiClients({size: 25, page: 0});
+
+// Get a single API client by ID (optional expand: organizations, roles)
+const apiClient = await client.getApiClient('api-client-id', ['organizations', 'roles']);
+
+// Create a new API client
+const newClient = await client.createApiClient({
+  name: 'My API Client',
+  password: 'initial-password',
+  organizations: ['org-id'],
+  roles: ['ECOM_ADMIN'],
+  active: true,
+});
+
+// Update an API client (e.g. disable, change name, roles, or organizations)
+await client.updateApiClient('api-client-id', {
+  name: 'Updated Name',
+  active: false,
+});
+
+// Change API client password (requires old password)
+await client.changeApiClientPassword('api-client-id', 'old-password', 'new-password');
+
+// Delete an API client (must be disabled for at least 7 days first)
+await client.deleteApiClient('api-client-id');
+```
+
+For direct access to the API Clients API only, use `createAccountManagerApiClientsClient` from `@salesforce/b2c-tooling-sdk/clients`.
+
 ## Module Exports
 
 The SDK provides subpath exports for tree-shaking and organization:
 
-| Export                                         | Description                                           |
-| ---------------------------------------------- | ----------------------------------------------------- |
-| `@salesforce/b2c-tooling-sdk`                  | Main entry point with all exports                     |
-| `@salesforce/b2c-tooling-sdk/config`           | Configuration resolution (resolveConfig)              |
-| `@salesforce/b2c-tooling-sdk/auth`             | Authentication strategies (OAuth, Basic, API Key)     |
-| `@salesforce/b2c-tooling-sdk/instance`         | B2CInstance class                                     |
-| `@salesforce/b2c-tooling-sdk/clients`          | Low-level API clients (WebDAV, OCAPI, SLAS, ODS, MRT) |
-| `@salesforce/b2c-tooling-sdk/operations/code`  | Code deployment operations                            |
-| `@salesforce/b2c-tooling-sdk/operations/jobs`  | Job execution and site import/export                  |
-| `@salesforce/b2c-tooling-sdk/operations/sites` | Site management                                       |
-| `@salesforce/b2c-tooling-sdk/discovery`        | Workspace type detection (PWA Kit, SFRA, etc.)        |
-| `@salesforce/b2c-tooling-sdk/cli`              | CLI utilities (BaseCommand, table rendering)          |
-| `@salesforce/b2c-tooling-sdk/logging`          | Structured logging utilities                          |
+| Export                                         | Description                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------ |
+| `@salesforce/b2c-tooling-sdk`                  | Main entry point with all exports                                              |
+| `@salesforce/b2c-tooling-sdk/config`           | Configuration resolution (resolveConfig)                                       |
+| `@salesforce/b2c-tooling-sdk/auth`             | Authentication strategies (OAuth, Basic, API Key)                              |
+| `@salesforce/b2c-tooling-sdk/instance`         | B2CInstance class                                                              |
+| `@salesforce/b2c-tooling-sdk/clients`          | Low-level API clients (WebDAV, OCAPI, SLAS, ODS, MRT, Account Manager clients) |
+| `@salesforce/b2c-tooling-sdk/operations/code`  | Code deployment operations                                                     |
+| `@salesforce/b2c-tooling-sdk/operations/jobs`  | Job execution and site import/export                                           |
+| `@salesforce/b2c-tooling-sdk/operations/sites` | Site management                                                                |
+| `@salesforce/b2c-tooling-sdk/operations/users` | Account Manager user management                                                |
+| `@salesforce/b2c-tooling-sdk/operations/roles` | Account Manager role management                                                |
+| `@salesforce/b2c-tooling-sdk/operations/orgs`  | Account Manager organization management                                        |
+| `@salesforce/b2c-tooling-sdk/discovery`        | Workspace type detection (PWA Kit, SFRA, etc.)                                 |
+| `@salesforce/b2c-tooling-sdk/cli`              | CLI utilities (BaseCommand, table rendering)                                   |
+| `@salesforce/b2c-tooling-sdk/logging`          | Structured logging utilities                                                   |
 
 ## Logging
 

package/data/scaffolds/cartridge/files/.project.ejs

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+    <name><%= cartridgeName %></name>
+    <comment></comment>
+    <projects>
+    </projects>
+    <buildSpec>
+        <buildCommand>
+            <name>com.demandware.studio.core.beehiveElementBuilder</name>
+            <arguments>
+            </arguments>
+        </buildCommand>
+    </buildSpec>
+    <natures>
+        <nature>com.demandware.studio.core.beehiveNature</nature>
+    </natures>
+</projectDescription>

package/data/scaffolds/cartridge/files/cartridge/cartridge.properties.ejs

@@ -0,0 +1,4 @@
+# <%= cartridgeName %> cartridge properties
+# Generated on <%= date %>
+
+demandware.cartridges.<%= cartridgeName %>.multipleLanguageStorefront=true

package/data/scaffolds/cartridge/files/cartridge/controllers/Example.js.ejs

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * Example controller for <%= cartridgeName %>
+ */
+
+var server = require('server');
+
+/**
+ * Example-Show: Renders an example page
+ */
+server.get('Show', function (req, res, next) {
+    res.render('example/show', {
+        message: 'Hello from <%= cartridgeName %>!'
+    });
+    next();
+});
+
+module.exports = server.exports();

package/data/scaffolds/cartridge/files/cartridge/models/example.js.ejs

@@ -0,0 +1,14 @@
+'use strict';
+
+/**
+ * Example model for <%= cartridgeName %>
+ * @param {Object} data - The input data
+ * @constructor
+ */
+function ExampleModel(data) {
+    this.id = data.id || null;
+    this.name = data.name || '';
+    this.description = data.description || '';
+}
+
+module.exports = ExampleModel;

package/data/scaffolds/cartridge/files/cartridge/scripts/helpers/exampleHelpers.js.ejs

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * Example helper functions for <%= cartridgeName %>
+ */
+
+/**
+ * Formats a string for display
+ * @param {string} input - The input string
+ * @returns {string} The formatted string
+ */
+function formatString(input) {
+    return input ? input.trim() : '';
+}
+
+module.exports = {
+    formatString: formatString
+};

package/data/scaffolds/cartridge/files/cartridge/static/default/css/example.css

@@ -0,0 +1,6 @@
+/* Example styles */
+.example-container {
+    padding: 20px;
+    margin: 10px auto;
+    max-width: 1200px;
+}

package/data/scaffolds/cartridge/files/cartridge/templates/default/example/show.isml.ejs

@@ -0,0 +1,11 @@
+<isdecorate template="common/layout/page">
+    <isscript>
+        var assets = require('*/cartridge/scripts/assets');
+        assets.addCss('/css/example.css');
+    </isscript>
+
+    <div class="container">
+        <h1>${pdict.message}</h1>
+        <p>This is an example page from the <%= cartridgeName %> cartridge.</p>
+    </div>
+</isdecorate>

package/data/scaffolds/cartridge/scaffold.json

@@ -0,0 +1,88 @@
+{
+  "name": "cartridge",
+  "displayName": "Cartridge",
+  "description": "Create a new B2C Commerce cartridge with standard structure",
+  "category": "cartridge",
+  "defaultOutputDir": "cartridges",
+  "parameters": [
+    {
+      "name": "cartridgeName",
+      "prompt": "What is the cartridge name?",
+      "type": "string",
+      "required": true,
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "validationMessage": "Cartridge name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores"
+    },
+    {
+      "name": "includeControllers",
+      "prompt": "Include controllers directory?",
+      "type": "boolean",
+      "required": false,
+      "default": true
+    },
+    {
+      "name": "includeModels",
+      "prompt": "Include models directory?",
+      "type": "boolean",
+      "required": false,
+      "default": true
+    },
+    {
+      "name": "includeScripts",
+      "prompt": "Include scripts directory?",
+      "type": "boolean",
+      "required": false,
+      "default": true
+    },
+    {
+      "name": "includeTemplates",
+      "prompt": "Include templates directory?",
+      "type": "boolean",
+      "required": false,
+      "default": true
+    },
+    {
+      "name": "includeStatic",
+      "prompt": "Include static assets directory?",
+      "type": "boolean",
+      "required": false,
+      "default": false
+    }
+  ],
+  "files": [
+    {
+      "template": ".project.ejs",
+      "destination": "{{cartridgeName}}/.project"
+    },
+    {
+      "template": "cartridge/cartridge.properties.ejs",
+      "destination": "{{cartridgeName}}/cartridge/{{cartridgeName}}.properties"
+    },
+    {
+      "template": "cartridge/controllers/Example.js.ejs",
+      "destination": "{{cartridgeName}}/cartridge/controllers/Example.js",
+      "condition": "includeControllers"
+    },
+    {
+      "template": "cartridge/models/example.js.ejs",
+      "destination": "{{cartridgeName}}/cartridge/models/example.js",
+      "condition": "includeModels"
+    },
+    {
+      "template": "cartridge/scripts/helpers/exampleHelpers.js.ejs",
+      "destination": "{{cartridgeName}}/cartridge/scripts/helpers/exampleHelpers.js",
+      "condition": "includeScripts"
+    },
+    {
+      "template": "cartridge/templates/default/example/show.isml.ejs",
+      "destination": "{{cartridgeName}}/cartridge/templates/default/example/show.isml",
+      "condition": "includeTemplates"
+    },
+    {
+      "template": "cartridge/static/default/css/example.css",
+      "destination": "{{cartridgeName}}/cartridge/static/default/css/example.css",
+      "condition": "includeStatic"
+    }
+  ],
+  "postInstructions": "Cartridge '<%= cartridgeName %>' has been created.\n\nNext steps:\n1. Add the cartridge to your cartridge path in Business Manager\n2. Deploy the cartridge to your instance"
+}

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

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * <%= controllerName %> Controller
+ *
+ * @module controllers/<%= controllerName %>
+ */
+
+var server = require('server');
+<% if (useMiddleware) { %>
+var cache = require('*/cartridge/scripts/middleware/cache');
+var consentTracking = require('*/cartridge/scripts/middleware/consentTracking');
+var pageMetaData = require('*/cartridge/scripts/middleware/pageMetaData');
+<% } %>
+
+<% if (routes.includes('Show')) { %>
+/**
+ * <%= controllerName %>-Show : Renders the <%= controllerName.toLowerCase() %> page
+ * @name <%= controllerName %>-Show
+ * @function
+ * @memberof <%= controllerName %>
+<% if (useMiddleware) { %> * @param {middleware} - server.middleware.https
+ * @param {middleware} - consentTracking.consent
+ * @param {middleware} - cache.applyDefaultCache<% } %>
+ * @param {category} - sensitive
+ * @param {renders} - isml
+ * @param {serverfunction} - get
+ */
+server.get(
+    'Show',
+<% if (useMiddleware) { %>    server.middleware.https,
+    consentTracking.consent,
+    cache.applyDefaultCache,
+<% } %>    function (req, res, next) {
+        var viewData = {
+            title: '<%= controllerName %>',
+            message: 'Hello from <%= controllerName %>!'
+        };
+
+        res.render('<%= kebabCase(controllerName) %>/show', viewData);
+        next();
+    }
+);
+<% if (useMiddleware) { %>
+server.append('Show', pageMetaData.computedPageMetaData);
+<% } %>
+<% } %>
+<% if (routes.includes('Submit')) { %>
+/**
+ * <%= controllerName %>-Submit : Handles form submission for <%= controllerName.toLowerCase() %>
+ * @name <%= controllerName %>-Submit
+ * @function
+ * @memberof <%= controllerName %>
+<% if (useMiddleware) { %> * @param {middleware} - server.middleware.https<% } %>
+ * @param {httpparameter} - csrf_token - CSRF token
+ * @param {category} - sensitive
+ * @param {returns} - json
+ * @param {serverfunction} - post
+ */
+server.post(
+    'Submit',
+<% if (useMiddleware) { %>    server.middleware.https,
+<% } %>    function (req, res, next) {
+        var form = req.form;
+
+        // TODO: Process form data
+        var result = {
+            success: true,
+            message: 'Form submitted successfully'
+        };
+
+        res.json(result);
+        next();
+    }
+);
+<% } %>
+<% if (routes.includes('JSON')) { %>
+/**
+ * <%= controllerName %>-JSON : Returns JSON data for <%= controllerName.toLowerCase() %>
+ * @name <%= controllerName %>-JSON
+ * @function
+ * @memberof <%= controllerName %>
+<% if (useMiddleware) { %> * @param {middleware} - cache.applyDefaultCache<% } %>
+ * @param {category} - non-sensitive
+ * @param {returns} - json
+ * @param {serverfunction} - get
+ */
+server.get(
+    'JSON',
+<% if (useMiddleware) { %>    cache.applyDefaultCache,
+<% } %>    function (req, res, next) {
+        var data = {
+            success: true,
+            data: {
+                // TODO: Add your data here
+            }
+        };
+
+        res.json(data);
+        next();
+    }
+);
+<% } %>
+<% if (routes.includes('SubmitJSON')) { %>
+/**
+ * <%= controllerName %>-SubmitJSON : Handles AJAX form submission for <%= controllerName.toLowerCase() %>
+ * @name <%= controllerName %>-SubmitJSON
+ * @function
+ * @memberof <%= controllerName %>
+<% if (useMiddleware) { %> * @param {middleware} - server.middleware.https<% } %>
+ * @param {httpparameter} - csrf_token - CSRF token
+ * @param {category} - sensitive
+ * @param {returns} - json
+ * @param {serverfunction} - post
+ */
+server.post(
+    'SubmitJSON',
+<% if (useMiddleware) { %>    server.middleware.https,
+<% } %>    function (req, res, next) {
+        var form = req.form;
+
+        // TODO: Validate and process form data
+        var result = {
+            success: true,
+            redirectUrl: null
+        };
+
+        res.json(result);
+        next();
+    }
+);
+<% } %>
+
+module.exports = server.exports();

package/data/scaffolds/controller/files/template.isml.ejs

@@ -0,0 +1,22 @@
+<iscontent type="text/html" charset="UTF-8" compact="true"/>
+
+<isinclude template="/components/modules"/>
+
+<!--- <%= controllerName %> Show Template --->
+
+<isdecorate template="common/layout/page">
+    <isscript>
+        var assets = require('*/cartridge/scripts/assets');
+        assets.addCss('/css/<%= kebabCase(controllerName) %>.css');
+        assets.addJs('/js/<%= kebabCase(controllerName) %>.js');
+    </isscript>
+
+    <div class="container <%= kebabCase(controllerName) %>-page">
+        <div class="row">
+            <div class="col-12">
+                <h1 class="page-title">${pdict.title}</h1>
+                <p class="lead">${pdict.message}</p>
+            </div>
+        </div>
+    </div>
+</isdecorate>

package/data/scaffolds/controller/scaffold.json

@@ -0,0 +1,64 @@
+{
+  "name": "controller",
+  "displayName": "SFRA Controller",
+  "description": "Create an SFRA controller with route handlers and middleware",
+  "category": "cartridge",
+  "parameters": [
+    {
+      "name": "controllerName",
+      "prompt": "What is the controller name?",
+      "type": "string",
+      "required": true,
+      "pattern": "^[A-Z][a-zA-Z0-9]*$",
+      "validationMessage": "Controller name must be PascalCase (start with uppercase letter)"
+    },
+    {
+      "name": "cartridgeName",
+      "prompt": "Which cartridge should contain this controller?",
+      "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": "routes",
+      "prompt": "Which route types do you want to include?",
+      "type": "multi-choice",
+      "required": true,
+      "choices": [
+        { "value": "Show", "label": "Show (GET - render page)" },
+        { "value": "Submit", "label": "Submit (POST - form handler)" },
+        { "value": "JSON", "label": "JSON (GET - AJAX endpoint)" },
+        { "value": "SubmitJSON", "label": "SubmitJSON (POST - AJAX form)" }
+      ],
+      "default": ["Show"]
+    },
+    {
+      "name": "useMiddleware",
+      "prompt": "Include middleware chain example?",
+      "type": "boolean",
+      "required": false,
+      "default": true
+    },
+    {
+      "name": "includeTemplate",
+      "prompt": "Generate accompanying ISML template?",
+      "type": "boolean",
+      "required": false,
+      "default": true
+    }
+  ],
+  "files": [
+    {
+      "template": "controller.js.ejs",
+      "destination": "{{cartridgeNamePath}}/cartridge/controllers/{{controllerName}}.js"
+    },
+    {
+      "template": "template.isml.ejs",
+      "destination": "{{cartridgeNamePath}}/cartridge/templates/default/{{kebabCase controllerName}}/show.isml",
+      "condition": "includeTemplate"
+    }
+  ],
+  "postInstructions": "Controller '<%= controllerName %>' has been created in '<%= cartridgeName %>'.\n\nRoutes created:\n<% routes.forEach(function(route) { %>\n- <%= controllerName %>-<%= route %>: /<%= controllerName %>-<%= route %>\n<% }); %>\n\nNext steps:\n1. Deploy the cartridge to your instance\n2. Ensure <%= cartridgeName %> is in your cartridge path"
+}

package/data/scaffolds/custom-api/files/api.json.ejs

@@ -0,0 +1,11 @@
+{
+  "endpoints": [
+<% if (includeExampleEndpoints) { %>
+    {"endpoint": "getHello", "schema": "schema.yaml", "implementation": "script"},
+    {"endpoint": "getItems", "schema": "schema.yaml", "implementation": "script"},
+    {"endpoint": "getItem", "schema": "schema.yaml", "implementation": "script"}
+<% } else { %>
+    {"endpoint": "getExample", "schema": "schema.yaml", "implementation": "script"}
+<% } %>
+  ]
+}