> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usespoke.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Public read SDK

> Install the versioned Spoke SDK and read public campaigns, receipts, graphs, and system status with validated types.

A typed, credential-free client for 32 public Spoke API methods. Version **0.1.2** targets API `/v1`, schema `3.0`, and the current Monad Testnet deployment. Monetary amounts remain base-unit strings.

## Install

Install the versioned package from npm:

```bash theme={null}
npm install @enochid/spoke-sdk@0.1.2
```

<Note>
  The public npm package is
  [`@enochid/spoke-sdk`](https://www.npmjs.com/package/@enochid/spoke-sdk). The
  [GitHub
  release](https://github.com/Enoch208/docs-madonna/releases/tag/sdk-v0.1.2)
  contains the same archive and a SHA-256 checksum.
</Note>

The archive includes compiled ESM/CommonJS and TypeScript declarations. It bundles the shared protocol schemas, so consumers do not need the Spoke monorepo or `@spoke/protocol`. Node.js 22 or later is supported. Browser integrations require native `fetch` and `AbortSignal.timeout`; their API deployment must also allow the browser origin through CORS. A server-side integration works without browser CORS restrictions. Browser credentials are always omitted.

## Read a receipt

```ts theme={null}
import { createSpokeClient, SpokeApiError } from "@enochid/spoke-sdk";

const spoke = createSpokeClient({ baseUrl: "https://api.usespoke.xyz" });

try {
  const receipt = await spoke.read("receipts.get", {
    saleId: "4",
    chainId: 10143,
  });
  console.log(receipt);
} catch (error) {
  if (error instanceof SpokeApiError) {
    console.error(error.code, error.status, error.requestId, error.retryable);
  } else {
    throw error;
  }
}
```

Pass the API origin, without `/v1`. CommonJS consumers can use `require("@enochid/spoke-sdk")`. Every request validates both its input and the successful response against the bundled shared Zod contract.

## Retain freshness and chain context

```ts theme={null}
const result = await spoke.readEnvelope("receipts.get", {
  saleId: "4",
  chainId: 10143,
});
console.log(
  result.requestId,
  result.chainId,
  result.blockNumber,
  result.indexingStatus,
);
console.log(result.data);
```

Indexing metadata describes a derived view. Check canonical receipts and contracts when settlement certainty matters. The hosted deployment uses non-redeemable SDUSD on Monad Testnet, not real-money mainnet settlement.

## Methods and types

`publicReadMethods` lists all 32 supported methods. They cover campaigns, products, merchants, links, graphs, checkout previews, receipts, distributor profiles, networks, tokens and system status. `SpokeReadInput<M>` and `SpokeReadOutput<M>` expose per-method types. `SpokeReadEnvelope<M>` describes the envelope; `SpokeReadClient` is the client type.

Paginated reads accept an opaque `cursor` and return `nextCursor`. Pass the returned cursor to the same method with the same filters; stop when it is null. Do not infer page numbers or create cursor strings yourself. The [method reference](https://docs.usespoke.xyz/reference/overview) lists the exact shapes.

## Errors and transport

`SpokeApiError` retains a structured server error's code, HTTP status, request ID and retryability. Input/response validation failures are Zod errors. Network failures, timeouts and invalid JSON can throw native transport/parsing errors; do not assume every rejection is a `SpokeApiError`.

Each request has a ten-second timeout. There are no automatic retries: callers decide bounded backoff for retryable reads. An optional `fetch` implementation supports framework integration and tests; it must respect the supplied signal and `credentials: "omit"`. Never pass private server RPC credentials as the API origin.

The SDK only reads public data. It does not sign transactions, hold keys, maintain authenticated sessions, issue claims or implement checkout writes. Runtime calls outside `publicReadMethods` are refused.

## Versions and releases

Pin exact SDK versions for repeatable integrations. Before 1.0, breaking changes increment the minor version; compatible fixes increment the patch version. The first release validates schema 3.0 responses, but the HTTP deployment is independently versioned and an SDK update may be required when its contract changes. Read [SDK changelog](https://github.com/Enoch208/docs-madonna/releases/tag/sdk-v0.1.2) before upgrading.

Maintainers build and check an isolated installation before publication:

```bash theme={null}
pnpm --filter @enochid/spoke-sdk build
pnpm --filter @enochid/spoke-sdk release:check
pnpm --filter @enochid/spoke-sdk exec npm pack --ignore-scripts
```

`release:check` installs the actual packed archive in a temporary project, checks the file allowlist, loads both module formats and typechecks ESM/CommonJS consumers. Publish that verified archive, never the repository root. npm registry publication requires access to the `@enochid` scope and a valid npm login. GitHub release assets provide the same package independently of the registry.

The application source repository requires repository access. The SDK archive, documentation and release notes are public through the documentation repository.

## Upgrade from the GitHub archive

Versions 0.1.0 and 0.1.1 used the name `@spoke/sdk` inside their GitHub archives. Version 0.1.2 is published on npm under `@enochid/spoke-sdk`. Update the dependency and import path:

```bash theme={null}
npm uninstall @spoke/sdk
npm install @enochid/spoke-sdk@0.1.2
```

```ts theme={null}
import { createSpokeClient } from "@enochid/spoke-sdk";
```

The methods, validation, and runtime behavior are unchanged from 0.1.1. The earlier GitHub archives remain available for pinned integrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.