@qcobro/common 1.11.3

package/src/schemas/userSettings.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+/** Supported console languages. Keep in sync with the webapp message catalogs. */
+export const languageSchema = z.enum(["en", "es"]);
+export type Language = z.infer<typeof languageSchema>;
+
+/** The per-user settings record (stored in the app DB, keyed by the Identity userRef). */
+export const userSettingsSchema = z.object({
+  userRef: z.string().min(1),
+  language: languageSchema
+});
+export type UserSettings = z.infer<typeof userSettingsSchema>;
+
+/** Operator-editable user settings. */
+export const updateUserLanguageSchema = z.object({
+  language: languageSchema
+});
+export type UpdateUserLanguageInput = z.infer<typeof updateUserLanguageSchema>;

package/src/schemas/users.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+export const updateProfileSchema = z.object({
+  name: z.string().min(1).max(60).optional(),
+  phone: z.string().max(20).optional()
+});
+export type UpdateProfileInput = z.infer<typeof updateProfileSchema>;

package/src/schemas/voiceEvent.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+/**
+ * Events emitted by the Fonoster autopilot events-hook for a Voz IA call.
+ * `conversation.started` lets us capture partial data even if the call never ends
+ * cleanly; `conversation.ended` carries the transcript and recording.
+ */
+export const voiceEventTypeSchema = z.enum(["conversation.started", "conversation.ended"]);
+export type VoiceEventType = z.infer<typeof voiceEventTypeSchema>;
+
+/**
+ * A raw chat-history entry from the autopilot: `{ ai: text }` (our agent) or
+ * `{ human: text }` (the customer). Kept permissive — only the ai/human keys are read.
+ */
+export const voiceChatMessageSchema = z.record(z.string(), z.unknown());
+
+export const voiceConversationEventSchema = z.object({
+  eventType: voiceEventTypeSchema,
+  appRef: z.string().min(1),
+  callRef: z.string().min(1),
+  phone: z.string().min(1),
+  chatHistory: z.array(voiceChatMessageSchema).optional(),
+  recordingUrl: z.string().optional(),
+  durationSeconds: z.number().int().nonnegative().optional()
+});
+export type VoiceConversationEvent = z.infer<typeof voiceConversationEventSchema>;
+
+/** A normalized transcript line stored in `channelData.transcript` for the console. */
+export interface TranscriptLine {
+  role: "agent" | "customer";
+  text: string;
+}
+
+/** Normalize autopilot chatHistory into ordered console transcript lines. */
+export function normalizeChatHistory(
+  chatHistory: ReadonlyArray<Record<string, unknown>> | undefined
+): TranscriptLine[] {
+  if (!chatHistory) return [];
+  const lines: TranscriptLine[] = [];
+  for (const entry of chatHistory) {
+    if (typeof entry.ai === "string") lines.push({ role: "agent", text: entry.ai });
+    else if (typeof entry.human === "string") lines.push({ role: "customer", text: entry.human });
+  }
+  return lines;
+}

package/src/schemas/whatsApp.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+
+/**
+ * WhatsApp integration contracts: the per-workspace WABA credentials and its sender
+ * numbers, plus the inbound Meta webhook body. This is QCobro's first tenant-provided
+ * secret — the `accessToken` is encrypted at rest (cloak) and never returned to clients.
+ *
+ * The webhook schema is a focused port of `../mikro/mods/common/src/schemas/whatsapp.ts`,
+ * trimmed to what QCobro ingests (customer messages, delivery/opt-out statuses) and
+ * extended with `metadata.phone_number_id` so events resolve to a workspace/sender.
+ */
+
+/** What a sender number can do. `messaging` now; `calling` reserved for WhatsApp Voice (future). */
+export const whatsAppCapabilitiesSchema = z.object({
+  messaging: z.boolean(),
+  calling: z.boolean()
+});
+export type WhatsAppCapabilities = z.infer<typeof whatsAppCapabilitiesSchema>;
+
+/** Connect (or update) the workspace's WABA. The token is the tenant secret. */
+export const upsertWhatsAppIntegrationSchema = z.object({
+  wabaId: z.string().min(1),
+  accessToken: z.string().min(1),
+  /** Token echoed back during Meta's webhook verify-token handshake. */
+  verifyToken: z.string().min(1),
+  /** Meta template-send language for this workspace (e.g. `es_DO`); the single source for
+   * the WhatsApp send language. Kept with the WhatsApp config rather than in WorkspaceSettings. */
+  defaultLanguage: z.string().min(1)
+});
+export type UpsertWhatsAppIntegrationInput = z.infer<typeof upsertWhatsAppIntegrationSchema>;
+
+/** Add a sender number to the workspace's integration. */
+export const addWhatsAppSenderNumberSchema = z.object({
+  /** Meta per-number messaging endpoint id. Globally unique across the deployment. */
+  phoneNumberId: z.string().min(1),
+  /** E.164 display number for the UI. */
+  displayNumber: z.string().min(1),
+  /** Operator label, e.g. "Cobranza Suave". */
+  label: z.string().min(1)
+});
+export type AddWhatsAppSenderNumberInput = z.infer<typeof addWhatsAppSenderNumberSchema>;
+
+export const removeWhatsAppSenderNumberSchema = z.object({
+  phoneNumberId: z.string().min(1)
+});
+export type RemoveWhatsAppSenderNumberInput = z.infer<typeof removeWhatsAppSenderNumberSchema>;
+
+// ── Inbound webhook body (Meta Cloud API) ─────────────────────────────────────
+
+const whatsAppInboundMessageSchema = z.object({
+  from: z.string(),
+  id: z.string(),
+  timestamp: z.string(),
+  type: z.string(),
+  text: z.object({ body: z.string() }).optional()
+});
+
+/** Delivery/read/opt-out status callbacks. `errors` carries opt-out/block signals (code 131050 etc.). */
+const whatsAppStatusSchema = z.object({
+  id: z.string(),
+  status: z.string(),
+  recipient_id: z.string().optional(),
+  timestamp: z.string().optional(),
+  errors: z
+    .array(z.object({ code: z.number().optional(), title: z.string().optional() }))
+    .optional()
+});
+
+const whatsAppChangeValueSchema = z.object({
+  messaging_product: z.string().optional(),
+  metadata: z
+    .object({
+      display_phone_number: z.string().optional(),
+      /** Resolves the event to a `WhatsAppSenderNumber` (and thus a workspace). */
+      phone_number_id: z.string()
+    })
+    .optional(),
+  messages: z.array(whatsAppInboundMessageSchema).optional(),
+  statuses: z.array(whatsAppStatusSchema).optional(),
+  // Quality-rating callbacks: phone_number_id is at the value root, not under metadata.
+  phone_number_id: z.string().optional(),
+  event: z.string().optional(),
+  new_quality_rating: z.string().optional()
+});
+
+const whatsAppChangeSchema = z.object({
+  field: z.string().optional(),
+  value: whatsAppChangeValueSchema.optional()
+});
+
+const whatsAppEntrySchema = z.object({
+  id: z.string().optional(),
+  changes: z.array(whatsAppChangeSchema).optional()
+});
+
+/** The full inbound webhook body. Lenient on unknown fields Meta may add. */
+export const whatsAppWebhookSchema = z.object({
+  object: z.string().optional(),
+  entry: z.array(whatsAppEntrySchema).optional()
+});
+export type WhatsAppWebhookBody = z.infer<typeof whatsAppWebhookSchema>;

package/src/schemas/workspaceSettings.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+/** Supported display/billing currencies. A workspace has exactly one. */
+export const currencySchema = z.enum(["USD", "DOP"]);
+export type Currency = z.infer<typeof currencySchema>;
+
+/** The per-workspace settings record (stored in the app DB, keyed by workspaceRef). */
+export const workspaceSettingsSchema = z.object({
+  workspaceRef: z.string().min(1),
+  currency: currencySchema,
+  timezone: z.string().min(1)
+});
+export type WorkspaceSettings = z.infer<typeof workspaceSettingsSchema>;
+
+/** Operator-editable settings for the active workspace. */
+export const updateWorkspaceSettingsSchema = z.object({
+  currency: currencySchema,
+  timezone: z.string().min(1)
+});
+export type UpdateWorkspaceSettingsInput = z.infer<typeof updateWorkspaceSettingsSchema>;

package/src/schemas/workspaces.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { currencySchema } from "./workspaceSettings.js";
+
+export const createWorkspaceSchema = z.object({
+  name: z.string().min(1).max(60),
+  currency: currencySchema,
+  timezone: z.string().min(1)
+});
+export type CreateWorkspaceInput = z.infer<typeof createWorkspaceSchema>;
+
+export const getWorkspaceSchema = z.object({
+  ref: z.string().min(1)
+});
+export type GetWorkspaceInput = z.infer<typeof getWorkspaceSchema>;
+
+export const updateWorkspaceSchema = z.object({
+  ref: z.string().min(1),
+  name: z.string().min(1).max(60)
+});
+export type UpdateWorkspaceInput = z.infer<typeof updateWorkspaceSchema>;
+
+export const deleteWorkspaceSchema = z.object({
+  ref: z.string().min(1)
+});
+export type DeleteWorkspaceInput = z.infer<typeof deleteWorkspaceSchema>;
+
+export const workspaceRoleEnum = z.enum(["WORKSPACE_ADMIN", "WORKSPACE_MEMBER"]);
+export type WorkspaceRole = z.infer<typeof workspaceRoleEnum>;
+
+export const inviteMemberSchema = z.object({
+  email: z.email(),
+  role: workspaceRoleEnum.default("WORKSPACE_MEMBER"),
+  // Identity's inviteUserToWorkspace requires a name; keep the apiserver
+  // contract in sync so a missing name fails validation with a clear message
+  // instead of an opaque gRPC error.
+  name: z.string().min(1).max(60)
+});
+export type InviteMemberInput = z.infer<typeof inviteMemberSchema>;
+
+export const removeMemberSchema = z.object({
+  userRef: z.string().min(1)
+});
+export type RemoveMemberInput = z.infer<typeof removeMemberSchema>;
+
+export const resendInvitationSchema = z.object({
+  userRef: z.string().min(1)
+});
+export type ResendInvitationInput = z.infer<typeof resendInvitationSchema>;
+
+export const acceptInvitationSchema = z.object({
+  token: z.string().min(1)
+});
+export type AcceptInvitationInput = z.infer<typeof acceptInvitationSchema>;

package/src/types/agentTemplates.ts

@@ -0,0 +1,104 @@
+import type {
+  AgentType,
+  CreateAgentTemplateInput,
+  UpdateAgentTemplateInput,
+  DeleteAgentTemplateInput
+} from "../schemas/agentTemplates.js";
+
+export interface AgentTemplateRecord {
+  id: string;
+  workspaceRef: string;
+  name: string;
+  type: AgentType;
+  archivedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface VoiceAiConfigRecord {
+  templateId: string;
+  fonosterAppName: string;
+  fonosterAppRef: string | null;
+  voice: string;
+  systemPrompt: string;
+  firstMessage: string | null;
+  language: string;
+}
+
+export interface VoicePrerecordedConfigRecord {
+  templateId: string;
+  fonosterAppName: string;
+  fonosterAppRef: string | null;
+  voice: string;
+  script: string;
+  language: string;
+}
+
+export interface SmsConfigRecord {
+  templateId: string;
+  messageBody: string;
+  senderId: string | null;
+}
+
+export interface EmailConfigRecord {
+  templateId: string;
+  subject: string;
+  messageBody: string;
+  fromName: string;
+  fromEmail: string;
+}
+
+export interface WhatsAppConfigRecord {
+  templateId: string;
+  templateName: string;
+  messageBody: string;
+}
+
+/** A child-config delegate exposing the create/read/update calls the functions use. */
+interface ChildConfigDelegate<R> {
+  create(args: { data: Record<string, unknown> }): Promise<R>;
+  update(args: { where: { templateId: string }; data: Record<string, unknown> }): Promise<R>;
+  findUnique(args: { where: { templateId: string } }): Promise<R | null>;
+}
+
+export interface AgentTemplateClient {
+  agentTemplate: {
+    findMany(args: {
+      where: { workspaceRef: string; type?: AgentType; archivedAt?: Date | null };
+      orderBy?: { createdAt: "asc" | "desc" };
+    }): Promise<AgentTemplateRecord[]>;
+
+    findFirst(args: {
+      where: { id: string; workspaceRef: string };
+    }): Promise<AgentTemplateRecord | null>;
+
+    findFirstOrThrow(args: {
+      where: { id: string; workspaceRef: string };
+    }): Promise<AgentTemplateRecord>;
+
+    create(args: { data: Record<string, unknown> }): Promise<AgentTemplateRecord>;
+
+    update(args: {
+      where: { id: string };
+      data: Record<string, unknown>;
+    }): Promise<AgentTemplateRecord>;
+
+    delete(args: { where: { id: string } }): Promise<AgentTemplateRecord>;
+  };
+
+  voiceAiConfig: ChildConfigDelegate<VoiceAiConfigRecord>;
+  voicePrerecordedConfig: ChildConfigDelegate<VoicePrerecordedConfigRecord>;
+  smsConfig: ChildConfigDelegate<SmsConfigRecord>;
+  emailConfig: ChildConfigDelegate<EmailConfigRecord>;
+  whatsAppConfig: ChildConfigDelegate<WhatsAppConfigRecord>;
+
+  campaign: {
+    count(args: {
+      where: { agentTemplateId: string; status?: { not: "ARCHIVED" } };
+    }): Promise<number>;
+  };
+
+  $transaction<T>(fn: (tx: AgentTemplateClient) => Promise<T>): Promise<T>;
+}
+
+export type { CreateAgentTemplateInput, UpdateAgentTemplateInput, DeleteAgentTemplateInput };

package/src/types/campaigns.ts

@@ -0,0 +1,210 @@
+import type { AgentType } from "../schemas/agentTemplates.js";
+import type {
+  CampaignStatus,
+  CreateCampaignInput,
+  UpdateCampaignInput,
+  UpdateCampaignStatusInput,
+  DeleteCampaignInput
+} from "../schemas/campaigns.js";
+import type {
+  ContactOutcome,
+  PaymentPromiseStatus,
+  CreateContactLogInput,
+  UpdatePaymentPromiseInput,
+  FollowUpPaymentPromiseInput
+} from "../schemas/contactLog.js";
+
+export interface CampaignRecord {
+  id: string;
+  workspaceRef: string;
+  name: string;
+  agentTemplateId: string;
+  status: CampaignStatus;
+  startDate: Date;
+  endDate: Date | null;
+  daysOfWeek: number[];
+  startTime: string;
+  endTime: string;
+  maxAttemptsPerAccount: number;
+  maxAttemptsPerDay: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CampaignTriggerRecord {
+  id: string;
+  campaignId: string;
+  type:
+    | "MAX_ATTEMPTS_PER_DAY"
+    | "DNC_CHECK"
+    | "WRONG_NUMBER"
+    | "OPT_OUT"
+    | "PAYMENT_PROMISE"
+    | "INTENT_MET"
+    | "CALLBACK_REQUESTED";
+  config: Record<string, unknown>;
+}
+
+export interface CampaignAccountStateRecord {
+  campaignId: string;
+  portfolioAccountId: string;
+  attemptCount: number;
+  attemptsToday: number;
+  lastAttemptAt: Date | null;
+  suppressUntil: Date | null;
+}
+
+export interface AccountContactLogRecord {
+  id: string;
+  portfolioAccountId: string;
+  campaignId: string | null;
+  agentType: AgentType;
+  contactedAt: Date;
+  durationSeconds: number | null;
+  outcome: ContactOutcome;
+  notes: string | null;
+  debtAmountSnapshot: number | null;
+  aiSummary: string | null;
+  aiSentiment: string | null;
+  aiDebtReason: string | null;
+  aiResult: string | null;
+  aiNextStep: string | null;
+  intentMetadata: Record<string, unknown> | null;
+  channelData: Record<string, unknown> | null;
+  correctedEntryId: string | null;
+  agentTemplateId: string | null;
+  paymentPromiseId: string | null;
+  providerRef: string | null;
+  createdAt: Date;
+}
+
+export interface PaymentPromiseRecord {
+  id: string;
+  contactLogId: string;
+  portfolioAccountId: string;
+  amount: number | null;
+  dueDate: Date;
+  status: PaymentPromiseStatus;
+  notes: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CampaignClient {
+  agentTemplate: {
+    findFirst(args: {
+      where: { id: string; workspaceRef: string };
+    }): Promise<{ id: string; workspaceRef: string; type: AgentType } | null>;
+  };
+
+  whatsAppSenderNumber: {
+    findUnique(args: {
+      where: { id: string };
+    }): Promise<{ id: string; workspaceRef: string } | null>;
+  };
+
+  campaign: {
+    findMany(args: {
+      where: { workspaceRef: string; status?: CampaignStatus | { notIn: CampaignStatus[] } };
+      orderBy?: { createdAt: "asc" | "desc" };
+    }): Promise<CampaignRecord[]>;
+
+    findFirst(args: {
+      where: { id: string; workspaceRef?: string };
+    }): Promise<CampaignRecord | null>;
+
+    findFirstOrThrow(args: {
+      where: { id: string; workspaceRef: string };
+    }): Promise<CampaignRecord>;
+
+    create(args: { data: Record<string, unknown> }): Promise<CampaignRecord>;
+
+    update(args: { where: { id: string }; data: Record<string, unknown> }): Promise<CampaignRecord>;
+
+    delete(args: { where: { id: string } }): Promise<CampaignRecord>;
+  };
+
+  campaignPortfolio: {
+    createMany(args: {
+      data: Array<{ campaignId: string; portfolioId: string }>;
+    }): Promise<{ count: number }>;
+  };
+
+  campaignTrigger: {
+    findMany(args: { where: { campaignId: string } }): Promise<CampaignTriggerRecord[]>;
+  };
+
+  campaignAccountState: {
+    findUnique(args: {
+      where: {
+        campaignId_portfolioAccountId: { campaignId: string; portfolioAccountId: string };
+      };
+    }): Promise<CampaignAccountStateRecord | null>;
+
+    upsert(args: {
+      where: {
+        campaignId_portfolioAccountId: { campaignId: string; portfolioAccountId: string };
+      };
+      create: Record<string, unknown>;
+      update: Record<string, unknown>;
+    }): Promise<CampaignAccountStateRecord>;
+
+    count(args: { where: { campaignId: string; attemptCount?: { gt: number } } }): Promise<number>;
+  };
+
+  accountContactLog: {
+    create(args: { data: Record<string, unknown> }): Promise<AccountContactLogRecord>;
+    findFirst(args: { where: Record<string, unknown> }): Promise<AccountContactLogRecord | null>;
+    update(args: {
+      where: { id: string };
+      data: Record<string, unknown>;
+    }): Promise<AccountContactLogRecord>;
+    findMany(args: {
+      where: Record<string, unknown>;
+      orderBy?: { createdAt: "asc" | "desc" };
+      take?: number;
+      skip?: number;
+    }): Promise<AccountContactLogRecord[]>;
+  };
+
+  paymentPromise: {
+    create(args: { data: Record<string, unknown> }): Promise<PaymentPromiseRecord>;
+    findFirst(args: { where: Record<string, unknown> }): Promise<PaymentPromiseRecord | null>;
+    update(args: {
+      where: { id: string };
+      data: Record<string, unknown>;
+    }): Promise<PaymentPromiseRecord>;
+    updateMany(args: {
+      where: Record<string, unknown>;
+      data: { status: PaymentPromiseStatus };
+    }): Promise<{ count: number }>;
+    findMany(args: {
+      where: Record<string, unknown>;
+      orderBy?: { dueDate: "asc" | "desc" };
+    }): Promise<PaymentPromiseRecord[]>;
+  };
+
+  portfolioAccount: {
+    findFirst(args: {
+      where: { id: string };
+    }): Promise<{ id: string; portfolioId: string; outstandingBalance: number } | null>;
+
+    update(args: { where: { id: string }; data: Record<string, unknown> }): Promise<{ id: string }>;
+  };
+
+  portfolio: {
+    update(args: { where: { id: string }; data: Record<string, unknown> }): Promise<{ id: string }>;
+  };
+
+  $transaction<T>(fn: (tx: CampaignClient) => Promise<T>): Promise<T>;
+}
+
+export type {
+  CreateCampaignInput,
+  UpdateCampaignInput,
+  UpdateCampaignStatusInput,
+  DeleteCampaignInput,
+  CreateContactLogInput,
+  UpdatePaymentPromiseInput,
+  FollowUpPaymentPromiseInput
+};