Automated doc/artifact sync pipeline for crowdsplit and contracts releases

.changeset/payments-generated-types-layer.md

@@ -0,0 +1,5 @@
+---
+"@oaknetwork/payments-sdk": minor
+---
+
+Add an internal generated types layer sourced from the Crowdsplit OpenAPI contract (v2.1.1). Types are generated into `src/generated/` from a committed spec snapshot and kept in sync by CI. Not part of the public API surface yet; services will adopt them progressively.

.gitattributes

@@ -0,0 +1,5 @@
+# Generated files — collapsed by default in PR review (still expandable).
+packages/payments/src/generated/** linguist-generated=true
+packages/payments/openapi/openapi.bundled.yaml linguist-generated=true
+packages/contracts/src/contracts/*/abi.ts linguist-generated=true
+packages/contracts/src/contracts/abi-manifest.json linguist-generated=true

.github/workflows/backend-sync.yml

@@ -129,6 +129,9 @@ jobs:
                 `2. Determine if SDK types, services, or methods need updating`,
                 `3. Follow SDK patterns (Result<T,E>, factory functions, withAuth)`,
                 ``,
+                `> **Note:** when this change reaches a stable release, the Crowdsplit API Sync workflow`,
+                `> will open a PR here automatically with the updated spec snapshot and generated types.`,
+                ``,
                 `---`,
                 `${runLink} · _Auto-generated by Backend Staging Sync workflow_`,
               ].join('\n'),

.github/workflows/ci.yml

@@ -40,6 +40,9 @@ jobs:
       - name: Build all packages
         run: pnpm -r --workspace-concurrency=Infinity build
 
+      - name: Check generated ABI modules against manifest
+        run: pnpm --filter @oaknetwork/contracts-sdk abis:check
+
       - name: Run tests with coverage (enforces 100% threshold)
         run: pnpm -r --workspace-concurrency=Infinity test --coverage
         env:
@@ -68,3 +71,42 @@ jobs:
 
       - name: Run lint
         run: pnpm -r --workspace-concurrency=Infinity lint
+
+  # Verifies packages/payments/src/generated/api.ts is exactly what the
+  # committed spec snapshot generates - catches hand edits to the generated
+  # file, snapshot edits without regeneration, and openapi-typescript bumps
+  # without regeneration. Node 20 pinned (openapi-typescript engine floor);
+  # single job on purpose - no need to triple it across the node matrix.
+  api-types-freshness:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Regenerate types from committed spec snapshot
+        run: pnpm --filter @oaknetwork/payments-sdk exec openapi-typescript openapi/openapi.bundled.yaml -o src/generated/api.ts
+
+      - name: Fail on drift
+        run: |
+          if ! git diff --exit-code -- packages/payments/src/generated; then
+            echo "::error::packages/payments/src/generated is out of sync with the committed spec snapshot." >&2
+            echo "Never hand-edit src/generated - re-run scripts/sync-crowdsplit.mjs (or the regen command above) and commit the result." >&2
+            exit 1
+          fi