Merge branch 'main' into feature/open-source-template

Author: clavery

easy-setup-step-by-step.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+export SFCC_MRT_PROJECT=cli
+export REALM="zzpq"
+export SFCC_CLIENT_ID="a0a4deb0-5e03-477b-bfdc-e42ccfae6161"
+
+b2c ods create -r $REALM --wait --ttl 0
+
+# create mrt env called chuck in the cli project
+b2c mrt env create chuck --name chuck \
+  --allow-cookies \
+  --proxy api=kv7kzm78.api.commercecloud.salesforce.com \
+  --proxy einstein=api.cquotient.com
+
+# construct redirect-uri from ssr_external_hostname above and don't use localhost:3000
+b2c slas client create \
+  --channels MarketStreet \
+  --tenant-id zzpq_014 \
+  --short-code kv7kzm78 \
+  --redirect-uri https://myproject-chuck.sfdc-8tgtt5-ecom1.exp-delivery.com/callback,http://localhost:3000/callback \
+  --default-scopes
+
+# get clientId and COMMERCE_API_SLAS_SECRET from the output of the previous command and callback from the redirect-uri above
+b2c mrt env var set -e chuck \
+  PUBLIC__app__commerce__api__clientId=5810be72-3b2f-49bc-8ca1-eb88119de2fa \
+  PUBLIC__app__commerce__api__organizationId=f_ecom_zzpq_014 \
+  PUBLIC__app__commerce__api__siteId=RefArch \
+  PUBLIC__app__commerce__api__shortCode= \
+  PUBLIC__app__commerce__api__callback=https://myproject-chuck.sfdc-8tgtt5-ecom1.exp-delivery.com/callback \
+  PUBLIC__app__commerce__api__privateKeyEnabled=true \
+  COMMERCE_API_SLAS_SECRET=sk_kasdjlkjsalkjasd
+
+# import market street data from storefront-datasets repo
+b2c job import --server zzpq-014.dx.commercecloud.salesforce.com ~/code/storefront-datasets/demo_data_marketstreet
+
+b2c code deploy
+b2c mrt push -e headertest -p cli -b ~/code/SFCC-Odyssey/packages/template-retail-rsc-app/build --ssr-only='ssr.js,ssr.mjs,chunk.mjs,server/**/*'
+
+

easy-setup.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Configuration - modify these values for your setup
+ENV_SLUG="demo15"
+ENV_NAME="demo15"
+SITE_ID="RefArch"
+TENANT_ID="zzpq_013"
+ORGANIZATION_ID="f_ecom_zzsa_009"
+SHORT_CODE="kv7kzm78"
+BUILD_PATH="${BUILD_PATH:-$HOME/code/SFCC-Odyssey/packages/template-retail-rsc-app/build}"
+
+export SFCC_MRT_PROJECT="${SFCC_MRT_PROJECT:-cli}"
+
+echo "=== Step 1: Creating MRT environment ==="
+ENV_JSON=$(b2c mrt env create "$ENV_SLUG" --name "$ENV_NAME" --json)
+echo "Environment created."
+
+# Extract the external hostname for the callback URL
+SSR_EXTERNAL_HOSTNAME=$(echo "$ENV_JSON" | jq -r '.ssr_external_hostname // empty')
+if [[ -z "$SSR_EXTERNAL_HOSTNAME" ]]; then
+  # Fall back to hostname if external hostname not set
+  SSR_EXTERNAL_HOSTNAME=$(echo "$ENV_JSON" | jq -r '.hostname // empty')
+fi
+
+if [[ -z "$SSR_EXTERNAL_HOSTNAME" ]]; then
+  echo "Warning: Could not determine external hostname from environment. Using localhost."
+  CALLBACK_URL="http://localhost:3000/callback"
+else
+  CALLBACK_URL="https://${SSR_EXTERNAL_HOSTNAME}/callback"
+fi
+echo "Callback URL: $CALLBACK_URL"
+
+echo ""
+echo "=== Step 2: Creating SLAS client ==="
+SLAS_JSON=$(b2c slas client create --channels "$SITE_ID" \
+  --redirect-uri "$CALLBACK_URL" \
+  --default-scopes \
+  --tenant-id "$TENANT_ID" \
+  --json)
+echo "SLAS client created."
+
+# Extract client ID and secret from SLAS response
+CLIENT_ID=$(echo "$SLAS_JSON" | jq -r '.clientId')
+CLIENT_SECRET=$(echo "$SLAS_JSON" | jq -r '.secret // empty')
+
+if [[ -z "$CLIENT_ID" ]]; then
+  echo "Error: Failed to get client ID from SLAS response"
+  exit 1
+fi
+
+echo "Client ID: $CLIENT_ID"
+if [[ -n "$CLIENT_SECRET" ]]; then
+  echo "Client Secret: $CLIENT_SECRET (save this - it won't be shown again)"
+fi
+
+echo ""
+echo "=== Step 3: Setting environment variables ==="
+b2c mrt env var set -e "$ENV_SLUG" \
+  "PUBLIC__app__commerce__api__clientId=$CLIENT_ID" \
+  "PUBLIC__app__commerce__api__organizationId=$ORGANIZATION_ID" \
+  "PUBLIC__app__commerce__api__siteId=$SITE_ID" \
+  "PUBLIC__app__commerce__api__shortCode=$SHORT_CODE" \
+  "PUBLIC__app__commerce__api__proxy=/mobify/proxy/api" \
+  "PUBLIC__app__commerce__api__callback=$CALLBACK_URL" \
+  "PUBLIC__app__commerce__api__privateKeyEnabled=true" \
+  ${CLIENT_SECRET:+"COMMERCE_API_SLAS_SECRET=$CLIENT_SECRET"}
+
+echo ""
+echo "=== Step 4: Deploying code ==="
+b2c code deploy
+
+echo ""
+echo "=== Step 5: Importing job data ==="
+b2c job import data/urls
+
+echo ""
+echo "=== Step 6: Pushing to MRT ==="
+b2c mrt push -e "$ENV_SLUG" -b "$BUILD_PATH"
+
+echo ""
+echo "=== Setup Complete ==="
+echo "Environment: $ENV_SLUG"
+echo "Client ID: $CLIENT_ID"
+echo "URL: https://${SSR_EXTERNAL_HOSTNAME:-localhost:3000}"

packages/b2c-cli/src/i18n/index.ts

@@ -3,6 +3,16 @@
  * 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
  */
+/**
+ * i18n setup for b2c-cli.
+ *
+ * This module registers CLI-specific translations with the 'cli' namespace.
+ * The core i18n infrastructure comes from @salesforce/b2c-tooling-sdk.
+ *
+ * Usage in commands:
+ *   import { t } from '../i18n/index.js'
+ *   this.log(t('commands.sites.list.fetching', 'Fetching sites from {{hostname}}...', { hostname }))
+ */
 
 import {registerTranslations, t as toolingT, type TOptions} from '@salesforce/b2c-tooling-sdk';
 import {locales} from './locales/index.js';

packages/b2c-tooling-sdk/src/auth/index.ts

@@ -3,6 +3,61 @@
  * 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
  */
+/**
+ * Authentication strategies for B2C Commerce APIs.
+ *
+ * This module provides different authentication mechanisms for connecting to
+ * B2C Commerce instances and platform services.
+ *
+ * ## Available Strategies
+ *
+ * - {@link BasicAuthStrategy} - Username/password authentication for WebDAV operations
+ * - {@link OAuthStrategy} - OAuth 2.0 client credentials for OCAPI and platform APIs
+ * - {@link ImplicitOAuthStrategy} - Interactive browser-based OAuth for CLI/desktop apps
+ * - {@link ApiKeyStrategy} - API key authentication for MRT services
+ *
+ * ## Strategy Resolution
+ *
+ * Use {@link resolveAuthStrategy} to automatically select the best strategy based on
+ * available credentials and allowed methods:
+ *
+ * ```typescript
+ * import { resolveAuthStrategy } from '@salesforce/b2c-tooling-sdk';
+ *
+ * // Automatically picks client-credentials if secret available, otherwise implicit
+ * const strategy = resolveAuthStrategy({
+ *   clientId: 'your-client-id',
+ *   clientSecret: process.env.CLIENT_SECRET, // may be undefined
+ * });
+ *
+ * // Force a specific method
+ * const implicitOnly = resolveAuthStrategy(
+ *   { clientId: 'your-client-id' },
+ *   { allowedMethods: ['implicit'] }
+ * );
+ * ```
+ *
+ * ## Direct Usage
+ *
+ * All strategies implement the {@link AuthStrategy} interface:
+ *
+ * ```typescript
+ * import { OAuthStrategy, ImplicitOAuthStrategy } from '@salesforce/b2c-tooling-sdk';
+ *
+ * // For automated/server usage (client credentials)
+ * const oauthAuth = new OAuthStrategy({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ * });
+ *
+ * // For interactive/CLI usage (opens browser)
+ * const implicitAuth = new ImplicitOAuthStrategy({
+ *   clientId: 'your-client-id',
+ * });
+ * ```
+ *
+ * @module auth
+ */
 
 // Types
 export type {

packages/b2c-tooling-sdk/src/auth/resolve.ts

@@ -3,6 +3,29 @@
  * 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
  */
+/**
+ * Auth strategy resolution utilities.
+ *
+ * This module provides functions to automatically select and create the appropriate
+ * authentication strategy based on available credentials and allowed methods.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { resolveAuthStrategy, checkAvailableAuthMethods } from '@salesforce/b2c-tooling-sdk';
+ *
+ * // Auto-select best strategy based on credentials
+ * const strategy = resolveAuthStrategy({
+ *   clientId: 'my-client-id',
+ *   clientSecret: process.env.CLIENT_SECRET,
+ * });
+ *
+ * // Check which methods are available
+ * const { available, unavailable } = checkAvailableAuthMethods(credentials);
+ * ```
+ *
+ * @module auth/resolve
+ */
 
 import type {AuthStrategy, AuthMethod, AuthCredentials} from './types.js';
 import {ALL_AUTH_METHODS} from './types.js';

packages/b2c-tooling-sdk/src/cli/index.ts

@@ -3,6 +3,90 @@
  * 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
  */
+/**
+ * CLI utilities and base command classes for building B2C Commerce CLI commands.
+ *
+ * This module provides reusable base classes, configuration loading, and table
+ * rendering utilities for oclif-based CLI applications.
+ *
+ * ## Base Command Classes
+ *
+ * Extend these classes to create CLI commands with pre-configured functionality:
+ *
+ * - {@link BaseCommand} - Foundation class with logging, JSON output, and error handling
+ * - {@link OAuthCommand} - Adds OAuth authentication setup
+ * - {@link InstanceCommand} - Adds B2C Commerce instance configuration
+ * - {@link CartridgeCommand} - Adds cartridge path configuration for code operations
+ * - {@link JobCommand} - Adds job execution configuration
+ * - {@link MrtCommand} - Adds Managed Runtime API authentication
+ * - {@link OdsCommand} - Adds On-Demand Sandbox configuration
+ *
+ * ## Command Hierarchy
+ *
+ * Commands inherit in a chain, each adding specific functionality:
+ *
+ * ```
+ * BaseCommand
+ *   └─ OAuthCommand (adds OAuth)
+ *        └─ InstanceCommand (adds instance config)
+ *             ├─ CartridgeCommand (adds cartridge paths)
+ *             └─ JobCommand (adds job config)
+ *        └─ MrtCommand (adds MRT API auth)
+ *        └─ OdsCommand (adds ODS config)
+ * ```
+ *
+ * ## Example Usage
+ *
+ * ```typescript
+ * import { InstanceCommand, createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * export default class ListSites extends InstanceCommand {
+ *   static description = 'List all sites on the instance';
+ *
+ *   async run() {
+ *     const client = await this.createOcapiClient();
+ *     const sites = await client.getSites();
+ *
+ *     const columns: Record<string, ColumnDef<Site>> = {
+ *       id: { header: 'ID', get: (s) => s.id },
+ *       name: { header: 'Name', get: (s) => s.display_name },
+ *     };
+ *
+ *     createTable(columns).render(sites, ['id', 'name']);
+ *   }
+ * }
+ * ```
+ *
+ * ## Configuration Loading
+ *
+ * Use {@link loadConfig} to resolve configuration from multiple sources:
+ *
+ * ```typescript
+ * import { loadConfig } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * const config = await loadConfig({
+ *   flags: { hostname: 'example.com' },
+ *   configPath: './dw.json',
+ * });
+ * ```
+ *
+ * ## Table Rendering
+ *
+ * Use {@link createTable} for consistent tabular output:
+ *
+ * ```typescript
+ * import { createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * const columns: Record<string, ColumnDef<Item>> = {
+ *   id: { header: 'ID', get: (item) => item.id },
+ *   status: { header: 'Status', get: (item) => item.status },
+ * };
+ *
+ * createTable(columns).render(items, ['id', 'status']);
+ * ```
+ *
+ * @module cli
+ */
 
 // Base command classes
 export {BaseCommand} from './base-command.js';

packages/b2c-tooling-sdk/src/cli/table.ts

@@ -3,6 +3,34 @@
  * 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
  */
+/**
+ * Table rendering utilities for CLI output.
+ *
+ * Provides a consistent, flexible way to render tabular data in CLI commands
+ * with dynamic column widths based on content.
+ *
+ * @module cli/table
+ *
+ * @example
+ * ```typescript
+ * import { TableRenderer, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * interface User {
+ *   name: string;
+ *   email: string;
+ *   role: string;
+ * }
+ *
+ * const columns: Record<string, ColumnDef<User>> = {
+ *   name: { header: 'Name', get: (u) => u.name },
+ *   email: { header: 'Email', get: (u) => u.email },
+ *   role: { header: 'Role', get: (u) => u.role },
+ * };
+ *
+ * const table = new TableRenderer(columns);
+ * table.render(users, ['name', 'email', 'role']);
+ * ```
+ */
 import {ux} from '@oclif/core';
 import cliui from 'cliui';