@pasosdejesus/m 0.15.0

package/dist/util/cli-parser.d.ts

@@ -0,0 +1,20 @@
+export interface FlagDef {
+    /** 'string' (consumes next arg), 'boolean' (no value), or 'number' (parseInt next arg) */
+    type: 'string' | 'boolean' | 'number';
+    /** Alternate flag name (e.g. -n for --dry-run) */
+    alias?: string;
+}
+/**
+ * Parses CLI flags after a subcommand.
+ *
+ * Usage: const { options, positional } = parseFlags(argv, flagDefs)
+ *
+ * @param argv Argument array (typically process.argv.slice(2) or slice(3))
+ * @param flags Record of flag name → definition
+ * @returns { options, positional }
+ */
+export declare function parseFlags(argv: string[], flags: Record<string, FlagDef>): {
+    options: Record<string, boolean | string | number | undefined>;
+    positional: string[];
+};
+//# sourceMappingURL=cli-parser.d.ts.map

package/dist/util/cli-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-parser.d.ts","sourceRoot":"","sources":["../../src/util/cli-parser.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,OAAO;IACtB,0FAA0F;IAC1F,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACtC,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAgC1F"}

package/dist/util/cli-parser.js

@@ -0,0 +1,38 @@
+/**
+ * Parses CLI flags after a subcommand.
+ *
+ * Usage: const { options, positional } = parseFlags(argv, flagDefs)
+ *
+ * @param argv Argument array (typically process.argv.slice(2) or slice(3))
+ * @param flags Record of flag name → definition
+ * @returns { options, positional }
+ */
+export function parseFlags(argv, flags) {
+    const options = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        // Check flag definitions by name or alias
+        let def;
+        let defKey;
+        for (const [k, d] of Object.entries(flags)) {
+            if (arg === `--${k}` || (d.alias && arg === d.alias)) {
+                def = d;
+                defKey = k;
+                break;
+            }
+        }
+        if (!def) {
+            positional.push(arg);
+            continue;
+        }
+        if (def.type === 'boolean') {
+            options[defKey] = true;
+        }
+        else if (i + 1 < argv.length) {
+            i++;
+            options[defKey] = def.type === 'number' ? parseInt(argv[i], 10) : argv[i];
+        }
+    }
+    return { options, positional };
+}

package/dist/util/colors.d.ts

@@ -0,0 +1,5 @@
+export declare const success: (message: string) => void;
+export declare const problem: (message: string) => void;
+export declare const info: (message: string) => void;
+export declare const warn: (message: string) => void;
+//# sourceMappingURL=colors.d.ts.map

package/dist/util/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/util/colors.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,GAAI,SAAS,MAAM,SAAmC,CAAC;AAC3E,eAAO,MAAM,OAAO,GAAI,SAAS,MAAM,SAAmC,CAAC;AAC3E,eAAO,MAAM,IAAI,GAAI,SAAS,MAAM,SAAkC,CAAC;AACvE,eAAO,MAAM,IAAI,GAAI,SAAS,MAAM,SAAqC,CAAC"}

package/dist/util/colors.js

@@ -0,0 +1,5 @@
+import pc from 'picocolors';
+export const success = (message) => console.log(pc.green(message));
+export const problem = (message) => console.error(pc.red(message));
+export const info = (message) => console.log(pc.cyan(message));
+export const warn = (message) => console.warn(pc.yellow(message));

package/dist/util/locale.d.ts

@@ -0,0 +1,3 @@
+export declare function detectLocale(): string;
+export declare function setLocale(locale: string): void;
+//# sourceMappingURL=locale.d.ts.map

package/dist/util/locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/util/locale.ts"],"names":[],"mappings":"AAGA,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,QAEvC"}

package/dist/util/locale.js

@@ -0,0 +1,10 @@
+let currentLocale = null;
+export function detectLocale() {
+    if (currentLocale)
+        return currentLocale;
+    const locale = process.env.LANG || process.env.LC_MESSAGES || process.env.LC_ALL || 'en_US.UTF-8';
+    return locale.split('.')[0].split('_')[0];
+}
+export function setLocale(locale) {
+    currentLocale = locale;
+}

package/dist/wba/client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Client-side event sending — framework-agnostic.
+ *
+ * Fire-and-forget POST to a project-provided endpoint.
+ */
+/**
+ * Sends an analytics event from the browser.
+ *
+ * @param url        Full URL of the event endpoint
+ *                   (e.g. `/api/web-analytics/event`).
+ * @param eventType  The event type string.
+ * @param metadata   Optional structured metadata.
+ * @param extra      Extra fields to include (e.g. wallet, session_id).
+ */
+export declare function sendEvent(url: string, eventType: string, metadata?: Record<string, unknown>, extra?: {
+    wallet?: string;
+    session_id?: string;
+}): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/wba/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/wba/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,KAAK,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAgBN"}

package/dist/wba/client.js

@@ -0,0 +1,31 @@
+/**
+ * Client-side event sending — framework-agnostic.
+ *
+ * Fire-and-forget POST to a project-provided endpoint.
+ */
+/**
+ * Sends an analytics event from the browser.
+ *
+ * @param url        Full URL of the event endpoint
+ *                   (e.g. `/api/web-analytics/event`).
+ * @param eventType  The event type string.
+ * @param metadata   Optional structured metadata.
+ * @param extra      Extra fields to include (e.g. wallet, session_id).
+ */
+export function sendEvent(url, eventType, metadata, extra) {
+    if (typeof window === 'undefined')
+        return; // SSR guard
+    fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            event_type: eventType,
+            metadata: metadata ?? null,
+            wallet: extra?.wallet ?? null,
+            session_id: extra?.session_id ?? null,
+        }),
+        keepalive: true,
+    }).catch(() => {
+        /* fire-and-forget — ignore network errors */
+    });
+}

package/dist/wba/index.d.ts

@@ -0,0 +1,4 @@
+export type { WebEvent, SummaryResponse, SummaryOptions, ScalarResult, TopPageRow, } from './types.js';
+export { recordEvent } from './server.js';
+export { sendEvent } from './client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/wba/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/wba/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,QAAQ,EACR,eAAe,EACf,cAAc,EACd,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA"}

package/dist/wba/index.js

@@ -0,0 +1,2 @@
+export { recordEvent } from './server.js';
+export { sendEvent } from './client.js';

package/dist/wba/routes/event.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Next.js POST route factory for recording analytics events.
+ *
+ * Usage in a Next.js project:
+ *
+ * ```typescript
+ * // app/api/web-analytics/event/route.ts
+ * import { makeEventHandler } from '@pasosdejesus/m/wba/routes'
+ * import { newKyselyPostgresql } from '@/.config/kysely.config'
+ *
+ * export const POST = makeEventHandler(() => newKyselyPostgresql(), 'web_event')
+ * ```
+ *
+ * The factory reads `x-forwarded-for`, `user-agent`, and `referer` from
+ * request headers to enrich the event automatically.
+ */
+import { type Kysely } from 'kysely';
+import { NextRequest, NextResponse } from 'next/server.js';
+type DbFactory = () => Kysely<unknown>;
+/**
+ * Creates a Next.js POST handler that records an analytics event.
+ *
+ * @param dbFactory  Function that returns a fresh Kysely instance per request.
+ * @param table      Name of the event table (default `'web_event'`).
+ */
+export declare function makeEventHandler(dbFactory: DbFactory, table?: string): (request: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+export {};
+//# sourceMappingURL=event.d.ts.map

package/dist/wba/routes/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../../src/wba/routes/event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAI1D,KAAK,SAAS,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;AAEtC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,SAAc,IAC7C,SAAS,WAAW;;;;IA4ChD"}

package/dist/wba/routes/event.js

@@ -0,0 +1,42 @@
+import { NextResponse } from 'next/server.js';
+import { recordEvent } from '../server.js';
+/**
+ * Creates a Next.js POST handler that records an analytics event.
+ *
+ * @param dbFactory  Function that returns a fresh Kysely instance per request.
+ * @param table      Name of the event table (default `'web_event'`).
+ */
+export function makeEventHandler(dbFactory, table = 'web_event') {
+    return async function POST(request) {
+        try {
+            const body = await request.json();
+            if (!body.event_type || typeof body.event_type !== 'string') {
+                return NextResponse.json({ error: 'event_type is required' }, { status: 400 });
+            }
+            // Enrich with request headers
+            const ip = request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
+                request.headers.get('x-real-ip') ??
+                undefined;
+            const userAgent = request.headers.get('user-agent') ?? undefined;
+            const referrer = request.headers.get('referer') ??
+                request.headers.get('referrer') ??
+                undefined;
+            const enriched = {
+                ...body,
+                ip: body.ip ?? ip,
+                user_agent: body.user_agent ?? userAgent,
+                referrer: body.referrer ?? referrer,
+                // If not provided via body, pathname from referrer path as fallback
+                pathname: body.pathname,
+                locale: body.locale,
+            };
+            const db = dbFactory();
+            await recordEvent(db, table, enriched);
+            return NextResponse.json({ success: true });
+        }
+        catch (error) {
+            console.error('[wba/event] Failed to record event:', error);
+            return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
+        }
+    };
+}

package/dist/wba/routes/index.d.ts

@@ -0,0 +1,3 @@
+export { makeEventHandler } from './event.js';
+export { makeSummaryHandler, verifyTransactionSchema, verifyWebEventSchema } from './summary.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/wba/routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/wba/routes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA"}

package/dist/wba/routes/index.js

@@ -0,0 +1,2 @@
+export { makeEventHandler } from './event.js';
+export { makeSummaryHandler, verifyTransactionSchema, verifyWebEventSchema } from './summary.js';

package/dist/wba/routes/summary.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Next.js GET route factory for the analytics summary endpoint.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * // app/api/web-analytics/summary/route.ts
+ * import { makeSummaryHandler } from '@pasosdejesus/m/wba/routes'
+ * import { newKyselyPostgresql } from '@/.config/kysely.config'
+ *
+ * export const GET = makeSummaryHandler(
+ *   () => newKyselyPostgresql(),
+ *   { transactionTable: 'transaction' },
+ * )
+ * ```
+ */
+import { type Kysely } from 'kysely';
+import { NextRequest, NextResponse } from 'next/server.js';
+import type { SummaryOptions, SummaryResponse } from '../types.js';
+/**
+ * Verify that the web_event table has the expected columns.
+ */
+export declare function verifyWebEventSchema(db: Kysely<unknown>, tableName?: string): Promise<{
+    columns: number;
+    missing: string[];
+    colTypes: Record<string, string>;
+} | null>;
+/**
+ * Verify that the transaction table has the expected English columns.
+ * Throws with a descriptive message if columns are missing.
+ */
+export declare function verifyTransactionSchema(db: Kysely<unknown>, tableName?: string): Promise<void>;
+type DbFactory = () => Kysely<unknown>;
+/**
+ * Creates a Next.js GET handler that returns the analytics summary.
+ *
+ * @param dbFactory  Function that returns a fresh Kysely instance per request.
+ * @param opts       Optional overrides (e.g. transaction table name).
+ */
+export declare function makeSummaryHandler(dbFactory: DbFactory, opts?: SummaryOptions): (_request: NextRequest) => Promise<NextResponse<SummaryResponse> | NextResponse<{
+    error: string;
+}>>;
+export {};
+//# sourceMappingURL=summary.d.ts.map

package/dist/wba/routes/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../../src/wba/routes/summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAO,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC1D,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAEhB,MAAM,aAAa,CAAA;AAEpB;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,SAAS,SAAc;;;;UAmBtF;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,SAAS,SAAgB,iBAmB3F;AAED,KAAK,SAAS,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;AAStC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,EACpB,IAAI,CAAC,EAAE,cAAc,IAIK,UAAU,WAAW;;IA6GhD"}

package/dist/wba/routes/summary.js

@@ -0,0 +1,146 @@
+/**
+ * Next.js GET route factory for the analytics summary endpoint.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * // app/api/web-analytics/summary/route.ts
+ * import { makeSummaryHandler } from '@pasosdejesus/m/wba/routes'
+ * import { newKyselyPostgresql } from '@/.config/kysely.config'
+ *
+ * export const GET = makeSummaryHandler(
+ *   () => newKyselyPostgresql(),
+ *   { transactionTable: 'transaction' },
+ * )
+ * ```
+ */
+import { sql } from 'kysely';
+import { NextResponse } from 'next/server.js';
+/**
+ * Verify that the web_event table has the expected columns.
+ */
+export async function verifyWebEventSchema(db, tableName = 'web_event') {
+    const result = await sql `
+    SELECT column_name, data_type
+    FROM information_schema.columns
+    WHERE table_name = ${tableName}
+    ORDER BY column_name
+  `.execute(db);
+    const rows = result.rows;
+    if (rows.length === 0)
+        return null; // table doesn't exist — not an error
+    const columns = new Set(rows.map(r => r.column_name));
+    const required = ['id', 'event_type', 'pathname', 'created_at'];
+    const missing = required.filter(c => !columns.has(c));
+    const colTypes = {};
+    for (const r of rows)
+        colTypes[r.column_name] = r.data_type;
+    return { columns: rows.length, missing, colTypes };
+}
+/**
+ * Verify that the transaction table has the expected English columns.
+ * Throws with a descriptive message if columns are missing.
+ */
+export async function verifyTransactionSchema(db, tableName = 'transaction') {
+    const result = await sql `
+    SELECT column_name, data_type
+    FROM information_schema.columns
+    WHERE table_name = ${tableName}
+    ORDER BY column_name
+  `.execute(db);
+    const columns = new Set(result.rows.map(r => r.column_name));
+    const required = ['crypto', 'amount', 'wallet'];
+    const missing = required.filter(c => !columns.has(c));
+    if (missing.length > 0) {
+        throw new Error(`Transaction table "${tableName}" is missing required columns: ${missing.join(', ')}.\n` +
+            `Expected schema: crypto VARCHAR, amount NUMERIC, wallet VARCHAR(42).\n` +
+            `If migrating from Spanish column names, rename: cantidad → amount, billetera → wallet.`);
+    }
+}
+const toNum = (rows) => rows?.[0] ? Number(rows[0].v ?? 0) : 0;
+const toStr = (rows, fallback = '0') => rows?.[0] ? String(rows[0].v ?? fallback) : fallback;
+/**
+ * Creates a Next.js GET handler that returns the analytics summary.
+ *
+ * @param dbFactory  Function that returns a fresh Kysely instance per request.
+ * @param opts       Optional overrides (e.g. transaction table name).
+ */
+export function makeSummaryHandler(dbFactory, opts) {
+    const txTable = opts?.transactionTable ?? 'transaction';
+    return async function GET(_request) {
+        try {
+            const db = dbFactory();
+            const [views24h, views7d, views30d, sessions24h, sessions7d, sessions30d, wallets24h, wallets7d, ips24h, ips7d, donationStarted24h, donationCompleted24h, topPages, errorTotal24h, totalDonations, totalUsdtDonated, uniqueDonors,] = await Promise.all([
+                // page views
+                sql `SELECT count(*)::int8 AS v FROM web_event WHERE event_type = 'pageview' AND created_at >= now() - interval '24 hours'`.execute(db),
+                sql `SELECT count(*)::int8 AS v FROM web_event WHERE event_type = 'pageview' AND created_at >= now() - interval '7 days'`.execute(db),
+                sql `SELECT count(*)::int8 AS v FROM web_event WHERE event_type = 'pageview' AND created_at >= now() - interval '30 days'`.execute(db),
+                // unique sessions
+                sql `SELECT count(DISTINCT session_id)::int8 AS v FROM web_event WHERE event_type = 'pageview' AND session_id IS NOT NULL AND created_at >= now() - interval '24 hours'`.execute(db),
+                sql `SELECT count(DISTINCT session_id)::int8 AS v FROM web_event WHERE event_type = 'pageview' AND session_id IS NOT NULL AND created_at >= now() - interval '7 days'`.execute(db),
+                sql `SELECT count(DISTINCT session_id)::int8 AS v FROM web_event WHERE event_type = 'pageview' AND session_id IS NOT NULL AND created_at >= now() - interval '30 days'`.execute(db),
+                // unique wallets
+                sql `SELECT count(DISTINCT wallet)::int8 AS v FROM web_event WHERE wallet IS NOT NULL AND created_at >= now() - interval '24 hours'`.execute(db),
+                sql `SELECT count(DISTINCT wallet)::int8 AS v FROM web_event WHERE wallet IS NOT NULL AND created_at >= now() - interval '7 days'`.execute(db),
+                // unique IPs
+                sql `SELECT count(DISTINCT ip)::int8 AS v FROM web_event WHERE ip IS NOT NULL AND created_at >= now() - interval '24 hours'`.execute(db),
+                sql `SELECT count(DISTINCT ip)::int8 AS v FROM web_event WHERE ip IS NOT NULL AND created_at >= now() - interval '7 days'`.execute(db),
+                // donation conversion (24h)
+                sql `SELECT count(*)::int8 AS v FROM web_event WHERE event_type = 'donation_started' AND created_at >= now() - interval '24 hours'`.execute(db),
+                sql `SELECT count(*)::int8 AS v FROM web_event WHERE event_type = 'donation_completed' AND created_at >= now() - interval '24 hours'`.execute(db),
+                // top pages (30d)
+                sql `SELECT pathname, count(*)::int8 AS cnt FROM web_event WHERE event_type = 'pageview' AND pathname IS NOT NULL AND created_at >= now() - interval '30 days' GROUP BY pathname ORDER BY count(*) DESC LIMIT 10`.execute(db),
+                // errors (24h)
+                sql `SELECT count(*)::int8 AS v FROM web_event WHERE event_type = 'api_error' AND created_at >= now() - interval '24 hours'`.execute(db),
+                // on-chain: donation count
+                sql `SELECT count(*)::int8 AS v FROM ${sql.raw(txTable)} WHERE crypto = 'usdt'`.execute(db),
+                // on-chain: total USDT donated
+                sql `SELECT coalesce(sum(amount::numeric), 0)::text AS v FROM ${sql.raw(txTable)} WHERE crypto = 'usdt'`.execute(db),
+                // on-chain: unique donors
+                sql `SELECT count(DISTINCT wallet)::int8 AS v FROM ${sql.raw(txTable)} WHERE crypto = 'usdt'`.execute(db),
+            ]);
+            const started = toNum(donationStarted24h.rows);
+            const completed = toNum(donationCompleted24h.rows);
+            const summary = {
+                pageViews: {
+                    '24h': toNum(views24h.rows),
+                    '7d': toNum(views7d.rows),
+                    '30d': toNum(views30d.rows),
+                },
+                uniqueSessions: {
+                    '24h': toNum(sessions24h.rows),
+                    '7d': toNum(sessions7d.rows),
+                    '30d': toNum(sessions30d.rows),
+                },
+                uniqueWallets: {
+                    '24h': toNum(wallets24h.rows),
+                    '7d': toNum(wallets7d.rows),
+                },
+                uniqueIps: {
+                    '24h': toNum(ips24h.rows),
+                    '7d': toNum(ips7d.rows),
+                },
+                donationConversion: {
+                    started,
+                    completed,
+                    rate: started > 0 ? Math.round((completed / started) * 100) : 0,
+                },
+                errors24h: toNum(errorTotal24h.rows),
+                topPages: topPages.rows.map((r) => ({
+                    path: r.pathname,
+                    views: Number(r.cnt),
+                })),
+                onChain: {
+                    totalDonations: toNum(totalDonations.rows),
+                    totalUsdtDonated: toStr(totalUsdtDonated.rows),
+                    uniqueDonors: toNum(uniqueDonors.rows),
+                },
+            };
+            return NextResponse.json(summary);
+        }
+        catch (error) {
+            console.error('[wba/summary] Error:', error);
+            return NextResponse.json({ error: 'Failed to load analytics' }, { status: 500 });
+        }
+    };
+}

package/dist/wba/server.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Server-side event recording — framework-agnostic.
+ *
+ * Inject your own Kysely instance and table name.
+ * No `next/headers` dependency — the caller is responsible for
+ * enriching the event with IP, user-agent, referrer, etc.
+ */
+import type { Kysely } from 'kysely';
+import type { WebEvent } from './types.js';
+/**
+ * Inserts a row into the analytics event table. Never throws.
+ *
+ * @param db       A Kysely instance connected to the project's database.
+ * @param table    Name of the event table (e.g. `'web_event'`, `'userevent'`).
+ * @param event    The event to record — the caller enriches with headers.
+ */
+export declare function recordEvent(db: Kysely<unknown>, table: string, event: WebEvent): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/wba/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/wba/server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,EACnB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/wba/server.js

@@ -0,0 +1,29 @@
+/**
+ * Inserts a row into the analytics event table. Never throws.
+ *
+ * @param db       A Kysely instance connected to the project's database.
+ * @param table    Name of the event table (e.g. `'web_event'`, `'userevent'`).
+ * @param event    The event to record — the caller enriches with headers.
+ */
+export async function recordEvent(db, table, event) {
+    try {
+        const { session_id, event_type, pathname, locale, referrer, user_agent, ip, wallet, metadata } = event;
+        await db
+            .insertInto(table)
+            .values({
+            session_id: session_id ?? null,
+            event_type,
+            pathname: pathname ?? null,
+            locale: locale ?? null,
+            referrer: referrer ?? null,
+            user_agent: user_agent ?? null,
+            ip: ip ?? null,
+            wallet: wallet ?? null,
+            metadata: metadata != null ? JSON.stringify(metadata) : null,
+        })
+            .execute();
+    }
+    catch (error) {
+        console.error('[wba/recordEvent] Failed to record event:', error);
+    }
+}

package/dist/wba/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Web + Blockchain Analytics — types
+ *
+ * Frameworks-agnostic types shared between sivel.xyz and learn.tg.
+ */
+/** Event to record into `web_event` (or equivalent) table. */
+export interface WebEvent {
+    session_id?: string;
+    event_type: string;
+    pathname?: string;
+    locale?: string;
+    referrer?: string;
+    user_agent?: string;
+    ip?: string;
+    wallet?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Row returned by the summary endpoint. */
+export interface SummaryResponse {
+    pageViews: {
+        '24h': number;
+        '7d': number;
+        '30d': number;
+    };
+    uniqueSessions: {
+        '24h': number;
+        '7d': number;
+        '30d': number;
+    };
+    uniqueWallets: {
+        '24h': number;
+        '7d': number;
+    };
+    uniqueIps: {
+        '24h': number;
+        '7d': number;
+    };
+    donationConversion: {
+        started: number;
+        completed: number;
+        rate: number;
+    };
+    errors24h: number;
+    topPages: {
+        path: string;
+        views: number;
+    }[];
+    onChain: {
+        totalDonations: number;
+        totalUsdtDonated: string;
+        uniqueDonors: number;
+    };
+}
+/** Optional overrides for the summary handler. */
+export interface SummaryOptions {
+    /** Name of the on-chain transaction table (default: 'transaction'). */
+    transactionTable?: string;
+}
+/** A single numeric result from a Kysely aggregation query. */
+export interface ScalarResult {
+    v: string | number | bigint | undefined;
+}
+/** A row with pathname + count for top-pages query. */
+export interface TopPageRow {
+    pathname: string;
+    cnt: number | bigint;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/wba/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/wba/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IACzD,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9D,aAAa,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9C,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C,kBAAkB,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxE,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC3C,OAAO,EAAE;QACP,cAAc,EAAE,MAAM,CAAA;QACtB,gBAAgB,EAAE,MAAM,CAAA;QACxB,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;CACF;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CACrB"}

package/dist/wba/types.js

@@ -0,0 +1,6 @@
+/**
+ * Web + Blockchain Analytics — types
+ *
+ * Frameworks-agnostic types shared between sivel.xyz and learn.tg.
+ */
+export {};