@ncukondo/search-hub 0.18.0 → 0.20.0

package/dist/session/types.d.ts

@@ -57,7 +57,7 @@ export interface SessionFile {
     id: string;
     name: string;
     description?: string;
-    type?: 'search' | 'merge';
+    type?: 'search' | 'merge' | 'related';
     createdAt: string;
     updatedAt: string;
     query?: {
@@ -66,6 +66,7 @@ export interface SessionFile {
         targets: ProviderName[];
     };
     sources?: SessionSource[];
+    seeds?: SessionSeeds;
     databases: Partial<Record<ProviderName, DatabaseStatus>>;
     summary: {
         totalHits: number;
@@ -73,10 +74,21 @@ export interface SessionFile {
         status: SessionStatus;
     };
 }
+/**
+ * Seed PMIDs for related article sessions.
+ */
+export interface SessionSeeds {
+    ids: string[];
+    sourceSession?: string;
+}
 /**
  * Check if a session is a merged session.
  */
 export declare function isMergedSession(session: SessionFile): boolean;
+/**
+ * Check if a session is a related articles session.
+ */
+export declare function isRelatedSession(session: SessionFile): boolean;
 /**
  * Session summary for listing.
  */

package/dist/session/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/session/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,SAAS,GACT,WAAW,GACX,SAAS,GACT,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,aAAa,GACb,WAAW,GACX,QAAQ,GACR,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,0EAA0E;QAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,YAAY,EAAE,CAAC;KACzB,CAAC;IACF,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC;IACzD,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE,aAAa,CAAC;KACvB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAE7D;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,OAAO,GACP,kBAAkB,GAClB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,CAAC;AAEtB;;GAEG;AACH,UAAU,YAAY;IACpB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,UAAU,mBAAoB,SAAQ,YAAY;IAChD,KAAK,EAAE,iBAAiB,CAAC;IACzB,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrC;AAED;;GAEG;AACH,UAAU,kBAAmB,SAAQ,YAAY;IAC/C,KAAK,EAAE,gBAAgB,CAAC;IACxB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED;;GAEG;AACH,UAAU,gBAAiB,SAAQ,YAAY;IAC7C,KAAK,EAAE,cAAc,CAAC;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,UAAU,gBAAiB,SAAQ,YAAY;IAC7C,KAAK,EAAE,cAAc,CAAC;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,UAAU,UAAW,SAAQ,YAAY;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,UAAU,oBAAqB,SAAQ,YAAY;IACjD,KAAK,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,UAAU,iBAAkB,SAAQ,YAAY;IAC9C,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,UAAU,qBAAsB,SAAQ,YAAY;IAClD,KAAK,EAAE,mBAAmB,CAAC;IAC3B,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED;;GAEG;AACH,UAAU,mBAAoB,SAAQ,YAAY;IAChD,KAAK,EAAE,iBAAiB,CAAC;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAChB,mBAAmB,GACnB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,UAAU,GACV,oBAAoB,GACpB,iBAAiB,GACjB,qBAAqB,GACrB,mBAAmB,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/session/types.ts"],"names":[],"mappings":"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"}

package/dist/session/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../src/session/types.ts"],"sourcesContent":["/**\n * Session types for search-hub.\n *\n * These types define the structure of session data, including:\n * - Session status and lifecycle\n * - Database-specific status and pagination\n * - Event logging\n */\n\n// Import and re-export ProviderName from the authoritative source\nimport type { ProviderName } from '../providers/base/types.js';\nexport type { ProviderName };\n\n/**\n * Overall session status.\n */\nexport type SessionStatus =\n  | 'created'\n  | 'running'\n  | 'completed'\n  | 'partial'\n  | 'failed';\n\n/**\n * Status for individual database searches.\n */\nexport type DatabaseStatusType =\n  | 'pending'\n  | 'in_progress'\n  | 'completed'\n  | 'failed'\n  | 'skipped';\n\n/**\n * Pagination state for resumable searches.\n */\nexport interface PaginationState {\n  cursor: string | null;\n  pageNumber: number;\n  isComplete: boolean;\n}\n\n/**\n * Error information for failed searches.\n */\nexport interface DatabaseError {\n  code: string;\n  message: string;\n  retryable: boolean;\n}\n\n/**\n * Status of a database search within a session.\n */\nexport interface DatabaseStatus {\n  status: DatabaseStatusType;\n  startedAt?: string;\n  completedAt?: string;\n  totalHits?: number;\n  retrievedCount?: number;\n  pagination?: PaginationState;\n  error?: DatabaseError;\n  files: {\n    query: string;\n    results: string;\n    /** Human-readable YAML results file (present when search is completed) */\n    resultsYaml?: string;\n  };\n}\n\n/**\n * Source session reference for merged sessions.\n */\nexport interface SessionSource {\n  id: string;\n  name: string;\n}\n\n/**\n * Session file structure (session.yaml).\n */\nexport interface SessionFile {\n  version: 1;\n  id: string;\n  name: string;\n  description?: string;\n  type?: 'search' | 'merge';\n  createdAt: string;\n  updatedAt: string;\n  query?: {\n    file: string;\n    hash: string;\n    targets: ProviderName[];\n  };\n  sources?: SessionSource[];\n  databases: Partial<Record<ProviderName, DatabaseStatus>>;\n  summary: {\n    totalHits: number;\n    totalRetrieved: number;\n    status: SessionStatus;\n  };\n}\n\n/**\n * Check if a session is a merged session.\n */\nexport function isMergedSession(session: SessionFile): boolean {\n  return session.type === 'merge';\n}\n\n/**\n * Session summary for listing.\n */\nexport interface SessionSummary {\n  id: string;\n  name: string;\n  status: SessionStatus;\n  createdAt: string;\n  totalHits: number;\n  totalRetrieved: number;\n}\n\n/**\n * Log event types.\n */\nexport type LogEventType =\n  | 'session_created'\n  | 'search_started'\n  | 'page_fetched'\n  | 'rate_limited'\n  | 'retry'\n  | 'search_completed'\n  | 'search_failed'\n  | 'session_completed'\n  | 'session_resumed';\n\n/**\n * Base log event structure.\n */\ninterface BaseLogEvent {\n  ts: string;\n}\n\n/**\n * Session created event.\n */\ninterface SessionCreatedEvent extends BaseLogEvent {\n  event: 'session_created';\n  data: { id: string; query: string };\n}\n\n/**\n * Search started event.\n */\ninterface SearchStartedEvent extends BaseLogEvent {\n  event: 'search_started';\n  provider: ProviderName;\n}\n\n/**\n * Page fetched event.\n */\ninterface PageFetchedEvent extends BaseLogEvent {\n  event: 'page_fetched';\n  provider: ProviderName;\n  page: number;\n  count: number;\n  cursor?: string;\n}\n\n/**\n * Rate limited event.\n */\ninterface RateLimitedEvent extends BaseLogEvent {\n  event: 'rate_limited';\n  provider: ProviderName;\n  waitMs: number;\n}\n\n/**\n * Retry event.\n */\ninterface RetryEvent extends BaseLogEvent {\n  event: 'retry';\n  provider: ProviderName;\n  attempt: number;\n  reason: string;\n}\n\n/**\n * Search completed event.\n */\ninterface SearchCompletedEvent extends BaseLogEvent {\n  event: 'search_completed';\n  provider: ProviderName;\n  total: number;\n  duration: number;\n}\n\n/**\n * Search failed event.\n */\ninterface SearchFailedEvent extends BaseLogEvent {\n  event: 'search_failed';\n  provider: ProviderName;\n  error: string;\n}\n\n/**\n * Session completed event.\n */\ninterface SessionCompletedEvent extends BaseLogEvent {\n  event: 'session_completed';\n  summary: { totalHits: number; totalRetrieved: number };\n}\n\n/**\n * Session resumed event.\n */\ninterface SessionResumedEvent extends BaseLogEvent {\n  event: 'session_resumed';\n  fromProvider: ProviderName;\n  fromPage: number;\n}\n\n/**\n * Union of all log event types.\n */\nexport type LogEvent =\n  | SessionCreatedEvent\n  | SearchStartedEvent\n  | PageFetchedEvent\n  | RateLimitedEvent\n  | RetryEvent\n  | SearchCompletedEvent\n  | SearchFailedEvent\n  | SessionCompletedEvent\n  | SessionResumedEvent;\n\n/**\n * Resume strategy for a provider.\n */\nexport type ResumeStrategy = 'fresh' | 'retry' | 'continue';\n\n/**\n * Information about a provider that can be resumed.\n */\nexport interface ResumableProvider {\n  provider: ProviderName;\n  strategy: ResumeStrategy;\n  cursor?: string | null;\n  pageNumber?: number;\n}\n"],"names":[],"mappings":"AA0GO,SAAS,gBAAgB,SAA+B;AAC7D,SAAO,QAAQ,SAAS;AAC1B;"}
+{"version":3,"file":"types.js","sources":["../../src/session/types.ts"],"sourcesContent":["/**\n * Session types for search-hub.\n *\n * These types define the structure of session data, including:\n * - Session status and lifecycle\n * - Database-specific status and pagination\n * - Event logging\n */\n\n// Import and re-export ProviderName from the authoritative source\nimport type { ProviderName } from '../providers/base/types.js';\nexport type { ProviderName };\n\n/**\n * Overall session status.\n */\nexport type SessionStatus =\n  | 'created'\n  | 'running'\n  | 'completed'\n  | 'partial'\n  | 'failed';\n\n/**\n * Status for individual database searches.\n */\nexport type DatabaseStatusType =\n  | 'pending'\n  | 'in_progress'\n  | 'completed'\n  | 'failed'\n  | 'skipped';\n\n/**\n * Pagination state for resumable searches.\n */\nexport interface PaginationState {\n  cursor: string | null;\n  pageNumber: number;\n  isComplete: boolean;\n}\n\n/**\n * Error information for failed searches.\n */\nexport interface DatabaseError {\n  code: string;\n  message: string;\n  retryable: boolean;\n}\n\n/**\n * Status of a database search within a session.\n */\nexport interface DatabaseStatus {\n  status: DatabaseStatusType;\n  startedAt?: string;\n  completedAt?: string;\n  totalHits?: number;\n  retrievedCount?: number;\n  pagination?: PaginationState;\n  error?: DatabaseError;\n  files: {\n    query: string;\n    results: string;\n    /** Human-readable YAML results file (present when search is completed) */\n    resultsYaml?: string;\n  };\n}\n\n/**\n * Source session reference for merged sessions.\n */\nexport interface SessionSource {\n  id: string;\n  name: string;\n}\n\n/**\n * Session file structure (session.yaml).\n */\nexport interface SessionFile {\n  version: 1;\n  id: string;\n  name: string;\n  description?: string;\n  type?: 'search' | 'merge' | 'related';\n  createdAt: string;\n  updatedAt: string;\n  query?: {\n    file: string;\n    hash: string;\n    targets: ProviderName[];\n  };\n  sources?: SessionSource[];\n  seeds?: SessionSeeds;\n  databases: Partial<Record<ProviderName, DatabaseStatus>>;\n  summary: {\n    totalHits: number;\n    totalRetrieved: number;\n    status: SessionStatus;\n  };\n}\n\n/**\n * Seed PMIDs for related article sessions.\n */\nexport interface SessionSeeds {\n  ids: string[];\n  sourceSession?: string;\n}\n\n/**\n * Check if a session is a merged session.\n */\nexport function isMergedSession(session: SessionFile): boolean {\n  return session.type === 'merge';\n}\n\n/**\n * Check if a session is a related articles session.\n */\nexport function isRelatedSession(session: SessionFile): boolean {\n  return session.type === 'related';\n}\n\n/**\n * Session summary for listing.\n */\nexport interface SessionSummary {\n  id: string;\n  name: string;\n  status: SessionStatus;\n  createdAt: string;\n  totalHits: number;\n  totalRetrieved: number;\n}\n\n/**\n * Log event types.\n */\nexport type LogEventType =\n  | 'session_created'\n  | 'search_started'\n  | 'page_fetched'\n  | 'rate_limited'\n  | 'retry'\n  | 'search_completed'\n  | 'search_failed'\n  | 'session_completed'\n  | 'session_resumed';\n\n/**\n * Base log event structure.\n */\ninterface BaseLogEvent {\n  ts: string;\n}\n\n/**\n * Session created event.\n */\ninterface SessionCreatedEvent extends BaseLogEvent {\n  event: 'session_created';\n  data: { id: string; query: string };\n}\n\n/**\n * Search started event.\n */\ninterface SearchStartedEvent extends BaseLogEvent {\n  event: 'search_started';\n  provider: ProviderName;\n}\n\n/**\n * Page fetched event.\n */\ninterface PageFetchedEvent extends BaseLogEvent {\n  event: 'page_fetched';\n  provider: ProviderName;\n  page: number;\n  count: number;\n  cursor?: string;\n}\n\n/**\n * Rate limited event.\n */\ninterface RateLimitedEvent extends BaseLogEvent {\n  event: 'rate_limited';\n  provider: ProviderName;\n  waitMs: number;\n}\n\n/**\n * Retry event.\n */\ninterface RetryEvent extends BaseLogEvent {\n  event: 'retry';\n  provider: ProviderName;\n  attempt: number;\n  reason: string;\n}\n\n/**\n * Search completed event.\n */\ninterface SearchCompletedEvent extends BaseLogEvent {\n  event: 'search_completed';\n  provider: ProviderName;\n  total: number;\n  duration: number;\n}\n\n/**\n * Search failed event.\n */\ninterface SearchFailedEvent extends BaseLogEvent {\n  event: 'search_failed';\n  provider: ProviderName;\n  error: string;\n}\n\n/**\n * Session completed event.\n */\ninterface SessionCompletedEvent extends BaseLogEvent {\n  event: 'session_completed';\n  summary: { totalHits: number; totalRetrieved: number };\n}\n\n/**\n * Session resumed event.\n */\ninterface SessionResumedEvent extends BaseLogEvent {\n  event: 'session_resumed';\n  fromProvider: ProviderName;\n  fromPage: number;\n}\n\n/**\n * Union of all log event types.\n */\nexport type LogEvent =\n  | SessionCreatedEvent\n  | SearchStartedEvent\n  | PageFetchedEvent\n  | RateLimitedEvent\n  | RetryEvent\n  | SearchCompletedEvent\n  | SearchFailedEvent\n  | SessionCompletedEvent\n  | SessionResumedEvent;\n\n/**\n * Resume strategy for a provider.\n */\nexport type ResumeStrategy = 'fresh' | 'retry' | 'continue';\n\n/**\n * Information about a provider that can be resumed.\n */\nexport interface ResumableProvider {\n  provider: ProviderName;\n  strategy: ResumeStrategy;\n  cursor?: string | null;\n  pageNumber?: number;\n}\n"],"names":[],"mappings":"AAmHO,SAAS,gBAAgB,SAA+B;AAC7D,SAAO,QAAQ,SAAS;AAC1B;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncukondo/search-hub",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "A CLI tool for systematic literature searching across multiple academic databases",
   "type": "module",
   "engines": {