feat: @alchemy/data-apis — dependency-free Data SDK (approved direction)

.eslintignore

@@ -14,3 +14,7 @@ site/.vitepress/cache/**/*
 **/test-results/*
 **/playwright-report/*
 pnpm-lock.yaml
+
+# codegen: committed spec snapshots (generated .ts files instead carry a
+# file-level eslint-disable banner so lint-staged can pass them explicitly)
+api-codegen/specs/**

.github/workflows/bump-api-specs.yml

@@ -0,0 +1,63 @@
+name: Bump API spec snapshots
+
+# Re-snapshots the bundled OpenAPI/OpenRPC specs from alchemyplatform/docs
+# (public) at its current main, regenerates SDK internals, and opens a PR if
+# anything changed. The manifest validation inside `pnpm generate` hard-fails
+# the run if an operation the SDK depends on was renamed or removed — that
+# failure is the drift alarm and needs a human decision, not a merge.
+#
+# Manual for now; switch `workflow_dispatch` to a schedule (or a
+# repository_dispatch from the docs repo's publish workflow) once the cadence
+# is settled.
+
+on:
+  workflow_dispatch:
+
+jobs:
+  bump-specs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+        with:
+          repository: alchemyplatform/docs
+          path: .docs-checkout
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Install docs dependencies
+        run: pnpm install --ignore-scripts
+        working-directory: .docs-checkout
+
+      - name: Snapshot specs from docs main
+        run: pnpm tsx api-codegen/src/cli.ts snapshot --docs "$GITHUB_WORKSPACE/.docs-checkout"
+
+      - name: Regenerate SDK internals
+        run: |
+          pnpm run build:libs
+          pnpm run generate
+
+      - name: Remove docs checkout before PR
+        run: rm -rf .docs-checkout
+
+      - name: Open PR if anything changed
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "chore(api-codegen): bump spec snapshots from docs main"
+          title: "chore(api-codegen): bump API spec snapshots"
+          body: |
+            Automated re-snapshot of the bundled OpenAPI/OpenRPC specs from
+            `alchemyplatform/docs` main, plus regenerated SDK internals.
+
+            Review the `api-codegen/specs/` diff for what moved
+            upstream and the `src/generated/` diff for the type impact.
+            Public types in `packages/data-apis/src/types.ts` are aliases —
+            check whether any public-surface change warrants a semver note.
+          branch: chore/bump-api-specs
+          delete-branch: true

.github/workflows/on-pull-request.yml

@@ -186,6 +186,12 @@ jobs:
       - name: Typecheck Test
         run: pnpm run test:typecheck
 
+      - name: Check generated API code is up to date
+        run: |
+          pnpm run generate
+          git diff --exit-code packages/*/src/generated api-codegen/specs || \
+            (echo "::error::Generated API code is out of date or spec snapshots were hand-edited. Run 'pnpm generate' and commit the changes." && exit 1)
+
       - name: Check SDK reference docs are up to date
         run: |
           pnpm run docs:sdk

api-codegen/README.md

@@ -0,0 +1,42 @@
+# @alchemy/api-codegen
+
+Internal (unpublished) codegen tool that generates SDK type internals from the
+docs repo's bundled OpenAPI/OpenRPC specs. Design doc: `data-sdk-codegen-plan.md`
+(alchemy-cli repo, alongside the data SDK scope plan).
+
+## Two-stage pipeline
+
+```
+alchemyplatform/docs (hand-authored YAML)
+        │  pnpm snapshot          ← network/local-checkout stage, run rarely
+        ▼
+specs/*.json + specs.lock.json    ← committed snapshots, pinned by docs SHA + sha256
+        │  pnpm generate          ← offline + deterministic, run on every change
+        ▼
+packages/<target>/src/generated/  ← committed TypeScript (prettier-formatted)
+```
+
+- **`pnpm --filter @alchemy/api-codegen snapshot`** — bundles specs from a local
+  docs checkout (`--docs <dir>`, `ALCHEMY_DOCS_DIR`, or `../docs` relative to the
+  repo root) using the docs repo's own tooling (redocly for OpenAPI, its
+  `generate:rpc` script for OpenRPC), copies the bundled JSON into `specs/`, and
+  writes `specs.lock.json` (docs commit SHA, branch, sha256 per file). The docs
+  working tree must be clean (`--allow-dirty` to override).
+- **`pnpm generate`** (root, or `pnpm --filter @alchemy/data-apis generate`) —
+  reads only the committed snapshots, verifies checksums against the lockfile,
+  and emits TypeScript into the target package. Never touches the network.
+
+## Updating specs
+
+1. Pull/checkout the desired commit in your local docs clone.
+2. `pnpm --filter @alchemy/api-codegen snapshot`
+3. `pnpm generate`
+4. Review the `specs/` + `src/generated/` diff and commit.
+
+## Targets
+
+Each consuming package declares a `codegen.manifest.ts` at its package root
+(operationIds / RPC methods → export names, path normalization rules) and a
+`generate` script invoking `src/cli.ts --target <name>`. Targets are registered
+in `src/targets/`. The generator hard-errors if a manifest references a spec
+operation that no longer exists in the snapshot — that's the drift alarm.

api-codegen/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@alchemy/api-codegen",
+  "version": "0.0.0",
+  "description": "Internal codegen tool: generates SDK type internals from the docs repo's bundled OpenAPI/OpenRPC specs",
+  "author": "Alchemy",
+  "license": "MIT",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "snapshot": "tsx src/cli.ts snapshot",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "devDependencies": {
+    "json-schema-to-typescript": "15.0.4",
+    "openapi-typescript": "7.13.0",
+    "prettier": "3.3.3",
+    "typescript-template": "workspace:*"
+  }
+}