Skip to content

Commit 8a1a9ef

Browse files
claveryclavery
authored
Remove B2CInstance.fromEnvironment() in favor of resolveConfig() (#37)
The fromEnvironment() method had no runtime usages - only documentation examples. This change: - Removes FromEnvironmentOptions interface and fromEnvironment() static method - Updates all JSDoc examples to use resolveConfig() pattern - Restructures docs/api-readme.md to document the unified config system - Adds Configuration Resolution section covering multi-source loading, validation helpers, warnings, and hostname protection
1 parent ef0e152 commit 8a1a9ef

File tree

9 files changed

+139
-168
lines changed

9 files changed

+139
-168
lines changed

‎docs/api-readme.md‎

Lines changed: 98 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,27 @@ npm install @salesforce/b2c-tooling-sdk
1010

1111
## Quick Start
1212

13-
### From Environment Configuration (Recommended)
13+
### From Configuration (Recommended)
1414

15-
The easiest way to create an instance is from environment configuration files:
15+
Use `resolveConfig()` to load configuration from project files (dw.json) and create a B2C instance:
1616

1717
```typescript
18-
import { B2CInstance } from '@salesforce/b2c-tooling-sdk';
18+
import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
1919

20-
// Load configuration from environment files (dw.json, etc.), override secrets from environment
21-
const instance = B2CInstance.fromEnvironment({
20+
// Load configuration, override secrets from environment
21+
const config = resolveConfig({
2222
clientId: process.env.SFCC_CLIENT_ID,
2323
clientSecret: process.env.SFCC_CLIENT_SECRET,
2424
});
2525

26+
// Validate configuration before use
27+
if (!config.hasB2CInstanceConfig()) {
28+
throw new Error('Missing B2C instance configuration');
29+
}
30+
31+
// Create instance from validated config
32+
const instance = config.createB2CInstance();
33+
2634
// Use typed WebDAV client
2735
await instance.webdav.mkcol('Cartridges/v1');
2836
await instance.webdav.put('Cartridges/v1/app.zip', zipBuffer);
@@ -31,11 +39,16 @@ await instance.webdav.put('Cartridges/v1/app.zip', zipBuffer);
3139
const { data, error } = await instance.ocapi.GET('/sites', {
3240
params: { query: { select: '(**)' } },
3341
});
42+
43+
// Check for configuration warnings
44+
for (const warning of config.warnings) {
45+
console.warn(warning.message);
46+
}
3447
```
3548

3649
### Direct Construction
3750

38-
You can also construct an instance directly with configuration:
51+
For advanced use cases, you can construct a B2CInstance directly:
3952

4053
```typescript
4154
import { B2CInstance } from '@salesforce/b2c-tooling-sdk';
@@ -51,6 +64,70 @@ const instance = new B2CInstance(
5164
);
5265
```
5366

67+
## Configuration Resolution
68+
69+
The `resolveConfig()` function provides a robust configuration system with multi-source loading and validation.
70+
71+
### Multi-Source Loading
72+
73+
Configuration is loaded from multiple sources with the following priority (highest to lowest):
74+
75+
1. **Explicit overrides** - Values passed to `resolveConfig()`
76+
2. **dw.json** - Project configuration file (searched upward from cwd)
77+
3. **~/.mobify** - Home directory file for MRT API key
78+
79+
```typescript
80+
import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
81+
82+
// Override specific values, rest loaded from dw.json
83+
const config = resolveConfig({
84+
hostname: process.env.SFCC_SERVER, // Override hostname
85+
clientId: process.env.SFCC_CLIENT_ID, // Override from env
86+
clientSecret: process.env.SFCC_CLIENT_SECRET,
87+
});
88+
```
89+
90+
### Validation Helpers
91+
92+
The resolved config provides methods to check what configuration is available:
93+
94+
```typescript
95+
const config = resolveConfig();
96+
97+
// Check for B2C instance configuration
98+
if (config.hasB2CInstanceConfig()) {
99+
const instance = config.createB2CInstance();
100+
}
101+
102+
// Check for MRT configuration
103+
if (config.hasMrtConfig()) {
104+
const mrtClient = config.createMrtClient({ project: 'my-project' });
105+
}
106+
107+
// Other validation methods
108+
config.hasOAuthConfig(); // OAuth credentials available?
109+
config.hasBasicAuthConfig(); // Basic auth credentials available?
110+
```
111+
112+
### Configuration Warnings
113+
114+
The config system detects potential issues and provides warnings:
115+
116+
```typescript
117+
const config = resolveConfig({
118+
hostname: 'staging.demandware.net', // Different from dw.json
119+
});
120+
121+
// Check warnings
122+
for (const warning of config.warnings) {
123+
console.warn(`[${warning.code}] ${warning.message}`);
124+
}
125+
```
126+
127+
### Hostname Protection
128+
129+
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.
130+
54131
## Authentication
55132

56133
B2CInstance supports multiple authentication methods:
@@ -60,36 +137,28 @@ B2CInstance supports multiple authentication methods:
60137
Used for OCAPI and can be used for WebDAV:
61138

62139
```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-
);
140+
const config = resolveConfig({
141+
clientId: 'your-client-id',
142+
clientSecret: 'your-client-secret',
143+
scopes: ['SALESFORCE_COMMERCE_API:...:dwsid'],
144+
});
145+
146+
const instance = config.createB2CInstance();
73147
```
74148

75149
### Basic Auth
76150

77151
Used for WebDAV operations (Business Manager credentials):
78152

79153
```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-
);
154+
const config = resolveConfig({
155+
username: 'admin',
156+
password: 'your-access-key',
157+
clientId: 'your-client-id', // Still needed for OCAPI
158+
clientSecret: 'your-client-secret',
159+
});
160+
161+
const instance = config.createB2CInstance();
93162
```
94163

95164
When both are configured, WebDAV uses Basic auth and OCAPI uses OAuth.

‎packages/b2c-tooling-sdk/README.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,22 @@ npm install @salesforce/b2c-tooling-sdk
1515

1616
## Quick Start
1717

18-
### From Environment Configuration (Recommended)
18+
### From Configuration (Recommended)
1919

20-
The easiest way to create an instance is from environment configuration files:
20+
Use `resolveConfig()` to load configuration from project files (dw.json) and create a B2C instance:
2121

2222
```typescript
23-
import { B2CInstance } from '@salesforce/b2c-tooling-sdk';
23+
import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
2424

25-
// Load configuration from environment files (dw.json, etc.), override secrets from environment
26-
const instance = B2CInstance.fromEnvironment({
25+
// Load configuration, override secrets from environment
26+
const config = resolveConfig({
2727
clientId: process.env.SFCC_CLIENT_ID,
2828
clientSecret: process.env.SFCC_CLIENT_SECRET,
2929
});
3030

31+
// Create instance from validated config
32+
const instance = config.createB2CInstance();
33+
3134
// Use typed WebDAV client
3235
await instance.webdav.mkcol('Cartridges/v1');
3336
await instance.webdav.put('Cartridges/v1/app.zip', zipBuffer);
@@ -40,7 +43,7 @@ const { data, error } = await instance.ocapi.GET('/sites', {
4043

4144
### Direct Construction
4245

43-
You can also construct an instance directly with configuration:
46+
For advanced use cases, you can construct a B2CInstance directly:
4447

4548
```typescript
4649
import { B2CInstance } from '@salesforce/b2c-tooling-sdk';
@@ -129,6 +132,7 @@ The SDK provides subpath exports for tree-shaking and organization:
129132
| Export | Description |
130133
|--------|-------------|
131134
| `@salesforce/b2c-tooling-sdk` | Main entry point with all exports |
135+
| `@salesforce/b2c-tooling-sdk/config` | Configuration resolution (resolveConfig) |
132136
| `@salesforce/b2c-tooling-sdk/auth` | Authentication strategies (OAuth, Basic, API Key) |
133137
| `@salesforce/b2c-tooling-sdk/instance` | B2CInstance class |
134138
| `@salesforce/b2c-tooling-sdk/clients` | Low-level API clients (WebDAV, OCAPI, SLAS, ODS, MRT) |

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,13 @@
2424
* and provides convenient `webdav` and `ocapi` getters.
2525
*
2626
* ```typescript
27-
* import { B2CInstance } from '@salesforce/b2c-tooling-sdk';
27+
* import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
2828
*
29-
* const instance = B2CInstance.fromEnvironment({
29+
* const config = resolveConfig({
30+
* clientId: process.env.SFCC_CLIENT_ID,
3031
* clientSecret: process.env.SFCC_CLIENT_SECRET,
3132
* });
33+
* const instance = config.createB2CInstance();
3234
*
3335
* // WebDAV operations via instance.webdav
3436
* await instance.webdav.put('Cartridges/v1/app.zip', content);

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,9 @@ export interface OcapiClientOptions {
9191
*
9292
* @example
9393
* // Via B2CInstance (recommended)
94-
* const instance = B2CInstance.fromEnvironment();
94+
* import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
95+
* const config = resolveConfig();
96+
* const instance = config.createB2CInstance();
9597
* const { data, error } = await instance.ocapi.GET('/sites', {});
9698
*
9799
* @example

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,9 @@ export interface PropfindEntry {
4040
*
4141
* @example
4242
* // Via B2CInstance (recommended)
43-
* const instance = B2CInstance.fromEnvironment();
43+
* import { resolveConfig } from '@salesforce/b2c-tooling-sdk/config';
44+
* const config = resolveConfig();
45+
* const instance = config.createB2CInstance();
4446
* await instance.webdav.mkcol('Cartridges/v1');
4547
* await instance.webdav.put('Cartridges/v1/app.zip', zipBuffer);
4648
*

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ export type {
6060

6161
// Context Layer - Instance
6262
export {B2CInstance} from './instance/index.js';
63-
export type {InstanceConfig, FromEnvironmentOptions, B2CInstanceOptions} from './instance/index.js';
63+
export type {InstanceConfig} from './instance/index.js';
6464

6565
// Clients
6666
export {

0 commit comments

Comments
 (0)