@porulle/plugin-loyalty 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @porulle/plugin-loyalty
+
+Points, tiers, leaderboard, and redemption offers tied to customers per organization.
+
+## Install
+
+```bash
+bun add @porulle/plugin-loyalty
+```
+
+Add to `commerce.config.ts`:
+
+```typescript
+import { loyaltyPlugin } from "@porulle/plugin-loyalty";
+
+export default defineConfig({
+  // ...
+  plugins: [loyaltyPlugin()],
+});
+```
+
+Add to `drizzle.config.ts`:
+
+```typescript
+schema: [
+  "./node_modules/@porulle/plugin-loyalty/src/schema.ts",
+  // ...
+],
+```
+
+## What it does
+
+Awards points from completed orders (`grandTotal`), maintains tiers from lifetime points, exposes redemption offers, and provides REST + MCP surfaces for balance and admin actions.
+
+## Routes exposed
+
+**`/loyalty`** — `GET /points/{customerId}`, `GET /leaderboard`, `POST /redeem`, `POST /offers`, `GET /offers`, `POST /offers/{id}/redeem` (permissions vary; some routes require `loyalty:admin` or auth).
+
+## Hooks
+
+**Emitted:** none.
+
+**Consumed:** **`orders.afterCreate`** — earns points from order total when `customerId` is present (`resolveOrgId` for tenant).
+
+## MCP tools
+
+**`loyalty`** — `balance`, `earn`, `redeem`, `leaderboard`, `list_offers`
+
+## Configuration options
+
+`LoyaltyPluginOptions`: `pointsPerDollar`, `tierThresholds` (`silver`, `gold`, `platinum` point thresholds).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { LoyaltyPluginOptions } from "./types.js";
+export type { LoyaltyPluginOptions, Db } from "./types.js";
+export { LoyaltyService } from "./services/loyalty-service.js";
+export declare function loyaltyPlugin(userOptions?: LoyaltyPluginOptions): 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":"AAKA,OAAO,KAAK,EAAM,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAG3D,YAAY,EAAE,oBAAoB,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,wBAAgB,aAAa,CAAC,WAAW,GAAE,oBAAyB,0CAsCnE"}

package/dist/index.js

@@ -0,0 +1,42 @@
+import { defineCommercePlugin, resolveOrgId } from "@porulle/core";
+import { loyaltyPoints, loyaltyTransactions, loyaltyRedemptionOffers } from "./schema.js";
+import { LoyaltyService } from "./services/loyalty-service.js";
+import { buildLoyaltyRoutes } from "./routes/loyalty.js";
+import { DEFAULT_LOYALTY_OPTIONS } from "./types.js";
+export { LoyaltyService } from "./services/loyalty-service.js";
+export function loyaltyPlugin(userOptions = {}) {
+    const options = { ...DEFAULT_LOYALTY_OPTIONS, ...userOptions };
+    return defineCommercePlugin({
+        id: "loyalty",
+        version: "1.0.0",
+        permissions: [
+            { scope: "loyalty:admin", description: "Create/manage redemption offers, view all loyalty data." },
+        ],
+        schema: () => ({ loyaltyPoints, loyaltyTransactions, loyaltyRedemptionOffers }),
+        hooks: () => [{
+                key: "orders.afterCreate",
+                async handler(args) {
+                    const { result, context } = args;
+                    if (!result.customerId)
+                        return;
+                    const rawDb = context.services.database?.db;
+                    if (!rawDb)
+                        return;
+                    const orgId = resolveOrgId(context.actor);
+                    const pointsEarned = Math.floor((result.grandTotal / 100) * options.pointsPerDollar);
+                    if (pointsEarned <= 0)
+                        return;
+                    const db = rawDb;
+                    const service = new LoyaltyService(db, options.tierThresholds);
+                    await service.earnPoints(orgId, result.customerId, pointsEarned, result.id);
+                    context.logger.info("loyalty_points_awarded", { customerId: result.customerId, orgId, pointsEarned });
+                },
+            }],
+        routes: (ctx) => {
+            const db = ctx.database.db;
+            if (!db)
+                return [];
+            return buildLoyaltyRoutes(new LoyaltyService(db, options.tierThresholds), ctx);
+        },
+    });
+}

package/dist/routes/loyalty.d.ts

@@ -0,0 +1,9 @@
+import type { LoyaltyService } from "../services/loyalty-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+export declare function buildLoyaltyRoutes(service: LoyaltyService, ctx: {
+    services?: Record<string, unknown>;
+    database?: {
+        db: unknown;
+    };
+}): PluginRouteRegistration[];
+//# sourceMappingURL=loyalty.d.ts.map

package/dist/routes/loyalty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loyalty.d.ts","sourceRoot":"","sources":["../../src/routes/loyalty.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GACtE,uBAAuB,EAAE,CA4D3B"}

package/dist/routes/loyalty.js

@@ -0,0 +1,62 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+export function buildLoyaltyRoutes(service, ctx) {
+    const r = router("Loyalty", "/loyalty", ctx);
+    r.get("/points/{customerId}").summary("Get loyalty points (admin)").permission("loyalty:admin")
+        .handler(async ({ params, orgId }) => {
+        const result = await service.getPoints(orgId, params.customerId);
+        if (!result.ok)
+            throw new Error("Failed");
+        if (!result.value)
+            return { customerId: params.customerId, points: 0, tier: "bronze", message: "No points yet" };
+        return result.value;
+    });
+    r.get("/leaderboard").summary("Loyalty leaderboard").auth()
+        .handler(async ({ orgId }) => {
+        const result = await service.getLeaderboard(orgId);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value.map((e, i) => ({ rank: i + 1, customerId: e.customerId, points: e.points, tier: e.tier }));
+    });
+    r.post("/redeem").summary("Redeem points (admin)").permission("loyalty:admin")
+        .input(z.object({ customerId: z.string().min(1), pointsToRedeem: z.number().int().min(1) }))
+        .handler(async ({ input, orgId }) => {
+        const body = input;
+        const result = await service.redeemPoints(orgId, body.customerId, body.pointsToRedeem);
+        if (!result.ok)
+            throw new Error(result.error);
+        return { remainingPoints: result.value.points, tier: result.value.tier };
+    });
+    // ─── Offers ────────────────────────────────────────────────────
+    r.post("/offers").summary("Create redemption offer").permission("loyalty:admin")
+        .input(z.object({
+        name: z.string().min(1), pointsRequired: z.number().int().positive(),
+        rewardType: z.enum(["discount_percentage", "discount_fixed", "free_item", "free_shipping"]),
+        rewardValue: z.number().int(), rewardEntityId: z.string().uuid().optional(),
+        validFrom: z.string().optional(), validUntil: z.string().optional(),
+        maxRedemptions: z.number().int().positive().optional(),
+    }))
+        .handler(async ({ input, orgId }) => {
+        const result = await service.createOffer(orgId, input);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    r.get("/offers").summary("List active offers").auth()
+        .handler(async ({ orgId }) => {
+        const result = await service.listOffers(orgId);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    r.post("/offers/{id}/redeem").summary("Redeem an offer (admin)").permission("loyalty:admin")
+        .input(z.object({ customerId: z.string().min(1) }))
+        .handler(async ({ params, input, orgId }) => {
+        const body = input;
+        const result = await service.redeemOffer(orgId, body.customerId, params.id);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    return r.routes();
+}