[RFC] @alchemy/data-apis v1 — publish-ready surface

.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 packages/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 `packages/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 packages/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

docs/pages/reference/common/src/classes/AlchemyApiError.mdx

@@ -0,0 +1,219 @@
+---
+title: AlchemyApiError
+description: "The normalized error family for Alchemy API failures. Both the REST channel (AlchemyRestClient → ServerError/FetchError, which extend this class) and SDK JSON-RPC actions surface failures as AlchemyApiError, so consumers can handle status/code/requestId/retryAfter uniformly:  ```ts try { ... } catch (e) {   if (e instanceof AlchemyApiError && e.status === 429) {     await sleep(e.retryAfter ?? 1_000);   } } ```"
+slug: wallets/reference/common/classes/AlchemyApiError
+layout: reference
+---
+
+{/* This file is auto-generated by TypeDoc. Do not edit manually. */}
+
+Defined in: [packages/common/src/errors/AlchemyApiError.ts:29](https://github.com/alchemyplatform/aa-sdk/blob/main/packages/common/src/errors/AlchemyApiError.ts#L29)
+
+The normalized error family for Alchemy API failures. Both the REST channel
+(AlchemyRestClient → ServerError/FetchError, which extend this class) and
+SDK JSON-RPC actions surface failures as AlchemyApiError, so consumers can
+handle status/code/requestId/retryAfter uniformly:
+
+```ts
+try { ... } catch (e) {
+  if (e instanceof AlchemyApiError && e.status === 429) {
+    await sleep(e.retryAfter ?? 1_000);
+  }
+}
+```
+
+## Extends
+
+- [`BaseError`](BaseError)
+
+## Extended by
+
+- [`FetchError`](FetchError)
+- [`ServerError`](ServerError)
+
+## Constructors
+
+### Constructor
+
+```ts
+new AlchemyApiError(shortMessage, args?): AlchemyApiError;
+```
+
+Defined in: [packages/common/src/errors/AlchemyApiError.ts:47](https://github.com/alchemyplatform/aa-sdk/blob/main/packages/common/src/errors/AlchemyApiError.ts#L47)
+
+Creates a normalized API error.
+
+#### Parameters
+
+<table>
+  <thead>
+    <tr>
+      <th align="left">Parameter</th>
+      <th align="left">Type</th>
+      <th align="left">Description</th>
+    </tr>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td>
+        `shortMessage`
+      </td>
+
+      <td>
+        `string`
+      </td>
+
+      <td>
+        The headline error message
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        `args?`
+      </td>
+
+      <td>
+        [`AlchemyApiErrorDetails`](../type-aliases/AlchemyApiErrorDetails) & `object`
+      </td>
+
+      <td>
+        Failure metadata plus BaseError options
+      </td>
+    </tr>
+
+  </tbody>
+</table>
+
+#### Returns
+
+`AlchemyApiError`
+
+#### Overrides
+
+[`BaseError`](BaseError).[`constructor`](BaseError#constructor)
+
+## Properties
+
+<table>
+  <thead>
+    <tr>
+      <th align="left">Property</th>
+      <th align="left">Type</th>
+      <th align="left">Default value</th>
+      <th align="left">Description</th>
+    </tr>
+  </thead>
+
+  <tbody>
+    <tr>
+      <td>
+        <a id="code" /> `code?`
+      </td>
+
+      <td>
+        `string` | `number`
+      </td>
+
+      <td>
+        `undefined`
+      </td>
+
+      <td>
+        Provider error code: JSON-RPC `error.code` or a REST error-body code.
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        <a id="name" /> `name`
+      </td>
+
+      <td>
+        `string`
+      </td>
+
+      <td>
+        `"AlchemyApiError"`
+      </td>
+
+      <td>
+        ‐
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        <a id="requestid" /> `requestId?`
+      </td>
+
+      <td>
+        `string`
+      </td>
+
+      <td>
+        `undefined`
+      </td>
+
+      <td>
+        The client-generated X-Alchemy-Client-Request-Id sent with the request.
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        <a id="retryafter" /> `retryAfter?`
+      </td>
+
+      <td>
+        `number`
+      </td>
+
+      <td>
+        `undefined`
+      </td>
+
+      <td>
+        Parsed Retry-After hint in milliseconds, when the server provided one.
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        <a id="status" /> `status?`
+      </td>
+
+      <td>
+        `number`
+      </td>
+
+      <td>
+        `undefined`
+      </td>
+
+      <td>
+        HTTP status code, when the failure was an HTTP response.
+      </td>
+    </tr>
+
+    <tr>
+      <td>
+        <a id="version" /> `version`
+      </td>
+
+      <td>
+        `string`
+      </td>
+
+      <td>
+        `VERSION`
+      </td>
+
+      <td>
+        ‐
+      </td>
+    </tr>
+
+  </tbody>
+</table>