@salesforce/b2c-cli 2.3.1 → 2.5.0

package/content/guidance/b2c-cli/b2c-site-import-export/references/METADATA-XML.md

@@ -0,0 +1,381 @@
+# Metadata XML Patterns
+
+Common XML patterns for site archive imports.
+
+## XSD Schema Reference
+
+For authoritative XML schema definitions, use the `b2c` CLI (if installed):
+
+```bash
+# View the metadata XSD schema
+b2c docs schema metadata
+
+# List all available schemas
+b2c docs schema --list
+```
+
+## Other Import Formats
+
+For service configurations (HTTP services, credentials, profiles), see the `b2c:b2c-webservices` skill.
+
+## System Object Extensions
+
+### Add String Attribute to Product
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="Product">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="externalId">
+                <display-name xml:lang="x-default">External ID</display-name>
+                <type>string</type>
+                <mandatory-flag>false</mandatory-flag>
+                <externally-managed-flag>true</externally-managed-flag>
+                <max-length>100</max-length>
+            </attribute-definition>
+        </custom-attribute-definitions>
+        <group-definitions>
+            <attribute-group group-id="ExternalData">
+                <display-name xml:lang="x-default">External Data</display-name>
+                <attribute attribute-id="externalId"/>
+            </attribute-group>
+        </group-definitions>
+    </type-extension>
+</metadata>
+```
+
+### Add Enum Attribute to Order
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="Order">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="fulfillmentStatus">
+                <display-name xml:lang="x-default">Fulfillment Status</display-name>
+                <type>enum-of-string</type>
+                <mandatory-flag>false</mandatory-flag>
+                <value-definitions>
+                    <value-definition default="true">
+                        <display xml:lang="x-default">Pending</display>
+                        <value>pending</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">Processing</display>
+                        <value>processing</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">Shipped</display>
+                        <value>shipped</value>
+                    </value-definition>
+                    <value-definition>
+                        <display xml:lang="x-default">Delivered</display>
+                        <value>delivered</value>
+                    </value-definition>
+                </value-definitions>
+            </attribute-definition>
+        </custom-attribute-definitions>
+        <group-definitions>
+            <attribute-group group-id="FulfillmentInfo">
+                <display-name xml:lang="x-default">Fulfillment Info</display-name>
+                <attribute attribute-id="fulfillmentStatus"/>
+            </attribute-group>
+        </group-definitions>
+    </type-extension>
+</metadata>
+```
+
+### Add Boolean Attribute to Customer Profile
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="Profile">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="marketingOptIn">
+                <display-name xml:lang="x-default">Marketing Opt-In</display-name>
+                <type>boolean</type>
+                <mandatory-flag>false</mandatory-flag>
+                <default-value>false</default-value>
+            </attribute-definition>
+            <attribute-definition attribute-id="loyaltyMember">
+                <display-name xml:lang="x-default">Loyalty Member</display-name>
+                <type>boolean</type>
+                <mandatory-flag>false</mandatory-flag>
+                <default-value>false</default-value>
+            </attribute-definition>
+        </custom-attribute-definitions>
+    </type-extension>
+</metadata>
+```
+
+## Site Preferences
+
+### Boolean Preference
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="SitePreferences">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="enableReviews">
+                <display-name xml:lang="x-default">Enable Product Reviews</display-name>
+                <type>boolean</type>
+                <default-value>true</default-value>
+            </attribute-definition>
+        </custom-attribute-definitions>
+    </type-extension>
+</metadata>
+```
+
+### String Preference (API Key)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="SitePreferences">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="analyticsApiKey">
+                <display-name xml:lang="x-default">Analytics API Key</display-name>
+                <type>password</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="analyticsEndpoint">
+                <display-name xml:lang="x-default">Analytics Endpoint</display-name>
+                <type>string</type>
+            </attribute-definition>
+        </custom-attribute-definitions>
+        <group-definitions>
+            <attribute-group group-id="AnalyticsSettings">
+                <display-name xml:lang="x-default">Analytics Settings</display-name>
+                <attribute attribute-id="analyticsApiKey"/>
+                <attribute attribute-id="analyticsEndpoint"/>
+            </attribute-group>
+        </group-definitions>
+    </type-extension>
+</metadata>
+```
+
+### Preference Values
+
+**sites/RefArch/preferences.xml:**
+
+Preferences can be set per instance type:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-03-31">
+    <custom-preferences>
+        <all-instances>
+            <preference preference-id="enableReviews">true</preference>
+        </all-instances>
+        <development>
+            <preference preference-id="analyticsEndpoint">https://dev-analytics.example.com/api</preference>
+        </development>
+        <production>
+            <preference preference-id="analyticsEndpoint">https://analytics.example.com/api</preference>
+        </production>
+    </custom-preferences>
+</preferences>
+```
+
+## Custom Object Types
+
+### Simple Custom Object
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <custom-type type-id="Banner">
+        <display-name xml:lang="x-default">Banner</display-name>
+        <staging-mode>source-to-target</staging-mode>
+        <storage-scope>site</storage-scope>
+        <key-definition attribute-id="bannerId">
+            <display-name xml:lang="x-default">Banner ID</display-name>
+            <type>string</type>
+            <min-length>1</min-length>
+        </key-definition>
+        <attribute-definitions>
+            <attribute-definition attribute-id="title">
+                <display-name xml:lang="x-default">Title</display-name>
+                <type>string</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="imageUrl">
+                <display-name xml:lang="x-default">Image URL</display-name>
+                <type>string</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="linkUrl">
+                <display-name xml:lang="x-default">Link URL</display-name>
+                <type>string</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="startDate">
+                <display-name xml:lang="x-default">Start Date</display-name>
+                <type>datetime</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="endDate">
+                <display-name xml:lang="x-default">End Date</display-name>
+                <type>datetime</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="isActive">
+                <display-name xml:lang="x-default">Active</display-name>
+                <type>boolean</type>
+                <default-value>true</default-value>
+            </attribute-definition>
+        </attribute-definitions>
+    </custom-type>
+</metadata>
+```
+
+### Custom Object Data
+
+**customobjects/Banner.xml:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<custom-objects xmlns="http://www.demandware.com/xml/impex/customobject/2006-10-31">
+    <custom-object type-id="Banner" object-id="homepage-hero">
+        <object-attribute attribute-id="title">Summer Sale</object-attribute>
+        <object-attribute attribute-id="imageUrl">/images/banners/summer-sale.jpg</object-attribute>
+        <object-attribute attribute-id="linkUrl">/sale</object-attribute>
+        <object-attribute attribute-id="startDate">2024-06-01T00:00:00.000Z</object-attribute>
+        <object-attribute attribute-id="endDate">2024-08-31T23:59:59.000Z</object-attribute>
+        <object-attribute attribute-id="isActive">true</object-attribute>
+    </custom-object>
+    <custom-object type-id="Banner" object-id="promo-banner">
+        <object-attribute attribute-id="title">Free Shipping</object-attribute>
+        <object-attribute attribute-id="imageUrl">/images/banners/free-shipping.jpg</object-attribute>
+        <object-attribute attribute-id="linkUrl">/shipping-info</object-attribute>
+        <object-attribute attribute-id="isActive">true</object-attribute>
+    </custom-object>
+</custom-objects>
+```
+
+## Content Assets
+
+**sites/RefArch/library/content/content.xml:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<library xmlns="http://www.demandware.com/xml/impex/library/2006-10-31">
+    <content content-id="terms-conditions">
+        <display-name xml:lang="x-default">Terms and Conditions</display-name>
+        <online-flag>true</online-flag>
+        <searchable-flag>false</searchable-flag>
+        <custom-attributes>
+            <custom-attribute attribute-id="body" xml:lang="x-default">
+                <![CDATA[<h1>Terms and Conditions</h1><p>Content here...</p>]]>
+            </custom-attribute>
+        </custom-attributes>
+    </content>
+</library>
+```
+
+## Attribute Types Reference
+
+| Type | XML Value | Example |
+|------|-----------|---------|
+| `string` | `<type>string</type>` | Text up to 4000 chars |
+| `text` | `<type>text</type>` | Unlimited text |
+| `int` | `<type>int</type>` | Whole numbers |
+| `double` | `<type>double</type>` | Decimal numbers |
+| `boolean` | `<type>boolean</type>` | true/false |
+| `date` | `<type>date</type>` | Date only |
+| `datetime` | `<type>datetime</type>` | Date and time |
+| `email` | `<type>email</type>` | Email format |
+| `password` | `<type>password</type>` | Encrypted |
+| `html` | `<type>html</type>` | HTML content |
+| `image` | `<type>image</type>` | Image reference |
+| `enum-of-string` | `<type>enum-of-string</type>` | Single select |
+| `set-of-string` | `<type>set-of-string</type>` | Multi-select |
+
+## Complete Import Example
+
+Directory structure for adding a custom integration:
+
+```
+integration-import/
+├── meta/
+│   ├── system-objecttype-extensions.xml
+│   └── custom-objecttype-definitions.xml
+├── sites/
+│   └── RefArch/
+│       └── preferences.xml
+└── customobjects/
+    └── IntegrationConfig.xml
+```
+
+**meta/system-objecttype-extensions.xml:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="SitePreferences">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="integrationEnabled">
+                <display-name xml:lang="x-default">Enable Integration</display-name>
+                <type>boolean</type>
+                <default-value>false</default-value>
+            </attribute-definition>
+        </custom-attribute-definitions>
+    </type-extension>
+    <type-extension type-id="Order">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="integrationId">
+                <display-name xml:lang="x-default">Integration ID</display-name>
+                <type>string</type>
+                <externally-managed-flag>true</externally-managed-flag>
+            </attribute-definition>
+        </custom-attribute-definitions>
+    </type-extension>
+</metadata>
+```
+
+**meta/custom-objecttype-definitions.xml:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <custom-type type-id="IntegrationConfig">
+        <display-name xml:lang="x-default">Integration Configuration</display-name>
+        <staging-mode>source-to-target</staging-mode>
+        <storage-scope>organization</storage-scope>
+        <key-definition attribute-id="configKey">
+            <display-name xml:lang="x-default">Config Key</display-name>
+            <type>string</type>
+        </key-definition>
+        <attribute-definitions>
+            <attribute-definition attribute-id="endpoint">
+                <display-name xml:lang="x-default">Endpoint</display-name>
+                <type>string</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="apiKey">
+                <display-name xml:lang="x-default">API Key</display-name>
+                <type>password</type>
+            </attribute-definition>
+        </attribute-definitions>
+    </custom-type>
+</metadata>
+```
+
+**sites/RefArch/preferences.xml:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-03-31">
+    <custom-preferences>
+        <all-instances>
+            <preference preference-id="integrationEnabled">true</preference>
+        </all-instances>
+    </custom-preferences>
+</preferences>
+```
+
+**customobjects/IntegrationConfig.xml:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<custom-objects xmlns="http://www.demandware.com/xml/impex/customobject/2006-10-31">
+    <custom-object type-id="IntegrationConfig" object-id="production">
+        <object-attribute attribute-id="endpoint">https://api.integration.com/v1</object-attribute>
+    </custom-object>
+</custom-objects>
+```
+
+Import command:
+```bash
+b2c job import ./integration-import --wait --show-log
+```

package/content/guidance/b2c-cli/b2c-site-import-export/references/WORKFLOWS.md

@@ -0,0 +1,182 @@
+# Archive Workflows
+
+## Common Workflows
+
+### Adding a Custom Attribute to Products
+
+1. Create the metadata XML file:
+
+**meta/system-objecttype-extensions.xml:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="Product">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="vendorSKU">
+                <display-name xml:lang="x-default">Vendor SKU</display-name>
+                <type>string</type>
+                <mandatory-flag>false</mandatory-flag>
+                <externally-managed-flag>true</externally-managed-flag>
+            </attribute-definition>
+        </custom-attribute-definitions>
+        <group-definitions>
+            <attribute-group group-id="CustomAttributes">
+                <display-name xml:lang="x-default">Custom Attributes</display-name>
+                <attribute attribute-id="vendorSKU"/>
+            </attribute-group>
+        </group-definitions>
+    </type-extension>
+</metadata>
+```
+
+2. Create the directory structure:
+
+```
+my-import/
+└── meta/
+    └── system-objecttype-extensions.xml
+```
+
+3. Import:
+
+```bash
+b2c job import ./my-import
+```
+
+### Adding Site Preferences
+
+1. Create metadata for the preference:
+
+**meta/system-objecttype-extensions.xml:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <type-extension type-id="SitePreferences">
+        <custom-attribute-definitions>
+            <attribute-definition attribute-id="enableFeatureX">
+                <display-name xml:lang="x-default">Enable Feature X</display-name>
+                <type>boolean</type>
+                <default-value>false</default-value>
+            </attribute-definition>
+        </custom-attribute-definitions>
+    </type-extension>
+</metadata>
+```
+
+2. Create preference values:
+
+**sites/MySite/preferences.xml:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-03-31">
+    <custom-preferences>
+        <all-instances>
+            <preference preference-id="enableFeatureX">true</preference>
+        </all-instances>
+    </custom-preferences>
+</preferences>
+```
+
+3. Directory structure:
+
+```
+my-import/
+├── meta/
+│   └── system-objecttype-extensions.xml
+└── sites/
+    └── MySite/
+        └── preferences.xml
+```
+
+4. Import:
+
+```bash
+b2c job import ./my-import
+```
+
+### Creating a Custom Object Type
+
+1. Define the custom object:
+
+**meta/custom-objecttype-definitions.xml:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<metadata xmlns="http://www.demandware.com/xml/impex/metadata/2006-10-31">
+    <custom-type type-id="APIConfiguration">
+        <display-name xml:lang="x-default">API Configuration</display-name>
+        <staging-mode>source-to-target</staging-mode>
+        <storage-scope>site</storage-scope>
+        <key-definition attribute-id="configId">
+            <display-name xml:lang="x-default">Config ID</display-name>
+            <type>string</type>
+            <min-length>1</min-length>
+        </key-definition>
+        <attribute-definitions>
+            <attribute-definition attribute-id="endpoint">
+                <display-name xml:lang="x-default">API Endpoint</display-name>
+                <type>string</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="apiKey">
+                <display-name xml:lang="x-default">API Key</display-name>
+                <type>password</type>
+            </attribute-definition>
+            <attribute-definition attribute-id="isActive">
+                <display-name xml:lang="x-default">Active</display-name>
+                <type>boolean</type>
+                <default-value>true</default-value>
+            </attribute-definition>
+        </attribute-definitions>
+    </custom-type>
+</metadata>
+```
+
+2. Import:
+
+```bash
+b2c job import ./my-import
+```
+
+### Importing Custom Object Data
+
+**customobjects/APIConfiguration.xml:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<custom-objects xmlns="http://www.demandware.com/xml/impex/customobject/2006-10-31">
+    <custom-object type-id="APIConfiguration" object-id="payment-gateway">
+        <object-attribute attribute-id="endpoint">https://api.payment.com/v2</object-attribute>
+        <object-attribute attribute-id="isActive">true</object-attribute>
+    </custom-object>
+</custom-objects>
+```
+
+## Site Archive Structure
+
+```
+site-archive/
+├── services.xml                           # Service configurations (credentials, profiles, services)
+├── meta/
+│   ├── system-objecttype-extensions.xml   # Custom attributes on system objects
+│   └── custom-objecttype-definitions.xml  # Custom object type definitions
+├── sites/
+│   └── {SiteID}/
+│       ├── preferences.xml                # Site preference values
+│       └── library/
+│           └── content/
+│               └── content.xml            # Content assets
+├── catalogs/
+│   └── {CatalogID}/
+│       └── catalog.xml                    # Products and categories
+├── pricebooks/
+│   └── {PriceBookID}/
+│       └── pricebook.xml                  # Price definitions
+├── customobjects/
+│   └── {ObjectTypeID}.xml                 # Custom object instances
+└── inventory-lists/
+    └── {InventoryListID}/
+        └── inventory.xml                  # Inventory records
+```

package/content/guidance/b2c-cli/b2c-sites/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: b2c-sites
+description: List storefront sites, check site status, and manage cartridge paths on B2C Commerce instances using the b2c CLI. Use this skill whenever the user needs to discover site IDs, check which storefronts are online or offline, get site configuration as JSON, or view/modify the ordered cartridge path for a site or Business Manager. Also use when the user needs site information for scripting, CI/CD pipelines, or as input to other commands — even if they just say "what sites do I have" or "add this cartridge to my site".
+---
+
+# B2C Sites Skill
+
+Use the `b2c` CLI plugin to list and manage storefront sites on Salesforce B2C Commerce instances.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli sites list`).
+
+## Configuration & Authentication
+
+The CLI auto-discovers the target instance and credentials from `SFCC_*` environment variables (including project `.env`), the selected project-local or shared `dw.json`, and configuration plugins. `package.json` supplies only non-sensitive defaults. **Flags like `--server`, `--client-id`, and `--client-secret` are usually unnecessary** — only pass them to override what's auto-detected.
+
+Run `b2c setup inspect` to see the resolved configuration and which source provided each value (use `--json` for scripting; secrets stay masked by default). For precedence rules and troubleshooting, see the `b2c-cli:b2c-config` skill.
+
+## Commands
+
+### `b2c sites list`
+
+Lists all sites on a B2C Commerce instance, showing site ID, display name, and storefront status.
+
+```bash
+# list all sites on the configured instance
+b2c sites list
+
+# list sites on a specific server
+b2c sites list --server my-sandbox.demandware.net
+
+# list sites with JSON output (useful for parsing/automation)
+b2c sites list --json
+
+# use a specific instance from config
+b2c sites list --instance production
+
+# enable debug logging
+b2c sites list --debug
+```
+
+### Cartridge Path Management
+
+Manage the ordered list of active cartridges on a site. The singular alias `sites cartridge` also works.
+
+```bash
+# list the cartridge path for a storefront site
+b2c sites cartridges list --site-id RefArch
+
+# list the Business Manager cartridge path
+b2c sites cartridges list --bm
+
+# add a cartridge to the beginning of a site's path (default)
+b2c sites cartridges add plugin_applepay --site-id RefArch
+
+# add a cartridge to the end
+b2c sites cartridges add plugin_applepay --site-id RefArch --position last
+
+# add a cartridge after a specific cartridge
+b2c sites cartridges add plugin_applepay --site-id RefArch --position after --target app_storefront_base
+
+# add a cartridge to Business Manager
+b2c sites cartridges add bm_extension --bm --position first
+
+# remove a cartridge from a site
+b2c sites cartridges remove old_cartridge --site-id RefArch
+
+# replace the entire cartridge path
+b2c sites cartridges set "app_storefront_base:plugin_applepay:plugin_wishlists" --site-id RefArch
+
+# JSON output for automation
+b2c sites cartridges list --site-id RefArch --json
+```
+
+When OCAPI direct permissions for `/sites/*/cartridges` are unavailable, cartridge commands automatically fall back to site archive import/export. Business Manager (`--bm`) updates always use site archive import.
+
+**Key flags (inherited from InstanceCommand):**
+
+| Flag         | Short | Description                                |
+| ------------ | ----- | ------------------------------------------ |
+| `--server`   | `-s`  | B2C instance hostname (env: `SFCC_SERVER`) |
+| `--json`     |       | Output full site data as JSON              |
+| `--instance` |       | Named instance from config                 |
+| `--debug`    |       | Enable debug logging                       |
+
+**Output columns:** ID, Display Name, Status (storefront_status).
+
+**JSON output** returns the full site objects including all properties (useful for extracting channel IDs, custom preferences, and other site metadata not shown in the table).
+
+Site reads and cartridge-path writes run over SCAPI (the `site/sites` API) when `shortCode`, `tenantId`, and the `sfcc.sites` / `sfcc.sites.rw` scopes are configured. `auto` temporarily falls back to deprecated OCAPI on safe SCAPI rejections, and writes can fall back again to site archive import when direct APIs are unavailable.
+
+## Common Use Cases
+
+**Finding site IDs for other commands:** Many commands (e.g., site import/export) require a site ID. Use `sites list` to discover valid IDs:
+
+```bash
+b2c sites list
+# then use the ID in other commands
+b2c job export --site RefArch --site-data content,site_preferences
+```
+
+**Checking site status:** The status column shows the storefront status (online/offline) for each site, useful for verifying deployment state.
+
+**Scripting and automation:** Use `--json` to get machine-readable output for CI/CD pipelines:
+
+```bash
+b2c sites list --json | jq '.data[].id'
+```
+
+## Related Skills
+
+- **b2c-config** -- configure instances, credentials, and debug connection issues
+- **b2c-site-import-export** -- import/export site archives and metadata XML