@tangle-network/starter-foundry 0.5.4 → 0.7.2

package/registry/layers/framework/crm-backend/files/reporting.ts

@@ -0,0 +1,69 @@
+// CRM reporting endpoints. Aggregates are computed at query time from the
+// deals + activities tables. For production you'll want materialized views
+// or a separate analytics store — this is the seam.
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { sql } from 'drizzle-orm'
+import { db } from '../db/client.js'
+import { deals, stages } from '../db/schema.js'
+
+export async function wonAmountByMonth(request: IncomingMessage, response: ServerResponse) {
+  const url = new URL(request.url ?? '', 'http://localhost')
+  const year = Number.parseInt(url.searchParams.get('year') ?? String(new Date().getUTCFullYear()), 10)
+  if (!Number.isInteger(year) || year < 1970 || year > 9999) {
+    response.writeHead(400, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'invalid year' }))
+    return
+  }
+  const rows = await db.execute(sql`
+    SELECT
+      date_trunc('month', ${deals.wonAt})::date AS month,
+      ${deals.currency} AS currency,
+      COUNT(*)::int AS deal_count,
+      SUM(${deals.amountCents})::bigint AS won_amount_cents
+    FROM ${deals}
+    WHERE ${deals.wonAt} IS NOT NULL
+      AND EXTRACT(YEAR FROM ${deals.wonAt}) = ${year}
+    GROUP BY month, ${deals.currency}
+    ORDER BY month ASC, ${deals.currency} ASC
+  `)
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ year, rows }))
+}
+
+export async function pipelineValue(_request: IncomingMessage, response: ServerResponse) {
+  // Open deals per stage, weighted by stage probability.
+  const rows = await db.execute(sql`
+    SELECT
+      ${stages.id} AS stage_id,
+      ${stages.name} AS stage_name,
+      ${stages.order} AS stage_order,
+      ${stages.probability} AS probability,
+      ${deals.currency} AS currency,
+      COUNT(${deals.id})::int AS open_count,
+      COALESCE(SUM(${deals.amountCents}), 0)::bigint AS open_amount_cents,
+      COALESCE(SUM(${deals.amountCents} * ${stages.probability})::bigint, 0) AS weighted_amount_cents
+    FROM ${stages}
+    LEFT JOIN ${deals}
+      ON ${deals.stageId} = ${stages.id}
+      AND ${deals.status} = 'open'
+    WHERE ${stages.isClosedWon} = false
+      AND ${stages.isClosedLost} = false
+    GROUP BY ${stages.id}, ${stages.name}, ${stages.order}, ${stages.probability}, ${deals.currency}
+    ORDER BY ${stages.order} ASC
+  `)
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ rows }))
+}
+
+export async function winRate(_request: IncomingMessage, response: ServerResponse) {
+  // Returns counts per status so the caller can compute won/(won+lost) as needed.
+  const rows = await db
+    .select({
+      status: deals.status,
+      count: sql<number>`count(*)::int`,
+    })
+    .from(deals)
+    .groupBy(deals.status)
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ rows }))
+}

package/registry/layers/framework/crm-backend/files/schema.ts

@@ -0,0 +1,146 @@
+// CRM schema. Pipelines + stages are configurable rows, not enums, so users
+// can reorder / rename without migrations. Deal stage transitions are logged
+// in deal_stage_history so velocity reporting is possible.
+import { pgTable, uuid, varchar, timestamp, integer, text, boolean, real, jsonb, index, uniqueIndex, pgEnum } from 'drizzle-orm/pg-core'
+import { relations } from 'drizzle-orm'
+
+export const activityTypeEnum = pgEnum('activity_type', ['call', 'email', 'meeting', 'note', 'task'])
+export const dealStatusEnum = pgEnum('deal_status', ['open', 'won', 'lost'])
+
+export const companies = pgTable(
+  'companies',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    name: varchar('name', { length: 300 }).notNull(),
+    domain: varchar('domain', { length: 254 }),
+    industry: varchar('industry', { length: 100 }),
+    sizeRange: varchar('size_range', { length: 32 }), // "1-10", "11-50", etc.
+    website: text('website'),
+    ownerUserId: varchar('owner_user_id', { length: 128 }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+    deletedAt: timestamp('deleted_at', { withTimezone: true }),
+  },
+  (t) => ({ domainIdx: index('companies_domain_idx').on(t.domain) }),
+)
+
+export const contacts = pgTable(
+  'contacts',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    firstName: varchar('first_name', { length: 100 }),
+    lastName: varchar('last_name', { length: 100 }),
+    email: varchar('email', { length: 254 }),
+    phone: varchar('phone', { length: 32 }),
+    title: varchar('title', { length: 200 }),
+    companyId: uuid('company_id').references(() => companies.id, { onDelete: 'set null' }),
+    ownerUserId: varchar('owner_user_id', { length: 128 }),
+    customFields: jsonb('custom_fields').$type<Record<string, unknown>>().default({}),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+    lastContactedAt: timestamp('last_contacted_at', { withTimezone: true }),
+    deletedAt: timestamp('deleted_at', { withTimezone: true }),
+  },
+  (t) => ({
+    emailIdx: index('contacts_email_idx').on(t.email), // NOT unique — multiple contacts may share an email
+    companyIdx: index('contacts_company_idx').on(t.companyId),
+    ownerIdx: index('contacts_owner_idx').on(t.ownerUserId),
+  }),
+)
+
+export const pipelines = pgTable('pipelines', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  name: varchar('name', { length: 100 }).notNull(),
+  isDefault: boolean('is_default').notNull().default(false),
+  archivedAt: timestamp('archived_at', { withTimezone: true }),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+})
+
+export const stages = pgTable(
+  'stages',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    pipelineId: uuid('pipeline_id').notNull().references(() => pipelines.id, { onDelete: 'cascade' }),
+    name: varchar('name', { length: 100 }).notNull(),
+    order: integer('order').notNull(),
+    probability: real('probability').notNull().default(0), // 0..1
+    isClosedWon: boolean('is_closed_won').notNull().default(false),
+    isClosedLost: boolean('is_closed_lost').notNull().default(false),
+  },
+  (t) => ({
+    pipelineOrderUniq: uniqueIndex('stages_pipeline_order_uniq').on(t.pipelineId, t.order),
+  }),
+)
+
+export const deals = pgTable(
+  'deals',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    title: varchar('title', { length: 300 }).notNull(),
+    // Integer cents — never float. Multi-currency: currency is per-deal, not global.
+    amountCents: integer('amount_cents').notNull().default(0),
+    currency: varchar('currency', { length: 3 }).notNull().default('USD'),
+    stageId: uuid('stage_id').notNull().references(() => stages.id, { onDelete: 'restrict' }),
+    status: dealStatusEnum('status').notNull().default('open'),
+    contactId: uuid('contact_id').references(() => contacts.id, { onDelete: 'set null' }),
+    companyId: uuid('company_id').references(() => companies.id, { onDelete: 'set null' }),
+    ownerUserId: varchar('owner_user_id', { length: 128 }),
+    expectedCloseAt: timestamp('expected_close_at', { withTimezone: true }),
+    wonAt: timestamp('won_at', { withTimezone: true }),
+    lostAt: timestamp('lost_at', { withTimezone: true }),
+    lostReason: varchar('lost_reason', { length: 200 }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    stageIdx: index('deals_stage_idx').on(t.stageId),
+    ownerIdx: index('deals_owner_idx').on(t.ownerUserId),
+    companyIdx: index('deals_company_idx').on(t.companyId),
+    wonAtIdx: index('deals_won_at_idx').on(t.wonAt),
+  }),
+)
+
+export const dealStageHistory = pgTable('deal_stage_history', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  dealId: uuid('deal_id').notNull().references(() => deals.id, { onDelete: 'cascade' }),
+  fromStageId: uuid('from_stage_id').references(() => stages.id),
+  toStageId: uuid('to_stage_id').notNull().references(() => stages.id),
+  movedAt: timestamp('moved_at', { withTimezone: true }).notNull().defaultNow(),
+  movedByUserId: varchar('moved_by_user_id', { length: 128 }),
+  notes: text('notes'),
+})
+
+export const activities = pgTable(
+  'activities',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    type: activityTypeEnum('type').notNull(),
+    occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull(),
+    summary: varchar('summary', { length: 500 }).notNull(),
+    body: text('body'),
+    contactId: uuid('contact_id').references(() => contacts.id, { onDelete: 'set null' }),
+    companyId: uuid('company_id').references(() => companies.id, { onDelete: 'set null' }),
+    dealId: uuid('deal_id').references(() => deals.id, { onDelete: 'set null' }),
+    ownerUserId: varchar('owner_user_id', { length: 128 }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    contactOccurredIdx: index('activities_contact_occurred_idx').on(t.contactId, t.occurredAt),
+    dealOccurredIdx: index('activities_deal_occurred_idx').on(t.dealId, t.occurredAt),
+  }),
+)
+
+export const dealsRelations = relations(deals, ({ one, many }) => ({
+  stage: one(stages, { fields: [deals.stageId], references: [stages.id] }),
+  contact: one(contacts, { fields: [deals.contactId], references: [contacts.id] }),
+  company: one(companies, { fields: [deals.companyId], references: [companies.id] }),
+  activities: many(activities),
+  stageHistory: many(dealStageHistory),
+}))
+
+export type Company = typeof companies.$inferSelect
+export type Contact = typeof contacts.$inferSelect
+export type Pipeline = typeof pipelines.$inferSelect
+export type Stage = typeof stages.$inferSelect
+export type Deal = typeof deals.$inferSelect
+export type Activity = typeof activities.$inferSelect

package/registry/layers/framework/crm-backend/files/server.ts

@@ -0,0 +1,42 @@
+import http from 'node:http'
+import { createCompany, createContact, getCompany, getContact } from './api/contacts.js'
+import { createDeal, logActivity, moveDealStage } from './api/pipeline.js'
+import { pipelineValue, winRate, wonAmountByMonth } from './api/reporting.js'
+
+const port = Number.parseInt(process.env.PORT ?? '8104', 10)
+
+const server = http.createServer(async (request, response) => {
+  const url = new URL(request.url ?? '/', `http://127.0.0.1:${port}`)
+
+  if (url.pathname === '/health') {
+    response.writeHead(200, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ status: 'ok', service: process.env.SERVICE_NAME ?? 'starter-foundry-crm' }))
+    return
+  }
+
+  if (url.pathname === '/api/contacts' && request.method === 'POST') return createContact(request, response)
+  const contactMatch = /^\/api\/contacts\/([^/]+)$/.exec(url.pathname)
+  if (contactMatch && request.method === 'GET') return getContact(request, response, contactMatch[1]!)
+
+  if (url.pathname === '/api/companies' && request.method === 'POST') return createCompany(request, response)
+  const companyMatch = /^\/api\/companies\/([^/]+)$/.exec(url.pathname)
+  if (companyMatch && request.method === 'GET') return getCompany(request, response, companyMatch[1]!)
+
+  if (url.pathname === '/api/deals' && request.method === 'POST') return createDeal(request, response)
+  const dealStageMatch = /^\/api\/deals\/([^/]+)\/stage$/.exec(url.pathname)
+  if (dealStageMatch && request.method === 'PATCH') return moveDealStage(request, response, dealStageMatch[1]!)
+
+  if (url.pathname === '/api/activities' && request.method === 'POST') return logActivity(request, response)
+
+  if (url.pathname === '/api/reports/won-by-month' && request.method === 'GET') return wonAmountByMonth(request, response)
+  if (url.pathname === '/api/reports/pipeline-value' && request.method === 'GET') return pipelineValue(request, response)
+  if (url.pathname === '/api/reports/win-rate' && request.method === 'GET') return winRate(request, response)
+
+  response.writeHead(404, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ error: 'not found' }))
+})
+
+server.listen(port, '0.0.0.0', () => {
+  // eslint-disable-next-line no-console
+  console.log(`${process.env.SERVICE_NAME ?? 'starter-foundry-crm'} listening on ${port}`)
+})

package/registry/layers/framework/crm-backend/manifest.json

@@ -0,0 +1,89 @@
+{
+  "id": "crm-backend",
+  "description": "CRM framework layer — contacts/companies/deals/activities/stages schema, configurable pipeline, stage-move endpoint, won-amount-by-month reporting.",
+  "appliesTo": ["crm-backend"],
+  "files": [
+    { "source": "files/package.json", "target": "package.json" },
+    { "source": "files/server.ts", "target": "src/server.ts" },
+    { "source": "files/schema.ts", "target": "src/db/schema.ts" },
+    { "source": "files/db.ts", "target": "src/db/client.ts" },
+    { "source": "files/contacts.ts", "target": "src/api/contacts.ts" },
+    { "source": "files/pipeline.ts", "target": "src/api/pipeline.ts" },
+    { "source": "files/reporting.ts", "target": "src/api/reporting.ts" },
+    { "source": "files/drizzle.config.ts", "target": "drizzle.config.ts" }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "drizzle-orm": "^0.36.0",
+      "postgres": "^3.4.5"
+    },
+    "devDependencies": {
+      "drizzle-kit": "^0.30.0",
+      "typescript": "^5.9.0",
+      "@types/node": "^20.17.0"
+    }
+  },
+  "buildHints": {
+    "firstSteps": [
+      "Set DATABASE_URL=postgres://user:pass@localhost:5432/crm in your environment",
+      "Run pnpm install",
+      "Run pnpm db:generate then pnpm db:migrate to create tables",
+      "Run pnpm dev — the server starts on PORT (default 8104)",
+      "POST a Pipeline row first, then Stages, before creating Deals",
+      "GET /health to confirm the server is up"
+    ],
+    "apiRoutes": [
+      "GET /health",
+      "POST /api/contacts / GET /api/contacts/:id",
+      "POST /api/companies / GET /api/companies/:id",
+      "POST /api/deals (create a deal in a stage)",
+      "PATCH /api/deals/:id/stage (move deal across pipeline stages)",
+      "POST /api/activities (call / email / meeting linked to contact+deal)",
+      "GET /api/reports/won-by-month?year=2026",
+      "GET /api/reports/pipeline-value",
+      "GET /api/reports/win-rate (returns counts per status: open/won/lost)"
+    ],
+    "dataModels": [
+      "Company (name, domain, industry, sizeRange, ownerUserId)",
+      "Contact (firstName, lastName, email, phone, title, companyId nullable, ownerUserId)",
+      "Stage (pipelineId, order, name, probability, isClosedWon, isClosedLost) — configurable",
+      "Pipeline (name, isDefault, archivedAt)",
+      "Deal (title, amountCents, currency, stageId, contactId, companyId, ownerUserId, expectedCloseAt, wonAt, lostAt)",
+      "Activity (type: call|email|meeting|note|task, occurredAt, summary, dealId nullable, contactId nullable, ownerUserId)",
+      "DealStageHistory (dealId, fromStageId, toStageId, movedAt, movedByUserId) — audit of pipeline progression"
+    ],
+    "architectureNotes": [
+      "Stages are configurable rows, not an enum — let users reorder / rename / add stages without migrations",
+      "Won/lost deals set wonAt or lostAt timestamp + stage flag; reports filter on those",
+      "Stage transitions write a DealStageHistory row so velocity reports (avg days per stage) are possible",
+      "Amounts are integer cents — avoid float, avoid NUMERIC-vs-bigint lossiness"
+    ],
+    "gotchas": [
+      "Email uniqueness across contacts is a business decision. Multiple contacts can share an email (shared inboxes, spouses at same B2C account) — do NOT make email UNIQUE without product confirmation.",
+      "Deal amounts in integer cents, not NUMERIC(10,2). Multi-currency deals need a currency column per deal; do NOT convert at write time, convert at report time so historical rates don't corrupt the past.",
+      "Pipeline stages are user-editable. Queries that hard-code stage names will break the moment a user renames 'Qualified' to 'MQL'. Query by stage.id or by stage flags (isClosedWon).",
+      "Merging duplicate contacts/companies is a critical CRM feature this starter does NOT implement. Bad merges destroy activities and deals — add a reversible merge log before wiring a merge button.",
+      "GDPR / CCPA: contacts are personal data. Right-to-erasure must soft-delete and preserve activity records anonymized. Hard-deleting a contact cascades and loses historical deals — don't.",
+      "Activity timestamps are the source of truth for 'last contacted'. Background ingestion (email sync, calendar sync) must use the real send/meeting time, not the import time.",
+      "Closed deals are immutable for revenue reporting. Allow editing TITLE / NOTES but do NOT allow editing amount or stage on a deal where wonAt IS NOT NULL without an audit trail + a correction log."
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "pnpm dev",
+      "pnpm db:generate",
+      "pnpm db:migrate",
+      "pnpm typecheck"
+    ],
+    "entrypoints": [
+      "src/server.ts",
+      "src/db/schema.ts",
+      "src/api/contacts.ts",
+      "src/api/pipeline.ts",
+      "src/api/reporting.ts"
+    ],
+    "preview": { "path": "/health" },
+    "extensionPoints": ["src/db/schema.ts", "src/api/"]
+  }
+}

package/registry/layers/framework/deno-edge/files/handlers.ts

@@ -0,0 +1,24 @@
+type Handler = (request: Request) => Response | Promise<Response>
+
+interface HealthPayload {
+  status: 'ok'
+  service: string
+  database: string
+  sdk: string
+  runtime: 'deno'
+}
+
+function health(): Response {
+  const payload: HealthPayload = {
+    status: 'ok',
+    service: '{{serviceName}}',
+    database: '{{databaseProvider}}',
+    sdk: Deno.env.get('SDK_PROVIDER') ?? 'none',
+    runtime: 'deno',
+  }
+  return Response.json(payload)
+}
+
+export const routes: Record<string, Handler> = {
+  '/health': health,
+}

package/registry/layers/framework/deno-edge/files/server.ts

@@ -0,0 +1,12 @@
+import { routes } from './handlers.ts'
+
+const port = Number(Deno.env.get('PORT') ?? '{{port}}')
+
+Deno.serve({ port, hostname: '0.0.0.0' }, (request) => {
+  const url = new URL(request.url)
+  const handler = routes[url.pathname]
+  if (handler) return handler(request)
+  return new Response('not found', { status: 404 })
+})
+
+console.log(`{{serviceName}} listening on http://localhost:${port}`)

package/registry/layers/framework/deno-edge/manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "deno-edge",
+  "description": "Deno.serve-based HTTP framework layer for Deno edge API starters.",
+  "appliesTo": ["deno-edge"],
+  "files": [
+    {
+      "source": "files/server.ts",
+      "target": "src/server.ts"
+    },
+    {
+      "source": "files/handlers.ts",
+      "target": "src/handlers.ts"
+    }
+  ]
+}

package/registry/layers/framework/ecommerce-headless/files/.env.example

@@ -0,0 +1,12 @@
+# PostgreSQL connection string
+DATABASE_URL=postgres://user:pass@localhost:5432/commerce
+
+# Stripe API keys — get from https://dashboard.stripe.com/apikeys
+STRIPE_SECRET_KEY=sk_test_...
+
+# Stripe webhook signing secret — get from https://dashboard.stripe.com/webhooks
+# Run `stripe listen --forward-to localhost:${PORT}/webhooks/stripe` locally
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# HTTP server port (default: 8105)
+PORT=8105

package/registry/layers/framework/ecommerce-headless/files/AGENTS.md

@@ -0,0 +1,57 @@
+# Headless Commerce Backend
+
+Products → Variants → Carts → Line Items → Orders → Payments, with Stripe
+PaymentIntent checkout and signature-verified idempotent webhooks.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Fill in DATABASE_URL and STRIPE_SECRET_KEY in .env
+
+pnpm install
+pnpm db:generate   # generates drizzle migrations from src/db/schema.ts
+pnpm db:migrate    # runs migrations against DATABASE_URL
+pnpm dev           # starts server on PORT (default 8105)
+```
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `src/db/schema.ts` | Drizzle schema — products, variants, carts, line_items, orders, payments, webhook_events |
+| `src/api/cart.ts` | Cart CRUD + line-item upsert (price snapshot at add-to-cart time) |
+| `src/api/checkout.ts` | Atomic inventory decrement + Order creation + Stripe PaymentIntent |
+| `src/webhooks/stripe.ts` | Signature-verified, idempotent Stripe webhook handler |
+| `src/server.ts` | Node.js HTTP router |
+| `drizzle.config.ts` | Drizzle Kit config (reads DATABASE_URL) |
+
+## API routes
+
+```
+GET  /health
+GET  /api/products
+GET  /api/products/:id
+POST /api/carts
+GET  /api/carts/:id
+POST /api/carts/:id/items        { variantId, qty }
+DELETE /api/carts/:id/items/:lineItemId
+POST /api/carts/:id/checkout     → { orderId, paymentIntentId, clientSecret }
+POST /webhooks/stripe
+```
+
+## Extension points
+
+- **Add product fields**: edit `products` / `variants` tables in `src/db/schema.ts`, re-run `pnpm db:generate && pnpm db:migrate`.
+- **Tax computation**: `checkout.ts` sets `taxCents: 0` — integrate Stripe Tax / TaxJar here before going live.
+- **Shipping**: add a `shippingCents` calculation before the `orders.insert` in `checkout.ts`.
+- **Webhook events**: add cases to the `switch` in `src/webhooks/stripe.ts`.
+- **Auth**: wrap route handlers in an auth middleware that verifies the customer token and attaches `customerId`.
+
+## Critical invariants — do not break these
+
+- **Inventory is decremented on ORDER PLACEMENT** (not on payment success) inside the same DB transaction. Moving this to the webhook causes oversell.
+- **Line-item `unitPriceCents` is snapshotted** at `addLineItem` time. Do not re-read `variants.priceCents` at checkout.
+- **Stripe webhooks must verify the raw body** (before JSON parse) via `stripe.webhooks.constructEvent`. The handler reads the raw buffer first.
+- **`webhook_events.event_id` is the idempotency key.** Duplicate Stripe deliveries insert nothing (ON CONFLICT DO NOTHING) and return 200 immediately.
+- **Never store PAN/CVV**. Only `payment_intent_id` from Stripe. The `payments` table is PCI-SAQ-A compliant as long as card data never touches this server.

package/registry/layers/framework/ecommerce-headless/files/cart.ts

@@ -0,0 +1,119 @@
+// Cart API. Line-item unit_price is snapshot at add-to-cart time so catalog
+// edits don't retroactively alter a customer's open cart.
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { and, eq } from 'drizzle-orm'
+import { db } from '../db/client.ts'
+import { carts, lineItems, variants } from '../db/schema.ts'
+
+async function readJsonBody(request: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  for await (const chunk of request) chunks.push(chunk as Buffer)
+  const raw = Buffer.concat(chunks).toString('utf8')
+  return raw ? JSON.parse(raw) : null
+}
+
+export async function createCart(request: IncomingMessage, response: ServerResponse) {
+  const body = (await readJsonBody(request)) as {
+    customerId?: string
+    currency?: string
+  } | null
+  const [row] = await db
+    .insert(carts)
+    .values({
+      customerId: body?.customerId ?? null,
+      currency: body?.currency ?? 'USD',
+    })
+    .returning()
+  response.writeHead(201, { 'content-type': 'application/json' })
+  response.end(JSON.stringify(row))
+}
+
+export async function getCart(_request: IncomingMessage, response: ServerResponse, cartId: string) {
+  const [cart] = await db.select().from(carts).where(eq(carts.id, cartId)).limit(1)
+  if (!cart) {
+    response.writeHead(404, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'cart not found' }))
+    return
+  }
+  const items = await db.select().from(lineItems).where(eq(lineItems.cartId, cartId))
+  const subtotal = items.reduce((acc, it) => acc + it.unitPriceCents * it.qty, 0)
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ ...cart, items, subtotalCents: subtotal }))
+}
+
+export async function addLineItem(
+  request: IncomingMessage,
+  response: ServerResponse,
+  cartId: string,
+) {
+  const body = (await readJsonBody(request)) as {
+    variantId?: string
+    qty?: number
+  } | null
+  if (!body?.variantId || !body.qty || body.qty <= 0) {
+    response.writeHead(422, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'variantId and positive qty required' }))
+    return
+  }
+  const result = await db.transaction(async (tx) => {
+    const [cart] = await tx.select().from(carts).where(eq(carts.id, cartId)).limit(1)
+    if (!cart) throw new Error('CART_NOT_FOUND')
+    if (cart.status !== 'active') throw new Error('CART_NOT_ACTIVE')
+    const [variant] = await tx.select().from(variants).where(eq(variants.id, body.variantId!)).limit(1)
+    if (!variant) throw new Error('VARIANT_NOT_FOUND')
+    if (variant.currency !== cart.currency) throw new Error('CURRENCY_MISMATCH')
+
+    // Upsert-by-variant: if the variant is already in the cart, increment qty.
+    const [existing] = await tx
+      .select()
+      .from(lineItems)
+      .where(and(eq(lineItems.cartId, cartId), eq(lineItems.variantId, variant.id)))
+      .limit(1)
+    if (existing) {
+      const [updated] = await tx
+        .update(lineItems)
+        .set({ qty: existing.qty + body.qty! })
+        .where(eq(lineItems.id, existing.id))
+        .returning()
+      return updated
+    }
+    const [inserted] = await tx
+      .insert(lineItems)
+      .values({
+        cartId,
+        variantId: variant.id,
+        qty: body.qty!,
+        // Snapshot the current price. Catalog edits WILL NOT affect this cart.
+        unitPriceCents: variant.priceCents,
+        currency: variant.currency,
+      })
+      .returning()
+    await tx.update(carts).set({ updatedAt: new Date() }).where(eq(carts.id, cartId))
+    return inserted
+  }).catch((e) => e as Error)
+
+  if (result instanceof Error) {
+    const map: Record<string, number> = {
+      CART_NOT_FOUND: 404,
+      VARIANT_NOT_FOUND: 404,
+      CART_NOT_ACTIVE: 409,
+      CURRENCY_MISMATCH: 422,
+    }
+    response.writeHead(map[result.message] ?? 500, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: result.message }))
+    return
+  }
+  response.writeHead(201, { 'content-type': 'application/json' })
+  response.end(JSON.stringify(result))
+}
+
+export async function removeLineItem(
+  _request: IncomingMessage,
+  response: ServerResponse,
+  cartId: string,
+  lineItemId: string,
+) {
+  await db.delete(lineItems).where(and(eq(lineItems.cartId, cartId), eq(lineItems.id, lineItemId)))
+  response.writeHead(204)
+  response.end()
+}