Skip to content

EVENT_EMISSION_STATUS.md

Latest commit

 

History

History
417 lines (338 loc) · 13.6 KB

EVENT_EMISSION_STATUS.md

File metadata and controls

417 lines (338 loc) · 13.6 KB
Raw

Event Emission Status

Last Updated: 2026-02-15 Branch: v1.2-auth-boundary

Overview

This document tracks the progress of adding event emission to existing endpoints across the platform.

✅ Events Currently Being Emitted

Admin Events (3/11 event types)

1. admin.action - Session Termination (src/routes/adminApi.ts)

  • Endpoint: DELETE /v1/ops/sessions/:id
  • Event Type: admin.action
  • Action Type: session.terminate
  • When: Admin terminates a single session
  • Data Captured:
    • Admin person ID and email
    • Session ID (resource_id)
    • Termination reason: user_logout

2. admin.action - Terminate All Sessions (src/routes/adminApi.ts)

  • Endpoint: DELETE /v1/ops/sessions
  • Event Type: admin.action
  • Action Type: sessions.terminate_all
  • When: Admin terminates all sessions except current
  • Data Captured:
    • Admin person ID and email
    • Number of sessions terminated
    • Termination reason: user_logout_all

3. admin.action - Flag Audit Entry (src/routes/adminApi.ts)

  • Endpoint: POST /v1/ops/audit/:id/flag
  • Event Type: admin.action
  • Action Type: audit.flag
  • When: Admin flags an audit entry for investigation
  • Data Captured:
    • Admin person ID and email
    • Audit entry ID
    • Flagged status (true/false)
    • Original action type being flagged

📋 Events Ready to Add (Priority Order)

Priority 1: High-Value Analytics Events

Transaction Events (2/3 implemented) ✅

transaction.completed

  • Where to add: Payment processing endpoints
  • File: src/routes/webhooks.ts
  • Status: ✅ Implemented (commit 157f363)
  • Value: Critical for revenue analytics
  • Location: Line ~103 in Stripe webhook handler (payment_intent.succeeded)
  • Notes: Emitted after marketplaceService.settleOrder() completes

transaction.failed

  • Where to add: Payment error handling
  • File: src/routes/webhooks.ts
  • Status: ✅ Implemented (commit 157f363)
  • Value: High - track failure patterns
  • Location: Line ~185 in Stripe webhook handler (payment_intent.payment_failed)
  • Notes: Captures failure_reason and error_code from Stripe event

transaction.refunded

  • Where to add: Refund processing endpoint
  • File: Admin refund endpoint (to be implemented)
  • Status: 🔴 Endpoint not yet implemented
  • Value: High - track refund patterns

User Events (0/4 implemented)

user.created

  • Where to add: User registration/bootstrap endpoint
  • File: src/routes/auth.ts (bootstrap endpoint) or similar
  • Status: 🔴 Not yet implemented
  • Value: High - track user growth
  • Example:
await emitUserCreated(fastify, request, {
  person_id: newUserId,
  email: email,
  identity_type: 'artist',
  tier: 'established',
  verified: false,
});

user.verified

  • Where to add: Email verification endpoint
  • File: src/routes/auth.ts or verification handler
  • Status: 🔴 Not yet implemented
  • Value: Medium - track verification funnel
  • Example:
await emitUserVerified(fastify, request, {
  person_id: userId,
  email: userEmail,
  verification_method: 'email',
});

user.suspended

  • Where to add: User suspension endpoint
  • File: Admin API (to be implemented)
  • Status: 🔴 Endpoint not yet implemented
  • Value: Medium - track moderation actions
  • Example:
await emitUserSuspended(fastify, request, {
  person_id: userId,
  email: userEmail,
  reason: 'Terms violation',
  suspended_by: actor.actor_person_id,
});

user.reactivated

  • Where to add: User reactivation endpoint
  • File: Admin API (to be implemented)
  • Status: 🔴 Endpoint not yet implemented
  • Value: Low - less frequent action

Priority 2: Marketplace Events

Artwork Events (3/3 implemented) ✅

artwork.created

  • Where to add: Artwork upload endpoint
  • File: src/routes/masterAssets.ts
  • Status: ✅ Implemented (commit 29d2798)
  • Value: Medium - track content creation
  • Location: Line ~133 in POST /ops/master-assets handler
  • Notes: Emitted after INSERT INTO master_assets completes

artwork.published

  • Where to add: Artwork publish endpoint
  • File: src/routes/masterAssets.ts
  • Status: ✅ Implemented (commit 15d280b)
  • Value: Medium - track publication patterns
  • Location: Line ~553 in PATCH /ops/master-assets/:id/distribute handler
  • Notes: Emitted when artwork state transitions to 'distributed' (publicly available)

artwork.purchased

  • Where to add: Marketplace purchase endpoint
  • File: src/routes/webhooks.ts
  • Status: ✅ Implemented (commit 157f363)
  • Value: High - critical for sales analytics
  • Location: Line ~125 in Stripe webhook handler (payment_intent.succeeded)
  • Notes: Emitted for each item in order.items_json after settlement

Marketplace Listing Events (2/3 implemented) ✅

listing.created

  • Where to add: Listing creation endpoint
  • File: src/routes/listings.ts
  • Status: ✅ Implemented (commit 0e8e36d)
  • Value: Medium - track marketplace inventory
  • Location: Line ~112 in POST /ops/listings handler
  • Notes: Emitted after INSERT INTO token_listings completes

listing.cancelled

  • Where to add: Listing cancellation endpoint
  • File: src/routes/listings.ts
  • Status: ✅ Implemented (commit 0e8e36d)
  • Value: Medium - monitor seller behavior
  • Location: Line ~193 in POST /ops/listings/:id/cancel handler
  • Notes: Emitted after status updated to 'cancelled'

listing.purchased

  • Where to add: Marketplace purchase completion
  • File: src/routes/webhooks.ts or marketplace settlement
  • Status: 🔴 Not yet implemented (redundant with artwork.purchased)
  • Value: Low - artwork.purchased already captures this

Compliance Events (1/3 implemented)

certification.requested

  • Where to add: Certification request endpoint
  • File: N/A
  • Status: 🔴 No separate request endpoint (certification happens in one step)
  • Value: Medium - would track certification demand

certification.approved

  • Where to add: Certification approval endpoint
  • File: src/routes/masterAssets.ts
  • Status: ✅ Implemented (commit 0e8e36d)
  • Value: Medium - track certification completions
  • Location: Line ~283 in PATCH /ops/master-assets/:id/certify handler
  • Notes: Emitted after is_certified flag set to true

certification.rejected

  • Where to add: Certification rejection endpoint
  • File: N/A
  • Status: 🔴 No rejection workflow in current implementation
  • Value: Low - certification always approves if prerequisites met

Priority 3: NFT Events

NFT Minting Events (3/3 implemented) ✅

nft.mint_requested

  • Where to add: NFT mint request endpoint
  • File: src/routes/blockchain.ts
  • Status: ✅ Implemented (commit 15d280b)
  • Value: Medium - track mint demand
  • Location: Line ~69 in POST /blockchain/mint/:token_id handler
  • Notes: Emitted after successful enqueueMint(), tracks minting demand before processing

nft.mint_completed

  • Where to add: NFT minting queue worker
  • File: src/jobs/nftMintingQueue.ts
  • Status: ✅ Implemented (commit 6634516)
  • Value: High - track successful mints
  • Location: Line ~217 in processSingleMint() after successful mint
  • Notes: Background job uses dataLakeWriter directly (no request context)

nft.mint_failed

  • Where to add: NFT minting error handling
  • File: src/jobs/nftMintingQueue.ts
  • Status: ✅ Implemented (commit 6634516)
  • Value: High - track failures for debugging
  • Location: Line ~295 in processSingleMint() error handler
  • Notes: Captures retry_count and failure_reason

Priority 4: Additional Admin Events

admin.login

  • Where to add: Admin login endpoint
  • File: src/routes/auth.ts (admin login)
  • Status: 🔴 Not yet implemented
  • Value: Low - session events more important

admin.logout

  • Where to add: Admin logout endpoint
  • File: src/routes/auth.ts (logout)
  • Status: 🔴 Not yet implemented
  • Value: Low - already tracking session termination

📊 Implementation Statistics

Total Event Types Defined: 32 Events Being Emitted: 14 (44%) High-Priority Events Remaining: 3 (user events, transaction refund) Medium-Priority Events Remaining: 2 (user verification, certification requested) Low-Priority Events Remaining: 13 (admin login/logout, other events)

🚀 Quick Wins (Recommended Next Steps)

Step 1: Add Transaction Events (Highest ROI)

Revenue analytics are the most valuable. Focus on:

  1. Find payment success path in src/routes/payments.ts
  2. Add emitTransactionCompleted after successful Stripe charge
  3. Add emitTransactionFailed in error handling
  4. Estimated Time: 30 minutes
  5. Analytics Value: Critical - enables revenue dashboards

Step 2: Add Artwork Purchase Events

Second most valuable for business analytics:

  1. Find purchase completion in src/routes/marketplace.ts or src/routes/listings.ts
  2. Add emitArtworkPurchased after successful purchase
  3. Estimated Time: 20 minutes
  4. Analytics Value: High - enables sales analytics

Step 3: Add NFT Minting Events

Important for blockchain operations monitoring:

  1. Find minting success in src/jobs/nftMintingQueue.ts
  2. Add emitNftMintCompleted after successful mint
  3. Add emitNftMintFailed in error handling
  4. Estimated Time: 30 minutes
  5. Analytics Value: High - enables NFT performance dashboards

Step 4: Add User Creation Events

Good for user growth analytics:

  1. Find user creation in src/routes/auth.ts or bootstrap endpoint
  2. Add emitUserCreated after INSERT into people table
  3. Estimated Time: 20 minutes
  4. Analytics Value: Medium-High - enables user growth dashboards

🧪 Testing Event Emission

1. Manual Testing

After adding event emission to an endpoint:

# Trigger the action (e.g., terminate a session)
curl -X DELETE http://localhost:3000/v1/ops/sessions/<session-id> \
  -H "Authorization: Bearer <admin-jwt>"

# Wait 5 seconds for buffer flush or force flush
curl -X POST http://localhost:3000/v1/analytics/lake/flush \
  -H "Authorization: Bearer <admin-jwt>"

# Check that event file was created
ls -la data-lake/events/category=admin/date=$(date +%Y-%m-%d)/

# Read the event
cat data-lake/events/category=admin/date=$(date +%Y-%m-%d)/events_001.jsonl | jq

# Query via API
curl http://localhost:3000/v1/analytics/lake/writer-stats \
  -H "Authorization: Bearer <admin-jwt>"

2. Verify Event Structure

Expected event for admin action:

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "admin.action",
  "event_category": "admin",
  "timestamp": "2026-02-15T14:30:00.000Z",
  "actor_person_id": "admin_123",
  "actor_role": "admin",
  "session_id": "session_xyz",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "metadata": {
    "action_type": "session.terminate",
    "resource_type": "admin_session",
    "resource_id": "session_abc",
    "admin_person_id": "admin_123",
    "admin_email": "admin@example.com",
    "action_success": true,
    "action_details": {
      "termination_reason": "user_logout"
    }
  }
}

📝 Implementation Checklist

Completed ✅

  • Import event emission helper in adminApi.ts
  • Add emitAdminAction to session termination endpoint
  • Add emitAdminAction to terminate all sessions endpoint
  • Add emitAdminAction to audit flag endpoint

Next Up 🔄

  • Add emitTransactionCompleted to payment success path
  • Add emitTransactionFailed to payment error handling
  • Add emitArtworkPurchased to marketplace purchase
  • Add emitNftMintCompleted to minting queue success
  • Add emitNftMintFailed to minting queue error
  • Add emitUserCreated to user registration/bootstrap (no production endpoint found)
  • Add emitUserVerified to email verification (no production endpoint found)
  • Add emitArtworkCreated to artwork upload
  • Add emitArtworkPublished to artwork distribute
  • Add emitNftMintRequested to mint request

Future 📅

  • Add emitUserVerified to email verification
  • Add emitArtworkCreated to artwork upload
  • Add emitNftMintRequested to mint request
  • Add remaining marketplace and admin events

🎯 Success Metrics

Once high-priority events are being emitted, you can build:

  1. Revenue Dashboard

    • Daily revenue trends
    • Transaction success rate
    • Average transaction value
    • Refund rate

  2. Sales Dashboard

    • Artworks sold per day
    • Top-selling artworks
    • Average sale price
    • Top artists by revenue

  3. NFT Performance Dashboard

    • Mint success rate
    • Average gas costs
    • Failed mint reasons
    • Minting volume trends

  4. User Growth Dashboard

    • New users per day
    • Cumulative user growth
    • Verification funnel
    • User activity patterns

Current Progress: 14 of 32 event types being emitted (44%) Next Milestone: Get to 18 event types (56%) by adding compliance and admin events Ultimate Goal: 100% event coverage for complete analytics

Notes:

  • User creation/verification events not implemented - no production endpoints exist (users created via seed scripts)
  • All high-value analytics events (transaction, artwork, NFT, marketplace) now implemented
  • Certification requested event skipped - no separate request endpoint (certification happens in one step)

See EVENT_EMISSION_GUIDE.md for implementation examples and best practices.