@quicknode/sdk 3.1.0-alpha.14 → 3.1.0-alpha.15

package/README.md

@@ -15,10 +15,10 @@ Rust SDK with Python, Node.js, and Ruby bindings.
   - [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)
+    - [Two-phase flow](#two-phase-flow)
+    - [Building blocks](#building-blocks)
+    - [Version conventions](#version-conventions)
+    - [First-time setup](#first-time-setup)
 - [License](#license)
 
 ## Per-language docs
@@ -76,7 +76,7 @@ cargo check
 cargo test -p quicknode-sdk
 
 # Python (from project root)
-just python-setup-env
+just python-setup
 just python-build
 
 # Node.js (from npm/)
@@ -120,126 +120,76 @@ 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`.
+All four packages (Rust crate, Python wheels, Node `.node` module, Ruby gem) ship together from a single project version. The release flow is split into two `just` commands:
 
-#### Rust crate only (crates.io)
+- **`just release-prepare <version>`** — bump versions, push, tag, build all Linux + macOS artifacts, attach them to a GitHub release. **No registry publish yet.**
+- **`just release-publish <version>`** — push to crates.io and trigger the PyPI / npm / RubyGems publish workflows.
 
-```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.
+The pause between the two commands is the natural review point: inspect the GitHub release page and confirm all artifacts are present before anything goes public.
 
-Anyone with permission to run the `Publish npm` workflow in this repo can cut a release.
+Requires the [`gh` CLI](https://cli.github.com/) authenticated to the repo, an Apple Silicon Mac (macOS arm64 artifacts are built locally to avoid the ~10× CI runner cost), and `cargo login` with a crates.io token.
 
-**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.
+#### Two-phase flow
 
-**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:**
+```bash
+# Phase 1: build a fully-staged GitHub release
+just release-prepare 0.2.0
 
-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.
+# Inspect https://github.com/<org>/<repo>/releases/tag/v0.2.0
+# Confirm: Linux Python wheels, Linux .node files, Linux Ruby gem,
+#          macOS arm64 wheels, index.darwin-arm64.node, arm64-darwin .gem.
 
-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`.
+# Phase 2: publish to crates.io + trigger registry publish workflows
+just release-publish 0.2.0
+```
 
-3. **Wait for `release.yml` to finish.** Confirm 16 wheels (4 Python versions × 4 Linux targets) and 1 sdist are attached to the release.
+`release-prepare` prompts twice — once up front before bumping, and once after the bump (showing the diff) before pushing the tag. `release-publish` prompts once before any registry write. Pass `yes=1` to skip prompts (e.g. for automation): `just release-prepare 0.2.0 yes=1`.
 
-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
-   ```
+#### Building blocks
 
-5. **Verify.**
-   ```bash
-   pip install quicknode-sdk==0.1.0a6
-   python -c "import sdk; print(sdk.QuicknodeSdk)"
-   ```
+If a phase fails partway, resume with the individual recipes — they are also useful for reruns:
 
-**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.
+| Recipe | Purpose |
+|---|---|
+| `release-bump <version>` | Bump versions in all manifests, commit + tag locally |
+| `release-push <version>` | `git push` + push tag |
+| `release-create-tag <version>` | `gh release create` (triggers Linux CI build) |
+| `release-wait-ci <version>` | Block until `release.yml` finishes attaching Linux artifacts |
+| `macos-build-and-publish <version>` | Build macOS arm64 wheels / `.node` / `.gem` and `gh release upload` |
+| `release-cargo-publish-check` | `cargo publish -p quicknode-sdk --dry-run` |
+| `release-cargo-publish` | `cargo publish -p quicknode-sdk` |
+| `release-trigger-pypi <version>` | Dispatch `publish-pypi.yml` |
+| `release-trigger-npm <version> [npm_tag]` | Dispatch `publish-npm.yml` (default tag: `next`) |
+| `release-trigger-rubygems <version>` | Dispatch `publish-rubygems.yml` |
+| `release-trigger-all <version> [npm_tag]` | All three trigger recipes in sequence |
+
+#### Version conventions
+
+A single version argument drives every manifest, with two automatic translations applied by `release-bump`:
+
+| Manifest | Format example for `0.1.0-alpha.6` |
+|---|---|
+| `Cargo.toml` (workspace) | `0.1.0-alpha.6` |
+| `crates/core/Cargo.toml` | `0.1.0-alpha.6` |
+| `pyproject.toml` (PEP 440) | `0.1.0a6` |
+| `ruby/quicknode_sdk.gemspec` | `0.1.0-alpha.6` |
+| `npm/package.json` | `3.0.0-alpha.6` (`0.x` → `3.x` because `@quicknode/sdk` 2.x already exists on npm) |
+
+Pre-release identifiers use SemVer 2.0 syntax: `MAJOR.MINOR.PATCH-<id>.<N>` — e.g. `0.1.0-alpha.4`, `0.2.0-beta.1`, `0.2.0-rc.1`. The npm pre-release period uses the `next` dist-tag so `npm install @quicknode/sdk` continues to resolve to legacy 2.x while `npm install @quicknode/sdk@next` pulls the rewrite.
+
+`release-bump` only accepts versions starting with `0.`. The `0.x → 3.x` mapping (and the recipe's guard) needs to be revisited when the project graduates to `1.0`.
+
+#### First-time setup
+
+- The first crates.io publish claims the `quicknode-sdk` name permanently. Published versions are immutable (only `cargo yank` is reversible, and it only hides).
+- The first PyPI upload needs a user-scoped `PYPI_API_TOKEN`; rotate to a project-scoped token after.
+- Verify a release reached each registry:
+  ```bash
+  cargo search quicknode-sdk
+  pip install quicknode-sdk==0.1.0a6
+  npm view @quicknode/sdk dist-tags
+  gem search -e quicknode_sdk
+  ```
 
 ## License
 

package/index.d.ts

@@ -108,7 +108,7 @@ export interface BulkUpdateEndpointStatusResponse {
 export interface BulkAddTagRequest {
   /** Endpoint ids to tag. */
   ids: Array<string>
-  /** Label of the tag to apply (created if it doesn't exist). */
+  /** Label of the tag to apply (created if it doesn't exist). Maximum 25 characters. */
   label: string
 }
 /** Tag reference returned on bulk tag operations. */
@@ -662,7 +662,7 @@ export interface UpdateEndpointStatusResponse {
 }
 /** Parameters for `create_tag` (on a specific endpoint). */
 export interface CreateTagRequest {
-  /** Label for the new tag. */
+  /** Label for the new tag. Maximum 25 characters. */
   label?: string
 }
 /** Response from `get_endpoint_security`. */
@@ -1244,12 +1244,7 @@ export const enum StreamDestination {
   S3 = 'S3',
   Azure = 'Azure',
   Postgres = 'Postgres',
-  Clickhouse = 'Clickhouse',
-  Snowflake = 'Snowflake',
-  Mysql = 'Mysql',
-  Mongo = 'Mongo',
-  Kafka = 'Kafka',
-  Redis = 'Redis'
+  Kafka = 'Kafka'
 }
 /** Language a stream's filter function is written in. */
 export const enum FilterLanguage {
@@ -1280,16 +1275,16 @@ export const enum StreamStatus {
 export interface WebhookAttributes {
   /** Destination URL that receives batched stream payloads. */
   url: string
-  /** Maximum number of retry attempts for a failed delivery. */
+  /** Maximum number of retry attempts for a failed delivery. Must be in the range 1–10. */
   maxRetry: number
   /** Seconds to wait between retry attempts. */
   retryIntervalSec: number
   /** Timeout in seconds for each POST request. */
   postTimeoutSec: number
-  /** Optional token included with each request so the receiver can verify authenticity. */
+  /** Optional token included with each request so the receiver can verify authenticity. When supplied, must be at least 32 bytes (256 bits). */
   securityToken?: string
-  /** Compression applied to the payload (e.g. `none`, `gzip`). */
-  compression: string
+  /** Compression applied to the payload (e.g. `none`, `gzip`). When omitted the server defaults to no compression. */
+  compression?: string
 }
 /** Configuration for delivering stream batches to an S3-compatible object store. */
 export interface S3Attributes {
@@ -1347,109 +1342,13 @@ export interface PostgresAttributes {
   password: string
   /** Destination table for inserted rows. */
   tableName: string
-  /** Postgres SSL mode (e.g. `disable`, `require`, `verify-full`). */
+  /** Postgres SSL mode. The Quicknode API accepts only `disable` or `require`. */
   sslmode: string
   /** Maximum number of retry attempts for a failed write. */
   maxRetry: number
   /** Seconds to wait between retry attempts. */
   retryIntervalSec: number
 }
-/** Configuration for delivering stream batches to a MySQL database. */
-export interface MysqlAttributes {
-  /** Database host. */
-  host: string
-  /** Database port. */
-  port: number
-  /** Database name. */
-  database: string
-  /** Username used to authenticate. */
-  username: string
-  /** Password used to authenticate. */
-  password: string
-  /** Destination table for inserted rows. */
-  tableName: string
-  /** Maximum number of retry attempts for a failed write. */
-  maxRetry: number
-  /** Seconds to wait between retry attempts. */
-  retryIntervalSec: number
-}
-/** Configuration for delivering stream batches to a MongoDB database. */
-export interface MongoAttributes {
-  /** Database host (connection string or hostname). */
-  host: string
-  /** Database name. */
-  database: string
-  /** Username used to authenticate. */
-  username: string
-  /** Password used to authenticate. */
-  password: string
-  /** Destination collection for inserted documents. */
-  collectionName: string
-  /** Maximum number of retry attempts for a failed write. */
-  maxRetry: number
-  /** Seconds to wait between retry attempts. */
-  retryIntervalSec: number
-}
-/** Configuration for delivering stream batches to a ClickHouse cluster. */
-export interface ClickhouseAttributes {
-  /** Comma-separated list of ClickHouse hosts. */
-  hosts: string
-  /** Database name. */
-  database: string
-  /** Username used to authenticate. */
-  username: string
-  /** Password used to authenticate. */
-  password: string
-  /** Destination table for inserted rows. */
-  tableName: string
-  /** Default table engine options applied when a table is created. */
-  defaultTableEngineOpts: string
-  /** Default index granularity for created tables. */
-  defaultGranularity: number
-  /** Default compression codec for created tables. */
-  defaultCompression: string
-  /** Default secondary index type for created tables. */
-  defaultIndexType: string
-  /** Maximum number of retry attempts for a failed write. */
-  maxRetry: number
-  /** Seconds to wait between retry attempts. */
-  retryIntervalSec: number
-  /** Disable datetime precision for older ClickHouse versions that don't support it. */
-  disableDatetimePrecision?: boolean
-  /** Enable when the target ClickHouse server does not support `RENAME COLUMN`. */
-  dontSupportRenameColumn?: boolean
-  /** Enable when the target ClickHouse server does not support empty default values. */
-  dontSupportEmptyDefaultValue?: boolean
-  /** Skip writing version metadata during initialization. */
-  skipInitializeWithVersion?: boolean
-}
-/** Configuration for delivering stream batches to a Snowflake data warehouse. */
-export interface SnowflakeAttributes {
-  /** Snowflake account identifier. */
-  account: string
-  /** Snowflake host. */
-  host: string
-  /** Snowflake port. */
-  port: number
-  /** Connection protocol (e.g. `https`). */
-  protocol: string
-  /** Database name. */
-  database: string
-  /** Schema within the database. */
-  schema: string
-  /** Warehouse used to run inserts. */
-  warehouse: string
-  /** Username used to authenticate. */
-  username: string
-  /** Password used to authenticate. */
-  password: string
-  /** Maximum number of retry attempts for a failed write. */
-  maxRetry: number
-  /** Seconds to wait between retry attempts. */
-  retryIntervalSec: number
-  /** Optional destination table for inserted rows. */
-  tableName?: string
-}
 /** Configuration for delivering stream batches to a Kafka topic. */
 export interface KafkaAttributes {
   /** Comma-separated list of Kafka broker addresses (host:port). */
@@ -1462,8 +1361,8 @@ export interface KafkaAttributes {
   batchSize: number
   /** Milliseconds the producer waits to batch additional messages. */
   lingerMs: number
-  /** Maximum request size in bytes. */
-  maxRequestSize: number
+  /** Maximum size in bytes of a single Kafka message (`max_message_bytes`). */
+  maxMessageBytes: number
   /** Request timeout in seconds. */
   timeoutSec: number
   /** Maximum number of retry attempts for a failed produce. */
@@ -1479,27 +1378,6 @@ export interface KafkaAttributes {
   /** Optional SASL mechanism (e.g. `PLAIN`, `SCRAM-SHA-256`). */
   mechanisms?: string
 }
-/** Configuration for delivering stream batches to a Redis instance. */
-export interface RedisAttributes {
-  /** Redis host. */
-  host: string
-  /** Redis port. */
-  port: number
-  /** Redis logical database index. */
-  database: number
-  /** Username used to authenticate. */
-  username: string
-  /** Password used to authenticate. */
-  password: string
-  /** Redis key that receives written payloads. */
-  keyName: string
-  /** Maximum number of retry attempts for a failed write. */
-  maxRetry: number
-  /** Seconds to wait between retry attempts. */
-  retryIntervalSec: number
-  /** Whether to connect over TLS. */
-  tls?: boolean
-}
 /**
  * Links a stream's filter to an address book so JSON paths resolve against its
  * managed address set.
@@ -1721,9 +1599,9 @@ export interface CreateStreamParamsNode {
   startRange: number
   endRange: number
   destinationAttributes: any
-  plan: string
-  thresholdFetchBuffer: number
-  datasetBatchSize?: number
+  plan?: string
+  thresholdFetchBuffer?: number
+  datasetBatchSize: number
   maxBatchSize?: number
   maxBufferRangeSize?: number
   maxBufferProcessingWorkers?: number
@@ -1737,7 +1615,7 @@ export interface CreateStreamParamsNode {
   notificationEmail?: string
   chargeMinCap?: number
   fixBlockReorgs?: number
-  elasticBatchEnabled?: boolean
+  elasticBatchEnabled: boolean
   extraDestinations?: Array<any>
 }
 export interface UpdateStreamParamsNode {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicknode/sdk",
-  "version": "3.1.0-alpha.14",
+  "version": "3.1.0-alpha.15",
   "description": "Quicknode SDK",
   "main": "sdk.js",
   "types": "sdk.d.ts",
@@ -46,10 +46,10 @@
   },
   "license": "MIT",
   "optionalDependencies": {
-    "@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"
+    "@quicknode/sdk-linux-x64-gnu": "3.1.0-alpha.15",
+    "@quicknode/sdk-linux-arm64-gnu": "3.1.0-alpha.15",
+    "@quicknode/sdk-linux-x64-musl": "3.1.0-alpha.15",
+    "@quicknode/sdk-linux-arm64-musl": "3.1.0-alpha.15",
+    "@quicknode/sdk-darwin-arm64": "3.1.0-alpha.15"
   }
 }

package/sdk.d.ts

@@ -6,12 +6,7 @@ import {
   S3Attributes,
   AzureAttributes,
   PostgresAttributes,
-  MysqlAttributes,
-  MongoAttributes,
-  ClickhouseAttributes,
-  SnowflakeAttributes,
   KafkaAttributes,
-  RedisAttributes,
   WebhookTemplateId,
   EvmWalletFilterTemplate,
   EvmContractEventsTemplate,
@@ -32,12 +27,7 @@ export type StreamDestinationAttributesInput =
   | { destination: "s3"; attributes: S3Attributes }
   | { destination: "azure"; attributes: AzureAttributes }
   | { destination: "postgres"; attributes: PostgresAttributes }
-  | { destination: "mysql"; attributes: MysqlAttributes }
-  | { destination: "mongo"; attributes: MongoAttributes }
-  | { destination: "clickhouse"; attributes: ClickhouseAttributes }
-  | { destination: "snowflake"; attributes: SnowflakeAttributes }
-  | { destination: "kafka"; attributes: KafkaAttributes }
-  | { destination: "redis"; attributes: RedisAttributes };
+  | { destination: "kafka"; attributes: KafkaAttributes };
 
 // Stream destination attributes (response). Mirrors the input shape so a
 // response can be round-tripped back into an update call without renaming.
@@ -117,12 +107,7 @@ export type {
   S3Attributes,
   AzureAttributes,
   PostgresAttributes,
-  MysqlAttributes,
-  MongoAttributes,
-  ClickhouseAttributes,
-  SnowflakeAttributes,
   KafkaAttributes,
-  RedisAttributes,
   AddressBookConfig,
   StreamsApiClient,
   // billing