# 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)

```json
{
  "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)

```json
{
  "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`).