better docs config/layout

Author: clavery

README.md

@@ -22,3 +22,9 @@ pnpm install
 pnpm start # start the cli in dev mode; see CLI readme for more details
 pnpm test
 ```
+
+Docs development
+
+```bash
+pnpm run docs:dev
+```

docs/.vitepress/config.mts

@@ -12,6 +12,7 @@ export default defineConfig({
   },
 
   themeConfig: {
+    logo: '/logo.svg',
     outline: {
       level: [2, 3],
     },
@@ -21,6 +22,11 @@ export default defineConfig({
       { text: 'API Reference', link: '/api/' },
     ],
 
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: `Copyright © ${new Date().getFullYear()} Salesforce, Inc. All rights reserved.`,
+    },
+
     sidebar: {
       '/guide/': [
         {

docs/public/logo.svg

@@ -1,3 +1,35 @@
+/**
+ * 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 ApiKeyStrategy} - API key authentication for MRT services
+ *
+ * ## Usage
+ *
+ * All strategies implement the {@link AuthStrategy} interface, allowing you to
+ * switch authentication methods without changing your code:
+ *
+ * ```typescript
+ * import { BasicAuthStrategy, OAuthStrategy } from '@salesforce/b2c-tooling';
+ *
+ * // For WebDAV operations (code upload)
+ * const basicAuth = new BasicAuthStrategy('username', 'access-key');
+ *
+ * // For OCAPI operations (sites, jobs)
+ * const oauthAuth = new OAuthStrategy({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ * });
+ * ```
+ *
+ * @module auth
+ */
 export {AuthStrategy, AccessTokenResponse, DecodedJWT} from './types.js';
 export {BasicAuthStrategy} from './basic.js';
 export {OAuthStrategy, OAuthConfig, decodeJWT} from './oauth.js';

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

@@ -1,38 +1,63 @@
-import i18next, {TOptions, Resource} from 'i18next';
-
-// Re-export TOptions for consumers
-export type {TOptions} from 'i18next';
-import {locales} from './locales/index.js';
-
 /**
- * i18n module for B2C CLI tools.
+ * Internationalization (i18n) support for B2C CLI tools.
+ *
+ * This module provides translation utilities using i18next, with support for
+ * multiple languages and environment-based language detection.
+ *
+ * ## Key Features
  *
- * Key features:
  * - Default strings are stored inline at point of use (no separate en.ts needed)
  * - TypeScript locale files for type safety and bundling
  * - Namespace separation: 'b2c' for tooling, 'cli' for CLI-specific messages
  *
- * Language detection precedence:
- * 1. Explicit setLanguage() call (from --lang flag)
- * 2. LANGUAGE environment variable (GNU gettext standard, supports colon-separated list)
- * 3. LANG system environment variable (Unix standard)
+ * ## Language Detection
+ *
+ * Language is detected in this order:
+ * 1. Explicit {@link setLanguage} call (from --lang flag)
+ * 2. `LANGUAGE` environment variable (GNU gettext standard)
+ * 3. `LANG` system environment variable (Unix standard)
  * 4. Default: 'en'
  *
- * Supported locale formats:
- * - "de" - simple language code
- * - "de_DE" - language with country
- * - "de-DE" - language with country (hyphen)
- * - "de_DE.UTF-8" - with encoding
- * - "de_DE@euro" - with modifier
- * - "de:en:fr" - colon-separated preference list (LANGUAGE only)
+ * ## Supported Locale Formats
+ *
+ * - `de` - simple language code
+ * - `de_DE` - language with country
+ * - `de-DE` - language with country (hyphen)
+ * - `de_DE.UTF-8` - with encoding
+ * - `de:en:fr` - colon-separated preference list (LANGUAGE only)
+ *
+ * ## Usage
  *
- * Usage:
- *   import { t } from '@salesforce/b2c-tooling'
- *   throw new Error(t('error.serverRequired', 'Server is required.'))
+ * ```typescript
+ * import { t } from '@salesforce/b2c-tooling';
  *
- * With interpolation:
- *   t('error.fileNotFound', 'File {{path}} not found.', { path: '/foo/bar' })
+ * // Simple translation with inline default
+ * const message = t('error.serverRequired', 'Server is required.');
+ *
+ * // With interpolation
+ * const fileError = t('error.fileNotFound', 'File {{path}} not found.', {
+ *   path: '/foo/bar'
+ * });
+ * ```
+ *
+ * ## Adding Translations
+ *
+ * ```typescript
+ * import { registerTranslations } from '@salesforce/b2c-tooling';
+ *
+ * // Register translations for a new namespace
+ * registerTranslations('my-package', 'de', {
+ *   greeting: 'Hallo Welt'
+ * });
+ * ```
+ *
+ * @module i18n
  */
+import i18next, {TOptions, Resource} from 'i18next';
+
+// Re-export TOptions for consumers
+export type {TOptions} from 'i18next';
+import {locales} from './locales/index.js';
 
 /** The namespace used by b2c-tooling messages */
 export const B2C_NAMESPACE = 'b2c';

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

@@ -1,3 +1,32 @@
+/**
+ * B2C Instance management.
+ *
+ * This module provides the {@link B2CInstance} class which represents a connection
+ * to a specific B2C Commerce instance. It combines instance configuration with
+ * an authentication strategy to make API requests.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { B2CInstance } from '@salesforce/b2c-tooling';
+ * import { OAuthStrategy } from '@salesforce/b2c-tooling/auth';
+ *
+ * const auth = new OAuthStrategy({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ * });
+ *
+ * const instance = new B2CInstance(
+ *   { hostname: 'your-sandbox.demandware.net', codeVersion: 'v1' },
+ *   auth
+ * );
+ *
+ * // Make OCAPI requests
+ * const response = await instance.ocapiDataRequest('sites');
+ * ```
+ *
+ * @module instance
+ */
 import {AuthStrategy} from '../auth/types.js';
 
 export interface InstanceConfig {

packages/b2c-tooling/src/instance/index.ts

@@ -1,6 +1,47 @@
 /**
- * Logger interface for b2c-tooling
- * Consumers can provide their own logger implementation
+ * Logging utilities for B2C CLI tools.
+ *
+ * This module provides a pluggable logging interface that allows consumers
+ * to integrate their own logging implementation.
+ *
+ * ## Built-in Loggers
+ *
+ * - {@link noopLogger} - Silent logger (default) - does nothing
+ * - {@link consoleLogger} - Logs to console
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { setLogger, getLogger, consoleLogger } from '@salesforce/b2c-tooling';
+ *
+ * // Enable console logging
+ * setLogger(consoleLogger);
+ *
+ * // Or use a custom logger
+ * setLogger({
+ *   debug: (msg, ...args) => myLogger.debug(msg, ...args),
+ *   info: (msg, ...args) => myLogger.info(msg, ...args),
+ *   warn: (msg, ...args) => myLogger.warn(msg, ...args),
+ *   error: (msg, ...args) => myLogger.error(msg, ...args),
+ * });
+ *
+ * // Get the current logger
+ * const logger = getLogger();
+ * logger.info('Operation completed');
+ * ```
+ *
+ * ## Default Behavior
+ *
+ * By default, the {@link noopLogger} is used, which silently discards all
+ * log messages. This ensures the library doesn't produce unexpected output
+ * unless logging is explicitly enabled.
+ *
+ * @module logger
+ */
+
+/**
+ * Logger interface for b2c-tooling.
+ * Consumers can provide their own logger implementation.
  */
 export interface Logger {
   debug(message: string, ...args: unknown[]): void;

packages/b2c-tooling/src/logger.ts

@@ -1 +1,38 @@
+/**
+ * Code deployment operations for B2C Commerce.
+ *
+ * This module provides functions for uploading cartridges and managing
+ * code versions on B2C Commerce instances via WebDAV.
+ *
+ * ## Functions
+ *
+ * - {@link uploadCartridges} - Upload cartridge code to an instance
+ * - {@link activateCodeVersion} - Activate a code version on an instance
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { uploadCartridges, activateCodeVersion } from '@salesforce/b2c-tooling/operations/code';
+ * import { B2CInstance, BasicAuthStrategy } from '@salesforce/b2c-tooling';
+ *
+ * const auth = new BasicAuthStrategy('username', 'access-key');
+ * const instance = new B2CInstance(
+ *   { hostname: 'your-sandbox.demandware.net', codeVersion: 'v1' },
+ *   auth
+ * );
+ *
+ * // Upload cartridges from local directory
+ * await uploadCartridges(instance, './cartridges');
+ *
+ * // Activate the code version
+ * await activateCodeVersion(instance, 'v1');
+ * ```
+ *
+ * ## Authentication
+ *
+ * Code deployment uses WebDAV, which supports both Basic Auth and OAuth.
+ * Basic Auth is recommended for better performance.
+ *
+ * @module operations/code
+ */
 export {uploadCartridges, activateCodeVersion} from './upload.js';

packages/b2c-tooling/src/operations/code/index.ts

@@ -1 +1,44 @@
+/**
+ * Job execution operations for B2C Commerce.
+ *
+ * This module provides functions for running and monitoring jobs
+ * on B2C Commerce instances via OCAPI.
+ *
+ * ## Functions
+ *
+ * - {@link runJob} - Start a job execution
+ * - {@link getJobStatus} - Check the status of a running job
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { runJob, getJobStatus } from '@salesforce/b2c-tooling/operations/jobs';
+ * import { B2CInstance, OAuthStrategy } from '@salesforce/b2c-tooling';
+ *
+ * const auth = new OAuthStrategy({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ * });
+ * const instance = new B2CInstance(
+ *   { hostname: 'your-sandbox.demandware.net' },
+ *   auth
+ * );
+ *
+ * // Start a job
+ * const result = await runJob(instance, 'my-job-id');
+ *
+ * // Poll for completion
+ * let status = await getJobStatus(instance, result.jobId, result.executionId);
+ * while (status.status === 'running') {
+ *   await new Promise(resolve => setTimeout(resolve, 5000));
+ *   status = await getJobStatus(instance, result.jobId, result.executionId);
+ * }
+ * ```
+ *
+ * ## Authentication
+ *
+ * Job operations require OAuth authentication with appropriate OCAPI permissions.
+ *
+ * @module operations/jobs
+ */
 export {runJob, getJobStatus, JobExecutionResult} from './run.js';

packages/b2c-tooling/src/operations/jobs/index.ts

@@ -1,3 +1,45 @@
+/**
+ * Site management operations for B2C Commerce.
+ *
+ * This module provides functions for listing and retrieving site information
+ * from B2C Commerce instances via OCAPI.
+ *
+ * ## Functions
+ *
+ * - {@link listSites} - List all sites on an instance
+ * - {@link getSite} - Get details for a specific site
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { listSites, getSite } from '@salesforce/b2c-tooling/operations/sites';
+ * import { B2CInstance, OAuthStrategy } from '@salesforce/b2c-tooling';
+ *
+ * const auth = new OAuthStrategy({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ * });
+ * const instance = new B2CInstance(
+ *   { hostname: 'your-sandbox.demandware.net' },
+ *   auth
+ * );
+ *
+ * // List all sites
+ * const sites = await listSites(instance);
+ * for (const site of sites) {
+ *   console.log(`${site.id}: ${site.displayName} (${site.status})`);
+ * }
+ *
+ * // Get a specific site
+ * const site = await getSite(instance, 'RefArch');
+ * ```
+ *
+ * ## Authentication
+ *
+ * Site operations require OAuth authentication with appropriate OCAPI permissions.
+ *
+ * @module operations/sites
+ */
 import {B2CInstance} from '../../instance/index.js';
 
 export interface Site {