feat: add CIP analytics topic, SDK client, and report tooling

.changeset/add-cip-topic-and-reports.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-cli': minor
+'@salesforce/b2c-tooling-sdk': minor
+---
+
+Add a new `cip` command topic for Commerce Intelligence platform (CCAC - Commerce Cloud Analytics) with `cip query` for raw SQL and curated `cip report <report-name>` subcommands for analytics workflows, including CIP host override support and tenant-based CIP instance targeting.

docs/.vitepress/config.mts

@@ -49,6 +49,7 @@ const guideSidebar = [
     items: [
       {text: 'Authentication Setup', link: '/guide/authentication'},
       {text: 'Account Manager', link: '/guide/account-manager'},
+      {text: 'Analytics Reports (CIP/CCAC)', link: '/guide/analytics-reports-cip-ccac'},
       {text: 'IDE Integration', link: '/guide/ide-integration'},
       {text: 'Scaffolding', link: '/guide/scaffolding'},
       {text: 'Security', link: '/guide/security'},
@@ -68,6 +69,7 @@ const guideSidebar = [
       {text: 'Overview', link: '/cli/'},
       {text: 'Code Commands', link: '/cli/code'},
       {text: 'Content Commands', link: '/cli/content'},
+      {text: 'CIP Commands', link: '/cli/cip'},
       {text: 'Job Commands', link: '/cli/jobs'},
       {text: 'Logs Commands', link: '/cli/logs'},
       {text: 'Sites Commands', link: '/cli/sites'},

docs/cli/cip.md

@@ -0,0 +1,246 @@
+---
+description: Run raw SQL and curated analytics reports against Commerce Intelligence Platform (CIP).
+---
+
+# CIP Commands
+
+Use `b2c cip` to query Commerce Intelligence Platform (CIP/CCAC) analytics data.
+
+::: tip Production and Non-Production Hosts
+By default, CIP uses the production analytics host for tenants ending in `_prd` and the staging analytics host for other tenant IDs. Use `--staging` to force the staging host, or `--cip-host` for an explicit override.
+:::
+
+## Command Overview
+
+| Command                           | Description                                    |
+| --------------------------------- | ---------------------------------------------- |
+| `b2c cip tables`                  | List tables from the CIP metadata catalog      |
+| `b2c cip describe <table>`        | Describe columns for a CIP table               |
+| `b2c cip query`                   | Run raw SQL (argument, file, or stdin)         |
+| `b2c cip report`                  | Report topic help and report command discovery |
+| `b2c cip report <report-command>` | Run a curated report command                   |
+
+::: warning Availability
+These commands target Commerce Cloud Analytics (CCAC) data and are primarily used with production analytics tenants. Non-production access is available when Reports & Dashboards data tracking is enabled for supported 26.1+ environments.
+:::
+
+## Authentication
+
+CIP commands use **OAuth client credentials only**.
+
+| Requirement           | How to provide                                 |
+| --------------------- | ---------------------------------------------- |
+| Client ID             | `--client-id` or `SFCC_CLIENT_ID`              |
+| Client Secret         | `--client-secret` or `SFCC_CLIENT_SECRET`      |
+| Tenant (CIP instance) | `--tenant-id` / `--tenant` or `SFCC_TENANT_ID` |
+
+Your API client must include the **Salesforce Commerce API** role with a tenant filter that includes your target instance.
+
+## Connection and Output Flags
+
+These flags are available on all CIP commands:
+
+| Flag           | Description                           | Default                                       |
+| -------------- | ------------------------------------- | --------------------------------------------- |
+| `--format`     | Output format: `table`, `csv`, `json` | `table`                                       |
+| `--fetch-size` | Frame fetch size for paging           | `1000`                                        |
+| `--cip-host`   | CIP host override                     | `jdbc.analytics.commercecloud.salesforce.com` |
+| `--staging`    | Use staging analytics host            | `false`                                       |
+
+## Query and Report Date Flags
+
+These flags are available on `cip query` and `cip report <report-command>` commands:
+
+| Flag     | Description                       | Default                    |
+| -------- | --------------------------------- | -------------------------- |
+| `--from` | Inclusive start date (YYYY-MM-DD) | First day of current month |
+| `--to`   | Inclusive end date (YYYY-MM-DD)   | Today                      |
+
+## b2c cip tables
+
+List tables from the CIP metadata catalog.
+
+### Usage
+
+```bash
+b2c cip tables [flags]
+```
+
+### Flags
+
+| Flag        | Description                                          |
+| ----------- | ---------------------------------------------------- |
+| `--schema`  | Metadata schema to inspect (default: `warehouse`)    |
+| `--pattern` | Table name pattern using SQL `LIKE` semantics        |
+| `--all`     | Include all table types (default filters to `TABLE`) |
+
+### Examples
+
+```bash
+# List warehouse tables
+b2c cip tables --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
+
+# Filter by table prefix
+b2c cip tables --tenant-id zzxy_prd --pattern "ccdw_aggr_%" --client-id <client-id> --client-secret <client-secret>
+
+# Include metadata/system tables
+b2c cip tables --tenant-id zzxy_prd --schema metadata --all --client-id <client-id> --client-secret <client-secret>
+```
+
+## b2c cip describe
+
+Describe table columns using CIP metadata catalog.
+
+### Usage
+
+```bash
+b2c cip describe <table> [flags]
+```
+
+### Flags
+
+| Flag       | Description                                                 |
+| ---------- | ----------------------------------------------------------- |
+| `--schema` | Metadata schema containing the table (default: `warehouse`) |
+
+### Examples
+
+```bash
+# Describe a warehouse table
+b2c cip describe ccdw_aggr_ocapi_request --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
+
+# Describe metadata system table
+b2c cip describe COLUMNS --schema metadata --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
+```
+
+## b2c cip query
+
+Run raw SQL directly against CIP.
+
+### Usage
+
+```bash
+b2c cip query [SQL] [flags]
+```
+
+### SQL Input Sources
+
+Provide SQL from exactly one source:
+
+1. Positional argument (`b2c cip query "SELECT ..."`)
+2. `--file <path>`
+3. Piped stdin (for example `cat query.sql | b2c cip query ...`)
+
+### Query-Specific Flags
+
+| Flag           | Description              |
+| -------------- | ------------------------ |
+| `--file`, `-f` | Read SQL query from file |
+
+### Placeholders
+
+`cip query` supports placeholder substitution:
+
+- `<FROM>` is replaced by `--from`
+- `<TO>` is replaced by `--to`
+
+### Examples
+
+```bash
+# Inline SQL argument
+b2c cip query \
+  --tenant-id zzxy_prd \
+  --client-id <client-id> \
+  --client-secret <client-secret> \
+  "SELECT submit_date, num_orders FROM ccdw_aggr_sales_summary LIMIT 10"
+
+# Non-production / staging analytics host
+b2c cip query \
+  --tenant-id zzxy_stg \
+  --staging \
+  --client-id <client-id> \
+  --client-secret <client-secret> \
+  "SELECT submit_date, num_orders FROM ccdw_aggr_sales_summary LIMIT 10"
+
+# Read SQL from file
+b2c cip query --file ./query.sql --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
+
+# Read SQL from stdin
+cat ./query.sql | b2c cip query --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
+```
+
+## b2c cip report
+
+Run curated reports using dedicated subcommands.
+
+### Usage
+
+```bash
+b2c cip report --help
+b2c cip report <report-command> [flags]
+```
+
+### Shared Report Flags
+
+| Flag         | Description                                 |
+| ------------ | ------------------------------------------- |
+| `--describe` | Show report metadata and parameter contract |
+| `--sql`      | Print generated SQL and exit                |
+
+Use `--sql` to pipe into `cip query`:
+
+```bash
+b2c cip report sales-analytics --site-id Sites-RefArch-Site --sql \
+  | b2c cip query --tenant-id zzxy_prd --client-id <client-id> --client-secret <client-secret>
+```
+
+### Report Commands
+
+| Command                        | Description                           | Extra Flags                  |
+| ------------------------------ | ------------------------------------- | ---------------------------- |
+| `sales-analytics`              | Daily sales performance with AOV/AOS  | `--site-id`                  |
+| `sales-summary`                | Detailed sales records                | `--site-id` (optional)       |
+| `ocapi-requests`               | OCAPI request volume and latency      | `--site-id`                  |
+| `top-selling-products`         | Top products by units/revenue         | `--site-id`                  |
+| `product-co-purchase-analysis` | Frequently co-purchased products      | `--site-id`                  |
+| `promotion-discount-analysis`  | Promotion discount impact             | none                         |
+| `search-query-performance`     | Search revenue and conversion metrics | `--site-id`, `--has-results` |
+| `payment-method-performance`   | Payment method adoption/performance   | `--site-id`                  |
+| `customer-registration-trends` | Registration trends by date/device    | `--site-id`                  |
+| `top-referrers`                | Referrer traffic share                | `--site-id`, `--limit`       |
+
+### Site ID Format
+
+For report commands that accept `--site-id`, the common CIP format is:
+
+`Sites-{siteId}-Site`
+
+If your value does not match this pattern, the command warns and still uses your provided value.
+
+### Examples
+
+```bash
+# Run a report
+b2c cip report sales-analytics \
+  --site-id Sites-RefArch-Site \
+  --from 2025-01-01 \
+  --to 2025-01-31 \
+  --tenant-id zzxy_prd \
+  --client-id <client-id> \
+  --client-secret <client-secret>
+
+# Show report parameter contract
+b2c cip report top-referrers --describe
+
+# Generate SQL only
+b2c cip report top-referrers --site-id Sites-RefArch-Site --limit 25 --sql
+```
+
+## Output Formats
+
+Both `cip query` and report commands support:
+
+- `--format table` (default)
+- `--format csv` (writes CSV to stdout)
+- `--format json` (writes JSON to stdout)
+- `--json` (global JSON mode)

docs/cli/index.md

@@ -47,6 +47,7 @@ These flags are available on all commands that interact with B2C instances:
 - [Sandbox Commands](./sandbox) - Create and manage On-Demand Sandboxes
 - [MRT Commands](./mrt) - Manage Managed Runtime (MRT) projects and deployments
 - [SLAS Commands](./slas) - Manage Shopper Login and Access Service (SLAS) API clients
+- [CIP Commands](./cip) - Run CIP SQL queries and curated analytics reports
 - [Custom APIs](./custom-apis) - SCAPI Custom API endpoint status
 
 ### Development