Qortal-Nextcloud-Integration/docs/product/connector-catalog-contract-v1.md

Connector Catalog Contract v1

This document defines the canonical CHD connector contract for NuQloud product catalog discovery.

Endpoint

• Method: POST
• Path: /api/sovereign/v1/billing/catalog

Required request headers

• Accept: application/json
• Content-Type: application/json
• Authorization: Bearer <instance-token> (when configured)
• X-SC-Signature: <hmac_sha256(body, instance-secret)> (when configured)

Request body (canonical)

{
  "instanceId": "sc-example-001",
  "nextcloudPublicUrl": "https://cloud.example.com",
  "packageTier": "nuqloud_starter",
  "billingProvider": "paymenter",
  "billingSyncMode": "managed",
  "billingScope": "instance",
  "audience": "MSP_NoBrand_User",
  "catalogContract": "sc.billing.catalog.v1",
  "contract": {
    "name": "sc.billing.catalog",
    "version": "1.0"
  },
  "categoryId": "42",
  "source": "nextcloud-plugin"
}

Optional request context keys used by current connector builds:

• audience / audienceKey / catalogAudience
• billingScope (instance or user)
• billingSubject (for user-scoped requests)
• catalogContext (metadata object)

Response body (canonical)

{
  "ok": true,
  "catalogContract": "sc.billing.catalog.v1",
  "catalog": {
    "subscriptions": [
      {
        "code": "nuqloud_starter",
        "tier": "nuqloud_starter",
        "name": "Starter",
        "price": "",
        "summary": "Single-user or lighter private-cloud plan.",
        "features": [
          "500 initial publishing credits",
          "10 GB on-instance storage",
          "10 GB decentralized publish storage"
        ],
        "category": "package",
        "purchaseType": "subscription",
        "purchaseInterval": "monthly",
        "actionLabel": "Upgrade"
      }
    ],
    "addons": [
      {
        "code": "credits-1000",
        "name": "1000 Decentralized Publishing Credits",
        "price": "",
        "summary": "Top-up for decentralized publishing operations.",
        "category": "addon",
        "purchaseType": "one_time",
        "purchaseInterval": "one_time",
        "actionLabel": "Buy credits",
        "quantity": "1",
        "credits": 1000
      },
      {
        "code": "capacity-25",
        "name": "25GB Additional Storage",
        "price": "",
        "summary": "Adds 25 GB on-instance storage and 25 GB decentralized publish storage.",
        "category": "addon",
        "purchaseType": "monthly_addon",
        "purchaseInterval": "monthly",
        "actionLabel": "Add monthly add-on",
        "quantity": "1"
      }
    ]
  },
  "warnings": []
}

Contract rules

1. catalogContract must be present and set to sc.billing.catalog.v1.
2. catalog.subscriptions and catalog.addons must be arrays (can be empty).
3. Every item must have a stable code.
4. code values must be unique within each list.
5. purchaseType should be one of:
   • subscription
   • one_time
   • monthly_addon
6. purchaseInterval should be:
   • monthly for recurring
   • one_time for one-off
7. codeByTier and priceByTier are optional maps for tier-dependent add-ons.

Compatibility policy

1. Current plugin keeps a compatibility parser for legacy response shapes.
2. Connector should migrate to canonical shape and include catalogContract.
3. Future breaking changes require a new contract id (example: sc.billing.catalog.v2).