notebooklm-kit 0.0.1 → 2.1.1

package/dist/src/services/sources.d.ts

@@ -0,0 +1,1085 @@
+/**
+ * Sources service
+ * Handles source operations (add URLs, files, text, Google Drive, YouTube, etc.)
+ *
+ * WORKFLOW USAGE NOTES:
+ * - Individual add methods (addFromURL, addFromText, etc.) return immediately after source is queued
+ * - Use pollProcessing() to check if sources are ready, or use workflow functions that handle waiting
+ * - For web search: Use searchWebAndWait() to get results, then addDiscovered() to add them
+ * - For batch operations: Use addBatch() to add multiple sources efficiently
+ * - All add methods check quota before adding and record usage after success
+ */
+import { RPCClient } from '../rpc/rpc-client.js';
+import type { Source, AddSourceFromURLOptions, AddSourceFromTextOptions, AddSourceFromFileOptions, SourceProcessingStatus, SourceContent, SourceFreshness, DiscoveredWebSource, DiscoveredDriveSource, SearchWebSourcesOptions, AddDiscoveredSourcesOptions, AddGoogleDriveSourceOptions, AddYouTubeSourceOptions, BatchAddSourcesOptions, SearchWebAndWaitOptions, WebSearchResult } from '../types/source.js';
+/**
+ * Web search sub-service for sources
+ * Handles web search operations (search, wait, get results, add discovered)
+ */
+export declare class WebSearchService {
+    private rpc;
+    private quota?;
+    constructor(rpc: RPCClient, quota?: import("../utils/quota.js").QuotaManager | undefined);
+    /**
+     * Search web sources (STEP 1 of multi-step workflow)
+     *
+     * **Use this for multi-step workflows where you want to see results before deciding next steps.**
+     *
+     * **Multi-Step Workflow (for user decision-making):**
+     * 1. `search()` → Returns `sessionId` (start here - this method)
+     *    - Shows you the search has started
+     *    - Returns immediately with sessionId
+     * 2. `getResults(sessionId)` → Returns discovered sources (you can validate/filter)
+     *    - Shows you what was found
+     *    - You can inspect, filter, or select which sources to add
+     * 3. `addDiscovered(sessionId, selectedSources)` → Adds your selected sources
+     *    - You decide which sources from step 2 to actually add
+     *
+     * **Simple Alternative (RECOMMENDED for automated workflows):**
+     * - Use `searchAndWait()` instead - one call, returns all results for validation
+     * - Then use `addDiscovered()` to add selected sources
+     *
+     * **Customization Options:**
+     * - `mode: ResearchMode.FAST` - Quick search (default)
+     * - `mode: ResearchMode.DEEP` - Comprehensive research (web only)
+     * - `sourceType: SearchSourceType.WEB` - Search web (default)
+     * - `sourceType: SearchSourceType.GOOGLE_DRIVE` - Search Google Drive (FAST mode only)
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Search options (query, mode, sourceType)
+     * @returns sessionId - Required for steps 2 and 3
+     *
+     * @example
+     * ```typescript
+     * // Multi-step: Start search, then check results later
+     * const sessionId = await client.sources.add.web.search('notebook-id', {
+     *   query: 'AI research',
+     *   mode: ResearchMode.DEEP,
+     * });
+     *
+     * // Later... check what was found
+     * const results = await client.sources.add.web.getResults('notebook-id', sessionId);
+     * console.log(`Found ${results.web.length} sources`);
+     *
+     * // User decides which ones to add
+     * const selected = results.web.filter(s => s.url.includes('arxiv.org'));
+     * await client.sources.add.web.addDiscovered('notebook-id', {
+     *   sessionId,
+     *   webSources: selected,
+     * });
+     * ```
+     */
+    search(notebookId: string, options: SearchWebSourcesOptions): Promise<string>;
+    /**
+     * Search web sources and wait for results (SIMPLE - one call, returns results for validation)
+     *
+     * **RECOMMENDED FOR SIMPLE WORKFLOWS** - One call, returns all results you can validate.
+     *
+     * **What it does:**
+     * - Starts search, waits for results automatically
+     * - Returns all discovered sources once available (or timeout)
+     * - Returns results + sessionId for validation
+     * - No user decision needed during search - just wait and get results
+     *
+     * **Simple Workflow:**
+     * 1. `searchAndWait()` → Returns results + sessionId (this method - validates results)
+     * 2. `addDiscovered(sessionId, selectedSources)` → Add your selected sources
+     *
+     * **Customization Options:**
+     * - `mode: ResearchMode.FAST` - Quick search (default, ~10-30 seconds)
+     * - `mode: ResearchMode.DEEP` - Comprehensive research (web only, ~60-120 seconds)
+     * - `sourceType: SearchSourceType.WEB` - Search web (default)
+     * - `sourceType: SearchSourceType.GOOGLE_DRIVE` - Search Google Drive (FAST mode only)
+     * - `timeout` - Max wait time (default: 60000ms = 60 seconds)
+     * - `pollInterval` - How often to check for results (default: 2000ms = 2 seconds)
+     * - `onProgress` - Callback to track progress
+     *
+     * **When to use:**
+     * - Automated workflows where you don't need to see intermediate steps
+     * - Simple cases where you just want to search and get results
+     * - When you want to validate all results before deciding which to add
+     *
+     * **When NOT to use:**
+     * - If you need to see results as they come in (use `search()` + `getResults()` instead)
+     * - If you want to make decisions during the search process
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Search options with waiting configuration
+     * @returns WebSearchResult with sessionId, web sources, and drive sources
+     *
+     * @example
+     * ```typescript
+     * // Simple: Search and get all results for validation
+     * const result = await client.sources.add.web.searchAndWait('notebook-id', {
+     *   query: 'quantum computing research',
+     *   mode: ResearchMode.DEEP,  // Comprehensive search
+     *   timeout: 120000,  // Wait up to 2 minutes
+     *   onProgress: (status) => {
+     *     console.log(`Found ${status.resultCount} results so far...`);
+     *   },
+     * });
+     *
+     * // Validate results
+     * console.log(`Found ${result.web.length} web sources`);
+     * console.log(`Found ${result.drive.length} drive sources`);
+     *
+     * // User decides which to add (or add all)
+     * const topSources = result.web.slice(0, 10);  // Top 10
+     * await client.sources.add.web.addDiscovered('notebook-id', {
+     *   sessionId: result.sessionId,  // Required!
+     *   webSources: topSources,
+     * });
+     * ```
+     */
+    searchAndWait(notebookId: string, options: SearchWebAndWaitOptions): Promise<WebSearchResult>;
+    /**
+     * Get search results (STEP 2 of multi-step workflow - returns results for validation)
+     *
+     * **REQUIRES:** You must have a `sessionId` from `search()` (step 1) to use this method.
+     *
+     * **What it does:**
+     * - Returns discovered sources from a search session
+     * - Shows you what was found so you can validate/filter/select
+     * - Returns results immediately (doesn't wait - call multiple times to poll)
+     *
+     * **Multi-Step Workflow:**
+     * 1. `search()` → Returns `sessionId` (step 1)
+     * 2. `getResults(sessionId)` → Returns discovered sources (this method - step 2)
+     *    - **You can validate results here** - see what was found
+     *    - **You can filter/select** - decide which sources to add
+     *    - **You can call multiple times** - to poll for more results
+     * 3. `addDiscovered(sessionId, selectedSources)` → Add your selected sources (step 3)
+     *
+     * **Simple Alternative:**
+     * - Use `searchAndWait()` to combine steps 1-2 automatically
+     *
+     * **Usage Patterns:**
+     * - Call once after `search()` to get initial results
+     * - Call multiple times to poll for more results (results accumulate)
+     * - Filter results before passing to `addDiscovered()`
+     *
+     * @param notebookId - The notebook ID
+     * @param sessionId - Session ID from `search()` to filter results (optional - if omitted, returns all results)
+     * @returns Discovered sources (web and drive) for validation
+     *
+     * @example
+     * ```typescript
+     * // Step 1: Start search
+     * const sessionId = await client.sources.add.web.search('notebook-id', {
+     *   query: 'AI research',
+     * });
+     *
+     * // Step 2: Get results (can call multiple times to poll)
+     * let results;
+     * do {
+     *   await new Promise(r => setTimeout(r, 2000));  // Wait 2 seconds
+     *   results = await client.sources.add.web.getResults('notebook-id', sessionId);
+     *   console.log(`Found ${results.web.length} sources so far...`);
+     * } while (results.web.length === 0);
+     *
+     * // Validate and filter results
+     * const relevant = results.web.filter(s =>
+     *   s.title.includes('machine learning') ||
+     *   s.url.includes('arxiv.org')
+     * );
+     *
+     * // Step 3: Add selected sources
+     * await client.sources.add.web.addDiscovered('notebook-id', {
+     *   sessionId,
+     *   webSources: relevant,
+     * });
+     * ```
+     */
+    getResults(notebookId: string, sessionId?: string): Promise<{
+        web: DiscoveredWebSource[];
+        drive: DiscoveredDriveSource[];
+    }>;
+    /**
+     * Add discovered sources from search results (final step - adds your selected sources)
+     *
+     * **REQUIRES:** You must have a `sessionId` from `search()` or `searchAndWait()`.
+     *
+     * **What it does:**
+     * - Adds the sources you selected from search results
+     * - You decide which sources to add (from `getResults()` or `searchAndWait()`)
+     * - Returns array of added source IDs for validation
+     *
+     * **Workflow Patterns:**
+     *
+     * **Simple Pattern:**
+     * ```typescript
+     * const result = await client.sources.add.web.searchAndWait(...);
+     * const addedIds = await client.sources.add.web.addDiscovered('notebook-id', {
+     *   sessionId: result.sessionId,
+     *   webSources: result.web,  // Add all, or filter first
+     * });
+     * ```
+     *
+     * **Multi-Step Pattern:**
+     * ```typescript
+     * const sessionId = await client.sources.add.web.search(...);
+     * const results = await client.sources.add.web.getResults(..., sessionId);
+     * const selected = results.web.filter(...);  // Your selection logic
+     * const addedIds = await client.sources.add.web.addDiscovered('notebook-id', {
+     *   sessionId,
+     *   webSources: selected,
+     * });
+     * ```
+     *
+     * **Important:**
+     * - `sessionId` must match the one from your search (from `search()` or `searchAndWait()`)
+     * - You can add web sources, drive sources, or both
+     * - Returns source IDs so you can validate what was added
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Session ID and sources to add (web and/or drive)
+     * @returns Array of added source IDs (for validation)
+     *
+     * @example
+     * ```typescript
+     * // After searchAndWait() - add selected sources
+     * const result = await client.sources.add.web.searchAndWait('notebook-id', {
+     *   query: 'research papers',
+     * });
+     *
+     * // Validate results, then add top 5
+     * const top5 = result.web.slice(0, 5);
+     * const addedIds = await client.sources.add.web.addDiscovered('notebook-id', {
+     *   sessionId: result.sessionId,
+     *   webSources: top5,
+     * });
+     *
+     * console.log(`Added ${addedIds.length} sources:`, addedIds);
+     * ```
+     */
+    addDiscovered(notebookId: string, options: AddDiscoveredSourcesOptions): Promise<string[]>;
+}
+/**
+ * Add sources sub-service
+ * Handles adding sources of various types (URL, text, file, YouTube, Google Drive, batch)
+ */
+export declare class AddSourcesService {
+    private rpc;
+    private quota?;
+    readonly web: WebSearchService;
+    constructor(rpc: RPCClient, quota?: import("../utils/quota.js").QuotaManager | undefined);
+    private extractSourceId;
+    /**
+     * Add a URL source
+     */
+    url(notebookId: string, options: AddSourceFromURLOptions): Promise<string>;
+    /**
+     * Add a text source
+     */
+    text(notebookId: string, options: AddSourceFromTextOptions): Promise<string>;
+    /**
+     * Add a file source
+     */
+    file(notebookId: string, options: AddSourceFromFileOptions): Promise<string>;
+    /**
+     * Add a YouTube video source
+     */
+    youtube(notebookId: string, options: AddYouTubeSourceOptions): Promise<string>;
+    /**
+     * Add a Google Drive source
+     *
+     * @deprecated This method is deprecated. Use `batch()` with `type: 'gdrive'` instead.
+     */
+    drive(notebookId: string, options: AddGoogleDriveSourceOptions): Promise<string>;
+    /**
+     * Add multiple sources in a batch
+     */
+    batch(notebookId: string, options: BatchAddSourcesOptions): Promise<string[]>;
+    private isYouTubeURL;
+}
+/**
+ * Service for source operations
+ */
+export declare class SourcesService {
+    private rpc;
+    private quota?;
+    readonly add: AddSourcesService;
+    constructor(rpc: RPCClient, quota?: import("../utils/quota.js").QuotaManager | undefined);
+    /**
+     * List all sources in a notebook
+     *
+     * **What it does:** Retrieves a list of all sources (URLs, text, files, YouTube videos,
+     * Google Drive files, etc.) associated with a notebook.
+     *
+     * **Input:**
+     * - `notebookId` (string, required): The ID of the notebook to list sources from
+     *
+     * **Output:** Returns an array of `Source` objects, each containing:
+     * - `sourceId`: Unique identifier for the source
+     * - `title`: Source title/name
+     * - `type`: Source type (URL, TEXT, FILE, YOUTUBE_VIDEO, GOOGLE_DRIVE, etc.)
+     * - `url`: Source URL (for URL/YouTube sources)
+     * - `createdAt`: Creation timestamp
+     * - `updatedAt`: Last modified timestamp
+     * - `status`: Processing status (PROCESSING, READY, FAILED)
+     * - `metadata`: Additional metadata (file size, MIME type, etc.)
+     *
+     * **Note:**
+     * - Sources are extracted from the notebook response (same RPC as `notebooks.get()`)
+     * - This method efficiently reuses the notebook data without requiring a separate RPC call
+     * - Processing status is inferred from the source metadata
+     *
+     * @param notebookId - The notebook ID
+     *
+     * @example
+     * ```typescript
+     * // List all sources
+     * const sources = await client.sources.list('notebook-id');
+     * console.log(`Found ${sources.length} sources`);
+     *
+     * // Filter by type
+     * const pdfs = sources.filter(s => s.type === SourceType.FILE);
+     * const urls = sources.filter(s => s.type === SourceType.URL);
+     *
+     * // Check processing status
+     * const ready = sources.filter(s => s.status === SourceStatus.READY);
+     * const processing = sources.filter(s => s.status === SourceStatus.PROCESSING);
+     *
+     * // Get source details
+     * sources.forEach(source => {
+     *   console.log(`${source.title} (${source.type}) - ${source.status}`);
+     * });
+     * ```
+     */
+    list(notebookId: string): Promise<Source[]>;
+    /**
+     * Parse sources from notebook response
+     *
+     * Source structure in response:
+     * [
+     *   ["source-id"],
+     *   "filename.pdf",
+     *   [null, fileSize, [timestamp], ["processed-id", timestamp], type_code, null, 1],
+     *   [null, 2]
+     * ]
+     *
+     * Type codes:
+     * - 1 = Google Drive
+     * - 2 = Text
+     * - 3 = File/PDF
+     * - 4 = Text note
+     * - 5 = URL
+     * - 8 = Mind map note
+     * - 9 = YouTube
+     * - 10 = Video file
+     * - 13 = Image
+     * - 14 = PDF from Drive
+     */
+    private parseSourcesFromResponse;
+    /**
+     * Map type code from API response to SourceType enum
+     *
+     * **What this does:**
+     * The NotebookLM API returns sources with numeric type codes in the metadata array.
+     * This function converts those internal API codes to our public SourceType enum.
+     *
+     * **Where the type code comes from:**
+     * In the API response, each source has this structure:
+     * ```
+     * [
+     *   ["source-id"],                    // [0] = source ID
+     *   "filename.pdf",                   // [1] = title
+     *   [null, 602, [...], [...], 3, ...], // [2] = metadata array
+     *                                     //      [2][4] = type code (the number we map)
+     * ]
+     * ```
+     *
+     * **Type Code Examples from Real API Responses:**
+     * - `3` = PDF file: `["fnz offer.pdf", [null, 602, [...], [...], 3, ...]`
+     * - `5` = URL: `["AI SDK", [null, 571, [...], [...], 5, ..., ["https://ai-sdk.dev/"]]`
+     * - `9` = YouTube: `["Building an iMessage AI Chatbot", [null, 793, [...], [...], 9, [...]]`
+     * - `4` = Text note: `["A Pussycat's Discourse", [null, 1, [...], [...], 4, ...]`
+     * - `1` = Google Drive: `["offer_letter_photon", [[...], 492, [...], [...], 1, ...]`
+     * - `13` = Image: `["Screenshot 2025-12-28.png", [null, 0, [...], [...], 13, ...]`
+     *
+     * **Mapping:**
+     * Each API type code maps to a specific SourceType enum value to preserve the distinction
+     * between different file types (PDF, video, image, etc.).
+     *
+     * @param typeCode - The numeric type code from API response metadata[4]
+     * @returns The corresponding SourceType enum value
+     */
+    private mapTypeCodeToSourceType;
+    /**
+     * Get source(s) from a notebook
+     *
+     * **What it does:**
+     * - If `sourceId` is provided: Returns a single source by ID
+     * - If `sourceId` is not provided: Returns all sources (same as `list()`)
+     *
+     * **Input:**
+     * - `notebookId` (string, required): The notebook ID
+     * - `sourceId` (string, optional): The source ID to get. If omitted, returns all sources.
+     *
+     * **Output:**
+     * - If `sourceId` provided: Returns a single `Source` object
+     * - If `sourceId` omitted: Returns an array of `Source` objects
+     *
+     * @param notebookId - The notebook ID
+     * @param sourceId - Optional source ID to get a single source
+     *
+     * @example
+     * ```typescript
+     * // Get all sources
+     * const allSources = await client.sources.get('notebook-id');
+     *
+     * // Get a specific source
+     * const source = await client.sources.get('notebook-id', 'source-id');
+     * console.log(source.title);
+     * ```
+     */
+    get(notebookId: string, sourceId?: string): Promise<Source | Source[]>;
+    /**
+     * Add a source from URL
+     *
+     * WORKFLOW USAGE:
+     * - Returns immediately after source is queued (does not wait for processing)
+     * - Use pollProcessing() to check if source is ready
+     * - Or use workflow functions like addSourceAndWait() that handle waiting automatically
+     * - Automatically detects YouTube URLs and routes to addYouTube()
+     *
+     * @param notebookId - The notebook ID
+     * @param options - URL and optional title
+     *
+     * @example
+     * ```typescript
+     * // Add a regular URL
+     * const sourceId = await client.sources.addFromURL('notebook-id', {
+     *   url: 'https://example.com/article',
+     * });
+     *
+     * // Check if ready (manual polling)
+     * let status;
+     * do {
+     *   status = await client.sources.pollProcessing('notebook-id');
+     *   await new Promise(r => setTimeout(r, 2000));
+     * } while (!status.allReady);
+     * ```
+     */
+    addFromURL(notebookId: string, options: AddSourceFromURLOptions): Promise<string>;
+    /**
+     * Add a source from text (copied text)
+     *
+     * WORKFLOW USAGE:
+     * - Returns immediately after source is queued
+     * - Use pollProcessing() to check if source is ready
+     * - Or use workflow functions that handle waiting automatically
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Text content and title
+     *
+     * @example
+     * ```typescript
+     * const sourceId = await client.sources.addFromText('notebook-id', {
+     *   title: 'My Notes',
+     *   content: 'This is my research content...',
+     * });
+     * ```
+     */
+    addFromText(notebookId: string, options: AddSourceFromTextOptions): Promise<string>;
+    /**
+     * Add a source from uploaded file
+     *
+     * WORKFLOW USAGE:
+     * - Returns immediately after file is uploaded and queued
+     * - File processing may take longer than URLs/text
+     * - Use pollProcessing() to check if source is ready
+     * - Or use workflow functions that handle waiting automatically
+     *
+     * @param notebookId - The notebook ID
+     * @param options - File content, name, and MIME type
+     *
+     * @example
+     * ```typescript
+     * // From Buffer (Node.js)
+     * const fileBuffer = await fs.readFile('document.pdf');
+     * const sourceId = await client.sources.addFromFile('notebook-id', {
+     *   content: fileBuffer,
+     *   fileName: 'document.pdf',
+     *   mimeType: 'application/pdf',
+     * });
+     *
+     * // From base64 string
+     * const sourceId = await client.sources.addFromFile('notebook-id', {
+     *   content: base64String,
+     *   fileName: 'document.pdf',
+     * });
+     * ```
+     */
+    addFromFile(notebookId: string, options: AddSourceFromFileOptions): Promise<string>;
+    /**
+     * Add a YouTube video source
+     *
+     * WORKFLOW USAGE:
+     * - Returns immediately after source is queued
+     * - YouTube videos may take longer to process than URLs/text
+     * - Use pollProcessing() to check if source is ready
+     * - Or use workflow functions that handle waiting automatically
+     *
+     * @param notebookId - The notebook ID
+     * @param options - YouTube URL or video ID
+     *
+     * @example
+     * ```typescript
+     * // From YouTube URL
+     * const sourceId = await client.sources.addYouTube('notebook-id', {
+     *   urlOrId: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+     * });
+     *
+     * // From video ID
+     * const sourceId = await client.sources.addYouTube('notebook-id', {
+     *   urlOrId: 'dQw4w9WgXcQ',
+     * });
+     * ```
+     */
+    addYouTube(notebookId: string, options: AddYouTubeSourceOptions): Promise<string>;
+    /**
+     * Add a Google Drive source directly (by file ID)
+     *
+     * @deprecated This method is deprecated. Use `addBatch()` with `type: 'gdrive'` instead.
+     *
+     * WORKFLOW USAGE:
+     * - Returns immediately after source is queued
+     * - Use pollProcessing() to check if source is ready
+     * - Or use workflow functions that handle waiting automatically
+     * - For searching Drive files first, use searchWeb() with sourceType: GOOGLE_DRIVE
+     *
+     * **Note:** This method is deprecated. Use `addBatch()` with `type: 'gdrive'` instead.
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Google Drive file ID and optional metadata
+     *
+     * @example
+     * ```typescript
+     * // DEPRECATED: Use addBatch() instead
+     * const sourceId = await client.sources.addGoogleDrive('notebook-id', {
+     *   fileId: '1a2b3c4d5e6f7g8h9i0j',
+     *   mimeType: 'application/vnd.google-apps.document',
+     *   title: 'My Document',
+     * });
+     *
+     * // RECOMMENDED: Use addBatch() instead
+     * const sourceIds = await client.sources.addBatch('notebook-id', {
+     *   sources: [{
+     *     type: 'gdrive',
+     *     fileId: '1a2b3c4d5e6f7g8h9i0j',
+     *     mimeType: 'application/vnd.google-apps.document',
+     *     title: 'My Document',
+     *   }],
+     * });
+     * ```
+     *
+     * **Note:** For finding Drive files, use `searchWeb()` with `sourceType: SearchSourceType.GOOGLE_DRIVE`
+     * to search your Drive, then use `addDiscovered()` to add the found files.
+     */
+    addGoogleDrive(notebookId: string, options: AddGoogleDriveSourceOptions): Promise<string>;
+    /**
+     * Search web sources (initiate search, returns sessionId)
+     *
+     * **NOTE: For most use cases, use `searchWebAndWait()` instead, which handles the complete workflow automatically.**
+     *
+     * **IMPORTANT: This is STEP 1 of a 3-step sequential workflow.**
+     *
+     * You must complete the steps in order - you cannot skip to step 2 or 3 without completing step 1 first.
+     *
+     * **Complete Workflow (3 steps):**
+     * 1. `searchWeb()` → Returns `sessionId` (start here - this method)
+     * 2. `getSearchResults()` → Returns discovered sources (requires step 1)
+     * 3. `addDiscovered()` → Adds selected sources (requires sessionId from step 1)
+     *
+     * **Simplified Alternative (RECOMMENDED):**
+     * - Use `searchWebAndWait()` instead - it combines steps 1-2 with automatic polling
+     * - Then use `addDiscovered()` to add sources (step 3)
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Search options
+     * @returns sessionId - Required for steps 2 and 3
+     *
+     * @example
+     * ```typescript
+     * // STEP 1: Initiate search (you must start here)
+     * const sessionId = await client.sources.searchWeb('notebook-id', {
+     *   query: 'AI research',
+     *   sourceType: SearchSourceType.WEB,
+     *   mode: ResearchMode.FAST,
+     * });
+     *
+     * // STEP 2: Get results (requires sessionId from step 1)
+     * const results = await client.sources.getSearchResults('notebook-id');
+     *
+     * // STEP 3: Add selected sources (requires sessionId from step 1)
+     * const addedIds = await client.sources.addDiscovered('notebook-id', {
+     *   sessionId: sessionId,
+     *   webSources: results.web.slice(0, 5),
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Deep research (web sources only - DEEP mode not available for Drive)
+     * const sessionId = await client.sources.searchWeb('notebook-id', {
+     *   query: 'Machine learning',
+     *   mode: ResearchMode.DEEP, // Only for WEB sources
+     * });
+     *
+     * // Google Drive search (FAST mode only)
+     * const sessionId = await client.sources.searchWeb('notebook-id', {
+     *   query: 'presentation',
+     *   sourceType: SearchSourceType.GOOGLE_DRIVE, // FAST mode only
+     * });
+     * ```
+     */
+    searchWeb(notebookId: string, options: SearchWebSourcesOptions): Promise<string>;
+    /**
+     * Search web sources and wait for results (complete workflow)
+     *
+     * **RECOMMENDED METHOD** - Use this instead of `searchWeb()` + `getSearchResults()` manually.
+     *
+     * WORKFLOW USAGE:
+     * - This is a complete workflow that combines searchWeb() + getSearchResults() with polling
+     * - Returns results once they're available (or timeout)
+     * - Use the returned sessionId with addDiscovered() to add sources
+     * - This is the recommended method for web search workflows
+     * - Automatically filters results by sessionId to avoid mixing with previous searches
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Search options with waiting configuration
+     *
+     * @example
+     * ```typescript
+     * // Search and wait for results
+     * const result = await client.sources.searchWebAndWait('notebook-id', {
+     *   query: 'AI research',
+     *   mode: ResearchMode.DEEP,
+     *   timeout: 60000, // Wait up to 60 seconds
+     *   onProgress: (status) => {
+     *     console.log(`Has results: ${status.hasResults}, Count: ${status.resultCount}`);
+     *   },
+     * });
+     *
+     * // Then add selected sources
+     * const addedIds = await client.sources.addDiscovered('notebook-id', {
+     *   sessionId: result.sessionId,
+     *   webSources: result.web.slice(0, 5), // Add first 5
+     * });
+     * ```
+     */
+    searchWebAndWait(notebookId: string, options: SearchWebAndWaitOptions): Promise<WebSearchResult>;
+    /**
+     * Get search results (STEP 2 of 3-step workflow)
+     *
+     * **REQUIRES:** You must call `searchWeb()` first (step 1) before calling this method.
+     *
+     * This method retrieves the search results from a previously initiated search.
+     * The search was started by `searchWeb()` in step 1.
+     *
+     * **Complete Workflow (3 steps):**
+     * 1. `searchWeb()` → Returns `sessionId` (required first step)
+     * 2. `getSearchResults()` → Returns discovered sources (this method - step 2)
+     * 3. `addDiscovered()` → Adds selected sources (requires sessionId from step 1)
+     *
+     * **Note:** If you haven't called `searchWeb()` yet, you'll get empty results.
+     * Use `searchWebAndWait()` if you want to combine steps 1-2 automatically.
+     *
+     * **Filtering:** If `sessionId` is provided, only results from that session will be returned.
+     * Otherwise, results from all sessions will be returned (may include previous searches).
+     *
+     * @param notebookId - The notebook ID (must match the notebookId used in step 1)
+     * @param sessionId - Optional session ID to filter results to only this search session
+     * @returns Discovered sources (web and/or drive)
+     *
+     * @example
+     * ```typescript
+     * // STEP 1: Initiate search first
+     * const sessionId = await client.sources.searchWeb('notebook-id', { query: 'AI' });
+     *
+     * // STEP 2: Get results (only works after step 1)
+     * // Option 1: Get all results (may include previous searches)
+     * const results = await client.sources.getSearchResults('notebook-id');
+     *
+     * // Option 2: Get results only from current search (recommended)
+     * const results = await client.sources.getSearchResults('notebook-id', sessionId);
+     * console.log(`Found ${results.web.length} web sources and ${results.drive.length} drive sources`);
+     *
+     * // STEP 3: Add selected sources
+     * const addedIds = await client.sources.addDiscovered('notebook-id', {
+     *   sessionId: sessionId,
+     *   webSources: results.web,
+     * });
+     * ```
+     */
+    getSearchResults(notebookId: string, sessionId?: string): Promise<{
+        web: DiscoveredWebSource[];
+        drive: DiscoveredDriveSource[];
+    }>;
+    /**
+     * Add discovered sources from search results (STEP 3 of 3-step workflow)
+     *
+     * **REQUIRES:** You must have a `sessionId` from `searchWeb()` (step 1) to use this method.
+     *
+     * This is the final step - it adds the selected discovered sources to your notebook.
+     *
+     * **Complete Workflow (3 steps):**
+     * 1. `searchWeb()` → Returns `sessionId` (required first step)
+     * 2. `getSearchResults()` → Returns discovered sources (optional - if you need to filter/select)
+     * 3. `addDiscovered()` → Adds selected sources (this method - final step)
+     *
+     * **Simplified Alternative:**
+     * - Use `searchWebAndWait()` to combine steps 1-2, then use this method for step 3
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Session ID (from step 1) and sources to add
+     * @returns Array of added source IDs
+     *
+     * @example
+     * ```typescript
+     * // Option 1: Complete 3-step workflow
+     * const sessionId = await client.sources.searchWeb('notebook-id', {
+     *   query: 'AI research',
+     *   mode: ResearchMode.DEEP,
+     * });
+     * const results = await client.sources.getSearchResults('notebook-id');
+     * const addedIds = await client.sources.addDiscovered('notebook-id', {
+     *   sessionId: sessionId, // Required: from step 1
+     *   webSources: results.web.slice(0, 5), // Add first 5 web sources
+     * });
+     *
+     * // Option 2: Simplified workflow (recommended)
+     * const result = await client.sources.searchWebAndWait('notebook-id', {
+     *   query: 'AI research',
+     *   mode: ResearchMode.DEEP,
+     * });
+     * const addedIds = await client.sources.addDiscovered('notebook-id', {
+     *   sessionId: result.sessionId, // From searchWebAndWait
+     *   webSources: result.web.slice(0, 5),
+     *   driveSources: result.drive.slice(0, 2), // Can also add Drive sources
+     * });
+     * ```
+     */
+    addDiscovered(notebookId: string, options: AddDiscoveredSourcesOptions): Promise<string[]>;
+    /**
+     * Add multiple sources in batch
+     *
+     * WORKFLOW USAGE:
+     * - Efficiently adds multiple sources of different types in one call
+     * - All source types are supported EXCEPT web sources (which come from search)
+     * - Optionally waits for all sources to be processed
+     * - Use this for adding multiple sources at once instead of individual calls
+     * - All sources are added in parallel (server-side)
+     *
+     * **Supported Source Types:**
+     * - `url` - Regular URLs (via `addFromURL()`)
+     * - `text` - Text content (via `addFromText()`)
+     * - `file` - File uploads (via `addFromFile()`)
+     * - `youtube` - YouTube videos (via `addYouTube()`)
+     * - `gdrive` - Google Drive files (via `addGoogleDrive()`)
+     *
+     * **NOT Supported:**
+     * - Web sources from search - Use `searchWebAndWait()` + `addDiscovered()` instead
+     *
+     * @param notebookId - The notebook ID
+     * @param options - Batch addition options
+     * @returns Array of source IDs for all added sources
+     *
+     * @example
+     * ```typescript
+     * // Add multiple sources without waiting
+     * const sourceIds = await client.sources.addBatch('notebook-id', {
+     *   sources: [
+     *     { type: 'url', url: 'https://example.com/article1' },
+     *     { type: 'url', url: 'https://example.com/article2' },
+     *     { type: 'text', title: 'Notes', content: 'My research notes...' },
+     *     { type: 'youtube', urlOrId: 'https://youtube.com/watch?v=...' },
+     *     { type: 'gdrive', fileId: '1a2b3c4d5e6f7g8h9i0j', mimeType: 'application/pdf' },
+     *   ],
+     * });
+     *
+     * // Add and wait for processing
+     * const sourceIds = await client.sources.addBatch('notebook-id', {
+     *   sources: [
+     *     { type: 'url', url: 'https://example.com/article' },
+     *     { type: 'text', title: 'Notes', content: 'Content...' },
+     *   ],
+     *   waitForProcessing: true,
+     *   timeout: 300000, // 5 minutes
+     *   onProgress: (ready, total) => {
+     *     console.log(`${ready}/${total} sources ready`);
+     *   },
+     * });
+     * ```
+     */
+    addBatch(notebookId: string, options: BatchAddSourcesOptions): Promise<string[]>;
+    /**
+     * Delete a source from a notebook
+     *
+     * WORKFLOW USAGE:
+     * - Permanently removes a source from the notebook
+     * - This action cannot be undone
+     * - To delete multiple sources, call this method multiple times
+     *
+     * @param notebookId - The notebook ID
+     * @param sourceId - The source ID to delete
+     *
+     * @example
+     * ```typescript
+     * // Delete a single source
+     * await client.sources.delete('notebook-id', 'source-id-123');
+     *
+     * // Delete multiple sources (call multiple times)
+     * await client.sources.delete('notebook-id', 'source-id-1');
+     * await client.sources.delete('notebook-id', 'source-id-2');
+     * await client.sources.delete('notebook-id', 'source-id-3');
+     * ```
+     */
+    delete(notebookId: string, sourceId: string): Promise<void>;
+    /**
+     * Update source metadata
+     *
+     * WORKFLOW USAGE:
+     * - Updates source properties like title, metadata, etc.
+     * - This updates the source information, not the content itself
+     * - Returns immediately (no waiting required)
+     *
+     * **Common Updates:**
+     * - `title` - Change the source title/name
+     * - `metadata` - Update custom metadata
+     * - Other source properties as defined in the Source interface
+     *
+     * @param notebookId - The notebook ID
+     * @param sourceId - The source ID to update
+     * @param updates - Partial Source object with fields to update
+     *
+     * @example
+     * ```typescript
+     * // Update source title
+     * await client.sources.update('notebook-id', 'source-id', {
+     *   title: 'Updated Source Title',
+     * });
+     *
+     * // Update metadata
+     * await client.sources.update('notebook-id', 'source-id', {
+     *   metadata: {
+     *     category: 'research',
+     *     priority: 'high',
+     *   },
+     * });
+     * ```
+     */
+    update(notebookId: string, sourceId: string, updates: Partial<Source>): Promise<void>;
+    /**
+     * Poll source processing status
+     *
+     * WORKFLOW USAGE:
+     * - Call this repeatedly to check if sources are ready
+     * - Use in loops with setTimeout for manual polling
+     * - Or use workflow functions that handle polling automatically
+     * - This is a single check - does not wait or retry
+     *
+     * @param notebookId - The notebook ID
+     *
+     * @example
+     * ```typescript
+     * // Manual polling
+     * let status;
+     * do {
+     *   status = await client.sources.pollProcessing('notebook-id');
+     *   if (!status.allReady) {
+     *     await new Promise(r => setTimeout(r, 2000)); // Wait 2s
+     *   }
+     * } while (!status.allReady);
+     * ```
+     */
+    /**
+     * Get source processing status
+     *
+     * **What it does:** Checks the processing status of all sources in a notebook.
+     * Returns information about which sources are still processing and whether all sources are ready.
+     *
+     * **Input:**
+     * - `notebookId` (string, required): The notebook ID
+     *
+     * **Output:** Returns a `SourceProcessingStatus` object containing:
+     * - `allReady` (boolean): Whether all sources are ready
+     * - `processing` (string[]): Array of source IDs that are still processing
+     *
+     * @param notebookId - The notebook ID
+     *
+     * @example
+     * ```typescript
+     * // Check processing status
+     * const status = await client.sources.status('notebook-id');
+     *
+     * if (status.allReady) {
+     *   console.log('All sources are ready!');
+     * } else {
+     *   console.log(`Still processing: ${status.processing.length} sources`);
+     *   console.log('Processing IDs:', status.processing);
+     * }
+     * ```
+     */
+    status(notebookId: string): Promise<SourceProcessingStatus>;
+    /**
+     * Select/prepare source for viewing
+     *
+     * @deprecated This method is deprecated. It's only used with loadContent(),
+     * which is also deprecated due to "Service unavailable" errors.
+     *
+     * WORKFLOW USAGE:
+     * - REQUIRED: Must call this before loadContent() for reliable content loading
+     * - NotebookLM requires sources to be selected before they can be loaded
+     * - Use in sequence: selectSource() → loadContent()
+     *
+     * @param sourceId - The source ID
+     *
+     * @example
+     * ```typescript
+     * // REQUIRED: select first, then load
+     * await client.sources.selectSource('source-id');
+     * const content = await client.sources.loadContent('source-id');
+     * console.log(content.text);
+     * ```
+     */
+    selectSource(sourceId: string): Promise<void>;
+    /**
+     * Load source content
+     *
+     * @deprecated This method is deprecated and may not work reliably.
+     * The API endpoint returns "Service unavailable" errors.
+     *
+     * WORKFLOW USAGE:
+     * - REQUIRED: Must call selectSource() first before calling this method
+     * - Returns full text content of the source
+     * - Use this to read source content after it's ready
+     *
+     * @param sourceId - The source ID
+     *
+     * @example
+     * ```typescript
+     * // REQUIRED: select first, then load
+     * await client.sources.selectSource('source-id');
+     * const content = await client.sources.loadContent('source-id');
+     * console.log(content.text);
+     * ```
+     */
+    loadContent(sourceId: string): Promise<SourceContent>;
+    /**
+     * Check source freshness
+     *
+     * @deprecated This method is deprecated and may not work reliably.
+     * The API endpoint returns "Service unavailable" errors.
+     *
+     * WORKFLOW USAGE:
+     * - Use this to check if source content is up-to-date
+     * - Can be used before refresh() to determine if refresh is needed
+     *
+     * @param sourceId - The source ID
+     */
+    checkFreshness(sourceId: string): Promise<SourceFreshness>;
+    /**
+     * Add deep research report as a source
+     *
+     * @deprecated This method is deprecated and may not work reliably.
+     * The API endpoint may return "Service unavailable" errors.
+     *
+     * WORKFLOW USAGE:
+     * - Creates an AI-generated deep research report on a topic and adds it as a source
+     * - Monthly quota limit: 10 reports per month
+     * - Returns immediately after research is queued
+     * - Use `pollProcessing()` to check when the research report is ready
+     * - Once ready, the report appears as a source in your notebook
+     *
+     * **Important Notes:**
+     * - This is DIFFERENT from `searchWeb()` with `ResearchMode.DEEP`
+     *   - `searchWeb(..., mode: ResearchMode.DEEP)` - Searches web and finds relevant sources
+     *   - `addDeepResearch()` - Creates a complete research report as a source itself
+     * - Monthly limit: 10 reports per month (enforced by quota system)
+     * - The generated report becomes a source that can be used for chat, artifacts, etc.
+     * - Processing can take several minutes for comprehensive research
+     *
+     * **Use Cases:**
+     * - Need a comprehensive research report on a complex topic
+     * - Want AI-generated analysis compiled into a single source
+     * - Starting research on a new domain and need foundational content
+     *
+     * @param notebookId - The notebook ID
+     * @param query - Research query/question (what you want researched)
+     * @returns Source ID of the generated research report
+     *
+     * @example
+     * ```typescript
+     * // Create a deep research report
+     * const sourceId = await client.sources.addDeepResearch('notebook-id',
+     *   'Latest developments in quantum computing and their applications'
+     * );
+     *
+     * // Wait for research report to be ready
+     * let status;
+     * do {
+     *   status = await client.sources.pollProcessing('notebook-id');
+     *   if (!status.allReady) {
+     *     console.log('Research report still being generated...');
+     *     await new Promise(r => setTimeout(r, 5000)); // Wait 5s between checks
+     *   }
+     * } while (!status.allReady);
+     *
+     * console.log(`Research report ready! Source ID: ${sourceId}`);
+     * ```
+     */
+    addDeepResearch(notebookId: string, query: string): Promise<string>;
+    /**
+     * Act on multiple sources (bulk action)
+     *
+     * @deprecated This method is deprecated and may not work reliably.
+     * The RPC endpoint returns "Service unavailable" errors.
+     *
+     * WORKFLOW USAGE:
+     * - Use this for bulk operations on multiple sources
+     * - Different from update() which works on a single source
+     * - Supports various AI-powered content transformation actions
+     *
+     * **Note:** This method is deprecated due to API reliability issues.
+     * Consider using artifact creation methods (e.g., `sdk.artifacts.create()`)
+     * for similar functionality.
+     *
+     * @param notebookId - The notebook ID
+     * @param action - Action to perform (see supported actions below)
+     * @param sourceIds - Array of source IDs to act on
+     *
+     * @example
+     * ```typescript
+     * // Rephrase content from multiple sources
+     * await client.sources.actOn('notebook-id', 'rephrase', ['source-1', 'source-2']);
+     *
+     * // Generate study guide from sources
+     * await client.sources.actOn('notebook-id', 'study_guide', ['source-1']);
+     *
+     * // Create interactive mindmap
+     * await client.sources.actOn('notebook-id', 'interactive_mindmap', ['source-1', 'source-2']);
+     * ```
+     *
+     * **Supported Actions:**
+     * - `rephrase` - Rephrase content from sources
+     * - `expand` - Expand content from sources
+     * - `summarize` - Summarize content from sources
+     * - `critique` - Critique content from sources
+     * - `brainstorm` - Brainstorm ideas from sources
+     * - `verify` - Verify information from sources
+     * - `explain` - Explain concepts from sources
+     * - `outline` - Create outline from sources
+     * - `study_guide` - Generate study guide from sources
+     * - `faq` - Generate FAQ from sources
+     * - `briefing_doc` - Create briefing document from sources
+     * - `interactive_mindmap` - Generate interactive mindmap from sources
+     * - `timeline` - Create timeline from sources
+     * - `table_of_contents` - Generate table of contents from sources
+     */
+    actOn(notebookId: string, action: string, sourceIds: string[]): Promise<void>;
+    private isYouTubeURL;
+    private extractYouTubeVideoId;
+    private extractSourceId;
+}
+//# sourceMappingURL=sources.d.ts.map