@foundrynorth/compass-schema 1.0.22 → 1.0.24

package/dist/schema.js

@@ -6168,7 +6168,15 @@ export const semCampaigns = pgTable("sem_campaigns", {
     index("sem_campaigns_status_idx").on(table.status),
 ]);
 // =============================================================================
-// COMPASS EVENT OUTBOX (dead-letter queue for fn-flux webhook events)
+// COMPASS EVENT OUTBOX (durable outbox for cross-system writes)
+//
+// Generic claim/retry/DLQ pattern used by multiple producers. Events are
+// namespaced by `eventType` prefix so multiple workers can drain the same
+// table without contention:
+//   • "flux.*"         — fn-flux webhook delivery to external consumers
+//   • "hubspot.*"      — HubSpot ticket / Campaign Task writes from fn-legacy
+//                        (drained by fn-v2 hubspot-outbox-worker)
+// Workers filter on `event_type LIKE '{namespace}.%'` in their claim query.
 // =============================================================================
 export const compassEventOutboxStatusEnum = pgEnum("compass_event_outbox_status", [
     "pending",
@@ -6277,4 +6285,169 @@ export const userMilestones = pgTable("user_milestones", {
     index("user_milestones_user_id_idx").on(table.userId),
     unique("user_milestones_user_key_unique").on(table.userId, table.milestoneKey),
 ]);
+// ─── Mid-Campaign Change Management ────────────────────────────────────────
+//
+// Finance-grade in-place edits to live media orders. Distinct from
+// AmendOrderWizard (which takes orders active→draft→sent). A mid-campaign
+// change keeps the order `active`, touches a surgical set of line items,
+// and routes through the existing rate-exception-engine if it would alter
+// rate rules or margin. HubSpot push is the canonical output — HubSpot's
+// own workflow pushes deltas to Naviga.
+//
+// State machine:
+//   draft → (rate violation?) ─┬─ pending_rate_approval ─┬─ applied → hubspot_syncing → hubspot_synced
+//                              │                          └─ rejected (terminal, line items rolled back)
+//                              └─ applied → hubspot_syncing ─┬─ hubspot_synced
+//                                                              └─ hubspot_failed (retryable)
+export const midCampaignChangeRequests = pgTable("mid_campaign_change_requests", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    mediaOrderId: varchar("media_order_id")
+        .notNull()
+        .references(() => mediaOrders.id),
+    reason: amendmentReasonEnum("reason").notNull(),
+    notes: text("notes").notNull(),
+    requestedByUserId: varchar("requested_by_user_id").notNull(),
+    requestedByEmail: varchar("requested_by_email"),
+    requestedByName: varchar("requested_by_name"),
+    requestedAt: timestamp("requested_at").notNull().defaultNow(),
+    appliedAt: timestamp("applied_at"),
+    status: varchar("status").notNull().default("draft"),
+    // draft | pending_rate_approval | applied | rejected | hubspot_syncing | hubspot_synced | hubspot_failed | verified
+    // `verified` is terminal — set when taskStateJson.allComplete && hubspotTicketStage is terminal.
+    // Denormalized summary (so finance reports never join into ops)
+    totalInvestmentDelta: numeric("total_investment_delta", { precision: 12, scale: 2 }).notNull().default("0"),
+    affectedLineItemCount: integer("affected_line_item_count").notNull().default(0),
+    marginDeltaPercent: numeric("margin_delta_percent", { precision: 7, scale: 4 }),
+    marginDeltaDollars: numeric("margin_delta_dollars", { precision: 12, scale: 2 }),
+    // Approval state (nullable — only set when rate engine returned pending_approval for any op)
+    rateApprovalCompletedAt: timestamp("rate_approval_completed_at"),
+    rejectionReason: text("rejection_reason"),
+    // HubSpot ticket (fulfillment pipeline, CHANGE_REQUIRED stage)
+    hubspotTicketId: text("hubspot_ticket_id"),
+    hubspotCampaignTaskIds: jsonb("hubspot_campaign_task_ids").$type().default(sql `'[]'::jsonb`),
+    // HubSpot line-item sync (via fn-v2 hubspot-order-sync)
+    hubspotSyncRunId: text("hubspot_sync_run_id"),
+    hubspotSyncStartedAt: timestamp("hubspot_sync_started_at"),
+    hubspotSyncCompletedAt: timestamp("hubspot_sync_completed_at"),
+    hubspotSyncError: text("hubspot_sync_error"),
+    // Closed-loop projection from HubSpot Campaign Task webhooks
+    // (updated by handleCampaignTaskChange in hubspot-mid-campaign-writeback.ts)
+    hubspotTicketStage: varchar("hubspot_ticket_stage", { length: 40 }),
+    // Current ticket stage as seen in the most recent webhook delivery.
+    // Values: CHANGE_REQUIRED | BILLING_CHANGE_REQUIRED | CANCELLED | COMPLETED | etc.
+    taskStateJson: jsonb("task_state_json").$type(),
+    taskStateUpdatedAt: timestamp("task_state_updated_at"),
+    verifiedAt: timestamp("verified_at"),
+    // Slack alert (thread follow-up replies on approval/sync completion)
+    slackMessageTs: text("slack_message_ts"),
+    slackChannelId: text("slack_channel_id"),
+    // Snapshot for rollback on rate-exception rejection
+    rollbackSnapshotVersion: integer("rollback_snapshot_version"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+}, (table) => [
+    index("mcc_requests_order_idx").on(table.mediaOrderId),
+    index("mcc_requests_status_idx").on(table.status),
+    index("mcc_requests_requested_at_idx").on(table.requestedAt),
+    index("mcc_requests_order_status_idx").on(table.mediaOrderId, table.status),
+]);
+/**
+ * One row per line-item operation inside a change request. This is the
+ * finance report source — one row per field changed per line item.
+ */
+export const midCampaignChangeOps = pgTable("mid_campaign_change_ops", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    changeRequestId: uuid("change_request_id")
+        .notNull()
+        .references(() => midCampaignChangeRequests.id, { onDelete: "cascade" }),
+    opType: varchar("op_type").notNull(), // update | cancel | create
+    lineItemId: varchar("line_item_id")
+        .notNull()
+        .references(() => mediaOrderLineItems.id),
+    // For cancel+create pairs (date-shift across month boundary, product swap)
+    supersedesLineItemId: varchar("supersedes_line_item_id").references(() => mediaOrderLineItems.id),
+    // Denormalized for reporting (so the report query is one table scan)
+    periodLabel: text("period_label"), // "Aug 2026"
+    productCode: text("product_code"),
+    productName: text("product_name"),
+    placement: text("placement"),
+    // The per-field diff — this is the atom finance sees
+    fieldChanges: jsonb("field_changes")
+        .notNull()
+        .$type(),
+    // Per-op investment delta (sums to totalInvestmentDelta on the request)
+    investmentDelta: numeric("investment_delta", { precision: 12, scale: 2 }).notNull().default("0"),
+    // Tracks which HubSpot action this op triggered when synced
+    hubspotOp: varchar("hubspot_op"), // update | cancel | create | skipped
+    hubspotLineItemIdBefore: text("hubspot_line_item_id_before"),
+    hubspotLineItemIdAfter: text("hubspot_line_item_id_after"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    index("mcc_ops_change_request_idx").on(table.changeRequestId),
+    index("mcc_ops_line_item_idx").on(table.lineItemId),
+    index("mcc_ops_period_idx").on(table.periodLabel),
+    uniqueIndex("mcc_ops_change_request_line_item_unique").on(table.changeRequestId, table.lineItemId),
+]);
+/**
+ * Join table: change requests ↔ rate exception requests. A single change
+ * request may trigger N rate exceptions (one per line item that violates
+ * rate rules). The change request blocks in `pending_rate_approval` until
+ * every linked exception is decided; if any reject, the change rolls back.
+ */
+export const midCampaignChangeRateExceptions = pgTable("mid_campaign_change_rate_exceptions", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    changeRequestId: uuid("change_request_id")
+        .notNull()
+        .references(() => midCampaignChangeRequests.id, { onDelete: "cascade" }),
+    rateExceptionRequestId: uuid("rate_exception_request_id")
+        .notNull()
+        .references(() => rateExceptionRequests.id, { onDelete: "restrict" }),
+    // Which op on the change request this exception corresponds to
+    changeOpId: uuid("change_op_id").references(() => midCampaignChangeOps.id, { onDelete: "cascade" }),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    index("mcc_rate_exc_change_request_idx").on(table.changeRequestId),
+    index("mcc_rate_exc_exception_idx").on(table.rateExceptionRequestId),
+    uniqueIndex("mcc_rate_exc_change_request_exception_unique").on(table.changeRequestId, table.rateExceptionRequestId),
+]);
+/**
+ * Campaign Task templates for mid-campaign changes. Hybrid storage — config
+ * in DB (queue, offset, priority, is_active, display_order) so admins can
+ * hot-edit without deploys; predicate logic stays in a code registry
+ * (mid-campaign-template-predicates.ts) keyed by `predicateKey`.
+ *
+ * CI validator asserts every row's `queue` value is in the live HubSpot
+ * Campaign Task `queue` enum. Prevents the "wrong queue ships to HubSpot and
+ * silently fails enum validation" bug.
+ */
+export const midCampaignTaskTemplates = pgTable("mid_campaign_task_templates", {
+    // Stable key (e.g. "review_change_request", "verify_billing_impact").
+    // Used as the templateId in the task plan and for deduplication.
+    id: varchar("id", { length: 64 }).primaryKey(),
+    // Human-readable name — sent as campaign_task_name to HubSpot.
+    name: text("name").notNull(),
+    // Portal Campaign Task queue enum value. CI validator enforces.
+    queue: varchar("queue", { length: 40 }).notNull(),
+    // Days from applied-at when the task is due. Negative = before apply.
+    offsetDays: integer("offset_days").notNull().default(0),
+    // Written to HubSpot priority: high | medium | low.
+    priority: varchar("priority", { length: 16 }).notNull().default("medium"),
+    // Key into the PREDICATES registry in code. Must resolve at runtime.
+    // Valid: always, has_financial_change, has_digital_update_or_cancel,
+    //   has_digital_create, has_print_change, touches_dates
+    predicateKey: varchar("predicate_key", { length: 64 }).notNull(),
+    // Inactive templates are skipped by buildMidCampaignChangeTaskPlan.
+    isActive: boolean("is_active").notNull().default(true),
+    // Display/evaluation order. Lower = higher up in the Compass task list.
+    displayOrder: integer("display_order").notNull().default(0),
+    // Optional human description for the admin UI.
+    description: text("description"),
+    // Audit — who last edited and when.
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+    updatedBy: varchar("updated_by"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+}, (table) => [
+    index("mid_campaign_task_templates_active_idx").on(table.isActive),
+    index("mid_campaign_task_templates_order_idx").on(table.displayOrder),
+]);
 //# sourceMappingURL=schema.js.map