feat: refactor SDK module structure for cleaner public API (#87)

* feat: refactor SDK module structure for cleaner public API

Reorganize SDK modules to improve discoverability and align with
documentation structure:

Module reorganization:
- Move operations/docs -> docs/ (top-level for B2C Script API docs)
- Move operations/scapi-schemas -> schemas/ (top-level for OpenAPI utils)
- Remove platform/ module (consolidated into operations/mrt, operations/ods)
- Remove deprecated src/logger.ts (use logging/ module)

Documentation updates:
- Revise API landing page intro to reflect full SDK scope
- Restructure Quick Start with capability examples (instance ops, jobs,
  platform clients, MRT operations)
- Update typedoc.json entry points to match actual modules and align
  ordering with documentation structure

CLI command updates:
- Update docs commands to import from new @salesforce/b2c-tooling-sdk/docs
- Update scapi schemas command to import from new /schemas module

* docs: add curated endpoint documentation to API clients

Add common endpoints table, code examples, and API reference links
to each client type alias JSDoc. Also adds a Typed Clients section
to the API landing page linking to all available clients.

Author: clavery

docs/.vitepress/config.mts

@@ -52,6 +52,9 @@ export default defineConfig({
   description: 'Salesforce Commerce Cloud B2C Developer Experience - CLI, MCP Server, and SDK',
   base: '/b2c-developer-tooling/',
 
+  // Ignore dead links in api-readme.md (links are valid after TypeDoc generates the API docs)
+  ignoreDeadLinks: [/^\.\/clients\//],
+
   // Show deeper heading levels in the outline
   markdown: {
     toc: { level: [2, 3, 4] },

docs/api-readme.md

@@ -4,68 +4,98 @@ description: API reference for the B2C Tooling SDK with typed WebDAV and OCAPI c
 
 # API Reference
 
-The `@salesforce/b2c-tooling-sdk` package provides a programmatic API for interacting with Salesforce B2C Commerce instances.
+The `@salesforce/b2c-tooling-sdk` package provides TypeScript APIs for B2C Commerce development, including instance clients (WebDAV, OCAPI), platform service clients (SCAPI, SLAS, MRT, ODS), high-level operations, and developer utilities.
 
 ## Installation
 
 ```bash
 npm install @salesforce/b2c-tooling-sdk
 ```
 
-## Quick Start
+## Package Structure
+
+The SDK is organized into focused submodules that can be imported individually:
 
-### From Configuration (Recommended)
+```
+@salesforce/b2c-tooling-sdk
+├── /config          # Configuration resolution (dw.json, env vars)
+├── /auth            # Authentication strategies (OAuth, Basic, API Key)
+├── /clients         # Low-level API clients (WebDAV, OCAPI, SLAS, ODS, MRT)
+├── /logging         # Pino-based logging configuration
+│
+├── /operations/code # Code deployment, cartridge management
+├── /operations/jobs # Job execution, site archive import/export
+├── /operations/logs # Log tailing and retrieval
+├── /operations/mrt  # Managed Runtime bundle operations
+├── /operations/ods  # On-demand sandbox utilities
+│
+├── /docs            # B2C Script API documentation search
+└── /schemas         # OpenAPI schema utilities
+```
 
-Use `resolveConfig()` to load configuration from project files (dw.json) and create a B2C instance:
+Import from specific submodules to access their functionality:
 
 ```typescript
 import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
+import { findAndDeployCartridges } from '@salesforce/b2c-tooling-sdk/operations/code';
+import { tailLogs } from '@salesforce/b2c-tooling-sdk/operations/logs';
+```
 
-// Load configuration, override secrets from environment
-const config = resolveConfig({
-  clientId: process.env.SFCC_CLIENT_ID,
-  clientSecret: process.env.SFCC_CLIENT_SECRET,
-});
+## Quick Start
 
-// Validate configuration before use
-if (!config.hasB2CInstanceConfig()) {
-  throw new Error('Missing B2C instance configuration');
-}
+### B2C Instance Operations
 
-// Create instance from validated config
-const instance = config.createB2CInstance();
+```typescript
+import { B2CInstance } from '@salesforce/b2c-tooling-sdk';
 
-// Use typed WebDAV client
-await instance.webdav.mkcol('Cartridges/v1');
-await instance.webdav.put('Cartridges/v1/app.zip', zipBuffer);
+const instance = new B2CInstance(
+  { hostname: 'your-sandbox.demandware.net', codeVersion: 'v1' },
+  { oauth: { clientId: 'your-client-id', clientSecret: 'your-client-secret' } }
+);
 
-// Use typed OCAPI client (openapi-fetch)
-const { data, error } = await instance.ocapi.GET('/sites', {
-  params: { query: { select: '(**)' } },
-});
+// Typed WebDAV client
+await instance.webdav.put('Cartridges/v1/app.zip', zipBuffer);
 
-// Check for configuration warnings
-for (const warning of config.warnings) {
-  console.warn(warning.message);
-}
+// Typed OCAPI client (openapi-fetch)
+const { data } = await instance.ocapi.GET('/sites');
 ```
 
-### Direct Construction
+### Job Execution
+
+```typescript
+import { executeJob, waitForJob } from '@salesforce/b2c-tooling-sdk/operations/jobs';
+
+const execution = await executeJob(instance, 'MyCustomJob');
+const result = await waitForJob(instance, 'MyCustomJob', execution.id!);
+```
 
-For advanced use cases, you can construct a B2CInstance directly:
+### Platform Service Clients
 
 ```typescript
-import { B2CInstance } from '@salesforce/b2c-tooling-sdk';
+import { createSlasClient, OAuthStrategy } from '@salesforce/b2c-tooling-sdk';
 
-const instance = new B2CInstance(
-  { hostname: 'your-sandbox.demandware.net', codeVersion: 'v1' },
-  {
-    oauth: {
-      clientId: 'your-client-id',
-      clientSecret: 'your-client-secret'
-    }
-  }
-);
+const auth = new OAuthStrategy({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+
+const slasClient = createSlasClient({ shortCode: 'kv7kzm78' }, auth);
+const { data } = await slasClient.GET('/tenants/{tenantId}/clients', {
+  params: { path: { tenantId: 'your-tenant' } },
+});
+```
+
+### MRT Operations
+
+```typescript
+import { pushBundle, ApiKeyStrategy } from '@salesforce/b2c-tooling-sdk';
+
+const auth = new ApiKeyStrategy(process.env.MRT_API_KEY!);
+const result = await pushBundle({
+  projectSlug: 'my-storefront',
+  buildDirectory: './build',
+  target: 'staging',
+}, auth);
 ```
 
 ## Configuration Resolution
@@ -105,33 +135,14 @@ if (config.hasB2CInstanceConfig()) {
 
 // Check for MRT configuration
 if (config.hasMrtConfig()) {
-  const mrtClient = config.createMrtClient({ project: 'my-project' });
+  const mrtAuth = config.createMrtAuth();
 }
 
 // Other validation methods
 config.hasOAuthConfig();      // OAuth credentials available?
 config.hasBasicAuthConfig();  // Basic auth credentials available?
 ```
 
-### Configuration Warnings
-
-The config system detects potential issues and provides warnings:
-
-```typescript
-const config = resolveConfig({
-  hostname: 'staging.demandware.net', // Different from dw.json
-});
-
-// Check warnings
-for (const warning of config.warnings) {
-  console.warn(`[${warning.code}] ${warning.message}`);
-}
-```
-
-### Hostname Protection
-
-When you explicitly override the hostname with a value that differs from dw.json, the system protects against credential leakage by ignoring the dw.json credentials. This prevents accidentally using production credentials against a staging server.
-
 ## Authentication
 
 B2CInstance supports multiple authentication methods:
@@ -169,32 +180,48 @@ When both are configured, WebDAV uses Basic auth and OCAPI uses OAuth.
 
 ## Typed Clients
 
+The SDK provides typed clients for B2C Commerce APIs. All clients use [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) for full TypeScript support with type-safe paths, parameters, and responses.
+
+### Instance Clients
+
+These clients are accessed via `B2CInstance` for operations on a specific B2C Commerce instance:
+
+| Client | Description | API Reference |
+|--------|-------------|---------------|
+| [WebDavClient](./clients/classes/WebDavClient.md) | File operations (upload, download, list) | WebDAV |
+| [OcapiClient](./clients/type-aliases/OcapiClient.md) | Data API operations (sites, jobs, code versions) | [OCAPI Data API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/b2c-api-doc.html) |
+
+### Platform Service Clients
+
+These clients are created directly for platform-wide services:
+
+| Client | Description | API Reference |
+|--------|-------------|---------------|
+| [SlasClient](./clients/type-aliases/SlasClient.md) | SLAS tenant and client management | [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references/slas-admin?meta=Summary) |
+| [OdsClient](./clients/type-aliases/OdsClient.md) | On-demand sandbox management | [ODS REST API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ods-rest-api?meta=Summary) |
+| [MrtClient](./clients/type-aliases/MrtClient.md) | Managed Runtime projects and deployments | [MRT Admin API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary) |
+| [MrtB2CClient](./clients/type-aliases/MrtB2CClient.md) | MRT B2C Commerce integration | [MRT B2C Config API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=Summary) |
+| [CdnZonesClient](./clients/type-aliases/CdnZonesClient.md) | eCDN zone and cache management | [CDN Zones API](https://developer.salesforce.com/docs/commerce/commerce-api/references/cdn-api-process-apis?meta=Summary) |
+| [ScapiSchemasClient](./clients/type-aliases/ScapiSchemasClient.md) | SCAPI schema discovery | [SCAPI Schemas API](https://developer.salesforce.com/docs/commerce/commerce-api/references/scapi-schemas?meta=Summary) |
+| [CustomApisClient](./clients/type-aliases/CustomApisClient.md) | Custom SCAPI endpoint status | [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=Summary) |
+
 ### WebDAV Client
 
 ```typescript
-// Create directories
-await instance.webdav.mkcol('Cartridges/v1');
-
 // Upload files
 await instance.webdav.put('Cartridges/v1/app.zip', buffer, 'application/zip');
 
-// Download files
-const content = await instance.webdav.get('Cartridges/v1/app.zip');
-
-// List directory
+// List directory contents
 const entries = await instance.webdav.propfind('Cartridges');
 
-// Check existence
-const exists = await instance.webdav.exists('Cartridges/v1');
+// Download files
+const content = await instance.webdav.get('Cartridges/v1/app.zip');
 
-// Delete
-await instance.webdav.delete('Cartridges/v1/old-file.zip');
+// Also supports: mkcol, exists, delete, unzip, request
 ```
 
 ### OCAPI Client
 
-The OCAPI client uses [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) with full TypeScript support:
-
 ```typescript
 // List sites
 const { data, error } = await instance.ocapi.GET('/sites', {

packages/b2c-cli/src/commands/docs/download.ts

@@ -5,7 +5,7 @@
  */
 import {Args, Flags} from '@oclif/core';
 import {InstanceCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import {downloadDocs, type DownloadDocsResult} from '@salesforce/b2c-tooling-sdk/operations/docs';
+import {downloadDocs, type DownloadDocsResult} from '@salesforce/b2c-tooling-sdk/docs';
 import {t} from '../../i18n/index.js';
 
 export default class DocsDownload extends InstanceCommand<typeof DocsDownload> {

packages/b2c-cli/src/commands/docs/read.ts

@@ -8,7 +8,7 @@ import {marked} from 'marked';
 
 import {markedTerminal} from 'marked-terminal';
 import {BaseCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import {readDocByQuery, type DocEntry} from '@salesforce/b2c-tooling-sdk/operations/docs';
+import {readDocByQuery, type DocEntry} from '@salesforce/b2c-tooling-sdk/docs';
 import {t} from '../../i18n/index.js';
 
 interface ReadDocsResult {

packages/b2c-cli/src/commands/docs/schema.ts

@@ -5,7 +5,7 @@
  */
 import {Args, Flags} from '@oclif/core';
 import {BaseCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import {readSchemaByQuery, listSchemas, type SchemaEntry} from '@salesforce/b2c-tooling-sdk/operations/docs';
+import {readSchemaByQuery, listSchemas, type SchemaEntry} from '@salesforce/b2c-tooling-sdk/docs';
 import {t} from '../../i18n/index.js';
 
 interface SchemaResult {

packages/b2c-cli/src/commands/docs/search.ts

@@ -5,7 +5,7 @@
  */
 import {Args, Flags, ux} from '@oclif/core';
 import {BaseCommand, createTable, type ColumnDef} from '@salesforce/b2c-tooling-sdk/cli';
-import {searchDocs, listDocs, type SearchResult, type DocEntry} from '@salesforce/b2c-tooling-sdk/operations/docs';
+import {searchDocs, listDocs, type SearchResult, type DocEntry} from '@salesforce/b2c-tooling-sdk/docs';
 import {t} from '../../i18n/index.js';
 
 interface SearchDocsResponse {

packages/b2c-cli/src/commands/scapi/schemas/get.ts

@@ -10,7 +10,7 @@ import {
   getSchemaNames,
   getExampleNames,
   type OpenApiSchemaInput,
-} from '@salesforce/b2c-tooling-sdk/operations/scapi-schemas';
+} from '@salesforce/b2c-tooling-sdk/schemas';
 import {ScapiSchemasCommand, formatApiError} from '../../../utils/scapi/schemas.js';
 import {t, withDocs} from '../../../i18n/index.js';
 

packages/b2c-tooling-sdk/package.json

@@ -57,17 +57,6 @@
         "default": "./dist/cjs/instance/index.js"
       }
     },
-    "./platform": {
-      "development": "./src/platform/index.ts",
-      "import": {
-        "types": "./dist/esm/platform/index.d.ts",
-        "default": "./dist/esm/platform/index.js"
-      },
-      "require": {
-        "types": "./dist/cjs/platform/index.d.ts",
-        "default": "./dist/cjs/platform/index.js"
-      }
-    },
     "./operations/code": {
       "development": "./src/operations/code/index.ts",
       "import": {
@@ -101,26 +90,26 @@
         "default": "./dist/cjs/operations/mrt/index.js"
       }
     },
-    "./operations/docs": {
-      "development": "./src/operations/docs/index.ts",
+    "./docs": {
+      "development": "./src/docs/index.ts",
       "import": {
-        "types": "./dist/esm/operations/docs/index.d.ts",
-        "default": "./dist/esm/operations/docs/index.js"
+        "types": "./dist/esm/docs/index.d.ts",
+        "default": "./dist/esm/docs/index.js"
       },
       "require": {
-        "types": "./dist/cjs/operations/docs/index.d.ts",
-        "default": "./dist/cjs/operations/docs/index.js"
+        "types": "./dist/cjs/docs/index.d.ts",
+        "default": "./dist/cjs/docs/index.js"
       }
     },
-    "./operations/scapi-schemas": {
-      "development": "./src/operations/scapi-schemas/index.ts",
+    "./schemas": {
+      "development": "./src/schemas/index.ts",
       "import": {
-        "types": "./dist/esm/operations/scapi-schemas/index.d.ts",
-        "default": "./dist/esm/operations/scapi-schemas/index.js"
+        "types": "./dist/esm/schemas/index.d.ts",
+        "default": "./dist/esm/schemas/index.js"
       },
       "require": {
-        "types": "./dist/cjs/operations/scapi-schemas/index.d.ts",
-        "default": "./dist/cjs/operations/scapi-schemas/index.js"
+        "types": "./dist/cjs/schemas/index.d.ts",
+        "default": "./dist/cjs/schemas/index.js"
       }
     },
     "./operations/logs": {

packages/b2c-tooling-sdk/src/cli/mrt-command.ts

@@ -9,8 +9,6 @@ import {loadConfig, extractMrtFlags} from './config.js';
 import type {LoadConfigOptions} from './config.js';
 import type {ResolvedB2CConfig} from '../config/index.js';
 import type {AuthStrategy} from '../auth/types.js';
-import {MrtClient} from '../platform/mrt.js';
-import type {MrtProject} from '../platform/mrt.js';
 import {t} from '../i18n/index.js';
 import {DEFAULT_MRT_ORIGIN} from '../clients/mrt.js';
 
@@ -108,13 +106,4 @@ export abstract class MrtCommand<T extends typeof Command> extends BaseCommand<T
       );
     }
   }
-
-  /**
-   * Creates an MRT client for the given project.
-   */
-  protected createMrtClient(project: MrtProject): MrtClient {
-    this.requireMrtCredentials();
-
-    return new MrtClient(project, this.getMrtAuth());
-  }
 }

packages/b2c-tooling-sdk/src/cli/oauth-command.ts

@@ -70,24 +70,6 @@ export abstract class OAuthCommand<T extends typeof Command> extends BaseCommand
     }),
   };
 
-  /**
-   * Parses auth methods from flags.
-   * Returns methods in the order specified (priority order).
-   * @deprecated Use extractOAuthFlags() instead which handles this internally
-   */
-  protected parseAuthMethods(): AuthMethod[] | undefined {
-    const flagValues = this.flags['auth-methods'] as string[] | undefined;
-    if (!flagValues || flagValues.length === 0) {
-      return undefined;
-    }
-
-    const methods = flagValues
-      .map((s) => s.trim())
-      .filter((s): s is AuthMethod => ALL_AUTH_METHODS.includes(s as AuthMethod));
-
-    return methods.length > 0 ? methods : undefined;
-  }
-
   protected override loadConfiguration(): ResolvedB2CConfig {
     return loadConfig(
       extractOAuthFlags(this.flags as Record<string, unknown>),