@unifiedcommerce/plugin-loyalty 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+import type { loyaltyPoints, loyaltyTransactions, loyaltyRedemptionOffers } from "./schema";
+export type { PluginDb as Db } from "@unifiedcommerce/core";
+export type LoyaltyPoints = typeof loyaltyPoints.$inferSelect;
+export type LoyaltyTransaction = typeof loyaltyTransactions.$inferSelect;
+export type LoyaltyOffer = typeof loyaltyRedemptionOffers.$inferSelect;
+export type Tier = "bronze" | "silver" | "gold" | "platinum";
+export interface LoyaltyPluginOptions {
+    pointsPerDollar?: number;
+    tierThresholds?: {
+        silver: number;
+        gold: number;
+        platinum: number;
+    };
+}
+export declare const DEFAULT_LOYALTY_OPTIONS: Required<LoyaltyPluginOptions>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAE5F,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,uBAAuB,CAAC;AAC5D,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,YAAY,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,OAAO,mBAAmB,CAAC,YAAY,CAAC;AACzE,MAAM,MAAM,YAAY,GAAG,OAAO,uBAAuB,CAAC,YAAY,CAAC;AACvE,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,oBAAoB;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAED,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,oBAAoB,CAGlE,CAAC"}

package/dist/types.js

@@ -0,0 +1,4 @@
+export const DEFAULT_LOYALTY_OPTIONS = {
+    pointsPerDollar: 1,
+    tierThresholds: { silver: 500, gold: 1500, platinum: 3000 },
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@unifiedcommerce/plugin-loyalty",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/zod-openapi": "^1.2.2",
+    "@unifiedcommerce/core": "*",
+    "drizzle-orm": "^0.45.1",
+    "hono": "^4.12.5"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+import { defineCommercePlugin, resolveOrgId } from "@unifiedcommerce/core";
+import { eq, and, sql } from "drizzle-orm";
+import { loyaltyPoints, loyaltyTransactions, loyaltyRedemptionOffers } from "./schema";
+import { LoyaltyService } from "./services/loyalty-service";
+import { buildLoyaltyRoutes } from "./routes/loyalty";
+import type { Db, LoyaltyPluginOptions } from "./types";
+import { DEFAULT_LOYALTY_OPTIONS } from "./types";
+
+export type { LoyaltyPluginOptions, Db } from "./types";
+export { LoyaltyService } from "./services/loyalty-service";
+
+export function loyaltyPlugin(userOptions: LoyaltyPluginOptions = {}) {
+  const options: Required<LoyaltyPluginOptions> = { ...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: unknown) {
+        const { result, context } = args as {
+          result: { id: string; customerId?: string; grandTotal: number };
+          context: { actor?: { organizationId?: string | null } | null; logger: { info(msg: string, data?: unknown): void }; services: { database?: { db: unknown } } };
+        };
+        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 as unknown as Db;
+        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 as unknown as Db;
+      if (!db) return [];
+      return buildLoyaltyRoutes(new LoyaltyService(db, options.tierThresholds), ctx);
+    },
+  });
+}

package/src/routes/loyalty.ts

@@ -0,0 +1,69 @@
+import { router } from "@unifiedcommerce/core";
+import { z } from "@hono/zod-openapi";
+import type { LoyaltyService } from "../services/loyalty-service";
+import type { PluginRouteRegistration } from "@unifiedcommerce/core";
+
+export function buildLoyaltyRoutes(
+  service: LoyaltyService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  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: { customerId: string; points: number; tier: string }, i: number) => ({ 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 as { customerId: string; pointsToRedeem: number };
+      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 as Parameters<typeof service.createOffer>[1]);
+      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 as { customerId: string };
+      const result = await service.redeemOffer(orgId, body.customerId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/schema.ts

@@ -0,0 +1,54 @@
+import { index, integer, boolean, pgTable, text, timestamp, uniqueIndex, uuid } from "drizzle-orm/pg-core";
+import { customers } from "@unifiedcommerce/core/schema";
+import { organization } from "@unifiedcommerce/core/auth-schema";
+
+export const loyaltyPoints = pgTable("loyalty_points", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull().references(() => organization.id, { onDelete: "cascade" }),
+  customerId: uuid("customer_id")
+    .notNull()
+    .references(() => customers.id, { onDelete: "cascade" }),
+  points: integer("points").notNull().default(0),
+  tier: text("tier", { enum: ["bronze", "silver", "gold", "platinum"] }).notNull().default("bronze"),
+  lifetimeSpend: integer("lifetime_spend").notNull().default(0),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_loyalty_points_org").on(table.organizationId),
+  orgCustomerUnique: uniqueIndex("loyalty_points_org_customer_unique").on(table.organizationId, table.customerId),
+}));
+
+export const loyaltyTransactions = pgTable("loyalty_transactions", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull().references(() => organization.id, { onDelete: "cascade" }),
+  customerId: uuid("customer_id")
+    .notNull()
+    .references(() => customers.id, { onDelete: "cascade" }),
+  orderId: uuid("order_id"),
+  type: text("type", { enum: ["earn", "redeem"] }).notNull(),
+  amount: integer("amount").notNull(),
+  description: text("description"),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_loyalty_transactions_org").on(table.organizationId),
+  customerIdx: index("idx_loyalty_transactions_customer").on(table.customerId),
+}));
+
+export const loyaltyRedemptionOffers = pgTable("loyalty_redemption_offers", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  name: text("name").notNull(),
+  pointsRequired: integer("points_required").notNull(),
+  rewardType: text("reward_type", { enum: ["discount_percentage", "discount_fixed", "free_item", "free_shipping"] }).notNull(),
+  rewardValue: integer("reward_value").notNull(),
+  rewardEntityId: uuid("reward_entity_id"),
+  isActive: boolean("is_active").notNull().default(true),
+  validFrom: timestamp("valid_from", { withTimezone: true }),
+  validUntil: timestamp("valid_until", { withTimezone: true }),
+  maxRedemptions: integer("max_redemptions"),
+  timesRedeemed: integer("times_redeemed").notNull().default(0),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_loyalty_offers_org").on(table.organizationId),
+}));

package/src/services/loyalty-service.ts

@@ -0,0 +1,130 @@
+import { eq, and, desc, sql } from "drizzle-orm";
+import { Ok, Err } from "@unifiedcommerce/core";
+import type { PluginResult } from "@unifiedcommerce/core";
+import { loyaltyPoints, loyaltyTransactions, loyaltyRedemptionOffers } from "../schema";
+import type { Db, LoyaltyPoints, LoyaltyOffer, Tier } from "../types";
+
+function calculateTier(points: number, thresholds: { silver: number; gold: number; platinum: number }): Tier {
+  if (points >= thresholds.platinum) return "platinum";
+  if (points >= thresholds.gold) return "gold";
+  if (points >= thresholds.silver) return "silver";
+  return "bronze";
+}
+
+export class LoyaltyService {
+  constructor(private db: Db, private thresholds: { silver: number; gold: number; platinum: number }) {}
+
+  async getPoints(orgId: string, customerId: string): Promise<PluginResult<LoyaltyPoints | null>> {
+    const rows = await this.db.select().from(loyaltyPoints)
+      .where(and(eq(loyaltyPoints.organizationId, orgId), eq(loyaltyPoints.customerId, customerId)));
+    return Ok(rows[0] ?? null);
+  }
+
+  async earnPoints(orgId: string, customerId: string, amount: number, orderId?: string): Promise<PluginResult<LoyaltyPoints>> {
+    if (amount <= 0) return Err("Amount must be positive");
+
+    await this.db.insert(loyaltyTransactions).values({
+      organizationId: orgId, customerId, orderId, type: "earn", amount,
+      description: `Earned ${amount} points`,
+    });
+
+    await this.db.insert(loyaltyPoints).values({
+      organizationId: orgId, customerId, points: amount, lifetimeSpend: 0,
+      tier: calculateTier(amount, this.thresholds),
+    }).onConflictDoUpdate({
+      target: [loyaltyPoints.organizationId, loyaltyPoints.customerId],
+      set: {
+        points: sql`${loyaltyPoints.points} + ${amount}`,
+        updatedAt: new Date(),
+      },
+    });
+
+    const [updated] = await this.db.select().from(loyaltyPoints)
+      .where(and(eq(loyaltyPoints.organizationId, orgId), eq(loyaltyPoints.customerId, customerId)));
+
+    if (updated) {
+      const newTier = calculateTier(updated.points, this.thresholds);
+      if (newTier !== updated.tier) {
+        await this.db.update(loyaltyPoints).set({ tier: newTier, updatedAt: new Date() })
+          .where(and(eq(loyaltyPoints.organizationId, orgId), eq(loyaltyPoints.customerId, customerId)));
+        return Ok({ ...updated, tier: newTier });
+      }
+    }
+
+    return Ok(updated!);
+  }
+
+  async redeemPoints(orgId: string, customerId: string, amount: number): Promise<PluginResult<LoyaltyPoints>> {
+    if (amount <= 0) return Err("Amount must be positive");
+
+    // Atomic check-and-deduct: lock the row to prevent concurrent double-spend
+    const [loyalty] = await this.db.select().from(loyaltyPoints)
+      .where(and(eq(loyaltyPoints.organizationId, orgId), eq(loyaltyPoints.customerId, customerId)))
+      .for("update");
+    if (!loyalty) return Err("No loyalty account found");
+    if (loyalty.points < amount) return Err("Not enough points");
+
+    const newPoints = loyalty.points - amount;
+    const newTier = calculateTier(newPoints, this.thresholds);
+
+    await this.db.update(loyaltyPoints).set({ points: newPoints, tier: newTier, updatedAt: new Date() })
+      .where(and(eq(loyaltyPoints.organizationId, orgId), eq(loyaltyPoints.customerId, customerId)));
+
+    await this.db.insert(loyaltyTransactions).values({
+      organizationId: orgId, customerId, type: "redeem", amount,
+      description: `Redeemed ${amount} points`,
+    });
+
+    return Ok({ ...loyalty, points: newPoints, tier: newTier });
+  }
+
+  async getLeaderboard(orgId: string, limit = 10): Promise<PluginResult<LoyaltyPoints[]>> {
+    const rows = await this.db.select().from(loyaltyPoints)
+      .where(eq(loyaltyPoints.organizationId, orgId))
+      .orderBy(desc(loyaltyPoints.points)).limit(limit);
+    return Ok(rows);
+  }
+
+  // ─── Offers ────────────────────────────────────────────────────────
+
+  async createOffer(orgId: string, input: {
+    name: string; pointsRequired: number; rewardType: "discount_percentage" | "discount_fixed" | "free_item" | "free_shipping";
+    rewardValue: number; rewardEntityId?: string; validFrom?: string; validUntil?: string; maxRedemptions?: number;
+  }): Promise<PluginResult<LoyaltyOffer>> {
+    const rows = await this.db.insert(loyaltyRedemptionOffers).values({
+      organizationId: orgId, name: input.name, pointsRequired: input.pointsRequired,
+      rewardType: input.rewardType, rewardValue: input.rewardValue,
+      rewardEntityId: input.rewardEntityId,
+      ...(input.validFrom ? { validFrom: new Date(input.validFrom) } : {}),
+      ...(input.validUntil ? { validUntil: new Date(input.validUntil) } : {}),
+      maxRedemptions: input.maxRedemptions,
+    }).returning();
+    return Ok(rows[0]!);
+  }
+
+  async listOffers(orgId: string): Promise<PluginResult<LoyaltyOffer[]>> {
+    const rows = await this.db.select().from(loyaltyRedemptionOffers)
+      .where(and(eq(loyaltyRedemptionOffers.organizationId, orgId), eq(loyaltyRedemptionOffers.isActive, true)));
+    return Ok(rows);
+  }
+
+  async redeemOffer(orgId: string, customerId: string, offerId: string): Promise<PluginResult<{ offer: LoyaltyOffer; remainingPoints: number }>> {
+    // Lock offer row to prevent concurrent over-redemption
+    const [offer] = await this.db.select().from(loyaltyRedemptionOffers)
+      .where(and(eq(loyaltyRedemptionOffers.id, offerId), eq(loyaltyRedemptionOffers.organizationId, orgId)))
+      .for("update");
+    if (!offer) return Err("Offer not found");
+    if (!offer.isActive) return Err("Offer is not active");
+    if (offer.maxRedemptions && offer.timesRedeemed >= offer.maxRedemptions) return Err("Offer fully redeemed");
+
+    // redeemPoints also uses FOR UPDATE — safe within same transaction context
+    const redeemResult = await this.redeemPoints(orgId, customerId, offer.pointsRequired);
+    if (!redeemResult.ok) return redeemResult;
+
+    await this.db.update(loyaltyRedemptionOffers)
+      .set({ timesRedeemed: sql`${loyaltyRedemptionOffers.timesRedeemed} + 1`, updatedAt: new Date() })
+      .where(eq(loyaltyRedemptionOffers.id, offerId));
+
+    return Ok({ offer, remainingPoints: redeemResult.value.points });
+  }
+}

package/src/types.ts

@@ -0,0 +1,17 @@
+import type { loyaltyPoints, loyaltyTransactions, loyaltyRedemptionOffers } from "./schema";
+
+export type { PluginDb as Db } from "@unifiedcommerce/core";
+export type LoyaltyPoints = typeof loyaltyPoints.$inferSelect;
+export type LoyaltyTransaction = typeof loyaltyTransactions.$inferSelect;
+export type LoyaltyOffer = typeof loyaltyRedemptionOffers.$inferSelect;
+export type Tier = "bronze" | "silver" | "gold" | "platinum";
+
+export interface LoyaltyPluginOptions {
+  pointsPerDollar?: number;
+  tierThresholds?: { silver: number; gold: number; platinum: number };
+}
+
+export const DEFAULT_LOYALTY_OPTIONS: Required<LoyaltyPluginOptions> = {
+  pointsPerDollar: 1,
+  tierThresholds: { silver: 500, gold: 1500, platinum: 3000 },
+};