Overview

• Adding a page writes to your account. monitoring.addPage adds a URL to monitoring and returns the siteId, sessionId and pageId. Pass siteId and sessionId together to add the page to an existing site. When you do, Fluxguard rejects siteNickname and every category option with 400 (“Site settings (categories, nickname) cannot be specified as the site already exists”), so the plugin refuses that combination before sending. Omit both to create a new site, optionally with siteNickname and a category.
• Crawls run in the background and spend credits. monitoring.startCrawl answers 204 as soon as the crawl is queued. Read the capture with monitoring.getPage; the trigger response repeats the ids it accepted.
• Deletes cannot be undone. monitoring.deletePage drops the page and every version captured for it, and monitoring.deleteSite drops the site with all of its sessions, pages and versions. Both answer 204. A deleted page still answers monitoring.getPage, with status: 'ignore', so the id keeps resolving.
• Webhooks fire on every change. webhooks.create takes a URL and returns an id; from then on every detected change is POSTed there, which is a lot of data on an active account. Only url is honoured: siteCategories and categories are accepted and silently ignored, so assign categories in the console. webhooks.delete takes the id in the request body, and webhooks.sample returns an array of example changes from your own account.
• categories.create makes site categories only. Site and page categories are stored separately and each row carries a for field saying which. categories.list restores the id Fluxguard keeps only as the map key. Pages report their categories as arrays of names, not ids.
• Rate limits and errors. Fluxguard does not document a limit or a Retry-After header, and fifteen parallel requests all answered 200, so no limit was observed. The plugin retries a 429 up to three times with backoff if one appears, and never retries a 403: that status covers a bad key (Forbidden) and a route that does not exist (Missing Authentication Token). Every error body is { message }.
• Inbound webhooks. Fluxguard signs each delivery with the webhook’s own secret key: fluxguard-signature: t=<unix seconds>,v1=<hex HMAC-SHA256> over <t>.<raw body>. Set webhookSecret, or store the key with keys.set_webhook_signature. Verification needs the untouched request body, so mount the webhook route without a JSON parser. With multiTenancy, your own route chooses the tenant: register each tenant’s webhook URL with ?tenantId=<id> and pass that to processWebhook, or the delivery is checked against the default tenant. Corsair Hub looks the tenant up by the delivery’s orgId instead, and only after you store it with corsair.withTenant(id).fluxguard.keys.set_tenant_external_id(orgId) (the id that account.get returns).

• 12 typed API operations
• 1 incoming webhook event types

​

Setup

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

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

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

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

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

export const corsair = createCorsair({
	plugins: [
		fluxguard(),
	],
	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!,
	},
});

fluxguard()

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

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.fluxguard.api.monitoring.getPage({ siteId: '0123jdq6th8dc', sessionId: '0123jdqze3cbg', pageId: '0123jdu8r4724' });

const tenant = corsair.withTenant('acme');
await tenant.fluxguard.api.monitoring.addPage({ url: 'https://example.org/pricing', siteNickname: 'Pricing' });

​

Webhooks

fluxguard({
    webhookHooks: {
        change: {
            detected: {
                after: async (ctx, result) => {
                    console.log('Change on', result.data?.url, 'flagged', result.data?.aiFlagged);
                }
            },
        },
    },
})

​

What’s next