@porulle/plugin-layaway 0.8.0

package/dist/schema.js

@@ -0,0 +1,45 @@
+/**
+ * Layaway plugin schema (issue #58).
+ *
+ * - layaways: a partial-payment plan reserving items until fully paid.
+ *   `status` is stored but always derived from payments: active →
+ *   completed (paidTotal >= total, creates the core order + releases the
+ *   reservation hold) or forfeited/cancelled (releases the hold).
+ * - layaway_payments: installment ledger (any tender).
+ */
+import { pgTable, uuid, text, integer, timestamp, jsonb, index } from "@porulle/core/drizzle";
+export const layaways = pgTable("layaways", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    customerId: uuid("customer_id"),
+    status: text("status", { enum: ["active", "completed", "forfeited", "cancelled"] }).notNull().default("active"),
+    currency: text("currency").notNull(),
+    items: jsonb("items").$type().notNull(),
+    total: integer("total").notNull(),
+    depositAmount: integer("deposit_amount").notNull().default(0),
+    paidTotal: integer("paid_total").notNull().default(0),
+    // Core order created at completion.
+    orderId: uuid("order_id"),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    forfeitedAt: timestamp("forfeited_at", { withTimezone: true }),
+    forfeitReason: text("forfeit_reason"),
+    createdBy: text("created_by").notNull(),
+    metadata: jsonb("metadata").$type().default({}),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_layaways_org").on(table.organizationId),
+    statusIdx: index("idx_layaways_status").on(table.status),
+    customerIdx: index("idx_layaways_customer").on(table.customerId),
+}));
+export const layawayPayments = pgTable("layaway_payments", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    layawayId: uuid("layaway_id").references(() => layaways.id, { onDelete: "cascade" }).notNull(),
+    amount: integer("amount").notNull(),
+    method: text("method").notNull(),
+    reference: text("reference"),
+    performedBy: text("performed_by").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    layawayIdx: index("idx_layaway_payments_layaway").on(table.layawayId),
+}));

package/dist/service.d.ts

@@ -0,0 +1,69 @@
+import type { PluginDb, PluginResult } from "@porulle/core";
+import { layaways, layawayPayments, type LayawayItem } from "./schema.js";
+export type Layaway = typeof layaways.$inferSelect;
+export type LayawayPayment = typeof layawayPayments.$inferSelect;
+export interface LayawayPluginOptions {
+    /** Default deposit percentage when neither depositAmount nor depositPercent is given. Default: 20. */
+    defaultDepositPercent?: number;
+    /**
+     * Forfeit policy hook — runs after a layaway is forfeited (deposit
+     * retention, customer notification, etc.). Errors are surfaced to the
+     * caller.
+     */
+    onForfeit?: (layaway: Layaway) => Promise<void> | void;
+}
+/**
+ * Layaway plans (issue #58): reserve items with a deposit, pay in
+ * installments, complete to a core order automatically at full payment.
+ */
+export declare class LayawayService {
+    private db;
+    private services;
+    private options;
+    constructor(db: PluginDb, services: Record<string, unknown>, options?: LayawayPluginOptions);
+    private get core();
+    create(orgId: string, input: {
+        currency: string;
+        items: LayawayItem[];
+        customerId?: string | undefined;
+        depositAmount?: number | undefined;
+        depositPercent?: number | undefined;
+        expiresAt?: string | undefined;
+        initialPayment?: {
+            amount: number;
+            method: string;
+            reference?: string | undefined;
+        } | undefined;
+    }, actor: {
+        userId: string;
+    } & Record<string, unknown>): Promise<PluginResult<{
+        layaway: Layaway;
+        payments: LayawayPayment[];
+    }>>;
+    private releaseItems;
+    getById(orgId: string, id: string): Promise<PluginResult<Layaway & {
+        payments: LayawayPayment[];
+    }>>;
+    list(orgId: string, status?: string): Promise<PluginResult<Layaway[]>>;
+    /**
+     * Records an installment. When cumulative payments reach the plan total,
+     * the plan completes automatically: a core order is created (cross-linked)
+     * and the inventory hold is released to the normal order flow.
+     */
+    addPayment(orgId: string, layawayId: string, input: {
+        amount: number;
+        method: string;
+        reference?: string | undefined;
+    }, actor: {
+        userId: string;
+    } & Record<string, unknown>): Promise<PluginResult<{
+        layaway: Layaway;
+        payment: LayawayPayment;
+        completed: boolean;
+    }>>;
+    /** Forfeits an active plan: releases stock and runs the forfeit policy hook. */
+    forfeit(orgId: string, layawayId: string, reason: string | undefined, actor: {
+        userId: string;
+    } & Record<string, unknown>): Promise<PluginResult<Layaway>>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/dist/service.js

@@ -0,0 +1,204 @@
+import { eq, and } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import { layaways, layawayPayments } from "./schema.js";
+/**
+ * Layaway plans (issue #58): reserve items with a deposit, pay in
+ * installments, complete to a core order automatically at full payment.
+ */
+export class LayawayService {
+    db;
+    services;
+    options;
+    constructor(db, services, options = {}) {
+        this.db = db;
+        this.services = services;
+        this.options = options;
+    }
+    get core() {
+        return this.services;
+    }
+    async create(orgId, input, actor) {
+        if (input.items.length === 0)
+            return Err("At least one item is required");
+        for (const item of input.items) {
+            if (!Number.isInteger(item.quantity) || item.quantity < 1)
+                return Err("Item quantity must be a positive integer");
+            if (item.unitPrice < 0)
+                return Err("Item unitPrice must be non-negative");
+        }
+        const total = input.items.reduce((sum, i) => sum + i.unitPrice * i.quantity, 0);
+        const depositPercent = input.depositPercent ?? this.options.defaultDepositPercent ?? 20;
+        const depositAmount = input.depositAmount ?? Math.round((total * depositPercent) / 100);
+        if (depositAmount > total)
+            return Err("Deposit cannot exceed the plan total");
+        const rows = await this.db
+            .insert(layaways)
+            .values({
+            organizationId: orgId,
+            customerId: input.customerId ?? null,
+            currency: input.currency,
+            items: input.items,
+            total,
+            depositAmount,
+            createdBy: actor.userId,
+            ...(input.expiresAt ? { expiresAt: new Date(input.expiresAt) } : {}),
+        })
+            .returning();
+        let layaway = rows[0];
+        // Reserve stock while the plan is active (released on completion/forfeit).
+        for (const item of input.items) {
+            const reserved = await this.core.inventory.reserve({
+                entityId: item.entityId,
+                ...(item.variantId ? { variantId: item.variantId } : {}),
+                quantity: item.quantity,
+                orderId: layaway.id,
+                performedBy: actor.userId,
+            }, actor);
+            if (!reserved.ok) {
+                // Roll back: release what was reserved so far and drop the plan.
+                await this.releaseItems(layaway, actor, item);
+                await this.db.delete(layaways).where(eq(layaways.id, layaway.id));
+                return Err(reserved.error?.message ?? `Could not reserve ${item.title}`);
+            }
+        }
+        const payments = [];
+        if (input.initialPayment) {
+            const paid = await this.addPayment(orgId, layaway.id, input.initialPayment, actor);
+            if (!paid.ok)
+                return Err(paid.error);
+            layaway = paid.value.layaway;
+            payments.push(paid.value.payment);
+        }
+        return Ok({ layaway, payments });
+    }
+    async releaseItems(layaway, actor, upTo) {
+        for (const item of layaway.items) {
+            if (upTo && item === upTo)
+                break;
+            await this.core.inventory.release({
+                entityId: item.entityId,
+                ...(item.variantId ? { variantId: item.variantId } : {}),
+                quantity: item.quantity,
+                orderId: layaway.id,
+                performedBy: actor.userId,
+            }, actor);
+        }
+    }
+    async getById(orgId, id) {
+        const rows = await this.db
+            .select()
+            .from(layaways)
+            .where(and(eq(layaways.id, id), eq(layaways.organizationId, orgId)));
+        const layaway = rows[0];
+        if (!layaway)
+            return Err("Layaway not found");
+        const payments = (await this.db
+            .select()
+            .from(layawayPayments)
+            .where(eq(layawayPayments.layawayId, id)));
+        return Ok({ ...layaway, payments });
+    }
+    async list(orgId, status) {
+        const conditions = [eq(layaways.organizationId, orgId)];
+        if (status)
+            conditions.push(eq(layaways.status, status));
+        const rows = await this.db.select().from(layaways).where(and(...conditions));
+        return Ok(rows);
+    }
+    /**
+     * Records an installment. When cumulative payments reach the plan total,
+     * the plan completes automatically: a core order is created (cross-linked)
+     * and the inventory hold is released to the normal order flow.
+     */
+    async addPayment(orgId, layawayId, input, actor) {
+        if (input.amount <= 0)
+            return Err("Payment amount must be positive");
+        const found = await this.getById(orgId, layawayId);
+        if (!found.ok)
+            return found;
+        const layaway = found.value;
+        if (layaway.status !== "active")
+            return Err(`Layaway is ${layaway.status}`);
+        const remaining = layaway.total - layaway.paidTotal;
+        if (input.amount > remaining) {
+            return Err(`Payment exceeds the remaining balance (${remaining})`);
+        }
+        const paymentRows = await this.db
+            .insert(layawayPayments)
+            .values({
+            layawayId,
+            amount: input.amount,
+            method: input.method,
+            reference: input.reference ?? null,
+            performedBy: actor.userId,
+        })
+            .returning();
+        const payment = paymentRows[0];
+        const paidTotal = layaway.paidTotal + input.amount;
+        let completed = false;
+        let orderId = null;
+        if (paidTotal >= layaway.total) {
+            // Full payment → create the core order and release the hold.
+            const order = await this.core.orders.create({
+                currency: layaway.currency,
+                subtotal: layaway.total,
+                taxTotal: 0,
+                shippingTotal: 0,
+                grandTotal: layaway.total,
+                ...(layaway.customerId ? { customerId: layaway.customerId } : {}),
+                metadata: { layawayId: layaway.id, source: "layaway" },
+                lineItems: layaway.items.map((item) => ({
+                    entityId: item.entityId,
+                    entityType: "product",
+                    ...(item.variantId ? { variantId: item.variantId } : {}),
+                    ...(item.sku ? { sku: item.sku } : {}),
+                    title: item.title,
+                    quantity: item.quantity,
+                    unitPrice: item.unitPrice,
+                    totalPrice: item.unitPrice * item.quantity,
+                })),
+            }, actor);
+            if (!order.ok || !order.value) {
+                return Err(order.error?.message ?? "Layaway completion failed to create the order");
+            }
+            orderId = order.value.id;
+            await this.releaseItems({ ...layaway, items: layaway.items }, actor);
+            completed = true;
+        }
+        const updated = await this.db
+            .update(layaways)
+            .set({
+            paidTotal,
+            ...(completed ? { status: "completed", orderId } : {}),
+            updatedAt: new Date(),
+        })
+            .where(eq(layaways.id, layawayId))
+            .returning();
+        return Ok({ layaway: updated[0], payment, completed });
+    }
+    /** Forfeits an active plan: releases stock and runs the forfeit policy hook. */
+    async forfeit(orgId, layawayId, reason, actor) {
+        const found = await this.getById(orgId, layawayId);
+        if (!found.ok)
+            return found;
+        const layaway = found.value;
+        if (layaway.status !== "active")
+            return Err(`Layaway is ${layaway.status}`);
+        await this.releaseItems(layaway, actor);
+        const rows = await this.db
+            .update(layaways)
+            .set({
+            status: "forfeited",
+            forfeitedAt: new Date(),
+            forfeitReason: reason ?? null,
+            updatedAt: new Date(),
+        })
+            .where(eq(layaways.id, layawayId))
+            .returning();
+        const forfeited = rows[0];
+        if (this.options.onForfeit) {
+            await this.options.onForfeit(forfeited);
+        }
+        return Ok(forfeited);
+    }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@porulle/plugin-layaway",
+  "version": "0.8.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    },
+    "./schema": {
+      "bun": "./src/schema.ts",
+      "import": "./dist/schema.js",
+      "require": "./dist/schema.js",
+      "types": "./src/schema.ts"
+    }
+  },
+  "dependencies": {
+    "@hono/zod-openapi": "^1.2.2",
+    "hono": "^4.12.5",
+    "@porulle/core": "0.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4",
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "description": "Layaway / partial-payment plans: reserve items with a deposit, pay in installments (any tender), derived status, automatic completion to a core order with stock release, forfeit policy.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/plugins/plugin-layaway"
+  },
+  "author": "Porulle contributors",
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,129 @@
+import { defineCommercePlugin, router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { PluginRouteRegistration } from "@porulle/core";
+import { layaways, layawayPayments } from "./schema.js";
+import { LayawayService, type LayawayPluginOptions } from "./service.js";
+
+export type { LayawayPluginOptions, Layaway, LayawayPayment } from "./service.js";
+export { LayawayService } from "./service.js";
+export type { LayawayItem } from "./schema.js";
+
+const ItemSchema = z.object({
+  entityId: z.string().uuid(),
+  variantId: z.string().uuid().optional(),
+  sku: z.string().optional(),
+  title: z.string().min(1),
+  quantity: z.number().int().positive(),
+  unitPrice: z.number().int().min(0),
+});
+
+/**
+ * Layaway plugin (issue #58): partial-payment plans — reserve items with a
+ * deposit, record installments (any tender), derived status, automatic
+ * completion to a core order (with the stock hold released) at full payment,
+ * and a forfeit policy hook.
+ *
+ * The actor needs `layaway:operate` for day-to-day flows and core
+ * `orders:create` (completion creates the order).
+ */
+export function layawayPlugin(options: LayawayPluginOptions = {}) {
+  return defineCommercePlugin({
+    id: "layaway",
+    version: "1.0.0",
+
+    permissions: [
+      { scope: "layaway:operate", description: "Create layaway plans, record installment payments." },
+      { scope: "layaway:manage", description: "Forfeit or cancel layaway plans." },
+    ],
+
+    schema: () => ({ layaways, layawayPayments }),
+
+    routes: (ctx) => {
+      const db = ctx.database.db;
+      if (!db) return [];
+      const service = new LayawayService(db, ctx.services, options);
+      const r = router("Layaways", "/layaways", ctx);
+
+      r.post("/")
+        .summary("Create a layaway plan (reserves stock; optional initial deposit payment)")
+        .permission("layaway:operate")
+        .input(z.object({
+          currency: z.string().length(3),
+          customerId: z.string().uuid().optional(),
+          items: z.array(ItemSchema).min(1),
+          depositAmount: z.number().int().min(0).optional(),
+          depositPercent: z.number().min(0).max(100).optional(),
+          expiresAt: z.string().datetime().optional(),
+          initialPayment: z.object({
+            amount: z.number().int().positive(),
+            method: z.string().min(1),
+            reference: z.string().optional(),
+          }).optional(),
+        }))
+        .handler(async ({ input, actor, orgId }) => {
+          const result = await service.create(
+            orgId,
+            input as Parameters<LayawayService["create"]>[1],
+            actor as { userId: string } & Record<string, unknown>,
+          );
+          if (!result.ok) throw new Error(result.error);
+          return result.value;
+        });
+
+      r.get("/")
+        .summary("List layaway plans")
+        .permission("layaway:operate")
+        .query(z.object({ status: z.string().optional() }))
+        .handler(async ({ query, orgId }) => {
+          const result = await service.list(orgId, (query as { status?: string }).status);
+          if (!result.ok) throw new Error(result.error);
+          return result.value;
+        });
+
+      r.get("/{id}")
+        .summary("Get a layaway plan with its payment ledger")
+        .permission("layaway:operate")
+        .handler(async ({ params, orgId }) => {
+          const result = await service.getById(orgId, params.id!);
+          if (!result.ok) throw new Error(result.error);
+          return result.value;
+        });
+
+      r.post("/{id}/payments")
+        .summary("Record an installment (completes the plan at full payment)")
+        .permission("layaway:operate")
+        .input(z.object({
+          amount: z.number().int().positive(),
+          method: z.string().min(1),
+          reference: z.string().optional(),
+        }))
+        .handler(async ({ params, input, actor, orgId }) => {
+          const result = await service.addPayment(
+            orgId,
+            params.id!,
+            input as { amount: number; method: string; reference?: string },
+            actor as { userId: string } & Record<string, unknown>,
+          );
+          if (!result.ok) throw new Error(result.error);
+          return result.value;
+        });
+
+      r.post("/{id}/forfeit")
+        .summary("Forfeit an active plan (releases stock, runs the forfeit policy)")
+        .permission("layaway:manage")
+        .input(z.object({ reason: z.string().max(500).optional() }))
+        .handler(async ({ params, input, actor, orgId }) => {
+          const result = await service.forfeit(
+            orgId,
+            params.id!,
+            (input as { reason?: string }).reason,
+            actor as { userId: string } & Record<string, unknown>,
+          );
+          if (!result.ok) throw new Error(result.error);
+          return result.value;
+        });
+
+      return r.routes() as PluginRouteRegistration[];
+    },
+  });
+}

package/src/schema.ts

@@ -0,0 +1,57 @@
+/**
+ * Layaway plugin schema (issue #58).
+ *
+ * - layaways: a partial-payment plan reserving items until fully paid.
+ *   `status` is stored but always derived from payments: active →
+ *   completed (paidTotal >= total, creates the core order + releases the
+ *   reservation hold) or forfeited/cancelled (releases the hold).
+ * - layaway_payments: installment ledger (any tender).
+ */
+
+import { pgTable, uuid, text, integer, timestamp, jsonb, index } from "@porulle/core/drizzle";
+
+export interface LayawayItem {
+  entityId: string;
+  variantId?: string | undefined;
+  sku?: string | undefined;
+  title: string;
+  quantity: number;
+  unitPrice: number;
+}
+
+export const layaways = pgTable("layaways", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  customerId: uuid("customer_id"),
+  status: text("status", { enum: ["active", "completed", "forfeited", "cancelled"] }).notNull().default("active"),
+  currency: text("currency").notNull(),
+  items: jsonb("items").$type<LayawayItem[]>().notNull(),
+  total: integer("total").notNull(),
+  depositAmount: integer("deposit_amount").notNull().default(0),
+  paidTotal: integer("paid_total").notNull().default(0),
+  // Core order created at completion.
+  orderId: uuid("order_id"),
+  expiresAt: timestamp("expires_at", { withTimezone: true }),
+  forfeitedAt: timestamp("forfeited_at", { withTimezone: true }),
+  forfeitReason: text("forfeit_reason"),
+  createdBy: text("created_by").notNull(),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_layaways_org").on(table.organizationId),
+  statusIdx: index("idx_layaways_status").on(table.status),
+  customerIdx: index("idx_layaways_customer").on(table.customerId),
+}));
+
+export const layawayPayments = pgTable("layaway_payments", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  layawayId: uuid("layaway_id").references(() => layaways.id, { onDelete: "cascade" }).notNull(),
+  amount: integer("amount").notNull(),
+  method: text("method").notNull(),
+  reference: text("reference"),
+  performedBy: text("performed_by").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  layawayIdx: index("idx_layaway_payments_layaway").on(table.layawayId),
+}));