@salesforce/b2c-tooling-sdk 1.24.2 → 2.0.0

package/data/content-schemas/componenttype.json

@@ -65,36 +65,6 @@
         }
       ]
     },
-    {
-      "anyOf": [
-        {
-          "not": {
-            "properties": {
-              "embedded": {
-                "enum": [
-                  true
-                ]
-              }
-            },
-            "required": [
-              "embedded"
-            ]
-          }
-        },
-        {
-          "properties": {
-            "arch_type": {
-              "enum": [
-                "headless"
-              ]
-            }
-          },
-          "required": [
-            "arch_type"
-          ]
-        }
-      ]
-    },
     {
       "anyOf": [
         {

package/data/scapi-snippets/campaign-promotions.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-expressions -- Stored function expression, evaluated by code mode. */
+async (input) => {
+  if (!siteId) throw new Error('SCAPI_SITE_REQUIRED: configure siteId for campaign inspection.');
+  const campaignId = input.campaignId;
+  const offset = input.offset ?? 0;
+  const org = encodeURIComponent(organizationId);
+  const assignments = await scapi.request({method: 'GET',
+    path: '/pricing/campaigns/v1/organizations/' + org + '/campaigns/'
+      + encodeURIComponent(campaignId) + '/promotions', query: {siteId}});
+  if (!assignments.ok) return {stage: 'assignments', ...assignments};
+  const all = assignments.data.data;
+  const selected = all.slice(offset, offset + (input.limit ?? 12));
+  const ids = [...new Set(selected.map(row => row.promotionId))];
+  const details = new Map();
+  for (let start = 0; start < ids.length; start += 4) {
+    const batch = await Promise.all(ids.slice(start, start + 4).map(async id => {
+      try {
+        const r = await scapi.request({method: 'GET',
+          path: '/pricing/promotions/v1/organizations/' + org + '/promotions/'
+            + encodeURIComponent(id), query: {siteId}});
+        return [id, r.ok ? {status: r.status, enabled: r.data.enabled,
+          archived: r.data.archived, promotionClass: r.data.promotionClass} : r];
+      } catch (error) {
+        return [id, {error: String(error)}];
+      }
+    }));
+    for (const [id, detail] of batch) details.set(id, detail);
+  }
+  const end = offset + selected.length;
+  return {campaignId, siteId, total: all.length, returned: selected.length,
+    nextOffset: end < all.length ? end : null,
+    assignments: selected.map(row => ({promotionId: row.promotionId,
+      assignmentEnabled: row.enabled, promotion: details.get(row.promotionId)}))};
+}

package/data/scapi-snippets/code-version-inspect.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-expressions -- Stored function expression, evaluated by code mode. */
+async (input) => {
+  const r = await scapi.request({method: 'GET', path: '/dx/scripts/v1/organizations/{organizationId}/code-versions'});
+  if (!r.ok) return {stage: 'versions', ...r};
+  const versions = r.data.data;
+  const offset = input.offset ?? 0;
+  const selected = versions.slice(offset, offset + (input.limit ?? 10));
+  const end = offset + selected.length;
+  return {
+    total: versions.length,
+    active: versions.filter((v) => v.active).map((v) => v.id),
+    rollback: versions.filter((v) => v.rollback).map((v) => v.id),
+    returned: selected.length,
+    hasMore: end < versions.length,
+    nextOffset: selected.length && end < versions.length ? end : null,
+    versions: selected.map((v) => ({
+      id: v.id,
+      active: v.active,
+      rollback: v.rollback,
+      activationTime: v.activationTime,
+      lastModificationTime: v.lastModificationTime,
+      compatibilityMode: v.compatibilityMode,
+    })),
+  };
+}

package/data/scapi-snippets/create-product.js

@@ -0,0 +1,108 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-expressions -- Stored function expression, evaluated by code mode. */
+async (input) => {
+  const product = {
+    id: input.productId,
+    owningCatalogId: input.catalogId,
+    onlineFlag: {default: !(input.offline ?? true)},
+    ...(input.name === undefined ? {} : {name: {default: input.name}}),
+  };
+  const path =
+    '/product/products/v1/organizations/' +
+    encodeURIComponent(organizationId) +
+    '/products/' +
+    encodeURIComponent(product.id);
+  let stage = 'inspect';
+  let writeStatus;
+  let writeAttempted = false;
+  let summary;
+  let categoryWriteStatus;
+  const categoryPath = input.category
+    ? '/product/catalogs/v1/organizations/' +
+      encodeURIComponent(organizationId) +
+      '/catalogs/' +
+      encodeURIComponent(input.category.catalogId) +
+      '/categories/' +
+      encodeURIComponent(input.category.categoryId)
+    : undefined;
+  try {
+    const before = await scapi.request({method: 'GET', path});
+    if (before.ok) return {state: 'exists', id: product.id, changed: false};
+    if (before.status !== 404) return {stage, ...before};
+    if (categoryPath) {
+      stage = 'inspect-category';
+      const category = await scapi.request({method: 'GET', path: categoryPath});
+      if (!category.ok) return {stage, category: input.category, ...category};
+    }
+    stage = 'create';
+    writeAttempted = true;
+    const created = await scapi.request({method: 'PUT', path, body: product});
+    if (!created.ok) return {stage, id: product.id, ...created};
+    writeStatus = created.status;
+    stage = 'verify';
+    const after = await scapi.request({method: 'GET', path});
+    if (!after.ok) return {stage, id: product.id, writeStatus, ...after};
+    const saved = after.data;
+    const verified =
+      saved.id === product.id &&
+      saved.owningCatalogId === product.owningCatalogId &&
+      saved.onlineFlag?.default === product.onlineFlag.default &&
+      (input.name === undefined || saved.name?.default === input.name);
+    summary = {
+      state: verified ? 'verified' : 'verification_failed',
+      id: saved.id,
+      catalog: saved.owningCatalogId,
+      onlineFlag: saved.onlineFlag,
+      writeStatus,
+      ...(input.name === undefined ? {} : {name: saved.name?.default}),
+    };
+    if (!verified || !categoryPath) return summary;
+    const assignment = {...input.category, productId: saved.id};
+    const assignmentPath = categoryPath + '/products/' + encodeURIComponent(saved.id);
+    stage = 'assign-category';
+    const assigned = await scapi.request({method: 'PUT', path: assignmentPath, body: assignment});
+    if (!assigned.ok) return {...summary, state: 'partial', stage, category: assignment, ...assigned};
+    categoryWriteStatus = assigned.status;
+    stage = 'verify-category';
+    const checked = await scapi.request({method: 'GET', path: assignmentPath});
+    if (!checked.ok)
+      return {
+        ...summary,
+        state: 'partial',
+        stage,
+        category: {...assignment, writeStatus: categoryWriteStatus},
+        ...checked,
+      };
+    const observed = {
+      catalogId: checked.data.catalogId,
+      categoryId: checked.data.categoryId,
+      productId: checked.data.productId,
+    };
+    const categoryVerified = Object.keys(assignment).every((key) => observed[key] === assignment[key]);
+    return {
+      ...summary,
+      state: categoryVerified ? 'verified' : 'verification_failed',
+      category: {
+        ...assignment,
+        verified: categoryVerified,
+        writeStatus: categoryWriteStatus,
+        ...(categoryVerified ? {} : {observed}),
+      },
+    };
+  } catch (error) {
+    return {
+      ...(summary ? {...summary, state: 'partial'} : {}),
+      stage,
+      id: product.id,
+      writeStatus,
+      error: String(error),
+      ...(input.category ? {category: {...input.category, writeStatus: categoryWriteStatus}} : {}),
+      checkWriteBeforeRetry: writeAttempted,
+    };
+  }
+}

package/data/scapi-snippets/failed-job-triage.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-expressions -- Stored function expression, evaluated by code mode. */
+async (input) => {
+  const {from, to} = input;
+  if (Date.parse(from) >= Date.parse(to)) throw new Error('from must precede to.');
+  const offset = input.offset ?? 0;
+  const base = '/operation/jobs/v1/organizations/' + encodeURIComponent(organizationId);
+  const search = await scapi.request({method: 'POST', path: base + '/job-execution-search',
+    body: {query: {filteredQuery: {
+      query: {termQuery: {fields: ['status'], operator: 'is', values: ['ERROR']}},
+      filter: {rangeFilter: {field: 'startTime', from, to}}
+    }}, sorts: [{field: 'startTime', sortOrder: 'desc'}], offset, limit: input.limit ?? 3}});
+  if (!search.ok) return {stage: 'search', ...search};
+  const hits = search.data.hits;
+  const executions = await Promise.all(hits.map(async hit => {
+    const identity = {id: hit.id, jobId: hit.jobId};
+    try {
+      const r = await scapi.request({method: 'GET', path: base + '/jobs/'
+        + encodeURIComponent(hit.jobId) + '/executions/' + encodeURIComponent(hit.id)});
+      if (!r.ok) return {...identity, ...r};
+      const d = r.data;
+      return {...identity, status: r.status, jobStatus: d.status, startTime: d.startTime,
+        duration: d.duration, exitStatus: d.exitStatus, logFilePath: d.logFilePath};
+    } catch (error) {
+      return {...identity, error: String(error)};
+    }
+  }));
+  const end = offset + hits.length;
+  return {from, to, total: search.data.total, returned: hits.length,
+    hasMore: end < search.data.total,
+    nextOffset: hits.length && end < search.data.total ? end : null, executions};
+}

package/data/scapi-snippets/job-execution-inspect.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-expressions -- Stored function expression, evaluated by code mode. */
+async (input) => {
+  const r = await scapi.request({
+    method: 'GET',
+    path:
+      '/operation/jobs/v1/organizations/{organizationId}/jobs/' +
+      encodeURIComponent(input.jobId) +
+      '/executions/' +
+      encodeURIComponent(input.executionId),
+  });
+  if (!r.ok) return {stage: 'execution', ...r};
+  const d = r.data;
+  const steps = d.stepExecutions ?? [];
+  const offset = input.offset ?? 0;
+  const selected = steps.slice(offset, offset + (input.limit ?? 10));
+  const end = offset + selected.length;
+  return {
+    id: d.id,
+    jobId: d.jobId,
+    executionStatus: d.executionStatus,
+    status: d.status,
+    exitStatus: d.exitStatus,
+    startTime: d.startTime,
+    endTime: d.endTime,
+    duration: d.duration,
+    logFilePath: d.logFilePath,
+    isLogFileExisting: d.isLogFileExisting,
+    totalSteps: steps.length,
+    returned: selected.length,
+    hasMore: end < steps.length,
+    nextOffset: selected.length && end < steps.length ? end : null,
+    steps: selected.map((s) => ({
+      id: s.id,
+      stepId: s.stepId,
+      executionScope: s.executionScope,
+      executionStatus: s.executionStatus,
+      status: s.status,
+      exitStatus: s.exitStatus,
+      startTime: s.startTime,
+      endTime: s.endTime,
+      duration: s.duration,
+      totalItemCount: s.totalItemCount,
+      itemWriteCount: s.itemWriteCount,
+    })),
+  };
+}

package/data/scapi-snippets/job-execution-review.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-expressions -- Stored function expression, evaluated by code mode. */
+async (input) => {
+  if (Date.parse(input.from) >= Date.parse(input.to)) throw new Error('from must precede to.');
+  const offset = input.offset ?? 0;
+  const query = {
+    filteredQuery: {
+      query: {matchAllQuery: {}},
+      filter: {rangeFilter: {field: 'startTime', from: input.from, to: input.to}},
+    },
+  };
+  if (input.jobId) query.filteredQuery.query = {termQuery: {fields: ['jobId'], operator: 'is', values: [input.jobId]}};
+  const r = await scapi.request({
+    method: 'POST',
+    path: '/operation/jobs/v1/organizations/{organizationId}/job-execution-search',
+    body: {query, sorts: [{field: 'startTime', sortOrder: 'desc'}], offset, limit: input.limit ?? 10},
+  });
+  if (!r.ok) return {stage: 'search', ...r};
+  const hits = r.data.hits;
+  const end = offset + hits.length;
+  return {
+    from: input.from,
+    to: input.to,
+    total: r.data.total,
+    returned: hits.length,
+    hasMore: end < r.data.total,
+    nextOffset: hits.length && end < r.data.total ? end : null,
+    executions: hits.map((d) => ({
+      id: d.id,
+      jobId: d.jobId,
+      executionStatus: d.executionStatus,
+      status: d.status,
+      exitStatus: d.exitStatus,
+      startTime: d.startTime,
+      endTime: d.endTime,
+      duration: d.duration,
+      logFilePath: d.logFilePath,
+      isLogFileExisting: d.isLogFileExisting,
+    })),
+  };
+}

package/data/scapi-snippets/manifest.json

@@ -0,0 +1,220 @@
+{
+  "version": 1,
+  "snippets": [
+    {
+      "name": "builtin/create-product",
+      "description": "Create a basic product, optionally assign it to a storefront catalog category, and verify saved fields and assignment.",
+      "effect": "write",
+      "file": "create-product.js",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "catalogId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Owning catalog for the new product."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Product name in the default locale."
+          },
+          "offline": {
+            "type": "boolean",
+            "default": true,
+            "description": "Create offline by default; false sets the default online flag."
+          },
+          "category": {
+            "type": "object",
+            "description": "Optional assignment target; its catalog may differ from the owning catalog.",
+            "properties": {
+              "catalogId": {
+                "type": "string",
+                "minLength": 1
+              },
+              "categoryId": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": ["catalogId", "categoryId"],
+            "additionalProperties": false
+          }
+        },
+        "required": ["productId", "catalogId"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "builtin/campaign-promotions",
+      "description": "Inspect campaign assignments and promotion details in bounded batches.",
+      "effect": "read",
+      "file": "campaign-promotions.js",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "campaignId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "offset": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 12
+          }
+        },
+        "required": ["campaignId"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "builtin/failed-job-triage",
+      "description": "Search failed job executions and inspect a bounded page with continuation.",
+      "effect": "read",
+      "file": "failed-job-triage.js",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "from": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "to": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "offset": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 3
+          }
+        },
+        "required": ["from", "to"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "builtin/job-execution-review",
+      "description": "Review job executions in a fixed interval, including successful runs; return compact statuses and continuation.",
+      "effect": "read",
+      "file": "job-execution-review.js",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "from": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "to": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "jobId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "offset": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20
+          }
+        },
+        "required": ["from", "to"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "builtin/job-execution-inspect",
+      "description": "Inspect one execution and a bounded page of its steps; return the exact WebDAV log path.",
+      "effect": "read",
+      "file": "job-execution-inspect.js",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "jobId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "executionId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "offset": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20
+          }
+        },
+        "required": ["jobId", "executionId"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "builtin/code-version-inspect",
+      "description": "Identify active and rollback code versions and inspect a bounded page of version metadata.",
+      "effect": "read",
+      "file": "code-version-inspect.js",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "offset": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "builtin/site-cartridge-inspect",
+      "description": "Inspect site status, catalog, and ordered cartridge paths; check expected cartridge names.",
+      "effect": "read",
+      "file": "site-cartridge-inspect.js",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "siteId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "expectedCartridges": {
+            "type": "array",
+            "maxItems": 50,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "required": ["siteId"],
+        "additionalProperties": false
+      }
+    }
+  ]
+}

package/data/scapi-snippets/site-cartridge-inspect.js

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-expressions -- Stored function expression, evaluated by code mode. */
+async (input) => {
+  const r = await scapi.request({
+    method: 'GET',
+    path: '/site/sites/v1/organizations/{organizationId}/sites/' + encodeURIComponent(input.siteId),
+  });
+  if (!r.ok) return {stage: 'site', ...r};
+  const site = r.data;
+  const cartridges = site.cartridges?.split(':').filter(Boolean);
+  const customCartridges = site.customCartridges?.split(':').filter(Boolean);
+  return {
+    siteId: site.id,
+    siteCatalogId: site.siteCatalogId,
+    storefrontStatus: site.storefrontStatus,
+    lastModified: site.lastModified,
+    cartridges,
+    customCartridges,
+    missing:
+      cartridges === undefined ? null : (input.expectedCartridges ?? []).filter((name) => !cartridges.includes(name)),
+  };
+}