@porulle/core 0.7.0 → 0.8.0

package/src/modules/analytics/reports.ts

@@ -0,0 +1,311 @@
+import { sql, type SQL } from "drizzle-orm";
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
+
+/**
+ * Canned retail reports (issue #48).
+ *
+ * Parameterized SQL over core tables, org-scoped, with all calendar math done
+ * by Postgres in the store's timezone (settings.general.timezone, default
+ * UTC). Range reports include a prior period of equal length with deltas.
+ */
+
+export interface ReportParams {
+  /** Local calendar date (YYYY-MM-DD) for single-day reports. Default: today in store tz. */
+  date?: string;
+  /** Local range start (YYYY-MM-DD, inclusive). Default: first of current month in store tz. */
+  from?: string;
+  /** Local range end (YYYY-MM-DD, inclusive). Default: today in store tz. */
+  to?: string;
+}
+
+export const RETAIL_REPORTS = [
+  { name: "daily-journal", description: "Per-day sales journal: order rows + summary with prior-day deltas." },
+  { name: "tax-summary", description: "Tax collected over a range, bucketed per local day, with prior-period deltas." },
+  { name: "inventory-aging", description: "On-hand stock bucketed by days since last restock (0-30/31-60/61-90/90+)." },
+  { name: "sell-through", description: "Units sold in the range vs current on-hand, per entity." },
+  { name: "reorder-needed", description: "Inventory rows at or below their reorder threshold." },
+  { name: "staff-sales", description: "Orders and revenue grouped by orders.metadata.staffId." },
+] as const;
+
+export type RetailReportName = (typeof RETAIL_REPORTS)[number]["name"];
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// Orders excluded from financial reports.
+const EXCLUDED_STATUSES = ["cancelled", "voided"];
+
+type SettingsReader = (orgId: string, group: string) => Promise<Record<string, unknown>>;
+
+interface JournalSummary {
+  orderCount: number;
+  grossSales: number;
+  subtotal: number;
+  discounts: number;
+  tax: number;
+  shipping: number;
+}
+
+export class RetailReportsEngine {
+  constructor(
+    private readonly db: DrizzleDatabase,
+    private readonly readSettings: SettingsReader,
+  ) {}
+
+  async run(
+    name: string,
+    params: ReportParams,
+    orgId: string,
+  ): Promise<Result<Record<string, unknown>>> {
+    for (const value of [params.date, params.from, params.to]) {
+      if (value !== undefined && !DATE_RE.test(value)) {
+        return Err(new CommerceValidationError("Dates must be YYYY-MM-DD."));
+      }
+    }
+    const tz = await this.timezoneFor(orgId);
+
+    switch (name) {
+      case "daily-journal":
+        return Ok(await this.dailyJournal(orgId, tz, params.date ?? localToday(tz)));
+      case "tax-summary": {
+        const [from, to] = this.rangeOrDefault(params, tz);
+        return Ok(await this.taxSummary(orgId, tz, from, to));
+      }
+      case "inventory-aging":
+        return Ok(await this.inventoryAging(orgId));
+      case "sell-through": {
+        const [from, to] = this.rangeOrDefault(params, tz);
+        return Ok(await this.sellThrough(orgId, tz, from, to));
+      }
+      case "reorder-needed":
+        return Ok(await this.reorderNeeded(orgId));
+      case "staff-sales": {
+        const [from, to] = this.rangeOrDefault(params, tz);
+        return Ok(await this.staffSales(orgId, tz, from, to));
+      }
+      default:
+        return Err(
+          new CommerceValidationError(
+            `Unknown report "${name}". Available: ${RETAIL_REPORTS.map((r) => r.name).join(", ")}.`,
+          ),
+        );
+    }
+  }
+
+  private async timezoneFor(orgId: string): Promise<string> {
+    const general = await this.readSettings(orgId, "general");
+    return typeof general.timezone === "string" ? general.timezone : "UTC";
+  }
+
+  private rangeOrDefault(params: ReportParams, tz: string): [string, string] {
+    const today = localToday(tz);
+    return [params.from ?? `${today.slice(0, 8)}01`, params.to ?? today];
+  }
+
+  private async rows(query: SQL): Promise<Record<string, unknown>[]> {
+    const result = await this.db.execute(query);
+    const raw: Record<string, unknown>[] = Array.isArray(result)
+      ? result
+      : ((result as { rows?: Record<string, unknown>[] }).rows ?? []);
+    return raw.map((row) => {
+      const mapped: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(row)) {
+        mapped[key] = typeof value === "bigint" ? Number(value) : value;
+      }
+      return mapped;
+    });
+  }
+
+  private async journalSummary(
+    orgId: string,
+    tz: string,
+    from: string,
+    to: string,
+  ): Promise<JournalSummary> {
+    const rows = await this.rows(sql`
+      SELECT count(*)::int AS "orderCount",
+             COALESCE(sum(grand_total), 0)::int AS "grossSales",
+             COALESCE(sum(subtotal), 0)::int AS "subtotal",
+             COALESCE(sum(discount_total), 0)::int AS "discounts",
+             COALESCE(sum(tax_total), 0)::int AS "tax",
+             COALESCE(sum(shipping_total), 0)::int AS "shipping"
+      FROM orders
+      WHERE organization_id = ${orgId}
+        AND status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql`${s}`), sql`, `)})
+        AND (placed_at AT TIME ZONE ${tz})::date BETWEEN ${from}::date AND ${to}::date
+    `);
+    return rows[0] as unknown as JournalSummary;
+  }
+
+  private async dailyJournal(orgId: string, tz: string, date: string) {
+    const summary = await this.journalSummary(orgId, tz, date, date);
+    const previousDate = shiftDate(date, -1);
+    const previous = await this.journalSummary(orgId, tz, previousDate, previousDate);
+    const orders = await this.rows(sql`
+      SELECT order_number AS "orderNumber", status, currency,
+             grand_total AS "grandTotal", tax_total AS "tax",
+             discount_total AS "discounts", placed_at AS "placedAt"
+      FROM orders
+      WHERE organization_id = ${orgId}
+        AND status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql`${s}`), sql`, `)})
+        AND (placed_at AT TIME ZONE ${tz})::date = ${date}::date
+      ORDER BY placed_at ASC
+    `);
+    return {
+      report: "daily-journal",
+      timezone: tz,
+      date,
+      summary,
+      previous,
+      delta: deltas(summary, previous),
+      orders,
+    };
+  }
+
+  private async taxSummary(orgId: string, tz: string, from: string, to: string) {
+    const days = await this.rows(sql`
+      SELECT to_char((placed_at AT TIME ZONE ${tz})::date, 'YYYY-MM-DD') AS "day",
+             count(*)::int AS "orderCount",
+             COALESCE(sum(tax_total), 0)::int AS "tax",
+             COALESCE(sum(grand_total), 0)::int AS "gross"
+      FROM orders
+      WHERE organization_id = ${orgId}
+        AND status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql`${s}`), sql`, `)})
+        AND (placed_at AT TIME ZONE ${tz})::date BETWEEN ${from}::date AND ${to}::date
+      GROUP BY 1
+      ORDER BY 1
+    `);
+    const totals = await this.journalSummary(orgId, tz, from, to);
+    const lengthDays = daysBetween(from, to) + 1;
+    const prevFrom = shiftDate(from, -lengthDays);
+    const prevTo = shiftDate(to, -lengthDays);
+    const previous = await this.journalSummary(orgId, tz, prevFrom, prevTo);
+    return {
+      report: "tax-summary",
+      timezone: tz,
+      from,
+      to,
+      totals,
+      previous: { from: prevFrom, to: prevTo, ...previous },
+      delta: deltas(totals, previous),
+      days,
+    };
+  }
+
+  private async inventoryAging(orgId: string) {
+    const rows = await this.rows(sql`
+      SELECT il.entity_id AS "entityId", il.variant_id AS "variantId",
+             e.slug AS "slug",
+             il.quantity_on_hand AS "quantityOnHand",
+             il.quantity_reserved AS "quantityReserved",
+             GREATEST(0, EXTRACT(day FROM now() - COALESCE(il.last_restocked_at, il.updated_at)))::int AS "ageDays"
+      FROM inventory_levels il
+      LEFT JOIN sellable_entities e ON e.id = il.entity_id
+      WHERE il.organization_id = ${orgId} AND il.quantity_on_hand > 0
+      ORDER BY "ageDays" DESC
+    `);
+    const buckets = [
+      { bucket: "0-30", min: 0, max: 30 },
+      { bucket: "31-60", min: 31, max: 60 },
+      { bucket: "61-90", min: 61, max: 90 },
+      { bucket: "90+", min: 91, max: Infinity },
+    ].map(({ bucket, min, max }) => {
+      const inBucket = rows.filter((r) => (r.ageDays as number) >= min && (r.ageDays as number) <= max);
+      return {
+        bucket,
+        skuCount: inBucket.length,
+        quantityOnHand: inBucket.reduce((sum, r) => sum + (r.quantityOnHand as number), 0),
+      };
+    });
+    return { report: "inventory-aging", buckets, rows };
+  }
+
+  private async sellThrough(orgId: string, tz: string, from: string, to: string) {
+    const rows = await this.rows(sql`
+      SELECT li.entity_id AS "entityId",
+             min(li.title) AS "title",
+             sum(li.quantity)::int AS "unitsSold",
+             COALESCE((SELECT sum(quantity_on_hand)::int FROM inventory_levels il
+                       WHERE il.entity_id = li.entity_id AND il.organization_id = ${orgId}), 0) AS "onHand"
+      FROM order_line_items li
+      JOIN orders o ON o.id = li.order_id
+      WHERE o.organization_id = ${orgId}
+        AND o.status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql`${s}`), sql`, `)})
+        AND (o.placed_at AT TIME ZONE ${tz})::date BETWEEN ${from}::date AND ${to}::date
+      GROUP BY li.entity_id
+      ORDER BY "unitsSold" DESC
+    `);
+    return {
+      report: "sell-through",
+      timezone: tz,
+      from,
+      to,
+      rows: rows.map((r) => {
+        const sold = r.unitsSold as number;
+        const onHand = r.onHand as number;
+        return { ...r, sellThroughRate: sold + onHand > 0 ? sold / (sold + onHand) : 0 };
+      }),
+    };
+  }
+
+  private async reorderNeeded(orgId: string) {
+    const rows = await this.rows(sql`
+      SELECT il.entity_id AS "entityId", il.variant_id AS "variantId",
+             il.warehouse_id AS "warehouseId", e.slug AS "slug",
+             il.quantity_on_hand AS "quantityOnHand",
+             il.quantity_reserved AS "quantityReserved",
+             (il.quantity_on_hand - il.quantity_reserved) AS "available",
+             il.reorder_threshold AS "reorderThreshold",
+             il.reorder_quantity AS "reorderQuantity"
+      FROM inventory_levels il
+      LEFT JOIN sellable_entities e ON e.id = il.entity_id
+      WHERE il.organization_id = ${orgId}
+        AND il.reorder_threshold IS NOT NULL
+        AND (il.quantity_on_hand - il.quantity_reserved) <= il.reorder_threshold
+      ORDER BY "available" ASC
+    `);
+    return { report: "reorder-needed", rows };
+  }
+
+  private async staffSales(orgId: string, tz: string, from: string, to: string) {
+    const rows = await this.rows(sql`
+      SELECT COALESCE(metadata->>'staffId', 'unattributed') AS "staffId",
+             count(*)::int AS "orderCount",
+             COALESCE(sum(grand_total), 0)::int AS "revenue",
+             COALESCE(sum(discount_total), 0)::int AS "discounts"
+      FROM orders
+      WHERE organization_id = ${orgId}
+        AND status NOT IN (${sql.join(EXCLUDED_STATUSES.map((s) => sql`${s}`), sql`, `)})
+        AND (placed_at AT TIME ZONE ${tz})::date BETWEEN ${from}::date AND ${to}::date
+      GROUP BY 1
+      ORDER BY "revenue" DESC
+    `);
+    return { report: "staff-sales", timezone: tz, from, to, rows };
+  }
+}
+
+// ── Pure date helpers (calendar dates, no time component) ──────────────────
+
+/** Today's local calendar date (YYYY-MM-DD) in an IANA timezone. */
+export function localToday(tz: string): string {
+  return new Intl.DateTimeFormat("en-CA", { timeZone: tz }).format(new Date());
+}
+
+function shiftDate(date: string, days: number): string {
+  const d = new Date(`${date}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + days);
+  return d.toISOString().slice(0, 10);
+}
+
+function daysBetween(from: string, to: string): number {
+  const ms = new Date(`${to}T00:00:00Z`).getTime() - new Date(`${from}T00:00:00Z`).getTime();
+  return Math.round(ms / 86_400_000);
+}
+
+function deltas(current: JournalSummary, previous: JournalSummary): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const key of Object.keys(current) as Array<keyof JournalSummary>) {
+    out[key] = (current[key] ?? 0) - (previous[key] ?? 0);
+  }
+  return out;
+}

package/src/modules/analytics/service.ts

@@ -9,6 +9,10 @@
 import type { CommerceConfig } from "../../config/types.js";
 import { CommerceValidationError } from "../../kernel/errors.js";
 import { Err, Ok, type Result } from "../../kernel/result.js";
+import { resolveOrgId } from "../../auth/org.js";
+import type { Actor } from "../../auth/types.js";
+import type { ReportParams, RetailReportsEngine } from "./reports.js";
+import { RETAIL_REPORTS } from "./reports.js";
 import type {
   AnalyticsAdapter,
   AnalyticsMeta,
@@ -31,6 +35,7 @@ export type {
 export interface AnalyticsServiceDeps {
   adapter: AnalyticsAdapter;
   config: CommerceConfig;
+  reports?: RetailReportsEngine;
 }
 
 export class AnalyticsService {
@@ -116,6 +121,24 @@ export class AnalyticsService {
     );
   }
 
+  /** The canned retail reports pack (issue #48). */
+  listReports(): Array<{ name: string; description: string }> {
+    return RETAIL_REPORTS.map((r) => ({ name: r.name, description: r.description }));
+  }
+
+  /** Runs a canned retail report (issue #48), org-scoped to the actor. */
+  async getReport(
+    name: string,
+    params: ReportParams,
+    actor?: Actor | null,
+  ): Promise<Result<Record<string, unknown>>> {
+    if (!this.deps.reports) {
+      return Err(new CommerceValidationError("Retail reports are not available."));
+    }
+    const orgId = resolveOrgId(actor ?? null);
+    return this.deps.reports.run(name, params, orgId);
+  }
+
   async getMeta(): Promise<Result<AnalyticsMeta>> {
     await this.ensureCustomSchemaModelsLoaded();
 

package/src/modules/cart/repository/index.ts

@@ -1,10 +1,11 @@
-import { eq, and, lt } from "drizzle-orm";
+import { eq, and, lt, desc, isNull, isNotNull } from "drizzle-orm";
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 import type {
   DrizzleDatabase,
   DbOrTx,
 } from "../../../kernel/database/drizzle-db.js";
 import { carts, cartLineItems } from "../schema.js";
+import { customers } from "../../customers/schema.js";
 
 // Infer types from Drizzle schema
 export type Cart = typeof carts.$inferSelect;
@@ -64,6 +65,34 @@ export class CartRepository {
     return rows[0];
   }
 
+  async list(
+    orgId: string,
+    filter?: { status?: string; olderThan?: Date; hasCustomer?: boolean },
+    ctx?: TxContext,
+  ): Promise<Array<Cart & { customerEmail: string | null }>> {
+    const db = this.getDb(ctx);
+    const conditions = [eq(carts.organizationId, orgId)];
+    if (filter?.status) {
+      conditions.push(eq(carts.status, filter.status as Cart["status"]));
+    }
+    if (filter?.olderThan) {
+      conditions.push(lt(carts.updatedAt, filter.olderThan));
+    }
+    if (filter?.hasCustomer === true) {
+      conditions.push(isNotNull(carts.customerId));
+    }
+    if (filter?.hasCustomer === false) {
+      conditions.push(isNull(carts.customerId));
+    }
+    const rows = await db
+      .select({ cart: carts, customerEmail: customers.email })
+      .from(carts)
+      .leftJoin(customers, eq(carts.customerId, customers.id))
+      .where(and(...conditions))
+      .orderBy(desc(carts.updatedAt));
+    return rows.map((r) => ({ ...r.cart, customerEmail: r.customerEmail ?? null }));
+  }
+
   async findExpiredCarts(ctx?: TxContext): Promise<Cart[]> {
     const db = this.getDb(ctx);
     return db

package/src/modules/cart/schema.ts

@@ -12,6 +12,8 @@ export const carts = pgTable("carts", {
     .notNull()
     .default("active"),
   currency: text("currency").notNull().default("USD"),
+  // Shopper contact for guest carts — enables abandoned-checkout recovery
+  email: text("email"),
   secret: text("secret"),
   metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
   expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),

package/src/modules/cart/schemas.ts

@@ -5,6 +5,7 @@ import { z } from "@hono/zod-openapi";
 export const CreateCartBodySchema = z.object({
   customerId: z.string().optional().openapi({ example: "customer-uuid" }),
   currency: z.string().length(3).optional().openapi({ example: "USD" }),
+  email: z.email().optional().openapi({ example: "shopper@example.com" }),
 }).openapi("CreateCartRequest");
 
 export const AddCartItemBodySchema = z.object({

package/src/modules/cart/service.ts

@@ -18,6 +18,7 @@ import type {
 import type { HookRegistry } from "../../kernel/hooks/registry.js";
 import { Err, Ok, type Result } from "../../kernel/result.js";
 import { createLogger } from "../../utils/logger.js";
+import { paginate, type Pagination } from "../../utils/pagination.js";
 import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
 import type { PluginDb } from "../../kernel/database/plugin-types.js";
 import type { TxContext } from "../../kernel/database/tx-context.js";
@@ -152,6 +153,7 @@ export class CartService {
         metadata: input.metadata ?? {},
         expiresAt: new Date(now.getTime() + ttlMinutes * 60 * 1000),
         ...(resolvedCustomerId !== null ? { customerId: resolvedCustomerId } : {}),
+        ...(input.email !== undefined ? { email: input.email } : {}),
       },
       ctx,
     );
@@ -455,6 +457,105 @@ export class CartService {
     return Ok(undefined);
   }
 
+  /**
+   * Admin listing of carts with abandoned-checkout recovery filters:
+   * status, olderThan (not touched since), hasCustomer, plus pagination.
+   * Returns shopper identity (cart email + linked customer email).
+   */
+  async list(
+    filter?: {
+      status?: string;
+      olderThan?: Date;
+      hasCustomer?: boolean;
+      page?: number;
+      limit?: number;
+    },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ items: Array<Cart & { customerEmail: string | null }>; pagination: Pagination }>> {
+    try {
+      assertPermission(actor ?? null, "cart:manage");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const rows = await this.repo.list(
+      orgId,
+      {
+        ...(filter?.status !== undefined ? { status: filter.status } : {}),
+        ...(filter?.olderThan !== undefined ? { olderThan: filter.olderThan } : {}),
+        ...(filter?.hasCustomer !== undefined ? { hasCustomer: filter.hasCustomer } : {}),
+      },
+      ctx,
+    );
+    const paged = paginate(rows, filter?.page ?? 1, filter?.limit ?? 20);
+    return Ok({ items: paged.items, pagination: paged.pagination });
+  }
+
+  /**
+   * Abandoned-checkout recovery primitive: reactivates the cart, extends its
+   * expiry, and returns a resume secret that gates guest access to the cart —
+   * enough to build a recovery email with a resume/checkout link.
+   * Fires the `cart.afterRecover` hook so plugins/webhooks can react.
+   */
+  async recover(
+    cartId: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<
+    Result<{
+      cartId: string;
+      secret: string;
+      status: string;
+      expiresAt: string;
+      email: string | null;
+      customerId: string | null;
+    }>
+  > {
+    try {
+      assertPermission(actor ?? null, "cart:manage");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const cart = await this.repo.findById(orgId, cartId, ctx);
+    if (!cart) return Err(new CommerceNotFoundError("Cart not found."));
+    if (cart.status === "checked_out" || cart.status === "merged" || cart.status === "checking_out") {
+      return Err(
+        new CommerceValidationError(
+          `Cart with status "${cart.status}" cannot be recovered.`,
+        ),
+      );
+    }
+
+    const secret = cart.secret ?? crypto.randomUUID();
+    const ttlMinutes = this.deps.config.cart?.ttlMinutes ?? 60 * 24 * 7;
+    const expiresAt = new Date(Date.now() + ttlMinutes * 60 * 1000);
+    const updated = await this.repo.update(
+      cart.id,
+      { status: "active", secret, expiresAt },
+      ctx,
+    );
+
+    const afterHooks = this.deps.hooks.resolve("cart.afterRecover") as AfterHook<Cart>[];
+    await runAfterHooks(
+      afterHooks,
+      null,
+      updated ?? cart,
+      "recover",
+      makeContext(actor ?? null, this.deps.services, this.deps.database, ctx?.tx ?? null),
+    );
+
+    return Ok({
+      cartId: cart.id,
+      secret,
+      status: "active",
+      expiresAt: expiresAt.toISOString(),
+      email: cart.email ?? null,
+      customerId: cart.customerId ?? null,
+    });
+  }
+
   async abandon(cartId: string, actor?: Actor | null, ctx?: TxContext): Promise<Result<void>> {
     const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
     const cart = await this.repo.findById(orgId, cartId, ctx);