notebooklm-sdk 0.1.7 → 0.2.0

package/README.md

@@ -1,17 +1,18 @@
 # notebooklm-sdk
 
+### Automate NotebookLM from your code.
+
 [![npm version](https://img.shields.io/npm/v/notebooklm-sdk?style=flat-square)](https://www.npmjs.com/package/notebooklm-sdk)
 ![types](https://img.shields.io/npm/types/notebooklm-sdk?style=flat-square)
 ![license](https://img.shields.io/npm/l/notebooklm-sdk?style=flat-square)
 
-A lightweight, zero-dependency TypeScript SDK for the NotebookLM API.  
-Works in **Node.js, Bun, and Deno**.
+Generate AI podcasts, chat with documents, run web research, and manage notebooks programmatically — from Node.js, Bun, or Deno.
 
-> This SDK is a TypeScript port of [notebooklm-py](https://github.com/teng-lin/notebooklm-py).
+> ⚠️ **Unofficial.** This SDK reverse-engineers the NotebookLM internal API. It may break when Google updates their service. Not affiliated with Google.
 
----
+TypeScript port of [notebooklm-py](https://github.com/teng-lin/notebooklm-py).
 
-## Installation
+## Install
 
 ```bash
 npm install notebooklm-sdk
@@ -19,289 +20,131 @@ npm install notebooklm-sdk
 bun add notebooklm-sdk
 ```
 
-## Authentication
-
-### Quick Login (Recommended)
-
-First, install playwright:
-
-```bash
-bun add -d playwright
-bunx playwright install chromium
-```
-
-Then, authenticate using the CLI:
+## Quickstart
 
 ```bash
+# Run once to authenticate
 npx notebooklm-sdk login
-# or
-bun x notebooklm-sdk login
 ```
 
-This opens a real browser for Google sign-in and generates a
-`storage_state.json` file you can reuse.
-
-Then connect using the file:
-
 ```ts
 import { NotebookLMClient } from "notebooklm-sdk";
 
-const client = await NotebookLMClient.connect({
-  cookiesFile: "./storage_state.json",
-});
-```
-
-<details>
-<summary>Manual Authentication</summary>
-
-You can authenticate in multiple ways depending on your setup.
-
-#### 1. Use `.env` Cookie String
-
-Copy the `Cookie` header from DevTools → Network and store it:
-
-```bash
-NOTEBOOKLM_COOKIE="SID=...; HSID=..."
-```
-
-Then:
-
-```ts
-const client = await NotebookLMClient.connect({
-  cookies: process.env.NOTEBOOKLM_COOKIE,
-});
-```
-
----
+const client = await NotebookLMClient.connect(); // uses ~/.notebooklm/session.json
 
-#### 2. Use Playwright `storage_state.json`
+// Create a notebook and add a source
+const { id } = await client.notebooks.create("My Research");
+await client.sources.addUrl(id, "https://en.wikipedia.org/wiki/TypeScript");
 
-If you already have a Playwright storage file:
-
-```ts
-const client = await NotebookLMClient.connect({
-  cookiesFile: "./storage_state.json",
+// Generate a podcast and download it
+const { artifactId } = await client.artifacts.createAudio(id, {
+  format: "deep_dive",
 });
-```
-
----
-
-#### 3. Pass Cookies Directly
+const audio = await client.artifacts.waitUntilReady(id, artifactId);
+const mp3 = await client.artifacts.downloadAudio(id, audio.id);
 
-You can also pass cookies at runtime:
-
-```ts
-const client = await NotebookLMClient.connect({
-  cookies: "SID=...; HSID=...",
-});
+// Chat with the sources
+const res = await client.chat.ask(id, "Summarize the key points.");
+console.log(res.answer);
 ```
 
-</details>
+## Use cases
 
----
+- **Blog & content generation** — research a topic, import sources, generate a blog post or briefing doc automatically
+- **Content pipelines** — ingest articles or reports, generate a podcast or briefing doc on a schedule
+- **Research automation** — run web research, import results, and query them via chat
+- **Document Q&A bots** — feed documents into a notebook and build a chat interface on top
+- **Batch artifact generation** — generate quizzes, flashcards, or study guides from a library of sources
+- **Notebook management tools** — create, organize, and share notebooks programmatically
 
-## Notebooks
-
-```ts
-const notebooks = await client.notebooks.list();
-const nb = await client.notebooks.get(id);
+## Authentication
 
-const { id: newId } = await client.notebooks.create("My Notebook");
+### Login (recommended)
 
-await client.notebooks.rename(newId, "New Title");
-await client.notebooks.delete(newId);
+Install Playwright once:
 
-const summary = await client.notebooks.getSummary(id);
-const description = await client.notebooks.getDescription(id);
+```bash
+bun add -d playwright
+bunx playwright install chromium
 ```
 
----
-
-## Sources
+Authenticate:
 
-```ts
-const sources = await client.sources.list(notebookId);
-
-const { sourceId } = await client.sources.addUrl(
-  notebookId,
-  "https://example.com",
-);
-const { sourceId } = await client.sources.addText(notebookId, "Text", "Title");
-const { sourceId } = await client.sources.addFile(
-  notebookId,
-  buffer,
-  "file.pdf",
-);
-
-await client.sources.waitUntilReady(notebookId, sourceId);
-
-await client.sources.delete(notebookId, sourceId);
+```bash
+npx notebooklm-sdk login
 ```
 
----
-
-## Artifacts
+Opens a real Chrome window for Google sign-in. Session is saved to `~/.notebooklm/session.json` and auto-discovered on every `connect()` — no config needed.
 
-Generate AI outputs from notebook sources.
-
-```ts
-const { artifactId } = await client.artifacts.createAudio(notebookId, {
-  format: AudioFormat.DEEP_DIVE,
-  length: AudioLength.DEFAULT,
-  language: "en",
-});
-
-const { artifactId } = await client.artifacts.createVideo(notebookId, {
-  format: VideoFormat.EXPLAINER,
-});
-
-const { artifactId } = await client.artifacts.createQuiz(notebookId);
-const { artifactId } = await client.artifacts.createFlashcards(notebookId);
-
-const { artifactId } = await client.artifacts.createReport(notebookId, {
-  format: "briefing_doc",
-});
+```bash
+npx notebooklm-sdk whoami  # verify session is valid
 ```
 
-Wait & download:
-
-```ts
-await client.artifacts.waitUntilReady(notebookId, artifactId);
+### CI / Server
 
-const audio = await client.artifacts.downloadAudio(notebookId, artifactId);
-const video = await client.artifacts.downloadVideo(notebookId, artifactId);
+Pass cookies via environment variable:
 
-const markdown = await client.artifacts.getReportMarkdown(
-  notebookId,
-  artifactId,
-);
-const html = await client.artifacts.getInteractiveHtml(notebookId, artifactId);
+```bash
+NOTEBOOKLM_COOKIES="SID=...; HSID=..."
 ```
 
----
-
-## Chat
-
 ```ts
-const res = await client.chat.ask(notebookId, "What is this about?");
-console.log(res.answer);
-
-const follow = await client.chat.ask(notebookId, "Tell me more.", {
-  conversationId: res.conversationId,
+const client = await NotebookLMClient.connect({
+  cookies: process.env.NOTEBOOKLM_COOKIES,
 });
-
-const convId = await client.chat.getLastConversationId(notebookId);
-const turns = await client.chat.getConversationTurns(notebookId, convId);
 ```
 
----
+> To get cookie values: open NotebookLM in Chrome → DevTools → Network → any request → copy the `Cookie` header.
 
-## Notes
+## What you can build
 
-```ts
-const { noteId } = await client.notes.create(notebookId, "# My Note");
+| API         | What it does                                            |
+| ----------- | ------------------------------------------------------- |
+| `notebooks` | Create, rename, delete, list notebooks                  |
+| `sources`   | Add URLs, text, files; wait for processing              |
+| `artifacts` | Generate and download AI outputs (see below)            |
+| `chat`      | Ask questions, follow-up conversations                  |
+| `research`  | Run web research, import results as sources             |
+| `notes`     | Create and manage saved notes                           |
+| `sharing`   | Control public access and per-user permissions          |
+| `settings`  | Get/set output language                                 |
 
-await client.notes.update(notebookId, noteId, "Updated");
-await client.notes.delete(notebookId, noteId);
-```
+**Artifact types**
 
----
+| Artifact       | Method               | Output            |
+| -------------- | -------------------- | ----------------- |
+| Audio Overview | `createAudio()`      | Downloadable MP3  |
+| Video Overview | `createVideo()`      | Downloadable MP4  |
+| Slide Deck     | `createSlideDeck()`  | PDF / PPTX download |
+| Infographic    | `createInfographic()`| PNG download      |
+| Mind Map       | `createMindMap()`    | JSON download     |
+| Reports        | `createReport()`     | Markdown download |
+| Flashcards     | `createFlashcards()` | Interactive HTML  |
+| Quiz           | `createQuiz()`       | Interactive HTML  |
+| Data Table     | `createDataTable()`  | CSV (headers + rows) |
 
-## Research
-
-```ts
-const task = await client.research.start(
-  notebookId,
-  "Latest advances in quantum computing",
-  "web",
-  "deep",
-);
-
-const result = await client.research.poll(notebookId);
-
-if (result.status === "completed") {
-  await client.research.importSources(
-    notebookId,
-    result.taskId,
-    result.sources.slice(0, 2),
-  );
-}
-```
-
----
-
-## Sharing
-
-```ts
-await client.sharing.setPublic(notebookId, true);
-
-await client.sharing.addUser(
-  notebookId,
-  "user@example.com",
-  SharePermission.VIEWER,
-);
-```
-
----
-
-## Settings
-
-```ts
-const lang = await client.settings.getOutputLanguage();
-await client.settings.setOutputLanguage("ja");
-```
-
----
+→ [Full API reference](./DOCS.md)
 
 ## Examples
 
-Runnable scripts are in [`examples/`](./examples).
-
-**Setup:**
-
-1. `npm run login` to create `storage_state.json`.
-2. Run any example below.
-
 ```bash
-# for auto login
-bun run login
-bun run examples/basic.ts
-
-# for manual cookie
-bunx dotenv -e .env -- bunx tsx examples/basic.ts
-```
-
----
-
-## Error Handling
-
-All errors extend `NotebookLMError`.
-
-```ts
-try {
-  await client.artifacts.downloadAudio(notebookId, artifactId);
-} catch (err) {
-  if (err instanceof ArtifactNotReadyError) {
-    // still processing
-  }
-}
-```
-
----
-
-## Project Structure
+npx notebooklm-sdk login
 
+bun run examples/basic.ts           # list notebooks and sources
+bun run examples/chat.ts            # ask questions, follow-up conversations
+bun run examples/audio.ts           # generate and download a podcast
+bun run examples/report.ts          # generate and download a briefing doc
+bun run examples/slide-deck.ts      # generate and download PDF / PPTX
+bun run examples/infographic.ts     # generate and download a PNG infographic
+bun run examples/mind-map.ts        # generate and download mind map JSON
+bun run examples/data-table.ts      # generate and download a CSV data table
+bun run examples/notes.ts           # create, update, list, and delete notes
+bun run examples/research.ts        # web research and import sources
+bun run examples/research-and-chat.ts  # research → import → chat
+bun run examples/full-lifecycle.ts  # create, add sources, chat, delete
+bun run examples/download.ts        # download all completed artifacts
 ```
-src/
-  client.ts
-  auth.ts
-  api/
-  rpc/
-  types/
-```
-
----
 
 ## License
 
-MIT
+MIT · TypeScript port of [notebooklm-py](https://github.com/teng-lin/notebooklm-py)

package/dist/{auth-Ba2hsZW_.d.cts → auth-Dxsm8894.d.cts}

@@ -50,6 +50,6 @@ interface ConnectOptions {
         }>;
     };
 }
-declare function connect(opts: ConnectOptions): Promise<AuthTokens>;
+declare function connect(opts?: ConnectOptions): Promise<AuthTokens>;
 
 export { type AuthTokens as A, type CookieMap as C, type ConnectOptions as a, buildCookieHeader as b, buildGoogleCookieHeader as c, connect as d, loadCookiesFromMap as e, fetchTokens as f, loadCookiesFromObject as g, loadCookiesFromString as h, loadCookiesFromFile as l };

package/dist/{auth-Ba2hsZW_.d.ts → auth-Dxsm8894.d.ts}

@@ -50,6 +50,6 @@ interface ConnectOptions {
         }>;
     };
 }
-declare function connect(opts: ConnectOptions): Promise<AuthTokens>;
+declare function connect(opts?: ConnectOptions): Promise<AuthTokens>;
 
 export { type AuthTokens as A, type CookieMap as C, type ConnectOptions as a, buildCookieHeader as b, buildGoogleCookieHeader as c, connect as d, loadCookiesFromMap as e, fetchTokens as f, loadCookiesFromObject as g, loadCookiesFromString as h, loadCookiesFromFile as l };

package/dist/auth.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
 var fs = require('fs');
+var os = require('os');
+var path = require('path');
 var playwright = require('playwright');
 
 // src/auth.ts
@@ -29,15 +31,14 @@ var AuthError = class extends RPCError {
 };
 
 // src/auth.ts
+var DEFAULT_SESSION_FILE = path.join(os.homedir(), ".notebooklm", "session.json");
 function loadCookiesFromFile(filePath) {
   let raw;
   try {
     raw = fs.readFileSync(filePath, "utf-8");
   } catch {
-    throw new AuthError(
-      `Cookie file not found: ${filePath}
-Provide valid Playwright storage state JSON.`
-    );
+    throw new AuthError(`Session file not found: ${filePath}
+Run: npx notebooklm-sdk login`);
   }
   return extractCookiesFromStorageState(JSON.parse(raw));
 }
@@ -80,7 +81,7 @@ function extractCookiesFromStorageState(storageState) {
   }
   if (!cookies["SID"]) {
     throw new AuthError(
-      "Missing required cookie: SID. Provide valid Playwright storage state with Google cookies."
+      "Missing required cookie: SID. Session may be invalid or expired.\nRun: npx notebooklm-sdk login"
     );
   }
   return cookies;
@@ -120,7 +121,7 @@ function extractCsrfToken(html, finalUrl) {
   const match = /"SNlM0e"\s*:\s*"([^"]+)"/.exec(html);
   if (!match?.[1]) {
     if (isGoogleAuthRedirect(finalUrl) || html.includes("accounts.google.com")) {
-      throw new AuthError("Authentication expired or invalid. Cookies may need to be refreshed.");
+      throw new AuthError("Session expired or invalid.\nRun: npx notebooklm-sdk login");
     }
     throw new AuthError("CSRF token (SNlM0e) not found in NotebookLM page HTML.");
   }
@@ -130,7 +131,7 @@ function extractSessionId(html, finalUrl) {
   const match = /"FdrFJe"\s*:\s*"([^"]+)"/.exec(html);
   if (!match?.[1]) {
     if (isGoogleAuthRedirect(finalUrl) || html.includes("accounts.google.com")) {
-      throw new AuthError("Authentication expired or invalid. Cookies may need to be refreshed.");
+      throw new AuthError("Session expired or invalid.\nRun: npx notebooklm-sdk login");
     }
     throw new AuthError("Session ID (FdrFJe) not found in NotebookLM page HTML.");
   }
@@ -139,7 +140,7 @@ function extractSessionId(html, finalUrl) {
 function isGoogleAuthRedirect(url) {
   return url.includes("accounts.google.com") || url.includes("signin");
 }
-async function connect(opts) {
+async function connect(opts = {}) {
   let cookieMap;
   let googleCookieHeader = null;
   if (opts.cookies) {
@@ -156,12 +157,23 @@ async function connect(opts) {
     }
   } else {
     const envCookies = process.env["NOTEBOOKLM_COOKIES"];
-    if (envCookies) {
+    const envFile = process.env["NOTEBOOKLM_COOKIES_FILE"];
+    if (envFile) {
+      cookieMap = loadCookiesFromFile(envFile);
+    } else if (fs.existsSync(DEFAULT_SESSION_FILE)) {
+      const raw = fs.readFileSync(DEFAULT_SESSION_FILE, "utf-8");
+      const storageState = JSON.parse(raw);
+      cookieMap = loadCookiesFromObject(storageState);
+      googleCookieHeader = buildGoogleCookieHeader(storageState);
+    } else if (fs.existsSync("storage_state.json")) {
+      const raw = fs.readFileSync("storage_state.json", "utf-8");
+      const storageState = JSON.parse(raw);
+      cookieMap = loadCookiesFromObject(storageState);
+      googleCookieHeader = buildGoogleCookieHeader(storageState);
+    } else if (envCookies) {
       cookieMap = loadCookiesFromString(envCookies);
     } else {
-      throw new AuthError(
-        "No cookies provided. Pass cookies, cookiesFile, or cookiesObject to connect()."
-      );
+      throw new AuthError("No session found. Run: npx notebooklm-sdk login");
     }
   }
   const { csrfToken, sessionId } = await fetchTokens(cookieMap);
@@ -174,27 +186,33 @@ async function connect(opts) {
     googleCookieHeader: googleCookieHeader ?? cookieHeader
   };
 }
+var DEFAULT_SESSION_DIR = path.join(os.homedir(), ".notebooklm");
+var DEFAULT_SESSION_FILE2 = path.join(DEFAULT_SESSION_DIR, "session.json");
 var NOTEBOOKLM_URL2 = "https://notebooklm.google.com/";
 var GOOGLE_ACCOUNTS_URL = "https://accounts.google.com/";
 async function login(opts = {}) {
-  const { persistFolder, headless = false, browserType = "chromium" } = opts;
+  const {
+    persistFolder = path.join(DEFAULT_SESSION_DIR, ".auth_profile"),
+    headless = false,
+    browserType = "chromium"
+  } = opts;
+  try {
+    playwright.chromium.executablePath();
+  } catch {
+    throw new Error("Playwright browser not found. Run: npx playwright install chromium");
+  }
+  if (!fs.existsSync(DEFAULT_SESSION_DIR)) {
+    fs.mkdirSync(DEFAULT_SESSION_DIR, { recursive: true });
+  }
   let context;
   const launchOptions = {
     headless,
     args: ["--disable-blink-features=AutomationControlled"]
   };
-  if (persistFolder) {
-    context = await playwright.chromium.launchPersistentContext(persistFolder, {
-      ...launchOptions,
-      channel: browserType === "msedge" ? "msedge" : void 0
-    });
-  } else {
-    const browser = await playwright.chromium.launch({
-      ...launchOptions,
-      channel: browserType === "msedge" ? "msedge" : void 0
-    });
-    context = await browser.newContext();
-  }
+  context = await playwright.chromium.launchPersistentContext(persistFolder, {
+    ...launchOptions,
+    channel: browserType === "msedge" ? "msedge" : void 0
+  });
   const page = context.pages()[0] || await context.newPage();
   await page.goto(NOTEBOOKLM_URL2);
   if (page.url().includes("accounts.google.com")) {
@@ -218,6 +236,8 @@ async function login(opts = {}) {
   };
 }
 
+exports.DEFAULT_SESSION_DIR = DEFAULT_SESSION_DIR;
+exports.DEFAULT_SESSION_FILE = DEFAULT_SESSION_FILE2;
 exports.buildCookieHeader = buildCookieHeader;
 exports.buildGoogleCookieHeader = buildGoogleCookieHeader;
 exports.connect = connect;