thevoidforge 21.0.11 → 21.0.13

package/dist/docs/patterns/revenue-source-adapter.ts

@@ -0,0 +1,311 @@
+/**
+ * Pattern: Revenue Source Adapter (Read-Only)
+ *
+ * Key principles:
+ * - Read-only interface — VoidForge never processes payments directly
+ * - Separate from AdPlatformAdapter — revenue in, ad spend out
+ * - Polling with overlapping windows for gap-free coverage (ADR-5)
+ * - Dedup by externalId to prevent double-counting
+ * - Webhook signature verification mandatory when webhooks are implemented
+ * - USD-only enforcement (ADR-6) at connection time
+ *
+ * Agents: Dockson (treasury), Vin (analytics)
+ *
+ * PRD Reference: §9.4, §9.9, §9.17 (polling improvements), ADR-5/ADR-6
+ */
+
+type Cents = number & { readonly __brand: 'Cents' };
+type RevenueSource = 'stripe' | 'paddle';
+
+// ── Revenue Source Interface ──────────────────────────
+
+interface RevenueSourceAdapter {
+  /** Establish connection and verify credentials work */
+  connect(credentials: RevenueCredentials): Promise<ConnectionResult>;
+
+  /** Detect the account's currency for ADR-6 enforcement */
+  detectCurrency(credentials: RevenueCredentials): Promise<string>;
+
+  /**
+   * Fetch transactions in a date range.
+   * Uses overlapping windows: fetch from (lastPollTime - 5 minutes) to now.
+   * Dedup by externalId at the caller.
+   */
+  getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage>;
+
+  /** Get current account balance (optional — not all sources support this) */
+  getBalance?(): Promise<BalanceResult>;
+
+  /**
+   * Verify webhook signature (mandatory when webhooks are implemented).
+   * Deferred to remote mode per ADR-5 — not called in v11.x polling mode.
+   */
+  verifyWebhookSignature?(payload: Buffer, signature: string, secret: string): boolean;
+}
+
+// ── Types ─────────────────────────────────────────────
+
+interface RevenueCredentials {
+  source: RevenueSource;
+  apiKey?: string;          // Stripe, Paddle (restricted, read-only)
+  accessToken?: string;     // OAuth token (for future sources)
+}
+
+interface ConnectionResult {
+  connected: boolean;
+  accountId?: string;
+  accountName?: string;
+  currency?: string;        // ISO 4217
+  error?: string;
+}
+
+interface DateRange {
+  start: string;            // ISO 8601
+  end: string;              // ISO 8601
+}
+
+interface TransactionPage {
+  transactions: RevenueTransaction[];
+  hasMore: boolean;
+  cursor?: string;          // For pagination — store in daemon state for crash recovery
+}
+
+interface RevenueTransaction {
+  externalId: string;       // Platform's transaction/event ID — dedup key
+  type: 'charge' | 'subscription' | 'refund' | 'dispute';
+  amount: Cents;            // Integer cents. Negative for refunds/disputes.
+  currency: 'USD';          // Validated at ingest per ADR-6
+  description: string;
+  customerId?: string;      // Hashed — never store raw email/name
+  subscriptionId?: string;  // For future MRR calculation (deferred to v11.2)
+  metadata: Record<string, string>;
+  createdAt: string;        // ISO 8601
+}
+
+interface BalanceResult {
+  available: Cents;
+  pending: Cents;
+  currency: 'USD';
+}
+
+// ── API Response Shapes (for type-safe access on apiCall results) ─────
+
+/** Shape of Stripe /account response fields we access */
+interface StripeAccountResponse {
+  id: string;
+  business_profile?: { name?: string };
+  email?: string;
+  default_currency?: string;
+  [key: string]: unknown;
+}
+
+/** Shape of Stripe /events list response */
+interface StripeEventsResponse {
+  data: Array<Record<string, unknown>>;
+  has_more: boolean;
+  [key: string]: unknown;
+}
+
+/** Shape of Stripe /balance response */
+interface StripeBalanceResponse {
+  available: Array<{ currency: string; amount: number }>;
+  pending: Array<{ currency: string; amount: number }>;
+  [key: string]: unknown;
+}
+
+/** Shape of Paddle /businesses response */
+interface PaddleBusinessesResponse {
+  data: Array<{ id: string; name: string; currency_code: string }>;
+  [key: string]: unknown;
+}
+
+/** Shape of Paddle /transactions response */
+interface PaddleTransactionsResponse {
+  data: Array<Record<string, unknown>>;
+  meta?: { pagination?: { next?: string } };
+  [key: string]: unknown;
+}
+
+// ── Reference Implementation: Stripe ──────────────────
+
+class StripeAdapter implements RevenueSourceAdapter {
+  private apiKey: string = '';
+  private readonly baseUrl = 'https://api.stripe.com/v1';
+
+  async connect(credentials: RevenueCredentials): Promise<ConnectionResult> {
+    this.apiKey = credentials.apiKey || '';
+    try {
+      const account = await this.apiCall('GET', '/account') as StripeAccountResponse;
+      return {
+        connected: true,
+        accountId: account.id,
+        accountName: account.business_profile?.name || account.email,
+        currency: account.default_currency?.toUpperCase(),
+      };
+    } catch (err) {
+      return { connected: false, error: (err as Error).message };
+    }
+  }
+
+  async detectCurrency(credentials: RevenueCredentials): Promise<string> {
+    const result = await this.connect(credentials);
+    return result.currency || 'USD';
+  }
+
+  async getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage> {
+    // Use Stripe Events API for sequential, immutable event log (§9.18)
+    const params: Record<string, string> = {
+      type: 'charge.succeeded',
+      'created[gte]': String(Math.floor(new Date(range.start).getTime() / 1000)),
+      'created[lte]': String(Math.floor(new Date(range.end).getTime() / 1000)),
+      limit: '100',
+    };
+    if (cursor) params.starting_after = cursor;
+
+    const data = await this.apiCall('GET', '/events', params) as StripeEventsResponse;
+    const transactions: RevenueTransaction[] = data.data.map((event: Record<string, unknown>) => {
+      const charge = (event.data as Record<string, unknown>)?.object as Record<string, unknown>;
+      return {
+        externalId: event.id as string,
+        type: 'charge' as const,
+        amount: (charge?.amount as number || 0) as Cents, // Stripe amounts are already in cents
+        currency: 'USD' as const,
+        description: (charge?.description as string) || '',
+        customerId: charge?.customer ? hashCustomerId(charge.customer as string) : undefined,
+        subscriptionId: charge?.subscription as string | undefined,
+        metadata: (charge?.metadata as Record<string, string>) || {},
+        createdAt: new Date((event.created as number) * 1000).toISOString(),
+      };
+    });
+
+    return {
+      transactions,
+      hasMore: data.has_more as boolean,
+      cursor: data.data.length > 0 ? data.data[data.data.length - 1].id as string : undefined,
+    };
+  }
+
+  async getBalance(): Promise<BalanceResult> {
+    const data = await this.apiCall('GET', '/balance') as StripeBalanceResponse;
+    const usd = data.available.find((b) => b.currency === 'usd');
+    const pending = data.pending.find((b) => b.currency === 'usd');
+    return {
+      available: (usd?.amount || 0) as Cents,
+      pending: (pending?.amount || 0) as Cents,
+      currency: 'USD',
+    };
+  }
+
+  verifyWebhookSignature(payload: Buffer, signature: string, secret: string): boolean {
+    // Stripe uses HMAC-SHA256 for webhook signatures
+    const { createHmac } = require('node:crypto');
+    const parts = signature.split(',').reduce((acc: Record<string, string>, part: string) => {
+      const [key, value] = part.split('=');
+      acc[key] = value;
+      return acc;
+    }, {});
+
+    const timestamp = parts['t'];
+    const expected = parts['v1'];
+    if (!timestamp || !expected) return false;
+
+    const signed = createHmac('sha256', secret)
+      .update(`${timestamp}.${payload.toString()}`)
+      .digest('hex');
+
+    // VG-006: Use timing-safe comparison to prevent timing attacks on signature
+    const { timingSafeEqual } = require('node:crypto');
+    if (signed.length !== expected.length) return false;
+    return timingSafeEqual(Buffer.from(signed), Buffer.from(expected));
+  }
+
+  private async apiCall(method: string, path: string, params?: Record<string, string>): Promise<Record<string, unknown>> {
+    // Implementation: raw HTTPS (no Stripe SDK — zero dependency principle)
+    // Headers: Authorization: Bearer {apiKey}, Content-Type: application/x-www-form-urlencoded
+    // Sanitize response strings per §9.19.16 before returning
+    throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+  }
+}
+
+// ── Paddle Adapter ────────────────────────────────────
+
+class PaddleAdapter implements RevenueSourceAdapter {
+  private apiKey: string = '';
+  private readonly baseUrl = 'https://api.paddle.com';
+
+  async connect(credentials: RevenueCredentials): Promise<ConnectionResult> {
+    this.apiKey = credentials.apiKey || '';
+    try {
+      const data = await this.apiCall('GET', '/businesses') as PaddleBusinessesResponse;
+      const biz = data.data?.[0];
+      return {
+        connected: true,
+        accountId: biz?.id,
+        accountName: biz?.name,
+        currency: biz?.currency_code,
+      };
+    } catch (err) {
+      return { connected: false, error: (err as Error).message };
+    }
+  }
+
+  async detectCurrency(credentials: RevenueCredentials): Promise<string> {
+    const result = await this.connect(credentials);
+    return result.currency || 'USD';
+  }
+
+  async getTransactions(range: DateRange, cursor?: string): Promise<TransactionPage> {
+    const params: Record<string, string> = {
+      'created_at[gte]': range.start,
+      'created_at[lte]': range.end,
+      per_page: '100',
+    };
+    if (cursor) params.after = cursor;
+
+    const data = await this.apiCall('GET', '/transactions', params) as PaddleTransactionsResponse;
+    const transactions: RevenueTransaction[] = data.data.map((txn: Record<string, unknown>) => {
+      const details = txn.details as Record<string, unknown> | undefined;
+      const totals = details?.totals as Record<string, unknown> | undefined;
+      const items = txn.items as Array<Record<string, unknown>> | undefined;
+      const firstItemPrice = items?.[0]?.price as Record<string, unknown> | undefined;
+      return {
+        externalId: txn.id as string,
+        type: mapPaddleStatus(txn.status as string),
+        amount: Math.round(parseFloat(totals?.total as string || '0') * 100) as Cents,
+        currency: 'USD' as const,
+        description: (firstItemPrice?.description as string) || '',
+        customerId: txn.customer_id ? hashCustomerId(txn.customer_id as string) : undefined,
+        subscriptionId: txn.subscription_id as string | undefined,
+        metadata: (txn.custom_data as Record<string, string>) || {},
+        createdAt: txn.created_at as string,
+      };
+    });
+
+    return {
+      transactions,
+      hasMore: !!data.meta?.pagination?.next,
+      cursor: data.meta?.pagination?.next,
+    };
+  }
+
+  private async apiCall(method: string, path: string, params?: Record<string, string>): Promise<Record<string, unknown>> {
+    throw new Error('HTTP implementation — use node:https, no SDK dependencies');
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────
+
+function hashCustomerId(customerId: string): string {
+  const { createHash } = require('node:crypto');
+  return createHash('sha256').update(customerId).digest('hex').substring(0, 16);
+}
+
+function mapPaddleStatus(status: string): RevenueTransaction['type'] {
+  if (status === 'completed' || status === 'paid') return 'charge';
+  if (status === 'refunded' || status === 'partially_refunded') return 'refund';
+  if (status === 'disputed') return 'dispute';
+  return 'charge';
+}
+
+export type { RevenueSourceAdapter, RevenueCredentials, ConnectionResult, TransactionPage, RevenueTransaction, BalanceResult, DateRange };
+export { StripeAdapter, PaddleAdapter, hashCustomerId };

package/dist/docs/patterns/service.ts

@@ -0,0 +1,224 @@
+/**
+ * Pattern: Service Layer
+ *
+ * Key principles:
+ * - All business logic lives in services, NOT in route handlers
+ * - Services are stateless and composable
+ * - Services throw typed errors (ApiError), routes catch and format
+ * - Database access is scoped — services enforce ownership/tenancy
+ * - No HTTP concepts in services (no req/res, no status codes)
+ *
+ * Agents: Strange (service architecture), Banner (database), Barton (errors)
+ *
+ * Framework adaptations:
+ *   Next.js/Node: This file (Prisma ORM, const object exports)
+ *   Express: Same pattern — services in /lib/, imported by route handlers
+ *   Django: Service functions in app/services.py, called by views, raise custom exceptions
+ *   Rails: Service objects in app/services/, called by controllers, raise custom errors
+ *
+ * === Django Deep Dive ===
+ *
+ *   # app/services/project_service.py
+ *   from django.db import transaction
+ *   from .models import Project
+ *   from .exceptions import NotFoundError, ForbiddenError
+ *
+ *   class ProjectService:
+ *       @staticmethod
+ *       def create(user, name, description=None):
+ *           return Project.objects.create(owner=user, name=name, description=description)
+ *
+ *       @staticmethod
+ *       def get(user, project_id):
+ *           try:
+ *               project = Project.objects.get(id=project_id)
+ *           except Project.DoesNotExist:
+ *               raise NotFoundError("Project not found")
+ *           if project.owner_id != user.id:
+ *               raise NotFoundError("Project not found")  # 404 not 403 — no IDOR
+ *           return project
+ *
+ *       @staticmethod
+ *       @transaction.atomic
+ *       def delete(user, project_id):
+ *           project = ProjectService.get(user, project_id)
+ *           project.delete()
+ *
+ *   # Key principles (same as TypeScript):
+ *   # - Business logic in services, not views
+ *   # - Ownership checks on every user-scoped query (return 404, not 403)
+ *   # - Use QuerySet methods (filter, get, select_related) — never raw SQL
+ *   # - Wrap multi-step mutations in @transaction.atomic
+ *   # - Raise domain exceptions (NotFoundError, ForbiddenError) — views map to HTTP
+ *
+ * === FastAPI Deep Dive ===
+ *
+ *   # app/services/project_service.py
+ *   from sqlalchemy.ext.asyncio import AsyncSession
+ *   from sqlalchemy import select
+ *   from .models import Project
+ *   from .exceptions import NotFoundError
+ *
+ *   class ProjectService:
+ *       def __init__(self, db: AsyncSession):
+ *           self.db = db
+ *
+ *       async def create(self, user, name, description=None):
+ *           project = Project(owner_id=user.id, name=name, description=description)
+ *           self.db.add(project)
+ *           await self.db.commit()
+ *           await self.db.refresh(project)
+ *           return project
+ *
+ *       async def get(self, user, project_id):
+ *           result = await self.db.execute(
+ *               select(Project).where(Project.id == project_id, Project.owner_id == user.id)
+ *           )
+ *           project = result.scalar_one_or_none()
+ *           if not project:
+ *               raise NotFoundError("Project not found")
+ *           return project
+ *
+ *   # Key principles:
+ *   # - Services receive db session via dependency injection (Depends)
+ *   # - Async by default — all DB operations use await
+ *   # - Repository pattern: service wraps SQLAlchemy queries
+ *   # - Same ownership enforcement: filter by owner_id in query, not after fetch
+ *
+ * See /docs/patterns/error-handling.ts for the canonical error strategy.
+ */
+
+import { db } from '@/lib/db'
+import { ApiError } from '@/lib/errors'
+
+// --- Types co-located with the service ---
+interface CreateProjectInput {
+  name: string
+  description?: string
+  ownerId: string
+}
+
+interface ListProjectsInput {
+  ownerId: string
+  page: number
+  limit: number
+}
+
+interface PaginatedResult<T> {
+  items: T[]
+  page: number
+  limit: number
+  total: number
+  hasMore: boolean
+}
+
+// --- Service object (no class needed for most cases) ---
+export const projectService = {
+  async create(input: CreateProjectInput) {
+    // Business rules enforced here, not in the route
+    const existingCount = await db.project.count({
+      where: { ownerId: input.ownerId },
+    })
+
+    // Tier enforcement (Ahsoka — access control)
+    const MAX_PROJECTS_FREE = 5
+    if (existingCount >= MAX_PROJECTS_FREE) {
+      throw new ApiError(
+        'PROJECT_LIMIT_REACHED',
+        'Upgrade to create more projects',
+        403
+      )
+    }
+
+    // ALWAYS use `select` on mutations — raw Prisma results include ALL columns,
+    // silently leaking sensitive fields. See /docs/patterns/api-route.ts for the rule.
+    return db.project.create({
+      data: {
+        name: input.name,
+        description: input.description ?? null,
+        ownerId: input.ownerId,
+      },
+      select: {
+        id: true,
+        name: true,
+        description: true,
+        createdAt: true,
+        updatedAt: true,
+      },
+    })
+  },
+
+  async list(input: ListProjectsInput): Promise<PaginatedResult<any>> {
+    const { ownerId, page, limit } = input
+    const skip = (page - 1) * limit
+
+    // Parallel queries for data + count (Banner — performance)
+    const [items, total] = await Promise.all([
+      db.project.findMany({
+        where: { ownerId },
+        orderBy: { createdAt: 'desc' },
+        skip,
+        take: limit,
+        select: {
+          id: true,
+          name: true,
+          description: true,
+          createdAt: true,
+          updatedAt: true,
+          // Only select fields needed — no over-fetching
+        },
+      }),
+      db.project.count({ where: { ownerId } }),
+    ])
+
+    return {
+      items,
+      page,
+      limit,
+      total,
+      hasMore: skip + items.length < total,
+    }
+  },
+
+  async getById(projectId: string, requestingUserId: string) {
+    const project = await db.project.findUnique({
+      where: { id: projectId },
+    })
+
+    if (!project) {
+      throw new ApiError('NOT_FOUND', 'Project not found', 404)
+    }
+
+    // Ownership check (Ahsoka — no IDOR)
+    if (project.ownerId !== requestingUserId) {
+      // Return 404, not 403 — don't reveal existence
+      throw new ApiError('NOT_FOUND', 'Project not found', 404)
+    }
+
+    return project
+  },
+
+  async delete(projectId: string, requestingUserId: string) {
+    // Verify ownership before deletion
+    const project = await this.getById(projectId, requestingUserId)
+
+    await db.project.delete({
+      where: { id: project.id },
+    })
+  },
+}
+
+// --- Error class (lives in /lib/errors.ts) ---
+// Shown here for completeness
+/*
+export class ApiError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public status: number
+  ) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+*/

package/dist/docs/patterns/sse-endpoint.ts

@@ -0,0 +1,118 @@
+/**
+ * SSE Endpoint Pattern — Server-Sent Events with proper lifecycle management
+ *
+ * Use for: streaming AI responses, progress bars, real-time notifications
+ * Don't use for: bidirectional communication (use WebSocket instead)
+ *
+ * Adaptations:
+ * - Express: res.writeHead + res.write (shown below)
+ * - FastAPI: StreamingResponse with async generator
+ * - Django: StreamingHttpResponse with iterator
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+// ── Express/Node SSE endpoint ──────────────────────
+
+export function handleSSE(req: IncomingMessage, res: ServerResponse): void {
+  // Headers — must be set before any write
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'X-Accel-Buffering': 'no', // Disable nginx buffering
+  });
+
+  // Keepalive — prevents proxy timeout (Caddy: 60s, nginx: 60s, Cloudflare: 100s)
+  const keepalive = setInterval(() => {
+    res.write(': keepalive\n\n');
+  }, 15000);
+
+  // Connection timeout — don't hold connections forever
+  const MAX_DURATION_MS = 5 * 60 * 1000; // 5 minutes
+  const timeout = setTimeout(() => {
+    sendEvent(res, 'done', { reason: 'timeout' });
+    cleanup();
+  }, MAX_DURATION_MS);
+
+  // Cleanup on client disconnect
+  req.on('close', cleanup);
+
+  function cleanup(): void {
+    clearInterval(keepalive);
+    clearTimeout(timeout);
+    if (!res.writableEnded) res.end();
+  }
+
+  // Send a typed event
+  function sendEvent(response: ServerResponse, event: string, data: unknown): void {
+    if (response.writableEnded) return;
+    response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  }
+
+  // ── Your streaming logic here ──────────────────
+  // Example: stream AI response chunks
+  // for await (const chunk of aiStream) {
+  //   sendEvent(res, 'chunk', { text: chunk });
+  // }
+  // sendEvent(res, 'done', { totalTokens: 1234 });
+  // cleanup();
+}
+
+// ── Client-side (vanilla JS) ──────────────────────
+//
+// const source = new EventSource('/api/stream');
+// source.addEventListener('chunk', (e) => {
+//   const data = JSON.parse(e.data);
+//   appendToUI(data.text);
+// });
+// source.addEventListener('done', (e) => {
+//   source.close();
+// });
+// source.addEventListener('error', () => {
+//   // EventSource auto-reconnects — add backoff if needed
+//   source.close();
+// });
+
+// ── React SSE hook ────────────────────────────────
+//
+// Use useRef for mutable callbacks in SSE handlers:
+//   const onChunkRef = useRef(onChunk);
+//   onChunkRef.current = onChunk; // Update ref on every render
+//   useEffect(() => {
+//     const source = new EventSource(url);
+//     source.addEventListener('chunk', (e) => onChunkRef.current(e));
+//     return () => source.close();
+//   }, [url]); // Only url in deps, NOT onChunk
+//
+// Why: EventSource registers callbacks once. If onChunk is in the dep array,
+// the effect re-runs on every render, creating/destroying EventSource rapidly.
+// The ref pattern gives the handler access to fresh state without re-registering.
+// (Field report #77: React SSE handler captured stale closure, missed updates)
+
+// ── FastAPI adaptation ────────────────────────────
+//
+// from fastapi.responses import StreamingResponse
+// import asyncio, json
+//
+// @app.get("/api/stream")
+// async def stream():
+//     async def generate():
+//         yield f"event: start\ndata: {json.dumps({'status': 'connected'})}\n\n"
+//         async for chunk in ai_stream():
+//             yield f"event: chunk\ndata: {json.dumps({'text': chunk})}\n\n"
+//         yield f"event: done\ndata: {json.dumps({'status': 'complete'})}\n\n"
+//     return StreamingResponse(generate(), media_type="text/event-stream")
+
+// ── Django adaptation ─────────────────────────────
+//
+// from django.http import StreamingHttpResponse
+// import json
+//
+// def stream_view(request):
+//     def generate():
+//         yield f"event: start\ndata: {json.dumps({'status': 'connected'})}\n\n"
+//         for chunk in ai_stream():
+//             yield f"event: chunk\ndata: {json.dumps({'text': chunk})}\n\n"
+//         yield f"event: done\ndata: {json.dumps({'status': 'complete'})}\n\n"
+//     return StreamingHttpResponse(generate(), content_type="text/event-stream")