Skip to content

Commit 62b6acb

Browse files
claveryclavery
authored
@W-20783316 Add SCAPI Schemas commands for browsing and retrieving API specifications (#49)
* Add SCAPI Schemas commands for browsing and retrieving API specifications Introduces new CLI commands to interact with the SCAPI Schemas API: - `scapi schemas list` - List available SCAPI schemas with filtering by apiFamily, apiName, apiVersion, and status - `scapi schemas get` - Get a specific schema with selective expansion support for context-efficient output (ideal for agentic/LLM use cases) Key features: - Schema collapsing by default (paths show methods, schemas show names only) - Selective expansion via --expand-paths, --expand-schemas, --expand-examples - List available items via --list-paths, --list-schemas, --list-examples - YAML output support via --yaml flag - Custom properties expansion (enabled by default) SDK additions: - OpenAPI spec and generated types for SCAPI Schemas API - createScapiSchemasClient() factory with OAuth scope sfcc.scapi-schemas - collapseOpenApiSchema() utility for three-tier disclosure model - Helper functions: getPathKeys, getSchemaNames, getExampleNames Also includes documentation page and b2c-cli skill for the new commands. * Fix lint errors and test assertion - Reorder class members per perfectionist rules - Fix union type ordering (null before string[]) - Remove unnecessary length check in Array.some() - Fix test assertion to use lowercase 'apiFamily'
1 parent a45bcc7 commit 62b6acb

19 files changed

Lines changed: 2792 additions & 2 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ const guideSidebar = [
3737
{ text: 'MRT Commands', link: '/cli/mrt' },
3838
{ text: 'SLAS Commands', link: '/cli/slas' },
3939
{ text: 'Custom APIs', link: '/cli/custom-apis' },
40+
{ text: 'SCAPI Schemas', link: '/cli/scapi-schemas' },
4041
{ text: 'Auth Commands', link: '/cli/auth' },
4142
{ text: 'Logging', link: '/cli/logging' },
4243
],

‎docs/cli/scapi-schemas.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# SCAPI Schemas
2+
3+
Commands for browsing and retrieving SCAPI (Salesforce Commerce API) schema specifications.
4+
5+
## Global SCAPI Schemas Flags
6+
7+
These flags are available on all SCAPI Schemas commands:
8+
9+
| Flag | Environment Variable | Description |
10+
|------|---------------------|-------------|
11+
| `--tenant-id` | `SFCC_TENANT_ID` | (Required) Organization/tenant ID |
12+
| `--short-code` | `SFCC_SHORTCODE` | SCAPI short code |
13+
14+
## Authentication
15+
16+
SCAPI Schemas commands require an Account Manager API Client with OAuth credentials.
17+
18+
### Required Scopes
19+
20+
The following scopes are automatically requested by the CLI:
21+
22+
| Scope | Description |
23+
|-------|-------------|
24+
| `sfcc.scapi-schemas` | Access to SCAPI Schemas API |
25+
| `SALESFORCE_COMMERCE_API:<tenant_id>` | Tenant-specific access scope |
26+
27+
### Configuration
28+
29+
```bash
30+
# Set credentials via environment variables
31+
export SFCC_CLIENT_ID=my-client
32+
export SFCC_CLIENT_SECRET=my-secret
33+
export SFCC_TENANT_ID=zzxy_prd
34+
export SFCC_SHORTCODE=kv7kzm78
35+
36+
# Or provide via flags
37+
b2c scapi schemas list --client-id xxx --client-secret xxx --tenant-id zzxy_prd
38+
```
39+
40+
---
41+
42+
## b2c scapi schemas list
43+
44+
List available SCAPI schemas with optional filtering.
45+
46+
### Usage
47+
48+
```bash
49+
b2c scapi schemas list --tenant-id <TENANT_ID>
50+
```
51+
52+
### Flags
53+
54+
| Flag | Description | Default |
55+
|------|-------------|---------|
56+
| `--tenant-id` | (Required) Organization/tenant ID | |
57+
| `--api-family` | Filter by API family (e.g., shopper, admin) | |
58+
| `--api-name` | Filter by API name (e.g., products, orders) | |
59+
| `--api-version` | Filter by API version (e.g., v1) | |
60+
| `--status`, `-s` | Filter by schema status (`current`, `deprecated`) | |
61+
| `--columns`, `-c` | Columns to display (comma-separated) | |
62+
| `--extended`, `-x` | Show all columns including extended fields | `false` |
63+
| `--json` | Output results as JSON | `false` |
64+
65+
### Available Columns
66+
67+
Default columns: `apiFamily`, `apiName`, `apiVersion`, `status`
68+
69+
Extended columns (shown with `--extended`): `schemaVersion`, `link`
70+
71+
### Examples
72+
73+
```bash
74+
# List all available SCAPI schemas
75+
b2c scapi schemas list --tenant-id zzxy_prd
76+
77+
# Filter by API family
78+
b2c scapi schemas list --tenant-id zzxy_prd --api-family shopper
79+
80+
# Filter by API name
81+
b2c scapi schemas list --tenant-id zzxy_prd --api-name products
82+
83+
# Filter by status
84+
b2c scapi schemas list --tenant-id zzxy_prd --status current
85+
b2c scapi schemas list --tenant-id zzxy_prd --status deprecated
86+
87+
# Show extended columns
88+
b2c scapi schemas list --tenant-id zzxy_prd --extended
89+
90+
# Output as JSON
91+
b2c scapi schemas list --tenant-id zzxy_prd --json
92+
```
93+
94+
### Output
95+
96+
Default table output:
97+
98+
```
99+
Found 15 schema(s):
100+
101+
API Family API Name Version Status
102+
──────────────────────────────────────────
103+
shopper products v1 current
104+
shopper orders v1 current
105+
shopper customers v1 current
106+
admin inventory v1 current
107+
...
108+
```
109+
110+
---
111+
112+
## b2c scapi schemas get
113+
114+
Get a specific SCAPI schema with optional selective expansion.
115+
116+
### Usage
117+
118+
```bash
119+
b2c scapi schemas get <apiFamily> <apiName> <apiVersion> --tenant-id <TENANT_ID>
120+
```
121+
122+
### Arguments
123+
124+
| Argument | Description |
125+
|----------|-------------|
126+
| `apiFamily` | API family (e.g., shopper, admin) |
127+
| `apiName` | API name (e.g., products, orders) |
128+
| `apiVersion` | API version (e.g., v1) |
129+
130+
### Flags
131+
132+
| Flag | Description | Default |
133+
|------|-------------|---------|
134+
| `--tenant-id` | (Required) Organization/tenant ID | |
135+
| `--expand-paths` | Paths to fully expand (comma-separated) | |
136+
| `--expand-schemas` | Schema names to fully expand (comma-separated) | |
137+
| `--expand-examples` | Example names to fully expand (comma-separated) | |
138+
| `--expand-custom-properties` | Expand custom properties | `true` |
139+
| `--no-expand-custom-properties` | Do not expand custom properties | |
140+
| `--expand-all` | Return full schema without collapsing | `false` |
141+
| `--list-paths` | List available paths and exit | `false` |
142+
| `--list-schemas` | List available schema names and exit | `false` |
143+
| `--list-examples` | List available example names and exit | `false` |
144+
| `--yaml` | Output as YAML instead of JSON | `false` |
145+
| `--json` | Output wrapped JSON with metadata | `false` |
146+
147+
### Schema Collapsing
148+
149+
By default, schemas are output in a collapsed/outline format optimized for context efficiency (ideal for agentic use cases and LLM consumption):
150+
151+
- **Paths**: Show only HTTP methods available: `{"/products": ["get", "post"]}`
152+
- **Schemas**: Show only schema names: `{"Product": {}, "Order": {}}`
153+
- **Examples**: Show only example names: `{"ProductExample": {}}`
154+
155+
Use the `--expand-*` flags for selective expansion or `--expand-all` for the full, unmodified schema.
156+
157+
### Examples
158+
159+
```bash
160+
# Get collapsed/outline schema (default - context efficient)
161+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd
162+
163+
# Get full schema without collapsing
164+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --expand-all
165+
166+
# Expand specific paths only
167+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --expand-paths /products,/products/{id}
168+
169+
# Expand specific schemas only
170+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --expand-schemas Product,SearchResult
171+
172+
# Expand specific examples only
173+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --expand-examples ProductExample
174+
175+
# Combine selective expansions
176+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --expand-paths /products --expand-schemas Product
177+
178+
# List available paths in the schema
179+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --list-paths
180+
181+
# List available schema names
182+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --list-schemas
183+
184+
# List available examples
185+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --list-examples
186+
187+
# Output as YAML
188+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --yaml
189+
190+
# Output wrapped JSON with metadata
191+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --json
192+
193+
# Disable custom properties expansion
194+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --no-expand-custom-properties
195+
```
196+
197+
### Output Formats
198+
199+
**Default (raw JSON to stdout)**: The schema is output directly to stdout as JSON. Use shell redirection to save to a file:
200+
201+
```bash
202+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd > schema.json
203+
```
204+
205+
**YAML format (`--yaml`)**: Output as YAML for readability:
206+
207+
```bash
208+
b2c scapi schemas get shopper products v1 --tenant-id zzxy_prd --yaml > schema.yaml
209+
```
210+
211+
**Wrapped JSON (`--json`)**: Output includes metadata wrapper:
212+
213+
```json
214+
{
215+
"apiFamily": "shopper",
216+
"apiName": "products",
217+
"apiVersion": "v1",
218+
"schema": { ... }
219+
}
220+
```
221+
222+
### Notes
223+
224+
- The collapsed output significantly reduces context size while preserving structure, making it ideal for AI/LLM consumption
225+
- Use `--list-paths` to discover available paths before using `--expand-paths`
226+
- Use `--list-schemas` to discover available schema names before using `--expand-schemas`
227+
- Custom properties expansion is enabled by default and fetches tenant-specific custom attributes

‎packages/b2c-cli/package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,9 @@
126126
"subtopics": {
127127
"custom": {
128128
"description": "Manage Custom API endpoints"
129+
},
130+
"schemas": {
131+
"description": "Browse and retrieve SCAPI schema specifications"
129132
}
130133
}
131134
}

0 commit comments

Comments
 (0)