@direct.dev/sdk 1.0.0 → 1.0.1

package/lib/index.d.ts

@@ -1,8 +1,139 @@
+/**
+ * Branded subtype of number for returned timestamps, used to guarantee
+ * correctness of date processing integrations and argument forwarding.
+ */
+type Timestamp = number & {
+    readonly __tsBrand: unique symbol;
+};
+
+/**
+ * Factory for creating WebSocket connections used by Direct Wire transports.
+ *
+ * This allows callers to simulate or instrument websocket behavior without
+ * globally monkeypatching `WebSocket`.
+ */
+type DirectCreateWebSocket = (url: string) => WebSocket;
+/**
+ * Public log levels exposed by the Direct.dev client surface.
+ *
+ * These are intentionally smaller than the internal Pulse log levels to keep
+ * the user-facing API simple and predictable.
+ */
+type ClientLogLevel = "silent" | "info" | "debug" | "warn" | "error";
+/**
+ * Per-request logging mode for request tracing and cache-resolution insight.
+ *
+ * - `off`: no request logs
+ * - `summary`: one concise resolution line per handled request
+ * - `debug`: detailed request/response logging plus pipeline stage diagnostics
+ */
+type RequestLogging = "off" | "summary" | "debug";
+/**
+ * Event emitted by Direct client logging hooks.
+ *
+ * Stable public events:
+ * - `request_resolution`
+ * - `preload.phase`
+ * - `preload.clock_sync`
+ * - `sync.rebuild`
+ * - `client.phase`
+ *
+ * Debug-oriented events:
+ * - `request_pipeline_resolution`
+ * - `request_handled`
+ * - `block.state_probe`
+ *
+ * Consumers should prefer the stable set unless they explicitly need deeper
+ * diagnostics from debug logging.
+ */
+type DirectLogEvent = {
+    level: Exclude<ClientLogLevel, "silent">;
+    name: string;
+    value: Record<string, unknown>;
+    timestamp: Timestamp;
+};
+/**
+ * Callback invoked for every emitted Direct client log event.
+ */
+type DirectLogEventListener = (event: DirectLogEvent) => void;
+/**
+ * Unified logging configuration for Direct client surfaces.
+ */
+type DirectLoggingConfig = {
+    /**
+     * Controls operational/client log verbosity.
+     *
+     * This governs operational and lifecycle events such as:
+     * - `preload.phase`
+     * - `preload.clock_sync`
+     * - `sync.rebuild`
+     * - `client.phase`
+     *
+     * @default "warn"
+     */
+    client?: ClientLogLevel;
+    /**
+     * Controls request-level tracing emitted by the client.
+     *
+   * This governs:
+   * - stable request completion: `request_resolution`
+   * - deeper diagnostics: `request_pipeline_resolution`, `request_handled`,
+   *   and `block.state_probe`
+     *
+     * @default "off"
+     */
+    requests?: RequestLogging;
+    /**
+     * Optional sink for intercepting emitted log events.
+     */
+    onEvent?: DirectLogEventListener;
+};
+
+/**
+ * Shared types for the Direct.dev SDK.
+ */
+
+/**
+ * Options for the fetch wrapper.
+ */
+type CreateFetchOptions = {
+    /** Optional fetch implementation to wrap (defaults to global fetch). */
+    fetch?: typeof globalThis.fetch;
+    /** Optional WebSocket factory used by the underlying Direct client. */
+    createWebSocket?: DirectCreateWebSocket;
+    /** Unified logging configuration for operational logs and request tracing. */
+    logging?: DirectLoggingConfig;
+    /** URLs to preload on init (fire-and-forget). */
+    preload?: string[];
+};
+type LoggingOptions = DirectLoggingConfig;
+type LogEvent = DirectLogEvent;
+
 /**
  * @direct.dev/sdk
  *
- * Fetch wrapper that intercepts direct.dev RPC calls and routes them through
+ * Direct.dev SDK that intercepts direct.dev RPC calls and routes them through
  * DirectRPCClient while preserving fetch semantics.
  */
-export { createFetch, install, type UninstallFn } from "./_fetch.js";
-export type { CreateFetchOptions, LogEvent, LoggingOptions } from "./typings.js";
+
+/**
+ * Create a fetch wrapper that intercepts direct.dev JSON-RPC calls.
+ * Each createFetch instance maintains its own isolated client pool.
+ *
+ * After install(), callers must provide an explicit base fetch to avoid
+ * wrapping the installed fetch instance.
+ */
+declare const createFetch: (rawOptions?: CreateFetchOptions) => typeof fetch;
+/**
+ * Uninstall function returned by install().
+ */
+type UninstallFn = () => void;
+/**
+ * Install the fetch wrapper globally on `globalThis.fetch`.
+ * Returns an uninstall function that restores the original fetch.
+ * Repeated installs are idempotent and return the active uninstall function.
+ */
+declare const install: (options?: CreateFetchOptions) => UninstallFn;
+
+export { createFetch, install };
+export type { CreateFetchOptions, LogEvent, LoggingOptions, UninstallFn };