@qcobro/common 1.11.3

package/src/utils/outreach.test.ts

@@ -0,0 +1,83 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { renderTemplate, buildOutreachContext, pickRandomNumber } from "./outreach.js";
+import type { PortfolioAccountRecord } from "../types/portfolios.js";
+
+function makeAccount(overrides: Partial<PortfolioAccountRecord> = {}): PortfolioAccountRecord {
+  return {
+    id: "acc-1",
+    portfolioId: "pf-1",
+    externalId: "EXT-1",
+    fullName: "María López",
+    phone: "+50670000000",
+    preferredLanguage: "es",
+    bestTimeToCall: null,
+    customerSegment: null,
+    principalAmount: 1000,
+    termsAmount: 0,
+    termsFrequency: null,
+    termsLength: 0,
+    outstandingBalance: 1500,
+    daysPastDue: 30,
+    missedInstallments: 2,
+    lastPaymentDate: null,
+    lastPaymentAmount: null,
+    negotiationOptions: null,
+    archivedAt: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides
+  };
+}
+
+describe("renderTemplate + buildOutreachContext", () => {
+  it("personalizes a body with account data and derived fields", () => {
+    const ctx = buildOutreachContext(makeAccount(), { currency: "CRC" });
+    const out = renderTemplate(
+      "Hola {{firstName}}, su saldo es {{outstandingBalance}} {{currency}}",
+      ctx
+    );
+    assert.equal(out, "Hola María, su saldo es 1500 CRC");
+  });
+
+  it("renders a missing field as empty without throwing", () => {
+    const ctx = buildOutreachContext(makeAccount(), { currency: "CRC" });
+    const out = renderTemplate("Hola {{firstName}} {{unknownField}}!", ctx);
+    assert.equal(out, "Hola María !");
+  });
+
+  it("derives firstName from the first token of fullName", () => {
+    const ctx = buildOutreachContext(makeAccount({ fullName: "Juan Carlos Pérez" }), {
+      currency: "USD"
+    });
+    assert.equal(ctx.firstName, "Juan");
+  });
+
+  it("derives isDue from daysPastDue", () => {
+    const overdue = buildOutreachContext(makeAccount({ daysPastDue: 30 }), { currency: "CRC" });
+    const current = buildOutreachContext(makeAccount({ daysPastDue: 0 }), { currency: "CRC" });
+    assert.equal(overdue.isDue, true);
+    assert.equal(current.isDue, false);
+  });
+
+  it("branches a template on the isDue conditional", () => {
+    const tpl = "{{#if isDue}}Su pago está vencido{{else}}Gracias por estar al día{{/if}}";
+    const overdue = renderTemplate(
+      tpl,
+      buildOutreachContext(makeAccount({ daysPastDue: 5 }), { currency: "CRC" })
+    );
+    const current = renderTemplate(
+      tpl,
+      buildOutreachContext(makeAccount({ daysPastDue: 0 }), { currency: "CRC" })
+    );
+    assert.equal(overdue, "Su pago está vencido");
+    assert.equal(current, "Gracias por estar al día");
+  });
+});
+
+describe("pickRandomNumber", () => {
+  it("returns a number from the pool", () => {
+    const pool = ["+1", "+2", "+3"];
+    assert.ok(pool.includes(pickRandomNumber(pool)));
+  });
+});

package/src/utils/outreach.ts

@@ -0,0 +1,57 @@
+import Handlebars from "handlebars";
+import type { PortfolioAccountRecord } from "../types/portfolios.js";
+import type { NumberSelector } from "../types/dispatch.js";
+
+/**
+ * Renders a Handlebars template against a context. Bodies are plain text (voice
+ * script / SMS), never HTML, so escaping is disabled. A missing `{{field}}`
+ * renders as empty rather than throwing, so a sparse account never aborts a
+ * dispatch mid-flight.
+ */
+export function renderTemplate(template: string, context: Record<string, unknown>): string {
+  const compiled = Handlebars.compile(template, { noEscape: true });
+  return compiled(context);
+}
+
+/**
+ * Extracts the distinct simple placeholder names from a template, in first-seen order
+ * (e.g. `"Hola {{firstName}}, saldo {{outstandingBalance}}"` → `["firstName",
+ * "outstandingBalance"]`). Block helpers like `{{#if}}`/`{{/if}}` are ignored. Used to
+ * turn a WhatsApp template body into Meta **named** parameters: each token becomes a
+ * `{ parameter_name, text }` pair rendered against the customer context.
+ */
+export function extractTemplateTokens(template: string): string[] {
+  const tokens: string[] = [];
+  const re = /\{\{\s*([A-Za-z_][\w.]*)\s*\}\}/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(template)) !== null) {
+    if (!tokens.includes(match[1])) tokens.push(match[1]);
+  }
+  return tokens;
+}
+
+/**
+ * Builds the render context exposed to outreach templates: every account field
+ * plus derived `firstName` (first token of `fullName`), `currency` (the
+ * workspace's currency from WorkspaceSettings), and `isDue` (whether the account
+ * is past due, i.e. `daysPastDue > 0`). `isDue` is a boolean so templates can
+ * branch on it with Handlebars conditionals, e.g.
+ * `{{#if isDue}}su pago está vencido{{else}}gracias por estar al día{{/if}}`.
+ * These are the variables documented in the agent console.
+ */
+export function buildOutreachContext(
+  account: PortfolioAccountRecord,
+  opts: { currency: string }
+): Record<string, unknown> {
+  const firstName = account.fullName.trim().split(/\s+/)[0] ?? "";
+  return {
+    ...account,
+    firstName,
+    currency: opts.currency,
+    isDue: account.daysPastDue > 0
+  };
+}
+
+/** Default number selector: a uniform random pick from the pool. */
+export const pickRandomNumber: NumberSelector = (numbers) =>
+  numbers[Math.floor(Math.random() * numbers.length)];

package/src/utils/time.ts

@@ -0,0 +1,66 @@
+/**
+ * Timezone-aware wall-clock helpers. The campaigns engine evaluates schedule
+ * windows and daily caps in the deployment timezone (from `qcobro.json`), not UTC.
+ * All functions take an IANA timezone string and use `Intl` so DST is handled.
+ */
+
+interface LocalParts {
+  /** Local calendar date as `YYYY-MM-DD`. */
+  date: string;
+  /** ISO weekday: 1 = Monday … 7 = Sunday. */
+  weekday: number;
+  /** Local time as `HH:MM` (24h, zero-padded). */
+  time: string;
+}
+
+const WEEKDAY_TO_ISO: Record<string, number> = {
+  Mon: 1,
+  Tue: 2,
+  Wed: 3,
+  Thu: 4,
+  Fri: 5,
+  Sat: 6,
+  Sun: 7
+};
+
+/** Decompose an instant into local date/weekday/time parts for the given timezone. */
+export function localParts(date: Date, timeZone: string): LocalParts {
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    weekday: "short",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false
+  });
+  const parts = Object.fromEntries(fmt.formatToParts(date).map((p) => [p.type, p.value]));
+  // `hour` can come back as "24" at midnight under hour12:false; normalize to "00".
+  const hour = parts.hour === "24" ? "00" : parts.hour;
+  return {
+    date: `${parts.year}-${parts.month}-${parts.day}`,
+    weekday: WEEKDAY_TO_ISO[parts.weekday] ?? 0,
+    time: `${hour}:${parts.minute}`
+  };
+}
+
+/** Local calendar date (`YYYY-MM-DD`) for an instant in the given timezone. */
+export function localDateString(date: Date, timeZone: string): string {
+  return localParts(date, timeZone).date;
+}
+
+/** True when two instants fall on the same local calendar day in the timezone. */
+export function isSameLocalDay(a: Date, b: Date, timeZone: string): boolean {
+  return localDateString(a, timeZone) === localDateString(b, timeZone);
+}
+
+/** ISO weekday (1=Mon … 7=Sun) for an instant in the timezone. */
+export function localWeekdayISO(date: Date, timeZone: string): number {
+  return localParts(date, timeZone).weekday;
+}
+
+/** Local `HH:MM` (24h) for an instant in the timezone. */
+export function localTimeHHMM(date: Date, timeZone: string): string {
+  return localParts(date, timeZone).time;
+}

package/src/utils/withErrorHandlingAndValidation.test.ts

@@ -0,0 +1,33 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { z } from "zod";
+import { withErrorHandlingAndValidation } from "./withErrorHandlingAndValidation.js";
+import { ValidationError } from "../errors/ValidationError.js";
+
+const schema = z.object({ name: z.string().min(1) });
+
+describe("withErrorHandlingAndValidation", () => {
+  it("passes parsed, typed input to the wrapped function and returns its result", async () => {
+    let received: { name: string } | null = null;
+    const wrapped = withErrorHandlingAndValidation(async (params: { name: string }) => {
+      received = params;
+      return `hello ${params.name}`;
+    }, schema);
+
+    const result = await wrapped({ name: "Ada" });
+
+    assert.equal(result, "hello Ada");
+    assert.deepEqual(received, { name: "Ada" });
+  });
+
+  it("throws ValidationError and never calls the inner function on invalid input", async () => {
+    let called = false;
+    const wrapped = withErrorHandlingAndValidation(async (params: { name: string }) => {
+      called = true;
+      return params.name;
+    }, schema);
+
+    await assert.rejects(() => wrapped({ name: "" }), ValidationError);
+    assert.equal(called, false);
+  });
+});

package/src/utils/withErrorHandlingAndValidation.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { ValidationError } from "../errors/ValidationError.js";
+
+/**
+ * Wraps an async function with Zod schema validation.
+ *
+ * The returned function validates its input against `schema` before calling
+ * `fn`. Valid input is passed through as parsed, typed data; invalid input
+ * throws a {@link ValidationError} and `fn` is never invoked.
+ *
+ * @example
+ * ```typescript
+ * const createCustomer = withErrorHandlingAndValidation(
+ *   async (params: CreateCustomerInput) => client.customer.create({ data: params }),
+ *   createCustomerSchema
+ * );
+ * ```
+ */
+export function withErrorHandlingAndValidation<TSchema extends z.ZodType, TResult>(
+  fn: (params: z.infer<TSchema>) => Promise<TResult>,
+  schema: TSchema
+): (params: unknown) => Promise<TResult> {
+  return async (params: unknown) => {
+    const result = schema.safeParse(params);
+
+    if (!result.success) {
+      throw new ValidationError(result.error);
+    }
+
+    return fn(result.data);
+  };
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}