@quicknode/sdk 3.0.0-alpha.5 → 3.1.0-alpha.14

package/README.md

@@ -0,0 +1,246 @@
+# Quicknode SDK
+
+A unified SDK for building on Quicknode.
+
+Rust SDK with Python, Node.js, and Ruby bindings.
+
+## Table of Contents
+
+- [Per-language docs](#per-language-docs)
+- [Project Structure](#project-structure)
+- [Installation](#installation)
+- [Development](#development)
+  - [Prerequisites](#prerequisites)
+  - [Build Commands](#build-commands)
+  - [Testing](#testing)
+  - [Examples](#examples)
+  - [Releasing](#releasing)
+    - [Rust crate only (crates.io)](#rust-crate-only-cratesio)
+    - [All bindings together (Python / Node / Ruby)](#all-bindings-together-python--node--ruby)
+    - [npm publish (`@quicknode/sdk`)](#npm-publish-quicknodesdk)
+    - [PyPI publish (`quicknode-sdk`)](#pypi-publish-quicknode-sdk)
+- [License](#license)
+
+## Per-language docs
+
+API reference, configuration, and error handling for each language live next to the package — those are also the docs that render on each package listing.
+
+- **Rust** — [`crates/core/README.md`](crates/core/README.md) (`quicknode-sdk` on crates.io)
+- **Python** — [`python/README.md`](python/README.md) (`quicknode-sdk` on PyPI)
+- **Node.js** — [`npm/README.md`](npm/README.md) (`@quicknode/sdk` on npm)
+- **Ruby** — [`ruby/README.md`](ruby/README.md) (`quicknode_sdk` on RubyGems)
+
+This file covers project structure, install index, and how to develop and release the SDK.
+
+## Project Structure
+
+```
+sdk/
+├── crates/
+│   ├── core/          # Pure Rust business logic
+│   ├── python/        # PyO3 bindings
+│   ├── node/          # napi-rs bindings
+│   └── ruby/          # magnus bindings
+├── python/sdk/        # Python package with type hints
+├── npm/               # Node.js package with TypeScript types
+├── ruby/              # Ruby package
+└── pyproject.toml     # maturin build config
+```
+
+## Installation
+
+| Language | Install |
+|---|---|
+| Rust    | `cargo add quicknode-sdk` — see [`crates/core/README.md`](crates/core/README.md) |
+| Python  | `uv add quicknode-sdk` — see [`python/README.md`](python/README.md) |
+| Node.js | `npm install @quicknode/sdk` — see [`npm/README.md`](npm/README.md) |
+| Ruby    | `gem install quicknode_sdk` — see [`ruby/README.md`](ruby/README.md) |
+
+## Development
+
+### Prerequisites
+
+- Rust (stable)
+- Python 3.8+ with [uv](https://docs.astral.sh/uv/)
+- Node.js 18+
+- Ruby 3.0+
+- [just](https://github.com/casey/just)
+
+### Build Commands
+
+Use the commands in the `Justfile` for the setup and build commands.
+
+```bash
+# Core library
+cargo check
+cargo test -p quicknode-sdk
+
+# Python (from project root)
+just python-setup-env
+just python-build
+
+# Node.js (from npm/)
+just node-build
+
+# Ruby
+just ruby-build
+
+# Rust
+cargo build -p quicknode-sdk
+```
+
+### Testing
+
+```bash
+just test
+```
+
+Runs the Rust unit tests for `quicknode-sdk` using [wiremock](https://github.com/LukeMathWalker/wiremock-rs) to mock HTTP responses — no API key required.
+
+### Examples
+
+```bash
+# Rust
+QN_SDK__API_KEY=replaceme cargo run --example admin -p quicknode-sdk --features rust
+
+# Python
+QN_SDK__API_KEY=replaceme uv run python/examples/admin.py
+QN_SDK__API_KEY=replaceme uv run python/examples/streams.py
+
+# Node.js
+cd npm && QN_SDK__API_KEY=replaceme npx tsx examples/admin.ts
+cd npm && QN_SDK__API_KEY=replaceme npx tsx examples/streams.ts
+
+# Ruby (build first, then run)
+just ruby-build
+QN_SDK__API_KEY=replaceme ruby ruby/examples/admin.rb
+QN_SDK__API_KEY=replaceme ruby ruby/examples/admin_e2e.rb
+QN_SDK__API_KEY=replaceme ruby ruby/examples/streams.rb
+```
+
+### Releasing
+
+The Rust crate (`quicknode-sdk` on crates.io) versions independently from the Python, Node, and Ruby bindings. Its version lives in `crates/core/Cargo.toml`; the bindings share the workspace version in the root `Cargo.toml`.
+
+#### Rust crate only (crates.io)
+
+```bash
+# 1. Bump the version in crates/core/Cargo.toml (e.g. 0.1.0 → 0.1.0-alpha.5)
+#    Pre-release identifiers use SemVer 2.0 syntax: MAJOR.MINOR.PATCH-<id>.<N>
+#    Examples: 0.1.0-alpha.4, 0.2.0-beta.1, 0.2.0-rc.1
+
+# 2. Commit and push
+git commit -am "chore: release quicknode-sdk 0.1.0-alpha.5"
+git push
+
+# 3. Validate the tarball (no upload)
+cargo publish -p quicknode-sdk --dry-run
+
+# 4. Publish (requires `cargo login` with a crates.io token)
+cargo publish -p quicknode-sdk
+```
+
+The first publish claims the `quicknode-sdk` name permanently. Published versions are immutable — you cannot overwrite or delete them (only `cargo yank`, which hides but doesn't remove).
+
+#### All bindings together (Python / Node / Ruby)
+
+macOS (Apple Silicon) artifacts are built locally rather than on GitHub Actions to avoid the ~10× runner cost. Linux artifacts are built by CI when a GitHub release is published.
+
+1. **Bump versions and commit:**
+   ```bash
+   just release 0.2.0
+   git push
+   ```
+
+2. **Create the GitHub release** via the GitHub UI:
+   - **Releases → Draft a new release**.
+   - **Choose a tag** → type `v0.2.0` → **Create new tag on publish**.
+   - Target branch: `main`.
+   - Fill in title and notes (or click **Generate release notes**).
+   - Click **Publish release**.
+
+   This creates + pushes the tag and triggers `.github/workflows/release.yml`, which builds Linux artifacts and attaches them to the release.
+
+3. **Build macOS arm64 artifacts locally and append them to the release:**
+   ```bash
+   just macos-build-and-publish 0.2.0
+   ```
+
+Step 3 requires the [`gh` CLI](https://cli.github.com/) authenticated to the repo. Intel macOS (`x86_64-apple-darwin`) is not shipped — users on Intel Macs install from source.
+
+`just release` does **not** bump the Rust crate version (that's managed separately in `crates/core/Cargo.toml`). If you want the Rust crate to move in lockstep with a binding release, bump it manually in the same commit.
+
+#### npm publish (`@quicknode/sdk`)
+
+The Node package is published to npm as `@quicknode/sdk`. During the 3.x pre-release period, publishes use the `next` dist-tag so `npm install @quicknode/sdk` continues to resolve to the legacy 2.x release while `npm install @quicknode/sdk@next` pulls the rewrite.
+
+The npm publish uses [napi-rs's multi-package layout](https://napi.rs/docs/deep-dive/release): one main package plus per-platform sub-packages (`@quicknode/sdk-linux-x64-gnu`, `@quicknode/sdk-darwin-arm64`, etc.) declared as `optionalDependencies`. Publishing is triggered manually via a GitHub Actions workflow so the macOS binary (built locally) can be uploaded to the GitHub release before publish.
+
+Anyone with permission to run the `Publish npm` workflow in this repo can cut a release.
+
+**Note on versions:** the git tag tracks the overall project version (e.g. `v0.1.0-alpha.5`) and is set in `crates/core/Cargo.toml` / the root `Cargo.toml`. The npm package version is set independently in `npm/package.json` (e.g. `3.0.0-alpha.5`) to stay compatible with the pre-existing `@quicknode/sdk` 2.x series on npm. The two versions do not need to match.
+
+**Per-release flow:**
+
+1. **Bump the npm version** in `npm/package.json` (e.g. `3.0.0-alpha.4` → `3.0.0-alpha.5`), commit, and push to `main`. (Bump the overall project version in `just release <version>` as part of the normal release flow above — this sets the git tag.)
+
+2. **Create the GitHub release** via the GitHub UI:
+   - Go to **Releases → Draft a new release**.
+   - Click **Choose a tag**, type the new tag (e.g. `v0.1.0-alpha.5`), and select **Create new tag on publish**.
+   - Target branch: `main`.
+   - Fill in the title and release notes (or click **Generate release notes**).
+   - Click **Publish release**.
+
+   Publishing the release creates + pushes the tag, which triggers `.github/workflows/release.yml`. CI builds the Linux `.node` artifacts and attaches them to the release you just created.
+
+3. **Wait for `release.yml` to finish.** Confirm the four Linux `index.*.node` artifacts are attached to the release.
+
+4. **Build and upload the macOS arm64 binary** locally (Apple Silicon Mac required):
+   ```bash
+   just node-build
+   gh release upload v0.1.0-alpha.5 npm/index.darwin-arm64.node
+   ```
+
+5. **Trigger the publish workflow.** From the GitHub UI: **Actions → Publish npm → Run workflow**, then enter the git tag (`v0.1.0-alpha.5`) and npm dist-tag (`next`). Or via CLI:
+   ```bash
+   gh workflow run publish-npm.yml -f tag=v0.1.0-alpha.5 -f npm_tag=next
+   ```
+
+6. **Verify.**
+   ```bash
+   npm view @quicknode/sdk dist-tags
+   # Expected: next: 3.0.0-alpha.5, latest: 2.6.0 (unchanged)
+   ```
+
+Users can install the pre-release with `npm install @quicknode/sdk@next`.
+
+#### PyPI publish (`quicknode-sdk`)
+
+The Python package is published to PyPI as `quicknode-sdk`. Wheels and the sdist are built by `release.yml` on every GitHub release and attached as artifacts; the `Publish PyPI` workflow downloads them from a release tag and uploads to PyPI via `twine`.
+
+**Version format:** PyPI uses PEP 440, so pre-releases are written without a hyphen. `0.1.0-alpha.6` → `0.1.0a6` in `pyproject.toml`.
+
+**Per-release flow:**
+
+1. **Bump the version** in `pyproject.toml` (e.g. `0.1.0a6` → `0.1.0a7`) and run `uv lock` to refresh `uv.lock`. Commit and push.
+
+2. **Create the GitHub release** as described in the main Releasing section — this triggers `release.yml`, which builds the Linux wheels and sdist and attaches them to the release as `quicknode_sdk-*.whl` and `quicknode_sdk-*.tar.gz`.
+
+3. **Wait for `release.yml` to finish.** Confirm 16 wheels (4 Python versions × 4 Linux targets) and 1 sdist are attached to the release.
+
+4. **Trigger the publish workflow.** From the GitHub UI: **Actions → Publish PyPI → Run workflow**, then enter the git tag. Or via CLI:
+   ```bash
+   gh workflow run publish-pypi.yml -f tag=v0.1.0-alpha.6
+   ```
+
+5. **Verify.**
+   ```bash
+   pip install quicknode-sdk==0.1.0a6
+   python -c "import sdk; print(sdk.QuicknodeSdk)"
+   ```
+
+**First publish:** the repo secret `PYPI_API_TOKEN` must be set. Project-scoped tokens only work after the project exists on PyPI, so the first upload needs a user-scoped token; rotate to a project-scoped token after.
+
+## License
+
+MIT

package/errors.js

@@ -0,0 +1,121 @@
+// Typed error classes. The Rust binding throws a plain napi Error whose
+// message is tagged "[<kind>|<status>|<body_len>]<msg>\x1f<body>"; parseAndRethrow
+// decodes that and throws an instance of the matching subclass below.
+
+class QuicknodeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QuicknodeError";
+  }
+}
+
+class ConfigError extends QuicknodeError {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+class HttpError extends QuicknodeError {
+  constructor(message) {
+    super(message);
+    this.name = "HttpError";
+  }
+}
+
+class TimeoutError extends HttpError {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+}
+
+class ConnectionError extends HttpError {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectionError";
+  }
+}
+
+class ApiError extends QuicknodeError {
+  constructor(message, status, body) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class DecodeError extends QuicknodeError {
+  constructor(message, body) {
+    super(message);
+    this.name = "DecodeError";
+    this.body = body;
+  }
+}
+
+const TAG_RE = /^\[(Config|Http|Timeout|Connect|Api|Decode)\|([^|]+)\|([^\]]+)\](.*)$/s;
+
+function fromNapiError(err) {
+  if (!(err instanceof Error)) return err;
+  const m = err.message.match(TAG_RE);
+  if (!m) return err;
+  const [, kind, statusStr, bodyLenStr, rest] = m;
+  // rest = "<msg>\x1f<body>". Use body_len (byte length from Rust) to split
+  // deterministically — the body may itself contain \x1f, and Api messages
+  // embed the body in msg, so scanning for the first separator is unsafe.
+  let msg = rest;
+  let body = "";
+  if (bodyLenStr !== "-") {
+    const bodyLen = Number(bodyLenStr);
+    const bodyBytes = Buffer.from(rest, "utf8");
+    const bodyStart = bodyBytes.length - bodyLen;
+    if (bodyStart >= 1 && bodyBytes[bodyStart - 1] === 0x1f) {
+      msg = bodyBytes.slice(0, bodyStart - 1).toString("utf8");
+      body = bodyBytes.slice(bodyStart).toString("utf8");
+    }
+  }
+  switch (kind) {
+    case "Config": return new ConfigError(msg);
+    case "Timeout": return new TimeoutError(msg);
+    case "Connect": return new ConnectionError(msg);
+    case "Http": return new HttpError(msg);
+    case "Api": return new ApiError(msg, Number(statusStr), body);
+    case "Decode": return new DecodeError(msg, body);
+    default: return err;
+  }
+}
+
+// Wraps an object's methods so thrown napi errors get retagged as typed
+// subclasses. Handles both sync throws and rejected promises.
+function wrapClient(client) {
+  return new Proxy(client, {
+    get(target, prop) {
+      const val = target[prop];
+      if (typeof val !== "function") return val;
+      return function (...args) {
+        try {
+          const result = val.apply(target, args);
+          if (result && typeof result.then === "function") {
+            return result.catch((e) => { throw fromNapiError(e); });
+          }
+          return result;
+        } catch (e) {
+          throw fromNapiError(e);
+        }
+      };
+    },
+  });
+}
+
+module.exports = {
+  QuicknodeError,
+  ConfigError,
+  HttpError,
+  TimeoutError,
+  ConnectionError,
+  ApiError,
+  DecodeError,
+  fromNapiError,
+  wrapClient,
+};

package/index.d.ts

@@ -172,7 +172,7 @@ export interface ChainNetwork {
   /** Numeric chain id, when applicable. */
   chainId?: number
 }
-/** A blockchain supported by QuickNode along with its networks. */
+/** A blockchain supported by Quicknode along with its networks. */
 export interface Chain {
   /** Chain slug (e.g. `ethereum`). */
   slug: string
@@ -362,7 +362,7 @@ export interface CreateIpRequest {
 }
 /** Parameters for `create_domain_mask`. */
 export interface CreateDomainMaskRequest {
-  /** Custom domain that will mask the endpoint's QuickNode URL. */
+  /** Custom domain that will mask the endpoint's Quicknode URL. */
   domainMask?: string
 }
 /** Parameters for `create_jwt`. */
@@ -469,7 +469,7 @@ export interface Pagination {
 export interface Endpoint {
   /** Unique endpoint identifier. */
   id: string
-  /** QuickNode-assigned subdomain. */
+  /** Quicknode-assigned subdomain. */
   name: string
   /** Human-readable label. */
   label?: string
@@ -1638,18 +1638,6 @@ export interface StellarWalletTransactionsFilterTemplate {
   /** Stellar wallet addresses to match against. */
   wallets: Array<string>
 }
-/**
- * Template identifier paired with its arguments, consumed by
- * `create_webhook_from_template` and `update_webhook_template`. Construct via
- * the typed static factory methods (one per template); do not set fields
- * directly.
- */
-export interface TemplateArgs {
-  /** Which filter template these arguments correspond to. */
-  templateId: WebhookTemplateId
-  /** Template arguments, pre-serialized as a JSON string. */
-  value: string
-}
 /** Destination configuration for a webhook. */
 export interface WebhookDestinationAttributes {
   /** Target URL that receives webhook payloads. */
@@ -1683,30 +1671,6 @@ export interface ActivateWebhookParams {
   /** Position to begin (or resume) delivery from. */
   startFrom: WebhookStartFrom
 }
-/** Parameters for `create_webhook_from_template`. */
-export interface CreateWebhookFromTemplateParams {
-  /** Human-readable label for the webhook. */
-  name: string
-  /** Blockchain network to watch (e.g. `ethereum-mainnet`). */
-  network: string
-  /** Optional email that receives alerts if the webhook terminates. */
-  notificationEmail?: string
-  /** Destination configuration for delivered payloads. */
-  destinationAttributes: WebhookDestinationAttributes
-  /** Filter template identifier and its arguments. */
-  templateArgs: TemplateArgs
-}
-/** Parameters for `update_webhook_template`. */
-export interface UpdateWebhookTemplateParams {
-  /** New human-readable name. */
-  name?: string
-  /** New notification email. */
-  notificationEmail?: string
-  /** New destination configuration. */
-  destinationAttributes?: WebhookDestinationAttributes
-  /** New template identifier and arguments. */
-  templateArgs: TemplateArgs
-}
 /** A webhook's full configuration and current state. */
 export interface Webhook {
   /** Unique webhook identifier. */
@@ -1728,10 +1692,21 @@ export interface Webhook {
   /** Destination-specific configuration as a JSON string. */
   destinationAttributes?: string
 }
+/** Pagination metadata returned alongside a paginated webhooks list. */
+export interface WebhookPageInfo {
+  /** Page size used for this response. */
+  limit: number
+  /** Starting index of this page within the full result set. */
+  offset: number
+  /** Total number of webhooks matching the query across all pages. */
+  total: number
+}
 /** Response from `list_webhooks`. */
 export interface ListWebhooksResponse {
   /** Webhooks on the current page. */
   data: Array<Webhook>
+  /** Pagination metadata for the response. */
+  pageInfo: WebhookPageInfo
 }
 /** Response from `get_enabled_count` for webhooks. */
 export interface WebhookEnabledCountResponse {
@@ -1830,7 +1805,20 @@ export interface ListStreamsResponseNode {
   data: Array<StreamNode>
   pageInfo: PageInfo
 }
-export declare class QuickNodeSdk {
+export interface CreateWebhookFromTemplateParamsNode {
+  name: string
+  network: string
+  notificationEmail?: string
+  destinationAttributes: WebhookDestinationAttributes
+  templateArgs: any
+}
+export interface UpdateWebhookTemplateParamsNode {
+  name?: string
+  notificationEmail?: string
+  destinationAttributes?: WebhookDestinationAttributes
+  templateArgs: any
+}
+export declare class QuicknodeSdk {
   /** Creates a new SDK instance from an explicit configuration. */
   constructor(config: SdkFullConfig)
   /** Returns the admin sub-client. */
@@ -1842,7 +1830,7 @@ export declare class QuickNodeSdk {
   /** Returns the kvstore sub-client. */
   get kvstore(): KvStoreApiClient
   /** Creates a new SDK instance using configuration from environment variables. */
-  static fromEnv(): QuickNodeSdk
+  static fromEnv(): QuicknodeSdk
 }
 export declare class AdminApiClient {
   /**
@@ -1949,7 +1937,7 @@ export declare class AdminApiClient {
   deleteIp(id: string, ipId: string): Promise<DeleteBoolResponse>
   /**
    * Adds a domain mask to an endpoint — a custom domain used to hide the
-   * endpoint's QuickNode URL so requests can be routed through your own
+   * endpoint's Quicknode URL so requests can be routed through your own
    * domain.
    */
   createDomainMask(id: string, params?: CreateDomainMaskRequest | undefined | null): Promise<void>
@@ -2034,7 +2022,7 @@ export declare class AdminApiClient {
    */
   getAccountMetrics(params: GetAccountMetricsRequest): Promise<GetAccountMetricsResponse>
   /**
-   * Returns all chains supported by QuickNode along with their networks.
+   * Returns all chains supported by Quicknode along with their networks.
    * Each entry includes the chain slug and its network slugs and names.
    */
   listChains(): Promise<ListChainsResponse>
@@ -2250,7 +2238,7 @@ export declare class WebhooksApiClient {
    * filters. An optional `notification_email` receives alerts if the
    * webhook terminates.
    */
-  createWebhookFromTemplate(params: CreateWebhookFromTemplateParams): Promise<Webhook>
+  createWebhookFromTemplate(params: CreateWebhookFromTemplateParamsNode): Promise<Webhook>
   /**
    * Updates an existing template-backed webhook, modifying its template
    * arguments and optionally its name, notification email, and destination
@@ -2259,7 +2247,7 @@ export declare class WebhooksApiClient {
    * generated automatically if not provided. Templates cover EVM chains,
    * Solana, Bitcoin, XRPL, Hyperliquid, and Stellar.
    */
-  updateWebhookTemplate(webhookId: string, params: UpdateWebhookTemplateParams): Promise<Webhook>
+  updateWebhookTemplate(webhookId: string, params: UpdateWebhookTemplateParamsNode): Promise<Webhook>
 }
 export declare class KvStoreApiClient {
   /** Creates a new set, storing a single string value under the given key. */

package/index.js

@@ -0,0 +1,328 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'index.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.android-arm64.node')
+          } else {
+            nativeBinding = require('@quicknode/sdk-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'index.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@quicknode/sdk-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@quicknode/sdk-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@quicknode/sdk-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@quicknode/sdk-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'index.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./index.darwin-universal.node')
+      } else {
+        nativeBinding = require('@quicknode/sdk-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'index.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.darwin-x64.node')
+          } else {
+            nativeBinding = require('@quicknode/sdk-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@quicknode/sdk-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'index.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./index.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@quicknode/sdk-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@quicknode/sdk-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@quicknode/sdk-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@quicknode/sdk-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@quicknode/sdk-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@quicknode/sdk-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@quicknode/sdk-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@quicknode/sdk-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'index.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./index.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@quicknode/sdk-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'index.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./index.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@quicknode/sdk-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { StreamRegion, StreamDataset, StreamDestination, FilterLanguage, StreamMetadataLocation, ProductType, StreamStatus, WebhookTemplateId, WebhookStartFrom, QuicknodeSdk, AdminApiClient, StreamsApiClient, WebhooksApiClient, KvStoreApiClient } = nativeBinding
+
+module.exports.StreamRegion = StreamRegion
+module.exports.StreamDataset = StreamDataset
+module.exports.StreamDestination = StreamDestination
+module.exports.FilterLanguage = FilterLanguage
+module.exports.StreamMetadataLocation = StreamMetadataLocation
+module.exports.ProductType = ProductType
+module.exports.StreamStatus = StreamStatus
+module.exports.WebhookTemplateId = WebhookTemplateId
+module.exports.WebhookStartFrom = WebhookStartFrom
+module.exports.QuicknodeSdk = QuicknodeSdk
+module.exports.AdminApiClient = AdminApiClient
+module.exports.StreamsApiClient = StreamsApiClient
+module.exports.WebhooksApiClient = WebhooksApiClient
+module.exports.KvStoreApiClient = KvStoreApiClient

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicknode/sdk",
-  "version": "3.0.0-alpha.5",
+  "version": "3.1.0-alpha.14",
   "description": "Quicknode SDK",
   "main": "sdk.js",
   "types": "sdk.d.ts",
@@ -18,7 +18,9 @@
     "sdk.js",
     "sdk.d.ts",
     "sdk.mjs",
+    "errors.js",
     "browser.js",
+    "README.md",
     "*.node"
   ],
   "napi": {
@@ -44,10 +46,10 @@
   },
   "license": "MIT",
   "optionalDependencies": {
-    "@quicknode/sdk-linux-x64-gnu": "3.0.0-alpha.5",
-    "@quicknode/sdk-linux-arm64-gnu": "3.0.0-alpha.5",
-    "@quicknode/sdk-linux-x64-musl": "3.0.0-alpha.5",
-    "@quicknode/sdk-linux-arm64-musl": "3.0.0-alpha.5",
-    "@quicknode/sdk-darwin-arm64": "3.0.0-alpha.5"
+    "@quicknode/sdk-linux-x64-gnu": "3.1.0-alpha.14",
+    "@quicknode/sdk-linux-arm64-gnu": "3.1.0-alpha.14",
+    "@quicknode/sdk-linux-x64-musl": "3.1.0-alpha.14",
+    "@quicknode/sdk-linux-arm64-musl": "3.1.0-alpha.14",
+    "@quicknode/sdk-darwin-arm64": "3.1.0-alpha.14"
   }
 }

package/sdk.d.ts

@@ -1,6 +1,6 @@
 // sdk.d.ts
 import {
-  QuickNodeSdk as _QuickNodeSdk,
+  QuicknodeSdk as _QuicknodeSdk,
   SdkFullConfig,
   WebhookAttributes,
   S3Attributes,
@@ -72,6 +72,36 @@ export type ListStreamsResponse = Omit<_ListStreamsResponseNode, "data"> & {
   data: Stream[];
 };
 
+// Webhook template args (input). The inner key is `args` rather than the
+// wire's `templateArgs` to avoid `templateArgs.templateArgs.wallets`; the
+// Node binding renames it back before the request.
+export type TemplateArgsInput =
+  | { templateId: "evmWalletFilter"; args: EvmWalletFilterTemplate }
+  | { templateId: "evmContractEvents"; args: EvmContractEventsTemplate }
+  | { templateId: "evmAbiFilter"; args: EvmAbiFilterTemplate }
+  | { templateId: "solanaWalletFilter"; args: SolanaWalletFilterTemplate }
+  | { templateId: "bitcoinWalletFilter"; args: BitcoinWalletFilterTemplate }
+  | { templateId: "xrplWalletFilter"; args: XrplWalletFilterTemplate }
+  | { templateId: "hyperliquidWalletEventsFilter"; args: HyperliquidWalletEventsFilterTemplate }
+  | {
+      templateId: "stellarWalletTransactionsSourceAccountFilter";
+      args: StellarWalletTransactionsFilterTemplate;
+    };
+
+// Replace the napi-generated JSON-blob templateArgs with typed unions.
+type _CreateWebhookFromTemplateParamsNode = import("./index").CreateWebhookFromTemplateParamsNode;
+type _UpdateWebhookTemplateParamsNode = import("./index").UpdateWebhookTemplateParamsNode;
+
+export type CreateWebhookFromTemplateParams =
+  Omit<_CreateWebhookFromTemplateParamsNode, "templateArgs"> & {
+    templateArgs: TemplateArgsInput;
+  };
+
+export type UpdateWebhookTemplateParams =
+  Omit<_UpdateWebhookTemplateParamsNode, "templateArgs"> & {
+    templateArgs: TemplateArgsInput;
+  };
+
 export type {
   SdkFullConfig,
   HttpConfig,
@@ -236,11 +266,10 @@ export type {
   UpdateWebhookParams,
   Webhook,
   ListWebhooksResponse,
+  WebhookPageInfo,
   WebhookEnabledCountResponse,
   WebhookDestinationAttributes,
   ActivateWebhookParams,
-  CreateWebhookFromTemplateParams,
-  UpdateWebhookTemplateParams,
   EvmWalletFilterTemplate,
   EvmContractEventsTemplate,
   EvmAbiFilterTemplate,
@@ -301,39 +330,60 @@ export interface StreamsApiClientTyped {
   getEnabledCount(streamType?: string | undefined | null): Promise<import("./index").EnabledCountResponse>;
 }
 
-export class QuickNodeSdk {
+// Retypes napi's `any` templateArgs to the discriminated union. Keep method
+// signatures in sync with the napi-generated WebhooksApiClient in ./index.d.ts.
+export interface WebhooksApiClientTyped {
+  listWebhooks(params?: import("./index").GetWebhooksParams | undefined | null): Promise<import("./index").ListWebhooksResponse>;
+  deleteAllWebhooks(): Promise<void>;
+  getWebhook(id: string): Promise<import("./index").Webhook>;
+  updateWebhook(
+    id: string,
+    params: import("./index").UpdateWebhookParams
+  ): Promise<import("./index").Webhook>;
+  deleteWebhook(id: string): Promise<void>;
+  pauseWebhook(id: string): Promise<void>;
+  activateWebhook(id: string, params: import("./index").ActivateWebhookParams): Promise<void>;
+  getEnabledCount(): Promise<import("./index").WebhookEnabledCountResponse>;
+  createWebhookFromTemplate(params: CreateWebhookFromTemplateParams): Promise<import("./index").Webhook>;
+  updateWebhookTemplate(
+    webhookId: string,
+    params: UpdateWebhookTemplateParams
+  ): Promise<import("./index").Webhook>;
+}
+
+export class QuicknodeSdk {
   constructor(config: SdkFullConfig);
-  static fromEnv(): QuickNodeSdk;
-  admin: _QuickNodeSdk["admin"];
+  static fromEnv(): QuicknodeSdk;
+  admin: _QuicknodeSdk["admin"];
   streams: StreamsApiClientTyped;
-  webhooks: _QuickNodeSdk["webhooks"];
-  kvstore: _QuickNodeSdk["kvstore"];
+  webhooks: WebhooksApiClientTyped;
+  kvstore: _QuicknodeSdk["kvstore"];
 }
 
-export class TemplateArgs {
-  templateId: WebhookTemplateId;
-  value: string;
-  static evmWalletFilter(attrs: EvmWalletFilterTemplate): TemplateArgs;
-  static evmContractEvents(attrs: EvmContractEventsTemplate): TemplateArgs;
-  static evmAbiFilter(attrs: EvmAbiFilterTemplate): TemplateArgs;
-  static solanaWalletFilter(attrs: SolanaWalletFilterTemplate): TemplateArgs;
-  static bitcoinWalletFilter(attrs: BitcoinWalletFilterTemplate): TemplateArgs;
-  static xrplWalletFilter(attrs: XrplWalletFilterTemplate): TemplateArgs;
-  static hyperliquidWalletEventsFilter(attrs: HyperliquidWalletEventsFilterTemplate): TemplateArgs;
-  static stellarWalletTransactionsFilter(attrs: StellarWalletTransactionsFilterTemplate): TemplateArgs;
-}
+// Typed static factory methods producing each discriminated variant of
+// TemplateArgsInput. Consumers can also construct the object literal directly.
+export const TemplateArgs: {
+  evmWalletFilter(attrs: EvmWalletFilterTemplate): Extract<TemplateArgsInput, { templateId: "evmWalletFilter" }>;
+  evmContractEvents(attrs: EvmContractEventsTemplate): Extract<TemplateArgsInput, { templateId: "evmContractEvents" }>;
+  evmAbiFilter(attrs: EvmAbiFilterTemplate): Extract<TemplateArgsInput, { templateId: "evmAbiFilter" }>;
+  solanaWalletFilter(attrs: SolanaWalletFilterTemplate): Extract<TemplateArgsInput, { templateId: "solanaWalletFilter" }>;
+  bitcoinWalletFilter(attrs: BitcoinWalletFilterTemplate): Extract<TemplateArgsInput, { templateId: "bitcoinWalletFilter" }>;
+  xrplWalletFilter(attrs: XrplWalletFilterTemplate): Extract<TemplateArgsInput, { templateId: "xrplWalletFilter" }>;
+  hyperliquidWalletEventsFilter(attrs: HyperliquidWalletEventsFilterTemplate): Extract<TemplateArgsInput, { templateId: "hyperliquidWalletEventsFilter" }>;
+  stellarWalletTransactionsFilter(attrs: StellarWalletTransactionsFilterTemplate): Extract<TemplateArgsInput, { templateId: "stellarWalletTransactionsSourceAccountFilter" }>;
+};
 
 // Typed error hierarchy. Any SDK call can throw one of these; catch
-// QuickNodeError to handle them all, or a specific subclass for finer control.
-export class QuickNodeError extends Error {}
-export class ConfigError extends QuickNodeError {}
-export class HttpError extends QuickNodeError {}
+// QuicknodeError to handle them all, or a specific subclass for finer control.
+export class QuicknodeError extends Error {}
+export class ConfigError extends QuicknodeError {}
+export class HttpError extends QuicknodeError {}
 export class TimeoutError extends HttpError {}
 export class ConnectionError extends HttpError {}
-export class ApiError extends QuickNodeError {
+export class ApiError extends QuicknodeError {
   status: number;
   body: string;
 }
-export class DecodeError extends QuickNodeError {
+export class DecodeError extends QuicknodeError {
   body: string;
 }

package/sdk.js

@@ -1,13 +1,13 @@
 // Exported main sdk file that imports from autogenerated napi-rs file
 //
 const _index = require("./index.js");
-const { QuickNodeSdk: _QuickNodeSdk } = _index;
+const { QuicknodeSdk: _QuicknodeSdk } = _index;
 const errors = require("./errors.js");
 
-class QuickNodeSdk {
+class QuicknodeSdk {
   constructor(config) {
     try {
-      this._inner = new _QuickNodeSdk(config);
+      this._inner = new _QuicknodeSdk(config);
     } catch (e) {
       throw errors.fromNapiError(e);
     }
@@ -18,9 +18,9 @@ class QuickNodeSdk {
   }
 
   static fromEnv() {
-    const instance = Object.create(QuickNodeSdk.prototype);
+    const instance = Object.create(QuicknodeSdk.prototype);
     try {
-      instance._inner = _QuickNodeSdk.fromEnv();
+      instance._inner = _QuicknodeSdk.fromEnv();
     } catch (e) {
       throw errors.fromNapiError(e);
     }
@@ -32,67 +32,53 @@ class QuickNodeSdk {
   }
 }
 
-// TemplateArgs.value is a pre-serialized JSON string; napi forwards camelCase
-// keys from JS but the API expects snake_case, so stringify through these.
-function toSnakeCase(str) {
-  return str.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
-}
-
-function keysToSnakeCase(obj) {
-  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) return obj;
-  return Object.fromEntries(
-    Object.entries(obj).map(([k, v]) => [toSnakeCase(k), keysToSnakeCase(v)])
-  );
-}
-
-// TemplateArgs wraps the napi-rs generated plain object with typed
-// static factory methods. The underlying object has `templateId` (string enum)
-// and `value` (JSON string) fields — callers should use the factory methods
-// rather than constructing the object directly.
+// TemplateArgs wraps the webhook template input with typed static factory
+// methods. The underlying object is `{ templateId, args }` — callers should
+// use the factory methods rather than constructing the object directly.
 class TemplateArgs {
-  constructor(templateId, value) {
+  constructor(templateId, args) {
     this.templateId = templateId;
-    this.value = value;
+    this.args = args;
   }
 
   static evmWalletFilter(attrs) {
-    return new TemplateArgs("EvmWalletFilter", JSON.stringify(keysToSnakeCase(attrs)));
+    return new TemplateArgs("evmWalletFilter", attrs);
   }
 
   static evmContractEvents(attrs) {
-    return new TemplateArgs("EvmContractEvents", JSON.stringify(keysToSnakeCase(attrs)));
+    return new TemplateArgs("evmContractEvents", attrs);
   }
 
   static evmAbiFilter(attrs) {
-    return new TemplateArgs("EvmAbiFilter", JSON.stringify(keysToSnakeCase(attrs)));
+    return new TemplateArgs("evmAbiFilter", attrs);
   }
 
   static solanaWalletFilter(attrs) {
-    return new TemplateArgs("SolanaWalletFilter", JSON.stringify(keysToSnakeCase(attrs)));
+    return new TemplateArgs("solanaWalletFilter", attrs);
   }
 
   static bitcoinWalletFilter(attrs) {
-    return new TemplateArgs("BitcoinWalletFilter", JSON.stringify(keysToSnakeCase(attrs)));
+    return new TemplateArgs("bitcoinWalletFilter", attrs);
   }
 
   static xrplWalletFilter(attrs) {
-    return new TemplateArgs("XrplWalletFilter", JSON.stringify(keysToSnakeCase(attrs)));
+    return new TemplateArgs("xrplWalletFilter", attrs);
   }
 
   static hyperliquidWalletEventsFilter(attrs) {
-    return new TemplateArgs("HyperliquidWalletEventsFilter", JSON.stringify(keysToSnakeCase(attrs)));
+    return new TemplateArgs("hyperliquidWalletEventsFilter", attrs);
   }
 
   static stellarWalletTransactionsFilter(attrs) {
-    return new TemplateArgs("StellarWalletTransactionsSourceAccountFilter", JSON.stringify(keysToSnakeCase(attrs)));
+    return new TemplateArgs("stellarWalletTransactionsSourceAccountFilter", attrs);
   }
 }
 
 module.exports = {
   ..._index,
-  QuickNodeSdk,
+  QuicknodeSdk,
   TemplateArgs,
-  QuickNodeError: errors.QuickNodeError,
+  QuicknodeError: errors.QuicknodeError,
   ConfigError: errors.ConfigError,
   HttpError: errors.HttpError,
   TimeoutError: errors.TimeoutError,

package/sdk.mjs

@@ -9,7 +9,7 @@ import cjs from './sdk.js';
 
 export default cjs;
 export const {
-  QuickNodeSdk,
+  QuicknodeSdk,
   TemplateArgs,
   StreamRegion,
   StreamDataset,
@@ -24,7 +24,7 @@ export const {
   StreamsApiClient,
   WebhooksApiClient,
   KvStoreApiClient,
-  QuickNodeError,
+  QuicknodeError,
   ConfigError,
   HttpError,
   TimeoutError,