notebooklm-kit 0.0.1 → 2.1.1

package/dist/src/client/notebooklm-client.d.ts

@@ -0,0 +1,372 @@
+/**
+ * Main NotebookLM Client
+ * Provides high-level interface for NotebookLM operations
+ */
+import { RPCClient } from '../rpc/rpc-client.js';
+import { NotebooksService } from '../services/notebooks.js';
+import { SourcesService } from '../services/sources.js';
+import { NotesService } from '../services/notes.js';
+import { ArtifactsService } from '../services/artifacts.js';
+import { GenerationService } from '../services/generation.js';
+import { NotebookLanguageService } from '../services/notebook-language.js';
+import { AutoRefreshManager } from '../auth/refresh.js';
+import { QuotaManager } from '../utils/quota.js';
+import type { NotebookLMConfig } from '../types/common.js';
+/**
+ * NotebookLM Client
+ *
+ * Main entry point for interacting with Google NotebookLM API.
+ * Provides a simple, organized interface to all NotebookLM features.
+ *
+ * **Features:**
+ * - **Notebooks:** Create, list, update, delete notebooks
+ * - **Sources:** Add URLs, text, files, YouTube videos, Google Drive files, web search
+ * - **Notes:** Create and manage notes within notebooks
+ * - **Artifacts:** Generate quizzes, flashcards, study guides, mind maps, infographics, slides, reports, audio, video
+ * - **Generation:** Chat with notebooks, generate guides, outlines, and reports
+ * - **Auto-Refresh:** Automatically keeps sessions alive (enabled by default)
+ * - **Quota Management:** Tracks and enforces NotebookLM usage limits
+ *
+ * **Usage:**
+ * ```typescript
+ * const sdk = new NotebookLMClient({
+ *   authToken: process.env.NOTEBOOKLM_AUTH_TOKEN!,
+ *   cookies: process.env.NOTEBOOKLM_COOKIES!,
+ * });
+ *
+ * // Access services
+ * const notebooks = await sdk.notebooks.list();
+ * const notebook = await sdk.notebooks.create({ title: 'My Research' });
+ * await sdk.sources.addFromURL(notebook.projectId, { url: 'https://example.com' });
+ * const response = await sdk.generation.chat(notebook.projectId, 'Summarize this');
+ * ```
+ *
+ * **Service Organization:**
+ * - `sdk.notebooks` - Notebook/project operations
+ * - `sdk.sources` - Source management (URLs, files, YouTube, Drive, web search)
+ * - `sdk.notes` - Note operations
+ * - `sdk.artifacts` - Artifact creation and management
+ * - `sdk.generation` - Chat and content generation
+ *
+ * **Auto-Refresh:**
+ * Credentials are automatically refreshed every 10 minutes (configurable) to keep sessions alive.
+ * Set `autoRefresh: false` to disable, or customize with `autoRefresh: { interval: 5 * 60 * 1000 }`.
+ *
+ * **Quota Management:**
+ * The SDK automatically tracks and enforces NotebookLM limits (100 notebooks, 50 chats/day, etc.).
+ * Use `sdk.getUsage()` to check current usage and `sdk.getRemaining('chats')` for remaining quota.
+ *
+ * **Cleanup:**
+ * Always call `sdk.dispose()` when done to stop auto-refresh and clean up resources.
+ */
+export declare class NotebookLMClient {
+    private rpcClient?;
+    private refreshManager?;
+    private quotaManager;
+    private config;
+    private credentials?;
+    private initialized;
+    private _notebooks?;
+    private _sources?;
+    private _notes?;
+    private _artifacts?;
+    private _generation?;
+    private _notebookLanguage?;
+    /**
+     * Notebook operations
+     * Create, list, get, update, delete notebooks
+     *
+     * @example
+     * ```typescript
+     * const notebooks = await sdk.notebooks.list();
+     * const notebook = await sdk.notebooks.create({ title: 'Research', emoji: '📚' });
+     * await sdk.notebooks.update(notebook.projectId, { title: 'Updated Title' });
+     * ```
+     */
+    get notebooks(): NotebooksService;
+    /**
+     * Source operations
+     * Add sources from URLs, text, files, YouTube, Google Drive, web search
+     *
+     * @example
+     * ```typescript
+     * await sdk.sources.addFromURL('notebook-id', { url: 'https://example.com' });
+     * await sdk.sources.addFromText('notebook-id', { title: 'Notes', content: '...' });
+     * await sdk.sources.addYouTube('notebook-id', { urlOrId: 'video-id' });
+     * ```
+     */
+    get sources(): SourcesService;
+    /**
+     * Note operations
+     * Create, list, update, delete notes within notebooks
+     *
+     * @example
+     * ```typescript
+     * const notes = await sdk.notes.list('notebook-id');
+     * const note = await sdk.notes.create('notebook-id', { title: 'Note', content: '...' });
+     * ```
+     */
+    get notes(): NotesService;
+    /**
+     * Artifact operations
+     * Create and manage artifacts: quizzes, flashcards, study guides, mind maps,
+     * infographics, slide decks, reports, audio overviews, video overviews
+     *
+     * @example
+     * ```typescript
+     * const quiz = await sdk.artifacts.create('notebook-id', ArtifactType.QUIZ, {
+     *   instructions: 'Create 10 questions',
+     * });
+     * const audio = await sdk.artifacts.create('notebook-id', ArtifactType.AUDIO, {
+     *   instructions: 'Focus on key findings',
+     * });
+     * ```
+     */
+    get artifacts(): ArtifactsService;
+    /**
+     * Generation operations
+     * Chat with notebooks, generate guides, outlines, reports
+     *
+     * @example
+     * ```typescript
+     * const response = await sdk.generation.chat('notebook-id', 'What are the key findings?');
+     * const guide = await sdk.generation.generateNotebookGuide('notebook-id');
+     * ```
+     */
+    get generation(): GenerationService;
+    /**
+     * Notebook language operations
+     * Get and set the notebook's default output language
+     *
+     * The notebook's default output language is used as the default for:
+     * - Artifact creation (audio, video, report, infographics, slide decks)
+     * - Chat responses
+     * - All other notebook operations
+     *
+     * @example
+     * ```typescript
+     * import { NotebookLMLanguage } from 'notebooklm-kit';
+     *
+     * // Get current default language
+     * const language = await sdk.notebookLanguage.get('notebook-id');
+     *
+     * // Set default language to German
+     * await sdk.notebookLanguage.set('notebook-id', NotebookLMLanguage.GERMAN);
+     *
+     * // Now all artifacts will default to German unless overridden
+     * const quiz = await sdk.artifacts.create('notebook-id', ArtifactType.QUIZ, {
+     *   // language will default to German
+     * });
+     * ```
+     */
+    get notebookLanguage(): NotebookLanguageService;
+    /**
+     * Create a new NotebookLM client
+     *
+     * **Auto-Refresh Configuration:**
+     *
+     * The SDK automatically keeps your session alive by refreshing credentials periodically.
+     * This prevents session expiration during long-running operations.
+     *
+     * - **Default behavior:** Auto-refresh is enabled by default with a 10-minute interval
+     * - **Custom interval:** Set `autoRefresh: { enabled: true, interval: 5 * 60 * 1000 }` for 5 minutes
+     * - **Disable:** Set `autoRefresh: false` to disable automatic refresh
+     * - **Initial refresh:** Credentials are refreshed immediately when the client is created
+     * - **Background refresh:** Subsequent refreshes happen automatically at the configured interval
+     *
+     * **Refresh Intervals:**
+     * - Recommended: 5-10 minutes (300,000 - 600,000 ms)
+     * - Minimum: 1 minute (60,000 ms) - not recommended as it may be too frequent
+     * - Maximum: 30 minutes (1,800,000 ms) - sessions may expire before refresh
+     *
+     * **Example configurations:**
+     * ```typescript
+     * // Default: Auto-refresh enabled, 10-minute interval
+     * const client = new NotebookLMClient({
+     *   authToken: '...',
+     *   cookies: '...',
+     * });
+     *
+     * // Custom 5-minute interval
+     * const client = new NotebookLMClient({
+     *   authToken: '...',
+     *   cookies: '...',
+     *   autoRefresh: {
+     *     enabled: true,
+     *     interval: 5 * 60 * 1000, // 5 minutes
+     *   },
+     * });
+     *
+     * // Disable auto-refresh
+     * const client = new NotebookLMClient({
+     *   authToken: '...',
+     *   cookies: '...',
+     *   autoRefresh: false,
+     * });
+     * ```
+     *
+     * @param config - Client configuration
+     *
+     * @example
+     * ```typescript
+     * const client = new NotebookLMClient({
+     *   authToken: process.env.NOTEBOOKLM_AUTH_TOKEN!,
+     *   cookies: process.env.NOTEBOOKLM_COOKIES!,
+     * });
+     *
+     * const notebooks = await client.notebooks.list();
+     * ```
+     */
+    constructor(config?: NotebookLMConfig);
+    /**
+     * Connect / Initialize the client
+     * Loads credentials (from config, env, saved, or auto-login) and sets up services
+     * This must be called before using any services
+     *
+     * @example
+     * ```typescript
+     * const sdk = new NotebookLMClient({});
+     * await sdk.connect();
+     * const notebooks = await sdk.notebooks.list();
+     * ```
+     */
+    connect(): Promise<void>;
+    /**
+     * Ensure client is connected (called before operations)
+     */
+    private ensureConnected;
+    /**
+     * Get RPC client (ensures connection)
+     */
+    private getRPCClientInternal;
+    /**
+     * Get the underlying RPC client
+     * For advanced use cases where you need direct RPC access
+     *
+     * @returns The RPC client instance
+     */
+    getRPCClient(): Promise<RPCClient>;
+    /**
+     * Execute a raw RPC call
+     * For advanced use cases where you need to call an RPC method directly
+     *
+     * @param rpcId - The RPC method ID (e.g., from RPCMethods)
+     * @param args - Arguments for the RPC call
+     * @param notebookId - Optional notebook ID for context
+     * @returns The RPC response
+     *
+     * @example
+     * ```typescript
+     * import { RPCMethods } from 'notebooklm-kit';
+     *
+     * const response = await sdk.rpc(
+     *   RPCMethods.RPC_LIST_PROJECTS,
+     *   []
+     * );
+     * ```
+     */
+    rpc(rpcId: string, args: any[], notebookId?: string): Promise<any>;
+    /**
+     * Get the refresh manager (if auto-refresh is enabled)
+     *
+     * @returns The auto-refresh manager, or undefined if disabled
+     */
+    getRefreshManager(): AutoRefreshManager | undefined;
+    /**
+     * Manually refresh credentials
+     * Useful for keeping long-running sessions alive or testing refresh functionality
+     *
+     * @throws Error if auto-refresh is not enabled
+     *
+     * @example
+     * ```typescript
+     * // Manual refresh
+     * await sdk.refreshCredentials();
+     *
+     * // Check if refresh is running
+     * const manager = sdk.getRefreshManager();
+     * if (manager?.isRunning()) {
+     *   console.log('Auto-refresh is active');
+     * }
+     * ```
+     */
+    refreshCredentials(): Promise<void>;
+    /**
+     * Get quota manager
+     * For advanced quota management and custom tracking
+     *
+     * @returns The quota manager instance
+     */
+    getQuotaManager(): QuotaManager;
+    /**
+     * Get current usage statistics
+     * Returns daily and monthly usage for all tracked resources
+     *
+     * @returns Usage data including daily chats, audio, video, artifacts, etc.
+     *
+     * @example
+     * ```typescript
+     * const usage = sdk.getUsage();
+     * console.log(`Chats: ${usage.daily.chats}/50`);
+     * console.log(`Audio: ${usage.daily.audioOverviews}/3`);
+     * console.log(`Video: ${usage.daily.videoOverviews}/3`);
+     * console.log(`Quizzes: ${usage.daily.quizzes}/10`);
+     * console.log(`Flashcards: ${usage.daily.flashcards}/10`);
+     * console.log(`Reports: ${usage.daily.reports}/10`);
+     * console.log(`Notebooks: ${usage.notebooks.total}/100`);
+     * ```
+     */
+    getUsage(): import("../utils/quota.js").UsageData;
+    /**
+     * Get remaining quota for a resource
+     *
+     * @param resource - Resource name: 'chats', 'audioOverviews', 'videoOverviews',
+     *                   'quizzes', 'flashcards', 'reports', 'createNotebook', etc.
+     * @returns Number of remaining uses for the resource
+     *
+     * @example
+     * ```typescript
+     * const remainingChats = sdk.getRemaining('chats');
+     * const remainingAudio = sdk.getRemaining('audioOverviews');
+     *
+     * console.log(`${remainingChats} chats remaining today`);
+     * console.log(`${remainingAudio} audio overviews remaining today`);
+     *
+     * if (remainingChats === 0) {
+     *   console.log('Daily chat limit reached');
+     * }
+     * ```
+     */
+    getRemaining(resource: string): number;
+    /**
+     * Dispose of the client and stop auto-refresh
+     * Call this when you're done with the client to clean up resources.
+     * This stops the background auto-refresh timer.
+     *
+     * @example
+     * ```typescript
+     * const sdk = new NotebookLMClient({ ... });
+     * await sdk.connect();
+     *
+     * // Use the client...
+     * await sdk.notebooks.list();
+     *
+     * // Clean up when done
+     * sdk.dispose();
+     * ```
+     */
+    dispose(): void;
+}
+/**
+ * Create a NotebookLM client with environment variables
+ * Reads NOTEBOOKLM_AUTH_TOKEN and NOTEBOOKLM_COOKIES from environment
+ * Note: Only works in Node.js environment
+ *
+ * @example
+ * ```typescript
+ * const client = createNotebookLMClient();
+ * const notebooks = await client.notebooks.list();
+ * ```
+ */
+export declare function createNotebookLMClient(config?: Partial<NotebookLMConfig>): NotebookLMClient;
+//# sourceMappingURL=notebooklm-client.d.ts.map

package/dist/src/client/notebooklm-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notebooklm-client.d.ts","sourceRoot":"","sources":["../../../src/client/notebooklm-client.ts"],"names":[],"mappings":"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"}