@tangle-network/starter-foundry 0.5.4 → 0.7.2

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

@@ -0,0 +1,113 @@
+// Checkout: creates an Order from a Cart, decrements variant inventory IN
+// THE SAME TRANSACTION (prevents oversell), then creates a Stripe
+// PaymentIntent and returns the client_secret for the front-end to confirm.
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import Stripe from 'stripe'
+import { and, eq, sql } from 'drizzle-orm'
+import { db } from '../db/client.ts'
+import { carts, lineItems, orders, payments, variants } from '../db/schema.ts'
+
+const stripeKey = process.env.STRIPE_SECRET_KEY
+const stripe = stripeKey ? new Stripe(stripeKey, { apiVersion: '2025-09-30.clover' as Stripe.LatestApiVersion }) : null
+
+export async function checkout(
+  request: IncomingMessage,
+  response: ServerResponse,
+  cartId: string,
+) {
+  if (!stripe) {
+    response.writeHead(503, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'STRIPE_SECRET_KEY is not set' }))
+    return
+  }
+
+  let orderId: string | null = null
+  let totalCents = 0
+  let currency = 'USD'
+  let customerId: string | null = null
+
+  try {
+    const prepared = 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 items = await tx.select().from(lineItems).where(eq(lineItems.cartId, cartId))
+      if (items.length === 0) throw new Error('CART_EMPTY')
+
+      let subtotal = 0
+      for (const item of items) {
+        subtotal += item.unitPriceCents * item.qty
+        // Decrement inventory atomically. If updated rows === 0, we had no stock.
+        const updated = await tx
+          .update(variants)
+          .set({ inventoryQty: sql`${variants.inventoryQty} - ${item.qty}` })
+          .where(and(eq(variants.id, item.variantId), sql`${variants.inventoryQty} >= ${item.qty}`))
+          .returning({ id: variants.id })
+        if (updated.length === 0) throw new Error(`OUT_OF_STOCK:${item.variantId}`)
+      }
+
+      const orderNumber = `ORD-${Date.now()}-${Math.floor(Math.random() * 1e4).toString().padStart(4, '0')}`
+      const [order] = await tx
+        .insert(orders)
+        .values({
+          cartId,
+          customerId: cart.customerId,
+          orderNumber,
+          subtotalCents: subtotal,
+          taxCents: 0, // NOTE: integrate Stripe Tax / TaxJar / Avalara before production
+          shippingCents: 0,
+          totalCents: subtotal,
+          currency: cart.currency,
+          status: 'pending',
+        })
+        .returning()
+
+      await tx.update(carts).set({ status: 'checked_out' }).where(eq(carts.id, cartId))
+
+      return { order, subtotal, currency: cart.currency, customerId: cart.customerId }
+    })
+    orderId = prepared.order.id
+    totalCents = prepared.subtotal
+    currency = prepared.currency
+    customerId = prepared.customerId
+  } catch (err) {
+    const msg = (err as Error).message
+    const code = msg.startsWith('OUT_OF_STOCK:') ? 409 : msg === 'CART_NOT_FOUND' ? 404 : 422
+    response.writeHead(code, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: msg }))
+    return
+  }
+
+  // Outside the DB transaction: create the Stripe PaymentIntent and record it.
+  const intent = await stripe.paymentIntents.create(
+    {
+      amount: totalCents,
+      currency: currency.toLowerCase(),
+      metadata: { orderId: orderId!, customerId: customerId ?? '' },
+      automatic_payment_methods: { enabled: true },
+    },
+    {
+      // Prevents duplicate PaymentIntent creation if the client retries.
+      idempotencyKey: `order:${orderId}`,
+    },
+  )
+  await db.insert(payments).values({
+    orderId: orderId!,
+    processor: 'stripe',
+    processorId: intent.id,
+    amountCents: totalCents,
+    currency,
+    status: 'requires_action',
+  })
+
+  response.writeHead(201, { 'content-type': 'application/json' })
+  response.end(
+    JSON.stringify({
+      orderId,
+      paymentIntentId: intent.id,
+      clientSecret: intent.client_secret,
+      amountCents: totalCents,
+      currency,
+    }),
+  )
+}

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

@@ -0,0 +1,8 @@
+import postgres from 'postgres'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import * as schema from './schema.ts'
+
+const url = process.env.DATABASE_URL
+if (!url) throw new Error('DATABASE_URL is required')
+const client = postgres(url, { ssl: 'prefer', max: 10 })
+export const db = drizzle(client, { schema })

package/registry/layers/framework/ecommerce-headless/files/drizzle.config.ts

@@ -0,0 +1,9 @@
+import type { Config } from 'drizzle-kit'
+
+export default {
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+  dbCredentials: { url: process.env.DATABASE_URL ?? '' },
+  strict: true,
+} satisfies Config

package/registry/layers/framework/ecommerce-headless/files/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch --experimental-strip-types src/server.ts",
+    "start": "node --experimental-strip-types src/server.ts",
+    "typecheck": "tsc --noEmit",
+    "validate": "node validate-commerce.mjs",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.36.0",
+    "postgres": "^3.4.5",
+    "stripe": "^17.0.0"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.30.0",
+    "typescript": "^5.9.0",
+    "@types/node": "^20.17.0"
+  }
+}

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

@@ -0,0 +1,33 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { eq } from 'drizzle-orm'
+import { db } from '../db/client.ts'
+import { products, variants } from '../db/schema.ts'
+
+export async function listProducts(_request: IncomingMessage, response: ServerResponse) {
+  const rows = await db.select().from(products).where(eq(products.status, 'active'))
+  const variantRows = await db.select().from(variants)
+  const byProduct = new Map<string, typeof variantRows>()
+  for (const v of variantRows) {
+    const arr = byProduct.get(v.productId) ?? []
+    arr.push(v)
+    byProduct.set(v.productId, arr)
+  }
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(
+    JSON.stringify({
+      products: rows.map((p) => ({ ...p, variants: byProduct.get(p.id) ?? [] })),
+    }),
+  )
+}
+
+export async function getProduct(_request: IncomingMessage, response: ServerResponse, id: string) {
+  const [product] = await db.select().from(products).where(eq(products.id, id)).limit(1)
+  if (!product) {
+    response.writeHead(404, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'product not found' }))
+    return
+  }
+  const rows = await db.select().from(variants).where(eq(variants.productId, id))
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ ...product, variants: rows }))
+}

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

@@ -0,0 +1,160 @@
+// Headless commerce schema. Amounts are integer cents. Line-item prices are
+// snapshot at add-to-cart time so catalog edits don't retroactively change
+// open carts. Webhooks are idempotency-locked via webhook_events.eventId UNIQUE.
+import { pgTable, uuid, varchar, timestamp, integer, text, boolean, jsonb, index, uniqueIndex, pgEnum } from 'drizzle-orm/pg-core'
+import { relations } from 'drizzle-orm'
+
+export const productStatusEnum = pgEnum('product_status', ['active', 'draft', 'archived'])
+export const cartStatusEnum = pgEnum('cart_status', ['active', 'checked_out', 'abandoned'])
+export const orderStatusEnum = pgEnum('order_status', ['pending', 'paid', 'fulfilled', 'refunded', 'cancelled'])
+export const paymentStatusEnum = pgEnum('payment_status', ['requires_action', 'processing', 'succeeded', 'failed', 'refunded'])
+
+export const products = pgTable(
+  'products',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    handle: varchar('handle', { length: 100 }).notNull(), // URL slug
+    title: varchar('title', { length: 300 }).notNull(),
+    description: text('description'),
+    status: productStatusEnum('status').notNull().default('active'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({ handleUniq: uniqueIndex('products_handle_uniq').on(t.handle) }),
+)
+
+export const variants = pgTable(
+  'variants',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    productId: uuid('product_id').notNull().references(() => products.id, { onDelete: 'cascade' }),
+    sku: varchar('sku', { length: 100 }).notNull(),
+    title: varchar('title', { length: 200 }),
+    priceCents: integer('price_cents').notNull(),
+    currency: varchar('currency', { length: 3 }).notNull().default('USD'),
+    inventoryQty: integer('inventory_qty').notNull().default(0),
+    // Variant attributes like { color: 'red', size: 'M' } — shape is product-dependent.
+    attributes: jsonb('attributes').$type<Record<string, string>>().default({}),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({ skuUniq: uniqueIndex('variants_sku_uniq').on(t.sku) }),
+)
+
+export const carts = pgTable(
+  'carts',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    customerId: varchar('customer_id', { length: 128 }),
+    status: cartStatusEnum('status').notNull().default('active'),
+    currency: varchar('currency', { length: 3 }).notNull().default('USD'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({ customerIdx: index('carts_customer_idx').on(t.customerId) }),
+)
+
+export const lineItems = pgTable(
+  'line_items',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    cartId: uuid('cart_id').notNull().references(() => carts.id, { onDelete: 'cascade' }),
+    variantId: uuid('variant_id').notNull().references(() => variants.id, { onDelete: 'restrict' }),
+    qty: integer('qty').notNull(),
+    // Snapshot at add-to-cart time — do NOT recompute from variants.priceCents.
+    unitPriceCents: integer('unit_price_cents').notNull(),
+    currency: varchar('currency', { length: 3 }).notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    cartIdx: index('line_items_cart_idx').on(t.cartId),
+    cartVariantUniq: uniqueIndex('line_items_cart_variant_uniq').on(t.cartId, t.variantId),
+  }),
+)
+
+export const orders = pgTable(
+  'orders',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    cartId: uuid('cart_id').notNull().references(() => carts.id, { onDelete: 'restrict' }),
+    customerId: varchar('customer_id', { length: 128 }),
+    orderNumber: varchar('order_number', { length: 64 }).notNull(),
+    subtotalCents: integer('subtotal_cents').notNull(),
+    taxCents: integer('tax_cents').notNull().default(0),
+    shippingCents: integer('shipping_cents').notNull().default(0),
+    totalCents: integer('total_cents').notNull(),
+    currency: varchar('currency', { length: 3 }).notNull(),
+    status: orderStatusEnum('status').notNull().default('pending'),
+    placedAt: timestamp('placed_at', { withTimezone: true }).notNull().defaultNow(),
+    paidAt: timestamp('paid_at', { withTimezone: true }),
+    fulfilledAt: timestamp('fulfilled_at', { withTimezone: true }),
+    cancelledAt: timestamp('cancelled_at', { withTimezone: true }),
+  },
+  (t) => ({
+    orderNumberUniq: uniqueIndex('orders_order_number_uniq').on(t.orderNumber),
+    customerIdx: index('orders_customer_idx').on(t.customerId),
+    statusIdx: index('orders_status_idx').on(t.status),
+  }),
+)
+
+export const payments = pgTable(
+  'payments',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    orderId: uuid('order_id').notNull().references(() => orders.id, { onDelete: 'restrict' }),
+    processor: varchar('processor', { length: 32 }).notNull().default('stripe'),
+    processorId: varchar('processor_id', { length: 200 }).notNull(), // pi_... (Stripe PaymentIntent id)
+    amountCents: integer('amount_cents').notNull(),
+    currency: varchar('currency', { length: 3 }).notNull(),
+    status: paymentStatusEnum('status').notNull().default('requires_action'),
+    capturedAt: timestamp('captured_at', { withTimezone: true }),
+    refundedAt: timestamp('refunded_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    processorIdUniq: uniqueIndex('payments_processor_id_uniq').on(t.processor, t.processorId),
+    orderIdx: index('payments_order_idx').on(t.orderId),
+  }),
+)
+
+/**
+ * Webhook idempotency log. Every incoming webhook is deduped on processor+event_id.
+ * If a duplicate arrives, we skip processing and 200 back so the processor stops retrying.
+ */
+export const webhookEvents = pgTable(
+  'webhook_events',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    processor: varchar('processor', { length: 32 }).notNull(),
+    eventId: varchar('event_id', { length: 200 }).notNull(),
+    type: varchar('type', { length: 100 }).notNull(),
+    payload: jsonb('payload').notNull(),
+    receivedAt: timestamp('received_at', { withTimezone: true }).notNull().defaultNow(),
+    processedAt: timestamp('processed_at', { withTimezone: true }),
+    error: text('error'),
+  },
+  (t) => ({
+    processorEventUniq: uniqueIndex('webhook_events_processor_event_uniq').on(t.processor, t.eventId),
+    typeIdx: index('webhook_events_type_idx').on(t.type),
+  }),
+)
+
+export const productsRelations = relations(products, ({ many }) => ({
+  variants: many(variants),
+}))
+
+export const cartsRelations = relations(carts, ({ many }) => ({
+  lineItems: many(lineItems),
+}))
+
+export const ordersRelations = relations(orders, ({ one, many }) => ({
+  cart: one(carts, { fields: [orders.cartId], references: [carts.id] }),
+  payments: many(payments),
+}))
+
+export type Product = typeof products.$inferSelect
+export type Variant = typeof variants.$inferSelect
+export type Cart = typeof carts.$inferSelect
+export type LineItem = typeof lineItems.$inferSelect
+export type Order = typeof orders.$inferSelect
+export type Payment = typeof payments.$inferSelect
+export type WebhookEvent = typeof webhookEvents.$inferSelect

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

@@ -0,0 +1,43 @@
+import http from 'node:http'
+import { getProduct, listProducts } from './api/products.ts'
+import { addLineItem, createCart, getCart, removeLineItem } from './api/cart.ts'
+import { checkout } from './api/checkout.ts'
+import { stripeWebhook } from './webhooks/stripe.ts'
+
+const port = Number.parseInt(process.env.PORT ?? '{{port}}', 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: '{{serviceName}}', baseCurrency: '{{baseCurrency}}' }))
+    return
+  }
+
+  if (url.pathname === '/api/products' && request.method === 'GET') return listProducts(request, response)
+  const productMatch = /^\/api\/products\/([^/]+)$/.exec(url.pathname)
+  if (productMatch && request.method === 'GET') return getProduct(request, response, productMatch[1])
+
+  if (url.pathname === '/api/carts' && request.method === 'POST') return createCart(request, response)
+  const cartMatch = /^\/api\/carts\/([^/]+)$/.exec(url.pathname)
+  if (cartMatch && request.method === 'GET') return getCart(request, response, cartMatch[1])
+
+  const itemsMatch = /^\/api\/carts\/([^/]+)\/items$/.exec(url.pathname)
+  if (itemsMatch && request.method === 'POST') return addLineItem(request, response, itemsMatch[1])
+  const itemMatch = /^\/api\/carts\/([^/]+)\/items\/([^/]+)$/.exec(url.pathname)
+  if (itemMatch && request.method === 'DELETE') return removeLineItem(request, response, itemMatch[1], itemMatch[2])
+
+  const checkoutMatch = /^\/api\/carts\/([^/]+)\/checkout$/.exec(url.pathname)
+  if (checkoutMatch && request.method === 'POST') return checkout(request, response, checkoutMatch[1])
+
+  if (url.pathname === '/webhooks/stripe' && request.method === 'POST') return stripeWebhook(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(`{{serviceName}} listening on ${port}`)
+})

package/registry/layers/framework/ecommerce-headless/files/stripe-webhook.ts

@@ -0,0 +1,148 @@
+// Stripe webhook: signature-verified and idempotent.
+//
+// Signature verification MUST operate on the RAW request body BEFORE JSON
+// parse. Parsing first, then re-serializing, breaks verification because
+// whitespace / field-order differ.
+//
+// Idempotency: webhook_events.event_id UNIQUE. Duplicate deliveries return
+// 200 without re-running handlers so Stripe stops retrying.
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import Stripe from 'stripe'
+import { and, eq } from 'drizzle-orm'
+import { db } from '../db/client.ts'
+import { orders, payments, webhookEvents } from '../db/schema.ts'
+
+const stripeKey = process.env.STRIPE_SECRET_KEY
+const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET
+
+const stripe = stripeKey ? new Stripe(stripeKey, { apiVersion: '2025-09-30.clover' as Stripe.LatestApiVersion }) : null
+
+async function readRawBody(request: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = []
+  for await (const chunk of request) chunks.push(chunk as Buffer)
+  return Buffer.concat(chunks)
+}
+
+export async function stripeWebhook(request: IncomingMessage, response: ServerResponse) {
+  if (!stripe || !webhookSecret) {
+    response.writeHead(503, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'Stripe not configured' }))
+    return
+  }
+  const signature = request.headers['stripe-signature']
+  if (typeof signature !== 'string') {
+    response.writeHead(400, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'missing stripe-signature header' }))
+    return
+  }
+
+  const raw = await readRawBody(request)
+
+  let event: Stripe.Event
+  try {
+    // constructEvent takes the raw body (Buffer/string) and verifies HMAC.
+    event = stripe.webhooks.constructEvent(raw, signature, webhookSecret!)
+  } catch (err) {
+    response.writeHead(400, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: `signature verification failed: ${(err as Error).message}` }))
+    return
+  }
+
+  // Idempotency: ON CONFLICT DO NOTHING on (processor, event_id). If the row
+  // already exists we skip handling and 200 back.
+  const inserted = await db
+    .insert(webhookEvents)
+    .values({
+      processor: 'stripe',
+      eventId: event.id,
+      type: event.type,
+      payload: event as unknown as Record<string, unknown>,
+    })
+    .onConflictDoNothing({ target: [webhookEvents.processor, webhookEvents.eventId] })
+    .returning({ id: webhookEvents.id })
+
+  if (inserted.length === 0) {
+    // Duplicate delivery — already processed. 200 so Stripe stops retrying.
+    response.writeHead(200, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ idempotent: true }))
+    return
+  }
+
+  try {
+    switch (event.type) {
+      case 'payment_intent.succeeded':
+        await handlePaymentSucceeded(event.data.object as Stripe.PaymentIntent)
+        break
+      case 'payment_intent.payment_failed':
+        await handlePaymentFailed(event.data.object as Stripe.PaymentIntent)
+        break
+      case 'charge.refunded':
+        await handleRefund(event.data.object as Stripe.Charge)
+        break
+      default:
+        // Unhandled type — stored in webhook_events for later inspection.
+        break
+    }
+    await db
+      .update(webhookEvents)
+      .set({ processedAt: new Date() })
+      .where(eq(webhookEvents.id, inserted[0]!.id))
+    response.writeHead(200, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ ok: true }))
+  } catch (err) {
+    // Keep the row so Stripe retries; record the error for debugging.
+    await db
+      .update(webhookEvents)
+      .set({ error: (err as Error).message })
+      .where(eq(webhookEvents.id, inserted[0]!.id))
+    response.writeHead(500, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: (err as Error).message }))
+  }
+}
+
+async function handlePaymentSucceeded(pi: Stripe.PaymentIntent): Promise<void> {
+  const orderId = pi.metadata?.orderId
+  if (!orderId) return
+  await db.transaction(async (tx) => {
+    await tx
+      .update(payments)
+      .set({ status: 'succeeded', capturedAt: new Date() })
+      .where(and(eq(payments.processor, 'stripe'), eq(payments.processorId, pi.id)))
+    await tx
+      .update(orders)
+      .set({ status: 'paid', paidAt: new Date() })
+      .where(eq(orders.id, orderId))
+  })
+}
+
+async function handlePaymentFailed(pi: Stripe.PaymentIntent): Promise<void> {
+  const orderId = pi.metadata?.orderId
+  if (!orderId) return
+  await db
+    .update(payments)
+    .set({ status: 'failed' })
+    .where(and(eq(payments.processor, 'stripe'), eq(payments.processorId, pi.id)))
+  // NOTE: restoring inventory on failure is a separate decision. If the
+  // PI can be retried, don't restore. If the order is cancelled, restore.
+}
+
+async function handleRefund(charge: Stripe.Charge): Promise<void> {
+  const piId = typeof charge.payment_intent === 'string' ? charge.payment_intent : charge.payment_intent?.id
+  if (!piId) return
+  await db.transaction(async (tx) => {
+    const [pay] = await tx
+      .select()
+      .from(payments)
+      .where(and(eq(payments.processor, 'stripe'), eq(payments.processorId, piId)))
+      .limit(1)
+    if (!pay) return
+    await tx
+      .update(payments)
+      .set({ status: 'refunded', refundedAt: new Date() })
+      .where(eq(payments.id, pay.id))
+    await tx
+      .update(orders)
+      .set({ status: 'refunded' })
+      .where(eq(orders.id, pay.orderId))
+  })
+}

package/registry/layers/framework/ecommerce-headless/files/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src/**/*.ts", "drizzle.config.ts"]
+}

package/registry/layers/framework/ecommerce-headless/manifest.json

@@ -0,0 +1,81 @@
+{
+  "id": "ecommerce-headless",
+  "description": "Headless commerce framework layer — products/variants/carts/line_items/orders/payments/webhook_events schema, Stripe PaymentIntent checkout, signature-verified idempotent Stripe webhooks.",
+  "appliesTo": ["ecommerce-headless"],
+  "files": [
+    { "source": "files/package.json", "target": "package.json" },
+    { "source": "files/tsconfig.json", "target": "tsconfig.json" },
+    { "source": "files/.env.example", "target": ".env.example" },
+    { "source": "files/AGENTS.md", "target": "AGENTS.md" },
+    { "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/products.ts", "target": "src/api/products.ts" },
+    { "source": "files/cart.ts", "target": "src/api/cart.ts" },
+    { "source": "files/checkout.ts", "target": "src/api/checkout.ts" },
+    { "source": "files/stripe-webhook.ts", "target": "src/webhooks/stripe.ts" },
+    { "source": "files/drizzle.config.ts", "target": "drizzle.config.ts" }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "drizzle-orm": "^0.36.0",
+      "postgres": "^3.4.5",
+      "stripe": "^17.0.0"
+    },
+    "devDependencies": {
+      "drizzle-kit": "^0.30.0",
+      "typescript": "^5.9.0",
+      "@types/node": "^20.17.0"
+    }
+  },
+  "buildHints": {
+    "apiRoutes": [
+      "GET /health",
+      "GET /api/products / GET /api/products/:id",
+      "POST /api/carts (create cart)",
+      "POST /api/carts/:id/items (add line item)",
+      "DELETE /api/carts/:id/items/:lineItemId",
+      "POST /api/carts/:id/checkout (creates Order + Stripe PaymentIntent, returns client_secret)",
+      "POST /webhooks/stripe (signature-verified, idempotent)"
+    ],
+    "dataModels": [
+      "Product (handle, title, description, status: active|draft|archived)",
+      "Variant (productId, sku, priceCents, currency, inventoryQty, attributes jsonb)",
+      "Cart (customerId nullable, status: active|checked_out|abandoned, currency)",
+      "LineItem (cartId, variantId, qty, unitPriceCents snapshot)",
+      "Order (cartId, customerId, subtotalCents, taxCents, totalCents, status: pending|paid|fulfilled|refunded|cancelled, placedAt, paidAt)",
+      "Payment (orderId, processor: stripe, processorId piId, amountCents, status, capturedAt)",
+      "WebhookEvent (processor, eventId UNIQUE, type, receivedAt, processedAt, payloadJson) — idempotency key"
+    ],
+    "integrations": [
+      "Stripe PaymentIntents for checkout (confirm on client with client_secret)",
+      "Stripe webhooks with signature verification (stripe.webhooks.constructEvent)",
+      "Drizzle ORM with Postgres"
+    ],
+    "architectureNotes": [
+      "Prices captured on LineItem at add-to-cart time — product price changes don't retroactively alter carts",
+      "Inventory decremented on ORDER PLACEMENT (not payment success) to prevent overselling during payment processing",
+      "Webhook idempotency: webhook_events.event_id is UNIQUE; duplicate Stripe deliveries no-op instead of double-crediting the order",
+      "Amounts are integer cents, currency per-row (Stripe minimum amount is also in cents)"
+    ],
+    "firstSteps": [
+      "Copy .env.example to .env and fill in DATABASE_URL (postgres://...) and STRIPE_SECRET_KEY (sk_test_...)",
+      "Run `pnpm db:generate` then `pnpm db:migrate` to create the schema in your database",
+      "Run `pnpm dev` — server starts on PORT (default 8105); confirm with GET /health",
+      "For local webhook testing: `stripe listen --forward-to localhost:8105/webhooks/stripe` and set STRIPE_WEBHOOK_SECRET to the printed whsec_ value",
+      "To add a product: INSERT into products + variants tables (priceCents is integer cents, currency is 3-char ISO code)",
+      "Extend src/db/schema.ts for new fields, then re-run db:generate + db:migrate — Drizzle infers the migration diff automatically"
+    ],
+    "gotchas": [
+      "Stripe webhook signatures MUST be verified with the raw request body BEFORE JSON parsing. Parsing first, then verifying against a re-serialized body, fails because of whitespace differences.",
+      "Webhooks MUST be idempotent. Stripe retries on any non-2xx AND on timeouts even after you succeed. Use webhook_events.event_id UNIQUE as the lock.",
+      "PCI-DSS: NEVER store card numbers (PAN), CVV, or full track data. Only Stripe's payment_intent_id / payment_method_id. PCI-SAQ A requires card data never touches your server — use Stripe.js on the client, server only sees tokens.",
+      "Oversell bug: decrement inventory in the SAME transaction as order placement. Decrementing on webhook 'payment_succeeded' leaves a race where two customers claim the last unit.",
+      "Price drift: snapshot the unit_price onto LineItem at add-to-cart. Reading product.price at checkout means catalog edits retroactively charge customers more (or less).",
+      "Tax is jurisdictional and this scaffold does NOT compute it. Integrate TaxJar / Stripe Tax / Avalara before going live; don't hard-code a percentage.",
+      "Refunds are NEW records (refund payment with negative amount OR separate Refund entity), not UPDATEs to the original payment. Financial auditability demands it.",
+      "Cart expiration / abandoned cart cleanup must NOT release inventory that was decremented on order placement — inventory is released by cancelling the order explicitly.",
+      "Currency minor units differ: JPY has 0 decimals, USD has 2, TND has 3. amountCents isn't literally 'cents' for every currency — follow Stripe's currency docs."
+    ]
+  }
+}