Keen plugin

• The project ID, which is part of every request path. Connect delivers it beside the key; the projectId plugin option overrides it.
• The key itself, sent bare in the Authorization header. Keen adds no Bearer scheme, and a key with one is rejected.

• A read key cannot write, and a write key cannot read. Keen answers 403 when the key’s kind does not permit the call. The plugin cannot tell which kind arrived, so a 403 usually means the key is the wrong kind rather than the wrong key.
• Events take a moment to be queryable. Keen acknowledges events.record at once but says it can take up to 10 seconds before the event appears in a query.
• events.recordMany partly succeeds. It answers one result per event, keyed by collection, and an entry with success: false was not stored. Keen recommends batches of 5,000 or less.
• Queries are POSTs but read nothing back into Keen. queries.run and queries.multiAnalysis send the analysis as a body. Because the method is POST, they are not replayed after a 5xx; a count that failed mid-way is safe to send again, and the caller can.
• A query has five minutes. Past that Keen stops it and answers 504 QueryIncompleteError. The plugin raises isQueryIncomplete and does not retry, because the same query would take as long again; narrow the timeframe instead.
• Every analysis but count and funnel needs a target_property, and percentile also needs its percentile value. A funnel takes steps, each with its own event_collection and actor_property, instead of a top-level collection. These are checked before the request, so a malformed analysis costs no call.
• Cached results. A saved query’s refresh_rate is 0 (no cache) or 14400 to 86400 seconds (four to 24 hours). savedQueries.result reads the cached answer, which is what makes a dashboard load instantly.
• Datasets page by cursor. datasets.list returns next_after_name, read out of Keen’s next_page_url; pass it back as after_name.
• Rate limits are per project, not per key. A 429 blocks that endpoint category for the next minute, and Keen sends no Retry-After, so the plugin waits a minute before its next attempt.
• Webhooks. The plugin does not receive Keen webhooks; none are configured here.

• 16 typed API operations

Setup

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

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

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

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

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

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

keen()

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

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.keen.api.queries.multiAnalysis({
	event_collection: 'purchases',
	analyses: {
		purchases: { analysis_type: 'count' },
		revenue: { analysis_type: 'sum', target_property: 'price' },
	},
	timeframe: 'this_7_days',
});

const tenant = corsair.withTenant('acme');
await tenant.keen.api.events.record({
	collection: 'purchases',
	event: { item: 'Avocado', number_of_items: 10 },
});

What’s next