@fonderie/customers 1.1.2 → 2.0.1

package/brain/outcomes.md

@@ -129,6 +129,8 @@ created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
 updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
 sex                      TEXT NOT NULL DEFAULT 'UNKNOWN'
 blacklist_reason         TEXT
+referral_code            TEXT
+referred_by              UUID REFERENCES fonderie_customers(id) ON DELETE SET NULL
 ```
 
 Raw SQL ships in `node_modules/@fonderie/customers/dist/migrations/sql/` — read it there if you must; never download tarballs.

package/brain/signatures.md

@@ -51,6 +51,8 @@ interface ICustomerDTO {
     avatarUrl: string;
     locale: string;
     referenceCode: string;
+    referralCode: string;
+    referredBy: string | null;
     blacklisted: {
         status: boolean;
         reason: string | null;
@@ -119,6 +121,7 @@ new CustomerEmailModel(store: IStoreAdapter): CustomerEmailModel
   .remove(emailId: string, customerId: string): Promise<void>
 
 new CustomerModel(store: IStoreAdapter): CustomerModel
+  .resolveReferralCode(workspaceId: string, code: string): Promise<string | null>
   .list(opts: ListCustomersOpts): Promise<ICustomer[]>
   .findById(id: string, workspaceId: string): Promise<ICustomer | null>
   .findDetail(id: string, workspaceId: string, depth: 2): Promise<ICustomerDetailD2 | null>
@@ -179,6 +182,8 @@ interface ICustomer {
     avatarUrl: string | null;
     locale: string;
     referenceCode: string | null;
+    referralCode: string | null;
+    referredBy: string | null;
     isBlacklisted: boolean;
     blacklistReason: string | null;
     createdBy: string | null;

package/dist/index.cjs

@@ -49,6 +49,8 @@ var EVENT_KEYS = {
   customerUnblacklisted: "fonderie.customer.unblacklisted"
 };
 var DEFAULT_REFERENCE_CODE_PREFIX = "CLT";
+var REFERRAL_CODE_ALPHABET = "23456789ABCDEFGHJKMNPQRSTUVWXYZ";
+var REFERRAL_CODE_LENGTH = 8;
 
 // src/dtos/customer.ts
 var import_core = require("@fonderie/core");
@@ -64,6 +66,8 @@ function toCustomerDTO(c) {
     avatarUrl: (0, import_core.stringOrEmpty)(c.avatarUrl),
     locale: (0, import_core.stringOrEmpty)(c.locale),
     referenceCode: (0, import_core.stringOrEmpty)(c.referenceCode),
+    referralCode: (0, import_core.stringOrEmpty)(c.referralCode),
+    referredBy: c.referredBy ?? null,
     blacklisted: { status: (0, import_core.booleanOrFalse)(c.isBlacklisted), reason: c.blacklistReason ?? null },
     createdBy: (0, import_core.stringOrEmpty)(c.createdBy),
     createdAt: (0, import_core.dateOrEmpty)(c.createdAt),
@@ -185,6 +189,7 @@ function toCustomerTagDTO(t) {
 }
 
 // src/models/customer.model.ts
+var import_node_crypto = require("crypto");
 function groupByCustomer(rows) {
   return rows.reduce((m, r) => {
     if (!m.has(r.customerId)) m.set(r.customerId, []);
@@ -203,6 +208,8 @@ var SELECT_CUSTOMER = `
 	avatar_url     AS "avatarUrl",
 	locale,
 	reference_code AS "referenceCode",
+	referral_code  AS "referralCode",
+	referred_by    AS "referredBy",
 	is_blacklisted    AS "isBlacklisted",
 	blacklist_reason  AS "blacklistReason",
 	created_by     AS "createdBy",
@@ -225,6 +232,39 @@ var CustomerModel = class {
     );
     return `${prefix}-${String(row.nextVal).padStart(4, "0")}`;
   }
+  /** A random referral code (crypto-random over the unambiguous alphabet). */
+  randomReferralCode() {
+    let out = "";
+    for (let i = 0; i < REFERRAL_CODE_LENGTH; i++) {
+      out += REFERRAL_CODE_ALPHABET[(0, import_node_crypto.randomInt)(REFERRAL_CODE_ALPHABET.length)];
+    }
+    return out;
+  }
+  /**
+   * A referral code unique within the workspace. Random codes collide only
+   * astronomically rarely; we still pre-check and retry a few times, and the
+   * unique index is the final guard. Throws only if the space is somehow
+   * exhausted (not reachable in practice).
+   */
+  async allocateReferralCode(workspaceId) {
+    for (let attempt = 0; attempt < 5; attempt++) {
+      const code = this.randomReferralCode();
+      const [hit] = await this.store.query(
+        `SELECT 1 AS one FROM fonderie_customers WHERE workspace_id = $1 AND referral_code = $2 LIMIT 1`,
+        [workspaceId, code]
+      );
+      if (!hit) return code;
+    }
+    throw new Error("could not allocate a unique referral code");
+  }
+  /** Resolve a referral code to the referring customer's id, within a workspace. */
+  async resolveReferralCode(workspaceId, code) {
+    const [row] = await this.store.query(
+      `SELECT id FROM fonderie_customers WHERE workspace_id = $1 AND referral_code = $2 LIMIT 1`,
+      [workspaceId, code]
+    );
+    return row?.id ?? null;
+  }
   async list(opts) {
     const conditions = ["workspace_id = $1"];
     const params = [opts.workspaceId];
@@ -540,10 +580,12 @@ var CustomerModel = class {
   }
   async create(opts) {
     const referenceCode = opts.referenceCode ?? await this.allocateCode(opts.workspaceId, opts.referenceCodePrefix ?? DEFAULT_REFERENCE_CODE_PREFIX);
+    const referralCode = opts.referralCode ?? await this.allocateReferralCode(opts.workspaceId);
+    const referredBy = opts.referredByCode ? await this.resolveReferralCode(opts.workspaceId, opts.referredByCode) : null;
     const [row] = await this.store.query(
       `INSERT INTO fonderie_customers
-			   (workspace_id, type, sex, first_name, last_name, company_name, avatar_url, locale, reference_code, created_by)
-			 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+			   (workspace_id, type, sex, first_name, last_name, company_name, avatar_url, locale, reference_code, referral_code, referred_by, created_by)
+			 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
 			 RETURNING ${SELECT_CUSTOMER}`,
       [
         opts.workspaceId,
@@ -555,6 +597,8 @@ var CustomerModel = class {
         opts.avatarUrl ?? null,
         opts.locale ?? "en-US",
         referenceCode,
+        referralCode,
+        referredBy,
         opts.createdBy ?? null
       ]
     );
@@ -1227,7 +1271,9 @@ var customerFields = {
   companyName: import_zod.z.string().max(200).nullable().optional(),
   avatarUrl: import_zod.z.string().trim().pipe(import_zod.z.url()).nullable().optional(),
   locale: import_zod.z.string().max(35).nullable().optional(),
-  referenceCode: import_zod.z.string().max(100).nullable().optional()
+  referenceCode: import_zod.z.string().max(100).nullable().optional(),
+  referralCode: import_zod.z.string().max(100).nullable().optional(),
+  referredByCode: import_zod.z.string().max(100).nullable().optional()
 };
 var createCustomerSchema = import_zod.z.object(customerFields);
 var updateCustomerSchema = import_zod.z.object(customerFields).refine((o) => Object.values(o).some((v) => v !== void 0), "Provide at least one field");
@@ -1349,6 +1395,8 @@ function customerController(store, config = {}, bus) {
       const avatarUrl = body?.["avatarUrl"];
       const locale = body?.["locale"];
       const referenceCode = body?.["referenceCode"];
+      const referralCode = body?.["referralCode"];
+      const referredByCode = body?.["referredByCode"];
       if (type !== void 0 && type !== "individual" && type !== "business") {
         return (0, import_core2.setApiResponse)(
           import_core2.HTTP.UNPROCESSABLE,
@@ -1377,6 +1425,9 @@ function customerController(store, config = {}, bus) {
           // exactOptionalPropertyTypes: omit the key entirely when absent
           ...typeof referenceCode === "string" ? { referenceCode: referenceCode.toUpperCase() } : {},
           referenceCodePrefix: prefix,
+          // referral: explicit code override is rare; referredByCode is the signup input
+          ...typeof referralCode === "string" ? { referralCode: referralCode.toUpperCase() } : {},
+          ...typeof referredByCode === "string" ? { referredByCode: referredByCode.toUpperCase() } : {},
           createdBy: ctx.user?.id ?? null
         });
       } catch (err) {