Skip to content

Commit 9a1063f

Browse files
ct-sdks[bot]ct-sdks[bot]
authored
chore(release): publish v0.8.0 (#27)
Co-authored-by: ct-sdks[bot] <153784748+ct-sdks[bot]@users.noreply.github.com>
1 parent 7f30623 commit 9a1063f

35 files changed

Lines changed: 2163 additions & 5 deletions

File tree

‎.agents/plugins/commercetools/.codex-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "commercetools",
33
"displayName": "commercetools",
4-
"version": "0.7.0",
4+
"version": "0.8.0",
55
"description": "Build commercetools solutions faster",
66
"author": {
77
"name": "commercetools",

‎.agents/plugins/commercetools/skills/commercetools-checkout/SKILL.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,28 @@ When this skill is invoked, always follow these steps:
4545

4646
3. **Provide implementation guidance** — Synthesize the documentation with the specific integration mode the user is targeting.
4747

48+
### Optional scripts
49+
50+
**Fetch GraphQL schema** — Run this when you need context about a commercetools GraphQL query or mutation — for example, to inspect a resource's fields, types, and available operations before writing a query, or to verify a GraphQL query/mutation you have just generated against the real schema. It fetches the partial GraphQL SDL for a single commercetools resource:
51+
```bash
52+
node scripts/graphql-schemata.mjs \
53+
--resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
54+
--app-name "<current-app, e.g. claude, copilot, cursor, codex>" \
55+
--model "<current-model>" \
56+
--skill-name "commercetools-checkout"
57+
```
58+
The output is the GraphQL SDL for that resource. If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. **Note:** the SDL may contain *stubbed types* — referenced resources rendered as stubs, with their real type name given in a comment. Fetch any you need separately by re-running this script with that type name as `--resource-name`.
59+
60+
**Fetch OpenAPI (REST) schema** — Run this when you need context about a commercetools REST endpoint, request/response payload, or update action — for example, to inspect a resource's REST operations before constructing a request, or to verify a REST request/payload you have just generated against the real specification. It fetches the partial OpenAPI specification for a single commercetools resource:
61+
```bash
62+
node scripts/openApi-schemata.mjs \
63+
--resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
64+
--app-name "<current-app, e.g. claude, copilot, cursor, codex>" \
65+
--model "<current-model>" \
66+
--skill-name "commercetools-checkout"
67+
```
68+
The output is the OpenAPI specification (YAML) for that resource. REST resources use a read/write-split naming form (e.g. `api-Cart-read`, `api-Cart-write`). If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. **Note:** the spec does not include reference-expansion schemas — fetch a referenced resource's schema separately by re-running this script with that resource as `--resource-name`.
69+
4870
## References
4971

5072
See [payment-only-mode.md](./references/payment-only-mode.md) for:

‎.agents/plugins/commercetools/skills/commercetools-checkout/scripts/graphql-schemata.mjs‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
#!/usr/bin/env node
2+
3+
/**
4+
* Fetch GraphQL schema for the agent
5+
*
6+
* Fetches a partial commercetools GraphQL SDL for a single resource as grounding
7+
* context for the agent, with instrumentation headers. Use this to inspect a
8+
* resource's fields and available operations before writing queries or mutations.
9+
* Results are written to stdout for consumption by AI agents.
10+
*
11+
* Usage:
12+
* node scripts/graphql-schemata.mjs --resource-name "Cart" --app-name <name> --model <model> --skill-name <skill>
13+
*
14+
* Required:
15+
* --resource-name <string> commercetools resource name (e.g., Cart, Product, Order)
16+
* --app-name <string> Calling app/tool (e.g., claude, copilot, cursor, codex)
17+
* --model <string> Model name (e.g., claude-sonnet-4.5, gpt-4)
18+
* --skill-name <string> Skill identifier (e.g., commercetools-platform)
19+
*/
20+
21+
import { parseArgs } from 'util';
22+
23+
const SCHEMA_URL = 'https://docs.commercetools.com/apis/rest/tools/graphql-schemata';
24+
25+
// Parse command line arguments
26+
const { values } = parseArgs({
27+
options: {
28+
'resource-name': { type: 'string' },
29+
'app-name': { type: 'string' },
30+
model: { type: 'string' },
31+
'skill-name': { type: 'string' },
32+
},
33+
});
34+
35+
// Validate required parameters
36+
const missingParams = [];
37+
if (!values['resource-name']) missingParams.push('--resource-name');
38+
if (!values['app-name']) missingParams.push('--app-name');
39+
if (!values.model) missingParams.push('--model');
40+
if (!values['skill-name']) missingParams.push('--skill-name');
41+
42+
if (missingParams.length > 0) {
43+
console.error(`Error: Missing required parameters: ${missingParams.join(', ')}`);
44+
console.error('Usage: node scripts/graphql-schemata.mjs --resource-name "Cart" --app-name "app" --model "model" --skill-name "skill"');
45+
process.exit(1);
46+
}
47+
48+
// Fetch the partial GraphQL SDL and print it (fail soft: exit 0 on any error)
49+
try {
50+
const res = await fetch(SCHEMA_URL, {
51+
method: 'POST',
52+
headers: {
53+
'Content-Type': 'application/json',
54+
'User-Agent': `${values['app-name']}/1.0 (${values.model})`,
55+
'X-Model': values.model,
56+
'X-Client-Type': values['app-name'],
57+
'X-Skill-Name': values['skill-name'],
58+
},
59+
body: JSON.stringify({ resourceName: values['resource-name'] }),
60+
signal: AbortSignal.timeout(60000),
61+
});
62+
63+
const response = await res.json();
64+
65+
// Surface API errors (e.g. an invalid resourceName returns HTTP 400)
66+
if (response.error) {
67+
const details = response.error.details;
68+
const validValues = Array.isArray(details)
69+
? details.find((d) => Array.isArray(d.values))?.values
70+
: undefined;
71+
72+
process.stdout.write(`No schema found for resource "${values['resource-name']}". Check the resource name spelling.\n`);
73+
if (validValues?.length) {
74+
process.stdout.write(`\nValid resource names:\n${validValues.join(', ')}\n`);
75+
}
76+
process.exit(0);
77+
}
78+
79+
if (!res.ok) process.exit(0);
80+
81+
// The result is a GraphQL SDL string for the requested resource
82+
if (typeof response.result === 'string' && response.result.length > 0) {
83+
process.stdout.write(`# GraphQL Schema for resource: ${values['resource-name']}\n\n`);
84+
process.stdout.write('```graphql\n');
85+
process.stdout.write(response.result.endsWith('\n') ? response.result : `${response.result}\n`);
86+
process.stdout.write('```\n');
87+
} else if (response.result) {
88+
// Fallback: output structured result as-is
89+
process.stdout.write(`${JSON.stringify(response.result, null, 2)}\n`);
90+
} else {
91+
process.stdout.write(`No schema found for resource "${values['resource-name']}". Check the resource name spelling.\n`);
92+
}
93+
} catch (err) {
94+
process.exit(0);
95+
}

‎.agents/plugins/commercetools/skills/commercetools-checkout/scripts/openApi-schemata.mjs‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
#!/usr/bin/env node
2+
3+
/**
4+
* Fetch OpenAPI (OAS) schema for the agent
5+
*
6+
* Fetches a partial commercetools OpenAPI specification for a single resource as
7+
* grounding context for the agent, with instrumentation headers. Use this to
8+
* inspect a resource's REST endpoints, request/response payloads, and update
9+
* actions before generating REST clients or requests.
10+
* Results are written to stdout for consumption by AI agents.
11+
*
12+
* Usage:
13+
* node scripts/openApi-schemata.mjs --resource-name "api-Cart-write" --app-name <name> --model <model> --skill-name <skill>
14+
*
15+
* Required:
16+
* --resource-name <string> commercetools resource name (e.g., api-Cart-read, api-Cart-write, api-Customer-write, checkout-Application)
17+
* --app-name <string> Calling app/tool (e.g., claude, copilot, cursor, codex)
18+
* --model <string> Model name (e.g., claude-sonnet-4.5, gpt-4)
19+
* --skill-name <string> Skill identifier (e.g., commercetools-platform)
20+
*/
21+
22+
import { parseArgs } from 'util';
23+
24+
const SCHEMA_URL = 'https://docs.commercetools.com/apis/rest/tools/oas-schemata';
25+
26+
// Parse command line arguments
27+
const { values } = parseArgs({
28+
options: {
29+
'resource-name': { type: 'string' },
30+
'app-name': { type: 'string' },
31+
model: { type: 'string' },
32+
'skill-name': { type: 'string' },
33+
},
34+
});
35+
36+
// Validate required parameters
37+
const missingParams = [];
38+
if (!values['resource-name']) missingParams.push('--resource-name');
39+
if (!values['app-name']) missingParams.push('--app-name');
40+
if (!values.model) missingParams.push('--model');
41+
if (!values['skill-name']) missingParams.push('--skill-name');
42+
43+
if (missingParams.length > 0) {
44+
console.error(`Error: Missing required parameters: ${missingParams.join(', ')}`);
45+
console.error('Usage: node scripts/openApi-schemata.mjs --resource-name "api-Cart-write" --app-name "app" --model "model" --skill-name "skill"');
46+
process.exit(1);
47+
}
48+
49+
// Fetch the partial OpenAPI spec and print it (fail soft: exit 0 on any error)
50+
try {
51+
const res = await fetch(SCHEMA_URL, {
52+
method: 'POST',
53+
headers: {
54+
'Content-Type': 'application/json',
55+
'User-Agent': `${values['app-name']}/1.0 (${values.model})`,
56+
'X-Model': values.model,
57+
'X-Client-Type': values['app-name'],
58+
'X-Skill-Name': values['skill-name'],
59+
},
60+
body: JSON.stringify({ resourceName: values['resource-name'] }),
61+
signal: AbortSignal.timeout(60000),
62+
});
63+
64+
const response = await res.json();
65+
66+
// Surface API errors (e.g. an invalid resourceName returns HTTP 400)
67+
if (response.error) {
68+
const details = response.error.details;
69+
const validValues = Array.isArray(details)
70+
? details.find((d) => Array.isArray(d.values))?.values
71+
: undefined;
72+
73+
process.stdout.write(`No schema found for resource "${values['resource-name']}". Check the resource name spelling.\n`);
74+
if (validValues?.length) {
75+
process.stdout.write(`\nValid resource names:\n${validValues.join(', ')}\n`);
76+
}
77+
process.exit(0);
78+
}
79+
80+
if (!res.ok) process.exit(0);
81+
82+
// The result is an OpenAPI specification (YAML string) for the requested resource
83+
if (typeof response.result === 'string' && response.result.length > 0) {
84+
process.stdout.write(`# OpenAPI Schema for resource: ${values['resource-name']}\n\n`);
85+
process.stdout.write('```yaml\n');
86+
process.stdout.write(response.result.endsWith('\n') ? response.result : `${response.result}\n`);
87+
process.stdout.write('```\n');
88+
} else if (response.result && typeof response.result === 'object') {
89+
// Fallback: output a structured (JSON) result as-is
90+
process.stdout.write(`# OpenAPI Schema for resource: ${values['resource-name']}\n\n`);
91+
process.stdout.write('```json\n');
92+
process.stdout.write(`${JSON.stringify(response.result, null, 2)}\n`);
93+
process.stdout.write('```\n');
94+
} else {
95+
process.stdout.write(`No schema found for resource "${values['resource-name']}". Check the resource name spelling.\n`);
96+
}
97+
} catch (err) {
98+
process.exit(0);
99+
}

‎.agents/plugins/commercetools/skills/commercetools-commerce-patterns/SKILL.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,27 @@ When this skill is invoked, always follow these steps:
3939

4040
3. **Provide implementation guidance** — Synthesize the documentation with the specific integration mode the user is targeting.
4141

42+
### Optional scripts
43+
44+
**Fetch GraphQL schema** — Run this when you need context about a commercetools GraphQL query or mutation — for example, to inspect a resource's fields, types, and available operations before writing a query, or to verify a GraphQL query/mutation you have just generated against the real schema. It fetches the partial GraphQL SDL for a single commercetools resource:
45+
```bash
46+
node scripts/graphql-schemata.mjs \
47+
--resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
48+
--app-name "<current-app, e.g. claude, copilot, cursor, codex>" \
49+
--model "<current-model>" \
50+
--skill-name "commercetools-commerce-patterns"
51+
```
52+
The output is the GraphQL SDL for that resource. If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. **Note:** the SDL may contain *stubbed types* — referenced resources rendered as stubs, with their real type name given in a comment. Fetch any you need separately by re-running this script with that type name as `--resource-name`.
53+
54+
**Fetch OpenAPI (REST) schema** — Run this when you need context about a commercetools REST endpoint, request/response payload, or update action — for example, to inspect a resource's REST operations before constructing a request, or to verify a REST request/payload you have just generated against the real specification. It fetches the partial OpenAPI specification for a single commercetools resource:
55+
```bash
56+
node scripts/openApi-schemata.mjs \
57+
--resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
58+
--app-name "<current-app, e.g. claude, copilot, cursor, codex>" \
59+
--model "<current-model>" \
60+
--skill-name "commercetools-commerce-patterns"
61+
```
62+
The output is the OpenAPI specification (YAML) for that resource. REST resources use a read/write-split naming form (e.g. `api-Cart-read`, `api-Cart-write`). If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. **Note:** the spec does not include reference-expansion schemas — fetch a referenced resource's schema separately by re-running this script with that resource as `--resource-name`.
4263
## Key Takeaways
4364

4465
**Discount stacking follows a strict priority chain.** Product Discounts → Cart Discounts → Discount Codes → Direct Discounts. Direct Discounts on a cart **block all Discount Codes**. Never mix Direct Discounts and Discount Code flows on the same cart.

‎.agents/plugins/commercetools/skills/commercetools-commerce-patterns/scripts/graphql-schemata.mjs‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
#!/usr/bin/env node
2+
3+
/**
4+
* Fetch GraphQL schema for the agent
5+
*
6+
* Fetches a partial commercetools GraphQL SDL for a single resource as grounding
7+
* context for the agent, with instrumentation headers. Use this to inspect a
8+
* resource's fields and available operations before writing queries or mutations.
9+
* Results are written to stdout for consumption by AI agents.
10+
*
11+
* Usage:
12+
* node scripts/graphql-schemata.mjs --resource-name "Cart" --app-name <name> --model <model> --skill-name <skill>
13+
*
14+
* Required:
15+
* --resource-name <string> commercetools resource name (e.g., Cart, Product, Order)
16+
* --app-name <string> Calling app/tool (e.g., claude, copilot, cursor, codex)
17+
* --model <string> Model name (e.g., claude-sonnet-4.5, gpt-4)
18+
* --skill-name <string> Skill identifier (e.g., commercetools-platform)
19+
*/
20+
21+
import { parseArgs } from 'util';
22+
23+
const SCHEMA_URL = 'https://docs.commercetools.com/apis/rest/tools/graphql-schemata';
24+
25+
// Parse command line arguments
26+
const { values } = parseArgs({
27+
options: {
28+
'resource-name': { type: 'string' },
29+
'app-name': { type: 'string' },
30+
model: { type: 'string' },
31+
'skill-name': { type: 'string' },
32+
},
33+
});
34+
35+
// Validate required parameters
36+
const missingParams = [];
37+
if (!values['resource-name']) missingParams.push('--resource-name');
38+
if (!values['app-name']) missingParams.push('--app-name');
39+
if (!values.model) missingParams.push('--model');
40+
if (!values['skill-name']) missingParams.push('--skill-name');
41+
42+
if (missingParams.length > 0) {
43+
console.error(`Error: Missing required parameters: ${missingParams.join(', ')}`);
44+
console.error('Usage: node scripts/graphql-schemata.mjs --resource-name "Cart" --app-name "app" --model "model" --skill-name "skill"');
45+
process.exit(1);
46+
}
47+
48+
// Fetch the partial GraphQL SDL and print it (fail soft: exit 0 on any error)
49+
try {
50+
const res = await fetch(SCHEMA_URL, {
51+
method: 'POST',
52+
headers: {
53+
'Content-Type': 'application/json',
54+
'User-Agent': `${values['app-name']}/1.0 (${values.model})`,
55+
'X-Model': values.model,
56+
'X-Client-Type': values['app-name'],
57+
'X-Skill-Name': values['skill-name'],
58+
},
59+
body: JSON.stringify({ resourceName: values['resource-name'] }),
60+
signal: AbortSignal.timeout(60000),
61+
});
62+
63+
const response = await res.json();
64+
65+
// Surface API errors (e.g. an invalid resourceName returns HTTP 400)
66+
if (response.error) {
67+
const details = response.error.details;
68+
const validValues = Array.isArray(details)
69+
? details.find((d) => Array.isArray(d.values))?.values
70+
: undefined;
71+
72+
process.stdout.write(`No schema found for resource "${values['resource-name']}". Check the resource name spelling.\n`);
73+
if (validValues?.length) {
74+
process.stdout.write(`\nValid resource names:\n${validValues.join(', ')}\n`);
75+
}
76+
process.exit(0);
77+
}
78+
79+
if (!res.ok) process.exit(0);
80+
81+
// The result is a GraphQL SDL string for the requested resource
82+
if (typeof response.result === 'string' && response.result.length > 0) {
83+
process.stdout.write(`# GraphQL Schema for resource: ${values['resource-name']}\n\n`);
84+
process.stdout.write('```graphql\n');
85+
process.stdout.write(response.result.endsWith('\n') ? response.result : `${response.result}\n`);
86+
process.stdout.write('```\n');
87+
} else if (response.result) {
88+
// Fallback: output structured result as-is
89+
process.stdout.write(`${JSON.stringify(response.result, null, 2)}\n`);
90+
} else {
91+
process.stdout.write(`No schema found for resource "${values['resource-name']}". Check the resource name spelling.\n`);
92+
}
93+
} catch (err) {
94+
process.exit(0);
95+
}

0 commit comments

Comments
 (0)