/**
 * Claude-Mem SDK - TypeScript Declarations
 *
 * Standalone module for external consumers to parse claude-mem observation XML
 * and build prompts for the memory worker.
 */

export interface ParsedObservation {
  type: string;
  title: string | null;
  subtitle: string | null;
  facts: string[];
  narrative: string | null;
  concepts: string[];
  files_read: string[];
  files_modified: string[];
}

export interface ParsedSummary {
  request: string | null;
  investigated: string | null;
  learned: string | null;
  completed: string | null;
  next_steps: string | null;
  notes: string | null;
}

export interface Observation {
  id: number;
  tool_name: string;
  tool_input: string;
  tool_output: string;
  created_at_epoch: number;
  cwd?: string;
}

export interface ParseObservationsOptions {
  /** Array of valid observation types. If provided, validates types against this list. */
  validTypes?: string[];
  /** Type to use if type is missing or invalid. Defaults to 'observation'. */
  fallbackType?: string;
}

/**
 * Parse observation XML blocks from text
 * Returns all observations found in the text
 *
 * @param text - The text containing observation XML blocks
 * @param options - Optional configuration for type validation
 * @returns Array of parsed observations
 *
 * @example
 * ```typescript
 * const text = `<observation>
 *   <type>code_change</type>
 *   <title>Added login feature</title>
 *   <facts><fact>New auth module</fact></facts>
 * </observation>`;
 *
 * const observations = parseObservations(text);
 * // => [{ type: 'code_change', title: 'Added login feature', ... }]
 * ```
 */
export function parseObservations(
  text: string,
  options?: ParseObservationsOptions
): ParsedObservation[];

/**
 * Parse summary XML block from text
 * Returns null if no valid summary found or if summary was skipped
 *
 * @param text - The text containing summary XML block
 * @returns Parsed summary or null
 *
 * @example
 * ```typescript
 * const text = `<summary>
 *   <request>Implement auth</request>
 *   <completed>Added JWT tokens</completed>
 * </summary>`;
 *
 * const summary = parseSummary(text);
 * // => { request: 'Implement auth', completed: 'Added JWT tokens', ... }
 * ```
 */
export function parseSummary(text: string): ParsedSummary | null;

/**
 * Build prompt to send tool observation to SDK agent
 *
 * @param obs - The observation object containing tool data
 * @returns Formatted XML prompt string
 *
 * @example
 * ```typescript
 * const obs = {
 *   id: 1,
 *   tool_name: 'Read',
 *   tool_input: '{"file_path": "/src/index.ts"}',
 *   tool_output: '{"content": "..."}',
 *   created_at_epoch: Date.now()
 * };
 *
 * const prompt = buildObservationPrompt(obs);
 * // => '<observed_from_primary_session>...'
 * ```
 */
export function buildObservationPrompt(obs: Observation): string;
