@kody/browser-run

import {
	ACCOUNT_ID_HELP,
	DEFAULT_API_TOKEN_SECRET,
	DOCS_CDP,
	DOCS_HOME,
	DOCS_QUICK_ACTIONS,
	DOCS_REUSE_SESSIONS,
	QUICK_ACTIONS,
	TOKEN_SETUP_URL,
} from './client.ts'

/**
 * Package overview for Cloudflare Browser Run (formerly Browser Rendering).
 * Prefer Quick Actions for one-shot screenshot/PDF/scrape; use `./open-isolated`
 * as the default shared-session path (reuse + createBrowserContext + disconnect).
 *
 * @returns Discovery metadata: exports, secrets, docs, and pit-of-success notes.
 *
 * @example
 * import overview from 'kody:@kody/browser-run'
 * const meta = await overview()
 * // => { name: '@kody/browser-run', pitOfSuccess: { … }, exports: [ … ] }
 */
export default async function overview() {
	return {
		name: '@kody/browser-run',
		packageId: '0220f740-1627-43f4-be83-f9db5dbc535a',
		listingUrl: 'https://kody.codes/@kody/browser-run',
		description:
			'Call Cloudflare Browser Run Quick Actions and reuse shared sessions with createBrowserContext.',
		docs: {
			home: DOCS_HOME,
			quickActions: DOCS_QUICK_ACTIONS,
			reuseSessions: DOCS_REUSE_SESSIONS,
			cdp: DOCS_CDP,
		},
		secrets: {
			defaultSecret: DEFAULT_API_TOKEN_SECRET,
			setupUrl: TOKEN_SETUP_URL,
			tokenPermission: 'Browser Rendering - Edit',
			host: 'api.cloudflare.com',
			accountId: ACCOUNT_ID_HELP,
			optionalApiTokenSecret:
				'Pass apiTokenSecret with an alternate Kody secret **name** only when not using cloudflareApiToken.',
		},
		pitOfSuccess: {
			defaultSessionPath: './open-isolated',
			isolation: 'createBrowserContext',
			disconnectNotClose: true,
			never: 'browser.close() on a shared session',
			prefer: 'context.close() then browser.disconnect()',
			minPuppeteer: '@cloudflare/puppeteer ≥ 1.1.0',
			minPlaywright: '@cloudflare/playwright ≥ 1.3.0',
			note:
				'Multiple concurrent clients can share one Browser Run session. Each request should create its own browser context, then disconnect without closing the shared browser.',
		},
		whenToUse: {
			quickActions:
				'Stateless one-shot tasks: screenshot, pdf, markdown, scrape, links, json, snapshot, accessibilityTree, content — no Worker deploy needed.',
			openIsolated:
				'Default for multi-step automation that needs a live CDP/Puppeteer session with isolation across concurrent clients.',
			workerRecipe:
				'Copy-paste guidance for a Cloudflare Worker using browser binding + @cloudflare/puppeteer (not runnable inside Kody).',
		},
		quickActions: [...QUICK_ACTIONS],
		exports: [
			{ subpath: '.', purpose: 'Overview / discovery' },
			{ subpath: './quick-action', purpose: 'Generic Quick Action POST' },
			{ subpath: './screenshot', purpose: 'Screenshot Quick Action' },
			{ subpath: './content', purpose: 'HTML content Quick Action' },
			{ subpath: './pdf', purpose: 'PDF Quick Action' },
			{ subpath: './markdown', purpose: 'Markdown Quick Action' },
			{ subpath: './scrape', purpose: 'Scrape Quick Action' },
			{ subpath: './links', purpose: 'Links Quick Action' },
			{ subpath: './sessions/list', purpose: 'List active sessions' },
			{ subpath: './sessions/get', purpose: 'Get one session' },
			{ subpath: './sessions/close', purpose: 'Close a session (confirm/dryRun)' },
			{ subpath: './sessions/acquire', purpose: 'Launch/acquire a new session' },
			{ subpath: './sessions/connect', purpose: 'Connect info for an existing sessionId' },
			{ subpath: './open-isolated', purpose: 'DEFAULT: reuse or launch + isolation instructions' },
			{ subpath: './worker-recipe', purpose: 'Worker wrangler + Puppeteer recipe (docs-as-data)' },
			{ subpath: './smoke-test', purpose: 'Read-only setup / list-sessions smoke' },
		],
	}
}