feat(browser-pools): typed acquire helper distinguishing got / timed-out

Add `acquireBrowserFromPool` returning a discriminated union — `{ status:
'acquired', browser }` on 200 or `{ status: 'timed_out' }` on 204 — so
callers can disambiguate the long-poll timeout from a successful lease
without inspecting the raw HTTP status. 404 continues to reject with the
existing `NotFoundError`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Jayko001

src/index.ts

@@ -7,6 +7,7 @@ export { APIPromise } from './core/api-promise';
 export { Kernel, type ClientOptions } from './client';
 export { type BrowserFetchInit } from './lib/browser-fetch';
 export { BrowserRouteCache, type BrowserRoute } from './lib/browser-routing';
+export { acquire as acquireBrowserFromPool, type AcquireOutcome } from './lib/browser-pools';
 export { PagePromise } from './core/pagination';
 export {
   KernelError,

src/lib/browser-pools.ts

@@ -0,0 +1,31 @@
+import type { Kernel } from '../client';
+import type { RequestOptions } from '../internal/request-options';
+import type { BrowserPoolAcquireParams, BrowserPoolAcquireResponse } from '../resources/browser-pools';
+
+export type AcquireOutcome =
+  | { status: 'acquired'; browser: BrowserPoolAcquireResponse }
+  | { status: 'timed_out' };
+
+/**
+ * Long-polling acquire that surfaces the HTTP outcome as a typed result.
+ *
+ * Resolves to one of:
+ *
+ * - `{ status: 'acquired', browser }` — a browser was leased from the pool.
+ * - `{ status: 'timed_out' }` — the long poll expired without a browser becoming
+ *   available. Retry to keep waiting.
+ *
+ * Rejects with `NotFoundError` if the pool does not exist.
+ */
+export async function acquire(
+  client: Kernel,
+  idOrName: string,
+  body: BrowserPoolAcquireParams = {},
+  options?: RequestOptions,
+): Promise<AcquireOutcome> {
+  const { data, response } = await client.browserPools.acquire(idOrName, body, options).withResponse();
+  if (response.status === 204) {
+    return { status: 'timed_out' };
+  }
+  return { status: 'acquired', browser: data };
+}

tests/lib/browser-pools.test.ts

@@ -0,0 +1,41 @@
+import Kernel, { NotFoundError } from '@onkernel/sdk';
+
+import { acquire, type AcquireOutcome } from '../../src/lib/browser-pools';
+
+const baseBrowser = {
+  session_id: 'sess-1',
+  base_url: 'http://browser-session.test/browser/kernel',
+  cdp_ws_url: 'wss://browser-session.test/browser/cdp?jwt=t',
+  webdriver_ws_url: 'wss://x',
+  created_at: '2020-01-01T00:00:00Z',
+  headless: true,
+  stealth: false,
+  timeout_seconds: 60,
+};
+
+const clientWith = (fetcher: typeof fetch) =>
+  new Kernel({ apiKey: 'k', baseURL: 'https://api.example/', fetch: fetcher });
+
+describe('browser pool typed acquire', () => {
+  test('resolves to acquired on 200', async () => {
+    const client = clientWith(async () => Response.json(baseBrowser));
+    const result: AcquireOutcome = await acquire(client, 'my-pool');
+    expect(result.status).toBe('acquired');
+    if (result.status === 'acquired') {
+      expect(result.browser.session_id).toBe('sess-1');
+    }
+  });
+
+  test('resolves to timed_out on 204', async () => {
+    const client = clientWith(async () => new Response(null, { status: 204 }));
+    const result = await acquire(client, 'my-pool');
+    expect(result.status).toBe('timed_out');
+  });
+
+  test('rejects with NotFoundError on 404', async () => {
+    const client = clientWith(async () =>
+      Response.json({ code: 'not_found', message: 'pool not found' }, { status: 404 }),
+    );
+    await expect(acquire(client, 'missing')).rejects.toBeInstanceOf(NotFoundError);
+  });
+});