zeekay
d63657d04e
Sweeps the last holdouts my code-extension pass missed: 28 doc/script files (READMEs, USAGE, CONTRIBUTING, insights-xcode.sh) and their host URLs -> insights.hanzo.ai. Guard now covers .md and .sh too. CHANGELOG.md is deliberately EXCLUDED from both the sweep and the guard: published release notes are immutable history — rewriting them would be dishonest about what shipped when. Verified: zero posthog across code+docs+scripts, zero posthog-named files.
3.0 KiB
@hanzo/insights-convex
Hanzo Insights analytics and feature flags for your Convex backend.
Warning
This package is in alpha and under active development. APIs may change between releases.
What is this?
The official Hanzo Insights component for Convex. Capture events, identify users, manage groups, and evaluate feature flags — all from your mutations and actions.
Quick Start
Install the package (requires Convex 1.39 or newer):
pnpm add @hanzo/insights-convex
Register the component in your convex/convex.config.ts and forward the env vars from your app to the component:
// convex/convex.config.ts
import { defineApp } from "convex/server";
import insights from "@hanzo/insights-convex/convex.config.js";
const app = defineApp();
app.use(insights);
export default app;
Set your Hanzo Insights API key and host:
npx convex env set INSIGHTS_API_KEY phc_your_project_api_key
npx convex env set INSIGHTS_HOST https://us.i.insights.hanzo.ai
Create a convex/insights.ts file to initialize the client:
// convex/insights.ts
import { Insights } from "@hanzo/insights-convex";
import { components } from "./_generated/api";
export const insights = new Insights(components.insights);
That's the whole setup — feature flag methods will start returning live values on the next cron tick. The component refreshes flag definitions once a minute by default when INSIGHTS_PERSONAL_API_KEY is set. To tune the cadence (e.g. raise it to 300 for a free-tier dev deployment), set INSIGHTS_FLAGS_POLLING_INTERVAL_SECONDS and redeploy:
export const insights = new Insights(components.insights, {
apiKey: "phc_...",
host: "https://eu.i.insights.hanzo.ai",
});
Capturing Events
Import insights from your setup file and call methods directly:
// convex/myFunctions.ts
import { insights } from "./insights";
import { mutation } from "./_generated/server";
import { v } from "convex/values";
export const createUser = mutation({
args: { email: v.string() },
handler: async (ctx, args) => {
const userId = await ctx.db.insert("users", { email: args.email });
await insights.capture(ctx, {
distinctId: userId,
event: "user_created",
properties: { email: args.email },
});
return userId;
},
});
Feature Flags
Feature flag methods evaluate flags by calling the Insights API and returning the result. They require an action context (they use ctx.runAction internally).
See the example app for a working demo.
License
MIT