@qcobro/common 1.11.3

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.11.0](https://github.com/fonoster/qcobro/compare/v1.10.0...v1.11.0) (2026-06-30)
+
+### Features
+
+- **whatsapp:** inbound autopilot — reply, opt-out, payment promise (§7.3, §7.4, §9.4) ([ef37a91](https://github.com/fonoster/qcobro/commit/ef37a9109909cb9e86ff3a787b5af06ed199fd78))
+- **whatsapp:** inbound event processing — opt-out suppression + quality-rating (§7.2, §9.3) ([974a9e3](https://github.com/fonoster/qcobro/commit/974a9e35d549e1baf6386ac6bcec40297c8ae703))
+- **whatsapp:** wire engine tick, webhook handshake, and unit tests (§6.2, §7.1, §9.1–9.2) ([a46bb1f](https://github.com/fonoster/qcobro/commit/a46bb1fd0f786e5856281da48d07f2f3249081e7))
+
+# [1.10.0](https://github.com/fonoster/qcobro/compare/v1.9.0...v1.10.0) (2026-06-30)
+
+### Features
+
+- **whatsapp:** add WhatsApp channel server foundation (§2–§6.1) ([51211f3](https://github.com/fonoster/qcobro/commit/51211f3b8af1cd7fb45e0b2ded40262915606548)), closes [#5](https://github.com/fonoster/qcobro/issues/5)
+
+# [1.9.0](https://github.com/fonoster/qcobro/compare/v1.8.0...v1.9.0) (2026-06-29)
+
+### Bug Fixes
+
+- **api:** stop resending Voz IA system prompt as call metadata ([0d66d18](https://github.com/fonoster/qcobro/commit/0d66d18b34d0f353f02d96599d8784f0f372a547))
+
+### Features
+
+- **common:** add isDue outreach variable and document template variables ([ed7a511](https://github.com/fonoster/qcobro/commit/ed7a51161b758d2337055028f7adf52f22f7ae56))
+
+## [1.5.4](https://github.com/fonoster/qcobro/compare/v1.5.3...v1.5.4) (2026-06-28)
+
+### Bug Fixes
+
+- **e2e:** supply fonoster voices in CI config; enable campaigns + console specs ([2ff90ab](https://github.com/fonoster/qcobro/commit/2ff90aba4da71f7e6d902aacff753ea5a9411950))
+
+# [1.5.0](https://github.com/fonoster/qcobro/compare/v1.4.1...v1.5.0) (2026-06-28)
+
+### Features
+
+- **profile-language:** per-user language preference + i18n hygiene sweep ([dbddb9c](https://github.com/fonoster/qcobro/commit/dbddb9c7915103afc339ec9d695b27c97d7634ce))
+
+# [1.4.0](https://github.com/fonoster/qcobro/compare/v1.3.2...v1.4.0) (2026-06-28)
+
+### Features
+
+- **workspace-settings:** collect currency + timezone at workspace creation ([682ae8f](https://github.com/fonoster/qcobro/commit/682ae8f5fcf2045564c0dd5ac0e8f38fa736ed4a))
+
+## [1.3.2](https://github.com/fonoster/qcobro/compare/v1.3.1...v1.3.2) (2026-06-28)
+
+**Note:** Version bump only for package @qcobro/common
+
+## [1.3.1](https://github.com/fonoster/qcobro/compare/v1.3.0...v1.3.1) (2026-06-28)
+
+### Bug Fixes
+
+- **timezone:** contact-log REST uses workspace tz; default is a constant ([1b86419](https://github.com/fonoster/qcobro/commit/1b86419fc98722d0c1174ce9f1bdf19848b35dd5))
+
+# [1.3.0](https://github.com/fonoster/qcobro/compare/v1.2.3...v1.3.0) (2026-06-28)
+
+### Features
+
+- **workspace-settings:** per-workspace currency + timezone (off Identity) ([c1516a3](https://github.com/fonoster/qcobro/commit/c1516a3d306e2b2a906d9ae476fb27f23887d5ae))
+
+# [1.2.0](https://github.com/fonoster/qcobro/compare/v1.1.4...v1.2.0) (2026-06-28)
+
+### Features
+
+- **payment-promises:** outcomes + PaymentPromise worklist, agent-based outreach ([6c620f8](https://github.com/fonoster/qcobro/commit/6c620f8a80c65a7178b0716b825a7d4ebb4077f7))
+
+# 1.1.0 (2026-06-28)
+
+### Bug Fixes
+
+- **channel-dispatch:** allow empty firstMessage for VOICE_AI; non-destructive engine test ([71e17a6](https://github.com/fonoster/qcobro/commit/71e17a6a32d8353e9d428e5763e937408df066df))
+- **channel-dispatch:** pre-recorded voice has no firstMessage either ([ebc8e90](https://github.com/fonoster/qcobro/commit/ebc8e9049b765388e8e0e7505dccef22d4dde875))
+- **email:** hydrate inbound body from received-emails api; strip quoted history ([ddcbdb1](https://github.com/fonoster/qcobro/commit/ddcbdb170953cb9428d92a0cc385d5b83eb43cfd))
+- **voice:** provision AUTOPILOT apps with required conversation settings ([c92a8aa](https://github.com/fonoster/qcobro/commit/c92a8aa52c30e2c8f3f78145dec17a99b72282cd))
+- **webapp:** drop unused fromName/fromEmail from EMAIL agent form; add Resend status badge ([625c3c8](https://github.com/fonoster/qcobro/commit/625c3c8300d275f9f1982353bdf87112a9f03fa2))
+- **workspaces:** wire invite acceptance to Identity HTTP bridge ([5b9fc40](https://github.com/fonoster/qcobro/commit/5b9fc40c57cd8d692d2711c1483bbd158e01aa54))
+
+### Features
+
+- **agent-templates:** per-channel agents, voices-from-config, Fonoster Voz IA sync ([6a8065d](https://github.com/fonoster/qcobro/commit/6a8065d27f8954aa5c5faf7ab34553dccefda5fc))
+- **ai-insights:** transcript-based AI analysis + Voz IA wiring ([4ed7d2e](https://github.com/fonoster/qcobro/commit/4ed7d2e0faf2af9d8ff7966c687c346183b05184))
+- **api-keys:** workspace API key management ([30dd25d](https://github.com/fonoster/qcobro/commit/30dd25d52e1083afb66c7bd323b10d0ac193425a))
+- **api,webapp:** delete-workspace — ownerProcedure and WorkspaceSettings UI ([2542443](https://github.com/fonoster/qcobro/commit/2542443d6cdf4c9a6b2587e3380de9ea3e9f8263))
+- **api,webapp:** profile-management — profile router and Profile page ([5850ec6](https://github.com/fonoster/qcobro/commit/5850ec6e777a987c559f6ab94a15725bc998820f))
+- **api:** add contact-verification and OAuth auth procedures ([b6b70c3](https://github.com/fonoster/qcobro/commit/b6b70c35dd8063ccbdc6e429ded21aa96154928d))
+- **api:** complete auth-and-workspaces change — password reset, resend invite, accept-invite UI ([09c557b](https://github.com/fonoster/qcobro/commit/09c557b00dfee7de725e45cfc5f6e5f61e91f44d))
+- **apiserver:** add auth router (signup, login, refresh, logout) ([9fd50e0](https://github.com/fonoster/qcobro/commit/9fd50e0a32c92ca6bcdf0c053f7050f16921b42b))
+- **apiserver:** add workspace create/list/get (Group 5 core) ([99de39c](https://github.com/fonoster/qcobro/commit/99de39c29c692fd2760053c3bb7f196e11c1a05b))
+- **campaigns-engine:** propose change + config/contracts (group 1) ([6ffd70d](https://github.com/fonoster/qcobro/commit/6ffd70df34cf0a3f33060243eadb1b7460e440eb))
+- **campaigns-engine:** wiring + cleanup (groups 7/9) ([828056d](https://github.com/fonoster/qcobro/commit/828056d091f419bafc5d675a6f0bd92e67bf9eb9))
+- **campaigns:** campaigns-core — lifecycle, days-of-week, edit modal, specs synced ([d1e75cd](https://github.com/fonoster/qcobro/commit/d1e75cd9e065a1556811ee0abf94c4e2ab569e20))
+- **campaigns:** checkpoint campaigns-core WIP before refinement ([2b3e339](https://github.com/fonoster/qcobro/commit/2b3e339913ab4de37152ed04e5aaf0d90fb247c4))
+- **channel-dispatch:** outreach trigger layer (Fonoster voice + Twilio SMS) ([56a4b9e](https://github.com/fonoster/qcobro/commit/56a4b9e4c7c9267f0bfbad42b4b37fff74b6b8fb))
+- **common:** add validated-function utilities and conventions guide ([a60bab9](https://github.com/fonoster/qcobro/commit/a60bab99affd9290602512e5921632c4a1f9f70f))
+- **console:** config-driven announcement banner; flag unimplemented data ([01d8977](https://github.com/fonoster/qcobro/commit/01d89775fa547766521c5be5c15ba429bf5a655c))
+- **console:** refinement + cleanup pass ([78dc3e5](https://github.com/fonoster/qcobro/commit/78dc3e58f2a4eaede4bf10a9d2a551b3c426d9ee))
+- **email-channel:** inbound autopilot — webhook, decision loop, reply cap ([67b6a85](https://github.com/fonoster/qcobro/commit/67b6a8515e75f8ca178293755bffa540a2a3d139))
+- **email-channel:** outbound email + engine integration (Resend) ([391d3d0](https://github.com/fonoster/qcobro/commit/391d3d0caf3440d4f41568d0c48ec37c7ec76d36))
+- **email-channel:** spec + contracts for bidirectional email (Resend autopilot) ([6c2461c](https://github.com/fonoster/qcobro/commit/6c2461ced535cc1b1eb4a7f9eb2a3dcd989dbbe5))
+- **email:** bidirectional email channel end-to-end ([b49a442](https://github.com/fonoster/qcobro/commit/b49a442104841023f3507a6c33cf85dfe689bf12))
+- **gestiones:** add voz IA channel webhook and rich detail panel ([824671f](https://github.com/fonoster/qcobro/commit/824671f0da22dcc9ec16a610618925f96e28d2c8))
+- identity now from the published fonoster identity mod ([9a6eaea](https://github.com/fonoster/qcobro/commit/9a6eaeaed20f51ea7a4846fe116735aeecdcc6e5))
+- **manual-outreach:** carteras reach-out modal + campaign-derived dispatch ([367db2d](https://github.com/fonoster/qcobro/commit/367db2d370c893317042b76239acb7d39c3e69f7))
+- **portfolios:** portfolio management, status enums, currency, and row actions ([6b6bac9](https://github.com/fonoster/qcobro/commit/6b6bac914d85f5140da0abfaa84bd682686364e3))
+- scaffold Qcobro app monorepo ([d5a7507](https://github.com/fonoster/qcobro/commit/d5a7507016d27cc2f76ece0c6aaeff33186d8da0))
+- scaffold spec-driven monorepo foundation ([1a17d89](https://github.com/fonoster/qcobro/commit/1a17d89dffe686032caafe1c09be50053286e48b))
+- **sdk:** add @qcobro/sdk with portfolios, API-key auth, and auto-refresh ([324405e](https://github.com/fonoster/qcobro/commit/324405e9922bf70ccd57088122098c6c2d8de2e7))
+- **voice:** embedded Fonoster VoiceServer for pre-recorded (external) agents ([00e581e](https://github.com/fonoster/qcobro/commit/00e581e78c503509ad7af4cade0b29b226a78a60))
+- **voice:** make pre-recorded audio permanent and spec the events-hook ([8b03fdb](https://github.com/fonoster/qcobro/commit/8b03fdbbbd84cc4233578ae94e37a9a364171584))
+- **voice:** pre-recorded via shared external app ref + Say playback ([e156292](https://github.com/fonoster/qcobro/commit/e15629223914a1141025a1804aa184222c3f244e))
+- **webapp:** implement Pencil UI — login brand panel, workspace picker, sidebar redesign ([e34ef12](https://github.com/fonoster/qcobro/commit/e34ef123b68941a007304316f3c0135f50a69cbd))
+- **workspaces:** rename + console navigation (workspace-management) ([46acf86](https://github.com/fonoster/qcobro/commit/46acf86d32a09d3cf4474818f4950e35776bef01))

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@qcobro/common",
+  "version": "1.11.3",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -b --force",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "handlebars": "^4.7.9",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,19 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ttsProductRefForVoice, type VoiceCatalogEntry } from "./config.js";
+
+const voices: VoiceCatalogEntry[] = [
+  { id: "v-eleven", name: "Sofía", language: "es", gender: "female", provider: "elevenlabs" },
+  { id: "v-google", name: "Andrés", language: "es", gender: "male", provider: "google" }
+];
+
+describe("ttsProductRefForVoice", () => {
+  it("derives the TTS product ref from the voice's provider", () => {
+    assert.equal(ttsProductRefForVoice("v-eleven", voices), "tts.elevenlabs");
+    assert.equal(ttsProductRefForVoice("v-google", voices), "tts.google");
+  });
+
+  it("falls back to tts.elevenlabs for an unknown voice", () => {
+    assert.equal(ttsProductRefForVoice("missing", voices), "tts.elevenlabs");
+  });
+});

package/src/config.ts

@@ -0,0 +1,358 @@
+import { z } from "zod";
+
+/**
+ * QCobro service configuration — the shape of `qcobro.json`.
+ *
+ * This module exports the schema/type only (no filesystem access) so it stays
+ * safe to import from the browser. Server packages load the file and call
+ * `qcobroConfigSchema.parse(...)`.
+ *
+ * Identity runs as an external Fonoster Identity service; QCobro only needs the
+ * endpoint to reach it. All Identity service configuration (database, keys,
+ * issuer, SMTP, …) lives with that service, not here.
+ */
+export const identityConfigSchema = z.object({
+  /** host:port the apiserver uses to reach the external Identity gRPC service. */
+  endpoint: z.string().default("localhost:50051"),
+  /** Base URL of the Identity HTTP bridge (accepts invite tokens). */
+  httpBridgeUrl: z.string().default("http://localhost:9110")
+});
+
+/**
+ * A selectable voice in the deployment's catalog. Voice agent templates pick a
+ * voice by `id` (the provider's voice identifier, e.g. an ElevenLabs voice id);
+ * the console renders the picker from this catalog rather than free text.
+ */
+export const voiceCatalogEntrySchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  language: z.string().min(1),
+  gender: z.enum(["female", "male"]),
+  provider: z.string().min(1).default("elevenlabs")
+});
+
+export type VoiceCatalogEntry = z.infer<typeof voiceCatalogEntrySchema>;
+
+/**
+ * Fonoster connection + Autopilot defaults. VOICE_AI agent templates are synced to
+ * Fonoster as AUTOPILOT applications; the apiserver authenticates with a workspace
+ * access key + API key/secret. Optional — when absent, voice templates save locally
+ * and stay unsynced (the console offers a manual re-sync).
+ */
+export const fonosterConfigSchema = z
+  .object({
+    accessKeyId: z.string().min(1),
+    apiKey: z.string().min(1),
+    apiSecret: z.string().min(1),
+    /** Optional override for the Fonoster API endpoint (host:port). */
+    endpoint: z.string().optional(),
+    /** Default products/model used when building the Autopilot application. The
+     * TTS product is NOT set here — it is derived per voice (see `voices`) since
+     * both Voz IA and pre-recorded voice use it. */
+    autopilot: z
+      .object({
+        sttProductRef: z.string().default("stt.deepgram"),
+        sttModel: z.string().default("nova-3"),
+        llmProductRef: z.string().default("llm.google"),
+        llmProvider: z.string().default("google"),
+        llmModel: z.string().default("gemini-2.0-flash"),
+        maxTokens: z.number().default(300),
+        temperature: z.number().default(0)
+      })
+      .default({
+        sttProductRef: "stt.deepgram",
+        sttModel: "nova-3",
+        llmProductRef: "llm.google",
+        llmProvider: "google",
+        llmModel: "gemini-2.0-flash",
+        maxTokens: 300,
+        temperature: 0
+      }),
+    /**
+     * Selectable voice catalog for voice agent templates (Voz IA + pre-recorded).
+     * Voices are Fonoster-only, so they live here. Seeded with three Spanish
+     * voices; deployments override in `qcobro.json`. The TTS product ref is
+     * derived from each voice's `provider` (see {@link ttsProductRefForVoice}).
+     */
+    // Shape only — the actual catalog is supplied by qcobro.json (see config/*.json),
+    // not defaulted in the schema.
+    voices: z.array(voiceCatalogEntrySchema).optional(),
+    /**
+     * Caller-ID numbers outbound voice dispatch rotates through. Use the format the
+     * carrier expects — Fonoster passes the number through as given, so whether a
+     * leading "+" is required depends on the carrier (here, no "+", e.g.
+     * `18297340812`). Empty by default — voice dispatch fails clearly until set.
+     */
+    numbers: z.array(z.string().min(1)).default([]),
+    /**
+     * The Fonoster EXTERNAL application ref used for ALL pre-recorded voice
+     * dispatch (one shared app pointing at the embedded VoiceServer). The
+     * per-customer script is passed as call metadata; this ref is deployment-wide,
+     * not per agent. Voz IA uses each template's own AUTOPILOT app ref instead.
+     */
+    prerecordedAppRef: z.string().min(1).optional(),
+    /**
+     * Externally reachable base URL of the apiserver for Fonoster callbacks (e.g. an
+     * ngrok URL). When set, syncing a Voz IA agent registers the autopilot events-hook
+     * at `${webhookBaseUrl}/api/voice/events` so conversation events return as gestiones.
+     */
+    webhookBaseUrl: z.string().url().optional(),
+    /**
+     * Campaigns-engine pacing: the maximum number of voice calls the engine will
+     * originate per minute, deployment-wide (the caller-ID pool is shared by all
+     * workspaces). A conservative value bounds in-flight concurrency given the pool
+     * size and typical call duration. Reserve `0` to pause voice dispatch.
+     */
+    maxCallsPerMinute: z.number().int().nonnegative().default(6)
+  })
+  .optional();
+
+export type FonosterConfig = z.infer<typeof fonosterConfigSchema>;
+
+/**
+ * Derives the TTS product ref for a voice from its provider (e.g. an `elevenlabs`
+ * voice → `tts.elevenlabs`). Used by both Voz IA (Autopilot) and pre-recorded
+ * voice. Falls back to `tts.elevenlabs` when the voice isn't in the catalog.
+ */
+export function ttsProductRefForVoice(voiceId: string, voices: VoiceCatalogEntry[]): string {
+  const voice = voices.find((v) => v.id === voiceId);
+  return voice ? `tts.${voice.provider}` : "tts.elevenlabs";
+}
+
+/**
+ * Twilio connection for SMS dispatch. Optional — when absent, SMS dispatch fails
+ * with a clear error. `fromNumbers` (E.164) are rotated through per message.
+ */
+export const twilioConfigSchema = z
+  .object({
+    accountSid: z.string().min(1),
+    authToken: z.string().min(1),
+    fromNumbers: z.array(z.string().min(1)).default([]),
+    /**
+     * Campaigns-engine pacing: the maximum number of SMS messages the engine will
+     * send per minute, deployment-wide (the sender pool is shared by all workspaces).
+     * Reserve `0` to pause SMS dispatch.
+     */
+    maxSmsPerMinute: z.number().int().nonnegative().default(60)
+  })
+  .optional();
+
+export type TwilioConfig = z.infer<typeof twilioConfigSchema>;
+
+/**
+ * Resend connection for the bidirectional EMAIL channel. Optional — when absent, EMAIL
+ * dispatch is inert (the engine reports EMAIL campaigns as not-configured) and the inbound
+ * webhook rejects everything. Outbound uses `apiKey` + `fromEmail`/`fromName`; inbound
+ * replies arrive at `reply+<token>@<inboundDomain>` and are verified with
+ * `inboundSigningSecret`. The per-attempt reply cap defaults to `maxRepliesDefault`.
+ */
+export const resendConfigSchema = z
+  .object({
+    apiKey: z.string().min(1),
+    fromEmail: z.string().email(),
+    fromName: z.string().min(1).optional(),
+    /** Domain the per-attempt reply-to token addresses are minted on (inbound). */
+    inboundDomain: z.string().min(1),
+    /** Shared secret used to verify inbound webhook signatures. */
+    inboundSigningSecret: z.string().min(1).optional(),
+    /**
+     * Campaigns-engine pacing: the maximum number of emails the engine will send per
+     * minute, deployment-wide. Reserve `0` to pause email dispatch.
+     */
+    maxEmailsPerMinute: z.number().int().nonnegative().default(60),
+    /**
+     * Default cap on autopilot replies per collection attempt (per gestión) when an EMAIL
+     * agent does not set its own `maxReplies`. Bounds the back-and-forth so a debtor can't
+     * keep the AI talking indefinitely.
+     */
+    maxRepliesDefault: z.number().int().nonnegative().default(3)
+  })
+  .optional();
+
+export type ResendConfig = z.infer<typeof resendConfigSchema>;
+
+/**
+ * AI-insight generation. Produces a gestión's structured analysis from its
+ * conversation transcript. Optional — when absent or `enabled:false`, no LLM is
+ * called and gestiones keep their unanalyzed / generic-insight state.
+ *
+ * Providers mirror the Fonoster autopilot / Mikro vendor set, reached over each
+ * vendor's REST API (no SDK dependency). `mock` is an offline provider that
+ * synthesizes a deterministic analysis from the transcript — for local dev,
+ * demos, and tests, with no key and no network/cost.
+ */
+export const aiProviderSchema = z.enum(["mock", "google", "openai", "anthropic"]);
+export type AiProvider = z.infer<typeof aiProviderSchema>;
+
+/** Valid models per provider; used to reject misconfiguration at load. */
+export const AI_MODELS: Record<AiProvider, string[]> = {
+  mock: ["mock"],
+  google: ["gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-2.5-pro", "gemini-2.0-flash"],
+  openai: ["gpt-4o", "gpt-4o-mini", "gpt-4.1"],
+  anthropic: ["claude-3-5-sonnet-latest", "claude-3-5-haiku-latest"]
+};
+
+export const aiConfigSchema = z
+  .object({
+    enabled: z.boolean().default(false),
+    provider: aiProviderSchema.default("mock"),
+    apiKey: z.string().optional(),
+    model: z.string().default("gemini-2.5-flash"),
+    temperature: z.number().min(0).max(2).default(0),
+    maxTokens: z.number().int().positive().default(600),
+    /** When the analysis is produced. `onDemand` = on first detail open (then
+     * cached); `onIngestion` = when the transcript is first stored. */
+    generation: z.enum(["onDemand", "onIngestion"]).default("onDemand")
+  })
+  .superRefine((cfg, ctx) => {
+    if (!AI_MODELS[cfg.provider].includes(cfg.model)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["model"],
+        message: `Invalid model "${cfg.model}" for provider "${cfg.provider}". Valid: ${AI_MODELS[cfg.provider].join(", ")}`
+      });
+    }
+    // apiKey is optional here: it may be omitted and supplied via an environment
+    // variable instead (the adapter resolves it and errors clearly if none is found
+    // at call time).
+  })
+  .optional();
+
+export type AiConfig = z.infer<typeof aiConfigSchema>;
+
+/**
+ * Text-to-speech for previewing pre-recorded agent scripts in the console (the
+ * Pre-grabada gestión detail plays the script as audio). Optional — when absent, the
+ * apiKey falls back to `ELEVENLABS_API_KEY`, and if no key resolves the player is simply
+ * unavailable. Voices come from `fonoster.voices`.
+ */
+export const ttsConfigSchema = z
+  .object({
+    provider: z.literal("elevenlabs").default("elevenlabs"),
+    apiKey: z.string().optional(),
+    model: z.string().default("eleven_multilingual_v2")
+  })
+  .optional();
+
+export type TtsConfig = z.infer<typeof ttsConfigSchema>;
+
+/**
+ * A piece of user-facing copy that may be localized. Either a single string
+ * (same text for every language) or a map of language code → string
+ * (e.g. `{ "en": "Early access", "es": "Acceso temprano" }`). The console
+ * resolves it against the active UI language, falling back to any available value.
+ */
+export const localizedStringSchema = z.union([
+  z.string().min(1),
+  z.record(z.string(), z.string().min(1))
+]);
+export type LocalizedString = z.infer<typeof localizedStringSchema>;
+
+/**
+ * A deployment-wide announcement rendered as a dismissible banner across the
+ * console (and the workspace picker). Optional — when absent, no banner shows.
+ *
+ * `variant` selects the color scheme and `icon` the leading glyph, so a
+ * deployment can style it as a neutral announcement, an amber alert, etc.
+ * `title` and `message` are localizable (see {@link localizedStringSchema}).
+ */
+export const announcementConfigSchema = z
+  .object({
+    enabled: z.boolean().default(true),
+    /** Color scheme: `announcement` (blue), `alert` (amber), `success` (green), `danger` (red). */
+    variant: z.enum(["announcement", "alert", "success", "danger"]).default("announcement"),
+    /** Leading icon from a curated set. */
+    icon: z
+      .enum(["megaphone", "info", "alert-triangle", "sparkles", "rocket", "bell"])
+      .default("megaphone"),
+    /** Whether the user can dismiss the banner. */
+    dismissible: z.boolean().default(true),
+    title: localizedStringSchema.optional(),
+    message: localizedStringSchema
+  })
+  .optional();
+
+export type AnnouncementConfig = z.infer<typeof announcementConfigSchema>;
+
+export const qcobroConfigSchema = z.object({
+  /** Application (apiserver) database. */
+  database: z.object({ url: z.string().min(1) }),
+  identity: identityConfigSchema,
+  apiserver: z
+    .object({
+      port: z.number().default(3000),
+      /**
+       * Port for the embedded Fonoster VoiceServer (external voice application).
+       * Pre-recorded voice agents are EXTERNAL Fonoster apps that call back into
+       * this server; it answers and plays the rendered script via the Say verb.
+       */
+      voicePort: z.number().default(50061),
+      /** External contact-log ingress (`POST /api/contact-logs`) auth gate. */
+      contactLogAuth: z.object({ enabled: z.boolean().default(false) }).default({ enabled: false })
+    })
+    .default({
+      port: 3000,
+      voicePort: 50061,
+      contactLogAuth: { enabled: false }
+    }),
+  fonoster: fonosterConfigSchema,
+  twilio: twilioConfigSchema,
+  resend: resendConfigSchema,
+  ai: aiConfigSchema,
+  tts: ttsConfigSchema,
+  announcement: announcementConfigSchema,
+  /**
+   * Secret-at-rest. `cloakEncryptionKey` is a versioned AES-GCM-256 key
+   * (`k1.aesgcm256.<base64-32-byte>`) used by `prisma-field-encryption` (the Fonoster/Routr
+   * "cloak" pattern) to encrypt tenant-provided secrets — today the WhatsApp WABA access
+   * token. Optional: when absent, features that store tenant secrets (the Workspace
+   * Integrations area) are disabled rather than crashing boot. Only the *key* is global; the
+   * *secret* is per-workspace in the DB.
+   */
+  security: z.object({ cloakEncryptionKey: z.string().min(1).optional() }).optional(),
+  /**
+   * WhatsApp (Meta Cloud API) connection defaults. Per-workspace credentials (WABA id +
+   * access token) live in the DB, not here — only the shared Graph API base/version are
+   * deployment config.
+   */
+  whatsapp: z
+    .object({
+      apiBaseUrl: z.string().url().default("https://graph.facebook.com"),
+      apiVersion: z.string().default("v18.0"),
+      /** Engine pacing: max template messages the engine may dispatch per minute. */
+      maxMessagesPerMinute: z.number().int().positive().default(60),
+      /**
+       * Meta App Secret — used to verify the `X-Hub-Signature-256` on inbound webhook
+       * events. Optional: when absent, signature verification is skipped (not recommended
+       * in production).
+       */
+      appSecret: z.string().min(1).optional(),
+      /**
+       * Default cap on autopilot replies per collection attempt (per gestión) when a
+       * WHATSAPP agent does not set its own `maxReplies`. Mirrors `resend.maxRepliesDefault`.
+       */
+      maxRepliesDefault: z.number().int().nonnegative().default(3)
+    })
+    .default({
+      apiBaseUrl: "https://graph.facebook.com",
+      apiVersion: "v18.0",
+      maxMessagesPerMinute: 60,
+      maxRepliesDefault: 3
+    }),
+  /**
+   * Campaigns engine. The autonomous in-process loop that originates campaign
+   * outreach. Disabled by default so it never auto-dials in local development;
+   * enable it in production. Per-channel pacing lives in the `fonoster`/`twilio`
+   * blocks (the provider pools they configure are deployment-wide).
+   */
+  engine: z
+    .object({
+      enabled: z.boolean().default(false),
+      /** Seconds between engine ticks. */
+      tickSeconds: z.number().int().positive().default(60)
+    })
+    .default({ enabled: false, tickSeconds: 60 })
+});
+
+export type IdentityConfig = z.infer<typeof identityConfigSchema>;
+export type QCobroConfig = z.infer<typeof qcobroConfigSchema>;

package/src/errors/ValidationError.test.ts

@@ -0,0 +1,38 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { z } from "zod";
+import { ValidationError } from "./ValidationError.js";
+
+const schema = z.object({ name: z.string().min(1), age: z.number() });
+
+function zodErrorFor(input: unknown): z.ZodError {
+  const result = schema.safeParse(input);
+  assert.equal(result.success, false);
+  return (result as { success: false; error: z.ZodError }).error;
+}
+
+describe("ValidationError", () => {
+  it("exposes a stable code and field-level errors", () => {
+    const error = new ValidationError(zodErrorFor({ name: "", age: "nope" }));
+
+    assert.equal(error.code, "VALIDATION_ERROR");
+    assert.equal(error.name, "ValidationError");
+    assert.ok(error instanceof Error);
+
+    const fields = error.fieldErrors.map((f) => f.field);
+    assert.ok(fields.includes("name"));
+    assert.ok(fields.includes("age"));
+    for (const fieldError of error.fieldErrors) {
+      assert.equal(typeof fieldError.message, "string");
+      assert.equal(typeof fieldError.code, "string");
+    }
+  });
+
+  it("serializes to a JSON shape for API responses", () => {
+    const error = new ValidationError(zodErrorFor({ name: "", age: 1 }));
+    const json = error.toJSON();
+
+    assert.deepEqual(Object.keys(json).sort(), ["code", "fieldErrors", "message"]);
+    assert.equal(json.code, "VALIDATION_ERROR");
+  });
+});

package/src/errors/ValidationError.ts

@@ -0,0 +1,68 @@
+import type { z } from "zod";
+
+export interface FieldError {
+  field: string;
+  message: string;
+  code: string;
+}
+
+/**
+ * Wraps a Zod validation error with structured, field-level details suitable
+ * for API responses.
+ */
+export class ValidationError extends Error {
+  public readonly code = "VALIDATION_ERROR";
+  public readonly fieldErrors: FieldError[];
+  public readonly zodError: z.ZodError;
+
+  constructor(zodError: z.ZodError) {
+    const fieldErrors = ValidationError.extractFieldErrors(zodError);
+    const message = ValidationError.formatMessage(fieldErrors);
+
+    super(message);
+    this.name = "ValidationError";
+    this.zodError = zodError;
+    this.fieldErrors = fieldErrors;
+
+    // Maintains proper stack trace for where the error was thrown (V8 engines).
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ValidationError);
+    }
+  }
+
+  private static extractFieldErrors(zodError: z.ZodError): FieldError[] {
+    return zodError.issues.map((issue) => ({
+      field: issue.path.join(".") || "root",
+      message: issue.message,
+      code: issue.code
+    }));
+  }
+
+  private static formatMessage(fieldErrors: FieldError[]): string {
+    if (fieldErrors.length === 0) {
+      return "Validation failed";
+    }
+
+    if (fieldErrors.length === 1) {
+      const { field, message } = fieldErrors[0];
+      return field === "root" ? message : `${field}: ${message}`;
+    }
+
+    const details = fieldErrors
+      .map(({ field, message }) => (field === "root" ? message : `${field}: ${message}`))
+      .join("; ");
+
+    return `Validation failed: ${details}`;
+  }
+
+  /**
+   * Returns a JSON-serializable representation for API responses.
+   */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      fieldErrors: this.fieldErrors
+    };
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1 @@
+export { ValidationError, type FieldError } from "./ValidationError.js";

package/src/index.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export * from "./errors/index.js";
+export * from "./utils/index.js";
+export * from "./schemas/index.js";
+export * from "./types/index.js";
+export * from "./config.js";
+
+/**
+ * Placeholder contract proving the shared-schema pattern.
+ *
+ * `common` is the single source of truth for domain types and Zod schemas,
+ * imported by both the apiserver (input validation) and the webapp (forms/types).
+ * Real domain schemas (portfolios, accounts, Objectives, ...) arrive in a later
+ * change; this entry exists so the contract pattern is wired end to end.
+ */
+export const PingInput = z.object({
+  message: z.string().min(1).max(280)
+});
+
+export type PingInput = z.infer<typeof PingInput>;