https://github.com/webdevtodayjason/notebooklm-ts
TypeScript/Node.js port of notebooklm-py for NotebookLM RPC access
https://github.com/webdevtodayjason/notebooklm-ts
Last synced: 17 days ago
JSON representation
TypeScript/Node.js port of notebooklm-py for NotebookLM RPC access
- Host: GitHub
- URL: https://github.com/webdevtodayjason/notebooklm-ts
- Owner: webdevtodayjason
- Created: 2026-03-04T04:10:18.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-04T04:10:20.000Z (5 months ago)
- Last Synced: 2026-06-05T07:18:48.334Z (about 1 month ago)
- Language: TypeScript
- Size: 43.9 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# notebooklm-ts
TypeScript/Node.js port of [`notebooklm-py`](https://github.com/webdevtodayjason/notebooklm-py), focused on programmatic access to Google NotebookLM through reverse-engineered RPC APIs.
## Project Status
This is a **work-in-progress port** with substantial core functionality already implemented and validated with build/typecheck/tests.
Current implementation includes:
- Authentication and core RPC transport
- Notebook operations
- Source operations (URL, text, Drive, file uploads)
- Chat operations with citation/reference extraction
- Artifacts operations
- Generate/list/get/poll/wait
- Download audio/video/report/quiz/flashcards/infographic/slide deck/data table/mind map
- Export report/data table
- Mind map generation and notes-backed persistence
- Notes operations
- Research operations
- Settings operations
- Sharing operations
- Smoke script and parser-focused unit tests
## Why This Exists
The original Python SDK is excellent, but many teams run NotebookLM automations and app backends in Node.js/TypeScript.
This repository ports the Python behavior and RPC payload patterns into a TypeScript-first SDK so Node applications can use a similar API surface.
## Attribution / Credit
This project is a **port** of the original Python work:
- Original repository: [`webdevtodayjason/notebooklm-py`](https://github.com/webdevtodayjason/notebooklm-py)
- Original author: [`webdevtodayjason`](https://github.com/webdevtodayjason)
A large share of RPC method mapping, payload shape understanding, endpoint behavior, and operational flow was derived from that project’s implementation and structure.
## Important Disclaimer
- This SDK uses undocumented/private NotebookLM RPC endpoints.
- It is not affiliated with or endorsed by Google.
- API behavior can change without notice.
- Use in production with proper retries, monitoring, and fallback handling.
## Requirements
- Node.js 20+ (Node 22 recommended)
- A valid NotebookLM authenticated browser storage state (same model as `notebooklm-py`)
## Install / Setup
```bash
npm install
npm run typecheck
npm run build
```
## Authentication
The SDK expects NotebookLM auth tokens loaded from browser storage state (or compatible auth JSON path):
- `NOTEBOOKLM_AUTH_JSON` (optional)
- default storage file support from the auth module
Example:
```ts
import { NotebookLMClient } from "./dist/index.js";
const client = await NotebookLMClient.fromStorage(process.env.NOTEBOOKLM_AUTH_JSON);
await client.open();
```
## Quick Usage Examples
### 1) List notebooks
```ts
import { NotebookLMClient } from "./dist/index.js";
const client = await NotebookLMClient.fromStorage();
await client.open();
const notebooks = await client.notebooks.list();
console.log(notebooks.map((n) => ({ id: n.id, title: n.title })));
await client.close();
```
### 2) Add source + ask chat
```ts
import { NotebookLMClient } from "./dist/index.js";
const client = await NotebookLMClient.fromStorage();
await client.open();
const notebookId = "YOUR_NOTEBOOK_ID";
const source = await client.sources.addText(
notebookId,
"Context",
"This is source content.",
true,
);
const result = await client.chat.ask(notebookId, "Summarize this source");
console.log(result.answer);
console.log(result.references);
await client.close();
```
### 3) Generate + download report
```ts
import { NotebookLMClient, ReportFormat } from "./dist/index.js";
const client = await NotebookLMClient.fromStorage();
await client.open();
const notebookId = "YOUR_NOTEBOOK_ID";
const generation = await client.artifacts.generateReport(notebookId, {
reportFormat: ReportFormat.BRIEFING_DOC,
});
const finalStatus = await client.artifacts.waitForCompletion(notebookId, generation.taskId);
if (finalStatus.status === "completed") {
await client.artifacts.downloadReport(notebookId, "./report.md", generation.taskId);
}
await client.close();
```
## Smoke Script
A runnable end-to-end smoke script is included:
```bash
npm run smoke
```
Supported env vars:
- `NOTEBOOKLM_SMOKE_AUTH_PATH` (or `NOTEBOOKLM_AUTH_JSON`)
- `NOTEBOOKLM_SMOKE_NOTEBOOK_ID`
- `NOTEBOOKLM_SMOKE_CLEANUP` (`true|false`, default `true`)
- `NOTEBOOKLM_SMOKE_SOURCE_TIMEOUT_SECONDS` (default `180`)
- `NOTEBOOKLM_SMOKE_ARTIFACT_TIMEOUT_SECONDS` (default `600`)
- `NOTEBOOKLM_SMOKE_OUTPUT_DIR` (default `tmp/notebooklm-smoke`)
- `NOTEBOOKLM_SMOKE_LANGUAGE` (default `en`)
Flow:
1. Create/use notebook
2. Add text source and wait for readiness
3. Generate report and wait for completion
4. Download report to output directory
5. Optionally clean up temporary notebook
## Tests
Parser-focused unit tests are implemented with Node test runner:
```bash
npm test
```
Current parser test coverage includes:
- Note parsing
- Mind map detection and mapping
- Artifact variant parsing (quiz vs flashcards)
- Report suggestion parsing
- Share status parsing
## API Surface (Current)
Client namespaces:
- `client.notebooks`
- `client.sources`
- `client.chat`
- `client.artifacts`
- `client.notes`
- `client.research`
- `client.settings`
- `client.sharing`
## Roadmap
- Expand automated test coverage (integration/cassette-style)
- Add more fixture-driven parser hardening
- Improve docs and publishable package workflow
- Add optional debug/logging hooks
## Repository Layout
- `src/client.ts` - main client
- `src/core.ts` - RPC transport/auth refresh retry
- `src/api/*` - namespace API modules
- `src/types.ts` - shared user-facing types + parsers
- `src/rpc/*` - rpc constants, encoder, decoder
- `src/scripts/smoke.ts` - end-to-end smoke flow
- `src/tests/parser.test.ts` - parser-focused unit tests
- `PORT_PROGRESS.md` - rolling checkpoint log for resumable work
## Legal / Responsibility
Use responsibly and at your own risk. This repository is for educational and developer tooling purposes and may require maintenance as upstream NotebookLM changes.