@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.18

package/example-configs/products/content/operations.mdx

@@ -0,0 +1,50 @@
+---
+id: guide.operations
+title: Daily operating checklist
+summary: A shared source page published explicitly into each supported product release.
+slug: /operations
+shared: true
+publications:
+  - { product: payments, channel: production, version: v2 }
+  - { product: payments, channel: production, version: v3 }
+  - { product: reporting, channel: production, version: v1 }
+---
+Run this checklist before closing a reporting period. The same source page serves Payments v2, Payments v3, and Reporting v1; each publication keeps its own links and navigation.
+
+## Before you start
+
+- Confirm the product and release shown in the page header.
+- Check the account and currency used for the day's activity.
+- Keep a list of orders that still need investigation.
+
+## Close the day
+
+1. Review completed payments and unsettled orders.
+2. Compare the settlement total with the matching reporting period.
+3. Record any unresolved discrepancy and assign an owner.
+
+<ForPublication product="payments" version="v2">
+
+### Payments v2 check
+
+Match settlement records using the merchant reference. This instruction belongs only to the Payments v2 publication.
+
+</ForPublication>
+
+<ForPublication product="payments" version="v3">
+
+### Payments v3 check
+
+Match settlement records using the order reference. Use the idempotency key only when investigating retries.
+
+</ForPublication>
+
+<ForFeature allOf="scheduled-exports">
+
+## Check automatic deliveries
+
+Confirm the latest scheduled export arrived and covers the expected period. This section is compiled into Customer A's edition.
+
+</ForFeature>
+
+[Return to this product's getting-started guide](doc:guide.start).

package/example-configs/products/content/payments-v2.mdx

@@ -0,0 +1,30 @@
+---
+id: guide.start
+title: Start with Payments v2
+summary: Configure the reference-based payment workflow used by Customer B.
+slug: /start
+product: payments
+version: v2
+shared: true
+---
+Payments v2 uses a merchant reference to track a payment from creation through settlement. This edition follows the v2 workflow while Reporting remains on its own v1 release.
+
+## Create a payment
+
+1. Choose a unique merchant reference for the order.
+2. Submit the amount and currency with that reference.
+3. Save the returned payment identifier before confirming the order.
+
+```json
+{
+  "merchantReference": "order-1042",
+  "amount": 12500,
+  "currency": "USD"
+}
+```
+
+## Confirm settlement
+
+Match the merchant reference on the settlement record to the original order. Retry a failed submission with the same reference so reconciliation can identify it.
+
+[Review the daily operating checklist](doc:guide.operations).

package/example-configs/products/content/payments-v3.mdx

@@ -0,0 +1,38 @@
+---
+id: guide.start
+title: Start with Payments v3
+summary: Use an idempotency key and a separate reconciliation reference in Payments v3.
+slug: /start
+product: payments
+version: v3
+shared: true
+---
+Payments v3 separates request retries from business reconciliation. Use an idempotency key for retry safety and an order reference for settlement matching. Reporting can stay on v1 when Payments moves to v3.
+
+## Create a payment
+
+1. Generate an idempotency key for this payment attempt.
+2. Send the order reference separately from the key.
+3. Save the returned payment identifier and status.
+
+```json
+{
+  "idempotencyKey": "payment-attempt-1042",
+  "orderReference": "order-1042",
+  "amount": { "value": 12500, "currency": "USD" }
+}
+```
+
+## Retry a submission
+
+Reuse the idempotency key for the same attempt. A new order needs a new key. Keep the order reference stable when comparing payment and settlement records.
+
+<ForFeature allOf="priority-settlement">
+
+## Settle an eligible payment sooner
+
+Your edition includes priority settlement. [Prepare and submit a priority batch](doc:guide.priority-settlement) after the payment reaches the eligible state.
+
+</ForFeature>
+
+[Review the daily operating checklist](doc:guide.operations).

package/example-configs/products/content/priority-settlement.mdx

@@ -0,0 +1,23 @@
+---
+id: guide.priority-settlement
+title: Submit a priority settlement batch
+summary: Check eligibility and submit a Payments v3 priority batch.
+slug: /priority-settlement
+product: payments
+version: v3
+requires:
+  allOf: [priority-settlement]
+---
+Priority settlement is included in Customer A's feature grants. This entire page is absent from an edition without that grant.
+
+## Prepare the batch
+
+1. Select payments that have completed authorization and meet the settlement rules.
+2. Confirm the settlement account, currency, and batch total.
+3. Assign a unique batch reference and submit the batch once.
+
+## Check the result
+
+Save the batch identifier and compare its accepted count with the submitted count. Investigate rejected entries before retrying them; do not resubmit payments already accepted into the batch.
+
+[Return to Payments v3](doc:guide.start).

package/example-configs/products/content/reporting-v1.mdx

@@ -0,0 +1,36 @@
+---
+id: guide.start
+title: Start with Reporting v1
+summary: Reconcile completed payments with a daily reporting period.
+slug: /start
+product: reporting
+version: v1
+shared: true
+---
+Reporting v1 organizes completed transactions by reporting period. Both customer editions use this release, even though they use different Payments versions.
+
+## Prepare a daily report
+
+1. Select a completed reporting period.
+2. Choose the account and settlement currency.
+3. Generate the report and record its period and creation time.
+
+| Field | Check before reconciliation |
+| --- | --- |
+| Reporting period | Covers the day being reconciled. |
+| Currency | Matches the settlement account. |
+| Order reference | Identifies the original order. |
+
+## Compare totals
+
+Compare the report total to the settlement record. Investigate missing orders and currency mismatches before closing the period.
+
+<ForFeature allOf="scheduled-exports">
+
+## Receive reports automatically
+
+Your edition includes scheduled exports. [Configure a recurring delivery](doc:guide.scheduled-exports) after reviewing the account and reporting period.
+
+</ForFeature>
+
+[Use the shared operating checklist](doc:guide.operations).

package/example-configs/products/content/scheduled-exports.mdx

@@ -0,0 +1,23 @@
+---
+id: guide.scheduled-exports
+title: Schedule a daily reporting export
+summary: Choose a delivery period and verify the first Reporting v1 export.
+slug: /scheduled-exports
+product: reporting
+version: v1
+requires:
+  allOf: [scheduled-exports]
+---
+Scheduled exports are included in Customer A's feature grants. Customer B uses the same Reporting v1 release with manual reporting instructions.
+
+## Configure the delivery
+
+1. Select the account, reporting period, and settlement currency.
+2. Choose a daily delivery time after the reporting period closes.
+3. Set the delivery destination and save the schedule.
+
+## Verify the first export
+
+Check that the first delivered file uses the expected period and currency. Compare its row count and total with a report generated manually for the same period.
+
+[Return to Reporting v1](doc:guide.start).

package/example-configs/products/docs.config.yaml

@@ -0,0 +1,56 @@
+schemaVersion: 1
+
+site:
+  title: Harbor product documentation
+  editionBadge: always
+
+theme:
+  preset: reef
+  palette: harbor
+  mode: system
+
+publications:
+  defaults: { channel: production, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  products:
+    payments:
+      label: Payments
+      pathPrefix: /payments
+      defaultVersion: v3
+      versions:
+        v2: { pathPrefix: /v2 }
+        v3: { pathPrefix: /v3 }
+    reporting:
+      label: Reporting
+      pathPrefix: /reporting
+      defaultVersion: v1
+      versions:
+        v1: { pathPrefix: /v1 }
+  enabled:
+    - { product: payments, channel: production, version: v2 }
+    - { product: payments, channel: production, version: v3 }
+    - { product: reporting, channel: production, version: v1 }
+
+profiles:
+  manifest: ./skus.yaml
+  requireClassification: true
+  pruneNavigation: true
+
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    language: en
+    access: { policy: public }
+
+navigation:
+  - { id: start, doc: guide.start }
+  - { id: operations, doc: guide.operations }
+  - { id: priority-settlement, doc: guide.priority-settlement }
+  - { id: scheduled-exports, doc: guide.scheduled-exports }
+
+outputs:
+  html:
+    highlighting: { provider: none }
+    shareImages: false

package/example-configs/products/profiles/all-releases.yaml

@@ -0,0 +1,9 @@
+schemaVersion: 1
+skus:
+  - { id: business, revision: '2026' }
+site:
+  title: Harbor - All publications
+  header:
+    links:
+      - { label: Payments, href: /payments/v3/start }
+      - { label: Reporting, href: /reporting/v1/start }

package/example-configs/products/profiles/customer-a.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+skus:
+  - { id: business, revision: '2026' }
+site:
+  title: Harbor - Customer A
+  header:
+    links:
+      - { label: Payments, href: /payments/v3/start }
+      - { label: Reporting, href: /reporting/v1/start }
+publications:
+  enabled:
+    - { product: payments, channel: production, version: v3 }
+    - { product: reporting, channel: production, version: v1 }

package/example-configs/products/profiles/customer-b.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+skus:
+  - { id: business, revision: '2025' }
+site:
+  title: Harbor - Customer B
+  header:
+    links:
+      - { label: Payments, href: /payments/v2/start }
+      - { label: Reporting, href: /reporting/v1/start }
+publications:
+  enabled:
+    - { product: payments, channel: production, version: v2 }
+    - { product: reporting, channel: production, version: v1 }

package/example-configs/products/skus.yaml

@@ -0,0 +1,11 @@
+schemaVersion: 1
+features:
+  priority-settlement:
+    description: Priority settlement instructions for Payments v3.
+  scheduled-exports:
+    description: Scheduled export instructions for Reporting v1.
+skus:
+  business:
+    revisions:
+      '2025': { features: [] }
+      '2026': { features: [priority-settlement, scheduled-exports] }

package/examples/content-delivery/preview.mjs

@@ -24,7 +24,7 @@ const clientDirectory = path.dirname(clientEntry);
 const clientFiles = new Map([
   ['/shoalrun/content-delivery.js', clientEntry],
   ['/shoalrun/content-delivery-contract.js', path.join(clientDirectory, 'content-delivery-contract.js')],
-  ...['content-mount', 'content-delivery-validation', 'content-delivery-transport', 'content-rest-client', 'content-rest-contract'].map(name => [`/shoalrun/${name}.js`, path.join(clientDirectory, `${name}.js`)]),
+  ...['content-mount', 'content-delivery-validation', 'content-delivery-transport', 'content-rest-client', 'content-rest-contract', 'publication-identity'].map(name => [`/shoalrun/${name}.js`, path.join(clientDirectory, `${name}.js`)]),
 ]);
 const mount = '/help/releases/demo/';
 const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.md': 'text/markdown; charset=utf-8', '.png': 'image/png' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.17",
+  "version": "0.1.0-alpha.18",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/schemas/content-export.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://shoalrun.com/schemas/content-export.schema.json",
-  "title": "Shoalrun content delivery manifest, version 1",
+  "title": "Shoalrun content delivery manifest, versions 1 and 2",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -18,7 +18,10 @@
   ],
   "properties": {
     "schemaVersion": {
-      "const": 1
+      "enum": [
+        1,
+        2
+      ]
     },
     "kind": {
       "const": "shoalrun-content-export"
@@ -229,6 +232,10 @@
         "language": {
           "type": "string",
           "minLength": 1
+        },
+        "product": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },
@@ -487,5 +494,36 @@
         }
       ]
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "schemaVersion": {
+            "const": 1
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "publication": {
+            "not": {
+              "required": [
+                "product"
+              ]
+            }
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "publication": {
+            "required": [
+              "product"
+            ]
+          }
+        }
+      }
+    }
+  ]
 }