@porulle/plugin-layaway 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unified-commerce-engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @porulle/plugin-layaway
+
+Layaway / partial-payment plans for `@porulle/core`: reserve items with a
+deposit, pay the balance in installments, and complete the sale automatically
+when it is paid off.
+
+## Install
+
+```bash
+bun add @porulle/plugin-layaway
+```
+
+Add to `commerce.config.ts`:
+
+```typescript
+import { layawayPlugin } from "@porulle/plugin-layaway";
+
+export default defineConfig({
+  plugins: [
+    layawayPlugin({
+      defaultDepositPercent: 25, // used when a plan gives no deposit (default 20)
+      onForfeit: async (layaway) => {
+        // Policy hook — deposit retention, customer notification, etc.
+      },
+    }),
+  ],
+});
+```
+
+Add to `drizzle.config.ts`:
+
+```typescript
+schema: [
+  "./node_modules/@porulle/plugin-layaway/src/schema.ts",
+  // ...
+],
+```
+
+## What it does
+
+Registers the `layaways` and `layaway_payments` tables. On create it reserves
+stock for the plan's items (rolled back if the reservation fails). Installments
+are recorded in any tender; when the cumulative paid amount reaches the total
+the plan auto-completes — a core order is created and cross-linked via
+`metadata.layawayId`, and the stock hold is released. Forfeiting releases the
+hold and runs the `onForfeit` policy hook (the plugin does not itself retain or
+refund the deposit — that is your policy).
+
+## Routes exposed
+
+- **`POST /layaways`** — create a plan (`layaway:operate`)
+- **`GET /layaways`** — list plans, optional `?status` (`layaway:operate`)
+- **`GET /layaways/{id}`** — plan with its payment ledger (`layaway:operate`)
+- **`POST /layaways/{id}/payments`** — record an installment; auto-completes at
+  full payment (`layaway:operate` + core `orders:create`)
+- **`POST /layaways/{id}/forfeit`** — forfeit a plan, release stock (`layaway:manage`)
+
+See the [Layaway guide](https://github.com/asyncdotengineering/porulle/blob/main/apps/docs/src/content/docs/building/layaway.mdx)
+for worked examples.

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { type LayawayPluginOptions } from "./service.js";
+export type { LayawayPluginOptions, Layaway, LayawayPayment } from "./service.js";
+export { LayawayService } from "./service.js";
+export type { LayawayItem } from "./schema.js";
+/**
+ * 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 declare function layawayPlugin(options?: LayawayPluginOptions): import("@porulle/core").CommercePlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzE,YAAY,EAAE,oBAAoB,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW/C;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,0CAoG/D"}

package/dist/index.js

@@ -0,0 +1,106 @@
+import { defineCommercePlugin, router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import { layaways, layawayPayments } from "./schema.js";
+import { LayawayService } from "./service.js";
+export { LayawayService } from "./service.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 = {}) {
+    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, actor);
+                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.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, actor);
+                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.reason, actor);
+                if (!result.ok)
+                    throw new Error(result.error);
+                return result.value;
+            });
+            return r.routes();
+        },
+    });
+}

package/dist/schema.d.ts

@@ -0,0 +1,444 @@
+/**
+ * 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).
+ */
+export interface LayawayItem {
+    entityId: string;
+    variantId?: string | undefined;
+    sku?: string | undefined;
+    title: string;
+    quantity: number;
+    unitPrice: number;
+}
+export declare const layaways: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
+    name: "layaways";
+    schema: undefined;
+    columns: {
+        id: import("@porulle/core/drizzle").PgColumn<{
+            name: "id";
+            tableName: "layaways";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        organizationId: import("@porulle/core/drizzle").PgColumn<{
+            name: "organization_id";
+            tableName: "layaways";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        customerId: import("@porulle/core/drizzle").PgColumn<{
+            name: "customer_id";
+            tableName: "layaways";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("@porulle/core/drizzle").PgColumn<{
+            name: "status";
+            tableName: "layaways";
+            dataType: "string";
+            columnType: "PgText";
+            data: "active" | "completed" | "forfeited" | "cancelled";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["active", "completed", "forfeited", "cancelled"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        currency: import("@porulle/core/drizzle").PgColumn<{
+            name: "currency";
+            tableName: "layaways";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        items: import("@porulle/core/drizzle").PgColumn<{
+            name: "items";
+            tableName: "layaways";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: LayawayItem[];
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: LayawayItem[];
+        }>;
+        total: import("@porulle/core/drizzle").PgColumn<{
+            name: "total";
+            tableName: "layaways";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        depositAmount: import("@porulle/core/drizzle").PgColumn<{
+            name: "deposit_amount";
+            tableName: "layaways";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        paidTotal: import("@porulle/core/drizzle").PgColumn<{
+            name: "paid_total";
+            tableName: "layaways";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        orderId: import("@porulle/core/drizzle").PgColumn<{
+            name: "order_id";
+            tableName: "layaways";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        expiresAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "expires_at";
+            tableName: "layaways";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        forfeitedAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "forfeited_at";
+            tableName: "layaways";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        forfeitReason: import("@porulle/core/drizzle").PgColumn<{
+            name: "forfeit_reason";
+            tableName: "layaways";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdBy: import("@porulle/core/drizzle").PgColumn<{
+            name: "created_by";
+            tableName: "layaways";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        metadata: import("@porulle/core/drizzle").PgColumn<{
+            name: "metadata";
+            tableName: "layaways";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        createdAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "created_at";
+            tableName: "layaways";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "updated_at";
+            tableName: "layaways";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+export declare const layawayPayments: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
+    name: "layaway_payments";
+    schema: undefined;
+    columns: {
+        id: import("@porulle/core/drizzle").PgColumn<{
+            name: "id";
+            tableName: "layaway_payments";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        layawayId: import("@porulle/core/drizzle").PgColumn<{
+            name: "layaway_id";
+            tableName: "layaway_payments";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        amount: import("@porulle/core/drizzle").PgColumn<{
+            name: "amount";
+            tableName: "layaway_payments";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        method: import("@porulle/core/drizzle").PgColumn<{
+            name: "method";
+            tableName: "layaway_payments";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        reference: import("@porulle/core/drizzle").PgColumn<{
+            name: "reference";
+            tableName: "layaway_payments";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        performedBy: import("@porulle/core/drizzle").PgColumn<{
+            name: "performed_by";
+            tableName: "layaway_payments";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "created_at";
+            tableName: "layaway_payments";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBlB,CAAC;AAEJ,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUzB,CAAC"}