@bufinance/events
v0.1.0
Published
OpenPanel analytics wrapper for BUFI apps: Provider + client track() + server setupAnalytics() + api-tracker + the canonical LogEvents registry. Ships TS source (consume via Next.js transpilePackages). Shared by desk-v1 and defi-web-app.
Readme
@bufinance/events
OpenPanel analytics wrapper for BUFI apps. Shared by desk-v1 and defi-web-app
(fx). Extracted as a standalone, publishable package so multiple apps can install
it from npm.
It provides:
- A client
<Provider/>(wrapsOpenPanelComponent) for the root layout. - A client
track({ event, ...props })hook helper. - A server
setupAnalytics()for server components / actions (identify + track). - An
apiTrackerfor API routes (typed fintech volume events: transfers, ramps, payroll, KYC/KYB, fees, subscriptions, virtual accounts, cards, sessions, …). - The canonical
LogEventsregistry (event name + channel) plus analytics helper functions (getChannelSummary,searchEvents, funnel definitions, …).
Ships TypeScript source
This package ships .ts/.tsx source (no build step). Consumers transpile it
via Next.js transpilePackages — same pattern as @bufinance/web3-signin.
Environment variables
| Var | Scope | Used by |
|---|---|---|
| NEXT_PUBLIC_OPENPANEL_CLIENT_ID | public (client + server) | Provider, setupAnalytics, apiTracker |
| OPENPANEL_SECRET_KEY | server-only secret | setupAnalytics, apiTracker |
The client id is a NEXT_PUBLIC_* value, so Next.js inlines it at build time. The
secret key is server-only and must never be exposed to the browser.
Install
npm install @bufinance/events
# or
bun add @bufinance/events.npmrc
@bufinance/* packages publish to the public npm registry under the @bufinance
scope. If your install needs an auth token (private registry / CI), configure it in
.npmrc — do not commit the token. For example:
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
@bufinance:registry=https://registry.npmjs.org…and provide NPM_TOKEN via the environment.
Consume
1. Transpile the package
next.config.ts (or .js):
const nextConfig = {
transpilePackages: ['@bufinance/events'],
};
export default nextConfig;2. Render <Provider/> in the root layout
// app/layout.tsx
import { Provider as AnalyticsProvider } from '@bufinance/events/client';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<AnalyticsProvider />
</body>
</html>
);
}3. Track events on the client
'use client';
import { track } from '@bufinance/events/client';
function PricingPage() {
// fire when the pricing view is shown
track({ event: 'pricing_viewed', channel: 'engagement', plan: 'pro' });
return null;
}4. Track on the server
import { setupAnalytics } from '@bufinance/events/server';
const analytics = await setupAnalytics({ userId, fullName });
analytics.track({ event: 'pricing_viewed', channel: 'engagement' });5. Track volume events from API routes
import { apiTracker } from '@bufinance/events/api-tracker';
await apiTracker.trackTransfer('completed', {
amount: 100,
currency: 'USDC',
user_id: userId,
});Subpath exports
| Import | Contents |
|---|---|
| @bufinance/events | Provider, track, the full LogEvents registry + helpers (client-safe barrel) |
| @bufinance/events/client | Provider, track |
| @bufinance/events/server | setupAnalytics ('use server' — server-only) |
| @bufinance/events/events | LogEvents + analytics helpers + types |
| @bufinance/events/api-tracker | apiTracker, buildCohortTags, types (server-only) |
server.ts and api-tracker.ts are intentionally subpath-only and are NOT
re-exported from the root barrel (server-only code must not leak into client
bundles).