@ncukondo/search-hub 0.1.0

package/dist/providers/arxiv/types.d.ts

@@ -0,0 +1,71 @@
+import { Article } from '../base/types.js';
+import { BaseProviderConfig } from '../base/provider.js';
+/**
+ * arXiv category taxonomy.
+ * Format: archive.subject (e.g., cs.AI, physics.gen-ph)
+ */
+export type ArxivCategory = string;
+/**
+ * Version information for an arXiv paper.
+ */
+export interface ArxivVersion {
+    version: string;
+    submitted: string;
+}
+/**
+ * arXiv paper extending the base Article type.
+ * Includes arXiv-specific fields like categories and versions.
+ */
+export interface ArxivPaper extends Article {
+    /** arXiv identifier (e.g., 2401.12345) - required for arXiv papers */
+    arxivId: string;
+    /** arXiv source identifier */
+    source: 'arxiv';
+    /** List of arXiv categories */
+    categories: ArxivCategory[];
+    /** Primary arXiv category */
+    primaryCategory: ArxivCategory;
+    /** Version history (optional) */
+    versions?: ArxivVersion[];
+}
+/**
+ * Response from arXiv API search.
+ * Parsed from Atom XML feed.
+ */
+export interface ArxivSearchResponse {
+    /** Total number of results matching the query */
+    totalResults: number;
+    /** Starting index of current page (0-based) */
+    startIndex: number;
+    /** Number of items per page */
+    itemsPerPage: number;
+    /** List of papers in current page */
+    entries: ArxivPaper[];
+}
+/**
+ * Configuration for arXiv provider.
+ */
+export interface ArxivConfig extends BaseProviderConfig {
+    /** arXiv API base URL */
+    baseUrl?: string;
+    /** Maximum results to fetch (arXiv recommends max 2000 per request) */
+    maxResults?: number;
+}
+/**
+ * arXiv API requires a minimum of 3 seconds between requests.
+ * See: https://info.arxiv.org/help/api/user-manual.html#paging
+ */
+export declare const ARXIV_MIN_REQUEST_INTERVAL_MS = 3000;
+/**
+ * Default arXiv configuration values.
+ */
+export declare const DEFAULT_ARXIV_CONFIG: Required<ArxivConfig>;
+/**
+ * Provider-specific state for session resume.
+ * arXiv uses offset-based pagination, so we only need to track the offset.
+ */
+export interface ArxivProviderState {
+    /** Current pagination offset (0-based) */
+    offset: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/arxiv/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/providers/arxiv/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAEhB,8BAA8B;IAC9B,MAAM,EAAE,OAAO,CAAC;IAEhB,+BAA+B;IAC/B,UAAU,EAAE,aAAa,EAAE,CAAC;IAE5B,6BAA6B;IAC7B,eAAe,EAAE,aAAa,CAAC;IAE/B,iCAAiC;IACjC,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IAErB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IAEnB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,qCAAqC;IACrC,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,kBAAkB;IACrD,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAStD,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/providers/arxiv/types.js

@@ -0,0 +1,17 @@
+const ARXIV_MIN_REQUEST_INTERVAL_MS = 3e3;
+const DEFAULT_ARXIV_CONFIG = {
+  baseUrl: "https://export.arxiv.org/api/query",
+  // Convert interval to requests per second: 1000ms / 3000ms = 0.33 req/s
+  rateLimit: 1e3 / ARXIV_MIN_REQUEST_INTERVAL_MS,
+  timeout: 6e4,
+  // arXiv can be slow
+  retries: 3,
+  maxResults: 1e4,
+  initialBackoff: 1e3,
+  maxBackoff: 3e4
+};
+export {
+  ARXIV_MIN_REQUEST_INTERVAL_MS,
+  DEFAULT_ARXIV_CONFIG
+};
+//# sourceMappingURL=types.js.map

package/dist/providers/arxiv/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":["../../../src/providers/arxiv/types.ts"],"sourcesContent":["/**\n * arXiv Provider Types\n *\n * Types for interacting with the arXiv API.\n * arXiv hosts preprints in physics, mathematics, computer science,\n * quantitative biology, and related fields.\n */\n\nimport type { Article } from '../base/types.js';\nimport type { BaseProviderConfig } from '../base/provider.js';\n\n/**\n * arXiv category taxonomy.\n * Format: archive.subject (e.g., cs.AI, physics.gen-ph)\n */\nexport type ArxivCategory = string;\n\n/**\n * Version information for an arXiv paper.\n */\nexport interface ArxivVersion {\n  version: string;\n  submitted: string;\n}\n\n/**\n * arXiv paper extending the base Article type.\n * Includes arXiv-specific fields like categories and versions.\n */\nexport interface ArxivPaper extends Article {\n  /** arXiv identifier (e.g., 2401.12345) - required for arXiv papers */\n  arxivId: string;\n\n  /** arXiv source identifier */\n  source: 'arxiv';\n\n  /** List of arXiv categories */\n  categories: ArxivCategory[];\n\n  /** Primary arXiv category */\n  primaryCategory: ArxivCategory;\n\n  /** Version history (optional) */\n  versions?: ArxivVersion[];\n}\n\n/**\n * Response from arXiv API search.\n * Parsed from Atom XML feed.\n */\nexport interface ArxivSearchResponse {\n  /** Total number of results matching the query */\n  totalResults: number;\n\n  /** Starting index of current page (0-based) */\n  startIndex: number;\n\n  /** Number of items per page */\n  itemsPerPage: number;\n\n  /** List of papers in current page */\n  entries: ArxivPaper[];\n}\n\n/**\n * Configuration for arXiv provider.\n */\nexport interface ArxivConfig extends BaseProviderConfig {\n  /** arXiv API base URL */\n  baseUrl?: string;\n\n  /** Maximum results to fetch (arXiv recommends max 2000 per request) */\n  maxResults?: number;\n}\n\n/**\n * arXiv API requires a minimum of 3 seconds between requests.\n * See: https://info.arxiv.org/help/api/user-manual.html#paging\n */\nexport const ARXIV_MIN_REQUEST_INTERVAL_MS = 3000;\n\n/**\n * Default arXiv configuration values.\n */\nexport const DEFAULT_ARXIV_CONFIG: Required<ArxivConfig> = {\n  baseUrl: 'https://export.arxiv.org/api/query',\n  // Convert interval to requests per second: 1000ms / 3000ms = 0.33 req/s\n  rateLimit: 1000 / ARXIV_MIN_REQUEST_INTERVAL_MS,\n  timeout: 60000, // arXiv can be slow\n  retries: 3,\n  maxResults: 10000,\n  initialBackoff: 1000,\n  maxBackoff: 30000,\n};\n\n/**\n * Provider-specific state for session resume.\n * arXiv uses offset-based pagination, so we only need to track the offset.\n */\nexport interface ArxivProviderState {\n  /** Current pagination offset (0-based) */\n  offset: number;\n}\n"],"names":[],"mappings":"AA+EO,MAAM,gCAAgC;AAKtC,MAAM,uBAA8C;AAAA,EACzD,SAAS;AAAA;AAAA,EAET,WAAW,MAAO;AAAA,EAClB,SAAS;AAAA;AAAA,EACT,SAAS;AAAA,EACT,YAAY;AAAA,EACZ,gBAAgB;AAAA,EAChB,YAAY;AACd;"}

package/dist/providers/base/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Provider base module.
+ *
+ * Provides the foundation for implementing database providers.
+ */
+export type { ProviderName, Author, Article, TranslatedQuery, SearchOptions, Provider, ProviderError, RateLimitError, AuthError, QueryAST, ProviderErrorCode, SearchState, SearchResumeResult, } from './types';
+export { createProviderError, isProviderError, isRateLimitError, isAuthError, } from './types';
+export { BaseProvider, serializeState, deserializeState } from './provider';
+export type { BaseProviderConfig } from './provider';
+export { RateLimiter } from './rate-limiter';
+export type { RateLimiterOptions } from './rate-limiter';
+export { ProviderRegistry, createProviderRegistry, globalRegistry } from './registry';
+export type { ProviderFactory } from './registry';
+export { MockProvider } from './mock-provider';
+export type { MockProviderOptions } from './mock-provider';
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/base/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/base/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EACV,YAAY,EACZ,MAAM,EACN,OAAO,EACP,eAAe,EACf,aAAa,EACb,QAAQ,EACR,aAAa,EACb,cAAc,EACd,SAAS,EACT,QAAQ,EACR,iBAAiB,EACjB,WAAW,EACX,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,WAAW,GACZ,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGzD,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACtF,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/providers/base/mock-provider.d.ts

@@ -0,0 +1,76 @@
+import { BaseProvider, BaseProviderConfig } from './provider';
+import { ProviderName, Article, TranslatedQuery, SearchOptions, QueryAST, ProviderError, SearchState, SearchResumeResult } from './types';
+/**
+ * Configuration options for MockProvider.
+ */
+export interface MockProviderOptions extends BaseProviderConfig {
+    /** Provider name to use */
+    name?: ProviderName;
+    /** Articles to return from search */
+    articles?: Article[];
+    /** Pre-configured translated query response */
+    translatedQuery?: TranslatedQuery;
+    /** Connection status to return from testConnection */
+    connectionStatus?: boolean;
+    /** Delay in ms before returning search results */
+    searchDelay?: number;
+    /** Error to throw on search */
+    searchError?: ProviderError;
+    /** State validation result to return */
+    stateValidation?: SearchResumeResult;
+}
+/**
+ * Mock provider for testing.
+ *
+ * Allows configuring:
+ * - Articles to return from search
+ * - Translated query response
+ * - Connection status
+ * - Search delay (for simulating network latency)
+ * - Search errors (for testing error handling)
+ */
+export declare class MockProvider extends BaseProvider {
+    readonly name: ProviderName;
+    private mockArticles;
+    private translatedQueryResponse;
+    private connectionStatus;
+    private searchDelay;
+    private searchError;
+    private currentSearchState;
+    private stateValidationResult;
+    private currentRetrievedCount;
+    constructor(options?: MockProviderOptions);
+    search(_query: TranslatedQuery, options?: SearchOptions): AsyncIterable<Article>;
+    translateQuery(ast: QueryAST): TranslatedQuery;
+    testConnection(): Promise<boolean>;
+    /**
+     * Update the articles to return.
+     */
+    setArticles(articles: Article[]): void;
+    /**
+     * Set the error to throw on search.
+     */
+    setSearchError(error: ProviderError | null): void;
+    /**
+     * Set the connection status.
+     */
+    setConnectionStatus(status: boolean): void;
+    /**
+     * Get current search state for session persistence.
+     */
+    getSearchState(): SearchState | null;
+    /**
+     * Resume search from saved state.
+     */
+    resumeSearch(state: SearchState): AsyncIterable<Article>;
+    /**
+     * Validate if state is still valid for resuming.
+     */
+    validateState(_state: SearchState): Promise<SearchResumeResult>;
+    /**
+     * Set the state validation result.
+     */
+    setStateValidation(result: SearchResumeResult): void;
+    private delay;
+}
+//# sourceMappingURL=mock-provider.d.ts.map

package/dist/providers/base/mock-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-provider.d.ts","sourceRoot":"","sources":["../../../src/providers/base/mock-provider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EACV,YAAY,EACZ,OAAO,EACP,eAAe,EACf,aAAa,EACb,QAAQ,EACR,aAAa,EACb,WAAW,EACX,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,2BAA2B;IAC3B,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,wCAAwC;IACxC,eAAe,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAwBD;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,OAAO,CAAC,YAAY,CAAY;IAChC,OAAO,CAAC,uBAAuB,CAAkB;IACjD,OAAO,CAAC,gBAAgB,CAAU;IAClC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,kBAAkB,CAA4B;IACtD,OAAO,CAAC,qBAAqB,CAAqB;IAClD,OAAO,CAAC,qBAAqB,CAAK;gBAEtB,OAAO,GAAE,mBAAwB;IA2BtC,MAAM,CACX,MAAM,EAAE,eAAe,EACvB,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAAC,OAAO,CAAC;IA8BzB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,eAAe;IAOxC,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxC;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI;IAOtC;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI;IAIjD;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAI1C;;OAEG;IACH,cAAc,IAAI,WAAW,GAAG,IAAI;IAIpC;;OAEG;IACI,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC;IAsC/D;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIrE;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAIpD,OAAO,CAAC,KAAK;CAGd"}

package/dist/providers/base/mock-provider.js

@@ -0,0 +1,159 @@
+import { BaseProvider } from "./provider.js";
+const DEFAULT_ARTICLES = [
+  {
+    doi: "10.1234/mock-article-1",
+    title: "Mock Article 1",
+    authors: [{ family: "Mock", given: "Author" }],
+    source: "pubmed",
+    retrievedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    abstract: "This is a mock article for testing purposes."
+  },
+  {
+    doi: "10.1234/mock-article-2",
+    title: "Mock Article 2",
+    authors: [{ family: "Test", given: "Researcher" }],
+    source: "pubmed",
+    retrievedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    abstract: "Another mock article for testing."
+  }
+];
+class MockProvider extends BaseProvider {
+  name;
+  mockArticles;
+  translatedQueryResponse;
+  connectionStatus;
+  searchDelay;
+  searchError;
+  currentSearchState = null;
+  stateValidationResult;
+  currentRetrievedCount = 0;
+  constructor(options = {}) {
+    super(options);
+    this.name = options.name ?? "pubmed";
+    this.mockArticles = options.articles ?? [...DEFAULT_ARTICLES];
+    this.translatedQueryResponse = options.translatedQuery ?? {
+      native: "mock query",
+      originalAst: {
+        name: "mock-query",
+        blocks: [],
+        filters: {},
+        overrides: {}
+      },
+      provider: this.name
+    };
+    this.connectionStatus = options.connectionStatus ?? true;
+    this.searchDelay = options.searchDelay ?? 0;
+    this.searchError = options.searchError ?? null;
+    this.stateValidationResult = options.stateValidation ?? { valid: true };
+    this.mockArticles = this.mockArticles.map((article) => ({
+      ...article,
+      source: this.name
+    }));
+  }
+  async *search(_query, options) {
+    if (this.searchError !== null) {
+      throw this.searchError;
+    }
+    if (this.searchDelay > 0) {
+      await this.delay(this.searchDelay);
+    }
+    const maxResults = options?.maxResults ?? this.mockArticles.length;
+    let count = 0;
+    for (const article of this.mockArticles) {
+      if (count >= maxResults) {
+        break;
+      }
+      if (options?.signal?.aborted) {
+        break;
+      }
+      yield article;
+      count++;
+    }
+  }
+  translateQuery(ast) {
+    return {
+      ...this.translatedQueryResponse,
+      originalAst: ast
+    };
+  }
+  async testConnection() {
+    return this.connectionStatus;
+  }
+  /**
+   * Update the articles to return.
+   */
+  setArticles(articles) {
+    this.mockArticles = articles.map((article) => ({
+      ...article,
+      source: this.name
+    }));
+  }
+  /**
+   * Set the error to throw on search.
+   */
+  setSearchError(error) {
+    this.searchError = error;
+  }
+  /**
+   * Set the connection status.
+   */
+  setConnectionStatus(status) {
+    this.connectionStatus = status;
+  }
+  /**
+   * Get current search state for session persistence.
+   */
+  getSearchState() {
+    return this.currentSearchState;
+  }
+  /**
+   * Resume search from saved state.
+   */
+  async *resumeSearch(state) {
+    const providerState = state.providerState;
+    const offset = providerState?.offset ?? state.retrievedCount;
+    if (this.searchError !== null) {
+      throw this.searchError;
+    }
+    if (this.searchDelay > 0) {
+      await this.delay(this.searchDelay);
+    }
+    this.currentSearchState = {
+      ...state,
+      lastUpdated: /* @__PURE__ */ new Date()
+    };
+    this.currentRetrievedCount = offset;
+    for (let i = offset; i < this.mockArticles.length; i++) {
+      const article = this.mockArticles[i];
+      if (article) {
+        this.currentRetrievedCount++;
+        this.currentSearchState = {
+          ...this.currentSearchState,
+          retrievedCount: this.currentRetrievedCount,
+          lastUpdated: /* @__PURE__ */ new Date(),
+          providerState: { offset: this.currentRetrievedCount }
+        };
+        yield article;
+      }
+    }
+  }
+  /**
+   * Validate if state is still valid for resuming.
+   */
+  async validateState(_state) {
+    return this.stateValidationResult;
+  }
+  /**
+   * Set the state validation result.
+   */
+  setStateValidation(result) {
+    this.stateValidationResult = result;
+  }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+export {
+  MockProvider
+};
+//# sourceMappingURL=mock-provider.js.map

package/dist/providers/base/mock-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-provider.js","sources":["../../../src/providers/base/mock-provider.ts"],"sourcesContent":["/**\n * Mock provider for testing.\n *\n * Provides configurable responses for testing search orchestration\n * and other components that depend on providers.\n */\n\nimport { BaseProvider } from './provider';\nimport type { BaseProviderConfig } from './provider';\nimport type {\n  ProviderName,\n  Article,\n  TranslatedQuery,\n  SearchOptions,\n  QueryAST,\n  ProviderError,\n  SearchState,\n  SearchResumeResult,\n} from './types';\n\n/**\n * Configuration options for MockProvider.\n */\nexport interface MockProviderOptions extends BaseProviderConfig {\n  /** Provider name to use */\n  name?: ProviderName;\n  /** Articles to return from search */\n  articles?: Article[];\n  /** Pre-configured translated query response */\n  translatedQuery?: TranslatedQuery;\n  /** Connection status to return from testConnection */\n  connectionStatus?: boolean;\n  /** Delay in ms before returning search results */\n  searchDelay?: number;\n  /** Error to throw on search */\n  searchError?: ProviderError;\n  /** State validation result to return */\n  stateValidation?: SearchResumeResult;\n}\n\n/**\n * Default mock articles.\n */\nconst DEFAULT_ARTICLES: Article[] = [\n  {\n    doi: '10.1234/mock-article-1',\n    title: 'Mock Article 1',\n    authors: [{ family: 'Mock', given: 'Author' }],\n    source: 'pubmed',\n    retrievedAt: new Date().toISOString(),\n    abstract: 'This is a mock article for testing purposes.',\n  },\n  {\n    doi: '10.1234/mock-article-2',\n    title: 'Mock Article 2',\n    authors: [{ family: 'Test', given: 'Researcher' }],\n    source: 'pubmed',\n    retrievedAt: new Date().toISOString(),\n    abstract: 'Another mock article for testing.',\n  },\n];\n\n/**\n * Mock provider for testing.\n *\n * Allows configuring:\n * - Articles to return from search\n * - Translated query response\n * - Connection status\n * - Search delay (for simulating network latency)\n * - Search errors (for testing error handling)\n */\nexport class MockProvider extends BaseProvider {\n  readonly name: ProviderName;\n  private mockArticles: Article[];\n  private translatedQueryResponse: TranslatedQuery;\n  private connectionStatus: boolean;\n  private searchDelay: number;\n  private searchError: ProviderError | null;\n  private currentSearchState: SearchState | null = null;\n  private stateValidationResult: SearchResumeResult;\n  private currentRetrievedCount = 0;\n\n  constructor(options: MockProviderOptions = {}) {\n    super(options);\n\n    this.name = options.name ?? 'pubmed';\n    this.mockArticles = options.articles ?? [...DEFAULT_ARTICLES];\n    this.translatedQueryResponse = options.translatedQuery ?? {\n      native: 'mock query',\n      originalAst: {\n        name: 'mock-query',\n        blocks: [],\n        filters: {},\n        overrides: {},\n      },\n      provider: this.name,\n    };\n    this.connectionStatus = options.connectionStatus ?? true;\n    this.searchDelay = options.searchDelay ?? 0;\n    this.searchError = options.searchError ?? null;\n    this.stateValidationResult = options.stateValidation ?? { valid: true };\n\n    // Update articles source to match provider name\n    this.mockArticles = this.mockArticles.map((article) => ({\n      ...article,\n      source: this.name,\n    }));\n  }\n\n  async *search(\n    _query: TranslatedQuery,\n    options?: SearchOptions\n  ): AsyncIterable<Article> {\n    // Throw configured error if set\n    if (this.searchError !== null) {\n      throw this.searchError;\n    }\n\n    // Simulate network delay\n    if (this.searchDelay > 0) {\n      await this.delay(this.searchDelay);\n    }\n\n    // Determine how many articles to yield\n    const maxResults = options?.maxResults ?? this.mockArticles.length;\n    let count = 0;\n\n    for (const article of this.mockArticles) {\n      if (count >= maxResults) {\n        break;\n      }\n\n      // Check for abort signal\n      if (options?.signal?.aborted) {\n        break;\n      }\n\n      yield article;\n      count++;\n    }\n  }\n\n  translateQuery(ast: QueryAST): TranslatedQuery {\n    return {\n      ...this.translatedQueryResponse,\n      originalAst: ast,\n    };\n  }\n\n  async testConnection(): Promise<boolean> {\n    return this.connectionStatus;\n  }\n\n  /**\n   * Update the articles to return.\n   */\n  setArticles(articles: Article[]): void {\n    this.mockArticles = articles.map((article) => ({\n      ...article,\n      source: this.name,\n    }));\n  }\n\n  /**\n   * Set the error to throw on search.\n   */\n  setSearchError(error: ProviderError | null): void {\n    this.searchError = error;\n  }\n\n  /**\n   * Set the connection status.\n   */\n  setConnectionStatus(status: boolean): void {\n    this.connectionStatus = status;\n  }\n\n  /**\n   * Get current search state for session persistence.\n   */\n  getSearchState(): SearchState | null {\n    return this.currentSearchState;\n  }\n\n  /**\n   * Resume search from saved state.\n   */\n  async *resumeSearch(state: SearchState): AsyncIterable<Article> {\n    // Extract offset from provider state\n    const providerState = state.providerState as { offset?: number } | undefined;\n    const offset = providerState?.offset ?? state.retrievedCount;\n\n    // Throw configured error if set\n    if (this.searchError !== null) {\n      throw this.searchError;\n    }\n\n    // Simulate network delay\n    if (this.searchDelay > 0) {\n      await this.delay(this.searchDelay);\n    }\n\n    // Update current state\n    this.currentSearchState = {\n      ...state,\n      lastUpdated: new Date(),\n    };\n    this.currentRetrievedCount = offset;\n\n    // Yield remaining articles starting from offset\n    for (let i = offset; i < this.mockArticles.length; i++) {\n      const article = this.mockArticles[i];\n      if (article) {\n        this.currentRetrievedCount++;\n        this.currentSearchState = {\n          ...this.currentSearchState,\n          retrievedCount: this.currentRetrievedCount,\n          lastUpdated: new Date(),\n          providerState: { offset: this.currentRetrievedCount },\n        };\n        yield article;\n      }\n    }\n  }\n\n  /**\n   * Validate if state is still valid for resuming.\n   */\n  async validateState(_state: SearchState): Promise<SearchResumeResult> {\n    return this.stateValidationResult;\n  }\n\n  /**\n   * Set the state validation result.\n   */\n  setStateValidation(result: SearchResumeResult): void {\n    this.stateValidationResult = result;\n  }\n\n  private delay(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/providers/base/provider.d.ts

@@ -0,0 +1,95 @@
+import { RateLimiter } from './rate-limiter';
+import { Provider, ProviderName, Article, TranslatedQuery, SearchOptions, QueryAST, SearchState, SearchResumeResult } from './types';
+/**
+ * Configuration options for BaseProvider.
+ */
+export interface BaseProviderConfig {
+    /** Requests per second rate limit */
+    rateLimit?: number;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Number of retry attempts */
+    retries?: number;
+    /** Initial backoff time in ms for exponential backoff */
+    initialBackoff?: number;
+    /** Maximum backoff time in ms */
+    maxBackoff?: number;
+}
+/**
+ * Abstract base class for database providers.
+ *
+ * Provides common infrastructure:
+ * - Rate limiting
+ * - Configuration management
+ * - Retry logic (implemented in subclass)
+ */
+export declare abstract class BaseProvider implements Provider {
+    /** Provider name identifier */
+    abstract readonly name: ProviderName;
+    /** Rate limiter instance */
+    protected readonly rateLimiter: RateLimiter;
+    /** Merged configuration */
+    protected readonly config: Required<BaseProviderConfig>;
+    constructor(config?: BaseProviderConfig);
+    /**
+     * Execute search and return results as async iterable (streaming).
+     */
+    abstract search(query: TranslatedQuery, options?: SearchOptions): AsyncIterable<Article>;
+    /**
+     * Convert QueryAST to database-native syntax.
+     */
+    abstract translateQuery(ast: QueryAST): TranslatedQuery;
+    /**
+     * Verify API access and credentials.
+     * Returns false on failure (doesn't throw).
+     */
+    abstract testConnection(): Promise<boolean>;
+    /**
+     * Get the current search state for session persistence.
+     * Returns null if no search is in progress.
+     */
+    abstract getSearchState(): SearchState | null;
+    /**
+     * Resume a search from a saved state.
+     * Continues yielding articles from where the previous search left off.
+     */
+    abstract resumeSearch(state: SearchState): AsyncIterable<Article>;
+    /**
+     * Validate if a saved state is still valid for resuming.
+     * Some providers (e.g., PubMed) have server-side state that can expire.
+     */
+    abstract validateState(state: SearchState): Promise<SearchResumeResult>;
+    /**
+     * Create a base SearchState with common fields.
+     * Subclasses can extend this with provider-specific state.
+     */
+    protected createBaseState(query: TranslatedQuery, totalResults: number, retrievedCount: number): SearchState;
+    /**
+     * Execute a function with retry logic.
+     *
+     * Retries on network errors and server errors.
+     * Does not retry on auth errors.
+     * Uses exponential backoff between retries.
+     * Respects rate limit error's retryAfter if provided.
+     */
+    protected withRetry<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Determine if an error should trigger a retry.
+     */
+    private shouldRetry;
+    /**
+     * Sleep for specified milliseconds.
+     */
+    private sleep;
+}
+/**
+ * Serialize a SearchState to a JSON string.
+ * Handles Date conversion to ISO 8601 string.
+ */
+export declare function serializeState(state: SearchState): string;
+/**
+ * Deserialize a JSON string to a SearchState.
+ * Handles Date conversion from ISO 8601 string.
+ */
+export declare function deserializeState(json: string): SearchState;
+//# sourceMappingURL=provider.d.ts.map

package/dist/providers/base/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/providers/base/provider.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,eAAe,EACf,aAAa,EACb,QAAQ,EAER,WAAW,EACX,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAGjB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAUD;;;;;;;GAOG;AACH,8BAAsB,YAAa,YAAW,QAAQ;IACpD,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAErC,4BAA4B;IAC5B,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAE5C,2BAA2B;IAC3B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;gBAE5C,MAAM,GAAE,kBAAuB;IAc3C;;OAEG;IACH,QAAQ,CAAC,MAAM,CACb,KAAK,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,aAAa,GACtB,aAAa,CAAC,OAAO,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,eAAe;IAEvD;;;OAGG;IACH,QAAQ,CAAC,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,cAAc,IAAI,WAAW,GAAG,IAAI;IAE7C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC;IAEjE;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAEvE;;;OAGG;IACH,SAAS,CAAC,eAAe,CACvB,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GACrB,WAAW;IAUd;;;;;;;OAOG;cACa,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAqC9D;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd;AAcD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAUzD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAU1D"}

package/dist/providers/base/provider.js

@@ -0,0 +1,117 @@
+import { RateLimiter } from "./rate-limiter.js";
+import { isRateLimitError, isProviderError } from "./types.js";
+const DEFAULT_CONFIG = {
+  rateLimit: 3,
+  timeout: 3e4,
+  retries: 3,
+  initialBackoff: 1e3,
+  maxBackoff: 6e4
+};
+class BaseProvider {
+  /** Rate limiter instance */
+  rateLimiter;
+  /** Merged configuration */
+  config;
+  constructor(config = {}) {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config
+    };
+    this.rateLimiter = new RateLimiter({
+      tokensPerSecond: this.config.rateLimit,
+      burstSize: this.config.rateLimit,
+      initialBackoff: this.config.initialBackoff,
+      maxBackoff: this.config.maxBackoff
+    });
+  }
+  /**
+   * Create a base SearchState with common fields.
+   * Subclasses can extend this with provider-specific state.
+   */
+  createBaseState(query, totalResults, retrievedCount) {
+    return {
+      provider: this.name,
+      query,
+      totalResults,
+      retrievedCount,
+      lastUpdated: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * Execute a function with retry logic.
+   *
+   * Retries on network errors and server errors.
+   * Does not retry on auth errors.
+   * Uses exponential backoff between retries.
+   * Respects rate limit error's retryAfter if provided.
+   */
+  async withRetry(fn) {
+    let lastError;
+    let currentBackoff = this.config.initialBackoff;
+    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        if (!this.shouldRetry(error)) {
+          throw error;
+        }
+        if (attempt >= this.config.retries) {
+          throw error;
+        }
+        let waitTime;
+        if (isRateLimitError(error) && "retryAfter" in error && typeof error.retryAfter === "number") {
+          waitTime = error.retryAfter;
+        } else {
+          waitTime = currentBackoff;
+          currentBackoff = Math.min(currentBackoff * 2, this.config.maxBackoff);
+        }
+        await this.sleep(waitTime);
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Determine if an error should trigger a retry.
+   */
+  shouldRetry(error) {
+    if (isProviderError(error)) {
+      return error.retryable;
+    }
+    return false;
+  }
+  /**
+   * Sleep for specified milliseconds.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+function serializeState(state) {
+  const serialized = {
+    provider: state.provider,
+    query: state.query,
+    totalResults: state.totalResults,
+    retrievedCount: state.retrievedCount,
+    lastUpdated: state.lastUpdated.toISOString(),
+    providerState: state.providerState
+  };
+  return JSON.stringify(serialized);
+}
+function deserializeState(json) {
+  const parsed = JSON.parse(json);
+  return {
+    provider: parsed.provider,
+    query: parsed.query,
+    totalResults: parsed.totalResults,
+    retrievedCount: parsed.retrievedCount,
+    lastUpdated: new Date(parsed.lastUpdated),
+    providerState: parsed.providerState
+  };
+}
+export {
+  BaseProvider,
+  deserializeState,
+  serializeState
+};
+//# sourceMappingURL=provider.js.map

package/dist/providers/base/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sources":["../../../src/providers/base/provider.ts"],"sourcesContent":["/**\n * Abstract base class for database providers.\n */\n\nimport { RateLimiter } from './rate-limiter';\nimport type {\n  Provider,\n  ProviderName,\n  Article,\n  TranslatedQuery,\n  SearchOptions,\n  QueryAST,\n  ProviderError,\n  SearchState,\n  SearchResumeResult,\n} from './types';\nimport { isProviderError, isRateLimitError } from './types';\n\n/**\n * Configuration options for BaseProvider.\n */\nexport interface BaseProviderConfig {\n  /** Requests per second rate limit */\n  rateLimit?: number;\n  /** Request timeout in milliseconds */\n  timeout?: number;\n  /** Number of retry attempts */\n  retries?: number;\n  /** Initial backoff time in ms for exponential backoff */\n  initialBackoff?: number;\n  /** Maximum backoff time in ms */\n  maxBackoff?: number;\n}\n\nconst DEFAULT_CONFIG: Required<BaseProviderConfig> = {\n  rateLimit: 3,\n  timeout: 30000,\n  retries: 3,\n  initialBackoff: 1000,\n  maxBackoff: 60000,\n};\n\n/**\n * Abstract base class for database providers.\n *\n * Provides common infrastructure:\n * - Rate limiting\n * - Configuration management\n * - Retry logic (implemented in subclass)\n */\nexport abstract class BaseProvider implements Provider {\n  /** Provider name identifier */\n  abstract readonly name: ProviderName;\n\n  /** Rate limiter instance */\n  protected readonly rateLimiter: RateLimiter;\n\n  /** Merged configuration */\n  protected readonly config: Required<BaseProviderConfig>;\n\n  constructor(config: BaseProviderConfig = {}) {\n    this.config = {\n      ...DEFAULT_CONFIG,\n      ...config,\n    };\n\n    this.rateLimiter = new RateLimiter({\n      tokensPerSecond: this.config.rateLimit,\n      burstSize: this.config.rateLimit,\n      initialBackoff: this.config.initialBackoff,\n      maxBackoff: this.config.maxBackoff,\n    });\n  }\n\n  /**\n   * Execute search and return results as async iterable (streaming).\n   */\n  abstract search(\n    query: TranslatedQuery,\n    options?: SearchOptions\n  ): AsyncIterable<Article>;\n\n  /**\n   * Convert QueryAST to database-native syntax.\n   */\n  abstract translateQuery(ast: QueryAST): TranslatedQuery;\n\n  /**\n   * Verify API access and credentials.\n   * Returns false on failure (doesn't throw).\n   */\n  abstract testConnection(): Promise<boolean>;\n\n  /**\n   * Get the current search state for session persistence.\n   * Returns null if no search is in progress.\n   */\n  abstract getSearchState(): SearchState | null;\n\n  /**\n   * Resume a search from a saved state.\n   * Continues yielding articles from where the previous search left off.\n   */\n  abstract resumeSearch(state: SearchState): AsyncIterable<Article>;\n\n  /**\n   * Validate if a saved state is still valid for resuming.\n   * Some providers (e.g., PubMed) have server-side state that can expire.\n   */\n  abstract validateState(state: SearchState): Promise<SearchResumeResult>;\n\n  /**\n   * Create a base SearchState with common fields.\n   * Subclasses can extend this with provider-specific state.\n   */\n  protected createBaseState(\n    query: TranslatedQuery,\n    totalResults: number,\n    retrievedCount: number\n  ): SearchState {\n    return {\n      provider: this.name,\n      query,\n      totalResults,\n      retrievedCount,\n      lastUpdated: new Date(),\n    };\n  }\n\n  /**\n   * Execute a function with retry logic.\n   *\n   * Retries on network errors and server errors.\n   * Does not retry on auth errors.\n   * Uses exponential backoff between retries.\n   * Respects rate limit error's retryAfter if provided.\n   */\n  protected async withRetry<T>(fn: () => Promise<T>): Promise<T> {\n    let lastError: ProviderError | Error | undefined;\n    let currentBackoff = this.config.initialBackoff;\n\n    for (let attempt = 0; attempt <= this.config.retries; attempt++) {\n      try {\n        return await fn();\n      } catch (error) {\n        lastError = error as ProviderError | Error;\n\n        // Check if we should retry\n        if (!this.shouldRetry(error)) {\n          throw error;\n        }\n\n        // If we've exhausted retries, throw\n        if (attempt >= this.config.retries) {\n          throw error;\n        }\n\n        // Calculate wait time\n        let waitTime: number;\n        if (isRateLimitError(error) && 'retryAfter' in error && typeof error.retryAfter === 'number') {\n          waitTime = error.retryAfter;\n        } else {\n          waitTime = currentBackoff;\n          currentBackoff = Math.min(currentBackoff * 2, this.config.maxBackoff);\n        }\n\n        await this.sleep(waitTime);\n      }\n    }\n\n    // This should never be reached, but TypeScript needs it\n    throw lastError;\n  }\n\n  /**\n   * Determine if an error should trigger a retry.\n   */\n  private shouldRetry(error: unknown): boolean {\n    if (isProviderError(error)) {\n      return error.retryable;\n    }\n\n    // Treat unknown errors as non-retryable\n    return false;\n  }\n\n  /**\n   * Sleep for specified milliseconds.\n   */\n  private sleep(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n  }\n}\n\n/**\n * Serialized search state for JSON storage.\n */\ninterface SerializedSearchState {\n  provider: string;\n  query: TranslatedQuery;\n  totalResults: number;\n  retrievedCount: number;\n  lastUpdated: string; // ISO 8601 string\n  providerState?: unknown;\n}\n\n/**\n * Serialize a SearchState to a JSON string.\n * Handles Date conversion to ISO 8601 string.\n */\nexport function serializeState(state: SearchState): string {\n  const serialized: SerializedSearchState = {\n    provider: state.provider,\n    query: state.query,\n    totalResults: state.totalResults,\n    retrievedCount: state.retrievedCount,\n    lastUpdated: state.lastUpdated.toISOString(),\n    providerState: state.providerState,\n  };\n  return JSON.stringify(serialized);\n}\n\n/**\n * Deserialize a JSON string to a SearchState.\n * Handles Date conversion from ISO 8601 string.\n */\nexport function deserializeState(json: string): SearchState {\n  const parsed = JSON.parse(json) as SerializedSearchState;\n  return {\n    provider: parsed.provider as SearchState['provider'],\n    query: parsed.query,\n    totalResults: parsed.totalResults,\n    retrievedCount: parsed.retrievedCount,\n    lastUpdated: new Date(parsed.lastUpdated),\n    providerState: parsed.providerState,\n  };\n}\n"],"names":[],"mappings":";;AAkCA,MAAM,iBAA+C;AAAA,EACnD,WAAW;AAAA,EACX,SAAS;AAAA,EACT,SAAS;AAAA,EACT,gBAAgB;AAAA,EAChB,YAAY;AACd;AAUO,MAAe,aAAiC;AAAA;AAAA,EAKlC;AAAA;AAAA,EAGA;AAAA,EAEnB,YAAY,SAA6B,IAAI;AAC3C,SAAK,SAAS;AAAA,MACZ,GAAG;AAAA,MACH,GAAG;AAAA,IAAA;AAGL,SAAK,cAAc,IAAI,YAAY;AAAA,MACjC,iBAAiB,KAAK,OAAO;AAAA,MAC7B,WAAW,KAAK,OAAO;AAAA,MACvB,gBAAgB,KAAK,OAAO;AAAA,MAC5B,YAAY,KAAK,OAAO;AAAA,IAAA,CACzB;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA,EA2CU,gBACR,OACA,cACA,gBACa;AACb,WAAO;AAAA,MACL,UAAU,KAAK;AAAA,MACf;AAAA,MACA;AAAA,MACA;AAAA,MACA,iCAAiB,KAAA;AAAA,IAAK;AAAA,EAE1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAgB,UAAa,IAAkC;AAC7D,QAAI;AACJ,QAAI,iBAAiB,KAAK,OAAO;AAEjC,aAAS,UAAU,GAAG,WAAW,KAAK,OAAO,SAAS,WAAW;AAC/D,UAAI;AACF,eAAO,MAAM,GAAA;AAAA,MACf,SAAS,OAAO;AACd,oBAAY;AAGZ,YAAI,CAAC,KAAK,YAAY,KAAK,GAAG;AAC5B,gBAAM;AAAA,QACR;AAGA,YAAI,WAAW,KAAK,OAAO,SAAS;AAClC,gBAAM;AAAA,QACR;AAGA,YAAI;AACJ,YAAI,iBAAiB,KAAK,KAAK,gBAAgB,SAAS,OAAO,MAAM,eAAe,UAAU;AAC5F,qBAAW,MAAM;AAAA,QACnB,OAAO;AACL,qBAAW;AACX,2BAAiB,KAAK,IAAI,iBAAiB,GAAG,KAAK,OAAO,UAAU;AAAA,QACtE;AAEA,cAAM,KAAK,MAAM,QAAQ;AAAA,MAC3B;AAAA,IACF;AAGA,UAAM;AAAA,EACR;AAAA;AAAA;AAAA;AAAA,EAKQ,YAAY,OAAyB;AAC3C,QAAI,gBAAgB,KAAK,GAAG;AAC1B,aAAO,MAAM;AAAA,IACf;AAGA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKQ,MAAM,IAA2B;AACvC,WAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AAAA,EACzD;AACF;AAkBO,SAAS,eAAe,OAA4B;AACzD,QAAM,aAAoC;AAAA,IACxC,UAAU,MAAM;AAAA,IAChB,OAAO,MAAM;AAAA,IACb,cAAc,MAAM;AAAA,IACpB,gBAAgB,MAAM;AAAA,IACtB,aAAa,MAAM,YAAY,YAAA;AAAA,IAC/B,eAAe,MAAM;AAAA,EAAA;AAEvB,SAAO,KAAK,UAAU,UAAU;AAClC;AAMO,SAAS,iBAAiB,MAA2B;AAC1D,QAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,SAAO;AAAA,IACL,UAAU,OAAO;AAAA,IACjB,OAAO,OAAO;AAAA,IACd,cAAc,OAAO;AAAA,IACrB,gBAAgB,OAAO;AAAA,IACvB,aAAa,IAAI,KAAK,OAAO,WAAW;AAAA,IACxC,eAAe,OAAO;AAAA,EAAA;AAE1B;"}