@pasosdejesus/m 0.15.0

package/src/wba/README.md

@@ -0,0 +1,175 @@
+# WBA — Web + Blockchain Analytics (`@pasosdejesus/m/wba`)
+
+> *"Let your 'yes' be 'yes' and your 'no' be 'no'"* (Matthew 5:37)
+
+Shared analytics infrastructure for the Pasos de Jesús ecosystem.
+Eliminates code duplication between sivel.xyz and learn.tg.
+
+## Exports
+
+### Core (`@pasosdejesus/m/wba`) — framework-agnostic
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `recordEvent(db, table, event)` | function | Server-side insert into event table. No framework dependency. |
+| `sendEvent(url, eventType, metadata?, extra?)` | function | Client-side fire-and-forget POST. |
+| `WebEvent` | interface | `{ session_id, event_type, pathname, locale, referrer, user_agent, ip, wallet, metadata }` |
+| `SummaryResponse` | interface | Shape returned by the summary endpoint. |
+
+### Routes (`@pasosdejesus/m/wba/routes`) — Next.js-only
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `makeEventHandler(dbFactory, tableName?)` | factory | Returns a Next.js `POST` handler that enriches with headers and calls `recordEvent`. |
+| `makeSummaryHandler(dbFactory, opts?)` | factory | Returns a Next.js `GET` handler with web + on-chain analytics. |
+
+## Usage
+
+### 1. Record an event server-side
+
+```typescript
+import { recordEvent } from '@pasosdejesus/m/wba'
+import { newKyselyPostgresql } from '@/.config/kysely.config'
+import { headers } from 'next/headers'
+
+const h = await headers()
+await recordEvent(newKyselyPostgresql(), 'web_event', {
+  event_type: 'pageview',
+  pathname: '/es/',
+  ip: h.get('x-forwarded-for')?.split(',')[0]?.trim(),
+  user_agent: h.get('user-agent') ?? undefined,
+  referrer: h.get('referer') ?? undefined,
+})
+```
+
+### 2. Record an event from the browser
+
+```typescript
+import { sendEvent } from '@pasosdejesus/m/wba'
+
+sendEvent('/api/web-analytics/event', 'wallet_connect', {
+  wallet: '0x...',
+  method: 'MiniPay',
+})
+```
+
+### 3. Wire the Next.js event route
+
+```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')
+```
+
+### 4. Wire the summary route
+
+```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' },
+)
+```
+
+## Schema (shared DDL reference)
+
+The shared analytics code expects a `web_event` table:
+
+```sql
+CREATE TABLE web_event (
+  id SERIAL PRIMARY KEY,
+  session_id VARCHAR(64),
+  event_type VARCHAR(40) NOT NULL,
+  pathname VARCHAR(200),
+  locale VARCHAR(5),
+  referrer VARCHAR(500),
+  user_agent VARCHAR(500),
+  ip VARCHAR(45),
+  wallet VARCHAR(42),
+  metadata JSONB,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+And an on-chain `transaction` table with at least:
+`crypto`, `amount` (numeric), `wallet` (varchar 42).
+
+> Project-specific columns (e.g., `region_id` in sivel3) stay in the project.
+
+> **Column names are in English.** Projects migrating from Spanish (`cantidad` → `amount`) must
+> update these references in their schema and SQL queries.
+>
+> Verify the schema at startup:
+> ```typescript
+> import { verifyTransactionSchema } from '@pasosdejesus/m/wba/routes'
+> const db = newKyselyPostgresql()
+> await verifyTransactionSchema(db, 'transaction')
+> // Throws if 'crypto', 'amount', or 'wallet' columns are missing.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────┐
+│  Project (sivel.xyz, learn.tg)          │
+│                                          │
+│  app/api/web-analytics/event/route.ts   │
+│    └── makeEventHandler(dbFactory)       │
+│          └── recordEvent(db, table)      │ ← @pasosdejesus/m/wba
+│                                          │
+│  app/api/web-analytics/summary/route.ts  │
+│    └── makeSummaryHandler(dbFactory)      │
+│          └── web_event + tx queries      │ ← @pasosdejesus/m/wba
+│                                          │
+│  lib/web-analytics.ts (re-export)        │
+└──────────────────────────────────────────┘
+```
+
+## What Stays in Each Project
+
+| Artifact | Why |
+|----------|-----|
+| Migrations (`web_event` + `transaction`) | Each project runs its own |
+| Calls to `recordEvent()` in catch/routes | Route names and logic are project-specific |
+| Domain events (wallet, donation, crossword) | Specific to each project |
+| `/stats` or `/metrics` page | Own UI, translations, layout |
+
+## Extending the Summary Endpoint
+
+Projects with extra analytics (regional donations, learning points) wrap the shared
+handler instead of modifying `m`:
+
+```typescript
+// app/api/web-analytics/summary/route.ts
+import { makeSummaryHandler } from '@pasosdejesus/m/wba/routes'
+import { sql } from 'kysely'
+import { NextResponse } from 'next/server'
+
+const baseHandler = makeSummaryHandler(
+  () => newKyselyPostgresql(),
+  { transactionTable: 'transaction' },
+)
+
+export async function GET(req: NextRequest) {
+  const res = await baseHandler(req)
+  if (res.status !== 200) return res
+
+  const data = await res.json()
+  const db = newKyselyPostgresql()
+
+  // Project-specific queries
+  const lpRows = await sql<{ v: string }>`
+    SELECT coalesce(sum(amount::numeric), 0)::text AS v
+    FROM transaction WHERE crypto = 'learningpoint'
+  `.execute(db)
+  data.onChain.totalLearningPoints = lpRows.rows[0]?.v || '0'
+
+  await db.destroy()
+  return NextResponse.json(data)
+}
+```
+