Fix AM role mapping, user display, org resolution, and auth error guidance (#143)

* Fix AM role mapping, user display, org resolution, and auth error guidance

- Replace hardcoded role ID maps with dynamic API-based role mapping
  (RoleMapping interface with byId, byEnumName, descriptions maps)
- Fix grant/revoke operations to handle mixed role formats: role IDs
  in roles array, roleEnumNames in roleTenantFilter
- Switch findUserByLogin to dedicated /users/search/findByLogin endpoint
- Extract shared user display utility (user-display.ts) used by
  am users get, am roles grant, and am roles revoke
- Show role descriptions with enum names: "Description (ENUM_NAME)"
- Resolve org IDs to friendly names in user display: "Name (UUID)"
- Add org name resolution utility (resolve-org.ts) so commands that
  accept org IDs also accept friendly org names
- Rename --organizations to --orgs in am clients create
- Detect "Access is denied" errors and suggest --user-auth for all
  AM command subtopics

* Add changeset for AM role mapping and display fixes

* Change changeset bump to patch

* Print user details after am users create success

* Fix null guard in user display for newly created users

The API returns null (not undefined) for empty array fields on new
users. Use truthy checks instead of === undefined.

Author: clavery

.changeset/fix-am-role-mapping-and-display.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Fix AM role ID mapping between API internal/external formats and improve user display output. Role grant/revoke now correctly handle mixed formats (role IDs in roles array, enum names in roleTenantFilter). User display shows role descriptions, resolves org names, and detects auth errors with actionable --user-auth suggestions. Commands accepting org IDs now also accept friendly org names.

docs/cli/auth.md

@@ -22,7 +22,7 @@ b2c auth token
 |------|---------------------|-------------|
 | `--client-id` | `SFCC_CLIENT_ID` | Client ID for OAuth |
 | `--client-secret` | `SFCC_CLIENT_SECRET` | Client Secret for OAuth |
-| `--scope` | `SFCC_OAUTH_SCOPES` | OAuth scopes to request (can be repeated) |
+| `--auth-scope` | `SFCC_OAUTH_SCOPES` | OAuth scopes to request (can be repeated) |
 | `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname (default: account.demandware.com) |
 
 ### Examples
@@ -32,7 +32,7 @@ b2c auth token
 b2c auth token --client-id xxx --client-secret yyy
 
 # Get a token with specific scopes
-b2c auth token --scope sfcc.orders --scope sfcc.products
+b2c auth token --auth-scope sfcc.orders --auth-scope sfcc.products
 
 # Output as JSON (useful for parsing)
 b2c auth token --json

packages/b2c-cli/src/commands/am/clients/create.ts

@@ -7,6 +7,7 @@ import {Flags} from '@oclif/core';
 import {AmCommand} from '@salesforce/b2c-tooling-sdk/cli';
 import {isValidRoleTenantFilter, type AccountManagerApiClient, type APIClientCreate} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
+import {resolveOrgId} from '../../../utils/am/resolve-org.js';
 
 function splitCommaSeparated(s: string): string[] {
   return s
@@ -24,8 +25,8 @@ export default class ClientCreate extends AmCommand<typeof ClientCreate> {
   static enableJsonFlag = true;
 
   static examples = [
-    '<%= config.bin %> <%= command.id %> --name my-client --organizations org-id-1 --password "SecureP@ss123"',
-    '<%= config.bin %> <%= command.id %> --name my-client --organizations org-id-1 --password "SecureP@ss123" --roles SALESFORCE_COMMERCE_API',
+    '<%= config.bin %> <%= command.id %> --name my-client --orgs org-id-1 --password "SecureP@ss123"',
+    '<%= config.bin %> <%= command.id %> --name my-client --orgs "My Organization" --password "SecureP@ss123" --roles SALESFORCE_COMMERCE_API',
   ];
 
   static flags = {
@@ -38,9 +39,9 @@ export default class ClientCreate extends AmCommand<typeof ClientCreate> {
       char: 'd',
       description: 'Description of the API client',
     }),
-    organizations: Flags.string({
+    orgs: Flags.string({
       char: 'o',
-      description: 'Comma-separated organization IDs (required)',
+      description: 'Comma-separated organization IDs or names',
       required: true,
     }),
     password: Flags.string({
@@ -84,9 +85,11 @@ export default class ClientCreate extends AmCommand<typeof ClientCreate> {
   async run(): Promise<AccountManagerApiClient> {
     const flags = this.flags;
     const nameTrimmed = flags.name.trim();
-    const orgIds = splitCommaSeparated(flags.organizations);
+    const orgInputs = splitCommaSeparated(flags.orgs);
 
-    this.validateCreateInput(flags, nameTrimmed, orgIds);
+    this.validateCreateInput(flags, nameTrimmed, orgInputs);
+
+    const orgIds = await Promise.all(orgInputs.map((o) => resolveOrgId(this.accountManagerClient, o)));
 
     const body = this.buildCreateBody(flags, nameTrimmed, orgIds);
 
@@ -187,7 +190,7 @@ export default class ClientCreate extends AmCommand<typeof ClientCreate> {
       );
     }
     if (orgIds.length === 0) {
-      this.error(t('commands.client.create.noOrgs', 'At least one organization ID is required'));
+      this.error(t('commands.client.create.noOrgs', 'At least one organization is required'));
     }
   }
 }

packages/b2c-cli/src/commands/am/roles/grant.ts

@@ -7,6 +7,7 @@ import {Args, Flags} from '@oclif/core';
 import {AmCommand} from '@salesforce/b2c-tooling-sdk/cli';
 import type {AccountManagerUser} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
+import {printUserDetails} from '../../../utils/am/user-display.js';
 
 /**
  * Command to grant a role to an Account Manager user.
@@ -79,6 +80,12 @@ export default class RoleGrant extends AmCommand<typeof RoleGrant> {
 
     this.log(message);
 
+    const [roleMapping, orgMapping] = await Promise.all([
+      this.accountManagerClient.getRoleMapping(),
+      this.accountManagerClient.getOrgMapping(),
+    ]);
+    printUserDetails(updatedUser, roleMapping, orgMapping);
+
     return updatedUser;
   }
 }

packages/b2c-cli/src/commands/am/roles/revoke.ts

@@ -7,6 +7,7 @@ import {Args, Flags} from '@oclif/core';
 import {AmCommand} from '@salesforce/b2c-tooling-sdk/cli';
 import type {AccountManagerUser} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
+import {printUserDetails} from '../../../utils/am/user-display.js';
 
 /**
  * Command to revoke a role from an Account Manager user.
@@ -79,6 +80,12 @@ export default class RoleRevoke extends AmCommand<typeof RoleRevoke> {
 
     this.log(message);
 
+    const [roleMapping, orgMapping] = await Promise.all([
+      this.accountManagerClient.getRoleMapping(),
+      this.accountManagerClient.getOrgMapping(),
+    ]);
+    printUserDetails(updatedUser, roleMapping, orgMapping);
+
     return updatedUser;
   }
 }

packages/b2c-cli/src/commands/am/users/create.ts

@@ -7,6 +7,8 @@ import {Flags} from '@oclif/core';
 import {AmCommand} from '@salesforce/b2c-tooling-sdk/cli';
 import type {AccountManagerUser} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
+import {resolveOrgId} from '../../../utils/am/resolve-org.js';
+import {printUserDetails} from '../../../utils/am/user-display.js';
 
 /**
  * Command to create a new Account Manager user.
@@ -18,13 +20,13 @@ export default class UserCreate extends AmCommand<typeof UserCreate> {
 
   static examples = [
     '<%= config.bin %> <%= command.id %> --org org-id --mail user@example.com --first-name John --last-name Doe',
-    '<%= config.bin %> <%= command.id %> --org org-id --mail user@example.com --first-name John --last-name Doe --json',
+    '<%= config.bin %> <%= command.id %> --org "My Organization" --mail user@example.com --first-name John --last-name Doe --json',
   ];
 
   static flags = {
     org: Flags.string({
       char: 'o',
-      description: 'Organization ID to create the user in',
+      description: 'Organization ID or name',
       required: true,
     }),
     mail: Flags.string({
@@ -43,26 +45,39 @@ export default class UserCreate extends AmCommand<typeof UserCreate> {
   };
 
   async run(): Promise<AccountManagerUser> {
-    const {org, mail, 'first-name': firstName, 'last-name': lastName} = this.flags;
+    const {org: orgInput, mail, 'first-name': firstName, 'last-name': lastName} = this.flags;
 
-    this.log(t('commands.user.create.creating', 'Creating user {{mail}} in organization {{org}}...', {mail, org}));
+    const orgId = await resolveOrgId(this.accountManagerClient, orgInput);
+
+    this.log(
+      t('commands.user.create.creating', 'Creating user {{mail}} in organization {{org}}...', {mail, org: orgId}),
+    );
 
     const user = await this.accountManagerClient.createUser({
       mail,
       firstName,
       lastName,
-      organizations: [org],
-      primaryOrganization: org,
+      organizations: [orgId],
+      primaryOrganization: orgId,
     });
 
     if (this.jsonEnabled()) {
       return user;
     }
 
     this.log(
-      t('commands.user.create.success', 'User {{mail}} created successfully in organization {{org}}.', {mail, org}),
+      t('commands.user.create.success', 'User {{mail}} created successfully in organization {{org}}.', {
+        mail,
+        org: orgId,
+      }),
     );
 
+    const [roleMapping, orgMapping] = await Promise.all([
+      this.accountManagerClient.getRoleMapping(),
+      this.accountManagerClient.getOrgMapping(),
+    ]);
+    printUserDetails(user, roleMapping, orgMapping);
+
     return user;
   }
 }

packages/b2c-cli/src/commands/am/users/get.ts

@@ -3,11 +3,11 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
-import {Args, Flags, ux} from '@oclif/core';
-import cliui from 'cliui';
+import {Args, Flags} from '@oclif/core';
 import {AmCommand} from '@salesforce/b2c-tooling-sdk/cli';
 import type {AccountManagerUser, UserExpandOption} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
+import {printUserDetails} from '../../../utils/am/user-display.js';
 
 /**
  * Valid expand values for the users API.
@@ -107,96 +107,12 @@ export default class UserGet extends AmCommand<typeof UserGet> {
       return user;
     }
 
-    this.printUserDetails(user);
+    const [roleMapping, orgMapping] = await Promise.all([
+      this.accountManagerClient.getRoleMapping(),
+      this.accountManagerClient.getOrgMapping(),
+    ]);
+    printUserDetails(user, roleMapping, orgMapping);
 
     return user;
   }
-
-  private printBasicFields(ui: ReturnType<typeof cliui>, user: AccountManagerUser): void {
-    const isPasswordExpired = user.passwordExpirationTimestamp
-      ? user.passwordExpirationTimestamp < Date.now()
-      : undefined;
-    const twoFAEnabled = user.verifiers && user.verifiers.length > 0 ? 'Yes' : 'No';
-
-    const fields: [string, string | undefined][] = [
-      ['ID', user.id],
-      ['Email', user.mail],
-      ['First Name', user.firstName],
-      ['Last Name', user.lastName],
-      ['Display Name', user.displayName],
-      ['State', user.userState],
-      ['Primary Organization', user.primaryOrganization],
-      ['Preferred Locale', user.preferredLocale || undefined],
-      ['Business Phone', user.businessPhone || undefined],
-      ['Home Phone', user.homePhone || undefined],
-      ['Mobile Phone', user.mobilePhone || undefined],
-      ['Linked to SF Identity', user.linkedToSfIdentity?.toString()],
-      ['2FA Enabled', twoFAEnabled],
-      ['Password Expired', isPasswordExpired === undefined ? undefined : isPasswordExpired ? 'Yes' : 'No'],
-      ['Last Login', user.lastLoginDate || undefined],
-      ['Created At', user.createdAt ? new Date(user.createdAt).toLocaleString() : undefined],
-      ['Last Modified', user.lastModified ? new Date(user.lastModified).toLocaleString() : undefined],
-    ];
-
-    for (const [label, value] of fields) {
-      if (value !== undefined) {
-        ui.div({text: `${label}:`, width: 25, padding: [0, 2, 0, 0]}, {text: value, padding: [0, 0, 0, 0]});
-      }
-    }
-  }
-
-  private printOrganizations(ui: ReturnType<typeof cliui>, user: AccountManagerUser): void {
-    if (user.organizations === undefined || user.organizations.length === 0) {
-      return;
-    }
-
-    ui.div({text: 'Organizations', padding: [2, 0, 0, 0]});
-    ui.div({text: '─'.repeat(50), padding: [0, 0, 0, 0]});
-
-    const orgIds = user.organizations.map((o) => (typeof o === 'string' ? o : o.id || 'Unknown'));
-    ui.div(
-      {text: 'Organization IDs:', width: 25, padding: [0, 2, 0, 0]},
-      {text: orgIds.join(', '), padding: [0, 0, 0, 0]},
-    );
-  }
-
-  private printRoles(ui: ReturnType<typeof cliui>, user: AccountManagerUser): void {
-    if (user.roles === undefined || user.roles.length === 0) {
-      return;
-    }
-
-    ui.div({text: 'Roles', padding: [2, 0, 0, 0]});
-    ui.div({text: '─'.repeat(50), padding: [0, 0, 0, 0]});
-
-    const roleNames = user.roles.map((r) => (typeof r === 'string' ? r : r.roleEnumName || r.id || 'Unknown'));
-    ui.div({text: 'Role IDs:', width: 25, padding: [0, 2, 0, 0]}, {text: roleNames.join(', '), padding: [0, 0, 0, 0]});
-  }
-
-  private printRoleTenantFilters(ui: ReturnType<typeof cliui>, user: AccountManagerUser): void {
-    if (user.roleTenantFilterMap === undefined || Object.keys(user.roleTenantFilterMap).length === 0) {
-      return;
-    }
-
-    ui.div({text: 'Role Tenant Filters', padding: [2, 0, 0, 0]});
-    ui.div({text: '─'.repeat(50), padding: [0, 0, 0, 0]});
-
-    for (const [roleId, filter] of Object.entries(user.roleTenantFilterMap)) {
-      const filterValue = typeof filter === 'string' ? filter : JSON.stringify(filter);
-      ui.div({text: `${roleId}:`, width: 30, padding: [0, 2, 0, 0]}, {text: filterValue, padding: [0, 0, 0, 0]});
-    }
-  }
-
-  private printUserDetails(user: AccountManagerUser): void {
-    const ui = cliui({width: process.stdout.columns || 80});
-
-    ui.div({text: 'User Details', padding: [1, 0, 0, 0]});
-    ui.div({text: '─'.repeat(50), padding: [0, 0, 0, 0]});
-
-    this.printBasicFields(ui, user);
-    this.printOrganizations(ui, user);
-    this.printRoles(ui, user);
-    this.printRoleTenantFilters(ui, user);
-
-    ux.stdout(ui.toString());
-  }
 }

packages/b2c-cli/src/commands/auth/token.ts

@@ -27,7 +27,7 @@ export default class AuthToken extends OAuthCommand<typeof AuthToken> {
 
   static examples = [
     '<%= config.bin %> <%= command.id %>',
-    '<%= config.bin %> <%= command.id %> --scope sfcc.orders --scope sfcc.products',
+    '<%= config.bin %> <%= command.id %> --auth-scope sfcc.orders --auth-scope sfcc.products',
     '<%= config.bin %> <%= command.id %> --json',
   ];
 

packages/b2c-cli/src/utils/am/resolve-org.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import type {AccountManagerOrganization} from '@salesforce/b2c-tooling-sdk';
+
+interface OrgResolver {
+  getOrg(orgId: string): Promise<AccountManagerOrganization>;
+  getOrgByName(name: string): Promise<AccountManagerOrganization>;
+}
+
+/**
+ * Resolves an organization identifier (ID or friendly name) to an org ID.
+ * Tries by ID first, then falls back to name lookup.
+ */
+export async function resolveOrgId(client: OrgResolver, orgIdOrName: string): Promise<string> {
+  try {
+    const org = await client.getOrg(orgIdOrName);
+    return org.id!;
+  } catch {
+    const org = await client.getOrgByName(orgIdOrName);
+    return org.id!;
+  }
+}