CustomJS plugin

• An exhausted window answers 403, not 429. The body is {"message":"Too Many Requests"}, so the plugin classifies a 403 by its body: a wrong key and an exhausted window share the status. On the free plan that 403 means the day’s quota is used up and carries no reset time, so the plugin reports CustomjsAPIError with isRateLimit at once instead of retrying. A 429, or a 403 with Retry-After, is retried up to three times.
• Files come back base64 encoded. pdf.fromHtml, pdf.fromMarkdown, screenshot.capture and javascript.runBinary return { base64, contentType, byteLength }. Decode base64 to write a file.
• javascript.run returns text, not parsed JSON. The route answers text/plain whatever the script returns, so an object arrives JSON encoded in output and a script with no return arrives empty.
• Missing required fields render blank files. CustomJS answers 200 with an empty PDF or PNG when html or url is absent, so the input schema requires them.
• scrape.agent bills model tokens. It drives a browser for up to maxSteps actions and returns its token usage. scrape.page runs your exact steps and spends none.
• Page names are not unique. pages.create publishes a new page every call, even with a name that already exists, so a retry duplicates it and the plugin never replays that call. pages.delete fails with a 404 for a page ID that does not exist.
• Stored functions are not wrapped. The docs describe calling a saved script by ID; the route answered 500 with every ID tried, so this plugin only runs code inline.

• 12 typed API operations

Setup

npm install corsair @corsair-dev/customjs better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/customjs better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/customjs better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/customjs better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { customjs } from '@corsair-dev/customjs';

export const corsair = createCorsair({
	plugins: [
		customjs(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

customjs()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'customjs',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.customjs.api.pdf.fromHtml({
	html: '<h1>Invoice #1042</h1><p>Total: {{ total }}</p>',
	data: { total: 100 },
	config: { pdfWidthMm: 210, pdfHeightMm: 297 },
});

const tenant = corsair.withTenant('acme');
await tenant.customjs.api.pages.create({ name: 'Launch page', htmlContent: '<h1>Launch day</h1>' });

What’s next