@porulle/core 0.7.0 → 0.8.0

package/src/modules/catalog/entity-service.ts

@@ -212,7 +212,7 @@ export class EntityService {
     const afterHooks = this.deps.hooks.resolve("catalog.afterCreate") as CatalogCreateAfterHook[];
     const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.create"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
     const processedInput = await runBeforeHooks(beforeHooks, input, "create", context);
-    const entity = await this.repo.createEntity({ organizationId: orgId, type: processedInput.type, slug: processedInput.slug, status: "draft", isVisible: false, metadata: processedInput.metadata ?? {} }, ctx);
+    const entity = await this.repo.createEntity({ organizationId: orgId, type: processedInput.type, slug: processedInput.slug, status: "draft", isVisible: false, ...(processedInput.taxClass !== undefined ? { taxClass: processedInput.taxClass } : {}), metadata: processedInput.metadata ?? {} }, ctx);
     if (processedInput.attributes) {
       await this.repo.createAttribute({ entityId: entity.id, locale: processedInput.attributes.locale ?? "en", title: processedInput.attributes.title, subtitle: processedInput.attributes.subtitle, description: processedInput.attributes.description, richDescription: processedInput.attributes.richDescription, seoTitle: processedInput.attributes.seoTitle, seoDescription: processedInput.attributes.seoDescription }, ctx);
     }
@@ -232,7 +232,7 @@ export class EntityService {
     const afterHooks = this.deps.hooks.resolve("catalog.afterUpdate") as CatalogUpdateAfterHook[];
     const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.update"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
     const processed = await runBeforeHooks(beforeHooks, input, "update", context);
-    const updated = await this.repo.updateEntity(id, { ...(processed.slug !== undefined ? { slug: processed.slug } : {}), ...(processed.status !== undefined ? { status: processed.status as SellableEntity["status"] } : {}), ...(processed.metadata !== undefined ? { metadata: processed.metadata } : {}), ...(processed.isVisible !== undefined ? { isVisible: processed.isVisible } : {}) }, ctx);
+    const updated = await this.repo.updateEntity(id, { ...(processed.slug !== undefined ? { slug: processed.slug } : {}), ...(processed.status !== undefined ? { status: processed.status as SellableEntity["status"] } : {}), ...(processed.taxClass !== undefined ? { taxClass: processed.taxClass } : {}), ...(processed.metadata !== undefined ? { metadata: processed.metadata } : {}), ...(processed.isVisible !== undefined ? { isVisible: processed.isVisible } : {}) }, ctx);
     if (!updated) return Err(new CommerceNotFoundError("Entity not found."));
     const hookReport = await runAfterHooks(afterHooks, existing, updated, "update", context);
     const hydrated = await this.hydrateEntity(updated, undefined, ctx);
@@ -437,7 +437,7 @@ export class EntityService {
       if (!ov) return Err(new CommerceValidationError(`Option value "${optVal}" does not exist for option type "${optName}".`));
       optionValueIds.push(ov.id);
     }
-    const variant = await this.repo.createVariant({ entityId: input.entityId, status: "active", sortOrder: 0, metadata: {}, ...(input.sku !== undefined ? { sku: input.sku } : {}) }, ctx);
+    const variant = await this.repo.createVariant({ entityId: input.entityId, status: "active", sortOrder: 0, metadata: {}, ...(input.sku !== undefined ? { sku: input.sku } : {}), ...(input.taxClass !== undefined ? { taxClass: input.taxClass } : {}) }, ctx);
     await this.repo.createVariantOptionValues(optionValueIds.map((optionValueId) => ({ variantId: variant.id, optionValueId })), ctx);
     return Ok(variant);
   }
@@ -490,4 +490,169 @@ export class EntityService {
     }
     return Ok(created);
   }
+
+  // ── One-call variant creation (issue #50) ────────────────────────────────
+  // Upserts option axes inline, creates variants, and seeds a zero-stock
+  // inventory level per variant so it is sellable immediately. Retry-safe:
+  // axes upsert by name/value and existing combinations are skipped.
+
+  private async upsertAxes(
+    entityId: string,
+    axes: Array<{ name: string; values: string[] }>,
+    ctx?: TxContext,
+  ): Promise<Map<string, Map<string, string>>> {
+    const existingTypes = await this.repo.findOptionTypesByEntityId(entityId, ctx);
+    const result = new Map<string, Map<string, string>>();
+    for (const axis of axes) {
+      let optionType = existingTypes.find((t) => t.name === axis.name);
+      if (!optionType) {
+        optionType = await this.repo.createOptionType(
+          { entityId, name: axis.name, displayName: axis.name, sortOrder: existingTypes.length },
+          ctx,
+        );
+        existingTypes.push(optionType);
+      }
+      const existingValues = await this.repo.findOptionValuesByTypeId(optionType.id, ctx);
+      const valueIds = new Map<string, string>();
+      for (const value of axis.values) {
+        let optionValue = existingValues.find((v) => v.value === value);
+        if (!optionValue) {
+          optionValue = await this.repo.createOptionValue(
+            { optionTypeId: optionType.id, value, displayValue: value, sortOrder: existingValues.length, metadata: {} },
+            ctx,
+          );
+          existingValues.push(optionValue);
+        }
+        valueIds.set(value, optionValue.id);
+      }
+      result.set(axis.name, valueIds);
+    }
+    return result;
+  }
+
+  private async existingComboKeys(entityId: string, ctx?: TxContext): Promise<Map<string, string>> {
+    const existing = new Map<string, string>();
+    for (const variant of await this.repo.findVariantsByEntityId(entityId, ctx)) {
+      const rows = await this.repo.findVariantOptionValues(variant.id, ctx);
+      const key = rows.map((r) => r.optionValueId).sort().join("|");
+      existing.set(key, variant.id);
+    }
+    return existing;
+  }
+
+  private async seedInventoryLevel(
+    entityId: string,
+    variantId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<unknown>> {
+    const inventory = this.deps.services.inventory as {
+      adjustDetailed: (
+        input: { entityId: string; variantId?: string; adjustment: number; reason: string },
+        actor?: Actor | null,
+        ctx?: TxContext,
+      ) => Promise<Result<unknown>>;
+    };
+    return inventory.adjustDetailed(
+      { entityId, variantId, adjustment: 0, reason: "Variant created — seed zero-stock level" },
+      actor,
+      ctx,
+    );
+  }
+
+  async quickCreateVariant(
+    entityId: string,
+    input: { options: Record<string, string>; sku?: string | undefined; barcode?: string | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ variant: Variant; created: boolean }>> {
+    try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
+    const entity = await this.repo.findEntityById(entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    try { this.assertSameOrg(entity, actor); } catch (error) { return Err(toCommerceError(error)); }
+
+    const axes = Object.entries(input.options).map(([name, value]) => ({ name, values: [value] }));
+    const axisValueIds = await this.upsertAxes(entityId, axes, ctx);
+    const optionValueIds = Object.entries(input.options)
+      .map(([name, value]) => axisValueIds.get(name)!.get(value)!);
+
+    const key = [...optionValueIds].sort().join("|");
+    const existing = await this.existingComboKeys(entityId, ctx);
+    const existingVariantId = existing.get(key);
+    if (existingVariantId !== undefined) {
+      const variant = await this.repo.findVariantById(existingVariantId, ctx);
+      return Ok({ variant: variant!, created: false });
+    }
+
+    const variant = await this.repo.createVariant(
+      {
+        entityId,
+        status: "active",
+        sortOrder: 0,
+        metadata: { generatedBy: "quick" },
+        ...(input.sku !== undefined ? { sku: input.sku } : {}),
+        ...(input.barcode !== undefined ? { barcode: input.barcode } : {}),
+      },
+      ctx,
+    );
+    await this.repo.createVariantOptionValues(
+      optionValueIds.map((optionValueId) => ({ variantId: variant.id, optionValueId })),
+      ctx,
+    );
+    const seeded = await this.seedInventoryLevel(entityId, variant.id, actor, ctx);
+    if (!seeded.ok) return seeded;
+    return Ok({ variant, created: true });
+  }
+
+  async bulkCreateVariants(
+    entityId: string,
+    input: { axes: Array<{ name: string; values: string[] }>; skuPrefix?: string | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ created: Variant[]; skipped: number }>> {
+    try { assertPermission(actor, "catalog:update"); } catch (error) { return Err(toCommerceError(error)); }
+    const entity = await this.repo.findEntityById(entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    try { this.assertSameOrg(entity, actor); } catch (error) { return Err(toCommerceError(error)); }
+
+    const axisValueIds = await this.upsertAxes(entityId, input.axes, ctx);
+    // Empty axis list → one option-less variant.
+    const groups = input.axes.map((axis) =>
+      axis.values.map((value) => ({ value, id: axisValueIds.get(axis.name)!.get(value)! })),
+    );
+    const combinations = cartesian(groups);
+
+    const existing = await this.existingComboKeys(entityId, ctx);
+    const created: Variant[] = [];
+    let skipped = 0;
+    for (const combo of combinations) {
+      const key = combo.map((c) => c.id).sort().join("|");
+      if (existing.has(key)) {
+        skipped += 1;
+        continue;
+      }
+      const sku = input.skuPrefix !== undefined
+        ? [input.skuPrefix, ...combo.map((c) => c.value)].join("-").toUpperCase().replace(/\s+/g, "-")
+        : undefined;
+      const variant = await this.repo.createVariant(
+        {
+          entityId,
+          status: "active",
+          sortOrder: 0,
+          metadata: { generatedBy: "bulk" },
+          ...(sku !== undefined ? { sku } : {}),
+        },
+        ctx,
+      );
+      await this.repo.createVariantOptionValues(
+        combo.map((c) => ({ variantId: variant.id, optionValueId: c.id })),
+        ctx,
+      );
+      const seeded = await this.seedInventoryLevel(entityId, variant.id, actor, ctx);
+      if (!seeded.ok) return seeded;
+      existing.set(key, variant.id);
+      created.push(variant);
+    }
+    return Ok({ created, skipped });
+  }
 }

package/src/modules/catalog/schema.ts

@@ -25,6 +25,9 @@ export const sellableEntities = pgTable(
       .notNull()
       .default("draft"),
     isVisible: boolean("is_visible").notNull().default(false),
+    // Tax class name (issue #57) — maps to tax_classes.name at checkout;
+    // a variant-level taxClass overrides this. Null = the org's default class.
+    taxClass: text("tax_class"),
     metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
@@ -183,6 +186,8 @@ export const variants = pgTable("variants", {
     .notNull(),
   sku: text("sku").unique(),
   barcode: text("barcode"),
+  // Overrides the entity's taxClass when set (issue #57).
+  taxClass: text("tax_class"),
   status: text("status", { enum: ["active", "discontinued"] })
     .notNull()
     .default("active"),

package/src/modules/catalog/schemas.ts

@@ -6,6 +6,7 @@ export const CreateEntityBodySchema = z.object({
   type: z.string().openapi({ example: "physicalGood" }),
   slug: z.string().openapi({ example: "my-product" }),
   status: z.string().optional().openapi({ example: "draft" }),
+  taxClass: z.string().optional().openapi({ example: "standard", description: "Product tax class name (issue #57)." }),
   basePrice: z.number().optional().openapi({ example: 29.99 }),
   currency: z.string().optional().openapi({ example: "USD" }),
   metadata: z.record(z.string(), z.unknown()).optional().openapi({ example: { title: "My Product" } }),
@@ -24,6 +25,7 @@ export const CreateEntityBodySchema = z.object({
 export const UpdateEntityBodySchema = z.object({
   slug: z.string().optional(),
   status: z.string().optional(),
+  taxClass: z.string().nullable().optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
   isVisible: z.boolean().optional(),
 }).openapi("UpdateEntityBody");
@@ -69,6 +71,7 @@ export const CreateVariantBodySchema = z.object({
   sku: z.string().optional().openapi({ example: "SKU-001" }),
   options: z.record(z.string(), z.string()).openapi({ example: { Color: "Red" } }),
   price: z.number().optional().openapi({ example: 34.99 }),
+  taxClass: z.string().optional().openapi({ example: "zero", description: "Overrides the entity's tax class (issue #57)." }),
 }).openapi("CreateVariantBody");
 
 const VariantMatrixRuleSchema = z.object({

package/src/modules/catalog/service.ts

@@ -259,6 +259,18 @@ export interface CatalogService {
     actor: Actor | null,
     ctx?: TxContext,
   ): Promise<Result<Variant[]>>;
+  quickCreateVariant(
+    entityId: string,
+    input: { options: Record<string, string>; sku?: string | undefined; barcode?: string | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ variant: Variant; created: boolean }>>;
+  bulkCreateVariants(
+    entityId: string,
+    input: { axes: Array<{ name: string; values: string[] }>; skuPrefix?: string | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ created: Variant[]; skipped: number }>>;
 }
 
 export interface CatalogServiceDeps {
@@ -411,4 +423,22 @@ export class CatalogServiceImpl implements CatalogService {
   generateVariants(entityId: string, strategy: VariantGenerationStrategy, actor: Actor | null, ctx?: TxContext): Promise<Result<Variant[]>> {
     return this.entities.generateVariants(entityId, strategy, actor, ctx);
   }
+
+  quickCreateVariant(
+    entityId: string,
+    input: { options: Record<string, string>; sku?: string | undefined; barcode?: string | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ variant: Variant; created: boolean }>> {
+    return this.entities.quickCreateVariant(entityId, input, actor, ctx);
+  }
+
+  bulkCreateVariants(
+    entityId: string,
+    input: { axes: Array<{ name: string; values: string[] }>; skuPrefix?: string | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ created: Variant[]; skipped: number }>> {
+    return this.entities.bulkCreateVariants(entityId, input, actor, ctx);
+  }
 }

package/src/modules/documents/module.ts

@@ -0,0 +1,19 @@
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { defineModule } from "../../kernel/module/index.js";
+import { DocumentsRepository } from "./repository/index.js";
+import { invoiceSequences, orderDocuments } from "./schema.js";
+import { DocumentsService } from "./service.js";
+
+export const documentsModule = defineModule<
+  { invoiceSequences: typeof invoiceSequences; orderDocuments: typeof orderDocuments },
+  DocumentsService,
+  Record<string, never>
+>({
+  id: "documents",
+  schema: () => ({ invoiceSequences, orderDocuments }),
+  service: (deps) =>
+    new DocumentsService({
+      repository: new DocumentsRepository(deps.db.db as DrizzleDatabase),
+      services: deps.services as Record<string, unknown>,
+    }),
+});

package/src/modules/documents/pdf.ts

@@ -0,0 +1,101 @@
+/**
+ * Minimal dependency-free PDF writer (issue #47).
+ *
+ * Emits PDF 1.4 with Helvetica / Helvetica-Bold (built-in base-14 fonts, no
+ * embedding) and uncompressed content streams. Pure string/Uint8Array work —
+ * no Node-only APIs, so it runs on Cloudflare Workers and other serverless
+ * runtimes. Enough for text documents like invoices; not a general renderer.
+ */
+
+export interface PdfTextOp {
+  x: number;
+  y: number;
+  size: number;
+  bold?: boolean | undefined;
+  text: string;
+}
+
+/** A4 in PDF points. */
+export const A4 = { width: 595.28, height: 841.89 } as const;
+
+// Escape to a PDF literal string: backslash, parens, and non-ASCII bytes as
+// octal escapes (Latin-1 / WinAnsi range; anything beyond becomes "?").
+function escapePdfText(text: string): string {
+  let out = "";
+  for (const ch of text) {
+    const code = ch.codePointAt(0)!;
+    if (ch === "\\" || ch === "(" || ch === ")") out += `\\${ch}`;
+    else if (code >= 32 && code <= 126) out += ch;
+    else if (code > 126 && code <= 255) out += `\\${code.toString(8).padStart(3, "0")}`;
+    else out += "?";
+  }
+  return out;
+}
+
+function contentStream(ops: PdfTextOp[]): string {
+  const parts: string[] = [];
+  for (const op of ops) {
+    const font = op.bold ? "/F2" : "/F1";
+    parts.push(
+      `BT ${font} ${op.size} Tf ${op.x.toFixed(2)} ${op.y.toFixed(2)} Td (${escapePdfText(op.text)}) Tj ET`,
+    );
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Builds a complete PDF document; one inner array of text ops per page.
+ */
+export function buildPdf(pages: PdfTextOp[][]): Uint8Array {
+  // Object numbering: 1 Catalog, 2 Pages, 3 F1, 4 F2, then per page: Page, Contents.
+  const objects: string[] = [];
+  const pageObjectNumbers: number[] = [];
+  const firstPageObj = 5;
+
+  for (let i = 0; i < pages.length; i++) {
+    pageObjectNumbers.push(firstPageObj + i * 2);
+  }
+
+  objects.push(`1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n`);
+  objects.push(
+    `2 0 obj\n<< /Type /Pages /Kids [${pageObjectNumbers.map((n) => `${n} 0 R`).join(" ")}] /Count ${pages.length} >>\nendobj\n`,
+  );
+  objects.push(`3 0 obj\n<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>\nendobj\n`);
+  objects.push(`4 0 obj\n<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding >>\nendobj\n`);
+
+  for (let i = 0; i < pages.length; i++) {
+    const pageNum = pageObjectNumbers[i]!;
+    const contentNum = pageNum + 1;
+    const stream = contentStream(pages[i]!);
+    objects.push(
+      `${pageNum} 0 obj\n<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${A4.width} ${A4.height}] ` +
+        `/Resources << /Font << /F1 3 0 R /F2 4 0 R >> >> /Contents ${contentNum} 0 R >>\nendobj\n`,
+    );
+    objects.push(
+      `${contentNum} 0 obj\n<< /Length ${stream.length} >>\nstream\n${stream}\nendstream\nendobj\n`,
+    );
+  }
+
+  const header = "%PDF-1.4\n";
+  let body = header;
+  const offsets: number[] = [];
+  for (const obj of objects) {
+    offsets.push(body.length);
+    body += obj;
+  }
+
+  const xrefOffset = body.length;
+  const count = objects.length + 1;
+  let xref = `xref\n0 ${count}\n0000000000 65535 f \n`;
+  for (const offset of offsets) {
+    xref += `${offset.toString().padStart(10, "0")} 00000 n \n`;
+  }
+  const trailer = `trailer\n<< /Size ${count} /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF\n`;
+
+  const full = body + xref + trailer;
+  // All bytes are ASCII/Latin-1 by construction (escapePdfText), so a
+  // byte-per-char encoding is exact.
+  const bytes = new Uint8Array(full.length);
+  for (let i = 0; i < full.length; i++) bytes[i] = full.charCodeAt(i) & 0xff;
+  return bytes;
+}

package/src/modules/documents/render.ts

@@ -0,0 +1,231 @@
+import type { HydratedOrder } from "../orders/service.js";
+import { A4, type PdfTextOp } from "./pdf.js";
+
+/** Branding values read from the settings module's `branding` group. */
+export interface DocumentBranding {
+  storeName?: string;
+  receiptHeader?: string;
+  receiptFooter?: string;
+  logoUrl?: string;
+  address?: string;
+  phone?: string;
+  email?: string;
+  taxId?: string;
+}
+
+export interface DocumentContext {
+  order: HydratedOrder;
+  branding: DocumentBranding;
+  invoiceNumber: string;
+}
+
+export function escapeHtml(value: unknown): string {
+  return String(value ?? "")
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+/** Minor units → "1,234.50 LKR". */
+export function formatAmount(minor: number, currency: string): string {
+  const major = minor / 100;
+  const formatted = major.toLocaleString("en-US", {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  });
+  return `${formatted} ${currency}`;
+}
+
+function formatDate(date: Date | string | null | undefined): string {
+  if (!date) return "";
+  const d = typeof date === "string" ? new Date(date) : date;
+  return d.toISOString().slice(0, 10);
+}
+
+function sellerBlockHtml(branding: DocumentBranding): string {
+  const lines = [
+    branding.storeName && `<strong>${escapeHtml(branding.storeName)}</strong>`,
+    branding.address && escapeHtml(branding.address),
+    branding.phone && escapeHtml(branding.phone),
+    branding.email && escapeHtml(branding.email),
+    branding.taxId && `Tax ID: ${escapeHtml(branding.taxId)}`,
+  ].filter(Boolean);
+  return lines.join("<br>");
+}
+
+function lineRowsHtml(order: HydratedOrder): string {
+  return order.lineItems
+    .map(
+      (li) => `<tr>
+  <td>${escapeHtml(li.title)}${li.sku ? `<br><small>${escapeHtml(li.sku)}</small>` : ""}</td>
+  <td class="num">${li.quantity}</td>
+  <td class="num">${escapeHtml(formatAmount(li.unitPrice, order.currency))}</td>
+  <td class="num">${escapeHtml(formatAmount(li.totalPrice, order.currency))}</td>
+</tr>`,
+    )
+    .join("\n");
+}
+
+function totalsRowsHtml(order: HydratedOrder): string {
+  const rows: Array<[string, number]> = [
+    ["Subtotal", order.subtotal],
+    ...(order.discountTotal ? ([["Discount", -order.discountTotal]] as Array<[string, number]>) : []),
+    ["Tax", order.taxTotal],
+    ...(order.shippingTotal ? ([["Shipping", order.shippingTotal]] as Array<[string, number]>) : []),
+  ];
+  const body = rows
+    .map(([label, amount]) => `<tr><td>${label}</td><td class="num">${escapeHtml(formatAmount(amount, order.currency))}</td></tr>`)
+    .join("\n");
+  return `${body}\n<tr class="grand"><td>Total</td><td class="num">${escapeHtml(formatAmount(order.grandTotal, order.currency))}</td></tr>`;
+}
+
+const BASE_STYLE = `body{font-family:system-ui,-apple-system,sans-serif;color:#111;margin:2rem auto;line-height:1.45}
+table{width:100%;border-collapse:collapse;margin:1rem 0}
+th,td{text-align:left;padding:.4rem .5rem;border-bottom:1px solid #ddd}
+td.num,th.num{text-align:right}
+tr.grand td{font-weight:700;border-top:2px solid #111}
+small{color:#666}`;
+
+/** A4-style HTML invoice with seller branding and fiscal invoice number. */
+export function invoiceHtml(ctx: DocumentContext): string {
+  const { order, branding, invoiceNumber } = ctx;
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><title>Invoice ${escapeHtml(invoiceNumber)}</title>
+<style>${BASE_STYLE}
+body{max-width:48rem}</style></head>
+<body>
+<table style="border:none"><tr>
+  <td style="border:none">${sellerBlockHtml(branding)}</td>
+  <td style="border:none;text-align:right">
+    <h1 style="margin:0">INVOICE</h1>
+    <div>Invoice #: <strong>${escapeHtml(invoiceNumber)}</strong></div>
+    <div>Order #: ${escapeHtml(order.orderNumber)}</div>
+    <div>Date: ${escapeHtml(formatDate(order.placedAt))}</div>
+  </td>
+</tr></table>
+<table>
+  <thead><tr><th>Item</th><th class="num">Qty</th><th class="num">Unit</th><th class="num">Amount</th></tr></thead>
+  <tbody>${lineRowsHtml(order)}</tbody>
+</table>
+<table style="max-width:20rem;margin-left:auto"><tbody>${totalsRowsHtml(order)}</tbody></table>
+${branding.receiptFooter ? `<p><small>${escapeHtml(branding.receiptFooter)}</small></p>` : ""}
+</body></html>`;
+}
+
+/** Narrow receipt-style HTML with the configured header/footer. */
+export function receiptHtml(ctx: Omit<DocumentContext, "invoiceNumber"> & { invoiceNumber?: string }): string {
+  const { order, branding } = ctx;
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><title>Receipt ${escapeHtml(order.orderNumber)}</title>
+<style>${BASE_STYLE}
+body{max-width:22rem;font-size:.9rem}
+h2,p.center{text-align:center}</style></head>
+<body>
+${branding.storeName ? `<h2>${escapeHtml(branding.storeName)}</h2>` : ""}
+${branding.receiptHeader ? `<p class="center">${escapeHtml(branding.receiptHeader)}</p>` : ""}
+${branding.taxId ? `<p class="center"><small>Tax ID: ${escapeHtml(branding.taxId)}</small></p>` : ""}
+<p>Order #: ${escapeHtml(order.orderNumber)}<br>Date: ${escapeHtml(formatDate(order.placedAt))}</p>
+<table>
+  <tbody>${lineRowsHtml(order)}</tbody>
+</table>
+<table><tbody>${totalsRowsHtml(order)}</tbody></table>
+${branding.receiptFooter ? `<p class="center"><small>${escapeHtml(branding.receiptFooter)}</small></p>` : ""}
+</body></html>`;
+}
+
+// ── PDF layout ─────────────────────────────────────────────────────────────
+
+const MARGIN = 50;
+const LINE_HEIGHT = 16;
+const COL = {
+  item: MARGIN,
+  qty: 380,
+  unit: 440,
+  total: 515,
+};
+
+function truncate(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/**
+ * Lays an invoice out as pages of text ops for the minimal PDF writer.
+ */
+export function invoicePdfOps(ctx: DocumentContext): PdfTextOp[][] {
+  const { order, branding, invoiceNumber } = ctx;
+  const pages: PdfTextOp[][] = [];
+  let ops: PdfTextOp[] = [];
+  let y = A4.height - MARGIN;
+
+  const write = (text: string, x: number, opts?: { size?: number | undefined; bold?: boolean | undefined }) => {
+    ops.push({ x, y, size: opts?.size ?? 10, bold: opts?.bold, text });
+  };
+  const newline = (lines = 1) => {
+    y -= LINE_HEIGHT * lines;
+    if (y < MARGIN + LINE_HEIGHT) {
+      pages.push(ops);
+      ops = [];
+      y = A4.height - MARGIN;
+    }
+  };
+
+  write("INVOICE", MARGIN, { size: 20, bold: true });
+  newline(2);
+  write(`Invoice #: ${invoiceNumber}`, MARGIN, { bold: true });
+  newline();
+  write(`Order #: ${order.orderNumber}`, MARGIN);
+  newline();
+  write(`Date: ${formatDate(order.placedAt)}`, MARGIN);
+  newline(2);
+
+  const seller = [
+    branding.storeName,
+    branding.address,
+    branding.phone,
+    branding.email,
+    branding.taxId ? `Tax ID: ${branding.taxId}` : undefined,
+  ].filter((v): v is string => Boolean(v));
+  for (const [i, line] of seller.entries()) {
+    write(line, MARGIN, { bold: i === 0 });
+    newline();
+  }
+  newline();
+
+  write("Item", COL.item, { bold: true });
+  write("Qty", COL.qty, { bold: true });
+  write("Unit", COL.unit, { bold: true });
+  write("Amount", COL.total, { bold: true });
+  newline();
+
+  for (const li of order.lineItems) {
+    write(truncate(li.title, 52), COL.item);
+    write(String(li.quantity), COL.qty);
+    write(formatAmount(li.unitPrice, order.currency), COL.unit);
+    write(formatAmount(li.totalPrice, order.currency), COL.total);
+    newline();
+  }
+  newline();
+
+  const totals: Array<[string, number, boolean?]> = [
+    ["Subtotal", order.subtotal],
+    ...(order.discountTotal ? ([["Discount", -order.discountTotal]] as Array<[string, number]>) : []),
+    ["Tax", order.taxTotal],
+    ...(order.shippingTotal ? ([["Shipping", order.shippingTotal]] as Array<[string, number]>) : []),
+    ["Total", order.grandTotal, true],
+  ];
+  for (const [label, amount, bold] of totals) {
+    write(label, COL.qty, { bold });
+    write(formatAmount(amount, order.currency), COL.total, { bold });
+    newline();
+  }
+
+  if (branding.receiptFooter) {
+    newline();
+    write(branding.receiptFooter, MARGIN, { size: 8 });
+  }
+
+  pages.push(ops);
+  return pages;
+}