Corsair
PluginsAmplitude

Amplitude

Integrate Amplitude analytics, events, and cohorts

Quick Start

Install the plugin:

pnpm install @corsair-dev/amplitude

Add the Amplitude plugin to your Corsair instance:

corsair.ts
import { createCorsair } from "corsair";
import { amplitude } from "@corsair-dev/amplitude";

export const corsair = createCorsair({
    plugins: [
        amplitude(),
    ],
});

Once configured, you can track events and manage analytics data:

// Track an event
await corsair.amplitude.api.events.upload({
    api_key: "your-api-key",
    events: [{
        event_type: "page_view",
        user_id: "user-123",
    }],
});

Authentication

Supported Auth Types

The Amplitude plugin supports:

  • api_key (default) - Use an Amplitude API key

Default Auth Type

If no authType is specified, the plugin defaults to api_key.

Configuring API Key Authentication

Store credentials with the CLI:

pnpm corsair setup --amplitude api_key=your-api-key

For webhook signature verification:

pnpm corsair setup --amplitude webhook_signature=your-webhook-secret

Alternatively, provide credentials directly in the config:

corsair.ts
amplitude({
    key: process.env.AMPLITUDE_API_KEY,
    webhookSecret: process.env.AMPLITUDE_WEBHOOK_SECRET,
})

See Authentication for details on managing credentials.

Options

OptionTypeDescription
authType'api_key'Authentication method (defaults to 'api_key')
keystringAPI key (optional, uses database if not provided)
webhookSecretstringWebhook secret for signature verification
hooksobjectEndpoint hooks for custom logic
webhookHooksobjectWebhook hooks for event handling
errorHandlersobjectCustom error handlers
permissionsobjectPermission configuration for AI agent access

Hooks

amplitude({
    hooks: {
        events: {
            upload: {
                before: async (ctx, input) => {
                    console.log("Uploading events:", input.events.length);
                    return { ctx, input };
                },
            },
        },
    },
})

See Hooks for complete documentation.

Error Handling

The plugin includes built-in error handlers for common scenarios. For complete documentation, see the Error Handlers reference.

Usage

Accessing the API

// Upload events
await corsair.amplitude.api.events.upload({
    api_key: "your-api-key",
    events: [{
        event_type: "purchase",
        user_id: "user-123",
        event_properties: { item: "Pro Plan", price: 99 },
    }],
});

// Search for a user
const user = await corsair.amplitude.api.users.search({
    user_id: "user-123",
});

// Create a cohort
await corsair.amplitude.api.cohorts.create({
    name: "Power Users",
    app_id: 12345,
    id_type: "BY_USER_ID",
    ids: ["user-1", "user-2", "user-3"],
});

See API Endpoints for the complete reference.

Webhooks

app/api/webhook/route.ts
import { processWebhook } from "corsair";
import { corsair } from "@/server/corsair";

export async function POST(request: Request) {
    const headers = Object.fromEntries(request.headers);
    const body = await request.json();

    const result = await processWebhook(corsair, headers, body);
    return result.response;
}

See Webhooks for all available events.

Database Access

const events = await corsair.amplitude.db.events.search({
    data: { event_type: "purchase" },
});

See Database for the complete schema.

Multi-Tenancy

const tenant = corsair.withTenant("org-123");

await tenant.amplitude.api.events.upload({
    api_key: "tenant-api-key",
    events: [{ event_type: "page_view", user_id: "u1" }],
});

Examples

Example 1: Track User Actions

inngest/functions.ts
export const trackUserAction = inngest.createFunction(
    { id: "track-amplitude-event" },
    { event: "app/user-action" },
    async ({ event }) => {
        const tenant = corsair.withTenant(event.data.tenantId);

        await tenant.amplitude.api.events.upload({
            api_key: event.data.apiKey,
            events: [{
                event_type: event.data.action, 
                user_id: event.data.userId, 
                time: Date.now(),
                event_properties: event.data.properties,
            }],
        });
    }
);

Example 2: Build a Cohort from Recent Signups

inngest/functions.ts
export const buildSignupCohort = inngest.createFunction(
    { id: "build-signup-cohort" },
    { cron: "0 0 * * 1" },
    async () => {
        const recentSignups = await corsair.amplitude.db.users.search({
            data: { createdAt: { gte: new Date(Date.now() - 7 * 86400000) } }, 
            limit: 1000,
        });

        await corsair.amplitude.api.cohorts.create({
            name: "Last 7 Day Signups",
            app_id: 12345,
            id_type: "BY_USER_ID",
            ids: recentSignups.data.map(u => u.user_id), 
        });
    }
);

Example 3: Monitor Alert Webhook

corsair.ts
export const corsair = createCorsair({
    plugins: [
        amplitude({
            webhookHooks: {
                monitors: {
                    alert: {
                        after: async (ctx, result) => {
                            await inngest.send({
                                name: "amplitude/monitor-alert",
                                data: {
                                    tenantId: ctx.tenantId,
                                    monitorId: result.data.monitor_id, 
                                    metricValue: result.data.metric_value,
                                },
                            });
                        },
                    },
                },
            },
        }),
    ],
});

Error Handlers

Previous Page

API Endpoints

Next Page

On this page

Quick Start
Authentication
Supported Auth Types
Default Auth Type
Configuring API Key Authentication
Options
Hooks
Error Handling
Usage
Accessing the API
Webhooks
Database Access
Multi-Tenancy
Examples
Example 1: Track User Actions
Example 2: Build a Cohort from Recent Signups
Example 3: Monitor Alert Webhook