@fonderie/customers 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -28,6 +28,8 @@ interface ICustomerDTO {
     avatarUrl: string;
     locale: string;
     referenceCode: string;
+    referralCode: string;
+    referredBy: string | null;
     blacklisted: {
         status: boolean;
         reason: string | null;
@@ -125,6 +127,10 @@ interface CreateCustomerOpts {
     referenceCode?: string;
     /** Prefix used when auto-generating. Defaults to 'CLT'. */
     referenceCodePrefix?: string;
+    /** Explicit referral code. Omit to auto-generate a random, workspace-unique one. */
+    referralCode?: string;
+    /** The referrer's referral code (from signup). Resolved to `referredBy` within the same workspace; ignored if it doesn't match a customer. */
+    referredByCode?: string;
     createdBy?: string | null;
 }
 interface UpdateCustomerOpts {
@@ -142,6 +148,17 @@ declare class CustomerModel {
     private readonly store;
     constructor(store: IStoreAdapter);
     private allocateCode;
+    /** A random referral code (crypto-random over the unambiguous alphabet). */
+    private randomReferralCode;
+    /**
+     * 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).
+     */
+    private allocateReferralCode;
+    /** Resolve a referral code to the referring customer's id, within a workspace. */
+    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>;
@@ -251,6 +268,8 @@ declare const createCustomerSchema: z.ZodObject<{
     avatarUrl: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodURL>>>;
     locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     referenceCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    referralCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    referredByCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const updateCustomerSchema: z.ZodObject<{
     type: z.ZodOptional<z.ZodEnum<{
@@ -268,6 +287,8 @@ declare const updateCustomerSchema: z.ZodObject<{
     avatarUrl: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodURL>>>;
     locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     referenceCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    referralCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    referredByCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const blacklistSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;

package/dist/index.d.ts

@@ -28,6 +28,8 @@ interface ICustomerDTO {
     avatarUrl: string;
     locale: string;
     referenceCode: string;
+    referralCode: string;
+    referredBy: string | null;
     blacklisted: {
         status: boolean;
         reason: string | null;
@@ -125,6 +127,10 @@ interface CreateCustomerOpts {
     referenceCode?: string;
     /** Prefix used when auto-generating. Defaults to 'CLT'. */
     referenceCodePrefix?: string;
+    /** Explicit referral code. Omit to auto-generate a random, workspace-unique one. */
+    referralCode?: string;
+    /** The referrer's referral code (from signup). Resolved to `referredBy` within the same workspace; ignored if it doesn't match a customer. */
+    referredByCode?: string;
     createdBy?: string | null;
 }
 interface UpdateCustomerOpts {
@@ -142,6 +148,17 @@ declare class CustomerModel {
     private readonly store;
     constructor(store: IStoreAdapter);
     private allocateCode;
+    /** A random referral code (crypto-random over the unambiguous alphabet). */
+    private randomReferralCode;
+    /**
+     * 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).
+     */
+    private allocateReferralCode;
+    /** Resolve a referral code to the referring customer's id, within a workspace. */
+    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>;
@@ -251,6 +268,8 @@ declare const createCustomerSchema: z.ZodObject<{
     avatarUrl: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodURL>>>;
     locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     referenceCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    referralCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    referredByCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const updateCustomerSchema: z.ZodObject<{
     type: z.ZodOptional<z.ZodEnum<{
@@ -268,6 +287,8 @@ declare const updateCustomerSchema: z.ZodObject<{
     avatarUrl: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodURL>>>;
     locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     referenceCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    referralCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    referredByCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 declare const blacklistSchema: z.ZodObject<{
     reason: z.ZodOptional<z.ZodString>;

package/dist/index.js

@@ -13,6 +13,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
 import { arrayOrEmpty, booleanOrFalse, dateOrEmpty, stringOrEmpty } from "@fonderie/core";
@@ -28,6 +30,8 @@ function toCustomerDTO(c) {
     avatarUrl: stringOrEmpty(c.avatarUrl),
     locale: stringOrEmpty(c.locale),
     referenceCode: stringOrEmpty(c.referenceCode),
+    referralCode: stringOrEmpty(c.referralCode),
+    referredBy: c.referredBy ?? null,
     blacklisted: { status: booleanOrFalse(c.isBlacklisted), reason: c.blacklistReason ?? null },
     createdBy: stringOrEmpty(c.createdBy),
     createdAt: dateOrEmpty(c.createdAt),
@@ -149,6 +153,7 @@ function toCustomerTagDTO(t) {
 }
 
 // src/models/customer.model.ts
+import { randomInt } from "crypto";
 function groupByCustomer(rows) {
   return rows.reduce((m, r) => {
     if (!m.has(r.customerId)) m.set(r.customerId, []);
@@ -167,6 +172,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",
@@ -189,6 +196,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[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];
@@ -504,10 +544,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,
@@ -519,6 +561,8 @@ var CustomerModel = class {
         opts.avatarUrl ?? null,
         opts.locale ?? "en-US",
         referenceCode,
+        referralCode,
+        referredBy,
         opts.createdBy ?? null
       ]
     );
@@ -1191,7 +1235,9 @@ var customerFields = {
   companyName: z.string().max(200).nullable().optional(),
   avatarUrl: z.string().trim().pipe(z.url()).nullable().optional(),
   locale: z.string().max(35).nullable().optional(),
-  referenceCode: z.string().max(100).nullable().optional()
+  referenceCode: z.string().max(100).nullable().optional(),
+  referralCode: z.string().max(100).nullable().optional(),
+  referredByCode: z.string().max(100).nullable().optional()
 };
 var createCustomerSchema = z.object(customerFields);
 var updateCustomerSchema = z.object(customerFields).refine((o) => Object.values(o).some((v) => v !== void 0), "Provide at least one field");
@@ -1313,6 +1359,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 setApiResponse(
           HTTP.UNPROCESSABLE,
@@ -1341,6 +1389,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) {