notebooklm-api-client 0.1.155 → 0.1.156

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notebooklm-api-client",
-  "version": "0.1.155",
+  "version": "0.1.156",
   "description": "NotebookLM API via Cloudflare Containers — on-demand Python sandbox that sleeps when idle",
   "author": "vtempest <grokthiscontact@gmail.com>",
   "license": "rights.institute/PROSPER",
@@ -14,14 +14,18 @@
   "scripts": {
     "dev": "wrangler dev",
     "deploy": "wrangler deploy",
-    "types": "wrangler types"
+    "types": "wrangler types",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@cloudflare/puppeteer": "^1.0.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20241127.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
     "wrangler": "^4.0.0"
   }
 }

package/test/login.test.ts

@@ -0,0 +1,212 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import worker, { type Env } from '../src/index';
+import { setLaunchImpl } from './stubs/puppeteer';
+
+const API_TOKEN = 'test-token';
+
+/** A puppeteer Page double recording the interactions handleLogin performs. */
+function createPage(overrides: Record<string, unknown> = {}) {
+  return {
+    typed: [] as { selector: string; value: string }[],
+    clicked: [] as string[],
+    setUserAgent: vi.fn(async () => {}),
+    goto: vi.fn(async () => {}),
+    waitForSelector: vi.fn(async () => {}),
+    waitForNavigation: vi.fn(async () => {}),
+    type: vi.fn(async function (this: never, selector: string, value: string) {
+      (page.typed as { selector: string; value: string }[]).push({ selector, value });
+    }),
+    click: vi.fn(async (selector: string) => {
+      (page.clicked as string[]).push(selector);
+    }),
+    $: vi.fn(async () => null),
+    cookies: vi.fn(async () => [{ name: 'SID', value: 'abc' }]),
+    evaluate: vi.fn(async () => ({ token: 'xyz' })),
+    ...overrides,
+  };
+  }
+
+let page: ReturnType<typeof createPage>;
+
+function createEnv() {
+  const containerFetch = vi.fn(async () => new Response('{}', { status: 200 }));
+  const env = {
+    NOTEBOOK_RUNNER: { idFromName: vi.fn(() => 'id'), get: vi.fn(() => ({ fetch: containerFetch })) },
+    BROWSER: { binding: true } as unknown as Fetcher,
+    API_TOKEN,
+    GOOGLE_EMAIL: 'user@example.com',
+    GOOGLE_PASSWORD: 'hunter2',
+  } as unknown as Env;
+  return { env, containerFetch };
+}
+
+function loginRequest(body: Record<string, unknown> = {}) {
+  return new Request('https://worker.example/', {
+    method: 'POST',
+    headers: { authorization: `Bearer ${API_TOKEN}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ action: 'login', ...body }),
+  });
+}
+
+let close: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  page = createPage();
+  close = vi.fn(async () => {});
+  setLaunchImpl(async () => ({ newPage: async () => page, close }));
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+/** handleLogin awaits fixed delays; advance them while the promise is pending. */
+async function runLogin(request: Request, env: Env) {
+  const promise = worker.fetch(request, env);
+  await vi.runAllTimersAsync();
+  return promise;
+}
+
+describe('handleLogin', () => {
+  it('navigates to NotebookLM and signs in with the configured credentials', async () => {
+    const { env } = createEnv();
+
+    const res = await runLogin(loginRequest(), env);
+
+    expect(res.status).toBe(200);
+    expect(page.goto).toHaveBeenCalledWith('https://notebooklm.google.com', {
+      waitUntil: 'networkidle0',
+    });
+    expect(page.typed).toEqual([
+      { selector: 'input[type="email"]', value: 'user@example.com' },
+      { selector: 'input[type="password"]', value: 'hunter2' },
+    ]);
+    expect(page.clicked).toEqual(['#identifierNext', '#passwordNext']);
+  });
+
+  it('sets a desktop user agent before navigating', async () => {
+    const { env } = createEnv();
+
+    await runLogin(loginRequest(), env);
+
+    expect(page.setUserAgent).toHaveBeenCalledWith(expect.stringContaining('Mozilla/5.0'));
+  });
+
+  it('stores the harvested cookies and localStorage on the container', async () => {
+    const { env, containerFetch } = createEnv();
+
+    await runLogin(loginRequest(), env);
+
+    const [url, init] = containerFetch.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('http://container/store-auth');
+    const stored = JSON.parse(init.body as string);
+    expect(stored.cookies).toEqual([{ name: 'SID', value: 'abc' }]);
+    expect(stored.localStorage).toEqual({ token: 'xyz' });
+    expect(stored.timestamp).toEqual(expect.any(String));
+  });
+
+  it('reports success with the cookie count', async () => {
+    const { env } = createEnv();
+
+    const res = await runLogin(loginRequest(), env);
+
+    expect(await res.json()).toEqual({
+      success: true,
+      message: 'Login complete, auth stored for container',
+      cookieCount: 1,
+    });
+  });
+
+  it('skips the 2FA step when no security code is supplied', async () => {
+    const { env } = createEnv();
+
+    await runLogin(loginRequest(), env);
+
+    expect(page.$).not.toHaveBeenCalled();
+  });
+
+  it('enters a supplied security code and submits it', async () => {
+    const typedCode: string[] = [];
+    const codeInput = { type: vi.fn(async (value: string) => void typedCode.push(value)) };
+    const nextBtn = { click: vi.fn(async () => {}) };
+    page = createPage({
+      $: vi.fn(async (selector: string) =>
+        selector.includes('tel') ? codeInput : nextBtn
+      ),
+    });
+    setLaunchImpl(async () => ({ newPage: async () => page, close }));
+    const { env } = createEnv();
+
+    await runLogin(loginRequest({ securityCode: '123456' }), env);
+
+    expect(typedCode).toEqual(['123456']);
+    expect(nextBtn.click).toHaveBeenCalled();
+  });
+
+  it('tolerates the 2FA input not being present', async () => {
+    const { env } = createEnv();
+
+    const res = await runLogin(loginRequest({ securityCode: '123456' }), env);
+
+    expect(res.status).toBe(200);
+  });
+
+  it('returns 500 with the failure detail when a step throws', async () => {
+    page = createPage({
+      waitForSelector: vi.fn(async () => {
+        throw new Error('email field never appeared');
+      }),
+    });
+    setLaunchImpl(async () => ({ newPage: async () => page, close }));
+    const { env } = createEnv();
+
+    const res = await runLogin(loginRequest(), env);
+
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({
+      error: 'Login failed',
+      detail: 'email field never appeared',
+    });
+  });
+
+  it('reports a non-Error throw as an unknown error', async () => {
+    page = createPage({
+      waitForSelector: vi.fn(async () => {
+        throw 'just a string';
+      }),
+    });
+    setLaunchImpl(async () => ({ newPage: async () => page, close }));
+    const { env } = createEnv();
+
+    const res = await runLogin(loginRequest(), env);
+
+    expect(await res.json()).toEqual({ error: 'Login failed', detail: 'Unknown error' });
+  });
+
+  it('closes the browser on both the success and failure paths', async () => {
+    const { env } = createEnv();
+    await runLogin(loginRequest(), env);
+    expect(close).toHaveBeenCalledTimes(1);
+
+    page = createPage({
+      goto: vi.fn(async () => {
+        throw new Error('nope');
+      }),
+    });
+    const secondClose = vi.fn(async () => {});
+    setLaunchImpl(async () => ({ newPage: async () => page, close: secondClose }));
+
+    await runLogin(loginRequest(), createEnv().env);
+    expect(secondClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('never reaches the container run endpoint for a login action', async () => {
+    const { env, containerFetch } = createEnv();
+
+    await runLogin(loginRequest(), env);
+
+    const urls = containerFetch.mock.calls.map((call) => call[0]);
+    expect(urls).not.toContain('http://container/run');
+  });
+});

package/test/stubs/cloudflare-workers.ts

@@ -0,0 +1,20 @@
+/**
+ * Stand-in for the `cloudflare:workers` runtime module, which only resolves
+ * inside workerd. `NotebookRunner` extends `Container` purely to inherit
+ * lifecycle plumbing, so an empty base class is enough to import the worker.
+ */
+export class Container {
+  ctx: {
+    container: { start: (options: unknown) => void };
+    storage: { get: <T>(key: string) => Promise<T | undefined> };
+  };
+
+  constructor() {
+    this.ctx = {
+      container: { start: () => {} },
+      storage: { get: async () => undefined },
+    };
+  }
+}
+
+export class DurableObject {}

package/test/stubs/puppeteer.ts

@@ -0,0 +1,18 @@
+import { vi } from 'vitest';
+
+/**
+ * Stand-in for `@cloudflare/puppeteer`. Tests swap in their own page/browser
+ * behaviour via `setLaunchImpl`; the default is a browser that never resolves
+ * a selector, which is the "login page did not appear" path.
+ */
+let launchImpl: (binding: unknown) => Promise<unknown> = async () => {
+  throw new Error('launch not stubbed');
+};
+
+export function setLaunchImpl(impl: (binding: unknown) => Promise<unknown>) {
+  launchImpl = impl;
+}
+
+export const launch = vi.fn((binding: unknown) => launchImpl(binding));
+
+export default { launch };

package/test/worker.test.ts

@@ -0,0 +1,202 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import worker, { NotebookRunner, type Env, type NotebookJob } from '../src/index';
+
+const API_TOKEN = 'test-token';
+
+function createEnv(overrides: Partial<Env> = {}) {
+  const containerFetch = vi.fn(
+    async () => new Response(JSON.stringify({ ok: true }), { status: 200 })
+  );
+  const stub = { fetch: containerFetch };
+  const idFromName = vi.fn(() => 'do-id');
+  const get = vi.fn(() => stub);
+
+  const env = {
+    NOTEBOOK_RUNNER: { idFromName, get },
+    BROWSER: {} as Fetcher,
+    API_TOKEN,
+    GOOGLE_EMAIL: 'user@example.com',
+    GOOGLE_PASSWORD: 'hunter2',
+    ...overrides,
+  } as unknown as Env;
+
+  return { env, containerFetch, idFromName, get };
+}
+
+function post(body: unknown, { token = API_TOKEN }: { token?: string | null } = {}) {
+  const headers: Record<string, string> = { 'content-type': 'application/json' };
+  if (token !== null) headers.authorization = `Bearer ${token}`;
+  return new Request('https://worker.example/', {
+    method: 'POST',
+    headers,
+    body: typeof body === 'string' ? body : JSON.stringify(body),
+  });
+}
+
+describe('worker fetch: CORS preflight', () => {
+  it('answers OPTIONS with permissive CORS headers and no body', async () => {
+    const { env } = createEnv();
+
+    const res = await worker.fetch(new Request('https://worker.example/', { method: 'OPTIONS' }), env);
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get('access-control-allow-origin')).toBe('*');
+    expect(res.headers.get('access-control-allow-methods')).toBe('POST, OPTIONS');
+    expect(res.headers.get('access-control-allow-headers')).toBe('content-type, authorization');
+    expect(await res.text()).toBe('');
+  });
+
+  it('does not require authorization for the preflight', async () => {
+    const { env, get } = createEnv();
+
+    const res = await worker.fetch(new Request('https://worker.example/', { method: 'OPTIONS' }), env);
+
+    expect(res.status).toBe(200);
+    expect(get).not.toHaveBeenCalled();
+  });
+});
+
+describe('worker fetch: method and auth guards', () => {
+  it.each(['GET', 'PUT', 'DELETE'])('rejects %s with 405', async (method) => {
+    const { env } = createEnv();
+
+    const res = await worker.fetch(new Request('https://worker.example/', { method }), env);
+
+    expect(res.status).toBe(405);
+    expect(await res.json()).toEqual({ error: 'Method not allowed' });
+  });
+
+  it('rejects a missing authorization header with 401', async () => {
+    const { env } = createEnv();
+
+    const res = await worker.fetch(post({ action: 'list' }, { token: null }), env);
+
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: 'Unauthorized' });
+  });
+
+  it('rejects a wrong bearer token with 401', async () => {
+    const { env } = createEnv();
+
+    const res = await worker.fetch(post({ action: 'list' }, { token: 'nope' }), env);
+
+    expect(res.status).toBe(401);
+  });
+
+  it('never reaches the container when unauthorized', async () => {
+    const { env, containerFetch } = createEnv();
+
+    await worker.fetch(post({ action: 'list' }, { token: 'nope' }), env);
+
+    expect(containerFetch).not.toHaveBeenCalled();
+  });
+});
+
+describe('worker fetch: request body validation', () => {
+  it('rejects a malformed JSON body with 400', async () => {
+    const { env } = createEnv();
+
+    const res = await worker.fetch(post('{not json'), env);
+
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({ error: 'Invalid JSON body' });
+  });
+
+  it('rejects a body with no action with 400', async () => {
+    const { env } = createEnv();
+
+    const res = await worker.fetch(post({ notebookId: 'abc' }), env);
+
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({ error: 'Missing action field' });
+  });
+});
+
+describe('worker fetch: container proxying', () => {
+  const actions: NotebookJob['action'][] = ['create', 'ask', 'summarize', 'list', 'delete'];
+
+  it.each(actions)('forwards the %s job to the container', async (action) => {
+    const { env, containerFetch, idFromName } = createEnv();
+    const job = { action, notebookId: 'nb-1' };
+
+    await worker.fetch(post(job), env);
+
+    expect(idFromName).toHaveBeenCalledWith('default');
+    const [url, init] = containerFetch.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('http://container/run');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body as string)).toEqual(job);
+  });
+
+  it('passes the container response body and status straight through', async () => {
+    const { env, containerFetch } = createEnv();
+    containerFetch.mockResolvedValue(
+      new Response(JSON.stringify({ notebookId: 'nb-9' }), { status: 201 })
+    );
+
+    const res = await worker.fetch(post({ action: 'create' }), env);
+
+    expect(res.status).toBe(201);
+    expect(await res.json()).toEqual({ notebookId: 'nb-9' });
+  });
+
+  it('propagates a container error status', async () => {
+    const { env, containerFetch } = createEnv();
+    containerFetch.mockResolvedValue(new Response(JSON.stringify({ error: 'boom' }), { status: 500 }));
+
+    const res = await worker.fetch(post({ action: 'ask', prompt: 'why' }), env);
+
+    expect(res.status).toBe(500);
+    expect(await res.json()).toEqual({ error: 'boom' });
+  });
+
+  it('always answers with JSON and CORS headers', async () => {
+    const { env } = createEnv();
+
+    const res = await worker.fetch(post({ action: 'list' }), env);
+
+    expect(res.headers.get('content-type')).toBe('application/json');
+    expect(res.headers.get('access-control-allow-origin')).toBe('*');
+  });
+});
+
+describe('NotebookRunner', () => {
+  it('is configured for port 8080 with a 5 minute idle timeout', () => {
+    const runner = new NotebookRunner();
+
+    expect(runner.defaultPort).toBe(8080);
+    expect(runner.sleepAfter).toBe('5m');
+  });
+
+  it('starts the container with stored auth and internet enabled', async () => {
+    const runner = new NotebookRunner();
+    const start = vi.fn();
+    runner.ctx = {
+      container: { start },
+      storage: { get: vi.fn(async () => 'stored-auth-json') },
+    } as never;
+
+    await runner.onStart();
+
+    expect(start).toHaveBeenCalledWith({
+      env: { NOTEBOOKLM_AUTH_JSON: 'stored-auth-json' },
+      enableInternet: true,
+    });
+  });
+
+  it('passes an empty auth string when nothing is stored yet', async () => {
+    const runner = new NotebookRunner();
+    const start = vi.fn();
+    runner.ctx = {
+      container: { start },
+      storage: { get: vi.fn(async () => undefined) },
+    } as never;
+
+    await runner.onStart();
+
+    expect(start).toHaveBeenCalledWith({
+      env: { NOTEBOOKLM_AUTH_JSON: '' },
+      enableInternet: true,
+    });
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,28 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+const dir = fileURLToPath(new URL('.', import.meta.url));
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      // Both of these only resolve inside workerd; test/stubs supplies the
+      // small slice of their surface that src/index.ts actually touches.
+      'cloudflare:workers': resolve(dir, 'test/stubs/cloudflare-workers.ts'),
+      '@cloudflare/puppeteer': resolve(dir, 'test/stubs/puppeteer.ts'),
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['test/**/*.test.ts'],
+    restoreMocks: true,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      include: ['src/**/*.ts'],
+      exclude: ['node_modules/**', 'dist/**', '**/*.test.ts'],
+    },
+  },
+});