Merge main into feature/scaffolding-framework

Resolve conflicts by keeping both:
- Scaffolding guide/commands from this branch
- IDE Support guide and Account Manager commands from main

Author: clavery

.changeset/am-topic-users-roles-orgs.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Account Manager (AM) topic with `users`, `roles`, and `orgs` subtopics. Use `b2c am users`, `b2c am roles`, and `b2c am orgs` for user, role, and organization management.

.claude/commands/update-script-api-docs.md

@@ -0,0 +1,40 @@
+# Update Script API Documentation
+
+Download the latest B2C Commerce Script API documentation from the configured sandbox and update the bundled docs in the SDK.
+
+## Steps
+
+1. Download Script API docs from the configured sandbox using `./cli docs download`
+2. Replace the markdown files in `packages/b2c-tooling-sdk/data/script-api/`
+3. Regenerate the search index with `pnpm --filter @salesforce/b2c-tooling-sdk run generate:docs-index`
+4. Show the version extracted from `index.md` header
+5. Show git status/diff summary of what changed
+
+## Commands to Run
+
+```bash
+# Download to temp directory
+./cli docs download /tmp/script-api-docs-update
+
+# Check version
+head -1 /tmp/script-api-docs-update/index.md
+
+# Replace existing files
+rm -f packages/b2c-tooling-sdk/data/script-api/*.md
+cp /tmp/script-api-docs-update/*.md packages/b2c-tooling-sdk/data/script-api/
+
+# Regenerate index
+pnpm --filter @salesforce/b2c-tooling-sdk run generate:docs-index
+
+# Show changes
+git status packages/b2c-tooling-sdk/data/script-api/ --short
+git diff packages/b2c-tooling-sdk/data/script-api/*.md --stat
+
+# Cleanup
+rm -rf /tmp/script-api-docs-update
+```
+
+After running, summarize:
+- The Script API version (from index.md header like "# B2C Commerce Script API 26.2")
+- Number of files updated
+- Key changes (new classes, deprecated methods, etc.)

docs/.vitepress/config.mts

@@ -16,6 +16,7 @@ const guideSidebar = [
     items: [
       { text: 'Authentication Setup', link: '/guide/authentication' },
       { text: 'Scaffolding', link: '/guide/scaffolding' },
+      { text: 'IDE Support', link: '/guide/ide-support' },
       { text: 'Security', link: '/guide/security' },
     ],
   },

docs/api-readme.md

@@ -241,6 +241,219 @@ const { data, error } = await instance.ocapi.PATCH('/code_versions/{code_version
 });
 ```
 
+## Account Manager Operations
+
+The SDK provides a unified client for managing users, roles, and organizations through the Account Manager API.
+
+### Authentication
+
+Account Manager operations use **OAuth implicit flow** by default, which opens a browser for interactive authentication. This is ideal for development and manual operations where you want to use roles assigned to your user account.
+
+For CI/CD and automation, you can also use **OAuth client credentials flow** (requires both client ID and secret).
+
+### Unified Client (Recommended)
+
+The recommended approach is to use the unified `createAccountManagerClient` which provides access to all Account Manager APIs (users, roles, and organizations):
+
+```typescript
+import { createAccountManagerClient } from '@salesforce/b2c-tooling-sdk/clients';
+import { ImplicitOAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+
+// Create Account Manager client with implicit OAuth (opens browser for login)
+const auth = new ImplicitOAuthStrategy({
+  clientId: 'your-client-id',
+  // No clientSecret needed for implicit flow
+});
+
+const client = createAccountManagerClient(
+  { accountManagerHost: 'account.demandware.com' },
+  auth,
+);
+
+// Users API
+const users = await client.listUsers({ size: 25, page: 0 });
+const user = await client.getUser('user-id');
+const userByLogin = await client.findUserByLogin('user@example.com');
+await client.createUser({
+  mail: 'newuser@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  organizations: ['org-id'],
+  primaryOrganization: 'org-id',
+});
+await client.updateUser('user-id', { firstName: 'Jane' });
+await client.grantRole('user-id', 'bm-admin', 'tenant1,tenant2');
+await client.revokeRole('user-id', 'bm-admin', 'tenant1');
+await client.resetUser('user-id');
+await client.deleteUser('user-id');
+
+// Roles API
+const roles = await client.listRoles({ size: 20, page: 0 });
+const role = await client.getRole('bm-admin');
+
+// Organizations API
+const orgs = await client.listOrgs({ size: 25, page: 0 });
+const org = await client.getOrg('org-id');
+const orgByName = await client.getOrgByName('My Organization');
+const auditLogs = await client.getOrgAuditLogs('org-id');
+```
+
+### Client Credentials Flow (Alternative)
+
+For automation and CI/CD, you can use client credentials flow:
+
+```typescript
+import { createAccountManagerClient } from '@salesforce/b2c-tooling-sdk/clients';
+import { OAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+
+// Create Account Manager client with client credentials OAuth
+const auth = new OAuthStrategy({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+
+const client = createAccountManagerClient(
+  { accountManagerHost: 'account.demandware.com' },
+  auth,
+);
+
+// Use the unified client as shown above
+```
+
+### Individual Clients
+
+If you only need access to a specific API, you can create individual clients:
+
+```typescript
+import {
+  createAccountManagerUsersClient,
+  createAccountManagerRolesClient,
+  createAccountManagerOrgsClient,
+} from '@salesforce/b2c-tooling-sdk/clients';
+import { ImplicitOAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+
+const auth = new ImplicitOAuthStrategy({
+  clientId: 'your-client-id',
+});
+
+// Users client
+const usersClient = createAccountManagerUsersClient(
+  { accountManagerHost: 'account.demandware.com' },
+  auth,
+);
+
+// Roles client
+const rolesClient = createAccountManagerRolesClient(
+  { accountManagerHost: 'account.demandware.com' },
+  auth,
+);
+
+// Organizations client
+const orgsClient = createAccountManagerOrgsClient(
+  { accountManagerHost: 'account.demandware.com' },
+  auth,
+);
+```
+
+### User Operations
+
+```typescript
+import { createAccountManagerClient } from '@salesforce/b2c-tooling-sdk/clients';
+import { ImplicitOAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+
+const auth = new ImplicitOAuthStrategy({ clientId: 'your-client-id' });
+const client = createAccountManagerClient({}, auth);
+
+// List users with pagination
+const users = await client.listUsers({ size: 25, page: 0 });
+
+// Get user by email/login
+const user = await client.findUserByLogin('user@example.com');
+
+// Get user with expanded organizations and roles
+const userExpanded = await client.getUser('user-id', ['organizations', 'roles']);
+
+// Create a new user
+const newUser = await client.createUser({
+  mail: 'newuser@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  organizations: ['org-id'],
+  primaryOrganization: 'org-id',
+});
+
+// Update a user
+await client.updateUser('user-id', { firstName: 'Jane' });
+
+// Grant a role to a user
+await client.grantRole('user-id', 'bm-admin', 'tenant1,tenant2'); // Optional tenant filter
+
+// Revoke a role from a user
+await client.revokeRole('user-id', 'bm-admin', 'tenant1'); // Optional: remove specific scope
+
+// Reset user to INITIAL state
+await client.resetUser('user-id');
+
+// Delete (disable) a user
+await client.deleteUser('user-id');
+```
+
+### Role Operations
+
+```typescript
+import { createAccountManagerClient } from '@salesforce/b2c-tooling-sdk/clients';
+import { ImplicitOAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+
+const auth = new ImplicitOAuthStrategy({ clientId: 'your-client-id' });
+const client = createAccountManagerClient({}, auth);
+
+// Get role details by ID
+const role = await client.getRole('bm-admin');
+
+// List all roles with pagination
+const roles = await client.listRoles({ size: 25, page: 0 });
+
+// List roles filtered by target type
+const userRoles = await client.listRoles({
+  size: 25,
+  page: 0,
+  roleTargetType: 'User',
+});
+```
+
+### Organization Operations
+
+```typescript
+import { createAccountManagerClient } from '@salesforce/b2c-tooling-sdk/clients';
+import { ImplicitOAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+
+const auth = new ImplicitOAuthStrategy({ clientId: 'your-client-id' });
+const client = createAccountManagerClient({}, auth);
+
+// Get organization by ID
+const org = await client.getOrg('org-123');
+
+// Get organization by name
+const orgByName = await client.getOrgByName('My Organization');
+
+// List organizations with pagination
+const orgs = await client.listOrgs({ size: 25, page: 0 });
+
+// List all organizations (uses max page size of 5000)
+const allOrgs = await client.listOrgs({ all: true });
+
+// Get audit logs for an organization
+const auditLogs = await client.getOrgAuditLogs('org-123');
+```
+
+### Required Permissions
+
+Account Manager operations require:
+- OAuth client with `sfcc.accountmanager.user.manage` scope
+- Account Manager hostname configuration
+- For implicit flow: roles configured on your **user account**
+- For client credentials flow: roles configured on the **API client**
+
 ## Logging
 
 Configure logging for debugging HTTP requests: