@qcobro/common 1.11.3

package/src/schemas/agentTemplates.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+export const agentTypeSchema = z.enum([
+  "SMS",
+  "VOICE_PRERECORDED",
+  "VOICE_AI",
+  "EMAIL",
+  "WHATSAPP"
+]);
+export type AgentType = z.infer<typeof agentTypeSchema>;
+
+const baseFields = {
+  name: z.string().min(1).max(120)
+};
+
+/**
+ * Creating an agent template is a discriminated union on `type`: each channel
+ * carries its own config fields, never mixed across types. `fonosterAppName` is
+ * optional on voice types — the create function defaults it to the template name.
+ */
+export const createAgentTemplateSchema = z.discriminatedUnion("type", [
+  z.object({
+    ...baseFields,
+    type: z.literal("VOICE_AI"),
+    voice: z.string().min(1),
+    systemPrompt: z.string().min(1),
+    // Optional: a VOICE_AI agent may rely on its system prompt with no scripted opening line.
+    firstMessage: z.string().optional(),
+    language: z.string().min(1),
+    fonosterAppName: z.string().min(1).optional()
+  }),
+  z.object({
+    ...baseFields,
+    type: z.literal("VOICE_PRERECORDED"),
+    voice: z.string().min(1),
+    script: z.string().min(1),
+    language: z.string().min(1),
+    fonosterAppName: z.string().min(1).optional()
+  }),
+  z.object({
+    ...baseFields,
+    type: z.literal("SMS"),
+    messageBody: z.string().min(1),
+    senderId: z.string().min(1).optional()
+  }),
+  z.object({
+    ...baseFields,
+    type: z.literal("EMAIL"),
+    subject: z.string().min(1),
+    messageBody: z.string().min(1),
+    /** Autopilot decision brain: governs reply/ignore/resolve/escalate on each inbound reply. */
+    systemPrompt: z.string().min(1),
+    /** Per-agent cap on autopilot replies per collection attempt; falls back to the
+     * `resend.maxRepliesDefault` deployment default when omitted. */
+    maxReplies: z.number().int().nonnegative().optional()
+  }),
+  z.object({
+    ...baseFields,
+    type: z.literal("WHATSAPP"),
+    /** Meta template id the operator enters; QCobro resolves + previews the template from the WABA. */
+    templateId: z.string().min(1),
+    /** Resolved from `templateId` (read-only in the UI); the approved Meta template name to send. */
+    templateName: z.string().min(1),
+    /** Fetched template body (read-only preview); its `{{vars}}` are sent as named parameters. */
+    messageBody: z.string().min(1),
+    /** Smart-agent decision brain for replies after the customer responds (mirrors EMAIL). */
+    systemPrompt: z.string().min(1),
+    /** Per-agent cap on automated replies per gestión; falls back to the deployment default when omitted. */
+    maxReplies: z.number().int().nonnegative().optional()
+  })
+]);
+export type CreateAgentTemplateInput = z.infer<typeof createAgentTemplateSchema>;
+
+/**
+ * Updating an agent template: mutable base fields plus a loose `config` bag of
+ * type-specific fields applied to the stored child table. `type` is immutable —
+ * `.strict()` rejects any attempt to pass it (or other unknown keys).
+ */
+export const updateAgentTemplateSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1).max(120).optional(),
+    // `archived` toggles the template's archived state: true sets `archivedAt` to
+    // now, false clears it (restore). Templates have no status concept.
+    archived: z.boolean().optional(),
+    config: z.record(z.string(), z.unknown()).optional()
+  })
+  .strict();
+export type UpdateAgentTemplateInput = z.infer<typeof updateAgentTemplateSchema>;
+
+export const deleteAgentTemplateSchema = z.object({
+  id: z.string().min(1)
+});
+export type DeleteAgentTemplateInput = z.infer<typeof deleteAgentTemplateSchema>;
+
+/** Manually re-attempt the Fonoster sync for a voice template. */
+export const syncAgentTemplateSchema = z.object({
+  id: z.string().min(1)
+});
+export type SyncAgentTemplateInput = z.infer<typeof syncAgentTemplateSchema>;

package/src/schemas/apiKeys.test.ts

@@ -0,0 +1,38 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createApiKeySchema, apiKeyRefSchema } from "./apiKeys.js";
+
+describe("createApiKeySchema", () => {
+  it("defaults the role to admin with no expiry", () => {
+    const parsed = createApiKeySchema.parse({});
+    assert.equal(parsed.role, "WORKSPACE_ADMIN");
+    assert.equal(parsed.expiresAt, undefined);
+  });
+
+  it("accepts an admin role with a future expiry", () => {
+    const future = Date.now() + 86_400_000;
+    const parsed = createApiKeySchema.parse({ role: "WORKSPACE_ADMIN", expiresAt: future });
+    assert.equal(parsed.role, "WORKSPACE_ADMIN");
+    assert.equal(parsed.expiresAt, future);
+  });
+
+  it("rejects member/owner roles — Identity only issues admin keys", () => {
+    assert.equal(createApiKeySchema.safeParse({ role: "WORKSPACE_MEMBER" }).success, false);
+    assert.equal(createApiKeySchema.safeParse({ role: "WORKSPACE_OWNER" }).success, false);
+  });
+
+  it("rejects an expiry in the past", () => {
+    const result = createApiKeySchema.safeParse({ expiresAt: Date.now() - 1000 });
+    assert.equal(result.success, false);
+    if (!result.success) {
+      assert.match(result.error.issues[0].message, /future/);
+    }
+  });
+});
+
+describe("apiKeyRefSchema", () => {
+  it("requires a non-empty ref", () => {
+    assert.equal(apiKeyRefSchema.safeParse({ ref: "" }).success, false);
+    assert.equal(apiKeyRefSchema.safeParse({ ref: "ak_1" }).success, true);
+  });
+});

package/src/schemas/apiKeys.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+// API keys are workspace-scoped credentials for unattended, server-to-server
+// integrations (e.g. @qcobro/sdk's loginWithApiKey). Unlike member invites,
+// Fonoster Identity only permits WORKSPACE_ADMIN for an API key (its
+// createApiKeyRequestSchema is `z.enum([WORKSPACE_ADMIN])`), so there is no role
+// choice — every key is an admin-scoped key.
+export const apiKeyRoleEnum = z.enum(["WORKSPACE_ADMIN"]);
+export type ApiKeyRole = z.infer<typeof apiKeyRoleEnum>;
+
+export const createApiKeySchema = z.object({
+  role: apiKeyRoleEnum.default("WORKSPACE_ADMIN"),
+  // Optional expiry as epoch milliseconds; must be in the future when present.
+  // Identity stores no expiry when this is omitted (the key never expires).
+  expiresAt: z
+    .number()
+    .int()
+    .positive()
+    .refine((ms) => ms > Date.now(), { message: "expiresAt must be in the future" })
+    .optional()
+});
+export type CreateApiKeyInput = z.infer<typeof createApiKeySchema>;
+
+// Identifies a single key for regenerate/delete.
+export const apiKeyRefSchema = z.object({
+  ref: z.string().min(1)
+});
+export type ApiKeyRefInput = z.infer<typeof apiKeyRefSchema>;

package/src/schemas/auth.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+
+export const signUpSchema = z.object({
+  name: z.string().min(1).max(60),
+  email: z.email(),
+  password: z.string().min(8).max(128),
+  phone: z.string().max(20).optional(),
+  avatar: z.string().max(255).optional()
+});
+export type SignUpInput = z.infer<typeof signUpSchema>;
+
+export const loginSchema = z.object({
+  email: z.email(),
+  password: z.string().min(1),
+  twoFactorCode: z.string().optional()
+});
+export type LoginInput = z.infer<typeof loginSchema>;
+
+export const refreshTokenSchema = z.object({
+  refreshToken: z.string().min(1)
+});
+export type RefreshTokenInput = z.infer<typeof refreshTokenSchema>;
+
+// Exchange a workspace API key (accessKeyId + accessKeySecret) for tokens.
+// Used by unattended, server-to-server integrations (e.g. the SDK's
+// loginWithApiKey) that cannot perform an interactive credentials login.
+export const apiKeyLoginSchema = z.object({
+  accessKeyId: z.string().min(1),
+  accessKeySecret: z.string().min(1)
+});
+export type ApiKeyLoginInput = z.infer<typeof apiKeyLoginSchema>;
+
+export const sendResetPasswordCodeSchema = z.object({
+  username: z.email(),
+  resetPasswordUrl: z.string().url()
+});
+export type SendResetPasswordCodeInput = z.infer<typeof sendResetPasswordCodeSchema>;
+
+export const resetPasswordSchema = z.object({
+  username: z.email(),
+  password: z.string().min(8).max(128),
+  verificationCode: z.string().min(1)
+});
+export type ResetPasswordInput = z.infer<typeof resetPasswordSchema>;
+
+export const contactTypeEnum = z.enum(["EMAIL", "PHONE"]);
+export type ContactType = z.infer<typeof contactTypeEnum>;
+
+export const sendVerificationCodeSchema = z.object({
+  contactType: contactTypeEnum,
+  value: z.string().min(1)
+});
+export type SendVerificationCodeInput = z.infer<typeof sendVerificationCodeSchema>;
+
+export const verifyCodeSchema = z.object({
+  username: z.email(),
+  contactType: contactTypeEnum,
+  value: z.string().min(1),
+  verificationCode: z.string().min(1)
+});
+export type VerifyCodeInput = z.infer<typeof verifyCodeSchema>;
+
+// Identity currently supports a single OAuth2 provider.
+export const oauthProviderEnum = z.enum(["GITHUB"]);
+export type OauthProvider = z.infer<typeof oauthProviderEnum>;
+
+export const oauthSignInSchema = z.object({
+  provider: oauthProviderEnum,
+  code: z.string().min(1)
+});
+export type OauthSignInInput = z.infer<typeof oauthSignInSchema>;
+
+export const oauthSignUpSchema = z.object({
+  code: z.string().min(1)
+});
+export type OauthSignUpInput = z.infer<typeof oauthSignUpSchema>;

package/src/schemas/campaigns.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+
+export const campaignStatusSchema = z.enum(["PAUSED", "ACTIVE", "COMPLETED", "ARCHIVED"]);
+export type CampaignStatus = z.infer<typeof campaignStatusSchema>;
+
+/**
+ * Valid status transitions. A new campaign starts ACTIVE (dispatching immediately).
+ * COMPLETED is read-only. An ARCHIVED campaign can be restored to PAUSED — it never
+ * resumes dispatch without an explicit later activation. The UI offers only the
+ * transitions valid for the current status; the API enforces the same map.
+ */
+export const campaignStatusTransitions: Record<CampaignStatus, CampaignStatus[]> = {
+  PAUSED: ["ACTIVE", "ARCHIVED"],
+  ACTIVE: ["PAUSED", "COMPLETED", "ARCHIVED"],
+  COMPLETED: ["ARCHIVED"],
+  ARCHIVED: ["PAUSED"]
+};
+
+const timeOfDay = z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "must be HH:MM 24h time");
+
+/**
+ * Days of the week the campaign runs, as ISO weekday numbers (1 = Monday … 7 = Sunday).
+ * Any non-empty combination is allowed (e.g. Monday + Friday only).
+ */
+const daysOfWeek = z
+  .array(z.number().int().min(1, "weekday must be 1–7").max(7, "weekday must be 1–7"))
+  .min(1, "select at least one day")
+  .refine((days) => new Set(days).size === days.length, {
+    message: "days of week must be unique"
+  });
+
+export const createCampaignSchema = z
+  .object({
+    name: z.string().min(1).max(120),
+    agentTemplateId: z.string().min(1),
+    portfolioIds: z.array(z.string().min(1)).min(1),
+    /**
+     * The WhatsApp sender number to send from. Required when the agent template is
+     * `WHATSAPP` (quality rating and conversation continuity are per-number, so the
+     * sender identity is chosen per campaign, not pooled like voice/SMS) and must be
+     * omitted otherwise. The cross-field rule is enforced in `createCampaign` against the
+     * template's resolved type.
+     */
+    whatsAppSenderNumberId: z.string().min(1).optional(),
+    startDate: z.string().min(1),
+    endDate: z.string().min(1).optional(),
+    daysOfWeek,
+    startTime: timeOfDay,
+    endTime: timeOfDay,
+    maxAttemptsPerAccount: z.number().int().positive(),
+    maxAttemptsPerDay: z.number().int().positive()
+  })
+  .refine((c) => !c.endDate || new Date(c.endDate) > new Date(c.startDate), {
+    message: "endDate must be after startDate",
+    path: ["endDate"]
+  });
+export type CreateCampaignInput = z.infer<typeof createCampaignSchema>;
+
+/**
+ * Updating a campaign: mutable configuration only. `agentTemplateId` is immutable and
+ * `status` is changed through {@link updateCampaignStatusSchema} (guarded transitions),
+ * so `.strict()` rejects either being passed here, along with any unknown keys.
+ */
+export const updateCampaignSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1).max(120).optional(),
+    startDate: z.string().min(1).optional(),
+    endDate: z.string().min(1).optional(),
+    daysOfWeek: daysOfWeek.optional(),
+    startTime: timeOfDay.optional(),
+    endTime: timeOfDay.optional(),
+    maxAttemptsPerAccount: z.number().int().positive().optional(),
+    maxAttemptsPerDay: z.number().int().positive().optional()
+  })
+  .strict();
+export type UpdateCampaignInput = z.infer<typeof updateCampaignSchema>;
+
+export const updateCampaignStatusSchema = z.object({
+  id: z.string().min(1),
+  status: campaignStatusSchema
+});
+export type UpdateCampaignStatusInput = z.infer<typeof updateCampaignStatusSchema>;
+
+export const deleteCampaignSchema = z.object({
+  id: z.string().min(1)
+});
+export type DeleteCampaignInput = z.infer<typeof deleteCampaignSchema>;

package/src/schemas/contactLog.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { agentTypeSchema } from "./agentTemplates.js";
+
+export const contactOutcomeSchema = z.enum([
+  "DELIVERED",
+  "NOT_DELIVERED",
+  "NO_ANSWER",
+  "PAYMENT_PROMISE",
+  "PARTIAL_PAYMENT_AGREED",
+  "NEW_TERMS",
+  "CALLBACK_REQUESTED",
+  "DISPUTE_RAISED",
+  "INFORMATION_REQUEST",
+  "RESOLVED",
+  "PAID",
+  "WRONG_NUMBER",
+  "OPT_OUT",
+  "REFUSED",
+  "OTHER"
+]);
+export type ContactOutcome = z.infer<typeof contactOutcomeSchema>;
+
+export const aiSentimentSchema = z.enum(["POSITIVE", "NEUTRAL", "NEGATIVE", "HOSTILE"]);
+export type AiSentiment = z.infer<typeof aiSentimentSchema>;
+
+/**
+ * PaymentPromise is the only outcome QCobro tracks with a lifecycle, because a payment
+ * is the only commitment it can verify. DUE is derived (PENDING past its dueDate), not a
+ * stored status. There is intentionally no "broken" status — an unpaid promise stays on
+ * the worklist until an operator resolves it. EXPIRED is set when the account leaves its
+ * portfolio.
+ */
+export const paymentPromiseStatusSchema = z.enum(["PENDING", "MET", "EXPIRED", "CANCELLED"]);
+export type PaymentPromiseStatus = z.infer<typeof paymentPromiseStatusSchema>;
+
+export const createContactLogSchema = z.object({
+  portfolioAccountId: z.string().min(1),
+  campaignId: z.string().min(1).optional(),
+  /** Agent template used (campaign dispatch or ad-hoc follow-up). */
+  agentTemplateId: z.string().min(1).optional(),
+  /** Set when this gestión is an ad-hoc follow-up on a specific PaymentPromise. */
+  paymentPromiseId: z.string().min(1).optional(),
+  agentType: agentTypeSchema,
+  contactedAt: z.string().min(1),
+  durationSeconds: z.number().int().nonnegative().optional(),
+  outcome: contactOutcomeSchema,
+  notes: z.string().optional(),
+  debtAmountSnapshot: z.number().nonnegative().optional(),
+  aiSummary: z.string().optional(),
+  aiSentiment: aiSentimentSchema.optional(),
+  aiDebtReason: z.string().optional(),
+  aiResult: z.string().optional(),
+  aiNextStep: z.string().optional(),
+  intentMetadata: z.record(z.string(), z.unknown()).optional(),
+  channelData: z.record(z.string(), z.unknown()).optional(),
+  /**
+   * Provider call ref (voice) / message sid (sms) for the dispatch-time attempt.
+   * When present, `recordOutcome` upserts the gestión keyed by it (one row per
+   * attempt, enriched by the async callback) instead of inserting a duplicate.
+   */
+  providerRef: z.string().min(1).optional()
+});
+export type CreateContactLogInput = z.infer<typeof createContactLogSchema>;
+
+/**
+ * Input to reserve a campaign attempt before the provider call (the engine's
+ * at-most-once step). Increments the attempt counters; writes no gestión.
+ */
+export const reserveAttemptSchema = z.object({
+  campaignId: z.string().min(1).optional(),
+  portfolioAccountId: z.string().min(1),
+  /** When the attempt is being made (ISO). */
+  at: z.string().min(1)
+});
+export type ReserveAttemptInput = z.infer<typeof reserveAttemptSchema>;
+
+/**
+ * Operator resolution of a payment promise. A promise leaves PENDING only by explicit
+ * action: `MET` (paid — v1 is manual-only, no trusted payment signal) or `CANCELLED`.
+ * `EXPIRED` is set by the system when the account leaves its portfolio, not here.
+ */
+export const updatePaymentPromiseSchema = z.object({
+  id: z.string().min(1),
+  status: z.enum(["MET", "CANCELLED"])
+});
+export type UpdatePaymentPromiseInput = z.infer<typeof updatePaymentPromiseSchema>;
+
+/**
+ * Follow up on a payment promise with an ad-hoc agent dispatch (no campaign). Writes a
+ * gestión with `campaignId` null, the chosen `agentTemplateId`, and a link to the promise.
+ */
+export const followUpPaymentPromiseSchema = z.object({
+  paymentPromiseId: z.string().min(1),
+  agentTemplateId: z.string().min(1)
+});
+export type FollowUpPaymentPromiseInput = z.infer<typeof followUpPaymentPromiseSchema>;

package/src/schemas/dispatch.ts

@@ -0,0 +1,115 @@
+import { z } from "zod";
+
+/** The channels the dispatch layer triggers (subset of AgentType). */
+export const dispatchChannelSchema = z.enum([
+  "VOICE_AI",
+  "VOICE_PRERECORDED",
+  "SMS",
+  "EMAIL",
+  "WHATSAPP"
+]);
+
+/**
+ * A normalized dispatch request: a channel, a destination, the render context
+ * (the customer's account fields), and the raw template body fields for that
+ * channel. The dispatch function renders the bodies against `context` before
+ * sending, so callers pass raw templates — not pre-rendered strings.
+ */
+export const dispatchOutreachSchema = z
+  .object({
+    channel: dispatchChannelSchema,
+    /** Destination number (E.164). */
+    to: z.string().min(1),
+    /** Render context — the customer's account fields plus derived values. */
+    context: z.record(z.string(), z.unknown()).default({}),
+    /** Optional explicit caller-ID/sender; otherwise picked from the pool. */
+    from: z.string().min(1).optional(),
+    /** Voice: the provider application ref to drive the call. */
+    appRef: z.string().min(1).optional(),
+    /** Voz IA: opening line template (the autopilot may also open silently). */
+    firstMessage: z.string().optional(),
+    /** Voz pregrabada: the whole spoken script template (locuted via TTS). */
+    script: z.string().optional(),
+    /** SMS / EMAIL / WHATSAPP: message body template. For WHATSAPP this is the fetched
+     * template body whose `{{vars}}` are extracted and sent as named parameters. */
+    body: z.string().optional(),
+    /** EMAIL: subject line template. */
+    subject: z.string().optional(),
+    /** WHATSAPP: Meta-approved template name to send. */
+    templateName: z.string().optional(),
+    /** WHATSAPP: Meta template-send language code (sourced from the workspace, e.g. `es_DO`). */
+    languageCode: z.string().optional()
+  })
+  .superRefine((value, ctx) => {
+    if (value.channel === "SMS" && (value.body ?? "").length === 0) {
+      ctx.addIssue({ code: "custom", path: ["body"], message: "SMS requires a message body" });
+    }
+    if (value.channel === "EMAIL") {
+      if ((value.subject ?? "").length === 0) {
+        ctx.addIssue({ code: "custom", path: ["subject"], message: "Email requires a subject" });
+      }
+      if ((value.body ?? "").length === 0) {
+        ctx.addIssue({ code: "custom", path: ["body"], message: "Email requires a body" });
+      }
+    }
+    if (value.channel === "WHATSAPP") {
+      if ((value.templateName ?? "").length === 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["templateName"],
+          message: "WhatsApp requires a templateName"
+        });
+      }
+      if ((value.languageCode ?? "").length === 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["languageCode"],
+          message: "WhatsApp requires a languageCode"
+        });
+      }
+      if ((value.body ?? "").length === 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["body"],
+          message: "WhatsApp requires a template body for parameter extraction"
+        });
+      }
+    }
+    // Voice dispatch needs the synced application ref. Neither voice channel requires a
+    // `firstMessage`: VOICE_AI may open silently (the autopilot places the call and waits
+    // for the customer to speak first), and pre-recorded has no first message at all.
+    // EMAIL and SMS are not voice and need no appRef.
+    const isVoice = value.channel === "VOICE_AI" || value.channel === "VOICE_PRERECORDED";
+    if (isVoice && !value.appRef) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["appRef"],
+        message: "Voice dispatch requires appRef"
+      });
+    }
+  });
+
+export type DispatchOutreachInput = z.infer<typeof dispatchOutreachSchema>;
+
+/**
+ * Input for the manual "Contactar manualmente" procedure: which customer and which
+ * campaign. A manual contact runs the campaign's agent against this one customer, so
+ * the campaign (required) determines the agent/channel; the server resolves these to
+ * a {@link dispatchOutreachSchema} request.
+ */
+export const manualOutreachSchema = z.object({
+  portfolioAccountId: z.string().min(1),
+  // Manual outreach is agent-based, not campaign-based: it dispatches the chosen agent
+  // template ad-hoc and records a campaign-less gestión (no CampaignAccountState).
+  agentTemplateId: z.string().min(1),
+  /** Operator override for the email subject (rendered, replaces template value). */
+  subject: z.string().optional(),
+  /** Operator override for the message body — SMS or EMAIL (rendered). */
+  body: z.string().optional(),
+  /** Operator override for the Voz IA opening line (rendered). */
+  firstMessage: z.string().optional(),
+  /** Operator override for the Voz pregrabada spoken script (rendered). */
+  script: z.string().optional()
+});
+
+export type ManualOutreachInput = z.infer<typeof manualOutreachSchema>;

package/src/schemas/email.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+/**
+ * The structured decision the EMAIL autopilot returns for an inbound reply. Validated so a
+ * model can't drive the loop with malformed output. `outcome` mirrors the contact-log
+ * outcomes; `objective` carries promise details when the reply implies one.
+ */
+export const emailAutopilotDecisionSchema = z.object({
+  action: z.enum(["reply", "ignore", "resolve", "escalate"]),
+  replyBody: z.string().optional(),
+  outcome: z.string().optional(),
+  objective: z
+    .object({
+      type: z.string(),
+      amount: z.number().optional(),
+      dueDate: z.string().optional(),
+      note: z.string().optional()
+    })
+    .nullish()
+});
+
+/**
+ * Normalized inbound email from the provider webhook. The provider payload is mapped to
+ * this before ingestion so the function stays provider-agnostic.
+ */
+export const inboundEmailSchema = z.object({
+  from: z.string().min(1),
+  to: z.array(z.string()).default([]),
+  subject: z.string().optional(),
+  text: z.string().default(""),
+  messageId: z.string().optional(),
+  inReplyTo: z.string().optional(),
+  references: z.array(z.string()).optional(),
+  headers: z.record(z.string(), z.string()).optional()
+});
+
+export type InboundEmailInput = z.infer<typeof inboundEmailSchema>;

package/src/schemas/index.ts

@@ -0,0 +1,15 @@
+export * from "./auth.js";
+export * from "./workspaces.js";
+export * from "./apiKeys.js";
+export * from "./users.js";
+export * from "./portfolios.js";
+export * from "./workspaceSettings.js";
+export * from "./userSettings.js";
+export * from "./agentTemplates.js";
+export * from "./campaigns.js";
+export * from "./contactLog.js";
+export * from "./dispatch.js";
+export * from "./email.js";
+export * from "./whatsApp.js";
+export * from "./voiceEvent.js";
+export * from "./insight.js";

package/src/schemas/insight.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { aiSentimentSchema } from "./contactLog.js";
+
+/**
+ * The structured analysis an LLM must return for a gestión transcript. Mirrors the
+ * `ai*` fields on `AccountContactLog`; text fields are written in the call's language,
+ * `aiSentiment` is always one of the fixed enum values.
+ */
+export const gestionInsightSchema = z.object({
+  aiSummary: z.string().min(1),
+  aiSentiment: aiSentimentSchema,
+  aiDebtReason: z.string().min(1),
+  aiResult: z.string().min(1),
+  aiNextStep: z.string().min(1)
+});
+export type GestionInsight = z.infer<typeof gestionInsightSchema>;
+
+/** Input to the generate-insight operation — the gestión (contact-log) id. */
+export const generateInsightInputSchema = z.object({ id: z.string().min(1) });
+export type GenerateInsightInput = z.infer<typeof generateInsightInputSchema>;

package/src/schemas/portfolios.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+
+export const createPortfolioSchema = z.object({
+  name: z.string().min(1).max(120),
+  clientId: z.string().min(1).max(120)
+});
+export type CreatePortfolioInput = z.infer<typeof createPortfolioSchema>;
+
+export const updatePortfolioSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1).max(120).optional(),
+  // `archived` toggles the portfolio's archived state: true sets `archivedAt` to
+  // now, false clears it (restore). There is no separate status concept.
+  archived: z.boolean().optional()
+});
+export type UpdatePortfolioInput = z.infer<typeof updatePortfolioSchema>;
+
+export const deletePortfolioSchema = z.object({
+  id: z.string().min(1)
+});
+export type DeletePortfolioInput = z.infer<typeof deletePortfolioSchema>;
+
+export const accountRowSchema = z.object({
+  externalId: z.string().min(1),
+  fullName: z.string().min(1),
+  phone: z.string().optional(),
+  email: z.string().email().optional(),
+  preferredLanguage: z.string().optional(),
+  bestTimeToCall: z.string().optional(),
+  customerSegment: z.string().optional(),
+  principalAmount: z.number().nonnegative().default(0),
+  termsAmount: z.number().nonnegative().default(0),
+  termsFrequency: z.string().optional(),
+  termsLength: z.number().int().nonnegative().default(0),
+  outstandingBalance: z.number().nonnegative(),
+  daysPastDue: z.number().int().nonnegative().default(0),
+  missedInstallments: z.number().int().nonnegative().default(0),
+  lastPaymentDate: z.string().optional(),
+  lastPaymentAmount: z.number().nonnegative().optional(),
+  negotiationOptions: z.string().optional()
+});
+export type AccountRowInput = z.infer<typeof accountRowSchema>;
+
+export const syncAccountsInputSchema = z.object({
+  portfolioId: z.string().min(1),
+  mode: z.enum(["APPEND_ONLY", "UPDATE_EXISTING", "REPLACE"]),
+  rows: z.array(accountRowSchema).min(1)
+});
+export type SyncAccountsInput = z.infer<typeof syncAccountsInputSchema>;