@wovin/core 0.2.0 → 0.3.0

package/dist/ipns/ipns-watcher.d.ts

@@ -0,0 +1,190 @@
+import { CID } from 'multiformats/cid';
+import { type Options as PartysocketOptions } from 'partysocket/ws';
+export type { PartysocketOptions };
+export interface W3NameRecord {
+    value: string;
+    seq?: number;
+    validity?: string;
+}
+/**
+ * Debug info provided when a stale WebSocket connection is detected.
+ */
+export interface StaleConnectionInfo {
+    /** When the WebSocket connection was established */
+    connectedAt: Date;
+    /** When we last received a WebSocket message */
+    lastMessageAt: Date | null;
+    /** How long since last message (ms) */
+    silenceDuration: number;
+    /** The stale value from WebSocket */
+    staleValue: string | null;
+    /** The current value from HTTP */
+    currentValue: string;
+}
+/**
+ * Enriched IPNS update with parsed CID and change detection.
+ * Backwards compatible - `.value` still works as before.
+ */
+export interface IpnsUpdate {
+    /** Raw IPNS value string (e.g. '/ipfs/bafy...') — same as W3NameRecord.value */
+    value: string;
+    /** Parsed CID if value is valid IPFS path, null otherwise */
+    cid: CID | null;
+    /** Previous value (null on first update) */
+    lastValue: string | null;
+    /** Whether this is a change from lastValue */
+    isNew: boolean;
+    /** Original W3NameRecord for access to seq/validity */
+    record: W3NameRecord;
+}
+export interface WatchRawOptions {
+    /** Called when the IPNS record is updated */
+    onUpdate: (record: W3NameRecord) => void;
+    /** Called when an error occurs */
+    onError?: (error: Event | Error) => void;
+    /** Called when the connection is opened */
+    onOpen?: () => void;
+    /** Called when the connection is closed */
+    onClose?: (event: CloseEvent) => void;
+}
+export interface WatchRawSubscription {
+    /** Close the WebSocket connection */
+    close: () => void;
+    /** The underlying WebSocket instance */
+    ws: WebSocket;
+}
+/**
+ * Low-level WebSocket watcher for IPNS (no reconnect logic).
+ * Use this when you want full control over connection lifecycle.
+ * For most cases, prefer `watchName` or `IpnsWatcher` which handle reconnection.
+ *
+ * @param nameBaseUrl - Base URL of a naming service that supports `/name/<ipns>/watch` (WebSocket) and `/name/<ipns>` (HTTP)
+ * @param name - The IPNS name/key to watch
+ * @param options - Callback options
+ * @returns Subscription with close() and ws
+ *
+ * @example
+ * ```ts
+ * const sub = watchNameRaw('https://name.example.com', 'k51qzi5u...', {
+ *   onUpdate: (record) => console.log('Update:', record.value),
+ *   onClose: () => console.log('Disconnected - handle reconnect yourself'),
+ * })
+ * ```
+ */
+export declare function watchNameRaw(nameBaseUrl: string, name: string, options: WatchRawOptions): WatchRawSubscription;
+export interface IpnsWatcherOptions {
+    /** Called when the IPNS record is updated (enriched payload with CID and change detection) */
+    onUpdate: (update: IpnsUpdate) => void | Promise<void>;
+    /** Called when an error occurs */
+    onError?: (error: Error | Event) => void;
+    /** Called when the connection is opened/reconnected */
+    onConnected?: () => void;
+    /** Called when the connection is closed */
+    onDisconnected?: () => void;
+    /** Fetch current IPNS state on first connect (default: false) */
+    fetchInitialState?: boolean;
+    /** Fetch current IPNS state on reconnect to catch missed updates (default: true) */
+    catchUpOnReconnect?: boolean;
+    /** If true, call onUpdate even when value hasn't changed (default: false) */
+    includeUnchanged?: boolean;
+    /**
+     * Enable periodic liveness checks via HTTP to detect zombie connections (default: true).
+     * When enabled, periodically fetches current IPNS value and forces reconnect if it
+     * differs from the last WebSocket update.
+     */
+    livenessCheck?: boolean;
+    /**
+     * Liveness check interval in milliseconds (default: 3600000 = 1 hour).
+     * Only used when livenessCheck is enabled.
+     */
+    livenessCheckInterval?: number;
+    /**
+     * Called when a stale connection is detected (WebSocket missed updates).
+     * Provides debug info about the connection state.
+     */
+    onStaleConnection?: (info: StaleConnectionInfo) => void;
+    /**
+     * Partysocket options (passed through to ReconnectingWebSocket).
+     * Useful options: startClosed, maxReconnectionDelay, minReconnectionDelay, etc.
+     * @see https://github.com/partykit/partykit/tree/main/packages/partysocket
+     */
+    wsOptions?: PartysocketOptions;
+}
+export declare class IpnsWatcher {
+    private name;
+    private nameBaseUrl;
+    private ws;
+    private lastKnownValue;
+    private options;
+    private isFirstConnect;
+    private livenessTimer;
+    private connectedAt;
+    private lastMessageAt;
+    constructor(nameBaseUrl: string, name: string, options: IpnsWatcherOptions);
+    /**
+     * Resolve current IPNS value via HTTP API to catch missed updates
+     */
+    private checkForMissedUpdates;
+    /**
+     * Start periodic liveness checks to detect zombie connections.
+     */
+    private startLivenessCheck;
+    /**
+     * Stop periodic liveness checks.
+     */
+    private stopLivenessCheck;
+    /**
+     * Perform a single liveness check via HTTP.
+     * If the HTTP value differs from lastKnownValue, the connection is stale.
+     */
+    private performLivenessCheck;
+    /**
+     * Manually start/reconnect the WebSocket.
+     * Only needed if you used `wsOptions: { startClosed: true }`.
+     */
+    start(): void;
+    /**
+     * Alias for close() - for backward compatibility
+     */
+    stop(): void;
+    /**
+     * Close the WebSocket connection and stop watching
+     */
+    close(): void;
+    /**
+     * Get the last known IPNS value
+     */
+    get lastValue(): string | null;
+    /**
+     * Get the WebSocket ready state
+     */
+    get readyState(): number;
+}
+/**
+ * Create an IPNS watcher with auto-reconnect and catch-up logic.
+ * Convenience function that creates and returns an IpnsWatcher instance.
+ *
+ * @param nameBaseUrl - Base URL of a naming service that supports `/name/<ipns>/watch` (WebSocket) and `/name/<ipns>` (HTTP)
+ * @param name - The IPNS name/key to watch (e.g. "k51qzi5u...")
+ * @param options - Callback options for handling events
+ * @returns An IpnsWatcher instance with close() method
+ */
+export declare function watchName(nameBaseUrl: string, name: string, options: IpnsWatcherOptions): IpnsWatcher;
+/**
+ * Watch an IPNS name and return updates as an async iterator.
+ * Includes auto-reconnect - iterator continues through disconnections.
+ *
+ * @param nameBaseUrl - Base URL of a naming service that supports `/name/<ipns>/watch` (WebSocket) and `/name/<ipns>` (HTTP)
+ * @param name - The IPNS name/key to watch
+ * @param signal - Optional AbortSignal to stop the watch
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController()
+ * for await (const update of watchNameIterator('https://name.example.com', 'k51qzi5u...', controller.signal)) {
+ *   console.log('Update:', update.cid?.toString())
+ * }
+ * ```
+ */
+export declare function watchNameIterator(nameBaseUrl: string, name: string, signal?: AbortSignal): AsyncGenerator<IpnsUpdate, void, unknown>;
+//# sourceMappingURL=ipns-watcher.d.ts.map

package/dist/ipns/ipns-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipns-watcher.d.ts","sourceRoot":"","sources":["../../src/ipns/ipns-watcher.ts"],"names":[],"mappings":"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"}

package/dist/ipns.d.ts

@@ -1,2 +1,5 @@
+export * from './ipns/gateway-resolver.ts';
 export * from './ipns/ipns-record.ts';
+export * from './ipns/ipns-w3name.ts';
+export * from './ipns/ipns-watcher.ts';
 //# sourceMappingURL=ipns.d.ts.map

package/dist/ipns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ipns.d.ts","sourceRoot":"","sources":["../src/ipns.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA"}
+{"version":3,"file":"ipns.d.ts","sourceRoot":"","sources":["../src/ipns.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,wBAAwB,CAAA"}