@taprootio/integration-sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taproot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# @taprootio/integration-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@taprootio/integration-sdk` is the public Node 22 kit for integrations that push their own content into Taproot. It has no third-party runtime dependencies and is versioned independently from the Taproot application.
+
+Taproot publishes accepted, immutable content; it does not call an integration during rendering or publishing. An integration receives signed webhooks that request reconciliation, then uses its installation credential to push pages, media, JSON documents, and placement fragments.
+
+## Install
+
+```sh
+npm install @taprootio/integration-sdk@0.1.1
+```
+
+The public manifest schema is exported at `@taprootio/integration-sdk/schema`. The fixtures under `@taprootio/integration-sdk/fixtures/...` are contract examples, not a local fixture host or a production deployment recipe.
+
+## Manifest
+
+The manifest is declarative data for registration, review, and owner consent. It does not cause Taproot to run integration code.
+
+```js
+import { assertValidManifest } from "@taprootio/integration-sdk";
+
+const manifest = assertValidManifest({
+  slug: "class-schedule",
+  displayName: "Class Schedule",
+  webhookEndpointUrl: "https://integration.example/webhooks/taproot",
+  settingsUrl: "https://integration.example/settings",
+  requestedCapabilities: ["pages.manage_own", "data.manage_own", "publish"],
+  offeredComponents: [],
+  externalScriptOrigins: [],
+  defaultPublishPolicy: "stage",
+  recommendedUninstallDisposition: "freeze",
+  contractVersion: "1",
+  pricingOptions: [{ id: "free", version: "1", quantityMin: 1, quantityMax: null, cadence: "free", catalogueItemKey: null }],
+});
+```
+
+`validateManifest` is a bounded local preflight. Taproot remains authoritative for DNS resolution, public-route validation, registry status, consent, and authorization. Do not treat a successful local validation as registration.
+
+## Credentials and content
+
+Publisher and installation credentials are separate authorities. Never put a browser session, a site-authoring key, or an owner credential in this client. Pass credentials when constructing the client; each method uses only the credential appropriate to its contract scope.
+
+```js
+import { TaprootIntegrationClient, createIdempotencyKey } from "@taprootio/integration-sdk";
+
+const client = new TaprootIntegrationClient({
+  // Canonical API base: include /api when Taproot serves its API beneath it.
+  baseUrl: "https://app.example/api",
+  installationCredential: process.env.TAPROOT_INSTALLATION_CREDENTIAL,
+  publisherCredential: process.env.TAPROOT_PUBLISHER_CREDENTIAL,
+});
+
+const sync = await client.createSync({
+  installationId,
+  mode: "full",
+  requestedSyncId: webhook.event.data.syncId,
+  idempotencyKey: createIdempotencyKey(),
+});
+
+await client.putManagedPage({
+  installationId,
+  syncId: sync.syncId,
+  idempotencyKey: createIdempotencyKey(),
+  page: {
+    externalId: "class-101", path: "/classes/class-101/", title: "Strength 101",
+    description: "A beginner strength class.", indexable: true, fragments: ["<p>Bring water.</p>"],
+    structuredData: [JSON.stringify({ "@context": "https://schema.org", "@type": "WebPage", "@id": "https://integration.example/classes#primary", name: "Classes" })],
+    primaryStructuredDataId: "https://integration.example/classes#primary", folder: "classes", tagIds: [],
+    includeInNavigation: false, publicationDate: "", archiveDate: "", includeInLatestPosts: false,
+  },
+});
+await client.completeSync({ installationId, syncId: sync.syncId, idempotencyKey: createIdempotencyKey() });
+```
+
+Keep an idempotency key with its one logical operation in durable application state. Content, sync, and fragment mutations retry a bounded number of transient failures with that same key. The SDK does not retry validation or authorization failures.
+
+`claimInstallation` deliberately does not retry after a transport failure or an unreadable successful response. The installation credential secret is returned only once; a lost successful claim response cannot recover it. Persist the secret before replying to the webhook. If the response is unknown, validate the installation and use the owner-visible claim reissue workflow when appropriate; do not submit the claim code repeatedly.
+
+Bundle admission is publisher-scoped. `requestBundleUpload` and `confirmBundleUpload` only create and confirm an immutable upload. Operator approval and owner pinning are separate Taproot-side authorities and are not SDK operations.
+
+## Webhooks
+
+Read request bytes with a size limit, then verify those same bytes before parsing JSON. The HMAC is over the ASCII timestamp, a period, and the exact body bytes: `ASCII(t + ".") + body`.
+
+```js
+import { claimWebhookReceipt, finishWebhookReceipt, verifyWebhookSignature } from "@taprootio/integration-sdk";
+
+const verified = verifyWebhookSignature({
+  headers: request.headers,
+  body: rawRequestBytes,
+  signingSecrets: signingSecretsByKeyId,
+});
+const claimed = await claimWebhookReceipt({ store: postgresWebhookReceipts, verified });
+if (claimed.state === "duplicate") return new Response(null, { status: 204 });
+if (claimed.state === "in_progress") return new Response(null, { status: 503, headers: { "Retry-After": "1" } });
+if (claimed.state === "conflict") return new Response(null, { status: 409 });
+
+try {
+  await process(verified.event);
+  await finishWebhookReceipt({ store: postgresWebhookReceipts, verified, token: claimed.token, status: "delivered" });
+  return new Response(null, { status: 204 });
+} catch (error) {
+  await finishWebhookReceipt({ store: postgresWebhookReceipts, verified, token: claimed.token, status: "failed" });
+  throw error;
+}
+```
+
+`WebhookReceiptStore` is intentionally an interface. Its `claim` operation must be atomic and durable across process restarts, keyed by delivery id and immutable signed metadata. An in-memory `Set` is not receipt persistence. Return `duplicate` only after the same immutable receipt is delivered. A current processing lease returns `in_progress`, so respond `503` rather than acknowledge it: Taproot must redeliver if that worker fails. A failed receipt or expired lease must be claimed again with a fresh token. A durable receipt gives at-least-once processing; it does not make external side effects exactly once. Recover expired processing leases in your database and make every downstream effect idempotent.
+
+During key rotation, keep active and overlapping retired HMAC secrets in `signingSecrets` until Taproot no longer sends either key id. Unknown key ids, stale timestamps, malformed signatures, modified body bytes, and mismatched delivery headers are rejected.
+
+## Settings handoff
+
+The owner settings redirect contains a five-minute RS256 handoff token. Strip it from the browser URL immediately and never log it, put it in analytics, or use it as a session. Verify the token, place a short-lived pending record in your service, then call the authoritative one-time confirmation before creating an integration-owned session.
+
+```js
+import { confirmHandoff, verifyHandoff } from "@taprootio/integration-sdk";
+
+const claims = await verifyHandoff({
+  token: handoffToken,
+  issuer: "https://app.taproot.io",
+  audience: integrationId,
+  installationId,
+  jwksUrl: "https://app.taproot.io/api/.well-known/taproot-integrations-jwks.json",
+});
+
+// Delete the local pending record before this request. If its response is lost,
+// do not replay the token: begin a new owner handoff.
+const session = await confirmHandoff({ client, claims, token: handoffToken });
+```
+
+`verifyHandoff` checks the token's exact RS256 header, JWK key selection, issuer, audience, installation binding, issued/expiry times, role, and claim shape. Set `issuer` to the exact operator-published `iss` value, not an API base URL, and configure the operator-published JWKS URL explicitly. The default `<issuer>/.well-known/taproot-integrations-jwks.json` is only suitable when the operator publishes keys at that derived URL. The JWKS cache observes the published lifetime, capped at five minutes. Confirmation checks the returned identity against verified claims and bounds the integration-owned session to 24 hours by default. There is no refresh credential.
+
+## Fragments and placements
+
+`validateFragment` is advisory feedback for obvious unsafe markup. It is not a copy of Taproot's sanitizer and cannot promise the same result. Send the original fragment to `putFragment`; the server validates final bytes, links them to the exact requested placement configuration revision, and selects them only through immutable publication. A static fragment must remain useful when an optional browser bundle is unavailable.
+
+`listPlacements` returns only the installation's placement identities and configuration. It never grants access to host page content. For stale configuration or fragment revision conflicts, fetch the latest placement, render against its exact configuration revision, and write a new idempotent operation rather than overwriting an older fragment.
+
+## Public boundaries
+
+This SDK deliberately excludes owner, administrator, operator, billing, registry-management, bundle-approval, and internal RPCs. It does not store credentials, execute integration bundles, provide an HTML sanitizer, or call Taproot from the published-site render path.

package/fixtures/manifest.valid.json

@@ -0,0 +1,28 @@
+{
+  "slug": "fixture-fitness",
+  "displayName": "Fixture Fitness Publisher",
+  "webhookEndpointUrl": "https://receiver.example.test/webhooks",
+  "settingsUrl": "https://receiver.example.test/settings",
+  "requestedCapabilities": [
+    "pages.manage_own",
+    "data.manage_own",
+    "media.manage_own",
+    "publish",
+    "site.pages.read"
+  ],
+  "offeredComponents": [],
+  "externalScriptOrigins": [],
+  "defaultPublishPolicy": "stage",
+  "recommendedUninstallDisposition": "freeze",
+  "contractVersion": "1",
+  "pricingOptions": [
+    {
+      "id": "free",
+      "version": "1",
+      "quantityMin": 1,
+      "quantityMax": null,
+      "cadence": "free",
+      "catalogueItemKey": null
+    }
+  ]
+}

package/fixtures/webhooks/v1/common.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/common.schema.json",
+  "$defs": {
+    "envelope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "version", "occurredAt", "integrationId", "installationId", "siteId", "data"],
+      "properties": {
+        "id": { "type": "string", "format": "uuid" },
+        "type": { "type": "string" },
+        "version": { "const": "1" },
+        "occurredAt": { "type": "string", "format": "date-time" },
+        "integrationId": { "type": "string", "format": "uuid" },
+        "installationId": { "type": "string", "format": "uuid" },
+        "siteId": { "type": "string", "format": "uuid" },
+        "data": true
+      }
+    },
+    "installationState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "revision", "grantedCapabilities", "publishPolicy", "contractVersion", "sourceKind", "sourceEngagementId", "sourceTerminationReason"],
+      "properties": {
+        "status": { "type": "string" },
+        "revision": { "type": "integer", "minimum": 0 },
+        "grantedCapabilities": { "type": "array", "items": { "type": "string" } },
+        "publishPolicy": { "enum": ["auto", "stage"] },
+        "contractVersion": { "type": "string" },
+        "sourceKind": { "enum": ["owner", "engagement"] },
+        "sourceEngagementId": { "type": ["string", "null"], "format": "uuid" },
+        "sourceTerminationReason": { "type": ["string", "null"] }
+      }
+    },
+    "publishedCandidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["candidateId", "revision"],
+      "properties": {
+        "candidateId": { "type": "string", "format": "uuid" },
+        "revision": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/fixtures/webhooks/v1/examples/installation.created.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000002","type":"installation.created","version":"1","occurredAt":"2025-01-01T00:00:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"installation":{"status":"pending_claim","revision":1,"grantedCapabilities":[],"publishPolicy":"stage","contractVersion":"1","sourceKind":"owner","sourceEngagementId":null,"sourceTerminationReason":null},"claimCode":"fixture-claim-code","claimExpiresAt":"2025-01-02T00:00:00Z"}}

package/fixtures/webhooks/v1/examples/installation.resumed.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000005","type":"installation.resumed","version":"1","occurredAt":"2025-01-01T00:03:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"status":"active","revision":4,"grantedCapabilities":[],"publishPolicy":"stage","contractVersion":"1","sourceKind":"owner","sourceEngagementId":null,"sourceTerminationReason":null}}

package/fixtures/webhooks/v1/examples/installation.suspended.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000004","type":"installation.suspended","version":"1","occurredAt":"2025-01-01T00:02:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"status":"suspended","revision":3,"grantedCapabilities":[],"publishPolicy":"stage","contractVersion":"1","sourceKind":"owner","sourceEngagementId":null,"sourceTerminationReason":null}}

package/fixtures/webhooks/v1/examples/installation.uninstalled.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000006","type":"installation.uninstalled","version":"1","occurredAt":"2025-01-01T00:04:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"status":"uninstalled","revision":5,"grantedCapabilities":[],"publishPolicy":"stage","contractVersion":"1","sourceKind":"owner","sourceEngagementId":null,"sourceTerminationReason":"owner_request"}}

package/fixtures/webhooks/v1/examples/installation.updated.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000003","type":"installation.updated","version":"1","occurredAt":"2025-01-01T00:01:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"status":"active","revision":2,"grantedCapabilities":[],"publishPolicy":"stage","contractVersion":"1","sourceKind":"owner","sourceEngagementId":null,"sourceTerminationReason":null}}

package/fixtures/webhooks/v1/examples/page.deleted.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000014","type":"page.deleted","version":"1","occurredAt":"2025-01-01T00:12:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"pageId":"80000000-0000-4000-8000-000000000001","externalId":"class-101","revision":15,"url":"/classes/class-101/"}}

package/fixtures/webhooks/v1/examples/page.published.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000013","type":"page.published","version":"1","occurredAt":"2025-01-01T00:11:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"pageId":"80000000-0000-4000-8000-000000000001","externalId":"class-101","publishedRevision":14,"url":"/classes/class-101/"}}

package/fixtures/webhooks/v1/examples/ping.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000001","type":"ping","version":"1","occurredAt":"2025-01-01T00:00:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"purpose":"endpoint_verification"}}

package/fixtures/webhooks/v1/examples/placement.created.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000008","type":"placement.created","version":"1","occurredAt":"2025-01-01T00:06:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"placementId":"60000000-0000-4000-8000-000000000001","componentId":"schedule","placementRevision":7,"config":{"location":"downtown","showCapacity":true}}}

package/fixtures/webhooks/v1/examples/placement.deleted.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000010","type":"placement.deleted","version":"1","occurredAt":"2025-01-01T00:08:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"placementId":"60000000-0000-4000-8000-000000000001","componentId":"schedule","placementRevision":9,"config":null}}

package/fixtures/webhooks/v1/examples/placement.updated.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000009","type":"placement.updated","version":"1","occurredAt":"2025-01-01T00:07:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"placementId":"60000000-0000-4000-8000-000000000001","componentId":"schedule","placementRevision":8,"config":{"location":"uptown","showCapacity":false}}}

package/fixtures/webhooks/v1/examples/publish.completed.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000011","type":"publish.completed","version":"1","occurredAt":"2025-01-01T00:09:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"deploymentId":"70000000-0000-4000-8000-000000000001","candidates":[{"candidateId":"50000000-0000-4000-8000-000000000001","revision":12}]}}

package/fixtures/webhooks/v1/examples/publish.failed.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000012","type":"publish.failed","version":"1","occurredAt":"2025-01-01T00:10:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"deploymentId":"70000000-0000-4000-8000-000000000002","candidateIds":["50000000-0000-4000-8000-000000000002"],"code":"render_failed"}}

package/fixtures/webhooks/v1/examples/sync.requested.json

@@ -0,0 +1 @@
+{"id":"00000000-0000-4000-8000-000000000007","type":"sync.requested","version":"1","occurredAt":"2025-01-01T00:05:00Z","integrationId":"10000000-0000-4000-8000-000000000001","installationId":"20000000-0000-4000-8000-000000000001","siteId":"30000000-0000-4000-8000-000000000001","data":{"reason":"reconcile","syncId":"40000000-0000-4000-8000-000000000001","candidateIds":["50000000-0000-4000-8000-000000000001","50000000-0000-4000-8000-000000000002"]}}

package/fixtures/webhooks/v1/installation.created.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/installation.created.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "installation.created" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["installation", "claimCode", "claimExpiresAt"],
+          "properties": {
+            "installation": { "$ref": "common.schema.json#/$defs/installationState" },
+            "claimCode": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "claimExpiresAt": { "type": "string", "format": "date-time" }
+          }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/installation.resumed.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/installation.resumed.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    { "properties": { "type": { "const": "installation.resumed" }, "data": { "$ref": "common.schema.json#/$defs/installationState" } } }
+  ]
+}

package/fixtures/webhooks/v1/installation.suspended.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/installation.suspended.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    { "properties": { "type": { "const": "installation.suspended" }, "data": { "$ref": "common.schema.json#/$defs/installationState" } } }
+  ]
+}

package/fixtures/webhooks/v1/installation.uninstalled.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/installation.uninstalled.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    { "properties": { "type": { "const": "installation.uninstalled" }, "data": { "$ref": "common.schema.json#/$defs/installationState" } } }
+  ]
+}

package/fixtures/webhooks/v1/installation.updated.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/installation.updated.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    { "properties": { "type": { "const": "installation.updated" }, "data": { "$ref": "common.schema.json#/$defs/installationState" } } }
+  ]
+}

package/fixtures/webhooks/v1/page.deleted.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/page.deleted.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "page.deleted" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["pageId", "externalId", "revision", "url"],
+          "properties": {
+            "pageId": { "type": "string", "format": "uuid" },
+            "externalId": { "type": "string", "minLength": 1 },
+            "revision": { "type": "integer", "minimum": 0 },
+            "url": { "type": "string", "format": "uri-reference" }
+          }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/page.published.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/page.published.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "page.published" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["pageId", "externalId", "publishedRevision", "url"],
+          "properties": {
+            "pageId": { "type": "string", "format": "uuid" },
+            "externalId": { "type": "string", "minLength": 1 },
+            "publishedRevision": { "type": "integer", "minimum": 0 },
+            "url": { "type": "string", "format": "uri-reference" }
+          }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/ping.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/ping.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "ping" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["purpose"],
+          "properties": { "purpose": { "type": "string", "minLength": 1 } }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/placement.created.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/placement.created.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "placement.created" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["placementId", "componentId", "placementRevision", "config"],
+          "properties": {
+            "placementId": { "type": "string", "format": "uuid" },
+            "componentId": { "type": "string", "minLength": 1 },
+            "placementRevision": { "type": "integer", "minimum": 0 },
+            "config": true
+          }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/placement.deleted.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/placement.deleted.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "placement.deleted" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["placementId", "componentId", "placementRevision", "config"],
+          "properties": {
+            "placementId": { "type": "string", "format": "uuid" },
+            "componentId": { "type": "string", "minLength": 1 },
+            "placementRevision": { "type": "integer", "minimum": 0 },
+            "config": true
+          }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/placement.updated.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/placement.updated.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "placement.updated" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["placementId", "componentId", "placementRevision", "config"],
+          "properties": {
+            "placementId": { "type": "string", "format": "uuid" },
+            "componentId": { "type": "string", "minLength": 1 },
+            "placementRevision": { "type": "integer", "minimum": 0 },
+            "config": true
+          }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/publish.completed.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/publish.completed.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "publish.completed" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["deploymentId", "candidates"],
+          "properties": {
+            "deploymentId": { "type": "string", "format": "uuid" },
+            "candidates": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/publishedCandidate" } }
+          }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/publish.failed.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/publish.failed.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "publish.failed" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["deploymentId", "candidateIds", "code"],
+          "properties": {
+            "deploymentId": { "type": "string", "format": "uuid" },
+            "candidateIds": { "type": "array", "items": { "type": "string", "format": "uuid" } },
+            "code": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  ]
+}

package/fixtures/webhooks/v1/schema-index.json

@@ -0,0 +1,19 @@
+{
+  "version": "1",
+  "events": {
+    "ping": "ping.schema.json",
+    "installation.created": "installation.created.schema.json",
+    "installation.updated": "installation.updated.schema.json",
+    "installation.suspended": "installation.suspended.schema.json",
+    "installation.resumed": "installation.resumed.schema.json",
+    "installation.uninstalled": "installation.uninstalled.schema.json",
+    "sync.requested": "sync.requested.schema.json",
+    "placement.created": "placement.created.schema.json",
+    "placement.updated": "placement.updated.schema.json",
+    "placement.deleted": "placement.deleted.schema.json",
+    "publish.completed": "publish.completed.schema.json",
+    "publish.failed": "publish.failed.schema.json",
+    "page.published": "page.published.schema.json",
+    "page.deleted": "page.deleted.schema.json"
+  }
+}

package/fixtures/webhooks/v1/signature-vector.json

@@ -0,0 +1,9 @@
+{
+  "algorithm": "HMAC-SHA256",
+  "signingSecretBase64": "SmVmZQ==",
+  "timestamp": 1735689600,
+  "keyId": "90000000-0000-4000-8000-000000000001",
+  "bodyFile": "examples/installation.created.json",
+  "bodySha256": "01a0fcd0a324d46ede4a7ba87dcd2a3239996f1b1b17cb44abcd24d3a9a19114",
+  "header": "t=1735689600,k=90000000-0000-4000-8000-000000000001,v1=b13fa92de238838f31de4b2ac3f9149ce87c5f5061893b194cd2104f918ddccf"
+}

package/fixtures/webhooks/v1/sync.requested.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.taproot.test/integrations/webhooks/v1/sync.requested.schema.json",
+  "allOf": [
+    { "$ref": "common.schema.json#/$defs/envelope" },
+    {
+      "properties": {
+        "type": { "const": "sync.requested" },
+        "data": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["reason", "syncId", "candidateIds"],
+          "properties": {
+            "reason": { "enum": ["scheduled", "owner", "placement_changed", "reconcile"] },
+            "syncId": { "type": "string", "format": "uuid" },
+            "candidateIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }
+          }
+        }
+      }
+    }
+  ]
+}