@nathanvale/chatline 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,688 @@
+/**
+* TypeScript type for the full configuration
+* Explicitly defined for DTS generation compatibility
+*/
+type Config = {
+	version: string;
+	attachmentRoots: string[];
+	gemini: {
+		apiKey: string;
+		model: string;
+		rateLimitDelay: number;
+		maxRetries: number;
+	};
+	firecrawl?: {
+		apiKey?: string;
+		enabled: boolean;
+	};
+	enrichment: {
+		enableVisionAnalysis: boolean;
+		enableAudioTranscription: boolean;
+		enableLinkEnrichment: boolean;
+		imageCacheDir: string;
+		checkpointInterval: number;
+		forceRefresh: boolean;
+	};
+	render: {
+		groupByTimeOfDay: boolean;
+		renderRepliesAsNested: boolean;
+		renderTapbacksAsEmoji: boolean;
+		maxNestingDepth: number;
+	};
+};
+/**
+* CONFIG-T01-AC05: Validate config with detailed error messages
+*
+* @param config - Raw config object (parsed from JSON/YAML)
+* @returns Validated and typed config object
+* @throws ZodError with field paths and expected types
+*
+* @example
+* ```typescript
+* try {
+*   const config = validateConfig(rawConfig)
+* } catch (error) {
+*   if (error instanceof z.ZodError) {
+*     error.errors.forEach(err => {
+*       console.error(`${err.path.join('.')}: ${err.message}`)
+*     })
+*   }
+* }
+* ```
+*/
+declare function validateConfig2(config: unknown): Config;
+/**
+* Validate config and return result with detailed errors
+*
+* @param config - Raw config object
+* @returns Validation result with success flag and data/errors
+*/
+declare function validateConfigSafe(config: unknown): {
+	success: boolean;
+	data?: Config;
+	errors?: Array<{
+		path: string;
+		message: string;
+	}>;
+};
+/**
+* Default configuration values
+*
+* Used as fallback when no config file is present
+*/
+declare const DEFAULT_CONFIG: Partial<Config>;
+/**
+* CONFIG-T01-AC04: Config file discovery patterns
+*
+* Checked in order:
+* 1. ./imessage-config.yaml
+* 2. ./imessage-config.yml
+* 3. ./imessage-config.json
+*/
+declare const CONFIG_FILE_PATTERNS: readonly ["./imessage-config.yaml", "./imessage-config.yml", "./imessage-config.json"];
+/**
+* CONFIG-T01-AC02: Supported config file formats
+*/
+type ConfigFormat = "json" | "yaml";
+/**
+* Detect config file format from file extension
+*/
+declare function detectConfigFormat(filePath: string): ConfigFormat;
+/**
+* CONFIG-T03-AC02: Generate config file content in specified format
+*
+* @param format - Output format ('json' or 'yaml')
+* @returns Formatted config file content as string
+*
+* @example
+* ```typescript
+* const yamlContent = generateConfigContent('yaml')
+* const jsonContent = generateConfigContent('json')
+* ```
+*/
+declare function generateConfigContent(format: ConfigFormat): string;
+/**
+* CONFIG-T03-AC05: Validate generated config content
+*
+* Parses the generated content and validates against schema
+* to ensure the template produces valid config.
+*
+* @param content - Generated config content
+* @param format - Format of content ('json' | 'yaml')
+* @returns Validation result
+*/
+declare function validateGeneratedConfig(content: string, format: ConfigFormat): {
+	valid: boolean;
+	errors?: string[];
+};
+/**
+* Get default config file path for a given format
+*
+* @param format - Desired format ('json' | 'yaml')
+* @returns Default file path
+*/
+declare function getDefaultConfigPath(format: ConfigFormat): string;
+/**
+* CONFIG-T02-AC01: Discover config file in directory
+*
+* Checks files in order:
+* 1. imessage-config.yaml
+* 2. imessage-config.yml
+* 3. imessage-config.json
+*
+* @param baseDir - Directory to search in (defaults to current directory)
+* @returns Path to first existing config file, or null if none found
+*/
+declare function discoverConfigFile(baseDir?: string): Promise<string | null>;
+/**
+* CONFIG-T02-AC01: Load and parse config file
+*
+* Supports JSON and YAML formats with auto-detection
+*
+* @param filePath - Path to config file
+* @returns Parsed config object (unvalidated)
+* @throws Error if file cannot be read or parsed
+*/
+declare function loadConfigFile(filePath: string): Promise<unknown>;
+/**
+* CONFIG-T02-AC03: Substitute environment variables in config
+*
+* Recursively replaces ${VAR_NAME} patterns with environment variable values
+*
+* @param obj - Config object (or primitive)
+* @returns Object with env vars substituted
+*
+* @example
+* ```typescript
+* // With process.env.GEMINI_API_KEY = 'secret123'
+* substituteEnvVars({ apiKey: '${GEMINI_API_KEY}' })
+* // => { apiKey: 'secret123' }
+* ```
+*/
+declare function substituteEnvVars(obj: unknown): unknown;
+/**
+* CONFIG-T02-AC02: Merge configuration with precedence
+*
+* Precedence (highest to lowest):
+* 1. CLI options
+* 2. Config file
+* 3. Defaults (applied by Zod schema)
+*
+* @param fileConfig - Config loaded from file
+* @param cliOptions - Options from CLI flags
+* @returns Merged config object
+*/
+declare function mergeConfig(fileConfig: Partial<Config>, cliOptions?: Partial<Config>): Partial<Config>;
+/**
+* CONFIG-T02: Main config loading function
+*
+* Loads configuration with the following precedence:
+* 1. CLI options (highest priority)
+* 2. Config file
+* 3. Defaults from schema (lowest priority)
+*
+* @param options - Loading options
+* @param options.configPath - Explicit config file path (optional)
+* @param options.cliOptions - CLI options to merge (optional)
+* @param options.skipCache - Force reload even if cached (optional)
+* @returns Validated and merged configuration
+* @throws Error if config is invalid or cannot be loaded
+*
+* @example
+* ```typescript
+* // Load with auto-discovery
+* const config = await loadConfig()
+*
+* // Load specific file
+* const config = await loadConfig({ configPath: './custom-config.yaml' })
+*
+* // Override with CLI options
+* const config = await loadConfig({
+*   cliOptions: {
+*     gemini: { apiKey: 'override-key' }
+*   }
+* })
+* ```
+*/
+declare function loadConfig(options?: {
+	configPath?: string;
+	cliOptions?: Partial<Config>;
+	skipCache?: boolean;
+}): Promise<Config>;
+/**
+* Clear the config cache
+*
+* Useful for testing or when config needs to be reloaded
+*/
+declare function clearConfigCache(): void;
+/**
+* Check if a config is currently cached
+*
+* @returns True if config is cached
+*/
+declare function isConfigCached(): boolean;
+/**
+* Rate Limiting and Retry Logic Module (ENRICH--T07)
+*
+* Implements comprehensive rate limiting with:
+* - AC01: Configurable delays between API calls (default 1000ms)
+* - AC02: Exponential backoff for 429 responses with ±25% jitter
+* - AC03: Retry 5xx errors with maxRetries limit (default 3)
+* - AC04: Respect Retry-After header for 429/503 responses
+* - AC05: Circuit breaker after N consecutive failures (default 5)
+*
+* Architecture:
+* - RateLimiter: Main class managing all rate limiting logic
+* - Configuration with sensible defaults
+* - Per-provider state isolation
+* - Deterministic jitter calculation
+*/
+type RateLimitConfig = {
+	rateLimitDelay: number;
+	maxRetries: number;
+	circuitBreakerThreshold: number;
+	circuitBreakerResetMs: number;
+};
+type RateLimitState = {
+	consecutiveFailures: number;
+	circuitOpen: boolean;
+	circuitOpenedAt: number | null;
+	lastCallTime: number | null;
+};
+type ApiResponse = {
+	status: number;
+	headers?: Record<string, string | number | undefined>;
+};
+declare class RateLimiter {
+	private config;
+	private state;
+	constructor(partialConfig?: Partial<RateLimitConfig>);
+	private validateConfig;
+	/**
+	* Check if rate limiting should delay the next call
+	* @returns delay in ms, or 0 if no delay needed
+	*/
+	shouldRateLimit(): number;
+	/**
+	* Record a successful API call for rate limiting tracking
+	*/
+	recordCall(): void;
+	/**
+	* Calculate exponential backoff with ±25% jitter
+	* Formula: 2^n seconds ± 25%
+	* @param attemptNumber - retry attempt number (1-based)
+	* @returns delay in ms
+	*/
+	private calculateExponentialBackoff;
+	/**
+	* Parse Retry-After header (can be integer seconds or HTTP date)
+	* @param retryAfterValue - header value
+	* @returns delay in ms, or null if invalid
+	*/
+	private parseRetryAfterHeader;
+	/**
+	* Determine if response should be retried and calculate delay
+	* @param response - API response with status and optional headers
+	* @param attemptNumber - current attempt (1-based)
+	* @returns { shouldRetry: boolean, delayMs: number }
+	*/
+	getRetryStrategy(response: ApiResponse, attemptNumber: number): {
+		shouldRetry: boolean;
+		delayMs: number;
+	};
+	/**
+	* Check if we should retry based on attempt count
+	* @param attemptNumber - current attempt (1-based)
+	* @returns true if we should retry
+	*/
+	shouldRetryAttempt(attemptNumber: number): boolean;
+	/**
+	* Check if circuit breaker is open
+	* @returns true if circuit is open (should fail fast)
+	*/
+	isCircuitOpen(): boolean;
+	/**
+	* Record a failure for circuit breaker tracking
+	*/
+	recordFailure(): void;
+	/**
+	* Record a success to reset failure counter
+	*/
+	recordSuccess(): void;
+	/**
+	* Manually reset circuit breaker
+	*/
+	resetCircuitBreaker(): void;
+	/**
+	* Get current state for inspection
+	*/
+	getState(): RateLimitState;
+	/**
+	* Get configuration
+	*/
+	getConfig(): RateLimitConfig;
+	/**
+	* Reset all state (for testing)
+	*/
+	reset(): void;
+}
+/**
+* Create a new rate limiter with default configuration
+*/
+declare function createRateLimiter(config?: Partial<RateLimitConfig>): RateLimiter;
+/**
+* Determine if a status code is a 5xx error (server error)
+*/
+declare function is5xx(status: number): boolean;
+/**
+* Determine if a status code should trigger retry
+*/
+declare function isRetryableStatus(status: number): boolean;
+import { z as z2 } from "zod";
+type MessageGUID = string;
+type ChatId = string;
+type MediaKind = "image" | "audio" | "video" | "pdf" | "unknown";
+type MediaEnrichment = {
+	kind: MediaKind | "link" | "transcription" | "pdf_summary" | "video_metadata" | "link_context" | "image_analysis";
+	model?: string;
+	createdAt: string;
+	visionSummary?: string;
+	shortDescription?: string;
+	transcription?: string;
+	transcript?: string;
+	speakers?: string[];
+	timestamps?: Array<{
+		time: string;
+		speaker: string;
+		content: string;
+	}>;
+	pdfSummary?: string;
+	videoMetadata?: {
+		filename?: string;
+		size?: number;
+		duration?: number;
+		analyzed?: boolean;
+		note?: string;
+	};
+	error?: string;
+	usedFallback?: boolean;
+	failedProviders?: string[];
+	url?: string;
+	title?: string;
+	summary?: string;
+	provider: "gemini" | "firecrawl" | "local" | "youtube" | "spotify" | "twitter" | "instagram" | "generic";
+	version: string;
+};
+type MediaProvenance = {
+	source: "csv" | "db" | "merged";
+	lastSeen: string;
+	resolvedAt: string;
+};
+type MediaMeta = {
+	id: string;
+	filename: string;
+	path: string;
+	size?: number;
+	mimeType?: string;
+	uti?: string | null;
+	isSticker?: boolean;
+	hidden?: boolean;
+	mediaKind?: MediaKind;
+	enrichment?: Array<MediaEnrichment>;
+	provenance?: MediaProvenance;
+};
+type ReplyInfo = {
+	sender?: string;
+	date?: string;
+	text?: string;
+	targetMessageGuid?: MessageGUID;
+};
+type TapbackInfo = {
+	type: "loved" | "liked" | "disliked" | "laughed" | "emphasized" | "questioned" | "emoji";
+	action: "added" | "removed";
+	targetMessageGuid?: MessageGUID;
+	targetMessagePart?: number;
+	targetText?: string;
+	isMedia?: boolean;
+	emoji?: string;
+};
+type MessageCore = {
+	guid: MessageGUID;
+	rowid?: number;
+	chatId?: ChatId | null;
+	service?: string | null;
+	subject?: string | null;
+	handleId?: number | null;
+	handle?: string | null;
+	destinationCallerId?: string | null;
+	isFromMe: boolean;
+	otherHandle?: number | null;
+	date: string;
+	dateRead?: string | null;
+	dateDelivered?: string | null;
+	dateEdited?: string | null;
+	isRead?: boolean;
+	itemType?: number;
+	groupActionType?: number;
+	groupTitle?: string | null;
+	shareStatus?: boolean;
+	shareDirection?: boolean | null;
+	expressiveSendStyleId?: string | null;
+	balloonBundleId?: string | null;
+	threadOriginatorGuid?: string | null;
+	threadOriginatorPart?: number | null;
+	numReplies?: number;
+	deletedFrom?: number | null;
+};
+type Message = {
+	messageKind: "text" | "media" | "tapback" | "notification";
+	text?: string | null;
+	tapback?: TapbackInfo | null;
+	replyingTo?: ReplyInfo | null;
+	replyingToRaw?: string | null;
+	media?: MediaMeta | null;
+	groupGuid?: string | null;
+	exportTimestamp?: string;
+	exportVersion?: string;
+	isUnsent?: boolean;
+	isEdited?: boolean;
+} & MessageCore;
+type ExportEnvelope = {
+	schemaVersion: string;
+	source: "csv" | "db" | "merged";
+	createdAt: string;
+	messages: Array<Message>;
+	meta?: Record<string, unknown>;
+};
+declare const MediaEnrichmentSchema: z2.ZodType<MediaEnrichment>;
+declare const MediaProvenanceSchema: z2.ZodType<MediaProvenance>;
+declare const MediaMetaSchema: z2.ZodType<MediaMeta>;
+declare const ReplyInfoSchema: z2.ZodType<ReplyInfo>;
+declare const TapbackInfoSchema: z2.ZodType<TapbackInfo>;
+declare const MessageCoreSchema: z2.ZodType<MessageCore>;
+/**
+* Deduplication and merge logic for NORMALIZE--T04
+*
+* Merges CSV and DB message sources with:
+* AC01: Exact GUID matching (primary)
+* AC02: DB authoritiveness for conflicts
+* AC03: Content equivalence detection
+* AC04: Data loss verification
+* AC05: Deterministic GUID assignment
+*/
+type MergeStats = {
+	csvCount: number;
+	dbCount: number;
+	outputCount: number;
+	exactMatches: number;
+	contentMatches: number;
+	conflicts: number;
+	noMatches: number;
+};
+type MergeResult = {
+	messages: Message[];
+	stats: MergeStats;
+	conflicts?: Array<{
+		csvMsg: Message;
+		dbMsg: Message;
+		confidence: number;
+	}>;
+	warnings?: string[];
+};
+/**
+* AC01 + AC02 + AC03 + AC04 + AC05: Main dedup and merge function
+*
+* Strategy:
+* 1. Build GUID index for fast lookup
+* 2. For each CSV message:
+*    a. Try exact GUID match (AC01)
+*    b. Try content equivalence (AC03)
+*    c. Apply DB authoritiveness if merging (AC02)
+*    d. Keep separate if no match
+* 3. Add unmatched DB messages
+* 4. Verify no data loss (AC04)
+* 5. Ensure determinism (AC05)
+*/
+declare function dedupAndMerge(csvMessages: Message[], dbMessages: Message[]): MergeResult;
+type IngestOptions = {
+	attachmentRoots: string[];
+	messageDate?: string;
+};
+type CSVRow = {
+	[key: string]: string | undefined;
+};
+/**
+* Main entry point: Ingest CSV file and convert to unified Message schema
+*/
+declare function ingestCSV(csvFilePath: string, options: IngestOptions): Message[];
+/**
+* Export envelope wrapper for CSV ingestion output
+*/
+declare function createExportEnvelope(messages: Message[]): ExportEnvelope;
+type EnrichmentStats = {
+	processedCount: number;
+	failedCount: number;
+	startTime: string;
+	endTime: string;
+};
+type PipelineConfig = {
+	configHash: string;
+};
+/**
+* Complete state for incremental enrichment tracking
+* Stored in .imessage-state.json at output directory root
+*/
+type IncrementalState = {
+	/** Schema version for backward compatibility */
+	version: string;
+	/** ISO 8601 UTC timestamp of last enrichment run */
+	lastEnrichedAt: string;
+	/** Total messages as of last run (for progress reporting) */
+	totalMessages: number;
+	/** Array of enriched message GUIDs (for delta detection) */
+	enrichedGuids: string[];
+	/** Pipeline configuration hash (detects config changes) */
+	pipelineConfig: PipelineConfig;
+	/** Optional: Stats from last enrichment run */
+	enrichmentStats: EnrichmentStats | null;
+};
+/**
+* Result of delta detection
+*
+* Provides:
+* - newGuids: Message GUIDs to enrich
+* - totalMessages: Total current messages
+* - previousEnrichedCount: Messages enriched in prior run
+* - newCount: Number of new messages found
+* - isFirstRun: Whether state file was missing
+* - state: Loaded or created state for update after enrichment
+*/
+type DeltaResult = {
+	/** GUIDs of messages to enrich (new since last run) */
+	newGuids: string[];
+	/** Total messages in normalized dataset */
+	totalMessages: number;
+	/** Count of previously enriched messages */
+	previousEnrichedCount: number;
+	/** Number of new messages found in delta */
+	newCount: number;
+	/** true if no prior state file found */
+	isFirstRun: boolean;
+	/** IncrementalState to update and save after enrichment */
+	state: IncrementalState;
+};
+/**
+* AC02 + AC03: Extract message GUIDs from normalized messages
+*
+* Converts Message[] to Set<guid> for efficient delta computation
+*
+* @param messages - Normalized messages to process
+* @returns Set of unique message GUIDs
+*/
+declare function extractGuidsFromMessages(messages: Message[]): Set<string>;
+/**
+* AC05: Log human-readable delta summary
+*
+* Outputs lines like:
+* - "Found 142 new messages to enrich"
+* - "Previously enriched: 358"
+* - "This is your first enrichment run"
+* - "Delta: 28.3% of 500 total messages"
+*
+* @param result - DeltaResult to summarize
+*/
+declare function logDeltaSummary(result: DeltaResult): void;
+/**
+* AC01-AC05: Perform complete delta detection
+*
+* Workflow:
+* 1. AC04: Load previous state (null if missing)
+* 2. AC02: Extract current message GUIDs
+* 3. AC03: Compute delta (new GUIDs only)
+* 4. AC05: Log summary
+*
+* Returns DeltaResult with:
+* - newGuids to enrich
+* - metadata for progress tracking
+* - state to update after enrichment
+*
+* @param messages - Normalized messages from normalize-link stage
+* @param stateFilePath - Path to .imessage-state.json
+* @returns DeltaResult with new GUIDs and metadata
+* @throws Error if state file can't be read (permission denied, etc.)
+*/
+declare function detectDelta(messages: Message[], stateFilePath: string): Promise<DeltaResult>;
+/**
+* Calculate delta statistics for progress monitoring
+*
+* Useful for:
+* - Progress bars (show percentage to enrich)
+* - ETA calculation
+* - Summary reports
+*
+* @param result - DeltaResult to analyze
+* @returns Statistics object with counts and percentages
+*/
+declare function getDeltaStats(result: DeltaResult): {
+	total: number;
+	new: number;
+	previous: number;
+	percentNew: number;
+	percentPrevious: number;
+};
+/**
+* Options for merge behavior
+*/
+type MergeOptions = {
+	/** Force refresh overwrites existing enrichments (default: false) */
+	forceRefresh?: boolean;
+};
+/**
+* Statistics from merge operation
+*/
+type MergeStatistics = {
+	/** Number of messages merged (existing GUIDs updated) */
+	mergedCount: number;
+	/** Number of messages added (new GUIDs) */
+	addedCount: number;
+	/** Number of messages with preserved enrichments */
+	preservedCount: number;
+	/** Total messages in result */
+	totalMessages: number;
+	/** Percentage of messages that were merged */
+	mergedPercentage?: number;
+	/** Percentage of messages that were added */
+	addedPercentage?: number;
+};
+/**
+* Result of merge operation
+*/
+type MergeResult2 = {
+	/** Merged messages with enrichments preserved/updated */
+	messages: Message[];
+	/** Statistics about the merge operation */
+	statistics: MergeStatistics;
+	/** Count of messages merged */
+	mergedCount: number;
+	/** Count of messages added */
+	addedCount: number;
+	/** Count of messages with preserved enrichments */
+	preservedCount: number;
+};
+/**
+* AC02 + AC03: Merge new enrichments with existing messages
+*
+* Strategy:
+* 1. Build index of existing messages by GUID
+* 2. For each new message:
+*    - If GUID exists: merge enrichments (preserve existing unless --force-refresh)
+*    - If GUID is new: add message
+* 3. Preserve enrichment order and structure
+*
+* @param existingMessages - Messages from prior enriched.json
+* @param newMessages - New/updated messages from enrichment
+* @param options - Merge options (forceRefresh, etc.)
+* @returns MergeResult with merged messages and statistics
+*/
+declare function mergeEnrichments(existingMessages: Message[], newMessages: Message[], options?: MergeOptions): MergeResult2;
+export { validateGeneratedConfig, validateConfigSafe, validateConfig2 as validateConfig, substituteEnvVars, mergeEnrichments, mergeConfig, logDeltaSummary, loadConfigFile, loadConfig, isRetryableStatus, isConfigCached, is5xx, ingestCSV, getDeltaStats, getDefaultConfigPath, generateConfigContent, extractGuidsFromMessages, discoverConfigFile, detectDelta, detectConfigFormat, dedupAndMerge, createRateLimiter, createExportEnvelope, clearConfigCache, TapbackInfoSchema, TapbackInfo, ReplyInfoSchema, ReplyInfo, RateLimiter, RateLimitState, RateLimitConfig, MessageGUID, MessageCoreSchema, MessageCore, Message, MergeStats, MergeStatistics, MergeOptions, MediaProvenanceSchema, MediaProvenance, MediaMetaSchema, MediaMeta, MediaKind, MediaEnrichmentSchema, MediaEnrichment, IngestOptions, MergeResult as IngestMergeResult, ExportEnvelope, MergeResult2 as EnrichmentMergeResult, DeltaResult, DEFAULT_CONFIG, ConfigFormat, Config, ChatId, CSVRow, CONFIG_FILE_PATTERNS, ApiResponse };