notebooklm-api 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,134 @@
+/**
+ * NotebookLM Client
+ *
+ * Main entry point for interacting with Google NotebookLM.
+ */
+import { AuthTokens } from './auth.ts';
+import { NotebooksAPI } from './api/notebooks.ts';
+import { SourcesAPI } from './api/sources.ts';
+import { ChatAPI } from './api/chat.ts';
+import { ArtifactsAPI } from './api/artifacts.ts';
+import { ResearchAPI } from './api/research.ts';
+import { NotesAPI } from './api/notes.ts';
+/**
+ * Main client for NotebookLM API.
+ *
+ * Provides access to NotebookLM functionality through namespaced sub-clients:
+ * - `notebooks` - Notebook management
+ * - `sources` - Source document management
+ * - `chat` - Conversational AI interactions
+ * - `artifacts` - AI-generated content (audio, video, reports, etc.)
+ * - `research` - Web and Drive research
+ * - `notes` - User notes management
+ *
+ * @example
+ * ```typescript
+ * const client = await NotebookLMClient.fromStorage();
+ *
+ * // List notebooks
+ * const notebooks = await client.notebooks.list();
+ *
+ * // Create a notebook
+ * const nb = await client.notebooks.create("My Research");
+ *
+ * // Add a source
+ * const source = await client.sources.addUrl(nb.id, "https://example.com");
+ *
+ * // Ask a question
+ * const result = await client.chat.ask(nb.id, "Summarize this content");
+ * console.log(result.answer);
+ *
+ * // Generate audio overview
+ * const status = await client.artifacts.generateAudio(nb.id);
+ * await client.artifacts.waitForGeneration(nb.id, status.artifactId);
+ * ```
+ */
+export declare class NotebookLMClient {
+    private core;
+    /**
+     * Notebook management API
+     */
+    readonly notebooks: NotebooksAPI;
+    /**
+     * Source document management API
+     */
+    readonly sources: SourcesAPI;
+    /**
+     * Conversational AI API
+     */
+    readonly chat: ChatAPI;
+    /**
+     * AI-generated content API
+     */
+    readonly artifacts: ArtifactsAPI;
+    /**
+     * Web and Drive research API
+     */
+    readonly research: ResearchAPI;
+    /**
+     * User notes management API
+     */
+    readonly notes: NotesAPI;
+    /**
+     * Creates a new NotebookLMClient instance.
+     *
+     * Prefer using `fromStorage()` for most use cases.
+     *
+     * @param auth - Authentication tokens
+     */
+    constructor(auth: AuthTokens);
+    /**
+     * Creates a NotebookLMClient from a Playwright storage state file.
+     *
+     * This is the recommended way to create a client after running
+     * `notebooklm login` to authenticate.
+     *
+     * @param storagePath - Path to storage state file (optional, uses default if not specified)
+     * @returns Promise resolving to a configured client
+     *
+     * @example
+     * ```typescript
+     * // Use default storage path (~/.notebooklm/storage-state.json)
+     * const client = await NotebookLMClient.fromStorage();
+     *
+     * // Use custom storage path
+     * const client = await NotebookLMClient.fromStorage('/path/to/storage.json');
+     * ```
+     */
+    static fromStorage(storagePath?: string): Promise<NotebookLMClient>;
+    /**
+     * Refreshes authentication tokens.
+     *
+     * Call this if you encounter "Session Expired" errors. The client
+     * will automatically attempt to refresh on auth errors, but you
+     * can call this proactively.
+     *
+     * @example
+     * ```typescript
+     * // Proactively refresh before a long operation
+     * await client.refreshAuth();
+     * ```
+     */
+    refreshAuth(): Promise<void>;
+    /**
+     * Gets the current authentication tokens.
+     *
+     * Useful for debugging or saving state.
+     */
+    getAuth(): AuthTokens;
+    /**
+     * Checks if the client is authenticated.
+     */
+    isAuthenticated(): boolean;
+}
+/**
+ * Creates a NotebookLMClient using the async context manager pattern.
+ *
+ * @example
+ * ```typescript
+ * await using client = await createClient();
+ * const notebooks = await client.notebooks.list();
+ * ```
+ */
+export declare function createClient(storagePath?: string): Promise<NotebookLMClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAK1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAa;IAEzB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAEzB;;;;;;OAMG;gBACS,IAAI,EAAE,UAAU;IAc5B;;;;;;;;;;;;;;;;;OAiBG;WACU,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAOzE;;;;;;;;;;;;OAYG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC;;;;OAIG;IACH,OAAO,IAAI,UAAU;IAIrB;;OAEG;IACH,eAAe,IAAI,OAAO;CAG3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAE3B"}

package/dist/core.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Core Client Implementation for NotebookLM API
+ *
+ * Handles HTTP communication, RPC encoding/decoding, and authentication.
+ */
+import { AuthTokens } from './auth.ts';
+import { type RPCMethod, type RPCParams } from './rpc/types.ts';
+import type { ConversationTurn } from './types.ts';
+/**
+ * Core client for NotebookLM API communication.
+ *
+ * This is an internal component used by higher-level sub-client APIs.
+ */
+export declare class ClientCore {
+    private auth;
+    private refreshLock;
+    private conversationCache;
+    constructor(auth: AuthTokens);
+    /**
+     * Gets the current auth tokens.
+     */
+    getAuth(): AuthTokens;
+    /**
+     * Executes an RPC call to the NotebookLM API.
+     *
+     * @param method - The RPC method to call
+     * @param params - Parameters for the RPC call
+     * @param retryOnAuthError - Whether to retry on auth failure
+     * @returns The decoded response data
+     */
+    rpcCall(method: RPCMethod, params: RPCParams, retryOnAuthError?: boolean): Promise<unknown>;
+    /**
+     * Refreshes authentication tokens.
+     *
+     * Uses a lock to ensure only one refresh runs at a time.
+     */
+    refreshAuth(): Promise<void>;
+    /**
+     * Uploads a file to NotebookLM.
+     *
+     * Uses Google's resumable upload protocol.
+     */
+    uploadFile(notebookId: string, filename: string, content: Uint8Array, contentType: string): Promise<string>;
+    /**
+     * Downloads content from a URL with authentication.
+     */
+    download(url: string): Promise<Response>;
+    /**
+     * Gets cached conversation turns for a conversation ID.
+     */
+    getCachedTurns(conversationId: string): ConversationTurn[];
+    /**
+     * Adds a turn to the conversation cache.
+     */
+    addCachedTurn(conversationId: string, turn: ConversationTurn): void;
+    /**
+     * Clears the conversation cache.
+     */
+    clearConversationCache(conversationId?: string): void;
+    /**
+     * Extracts source IDs from a notebook response.
+     */
+    extractSourceIds(notebookData: unknown): string[];
+}
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAiB,MAAM,WAAW,CAAC;AACtD,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAexB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAOnD;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,iBAAiB,CAA8C;gBAE3D,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,OAAO,IAAI,UAAU;IAIrB;;;;;;;OAOG;IACG,OAAO,CACX,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,SAAS,EACjB,gBAAgB,UAAO,GACtB,OAAO,CAAC,OAAO,CAAC;IA6CnB;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBlC;;;;OAIG;IACG,UAAU,CACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IAsDlB;;OAEG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAa9C;;OAEG;IACH,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAI1D;;OAEG;IACH,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAkBnE;;OAEG;IACH,sBAAsB,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI;IAYrD;;OAEG;IACH,gBAAgB,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,EAAE;CAiBlD"}

package/dist/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Error Classes for NotebookLM Client
+ */
+export { RPCError, AuthError } from './rpc/decoder.ts';
+/**
+ * Base error class for source-related errors
+ */
+export declare class SourceError extends Error {
+    readonly sourceId?: string | undefined;
+    readonly notebookId?: string | undefined;
+    constructor(message: string, sourceId?: string | undefined, notebookId?: string | undefined);
+}
+/**
+ * Error thrown when source processing fails
+ */
+export declare class SourceProcessingError extends SourceError {
+    readonly errorCode?: number | undefined;
+    constructor(message: string, sourceId?: string, notebookId?: string, errorCode?: number | undefined);
+}
+/**
+ * Error thrown when waiting for source processing times out
+ */
+export declare class SourceTimeoutError extends SourceError {
+    readonly elapsedMs?: number | undefined;
+    constructor(message: string, sourceId?: string, notebookId?: string, elapsedMs?: number | undefined);
+}
+/**
+ * Error thrown when a source is not found
+ */
+export declare class SourceNotFoundError extends SourceError {
+    constructor(sourceId: string, notebookId?: string);
+}
+/**
+ * Error thrown when a notebook is not found
+ */
+export declare class NotebookNotFoundError extends Error {
+    readonly notebookId: string;
+    constructor(notebookId: string);
+}
+/**
+ * Error thrown when artifact generation fails
+ */
+export declare class GenerationError extends Error {
+    readonly artifactId?: string | undefined;
+    readonly contentType?: string | undefined;
+    constructor(message: string, artifactId?: string | undefined, contentType?: string | undefined);
+}
+/**
+ * Error thrown when artifact generation times out
+ */
+export declare class GenerationTimeoutError extends GenerationError {
+    readonly elapsedMs?: number | undefined;
+    constructor(message: string, artifactId?: string, contentType?: string, elapsedMs?: number | undefined);
+}
+/**
+ * Error thrown when research operations fail
+ */
+export declare class ResearchError extends Error {
+    readonly taskId?: string | undefined;
+    constructor(message: string, taskId?: string | undefined);
+}
+/**
+ * Error thrown for invalid configuration
+ */
+export declare class ConfigurationError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGlB,QAAQ,CAAC,EAAE,MAAM;aACjB,UAAU,CAAC,EAAE,MAAM;gBAFnC,OAAO,EAAE,MAAM,EACC,QAAQ,CAAC,EAAE,MAAM,YAAA,EACjB,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,WAAW;aAKlC,SAAS,CAAC,EAAE,MAAM;gBAHlC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EACH,SAAS,CAAC,EAAE,MAAM,YAAA;CAKrC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;aAK/B,SAAS,CAAC,EAAE,MAAM;gBAHlC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EACH,SAAS,CAAC,EAAE,MAAM,YAAA;CAKrC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAIlD;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAClB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAI/C;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,UAAU,CAAC,EAAE,MAAM;aACnB,WAAW,CAAC,EAAE,MAAM;gBAFpC,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,WAAW,CAAC,EAAE,MAAM,YAAA;CAKvC;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,eAAe;aAKvC,SAAS,CAAC,EAAE,MAAM;gBAHlC,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,EACJ,SAAS,CAAC,EAAE,MAAM,YAAA;CAKrC;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;aAGpB,MAAM,CAAC,EAAE,MAAM;gBAD/B,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA;CAKlC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * NotebookLM TypeScript Client
+ *
+ * An unofficial TypeScript client for Google NotebookLM.
+ *
+ * @example
+ * ```typescript
+ * import { NotebookLMClient } from 'notebooklm';
+ *
+ * const client = await NotebookLMClient.fromStorage();
+ *
+ * // List notebooks
+ * const notebooks = await client.notebooks.list();
+ *
+ * // Create a notebook and add sources
+ * const nb = await client.notebooks.create("My Research");
+ * await client.sources.addUrl(nb.id, "https://example.com");
+ *
+ * // Ask questions
+ * const result = await client.chat.ask(nb.id, "Summarize this");
+ * console.log(result.answer);
+ *
+ * // Generate audio overview
+ * const status = await client.artifacts.generateAudio(nb.id);
+ * await client.artifacts.waitForGeneration(nb.id, status.artifactId);
+ * ```
+ *
+ * @remarks
+ * This library uses undocumented Google APIs that can change without notice.
+ * It is best suited for prototyping, research, and personal projects.
+ *
+ * @packageDocumentation
+ */
+export { NotebookLMClient, createClient } from './client.ts';
+export { AuthTokens } from './auth.ts';
+export { DEFAULT_STORAGE_PATH, DEFAULT_DATA_DIR } from './paths.ts';
+export type { Notebook, NotebookDescription, SuggestedTopic, Source, SourceType, SourceFulltext, SourceSection, SourceGuide, AskResult, ChatReference, ConversationTurn, ChatConfig, Artifact, GenerationStatus, AudioOptions, VideoOptions, ReportOptions, QuizOptions, FlashcardOptions, MindMapOptions, InfographicOptions, SlideOptions, DataTableOptions, ResearchTask, ResearchResult, ResearchSource, Note, Cookie, } from './types.ts';
+export { StudioContentType, AudioFormat, AudioLength, VideoFormat, VideoStyle, QuizDifficulty, ReportFormat, InfographicOrientation, ChatMode, ResponseLength, ResearchSourceType, ResearchMode, SourceStatus, GenerationStatusCode, DriveDocType, ExportDestination, } from './types.ts';
+export { RPCError, AuthError, SourceError, SourceProcessingError, SourceTimeoutError, SourceNotFoundError, NotebookNotFoundError, GenerationError, GenerationTimeoutError, ResearchError, ConfigurationError, } from './errors.ts';
+export { setLogLevel, getLogLevel, createLogger } from './logger.ts';
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG7D,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGpE,YAAY,EAEV,QAAQ,EACR,mBAAmB,EACnB,cAAc,EAGd,MAAM,EACN,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EAGX,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,UAAU,EAGV,QAAQ,EACR,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAGhB,YAAY,EACZ,cAAc,EACd,cAAc,EAGd,IAAI,EAGJ,MAAM,GACP,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,WAAW,EACX,UAAU,EACV,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,sBAAsB,EACtB,aAAa,EACb,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGrE,eAAO,MAAM,OAAO,UAAU,CAAC"}