doc updates

Author: clavery

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

@@ -7,29 +7,45 @@
  * ## Available Clients
  *
  * - {@link WebDavClient} - File operations via WebDAV
- * - {@link OcapiClient} - Data API operations via OCAPI
+ * - {@link OcapiClient} - Data API operations via OCAPI (openapi-fetch Client)
  *
  * ## Usage
  *
- * Clients are typically accessed via {@link B2CInstance} rather than
- * instantiated directly:
+ * **Note:** These clients are typically accessed via {@link B2CInstance} rather than
+ * instantiated directly. The `B2CInstance` class handles authentication setup
+ * and provides convenient `webdav` and `ocapi` getters.
  *
  * ```typescript
- * const instance = B2CInstance.fromDwJson();
+ * import { B2CInstance } from '@salesforce/b2c-tooling';
  *
- * // WebDAV operations
+ * const instance = B2CInstance.fromDwJson({
+ *   clientSecret: process.env.SFCC_CLIENT_SECRET,
+ * });
+ *
+ * // WebDAV operations via instance.webdav
  * await instance.webdav.put('Cartridges/v1/app.zip', content);
  *
- * // OCAPI operations (openapi-fetch)
+ * // OCAPI operations via instance.ocapi (openapi-fetch)
  * const { data } = await instance.ocapi.GET('/sites', {});
  * ```
  *
+ * ## Direct Client Usage
+ *
+ * For advanced use cases, clients can be instantiated directly:
+ *
+ * ```typescript
+ * import { WebDavClient, createOcapiClient } from '@salesforce/b2c-tooling/clients';
+ *
+ * const webdav = new WebDavClient('sandbox.demandware.net', authStrategy);
+ * const ocapi = createOcapiClient('sandbox.demandware.net', authStrategy);
+ * ```
+ *
  * @module clients
  */
 export {WebDavClient} from './webdav.js';
 export type {PropfindEntry} from './webdav.js';
 
-export {createOcapiClient, createAuthMiddleware} from './ocapi.js';
+export {createOcapiClient, createAuthMiddleware, createLoggingMiddleware} from './ocapi.js';
 export type {
   OcapiClient,
   OcapiError,

packages/b2c-tooling/src/clients/ocapi.ts

@@ -19,7 +19,12 @@ const DEFAULT_API_VERSION = 'v25_6';
 export type {paths, components};
 
 /**
- * The typed OCAPI client - this is the actual openapi-fetch Client.
+ * The typed OCAPI client - this is the openapi-fetch Client with full type safety.
+ *
+ * **Note:** This client is typically accessed via {@link B2CInstance.ocapi} rather
+ * than created directly. The `B2CInstance` class handles authentication setup.
+ *
+ * @see {@link createOcapiClient} for direct instantiation
  */
 export type OcapiClient = Client<paths>;
 
@@ -129,12 +134,21 @@ export function createLoggingMiddleware(): Middleware {
  * handled via middleware. This gives full access to all openapi-fetch
  * features with type-safe paths, parameters, and responses.
  *
+ * **Note:** This client is typically accessed via {@link B2CInstance.ocapi} rather
+ * than created directly. The `B2CInstance` class handles authentication setup.
+ *
  * @param hostname - B2C instance hostname
- * @param auth - OAuth authentication strategy
+ * @param auth - Authentication strategy (typically OAuth)
  * @param apiVersion - API version (defaults to v25_6)
  * @returns Typed openapi-fetch client
  *
  * @example
+ * // Via B2CInstance (recommended)
+ * const instance = B2CInstance.fromDwJson();
+ * const { data, error } = await instance.ocapi.GET('/sites', {});
+ *
+ * @example
+ * // Direct instantiation (advanced)
  * const client = createOcapiClient('sandbox.demandware.net', authStrategy);
  *
  * // Fully typed GET request

packages/b2c-tooling/src/clients/webdav.ts

@@ -27,7 +27,17 @@ export interface PropfindEntry {
  * Handles WebDAV requests with proper authentication and provides
  * typed methods for common operations.
  *
+ * **Note:** This client is typically accessed via {@link B2CInstance.webdav} rather
+ * than instantiated directly. The `B2CInstance` class handles authentication setup.
+ *
+ * @example
+ * // Via B2CInstance (recommended)
+ * const instance = B2CInstance.fromDwJson();
+ * await instance.webdav.mkcol('Cartridges/v1');
+ * await instance.webdav.put('Cartridges/v1/app.zip', zipBuffer);
+ *
  * @example
+ * // Direct instantiation (advanced)
  * const client = new WebDavClient('sandbox.demandware.net', authStrategy);
  * await client.mkcol('Cartridges/v1');
  * await client.put('Cartridges/v1/app_storefront/cartridge.zip', zipBuffer);

typedoc.json

@@ -2,6 +2,7 @@
   "$schema": "https://typedoc.org/schema.json",
   "entryPoints": [
     "./packages/b2c-tooling/src/auth/index.ts",
+    "./packages/b2c-tooling/src/clients/index.ts",
     "./packages/b2c-tooling/src/instance/index.ts",
     "./packages/b2c-tooling/src/platform/index.ts",
     "./packages/b2c-tooling/src/operations/code/index.ts",