@direct.dev/sdk 1.0.0 → 1.0.2

package/README.md

@@ -13,7 +13,7 @@
   </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.
+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 requests to its own URLs and serves them faster, with caching, sync, and failover built in.
 
 ## Highlights
 
@@ -21,13 +21,13 @@ A drop-in `fetch` wrapper for [Direct.dev](https://direct.dev/) RPC endpoints. Y
 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.
+Direct Sync streams only what changed since your last request, 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.
+Requests 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.
@@ -40,14 +40,14 @@ npm install @direct.dev/sdk
 
 ## Quick start
 
-Call `install()` once at app startup and you're done:
+Run `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", {
+const res = await fetch("https://rpc.direct.dev/v1/<project>.<token>/ethereum", {
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [] }),
@@ -57,7 +57,7 @@ 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`.
+That's it. Every request to a Direct.dev RPC URL now goes through the SDK.
 
 ### With options
 
@@ -78,7 +78,7 @@ const directFetch = createFetch({
   logging: { client: "info" },
 });
 
-const res = await directFetch("https://rpc.direct.dev/v1/<projectId>.<token>/ethereum", {
+const res = await directFetch("https://rpc.direct.dev/v1/<project>.<token>/ethereum", {
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [] }),
@@ -102,7 +102,7 @@ install();
 
 const client = createPublicClient({
   chain: mainnet,
-  transport: http("https://rpc.direct.dev/v1/<projectId>.<token>/ethereum"),
+  transport: http("https://rpc.direct.dev/v1/<project>.<token>/ethereum"),
 });
 
 await client.getBlockNumber();
@@ -119,7 +119,7 @@ const directFetch = createFetch({ logging: { client: "info" } });
 
 const client = createPublicClient({
   chain: mainnet,
-  transport: http("https://rpc.direct.dev/v1/<projectId>.<token>/ethereum", {
+  transport: http("https://rpc.direct.dev/v1/<project>.<token>/ethereum", {
     fetch: directFetch,
   }),
 });
@@ -136,7 +136,7 @@ In the browser, prefer an HTML preload link. It lets the browser start fetching
   rel="preload"
   as="fetch"
   crossorigin="anonymous"
-  href="https://rpc.direct.dev/v1/<projectId>.<token>/ethereum"
+  href="https://rpc.direct.dev/v1/<project>.<token>/ethereum"
 />
 ```
 
@@ -145,8 +145,8 @@ On the server, or in environments without preload links, pass `preload` to `inst
 ```ts
 install({
   preload: [
-    "https://rpc.direct.dev/v1/<projectId>.<token>/ethereum",
-    "https://rpc.direct.dev/v1/<projectId>.<token>/sonic",
+    "https://rpc.direct.dev/v1/<project>.<token>/ethereum",
+    "https://rpc.direct.dev/v1/<project>.<token>/sonic",
   ],
 });
 ```
@@ -157,14 +157,14 @@ install({
 | --- | --- | --- | --- |
 | `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. |
+| `logging.onEvent` | `(event: LogEvent) => 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()`:
+Wrap a specific implementation instead of `globalThis.fetch`. Useful in tests, custom runtimes, or when you need a `createFetch()` instance that bypasses an existing `install()`:
 
 ```ts
 const directFetch = createFetch({
@@ -199,7 +199,7 @@ The `logging` option covers three independent concerns:
 | `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. |
+| `info` | Sparse operational summaries, including live sync connection state. |
 | `debug` | Full lifecycle: preload, sync, client phases. |
 
 Example debug output:
@@ -215,6 +215,27 @@ Example debug output:
   client_instance_id: "client_ethereum_f47ac10b_1",
   network_id: "ethereum"
 }
+[direct:INFO] sync.connection {
+  client_instance_id: "client_ethereum_f47ac10b_1",
+  network_id: "ethereum",
+  connected: true,
+  transport: "wire_socket",
+  reason: "started"
+}
+[direct:INFO] sync.ready {
+  client_instance_id: "client_ethereum_f47ac10b_1",
+  network_id: "ethereum",
+  ready: true,
+  transport: "wire_socket",
+  reason: "block_state_available",
+  current_block_height: "0x134a1c0"
+}
+[direct:INFO] block.advanced {
+  client_instance_id: "client_ethereum_f47ac10b_1",
+  network_id: "ethereum",
+  source: "wire_socket",
+  current_block_height: "0x134a1c1"
+}
 ```
 
 ### `logging.requests`
@@ -257,13 +278,17 @@ Debug example (a single request):
 Get events as structured objects — useful for dashboards, telemetry, or piping into your own observability stack:
 
 ```ts
+import { install, type LogEvent } from "@direct.dev/sdk";
+
+const onDirectEvent = (event: LogEvent) => {
+  dashboard.push(event);
+};
+
 install({
   logging: {
     client: "debug",
     requests: "debug",
-    onEvent(event) {
-      dashboard.push(event);
-    },
+    onEvent: onDirectEvent,
   },
 });
 ```
@@ -271,7 +296,7 @@ install({
 Event shape:
 
 ```ts
-type DirectLogEvent = {
+type LogEvent = {
   level: "debug" | "info" | "warn" | "error";
   name: string;
   value: Record<string, unknown>;
@@ -285,6 +310,9 @@ type DirectLogEvent = {
 - `preload.phase`
 - `preload.clock_sync`
 - `sync.rebuild`
+- `sync.connection`
+- `sync.ready`
+- `block.advanced`
 - `client.phase`
 
 **Debug-only diagnostics** — only emitted when the relevant log level is active:
@@ -293,14 +321,14 @@ type DirectLogEvent = {
 - `request_handled`
 - `block.state_probe`
 
-Typed helper unions live in `@direct.dev/client`: `KnownDirectLogEvent`, `StableDirectLogEvent`, `DebugDirectLogEvent`.
+The SDK exports `LogEvent`, `LoggingOptions`, and `CreateFetchOptions` for typed integrations.
 
 ## 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", {
+const res = await fetch("https://rpc.direct.dev/v1/<project>.<token>/ethereum", {
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({
@@ -326,11 +354,9 @@ const { result } = await res.json();
 
 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`.
+- `https://rpc.direct.dev/v1/<project>.<token>/<network>`
+- `https://staging.rpc.direct.dev/v1/<project>.<token>/<network>`
+- `https://prod.rpc.direct.dev/v1/<project>.<token>/<network>`
 
 ## License