notebooklm-sdk 0.1.0 → 0.1.4

package/README.md

@@ -2,6 +2,8 @@
 
 A lightweight, zero-dependency TypeScript SDK for the NotebookLM API. Works with Node.js, Bun, and Deno.
 
+> **Note**: This SDK is a TypeScript port of [notebooklm-py](https://github.com/teng-lin/notebooklm-py).
+
 ## Installation
 
 ```bash
@@ -15,16 +17,19 @@ bun add notebooklm-sdk
 This SDK uses **manual cookie auth only** — no Playwright, no headless browser. You extract your cookies once and pass them in.
 
 **Option 1 — Raw cookie string** (from browser DevTools → Network tab → copy `Cookie` request header):
+
 ```bash
 NOTEBOOKLM_COOKIE="SID=...; HSID=...; ..."
 ```
 
 **Option 2 — Playwright `storage_state.json`** (JSON array of cookie objects):
+
 ```bash
 NOTEBOOKLM_COOKIE='[{"name":"SID","value":"...","domain":".google.com",...}]'
 ```
 
 Then connect:
+
 ```typescript
 import { NotebookLMClient } from "notebooklm-sdk";
 
@@ -40,9 +45,9 @@ const client = await NotebookLMClient.connect({
 ```typescript
 const notebooks = await client.notebooks.list();
 const nb = await client.notebooks.get(notebookId);
-const { notebookId } = await client.notebooks.create("My Notebook");
-await client.notebooks.rename(notebookId, "New Title");
-await client.notebooks.delete(notebookId);
+const { id: newNbId } = await client.notebooks.create("My Notebook");
+await client.notebooks.rename(newNbId, "New Title");
+await client.notebooks.delete(newNbId);
 
 const summary = await client.notebooks.getSummary(notebookId);
 const description = await client.notebooks.getDescription(notebookId);
@@ -56,9 +61,20 @@ const sources = await client.sources.list(notebookId);
 const source = await client.sources.get(notebookId, sourceId);
 
 // Add sources
-const { sourceId } = await client.sources.addUrl(notebookId, "https://example.com");
-const { sourceId } = await client.sources.addText(notebookId, "My text", "My Title");
-const { sourceId } = await client.sources.addFile(notebookId, buffer, "file.pdf");
+const { sourceId } = await client.sources.addUrl(
+  notebookId,
+  "https://example.com",
+);
+const { sourceId } = await client.sources.addText(
+  notebookId,
+  "My text",
+  "My Title",
+);
+const { sourceId } = await client.sources.addFile(
+  notebookId,
+  buffer,
+  "file.pdf",
+);
 
 // Poll until ready (status: "ready")
 const source = await client.sources.waitUntilReady(notebookId, sourceId);
@@ -73,14 +89,14 @@ Generate AI artifacts from notebook sources:
 ```typescript
 // Audio podcast
 const { artifactId } = await client.artifacts.createAudio(notebookId, {
-  format: AudioFormat.DEEP_DIVE,  // DEEP_DIVE | BRIEF | CRITIQUE | DEBATE
-  length: AudioLength.DEFAULT,    // SHORT | DEFAULT | LONG
+  format: AudioFormat.DEEP_DIVE, // DEEP_DIVE | BRIEF | CRITIQUE | DEBATE
+  length: AudioLength.DEFAULT, // SHORT | DEFAULT | LONG
   language: "en",
 });
 
 // Video
 const { artifactId } = await client.artifacts.createVideo(notebookId, {
-  format: VideoFormat.EXPLAINER,  // EXPLAINER | BRIEF | CINEMATIC
+  format: VideoFormat.EXPLAINER, // EXPLAINER | BRIEF | CINEMATIC
 });
 
 // Quiz / Flashcards
@@ -92,7 +108,7 @@ const { artifactId } = await client.artifacts.createFlashcards(notebookId);
 
 // Report (markdown)
 const { artifactId } = await client.artifacts.createReport(notebookId, {
-  format: "briefing_doc",  // "briefing_doc" | "study_guide" | "blog_post" | "custom"
+  format: "briefing_doc", // "briefing_doc" | "study_guide" | "blog_post" | "custom"
   language: "en",
 });
 
@@ -109,9 +125,18 @@ Poll and download:
 const artifact = await client.artifacts.waitUntilReady(notebookId, artifactId);
 
 // Download
-const audioBuffer = await client.artifacts.downloadAudio(notebookId, artifactId);
-const videoBuffer = await client.artifacts.downloadVideo(notebookId, artifactId);
-const markdown = await client.artifacts.getReportMarkdown(notebookId, artifactId);
+const audioBuffer = await client.artifacts.downloadAudio(
+  notebookId,
+  artifactId,
+);
+const videoBuffer = await client.artifacts.downloadVideo(
+  notebookId,
+  artifactId,
+);
+const markdown = await client.artifacts.getReportMarkdown(
+  notebookId,
+  artifactId,
+);
 const html = await client.artifacts.getInteractiveHtml(notebookId, artifactId); // quiz/flashcards
 ```
 
@@ -138,7 +163,10 @@ const turns = await client.chat.getConversationTurns(notebookId, lastConvId);
 ```typescript
 const { notes, mindMaps } = await client.notes.list(notebookId);
 
-const { noteId } = await client.notes.create(notebookId, "# My Note\n\nContent here.");
+const { noteId } = await client.notes.create(
+  notebookId,
+  "# My Note\n\nContent here.",
+);
 await client.notes.update(notebookId, noteId, "Updated content.");
 await client.notes.delete(notebookId, noteId);
 ```
@@ -147,7 +175,12 @@ await client.notes.delete(notebookId, noteId);
 
 ```typescript
 // Start a fast web search or deep research
-const task = await client.research.start(notebookId, "Latest advances in quantum computing", "web", "deep");
+const task = await client.research.start(
+  notebookId,
+  "Latest advances in quantum computing",
+  "web",
+  "deep",
+);
 
 // Poll for results
 const result = await client.research.poll(notebookId);
@@ -155,9 +188,13 @@ const result = await client.research.poll(notebookId);
 if (result.status === "completed") {
   console.log(result.summary);
   console.log(`Found ${result.sources.length} sources.`);
-  
+
   // Import desired sources into the notebook
-  await client.research.importSources(notebookId, result.taskId, result.sources.slice(0, 2));
+  await client.research.importSources(
+    notebookId,
+    result.taskId,
+    result.sources.slice(0, 2),
+  );
 }
 ```
 
@@ -171,8 +208,16 @@ const status = await client.sharing.getStatus(notebookId);
 await client.sharing.setPublic(notebookId, true);
 
 // Share with a specific user
-await client.sharing.addUser(notebookId, "user@example.com", SharePermission.VIEWER);
-await client.sharing.updateUser(notebookId, "user@example.com", SharePermission.EDITOR);
+await client.sharing.addUser(
+  notebookId,
+  "user@example.com",
+  SharePermission.VIEWER,
+);
+await client.sharing.updateUser(
+  notebookId,
+  "user@example.com",
+  SharePermission.EDITOR,
+);
 await client.sharing.removeUser(notebookId, "user@example.com");
 ```
 
@@ -187,15 +232,17 @@ await client.settings.setOutputLanguage("ja");
 
 Runnable scripts in [`examples/`](./examples). Requires `.env` with `NOTEBOOKLM_COOKIE`.
 
-| Script | What it does |
-|--------|-------------|
-| `basic.ts` | List notebooks and sources |
-| `report.ts` | Generate and download a report |
-| `audio.ts` | Generate a podcast (long wait) |
-| `download.ts` | Download all completed artifacts (audio, video, reports, quiz, flashcards) |
-| `chat.ts` | Ask questions and follow up |
-| `research.ts` | Start a web research session and import sources |
-| `settings.ts` | Check output language and sharing status |
+| Script                 | What it does                                                               |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `basic.ts`             | List notebooks and sources                                                 |
+| `report.ts`            | Generate and download a report                                             |
+| `audio.ts`             | Generate a podcast (long wait)                                             |
+| `download.ts`          | Download all completed artifacts (audio, video, reports, quiz, flashcards) |
+| `chat.ts`              | Ask questions and follow up                                                |
+| `research.ts`          | Start a web research session and import sources                            |
+| `research-and-chat.ts` | Complete workflow: create notebook, research, import sources, and chat     |
+| `full-lifecycle.ts`    | Create/rename notebook, upload files/urls/text, chat, and delete           |
+| `settings.ts`          | Check output language and sharing status                                   |
 
 ```bash
 bunx dotenv -e .env -- bunx tsx examples/basic.ts
@@ -206,14 +253,24 @@ bunx dotenv -e .env -- bunx tsx examples/basic.ts
 All errors extend `NotebookLMError`:
 
 ```typescript
-import { ArtifactNotReadyError, AuthError, RateLimitError } from "notebooklm-sdk";
+import {
+  ArtifactNotReadyError,
+  AuthError,
+  RateLimitError,
+} from "notebooklm-sdk";
 
 try {
   await client.artifacts.downloadAudio(notebookId, artifactId);
 } catch (err) {
-  if (err instanceof ArtifactNotReadyError) { /* artifact still processing */ }
-  if (err instanceof AuthError) { /* cookies expired */ }
-  if (err instanceof RateLimitError) { /* back off */ }
+  if (err instanceof ArtifactNotReadyError) {
+    /* artifact still processing */
+  }
+  if (err instanceof AuthError) {
+    /* cookies expired */
+  }
+  if (err instanceof RateLimitError) {
+    /* back off */
+  }
 }
 ```