@direct.dev/sdk 1.0.0

package/LICENSE.md

@@ -0,0 +1,6 @@
+Copyright © 2025 0ms Inc. d/b/a Direct. All rights reserved.
+
+This software is provided under the Direct Terms and Conditions, available at:
+https://direct.dev/terms
+
+By using this software, you agree to the Direct Terms and Conditions.

package/README.md

@@ -0,0 +1,339 @@
+# @direct.dev/sdk
+
+<div align="center">
+  <p>
+    <a href="https://direct.dev/">
+      <img src="https://s6.imgcdn.dev/YVbIIy.png" alt="Direct.dev logo" width="125" />
+    </a>
+  </p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@direct.dev/sdk"><img alt="NPM Version" src="https://img.shields.io/npm/v/%40direct.dev%2Fsdk?style=for-the-badge&labelColor=555&color=00BCB1"></a>
+    <a href="https://direct.dev/terms"><img alt="License" src="https://img.shields.io/badge/license-Direct.dev%20Terms-blue?style=for-the-badge&labelColor=555&color=00BCB1"></a>
+  </p>
+</div>
+
+A drop-in `fetch` wrapper for [Direct.dev](https://direct.dev/) RPC endpoints. Your existing code keeps working — Direct.dev quietly takes over JSON-RPC calls to its own URLs and serves them faster, with caching, sync, and failover built in. Everything else passes through to native `fetch` untouched.
+
+## Highlights
+
+**Sub-millisecond responses**<br />
+Popular requests are answered from a local cache; the rest are routed through the Direct.dev edge.
+
+**Less bandwidth**<br />
+Direct Sync streams only what changed since your last call, instead of resending the full payload every time.
+
+**Compact wire format**<br />
+Direct Wire is a binary protocol tuned for Web3 traffic — smaller frames and faster decode than JSON-RPC.
+
+**Built-in failover**<br />
+Calls reroute through a healthy path automatically when an upstream is unavailable. No retry logic to write.
+
+**Drop-in**<br />
+Plugs into native `fetch`, so viem, ethers, and your own code work unchanged. Only Direct.dev URLs are intercepted.
+
+## Install
+
+```sh
+npm install @direct.dev/sdk
+```
+
+## Quick start
+
+Call `install()` once at app startup and you're done:
+
+```ts
+import { install } from "@direct.dev/sdk";
+
+install();
+
+const res = await fetch("https://rpc.direct.dev/v1/<projectId>.<token>/ethereum", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [] }),
+});
+
+const { result } = await res.json();
+// "0x134a1c0"
+```
+
+That's it. Every call to a Direct.dev RPC URL now goes through the SDK; everything else still hits native `fetch`.
+
+### With options
+
+```ts
+install({
+  logging: { client: "warn", requests: "summary" },
+});
+```
+
+### Without touching globals
+
+If you'd rather not wrap `globalThis.fetch` (e.g. inside a library, or to scope to a single instance), use `createFetch()`:
+
+```ts
+import { createFetch } from "@direct.dev/sdk";
+
+const directFetch = createFetch({
+  logging: { client: "info" },
+});
+
+const res = await directFetch("https://rpc.direct.dev/v1/<projectId>.<token>/ethereum", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [] }),
+});
+
+const { result } = await res.json();
+```
+
+> Pick one — `install()` or `createFetch()`. Don't mix them.
+
+## Using with viem
+
+With `install()`, viem (and anything else that reaches for `fetch`) just works:
+
+```ts
+import { install } from "@direct.dev/sdk";
+import { createPublicClient, http } from "viem";
+import { mainnet } from "viem/chains";
+
+install();
+
+const client = createPublicClient({
+  chain: mainnet,
+  transport: http("https://rpc.direct.dev/v1/<projectId>.<token>/ethereum"),
+});
+
+await client.getBlockNumber();
+```
+
+If you'd rather keep the global `fetch` untouched, pass `createFetch()` directly:
+
+```ts
+import { createPublicClient, http } from "viem";
+import { mainnet } from "viem/chains";
+import { createFetch } from "@direct.dev/sdk";
+
+const directFetch = createFetch({ logging: { client: "info" } });
+
+const client = createPublicClient({
+  chain: mainnet,
+  transport: http("https://rpc.direct.dev/v1/<projectId>.<token>/ethereum", {
+    fetch: directFetch,
+  }),
+});
+```
+
+## Preload
+
+Warm endpoints at startup so the first request resolves locally.
+
+In the browser, prefer an HTML preload link. It lets the browser start fetching the warmup payload before your JS bundle even loads:
+
+```html
+<link
+  rel="preload"
+  as="fetch"
+  crossorigin="anonymous"
+  href="https://rpc.direct.dev/v1/<projectId>.<token>/ethereum"
+/>
+```
+
+On the server, or in environments without preload links, pass `preload` to `install()`:
+
+```ts
+install({
+  preload: [
+    "https://rpc.direct.dev/v1/<projectId>.<token>/ethereum",
+    "https://rpc.direct.dev/v1/<projectId>.<token>/sonic",
+  ],
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `logging.client` | `"silent" \| "error" \| "warn" \| "info" \| "debug"` | `"warn"` | Operational / lifecycle log verbosity. |
+| `logging.requests` | `"off" \| "summary" \| "debug"` | `"off"` | Per-request tracing. |
+| `logging.onEvent` | `(event) => void` | — | Structured event sink. Replaces console output when set. |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Underlying fetch to wrap. |
+| `createWebSocket` | `(url) => WebSocket` | `globalThis.WebSocket` | WebSocket factory for Direct Wire sync. |
+| `preload` | `string[]` | auto from `<link rel="preload">` | Endpoint URLs to warm at startup. In the browser, the SDK already picks up `<link rel="preload">` tags automatically — use this option for SSR / non-browser runtimes, or to add endpoints not declared in the HTML. |
+
+### `fetch`
+
+Wrap a specific implementation instead of `globalThis.fetch`. Useful in tests, polyfilled environments, or when you want a `createFetch()` instance that bypasses an existing `install()`:
+
+```ts
+const directFetch = createFetch({
+  fetch: window.fetch.bind(window),
+});
+```
+
+### `createWebSocket`
+
+Provide your own constructor for the Direct Wire sync connection. Handy for instrumentation, tests, or runtimes where `globalThis.WebSocket` isn't what you want:
+
+```ts
+install({
+  createWebSocket: (url) => new WebSocket(url),
+});
+```
+
+## Logging
+
+The `logging` option covers three independent concerns:
+
+- **`logging.client`** — operational logs (preload, sync, client phases).
+- **`logging.requests`** — per-request tracing.
+- **`logging.onEvent`** — a structured sink. When set, events go here instead of the console.
+
+`logging.client` and `logging.requests` don't gate each other — `requests: "summary"` still logs request summaries when `client` is `"warn"`.
+
+### `logging.client`
+
+| Level | What's emitted |
+| --- | --- |
+| `silent` | Nothing. |
+| `error` | Errors only. `[direct:ERROR] Batch contains duplicate request IDs { ids: [1, 1] }` |
+| `warn` | Errors + warnings. `[direct:WARN] Request failed { input: ..., err: ... }` |
+| `info` | Reserved for sparse operational summaries. No default emissions yet. |
+| `debug` | Full lifecycle: preload, sync, client phases. |
+
+Example debug output:
+
+```text
+[direct:DEBUG] preload.phase {
+  phase: "applied",
+  client_instance_id: "client_ethereum_f47ac10b_1",
+  network_id: "ethereum"
+}
+[direct:DEBUG] client.phase {
+  phase: "created",
+  client_instance_id: "client_ethereum_f47ac10b_1",
+  network_id: "ethereum"
+}
+```
+
+### `logging.requests`
+
+| Level | What's emitted |
+| --- | --- |
+| `off` | No request tracing. |
+| `summary` | One concise resolution log per handled request. |
+| `debug` | `request_resolution` + `request_pipeline_resolution` + `request_handled` + `block.state_probe`. |
+
+Summary example:
+
+```text
+[direct:REQUEST] request_resolution {
+  method: "eth_blockNumber",
+  latency_ms: 8,
+  stage_type: "cache",
+  stage_name: "local_memory_cache"
+}
+```
+
+Debug example (a single request):
+
+```text
+[direct:REQUEST_DEBUG] request_pipeline_resolution {
+  method: "eth_call",
+  latency_ms: 12,
+  stage_type: "cache",
+  stage_name: "continuum_cache"
+}
+[direct:REQUEST_DEBUG] request_handled {
+  req: { jsonrpc: "2.0", id: 1, method: "eth_call", params: [...] },
+  res: { jsonrpc: "2.0", id: 1, result: "0x1" },
+  latency_ms: 12
+}
+```
+
+### `logging.onEvent`
+
+Get events as structured objects — useful for dashboards, telemetry, or piping into your own observability stack:
+
+```ts
+install({
+  logging: {
+    client: "debug",
+    requests: "debug",
+    onEvent(event) {
+      dashboard.push(event);
+    },
+  },
+});
+```
+
+Event shape:
+
+```ts
+type DirectLogEvent = {
+  level: "debug" | "info" | "warn" | "error";
+  name: string;
+  value: Record<string, unknown>;
+  timestamp: number;
+};
+```
+
+**Stable public events** — always safe to consume:
+
+- `request_resolution`
+- `preload.phase`
+- `preload.clock_sync`
+- `sync.rebuild`
+- `client.phase`
+
+**Debug-only diagnostics** — only emitted when the relevant log level is active:
+
+- `request_pipeline_resolution`
+- `request_handled`
+- `block.state_probe`
+
+Typed helper unions live in `@direct.dev/client`: `KnownDirectLogEvent`, `StableDirectLogEvent`, `DebugDirectLogEvent`.
+
+## Inspecting the live client
+
+The SDK intercepts a special JSON-RPC method, `direct_client_status`, and answers it locally without touching the network. Useful for debugging your integration:
+
+```ts
+const res = await fetch("https://rpc.direct.dev/v1/<projectId>.<token>/ethereum", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "direct_client_status",
+    params: [],
+  }),
+});
+
+const { result } = await res.json();
+// {
+//   initialized: true,
+//   projectId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+//   projectToken: "abc123",
+//   networkId: "ethereum",
+//   baseUrl: "https://rpc.direct.dev",
+//   logging: { client: "warn", requests: "off" }
+// }
+```
+
+## How it works
+
+The SDK only takes over POST requests whose body is JSON-RPC and whose URL matches a Direct.dev RPC endpoint:
+
+- `https://rpc.direct.dev/v1/<projectId>.<token>/<networkId>`
+- `https://staging.rpc.direct.dev/v1/<projectId>.<token>/<networkId>`
+- `https://prod.rpc.direct.dev/v1/<projectId>.<token>/<networkId>`
+
+Everything else — REST APIs, image loads, third-party APIs — passes straight through to native `fetch`.
+
+## License
+
+Provided under the [Direct.dev Terms and Conditions](https://direct.dev/terms). Use of this package requires agreement to those terms.
+
+For questions, reach out at [info@direct.dev](mailto:info@direct.dev).