@diffdelta/client 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,230 @@
+/** A single item from a DiffDelta feed. */
+interface FeedItem {
+    /** Source identifier (e.g. "cisa_kev", "nist_nvd"). */
+    source: string;
+    /** Unique item ID within the source. */
+    id: string;
+    /** Human/agent-readable headline. */
+    headline: string;
+    /** Link to the original source. */
+    url: string;
+    /** Summary text extracted from the source. */
+    excerpt: string;
+    /** When the item was originally published. */
+    publishedAt: string | null;
+    /** When the item was last updated. */
+    updatedAt: string | null;
+    /** Which change bucket: "new", "updated", or "removed". */
+    bucket: "new" | "updated" | "removed";
+    /** Risk score 0–10, or null if not scored. */
+    riskScore: number | null;
+    /** Raw provenance data (fetched_at, evidence_urls, content_hash). */
+    provenance: Record<string, unknown>;
+    /** The full raw item object from the feed. */
+    raw: Record<string, unknown>;
+}
+/** The lightweight head pointer for change detection. */
+interface Head {
+    /** Opaque cursor string for change detection. */
+    cursor: string;
+    /** Content hash of the latest feed. */
+    hash: string;
+    /** Whether content has changed since last generation. */
+    changed: boolean;
+    /** When this head was generated. */
+    generatedAt: string;
+    /** Recommended polling interval in seconds. */
+    ttlSec: number;
+}
+/** A full DiffDelta feed response. */
+interface Feed {
+    /** The new cursor (save this for next poll). */
+    cursor: string;
+    /** The previous cursor. */
+    prevCursor: string;
+    /** Source ID (if per-source feed) or "global". */
+    sourceId: string;
+    /** When this feed was generated. */
+    generatedAt: string;
+    /** All items across all buckets. */
+    items: FeedItem[];
+    /** Items in the "new" bucket. */
+    new: FeedItem[];
+    /** Items in the "updated" bucket. */
+    updated: FeedItem[];
+    /** Items in the "removed" bucket. */
+    removed: FeedItem[];
+    /** Human-readable summary of what changed. */
+    narrative: string;
+    /** The full raw feed object. */
+    raw: Record<string, unknown>;
+}
+/** Metadata about an available DiffDelta source. */
+interface SourceInfo {
+    /** Unique source identifier (e.g. "cisa_kev"). */
+    sourceId: string;
+    /** Human-readable display name. */
+    name: string;
+    /** List of tags (e.g. ["security"]). */
+    tags: string[];
+    /** Brief description of the source. */
+    description: string;
+    /** URL of the source's homepage. */
+    homepage: string;
+    /** Whether the source is currently active. */
+    enabled: boolean;
+    /** Health status ("ok", "degraded", "error"). */
+    status: string;
+    /** Path to the source's head.json. */
+    headUrl: string;
+    /** Path to the source's latest.json. */
+    latestUrl: string;
+}
+
+/**
+ * DiffDelta TypeScript client — agent-ready intelligence feeds.
+ *
+ * @example
+ * ```ts
+ * import { DiffDelta } from "diffdelta";
+ *
+ * const dd = new DiffDelta();
+ *
+ * // Poll for new items across all sources
+ * const items = await dd.poll();
+ * items.forEach(i => console.log(`${i.source}: ${i.headline}`));
+ *
+ * // Poll only security sources
+ * const sec = await dd.poll({ tags: ["security"] });
+ *
+ * // Continuous monitoring
+ * dd.watch(item => console.log("🚨", item.headline), { tags: ["security"] });
+ * ```
+ */
+
+interface DiffDeltaOptions {
+    /** DiffDelta API base URL. Defaults to https://diffdelta.io. */
+    baseUrl?: string;
+    /** Pro/Enterprise API key (dd_live_...). */
+    apiKey?: string;
+    /**
+     * Path to cursor file. Defaults to ~/.diffdelta/cursors.json.
+     * Set to `null` to disable file persistence (in-memory only).
+     * Set to `"memory"` for explicit in-memory mode (serverless, edge).
+     */
+    cursorPath?: string | null;
+    /** HTTP timeout in milliseconds. Defaults to 15000. */
+    timeout?: number;
+}
+interface PollOptions {
+    /** Filter items to these tags (e.g. ["security"]). */
+    tags?: string[];
+    /** Filter items to these source IDs (e.g. ["cisa_kev", "nist_nvd"]). */
+    sources?: string[];
+    /**
+     * Which buckets to return.
+     * Defaults to ["new", "updated"].
+     * Use ["new", "updated", "removed"] to include removals.
+     */
+    buckets?: Array<"new" | "updated" | "removed">;
+}
+interface WatchOptions extends PollOptions {
+    /** Seconds between polls. Defaults to feed TTL (usually 900s). */
+    interval?: number;
+    /** If provided, an AbortSignal to stop watching. */
+    signal?: AbortSignal;
+}
+declare class DiffDelta {
+    readonly baseUrl: string;
+    readonly apiKey?: string;
+    readonly timeout: number;
+    private cursors;
+    private sourceTagsCache;
+    constructor(options?: DiffDeltaOptions);
+    /**
+     * Poll the global feed for new items since last poll.
+     *
+     * Checks head.json first (~400 bytes). Only fetches the full feed
+     * if the cursor has changed. Automatically saves the new cursor.
+     */
+    poll(options?: PollOptions): Promise<FeedItem[]>;
+    /**
+     * Poll a specific source for new items since last poll.
+     *
+     * More efficient than `poll({ sources: [...] })` if you only
+     * care about one source — fetches a smaller payload.
+     */
+    pollSource(sourceId: string, options?: Omit<PollOptions, "sources">): Promise<FeedItem[]>;
+    /**
+     * Fetch a head.json pointer.
+     * @param url Full URL to head.json. Defaults to global head.
+     */
+    head(url?: string): Promise<Head>;
+    /**
+     * Fetch a full latest.json feed.
+     * @param url Full URL to latest.json. Defaults to global latest.
+     */
+    fetchFeed(url?: string): Promise<Feed>;
+    /** List all available DiffDelta sources. */
+    sources(): Promise<SourceInfo[]>;
+    /**
+     * Continuously poll and call a function for each new item.
+     *
+     * @param callback - Async or sync function called for each new FeedItem.
+     * @param options - Watch options (tags, sources, interval, signal).
+     *
+     * @example
+     * ```ts
+     * dd.watch(item => {
+     *   console.log(`🚨 ${item.source}: ${item.headline}`);
+     * }, { tags: ["security"] });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Stop with AbortController
+     * const ac = new AbortController();
+     * dd.watch(handler, { signal: ac.signal });
+     * setTimeout(() => ac.abort(), 60_000); // stop after 1 minute
+     * ```
+     */
+    watch(callback: (item: FeedItem) => void | Promise<void>, options?: WatchOptions): Promise<void>;
+    /** Reset stored cursors so the next poll returns all current items. */
+    resetCursors(sourceId?: string): void;
+    private pollFeed;
+    private getSourceTags;
+    private fetchJson;
+    toString(): string;
+}
+
+/**
+ * Persists cursors to a local JSON file so bots survive restarts.
+ *
+ * By default, cursors are saved to ~/.diffdelta/cursors.json.
+ * Each feed key gets its own cursor entry.
+ */
+declare class CursorStore {
+    private path;
+    private cursors;
+    constructor(path?: string);
+    /** Get the stored cursor for a feed key. */
+    get(key: string): string | undefined;
+    /** Save a cursor and persist to disk. */
+    set(key: string, cursor: string): void;
+    /** Clear cursor(s). If key is undefined, clears all cursors. */
+    clear(key?: string): void;
+    private load;
+    private save;
+}
+/**
+ * In-memory-only cursor store (no file I/O).
+ * Useful for serverless, browser, or Deno environments.
+ */
+declare class MemoryCursorStore {
+    private cursors;
+    get(key: string): string | undefined;
+    set(key: string, cursor: string): void;
+    clear(key?: string): void;
+}
+
+export { CursorStore, DiffDelta, type DiffDeltaOptions, type Feed, type FeedItem, type Head, MemoryCursorStore, type PollOptions, type SourceInfo, type WatchOptions };

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+/** A single item from a DiffDelta feed. */
+interface FeedItem {
+    /** Source identifier (e.g. "cisa_kev", "nist_nvd"). */
+    source: string;
+    /** Unique item ID within the source. */
+    id: string;
+    /** Human/agent-readable headline. */
+    headline: string;
+    /** Link to the original source. */
+    url: string;
+    /** Summary text extracted from the source. */
+    excerpt: string;
+    /** When the item was originally published. */
+    publishedAt: string | null;
+    /** When the item was last updated. */
+    updatedAt: string | null;
+    /** Which change bucket: "new", "updated", or "removed". */
+    bucket: "new" | "updated" | "removed";
+    /** Risk score 0–10, or null if not scored. */
+    riskScore: number | null;
+    /** Raw provenance data (fetched_at, evidence_urls, content_hash). */
+    provenance: Record<string, unknown>;
+    /** The full raw item object from the feed. */
+    raw: Record<string, unknown>;
+}
+/** The lightweight head pointer for change detection. */
+interface Head {
+    /** Opaque cursor string for change detection. */
+    cursor: string;
+    /** Content hash of the latest feed. */
+    hash: string;
+    /** Whether content has changed since last generation. */
+    changed: boolean;
+    /** When this head was generated. */
+    generatedAt: string;
+    /** Recommended polling interval in seconds. */
+    ttlSec: number;
+}
+/** A full DiffDelta feed response. */
+interface Feed {
+    /** The new cursor (save this for next poll). */
+    cursor: string;
+    /** The previous cursor. */
+    prevCursor: string;
+    /** Source ID (if per-source feed) or "global". */
+    sourceId: string;
+    /** When this feed was generated. */
+    generatedAt: string;
+    /** All items across all buckets. */
+    items: FeedItem[];
+    /** Items in the "new" bucket. */
+    new: FeedItem[];
+    /** Items in the "updated" bucket. */
+    updated: FeedItem[];
+    /** Items in the "removed" bucket. */
+    removed: FeedItem[];
+    /** Human-readable summary of what changed. */
+    narrative: string;
+    /** The full raw feed object. */
+    raw: Record<string, unknown>;
+}
+/** Metadata about an available DiffDelta source. */
+interface SourceInfo {
+    /** Unique source identifier (e.g. "cisa_kev"). */
+    sourceId: string;
+    /** Human-readable display name. */
+    name: string;
+    /** List of tags (e.g. ["security"]). */
+    tags: string[];
+    /** Brief description of the source. */
+    description: string;
+    /** URL of the source's homepage. */
+    homepage: string;
+    /** Whether the source is currently active. */
+    enabled: boolean;
+    /** Health status ("ok", "degraded", "error"). */
+    status: string;
+    /** Path to the source's head.json. */
+    headUrl: string;
+    /** Path to the source's latest.json. */
+    latestUrl: string;
+}
+
+/**
+ * DiffDelta TypeScript client — agent-ready intelligence feeds.
+ *
+ * @example
+ * ```ts
+ * import { DiffDelta } from "diffdelta";
+ *
+ * const dd = new DiffDelta();
+ *
+ * // Poll for new items across all sources
+ * const items = await dd.poll();
+ * items.forEach(i => console.log(`${i.source}: ${i.headline}`));
+ *
+ * // Poll only security sources
+ * const sec = await dd.poll({ tags: ["security"] });
+ *
+ * // Continuous monitoring
+ * dd.watch(item => console.log("🚨", item.headline), { tags: ["security"] });
+ * ```
+ */
+
+interface DiffDeltaOptions {
+    /** DiffDelta API base URL. Defaults to https://diffdelta.io. */
+    baseUrl?: string;
+    /** Pro/Enterprise API key (dd_live_...). */
+    apiKey?: string;
+    /**
+     * Path to cursor file. Defaults to ~/.diffdelta/cursors.json.
+     * Set to `null` to disable file persistence (in-memory only).
+     * Set to `"memory"` for explicit in-memory mode (serverless, edge).
+     */
+    cursorPath?: string | null;
+    /** HTTP timeout in milliseconds. Defaults to 15000. */
+    timeout?: number;
+}
+interface PollOptions {
+    /** Filter items to these tags (e.g. ["security"]). */
+    tags?: string[];
+    /** Filter items to these source IDs (e.g. ["cisa_kev", "nist_nvd"]). */
+    sources?: string[];
+    /**
+     * Which buckets to return.
+     * Defaults to ["new", "updated"].
+     * Use ["new", "updated", "removed"] to include removals.
+     */
+    buckets?: Array<"new" | "updated" | "removed">;
+}
+interface WatchOptions extends PollOptions {
+    /** Seconds between polls. Defaults to feed TTL (usually 900s). */
+    interval?: number;
+    /** If provided, an AbortSignal to stop watching. */
+    signal?: AbortSignal;
+}
+declare class DiffDelta {
+    readonly baseUrl: string;
+    readonly apiKey?: string;
+    readonly timeout: number;
+    private cursors;
+    private sourceTagsCache;
+    constructor(options?: DiffDeltaOptions);
+    /**
+     * Poll the global feed for new items since last poll.
+     *
+     * Checks head.json first (~400 bytes). Only fetches the full feed
+     * if the cursor has changed. Automatically saves the new cursor.
+     */
+    poll(options?: PollOptions): Promise<FeedItem[]>;
+    /**
+     * Poll a specific source for new items since last poll.
+     *
+     * More efficient than `poll({ sources: [...] })` if you only
+     * care about one source — fetches a smaller payload.
+     */
+    pollSource(sourceId: string, options?: Omit<PollOptions, "sources">): Promise<FeedItem[]>;
+    /**
+     * Fetch a head.json pointer.
+     * @param url Full URL to head.json. Defaults to global head.
+     */
+    head(url?: string): Promise<Head>;
+    /**
+     * Fetch a full latest.json feed.
+     * @param url Full URL to latest.json. Defaults to global latest.
+     */
+    fetchFeed(url?: string): Promise<Feed>;
+    /** List all available DiffDelta sources. */
+    sources(): Promise<SourceInfo[]>;
+    /**
+     * Continuously poll and call a function for each new item.
+     *
+     * @param callback - Async or sync function called for each new FeedItem.
+     * @param options - Watch options (tags, sources, interval, signal).
+     *
+     * @example
+     * ```ts
+     * dd.watch(item => {
+     *   console.log(`🚨 ${item.source}: ${item.headline}`);
+     * }, { tags: ["security"] });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Stop with AbortController
+     * const ac = new AbortController();
+     * dd.watch(handler, { signal: ac.signal });
+     * setTimeout(() => ac.abort(), 60_000); // stop after 1 minute
+     * ```
+     */
+    watch(callback: (item: FeedItem) => void | Promise<void>, options?: WatchOptions): Promise<void>;
+    /** Reset stored cursors so the next poll returns all current items. */
+    resetCursors(sourceId?: string): void;
+    private pollFeed;
+    private getSourceTags;
+    private fetchJson;
+    toString(): string;
+}
+
+/**
+ * Persists cursors to a local JSON file so bots survive restarts.
+ *
+ * By default, cursors are saved to ~/.diffdelta/cursors.json.
+ * Each feed key gets its own cursor entry.
+ */
+declare class CursorStore {
+    private path;
+    private cursors;
+    constructor(path?: string);
+    /** Get the stored cursor for a feed key. */
+    get(key: string): string | undefined;
+    /** Save a cursor and persist to disk. */
+    set(key: string, cursor: string): void;
+    /** Clear cursor(s). If key is undefined, clears all cursors. */
+    clear(key?: string): void;
+    private load;
+    private save;
+}
+/**
+ * In-memory-only cursor store (no file I/O).
+ * Useful for serverless, browser, or Deno environments.
+ */
+declare class MemoryCursorStore {
+    private cursors;
+    get(key: string): string | undefined;
+    set(key: string, cursor: string): void;
+    clear(key?: string): void;
+}
+
+export { CursorStore, DiffDelta, type DiffDeltaOptions, type Feed, type FeedItem, type Head, MemoryCursorStore, type PollOptions, type SourceInfo, type WatchOptions };