Skip to content

Commit d79bb00

Browse files
claveryclavery
committed
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.
1 parent 4ad0673 commit d79bb00

File tree

10 files changed

+248
-9
lines changed

10 files changed

+248
-9
lines changed

‎docs/.vitepress/config.mts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ export default defineConfig({
5252
description: 'Salesforce Commerce Cloud B2C Developer Experience - CLI, MCP Server, and SDK',
5353
base: '/b2c-developer-tooling/',
5454

55+
// Ignore dead links in api-readme.md (links are valid after TypeDoc generates the API docs)
56+
ignoreDeadLinks: [/^\.\/clients\//],
57+
5558
// Show deeper heading levels in the outline
5659
markdown: {
5760
toc: { level: [2, 3, 4] },

‎docs/api-readme.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,6 @@ import { createSlasClient, OAuthStrategy } from '@salesforce/b2c-tooling-sdk';
7777
const auth = new OAuthStrategy({
7878
clientId: 'your-client-id',
7979
clientSecret: 'your-client-secret',
80-
scopes: ['SLAS_ORGANIZATION_ADMIN'],
8180
});
8281

8382
const slasClient = createSlasClient({ shortCode: 'kv7kzm78' }, auth);
@@ -181,6 +180,31 @@ When both are configured, WebDAV uses Basic auth and OCAPI uses OAuth.
181180

182181
## Typed Clients
183182

183+
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.
184+
185+
### Instance Clients
186+
187+
These clients are accessed via `B2CInstance` for operations on a specific B2C Commerce instance:
188+
189+
| Client | Description | API Reference |
190+
|--------|-------------|---------------|
191+
| [WebDavClient](./clients/classes/WebDavClient.md) | File operations (upload, download, list) | WebDAV |
192+
| [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) |
193+
194+
### Platform Service Clients
195+
196+
These clients are created directly for platform-wide services:
197+
198+
| Client | Description | API Reference |
199+
|--------|-------------|---------------|
200+
| [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) |
201+
| [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) |
202+
| [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) |
203+
| [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) |
204+
| [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) |
205+
| [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) |
206+
| [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) |
207+
184208
### WebDAV Client
185209

186210
```typescript
@@ -198,8 +222,6 @@ const content = await instance.webdav.get('Cartridges/v1/app.zip');
198222

199223
### OCAPI Client
200224

201-
The OCAPI client uses [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) with full TypeScript support:
202-
203225
```typescript
204226
// List sites
205227
const { data, error } = await instance.ocapi.GET('/sites', {

‎packages/b2c-tooling-sdk/src/clients/cdn-zones.ts‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,41 @@ export type {paths, components};
3232
export {toOrganizationId, toTenantId, buildTenantScope};
3333

3434
/**
35-
* The typed CDN Zones client - this is the openapi-fetch Client with full type safety.
35+
* The typed CDN Zones client for eCDN management.
36+
*
37+
* ## Common Endpoints
38+
*
39+
* | Method | Path | Description |
40+
* |--------|------|-------------|
41+
* | GET | `/organizations/{organizationId}/zones/info` | List all zones |
42+
* | GET | `/organizations/{organizationId}/zones/{zoneId}/certificates` | Get zone certificates |
43+
* | POST | `/organizations/{organizationId}/zones/{zoneId}/cachepurge` | Purge cache |
44+
* | GET | `/organizations/{organizationId}/zones/{zoneId}/firewall/waf` | Get WAF settings |
45+
* | GET | `/organizations/{organizationId}/zones/{zoneId}/speed` | Get speed settings |
46+
*
47+
* @example
48+
* ```typescript
49+
* import { createCdnZonesClient, toOrganizationId } from '@salesforce/b2c-tooling-sdk/clients';
50+
* import { OAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
51+
*
52+
* const auth = new OAuthStrategy({
53+
* clientId: 'your-client-id',
54+
* clientSecret: 'your-client-secret',
55+
* });
56+
*
57+
* const client = createCdnZonesClient(
58+
* { shortCode: 'kv7kzm78', tenantId: 'zzxy_prd' },
59+
* auth
60+
* );
61+
*
62+
* // List all zones
63+
* const { data, error } = await client.GET('/organizations/{organizationId}/zones/info', {
64+
* params: { path: { organizationId: toOrganizationId('zzxy_prd') } }
65+
* });
66+
* ```
3667
*
3768
* @see {@link createCdnZonesClient} for instantiation
69+
* @see {@link https://developer.salesforce.com/docs/commerce/commerce-api/references/cdn-api-process-apis?meta=Summary | CDN Zones API Reference}
3870
*/
3971
export type CdnZonesClient = Client<paths>;
4072

‎packages/b2c-tooling-sdk/src/clients/custom-apis.ts‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,38 @@ import {globalMiddlewareRegistry, type MiddlewareRegistry} from './middleware-re
2525
export type {paths, components};
2626

2727
/**
28-
* The typed Custom APIs client - this is the openapi-fetch Client with full type safety.
28+
* The typed Custom APIs client for Custom SCAPI endpoint management.
29+
*
30+
* ## Common Endpoints
31+
*
32+
* | Method | Path | Description |
33+
* |--------|------|-------------|
34+
* | GET | `/organizations/{organizationId}/endpoints` | List all custom API endpoints |
35+
* | GET | `/organizations/{organizationId}/endpoints/{apiName}` | Get specific API info |
36+
*
37+
* @example
38+
* ```typescript
39+
* import { createCustomApisClient, toOrganizationId } from '@salesforce/b2c-tooling-sdk/clients';
40+
* import { OAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
41+
*
42+
* const auth = new OAuthStrategy({
43+
* clientId: 'your-client-id',
44+
* clientSecret: 'your-client-secret',
45+
* });
46+
*
47+
* const client = createCustomApisClient(
48+
* { shortCode: 'kv7kzm78', tenantId: 'zzxy_prd' },
49+
* auth
50+
* );
51+
*
52+
* // List all custom API endpoints
53+
* const { data, error } = await client.GET('/organizations/{organizationId}/endpoints', {
54+
* params: { path: { organizationId: toOrganizationId('zzxy_prd') } }
55+
* });
56+
* ```
2957
*
3058
* @see {@link createCustomApisClient} for instantiation
59+
* @see {@link https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=Summary | Custom APIs Reference}
3160
*/
3261
export type CustomApisClient = Client<paths>;
3362

‎packages/b2c-tooling-sdk/src/clients/mrt-b2c.ts‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,33 @@ import {globalMiddlewareRegistry, type MiddlewareRegistry} from './middleware-re
2323
export type {paths, components};
2424

2525
/**
26-
* The typed MRT B2C client - openapi-fetch Client with full type safety.
26+
* The typed MRT B2C client for B2C Commerce integration with Managed Runtime.
27+
*
28+
* ## Common Endpoints
29+
*
30+
* | Method | Path | Description |
31+
* |--------|------|-------------|
32+
* | GET | `/b2c-organization-info/{organization_slug}/` | Get B2C org info |
33+
* | GET | `/projects/{project_slug}/b2c-target-info/{target_slug}/` | Get B2C target info |
34+
* | PUT | `/projects/{project_slug}/b2c-target-info/{target_slug}/` | Update B2C target |
35+
* | PATCH | `/projects/{project_slug}/b2c-target-info/{target_slug}/` | Partial update target |
36+
*
37+
* @example
38+
* ```typescript
39+
* import { createMrtB2CClient } from '@salesforce/b2c-tooling-sdk/clients';
40+
* import { ApiKeyStrategy } from '@salesforce/b2c-tooling-sdk/auth';
41+
*
42+
* const auth = new ApiKeyStrategy(apiKey, 'Authorization');
43+
* const client = createMrtB2CClient({}, auth);
44+
*
45+
* // Get B2C target info
46+
* const { data, error } = await client.GET('/projects/{project_slug}/b2c-target-info/{target_slug}/', {
47+
* params: { path: { project_slug: 'my-project', target_slug: 'staging' } }
48+
* });
49+
* ```
2750
*
2851
* @see {@link createMrtB2CClient} for instantiation
52+
* @see {@link https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=Summary | MRT B2C Config API Reference}
2953
*/
3054
export type MrtB2CClient = Client<paths>;
3155

‎packages/b2c-tooling-sdk/src/clients/mrt.ts‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,32 @@ import {globalMiddlewareRegistry, type MiddlewareRegistry} from './middleware-re
2424
export type {paths, components};
2525

2626
/**
27-
* The typed MRT client - this is the openapi-fetch Client with full type safety.
27+
* The typed MRT client for Managed Runtime operations.
28+
*
29+
* ## Common Endpoints
30+
*
31+
* | Method | Path | Description |
32+
* |--------|------|-------------|
33+
* | GET | `/api/projects/` | List all projects |
34+
* | GET | `/api/projects/{projectSlug}/` | Get project details |
35+
* | POST | `/api/projects/{projectSlug}/builds/` | Push a bundle |
36+
* | GET | `/api/projects/{projectSlug}/target/{targetId}/` | Get target/environment |
37+
* | POST | `/api/projects/{projectSlug}/target/{targetId}/deploy/` | Deploy to target |
38+
*
39+
* @example
40+
* ```typescript
41+
* import { createMrtClient } from '@salesforce/b2c-tooling-sdk/clients';
42+
* import { ApiKeyStrategy } from '@salesforce/b2c-tooling-sdk/auth';
43+
*
44+
* const auth = new ApiKeyStrategy(apiKey, 'Authorization');
45+
* const client = createMrtClient({}, auth);
46+
*
47+
* // List all projects
48+
* const { data, error } = await client.GET('/api/projects/', {});
49+
* ```
2850
*
2951
* @see {@link createMrtClient} for instantiation
52+
* @see {@link https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary | MRT Admin API Reference}
3053
*/
3154
export type MrtClient = Client<paths>;
3255

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,29 @@ export type {paths, components};
3030
* **Note:** This client is typically accessed via `B2CInstance.ocapi` rather
3131
* than created directly. The `B2CInstance` class handles authentication setup.
3232
*
33+
* ## Common Endpoints
34+
*
35+
* | Method | Path | Description |
36+
* |--------|------|-------------|
37+
* | GET | `/sites` | List all sites |
38+
* | GET | `/code_versions` | List code versions |
39+
* | PATCH | `/code_versions/{code_version_id}` | Activate a code version |
40+
* | GET | `/jobs/{job_id}/executions` | Get job execution history |
41+
* | POST | `/jobs/{job_id}/executions` | Start a job execution |
42+
*
43+
* @example
44+
* ```typescript
45+
* import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
46+
*
47+
* const config = resolveConfig();
48+
* const instance = config.createB2CInstance();
49+
*
50+
* // List all sites
51+
* const { data, error } = await instance.ocapi.GET('/sites', {});
52+
* ```
53+
*
3354
* @see {@link createOcapiClient} for direct instantiation
55+
* @see {@link https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/b2c-api-doc.html | OCAPI Data API Reference}
3456
*/
3557
export type OcapiClient = Client<paths>;
3658

‎packages/b2c-tooling-sdk/src/clients/ods.ts‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,36 @@ const DEFAULT_ODS_HOST = 'admin.dx.commercecloud.salesforce.com';
3131
export type {paths, components};
3232

3333
/**
34-
* The typed ODS client - this is the openapi-fetch Client with full type safety.
34+
* The typed ODS client for On-Demand Sandbox management.
35+
*
36+
* ## Common Endpoints
37+
*
38+
* | Method | Path | Description |
39+
* |--------|------|-------------|
40+
* | GET | `/sandboxes` | List all sandboxes |
41+
* | POST | `/sandboxes` | Create a new sandbox |
42+
* | GET | `/sandboxes/{sandboxId}` | Get sandbox details |
43+
* | DELETE | `/sandboxes/{sandboxId}` | Delete a sandbox |
44+
* | POST | `/sandboxes/{sandboxId}/operations` | Start/stop a sandbox |
45+
*
46+
* @example
47+
* ```typescript
48+
* import { createOdsClient } from '@salesforce/b2c-tooling-sdk/clients';
49+
* import { OAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
50+
*
51+
* const auth = new OAuthStrategy({
52+
* clientId: 'your-client-id',
53+
* clientSecret: 'your-client-secret',
54+
* });
55+
*
56+
* const client = createOdsClient({}, auth);
57+
*
58+
* // List all sandboxes
59+
* const { data, error } = await client.GET('/sandboxes', {});
60+
* ```
3561
*
3662
* @see {@link createOdsClient} for instantiation
63+
* @see {@link https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ods-rest-api?meta=Summary | ODS REST API Reference}
3764
*/
3865
export type OdsClient = Client<paths>;
3966

‎packages/b2c-tooling-sdk/src/clients/scapi-schemas.ts‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,38 @@ export type {paths, components};
3131
export {toOrganizationId, toTenantId, buildTenantScope};
3232

3333
/**
34-
* The typed SCAPI Schemas client - this is the openapi-fetch Client with full type safety.
34+
* The typed SCAPI Schemas client for discovering available SCAPI APIs.
35+
*
36+
* ## Common Endpoints
37+
*
38+
* | Method | Path | Description |
39+
* |--------|------|-------------|
40+
* | GET | `/organizations/{organizationId}/schemas` | List available schemas |
41+
* | GET | `/organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}` | Get specific schema |
42+
*
43+
* @example
44+
* ```typescript
45+
* import { createScapiSchemasClient, toOrganizationId } from '@salesforce/b2c-tooling-sdk/clients';
46+
* import { OAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
47+
*
48+
* const auth = new OAuthStrategy({
49+
* clientId: 'your-client-id',
50+
* clientSecret: 'your-client-secret',
51+
* });
52+
*
53+
* const client = createScapiSchemasClient(
54+
* { shortCode: 'kv7kzm78', tenantId: 'zzxy_prd' },
55+
* auth
56+
* );
57+
*
58+
* // List all available SCAPI schemas
59+
* const { data, error } = await client.GET('/organizations/{organizationId}/schemas', {
60+
* params: { path: { organizationId: toOrganizationId('zzxy_prd') } }
61+
* });
62+
* ```
3563
*
3664
* @see {@link createScapiSchemasClient} for instantiation
65+
* @see {@link https://developer.salesforce.com/docs/commerce/commerce-api/references/scapi-schemas?meta=Summary | SCAPI Schemas API Reference}
3766
*/
3867
export type ScapiSchemasClient = Client<paths>;
3968

‎packages/b2c-tooling-sdk/src/clients/slas-admin.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,35 @@ export type {paths, components};
2626
/**
2727
* The typed SLAS client - this is the openapi-fetch Client with full type safety.
2828
*
29+
* ## Common Endpoints
30+
*
31+
* | Method | Path | Description |
32+
* |--------|------|-------------|
33+
* | GET | `/tenants/{tenantId}` | Get tenant info |
34+
* | GET | `/tenants/{tenantId}/clients` | List SLAS clients |
35+
* | PUT | `/tenants/{tenantId}/clients/{clientId}` | Create/update a client |
36+
* | DELETE | `/tenants/{tenantId}/clients/{clientId}` | Delete a client |
37+
*
38+
* @example
39+
* ```typescript
40+
* import { createSlasClient } from '@salesforce/b2c-tooling-sdk/clients';
41+
* import { OAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
42+
*
43+
* const auth = new OAuthStrategy({
44+
* clientId: 'your-client-id',
45+
* clientSecret: 'your-client-secret',
46+
* });
47+
*
48+
* const client = createSlasClient({ shortCode: 'kv7kzm78' }, auth);
49+
*
50+
* // List all SLAS clients for a tenant
51+
* const { data, error } = await client.GET('/tenants/{tenantId}/clients', {
52+
* params: { path: { tenantId: 'your-tenant' } }
53+
* });
54+
* ```
55+
*
2956
* @see {@link createSlasClient} for instantiation
57+
* @see {@link https://developer.salesforce.com/docs/commerce/commerce-api/references/slas-admin?meta=Summary | SLAS Admin API Reference}
3058
*/
3159
export type SlasClient = Client<paths>;
3260

0 commit comments

Comments
 (0)