Catalog schema

Field-by-field documentation for the structured catalog at/catalog.json.

Schema version: 1. No compatibility contract.Ingesters adapt to schema changes. The page documents what is true today; older versions are not preserved at separate URLs. This framing follows Thinwrap's "internal-with-public-availability" stance — Thinwrap publishes the catalog as a courtesy; consumers do not get version pinning.

Top-level shape

Field	Type	Description
`$schema`	`string`	Pointer to this page (informal; not a JSON-Schema validator URL).
`version`	`"1"`	Schema-format version. Bumps on breaking shape change.
`generatedAt`	`string` (ISO-8601)	Build-time aggregator run timestamp.
`packages`	`Package[]`	One entry per published Thinwrap library.

Package entry

Field	Type	Description
`repoName`	`"notifications-ts" \| "notifications-php" \| "location-ts" \| "location-php"`	Canonical repo + page slug.
`language`	`"typescript" \| "php"`	Implementation language.
`scope`	`"notifications" \| "location"`	Domain coverage.
`registry`	`"npm" \| "packagist"`	Package registry.
`registryUrl`	`string` (URL)	Public registry page.
`packageName`	`string`	Registry-canonical name (e.g. `@thinwrap/notifications`).
`version`	`string`	Latest published version.
`agentDocUrl`	`string` (URL)	Repo-internal `.ai/guidelines.md` for LLM authoring.
`agentDocFreshness`	`"current" \| "stale"`	Agent-doc currency tag.
`providers`	`Provider[]`	Every connector this package ships.

Provider entry

Field	Type	Description
`providerId`	`string`	Lowercase id (e.g. `sendgrid`, `mapbox`).
`humanName`	`string`	Display label.
`channel`	`"email" \| "sms" \| "push" \| "chat"` (notifications only)	Delivery channel.
`operation`	`"routing" \| "matrix" \| "geocoding" \| "isochrone"` (location only)	Single primary operation if applicable.
`operations`	`string[]`	Operations supported (location providers commonly ship multiple).
`auth.method`	enum (see below)	HTTP auth strategy.
`auth.tokenLifecycle`	`"opaque-static" \| "per-call-signed"`	Whether the token is rotated/signed per call.
`auth.tokenCacheHookSupported`	`boolean`	Whether BYO token-cache hook applies (FCM/APNs etc.).
`regionalEndpoints`	`string[]`	Provider's region-routed endpoints. Empty if not regional.
`rateLimitDocsUrl`	`string \| null`	Provider's published rate-limit documentation.
`novuProviderId`	`string \| null`	Mapping to Novu's provider enum (notifications only).

Enum values

`auth.method`

header — API key in a request header.
query — API key in a query string.
basic — HTTP Basic.
bearer — Bearer token.
rs256-jwt — RS256-signed JWT (e.g. FCM).
es256-jwt — ES256-signed JWT (e.g. APNs).
webhook-url — Pre-signed webhook URL (chat).
aws-sig-v4 — AWS Signature v4.

JSON Schema artifact

A machine-validatable JSON Schema export is published at/catalog.schema.json. Same disclaimer applies — no compatibility contract. The full schema is reproduced below for copy/paste.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thinwrap.dev/catalog.schema.json",
  "title": "Thinwrap catalog",
  "description": "Schema for https://thinwrap.dev/catalog.json. Documented at /catalog-spec. No compatibility contract — ingesters adapt to changes.",
  "type": "object",
  "required": ["version", "generatedAt", "packages"],
  "properties": {
    "$schema": { "type": "string", "format": "uri" },
    "version": { "type": "string", "const": "1" },
    "generatedAt": { "type": "string", "format": "date-time" },
    "packages": {
      "type": "array",
      "items": { "$ref": "#/$defs/Package" }
    }
  },
  "$defs": {
    "Package": {
      "type": "object",
      "required": [
        "repoName",
        "language",
        "scope",
        "registry",
        "registryUrl",
        "packageName",
        "version",
        "agentDocUrl",
        "agentDocFreshness",
        "providers"
      ],
      "properties": {
        "repoName": {
          "type": "string",
          "enum": [
            "notifications-ts",
            "notifications-php",
            "location-ts",
            "location-php"
          ]
        },
        "language": { "type": "string", "enum": ["typescript", "php"] },
        "scope": { "type": "string", "enum": ["notifications", "location"] },
        "registry": { "type": "string", "enum": ["npm", "packagist"] },
        "registryUrl": { "type": "string", "format": "uri" },
        "packageName": { "type": "string", "minLength": 1 },
        "version": { "type": "string", "minLength": 1 },
        "agentDocUrl": { "type": "string", "format": "uri" },
        "agentDocFreshness": { "type": "string", "enum": ["current", "stale"] },
        "providers": { "type": "array", "items": { "$ref": "#/$defs/Provider" } }
      },
      "additionalProperties": false
    },
    "Provider": {
      "type": "object",
      "required": [
        "providerId",
        "humanName",
        "auth",
        "regionalEndpoints",
        "rateLimitDocsUrl"
      ],
      "properties": {
        "providerId": { "type": "string", "minLength": 1 },
        "humanName": { "type": "string", "minLength": 1 },
        "channel": {
          "type": "string",
          "enum": ["email", "sms", "push", "chat"]
        },
        "operation": {
          "type": "string",
          "enum": ["routing", "matrix", "geocoding", "isochrone"]
        },
        "operations": { "type": "array", "items": { "type": "string" } },
        "auth": {
          "type": "object",
          "required": ["method", "tokenLifecycle", "tokenCacheHookSupported"],
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "header",
                "query",
                "basic",
                "bearer",
                "rs256-jwt",
                "es256-jwt",
                "webhook-url",
                "aws-sig-v4"
              ]
            },
            "tokenLifecycle": {
              "type": "string",
              "enum": ["opaque-static", "per-call-signed"]
            },
            "tokenCacheHookSupported": { "type": "boolean" }
          },
          "additionalProperties": false
        },
        "regionalEndpoints": { "type": "array", "items": { "type": "string" } },
        "rateLimitDocsUrl": {
          "oneOf": [{ "type": "string", "format": "uri" }, { "type": "null" }]
        },
        "novuProviderId": {
          "oneOf": [{ "type": "string" }, { "type": "null" }]
        }
      },
      "additionalProperties": false,
      "$comment": "novuProviderId is intentionally NOT in `required`. Notifications providers carry it (string or null for non-Novu-mapped providers); location providers omit it entirely. Keeping it optional lets a single Provider definition validate both scopes; the per-scope `channel` vs `operation` distinction is enforced by the source frontmatter validator (src/utils/frontmatter-validator.ts), which is scope-aware."
    }
  }
}

Source

The catalog is derived from the published packages and their per-connector READMEs; the machine-readable schema is the JSON Schema artifact above.