{"id":51324585,"url":"https://github.com/webdevtodayjason/notebooklm-ts","last_synced_at":"2026-07-01T17:02:40.153Z","repository":{"id":362620443,"uuid":"1172220709","full_name":"webdevtodayjason/notebooklm-ts","owner":"webdevtodayjason","description":"TypeScript/Node.js port of notebooklm-py for NotebookLM RPC access","archived":false,"fork":false,"pushed_at":"2026-03-04T04:10:20.000Z","size":45,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T07:18:48.334Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webdevtodayjason.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T04:10:18.000Z","updated_at":"2026-03-07T20:32:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/webdevtodayjason/notebooklm-ts","commit_stats":null,"previous_names":["webdevtodayjason/notebooklm-ts"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/webdevtodayjason/notebooklm-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fnotebooklm-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fnotebooklm-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fnotebooklm-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fnotebooklm-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webdevtodayjason","download_url":"https://codeload.github.com/webdevtodayjason/notebooklm-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdevtodayjason%2Fnotebooklm-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35015061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-01T17:02:39.107Z","updated_at":"2026-07-01T17:02:40.138Z","avatar_url":"https://github.com/webdevtodayjason.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# notebooklm-ts\n\nTypeScript/Node.js port of [`notebooklm-py`](https://github.com/webdevtodayjason/notebooklm-py), focused on programmatic access to Google NotebookLM through reverse-engineered RPC APIs.\n\n## Project Status\n\nThis is a **work-in-progress port** with substantial core functionality already implemented and validated with build/typecheck/tests.\n\nCurrent implementation includes:\n\n- Authentication and core RPC transport\n- Notebook operations\n- Source operations (URL, text, Drive, file uploads)\n- Chat operations with citation/reference extraction\n- Artifacts operations\n  - Generate/list/get/poll/wait\n  - Download audio/video/report/quiz/flashcards/infographic/slide deck/data table/mind map\n  - Export report/data table\n  - Mind map generation and notes-backed persistence\n- Notes operations\n- Research operations\n- Settings operations\n- Sharing operations\n- Smoke script and parser-focused unit tests\n\n## Why This Exists\n\nThe original Python SDK is excellent, but many teams run NotebookLM automations and app backends in Node.js/TypeScript.\n\nThis repository ports the Python behavior and RPC payload patterns into a TypeScript-first SDK so Node applications can use a similar API surface.\n\n## Attribution / Credit\n\nThis project is a **port** of the original Python work:\n\n- Original repository: [`webdevtodayjason/notebooklm-py`](https://github.com/webdevtodayjason/notebooklm-py)\n- Original author: [`webdevtodayjason`](https://github.com/webdevtodayjason)\n\nA large share of RPC method mapping, payload shape understanding, endpoint behavior, and operational flow was derived from that project’s implementation and structure.\n\n## Important Disclaimer\n\n- This SDK uses undocumented/private NotebookLM RPC endpoints.\n- It is not affiliated with or endorsed by Google.\n- API behavior can change without notice.\n- Use in production with proper retries, monitoring, and fallback handling.\n\n## Requirements\n\n- Node.js 20+ (Node 22 recommended)\n- A valid NotebookLM authenticated browser storage state (same model as `notebooklm-py`)\n\n## Install / Setup\n\n```bash\nnpm install\nnpm run typecheck\nnpm run build\n```\n\n## Authentication\n\nThe SDK expects NotebookLM auth tokens loaded from browser storage state (or compatible auth JSON path):\n\n- `NOTEBOOKLM_AUTH_JSON` (optional)\n- default storage file support from the auth module\n\nExample:\n\n```ts\nimport { NotebookLMClient } from \"./dist/index.js\";\n\nconst client = await NotebookLMClient.fromStorage(process.env.NOTEBOOKLM_AUTH_JSON);\nawait client.open();\n```\n\n## Quick Usage Examples\n\n### 1) List notebooks\n\n```ts\nimport { NotebookLMClient } from \"./dist/index.js\";\n\nconst client = await NotebookLMClient.fromStorage();\nawait client.open();\n\nconst notebooks = await client.notebooks.list();\nconsole.log(notebooks.map((n) =\u003e ({ id: n.id, title: n.title })));\n\nawait client.close();\n```\n\n### 2) Add source + ask chat\n\n```ts\nimport { NotebookLMClient } from \"./dist/index.js\";\n\nconst client = await NotebookLMClient.fromStorage();\nawait client.open();\n\nconst notebookId = \"YOUR_NOTEBOOK_ID\";\nconst source = await client.sources.addText(\n  notebookId,\n  \"Context\",\n  \"This is source content.\",\n  true,\n);\n\nconst result = await client.chat.ask(notebookId, \"Summarize this source\");\nconsole.log(result.answer);\nconsole.log(result.references);\n\nawait client.close();\n```\n\n### 3) Generate + download report\n\n```ts\nimport { NotebookLMClient, ReportFormat } from \"./dist/index.js\";\n\nconst client = await NotebookLMClient.fromStorage();\nawait client.open();\n\nconst notebookId = \"YOUR_NOTEBOOK_ID\";\n\nconst generation = await client.artifacts.generateReport(notebookId, {\n  reportFormat: ReportFormat.BRIEFING_DOC,\n});\n\nconst finalStatus = await client.artifacts.waitForCompletion(notebookId, generation.taskId);\nif (finalStatus.status === \"completed\") {\n  await client.artifacts.downloadReport(notebookId, \"./report.md\", generation.taskId);\n}\n\nawait client.close();\n```\n\n## Smoke Script\n\nA runnable end-to-end smoke script is included:\n\n```bash\nnpm run smoke\n```\n\nSupported env vars:\n\n- `NOTEBOOKLM_SMOKE_AUTH_PATH` (or `NOTEBOOKLM_AUTH_JSON`)\n- `NOTEBOOKLM_SMOKE_NOTEBOOK_ID`\n- `NOTEBOOKLM_SMOKE_CLEANUP` (`true|false`, default `true`)\n- `NOTEBOOKLM_SMOKE_SOURCE_TIMEOUT_SECONDS` (default `180`)\n- `NOTEBOOKLM_SMOKE_ARTIFACT_TIMEOUT_SECONDS` (default `600`)\n- `NOTEBOOKLM_SMOKE_OUTPUT_DIR` (default `tmp/notebooklm-smoke`)\n- `NOTEBOOKLM_SMOKE_LANGUAGE` (default `en`)\n\nFlow:\n\n1. Create/use notebook\n2. Add text source and wait for readiness\n3. Generate report and wait for completion\n4. Download report to output directory\n5. Optionally clean up temporary notebook\n\n## Tests\n\nParser-focused unit tests are implemented with Node test runner:\n\n```bash\nnpm test\n```\n\nCurrent parser test coverage includes:\n\n- Note parsing\n- Mind map detection and mapping\n- Artifact variant parsing (quiz vs flashcards)\n- Report suggestion parsing\n- Share status parsing\n\n## API Surface (Current)\n\nClient namespaces:\n\n- `client.notebooks`\n- `client.sources`\n- `client.chat`\n- `client.artifacts`\n- `client.notes`\n- `client.research`\n- `client.settings`\n- `client.sharing`\n\n## Roadmap\n\n- Expand automated test coverage (integration/cassette-style)\n- Add more fixture-driven parser hardening\n- Improve docs and publishable package workflow\n- Add optional debug/logging hooks\n\n## Repository Layout\n\n- `src/client.ts` - main client\n- `src/core.ts` - RPC transport/auth refresh retry\n- `src/api/*` - namespace API modules\n- `src/types.ts` - shared user-facing types + parsers\n- `src/rpc/*` - rpc constants, encoder, decoder\n- `src/scripts/smoke.ts` - end-to-end smoke flow\n- `src/tests/parser.test.ts` - parser-focused unit tests\n- `PORT_PROGRESS.md` - rolling checkpoint log for resumable work\n\n## Legal / Responsibility\n\nUse responsibly and at your own risk. This repository is for educational and developer tooling purposes and may require maintenance as upstream NotebookLM changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdevtodayjason%2Fnotebooklm-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebdevtodayjason%2Fnotebooklm-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdevtodayjason%2Fnotebooklm-ts/lists"}