Skip to content

Commit 9ec97dc

Browse files
claveryclavery
committed
doc updates; common plugins
1 parent eabfb95 commit 9ec97dc

File tree

6 files changed

+178
-24
lines changed

6 files changed

+178
-24
lines changed

‎docs/api-readme.md‎

Lines changed: 140 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,146 @@ npm install @salesforce/b2c-tooling
1010

1111
## Quick Start
1212

13+
### From dw.json (Recommended)
14+
15+
The easiest way to create an instance is from a `dw.json` file:
16+
17+
```typescript
18+
import { B2CInstance } from '@salesforce/b2c-tooling';
19+
20+
// Load configuration from dw.json, override secrets from environment
21+
const instance = B2CInstance.fromDwJson({
22+
clientId: process.env.SFCC_CLIENT_ID,
23+
clientSecret: process.env.SFCC_CLIENT_SECRET,
24+
});
25+
26+
// Use typed WebDAV client
27+
await instance.webdav.mkcol('Cartridges/v1');
28+
await instance.webdav.put('Cartridges/v1/app.zip', zipBuffer);
29+
30+
// Use typed OCAPI client (openapi-fetch)
31+
const { data, error } = await instance.ocapi.GET('/sites', {
32+
params: { query: { select: '(**)' } },
33+
});
34+
```
35+
36+
### Direct Construction
37+
38+
You can also construct an instance directly with configuration:
39+
40+
```typescript
41+
import { B2CInstance } from '@salesforce/b2c-tooling';
42+
43+
const instance = new B2CInstance(
44+
{ hostname: 'your-sandbox.demandware.net', codeVersion: 'v1' },
45+
{
46+
oauth: {
47+
clientId: 'your-client-id',
48+
clientSecret: 'your-client-secret'
49+
}
50+
}
51+
);
52+
```
53+
54+
## Authentication
55+
56+
B2CInstance supports multiple authentication methods:
57+
58+
### OAuth (Client Credentials)
59+
60+
Used for OCAPI and can be used for WebDAV:
61+
62+
```typescript
63+
const instance = new B2CInstance(
64+
{ hostname: 'sandbox.demandware.net' },
65+
{
66+
oauth: {
67+
clientId: 'your-client-id',
68+
clientSecret: 'your-client-secret',
69+
scopes: ['SALESFORCE_COMMERCE_API:...:dwsid'],
70+
}
71+
}
72+
);
73+
```
74+
75+
### Basic Auth
76+
77+
Used for WebDAV operations (Business Manager credentials):
78+
79+
```typescript
80+
const instance = new B2CInstance(
81+
{ hostname: 'sandbox.demandware.net' },
82+
{
83+
basic: {
84+
username: 'admin',
85+
password: 'your-access-key'
86+
},
87+
oauth: {
88+
clientId: 'your-client-id',
89+
clientSecret: 'your-client-secret',
90+
}
91+
}
92+
);
93+
```
94+
95+
When both are configured, WebDAV uses Basic auth and OCAPI uses OAuth.
96+
97+
## Typed Clients
98+
99+
### WebDAV Client
100+
101+
```typescript
102+
// Create directories
103+
await instance.webdav.mkcol('Cartridges/v1');
104+
105+
// Upload files
106+
await instance.webdav.put('Cartridges/v1/app.zip', buffer, 'application/zip');
107+
108+
// Download files
109+
const content = await instance.webdav.get('Cartridges/v1/app.zip');
110+
111+
// List directory
112+
const entries = await instance.webdav.propfind('Cartridges');
113+
114+
// Check existence
115+
const exists = await instance.webdav.exists('Cartridges/v1');
116+
117+
// Delete
118+
await instance.webdav.delete('Cartridges/v1/old-file.zip');
119+
```
120+
121+
### OCAPI Client
122+
123+
The OCAPI client uses [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) with full TypeScript support:
124+
13125
```typescript
14-
import { B2CInstance } from '@salesforce/b2c-tooling/instance';
15-
import { OAuthStrategy } from '@salesforce/b2c-tooling/auth';
16-
17-
const instance = new B2CInstance({
18-
hostname: 'your-instance.salesforce.com',
19-
auth: new OAuthStrategy({
20-
clientId: 'your-client-id',
21-
clientSecret: 'your-client-secret',
22-
}),
126+
// List sites
127+
const { data, error } = await instance.ocapi.GET('/sites', {
128+
params: { query: { select: '(**)' } },
129+
});
130+
131+
// Get a specific site
132+
const { data, error } = await instance.ocapi.GET('/sites/{site_id}', {
133+
params: { path: { site_id: 'RefArch' } },
23134
});
135+
136+
// Activate a code version
137+
const { data, error } = await instance.ocapi.PATCH('/code_versions/{code_version_id}', {
138+
params: { path: { code_version_id: 'v1' } },
139+
body: { active: true },
140+
});
141+
```
142+
143+
## Logging
144+
145+
Configure logging for debugging HTTP requests:
146+
147+
```typescript
148+
import { configureLogger } from '@salesforce/b2c-tooling/logging';
149+
150+
// Enable debug logging (shows HTTP request summaries)
151+
configureLogger({ level: 'debug' });
152+
153+
// Enable trace logging (shows full request/response with headers and bodies)
154+
configureLogger({ level: 'trace' });
24155
```

‎packages/b2c-cli/package.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
"@oclif/core": "^4",
1212
"@oclif/plugin-help": "^6",
1313
"@oclif/plugin-plugins": "^5",
14+
"@oclif/plugin-not-found": "^3",
15+
"@oclif/plugin-autocomplete": "^3",
1416
"@salesforce/b2c-tooling": "workspace:*",
1517
"cliui": "^9.0.1"
1618
},
@@ -59,7 +61,9 @@
5961
"commands": "./dist/commands",
6062
"plugins": [
6163
"@oclif/plugin-help",
62-
"@oclif/plugin-plugins"
64+
"@oclif/plugin-plugins",
65+
"@oclif/plugin-not-found",
66+
"@oclif/plugin-autocomplete"
6367
],
6468
"topicSeparator": " ",
6569
"topics": {

‎packages/b2c-tooling/src/cli/instance-command.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ import {t} from '../i18n/index.js';
2828
* export default class MySiteCommand extends InstanceCommand<typeof MySiteCommand> {
2929
* async run(): Promise<void> {
3030
* // Single instance for all operations
31-
* const sites = await this.instance.ocapi.get('sites');
31+
* const { data } = await this.instance.ocapi.GET('/sites', {});
3232
* await this.instance.webdav.mkcol('Cartridges/v1');
3333
* }
3434
* }
@@ -99,7 +99,7 @@ export abstract class InstanceCommand<T extends typeof Command> extends OAuthCom
9999
* await this.instance.webdav.mkcol('Cartridges/v1');
100100
*
101101
* // OCAPI operations (uses OAuth)
102-
* const sites = await this.instance.ocapi.get('sites');
102+
* const { data } = await this.instance.ocapi.GET('/sites', {});
103103
*/
104104
protected get instance(): B2CInstance {
105105
if (!this._instance) {

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@
2020
* // WebDAV operations
2121
* await instance.webdav.put('Cartridges/v1/app.zip', content);
2222
*
23-
* // OCAPI operations
24-
* const sites = await instance.ocapi.get('sites');
23+
* // OCAPI operations (openapi-fetch)
24+
* const { data } = await instance.ocapi.GET('/sites', {});
2525
* ```
2626
*
2727
* @module clients

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
*
2121
* // Use typed clients
2222
* await instance.webdav.put('Cartridges/v1/app.zip', content);
23-
* const sites = await instance.ocapi.get('sites');
23+
* const { data } = await instance.ocapi.GET('/sites', {});
2424
* ```
2525
*
2626
* ### Direct construction
@@ -97,7 +97,7 @@ export interface FromDwJsonOptions {
9797
* await instance.webdav.mkcol('Cartridges/v1');
9898
*
9999
* // OCAPI always uses OAuth
100-
* const sites = await instance.ocapi.get('sites');
100+
* const { data } = await instance.ocapi.GET('/sites', {});
101101
*/
102102
export class B2CInstance {
103103
private _webdav?: WebDavClient;

‎pnpm-lock.yaml‎

Lines changed: 27 additions & 8 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)