@openlup/platform 0.28.0 → 0.29.0

package/src/marketing/server/prelaunchAcquisitionDirect.ts

@@ -0,0 +1,121 @@
+import {
+  PRELAUNCH_ACQUISITION_CONTRACT_VERSION,
+  prelaunchAcquisitionDetailRequestSchema,
+  prelaunchAcquisitionDetailResponseSchema,
+  prelaunchAcquisitionListRequestSchema,
+  prelaunchAcquisitionListResponseSchema,
+  type PrelaunchAcquisitionLead,
+} from "../prelaunchAcquisitionSchemas.js";
+import type { AcquisitionCaseProjection } from "../contracts/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { AcquisitionCaseFailureKind } from "../contracts/index.js";
+import type { PrelaunchAcquisitionDirectDeps, AcquisitionCaseBindingResolver } from "./directPorts.js";
+
+export function createPrelaunchAcquisitionListHandler(options: PrelaunchAcquisitionDirectDeps) {
+  const { respond, authorize, resolveBinding } = options;
+  const { sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    const actorRef = await authorize(req, res);
+    if (!actorRef) return;
+    const request = prelaunchAcquisitionListRequestSchema.safeParse({
+      view: first(req.query.view),
+      cursor: first(req.query.cursor),
+      limit: first(req.query.limit) ?? "25",
+    });
+    if (!request.success) return badRequest(res, respond, request.error.flatten());
+    const binding = await bindingOrError(res, respond, resolveBinding);
+    if (!binding) return;
+    const result = await operationOrError(res, respond, () => binding.handlers.list(actorRef, {
+      view: "acquisition_case_v1",
+      ...(request.data.cursor ? { cursor: request.data.cursor } : {}),
+      limit: request.data.limit,
+    }));
+    if (!result) return;
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    const response = prelaunchAcquisitionListResponseSchema.safeParse({
+      contractVersion: PRELAUNCH_ACQUISITION_CONTRACT_VERSION,
+      leads: result.value.cases.map(toLead),
+      nextCursor: result.value.nextCursor,
+    });
+    if (!response.success) return invalidResponse(res, respond);
+    sendBffSuccess(res, response.data);
+  };
+}
+
+export function createPrelaunchAcquisitionDetailHandler(options: PrelaunchAcquisitionDirectDeps) {
+  const { respond, authorize, resolveBinding } = options;
+  const { sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+    if (req.method !== "GET") return sendMethodNotAllowed(res, ["GET"]);
+    const actorRef = await authorize(req, res);
+    if (!actorRef) return;
+    const request = prelaunchAcquisitionDetailRequestSchema.safeParse({
+      sourceRef: first(req.query.sourceRef),
+    });
+    if (!request.success) return badRequest(res, respond, request.error.flatten());
+    const binding = await bindingOrError(res, respond, resolveBinding);
+    if (!binding) return;
+    const result = await operationOrError(res, respond, () => binding.handlers.get(actorRef, request.data.sourceRef));
+    if (!result) return;
+    if (result.ok === false) return failure(res, respond, result.error.kind);
+    const response = prelaunchAcquisitionDetailResponseSchema.safeParse({
+      contractVersion: PRELAUNCH_ACQUISITION_CONTRACT_VERSION,
+      lead: toLead(result.value),
+    });
+    if (!response.success) return invalidResponse(res, respond);
+    sendBffSuccess(res, response.data);
+  };
+}
+
+function toLead(value: AcquisitionCaseProjection): PrelaunchAcquisitionLead {
+  return {
+    sourceRef: value.caseRef,
+    contactRef: value.contactRef,
+    sourceKind: value.sourceKind,
+    consent: value.consent,
+    addressReference: value.addressReference,
+    state: value.state,
+    version: value.version,
+    createdAt: value.createdAt,
+    updatedAt: value.updatedAt,
+  };
+}
+
+async function bindingOrError(res: HttpResponse, respond: BffResponder, resolve: AcquisitionCaseBindingResolver) {
+  try {
+    const binding = await resolve();
+    if (binding) return binding;
+  } catch { /* fail closed below */ }
+  respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Prelaunch acquisition service unavailable");
+  return null;
+}
+
+async function operationOrError<T>(res: HttpResponse, respond: BffResponder, operation: () => Promise<T>): Promise<T | null> {
+  try { return await operation(); }
+  catch {
+    respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Prelaunch acquisition service unavailable");
+    return null;
+  }
+}
+
+function first(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function badRequest(res: HttpResponse, respond: BffResponder, details?: unknown): void {
+  respond.sendBffError(res, "BAD_REQUEST", "Invalid prelaunch acquisition request", { details });
+}
+
+function invalidResponse(res: HttpResponse, respond: BffResponder): void {
+  respond.sendBffError(res, "INVALID_RESPONSE", "Prelaunch acquisition returned invalid response");
+}
+
+function failure(res: HttpResponse, respond: BffResponder, kind: AcquisitionCaseFailureKind): void {
+  if (kind === "invalid") return badRequest(res, respond);
+  if (kind === "not_found") return respond.sendBffError(res, "NOT_FOUND", "Prelaunch acquisition case not found");
+  if (kind === "conflict") return respond.sendBffError(res, "CONFLICT", "Prelaunch acquisition request conflicts with prior state");
+  if (kind === "rate_limited") return respond.sendBffError(res, "RATE_LIMITED", "Prelaunch acquisition request rate limited");
+  respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Prelaunch acquisition service unavailable");
+}

package/src/marketing/server/privacyContributor.ts

@@ -0,0 +1,123 @@
+import { personalDataObligationSchema } from "../../identity/contracts/index.js";
+import type { PersonalDataDocument, PersonalDataObligation, PrivacyJson } from "../../identity/contracts/index.js";
+
+interface AuthorizedHumanAdministrator { principalId: string }
+interface ResolvedPrivacySubject {
+  contactId: string | null;
+  principalId: string | null;
+  identity: { [key: string]: PrivacyJson };
+}
+interface ErasureAssessment { obligations: PersonalDataObligation[] }
+/** Structural identity contributor contract without selecting identity's server adapters. */
+export interface MarketingPrivacyContributor<Context> {
+  readonly id: string;
+  readonly version: string;
+  readonly ownedResources: readonly string[];
+  prepareErasure(context: Context): Promise<void>;
+  export(context: Context, subject: ResolvedPrivacySubject): Promise<PersonalDataDocument>;
+  assessErasure(context: Context, subject: ResolvedPrivacySubject): Promise<ErasureAssessment>;
+  eraseOrRetain(context: Context, subject: ResolvedPrivacySubject, assessment: ErasureAssessment, actor: AuthorizedHumanAdministrator): Promise<{
+    contributorId: string; version: string; obligations: PersonalDataObligation[];
+  }>;
+}
+
+export interface MarketingAcquisitionPrivacyPort<Context> {
+  export(context: Context, subject: ResolvedPrivacySubject): Promise<{ records: PrivacyJson; evidence: PrivacyJson; obligations: PersonalDataObligation[] }>;
+  /** Read-only; declare both local resources, including explicit retention policy. */
+  assessErasure(context: Context, subject: ResolvedPrivacySubject): Promise<ErasureAssessment>;
+  eraseOrRetain(context: Context, subject: ResolvedPrivacySubject, assessment: ErasureAssessment, actor: AuthorizedHumanAdministrator): Promise<ErasureAssessment>;
+}
+export interface MarketingRemoteErasureCase {
+  state: "pending" | "requested" | "accepted" | "failed" | "not_bound";
+  fenced: boolean;
+  pendingTargets: number;
+  waitingImports: number;
+}
+export interface MarketingRemoteErasurePort<Context> {
+  /** Read-only subject lookup; return no addresses or provider references. */
+  read(context: Context, subject: ResolvedPrivacySubject): Promise<MarketingRemoteErasureCase | null>;
+  /** Authorized transaction: atomically fence against recreation and record the case, replay-safe per caseId.
+   * In-flight imports and late-import orphan targets remain the case owner's obligations.
+   */
+  openAndFence(context: Context, input: { caseId: string; subject: ResolvedPrivacySubject; actor: AuthorizedHumanAdministrator; openedAt: string }): Promise<MarketingRemoteErasureCase>;
+}
+export interface MarketingPrivacyDependencies<Context> {
+  acquisition: MarketingAcquisitionPrivacyPort<Context> | null;
+  remoteErasure: MarketingRemoteErasurePort<Context> | null;
+  now?: () => Date;
+  randomId(): string;
+}
+const localResources = ["marketing.acquisition-records", "marketing.acquisition-evidence"] as const;
+const remoteResource = "marketing.remote-profile";
+const id = "marketing", version = "marketing.personal-data.v1";
+function obligation(resource: string, disposition: PersonalDataObligation["disposition"], reasonCode: string): PersonalDataObligation {
+  return { owner: id, resource, disposition, reasonCode, remote: resource === remoteResource };
+}
+function unresolved(resource: string): PersonalDataObligation { return obligation(resource, "unresolved", "MARKETING_OWNER_UNAVAILABLE"); }
+function localObligations(value: unknown): PersonalDataObligation[] {
+  const invalid = () => localResources.map(unresolved);
+  if (!Array.isArray(value) || value.length !== localResources.length) return invalid();
+  const parsed = value.map(item => personalDataObligationSchema.safeParse(item));
+  if (parsed.some(item => !item.success)) return invalid();
+  const rows = parsed.map(item => { if (!item.success) throw new Error("marketing_obligation_invalid"); return item.data; });
+  if (rows.some(row => row.owner !== id || row.remote || !localResources.some(resource => resource === row.resource))
+    || localResources.some(resource => rows.filter(row => row.resource === resource).length !== 1)) return invalid();
+  // Owner text is never echoed into receipts; only closed, content-free reasons cross this boundary.
+  return rows.map(row => obligation(row.resource, row.disposition, row.disposition === "erase" ? "LOCAL_OWNER_ERASURE"
+    : row.disposition === "retain" ? "LOCAL_OWNER_RETENTION" : "MARKETING_OWNER_UNAVAILABLE"));
+}
+function validCase(value: MarketingRemoteErasureCase): boolean {
+  return !!value && ["pending", "requested", "accepted", "failed", "not_bound"].includes(value.state)
+    && typeof value.fenced === "boolean" && Number.isSafeInteger(value.pendingTargets) && value.pendingTargets >= 0
+    && Number.isSafeInteger(value.waitingImports) && value.waitingImports >= 0;
+}
+function remoteObligation(value: MarketingRemoteErasureCase | null): PersonalDataObligation {
+  if (value === null) return obligation(remoteResource, "retain", "REMOTE_ERASURE_NOT_REQUESTED");
+  if (!validCase(value)) return unresolved(remoteResource);
+  const reasons = { pending: "REMOTE_ERASURE_PENDING", requested: "REMOTE_ERASURE_REQUESTED", accepted: "REMOTE_ERASURE_ACCEPTED_NOT_OBSERVED",
+    failed: "REMOTE_ERASURE_FAILED", not_bound: value.fenced ? "REMOTE_ERASURE_NOT_BOUND_LOCAL_FENCE_ONLY" : "REMOTE_ERASURE_NOT_BOUND" };
+  return obligation(remoteResource, "retain", `${reasons[value.state]}${value.waitingImports > 0 ? "_WAITING_IMPORTS" : ""}${value.pendingTargets > 0 ? "_PENDING_TARGETS" : ""}`);
+}
+async function ownerCall<T>(run: () => Promise<T>): Promise<T> {
+  try { return await run(); } catch { throw new Error("marketing_privacy_owner_failed"); }
+}
+
+/** Identity orchestrates authorization, assessment, transaction rollback and receipt replay. */
+export function createMarketingPrivacyContributor<Context>(input: MarketingPrivacyDependencies<Context>): MarketingPrivacyContributor<Context> {
+  // Partial ownership cannot establish coverage or permit any erasure effects.
+  const acquisition = input.acquisition && input.remoteErasure ? input.acquisition : null;
+  const remoteErasure = acquisition ? input.remoteErasure : null;
+  const { randomId } = input, now = input.now ?? (() => new Date());
+  return {
+    id, version, ownedResources: [...localResources, remoteResource],
+    async prepareErasure() {},
+    async export(context, subject) {
+      const local = acquisition ? await ownerCall(() => acquisition.export(context, subject)) : null;
+      const remote = remoteErasure ? await ownerCall(() => remoteErasure.read(context, subject)) : null;
+      const validRemote = remote === null || validCase(remote);
+      return { contributorId: id, version, data: { acquisition: local ? { records: local.records, evidence: local.evidence } : null,
+        remoteProfile: { state: validRemote ? remote?.state ?? null : null } },
+      coverage: { complete: false, included: local ? [...localResources] : [], unavailable: [...(local ? [] : localResources), remoteResource] },
+      obligations: [...(local ? localObligations(local.obligations) : localResources.map(unresolved)),
+        remoteErasure ? remoteObligation(remote) : unresolved(remoteResource)] };
+    },
+    async assessErasure(context, subject) {
+      const local = acquisition ? await ownerCall(() => acquisition.assessErasure(context, subject)) : null;
+      const remote = remoteErasure ? await ownerCall(() => remoteErasure.read(context, subject)) : null;
+      return { obligations: [...(local ? localObligations(local.obligations) : localResources.map(unresolved)),
+        remoteErasure ? remoteObligation(remote) : unresolved(remoteResource)] };
+    },
+    async eraseOrRetain(context, subject, assessment, actor) {
+      if (!acquisition || !remoteErasure || assessment.obligations.some(row => row.disposition === "unresolved")) throw new Error("marketing_privacy_unbound");
+      // Identity receipt replay bypasses contributors. Rolled-back attempts may use a fresh ID;
+      // the owner atomically reuses the subject fence and deduplicates each case ID.
+      const remote = await ownerCall(() => remoteErasure.openAndFence(context, { caseId: randomId(), subject, actor, openedAt: now().toISOString() }));
+      if (!validCase(remote) || remote.fenced !== true) throw new Error("marketing_privacy_fence_required");
+      const local = await ownerCall(() => acquisition.eraseOrRetain(context, subject,
+        { obligations: assessment.obligations.filter(row => localResources.some(resource => resource === row.resource)) }, actor));
+      const obligations = localObligations(local.obligations);
+      if (obligations.some(row => row.disposition === "unresolved")) throw new Error("marketing_privacy_disposition_invalid");
+      return { contributorId: id, version, obligations: [...obligations, remoteObligation(remote)] };
+    },
+  };
+}

package/src/marketing/server/research/adminSurveyResponsesHandler.ts

@@ -0,0 +1,78 @@
+import type { HttpRequest, HttpResponse } from "../../../http/index.js";
+import type { BffResponder } from "../../../bff/index.js";
+import {
+  adminSurveyResponsesRequestSchema,
+  adminSurveyResponsesResponseSchema,
+} from "@openlup/core/marketing/research";
+import type { MarketingResearchSurveyResponsesReadPort } from "@openlup/core/marketing/research";
+
+export interface AdminSurveyResponsesHandlerDeps {
+  respond: BffResponder;
+  readPort: MarketingResearchSurveyResponsesReadPort;
+  authorizeAdmin: (req: HttpRequest) => Promise<boolean>;
+}
+
+export function createAdminSurveyResponsesHandler({
+  respond,
+  readPort,
+  authorizeAdmin,
+}: AdminSurveyResponsesHandlerDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    const authorized = await authorize(req, res, authorizeAdmin, respond);
+    if (!authorized) return;
+
+    const request = adminSurveyResponsesRequestSchema.safeParse({
+      surveyType: firstQueryValue(req.query.surveyType),
+      page: firstQueryValue(req.query.page),
+      pageSize: firstQueryValue(req.query.pageSize),
+      limit: firstQueryValue(req.query.limit),
+    });
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid survey responses request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await readPort.getAdminSurveyResponses(request.data);
+      const response = adminSurveyResponsesResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Survey responses returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Survey responses read failed");
+    }
+  };
+}
+
+async function authorize(
+  req: HttpRequest,
+  res: HttpResponse,
+  authorizeAdmin: (req: HttpRequest) => Promise<boolean>,
+  respond: BffResponder,
+): Promise<boolean> {
+  const { sendBffError } = respond;
+  try {
+    if (await authorizeAdmin(req)) return true;
+  } catch {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+    return false;
+  }
+
+  sendBffError(res, "UNAUTHORIZED", "Admin session required");
+  return false;
+}
+
+function firstQueryValue(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value;
+}

package/src/marketing/server/research/managedSurveyResponseSubmit.ts

@@ -0,0 +1,158 @@
+import type { ResearchSurveySubmitRequest, ResearchSurveySubmitResponse } from "@openlup/core/marketing/research";
+import type { PublicIntakeDeliveryPort, PublicIntakeDeliveryResult } from "../../../communications/contracts/index.js";
+
+type SurveyTable = "survey_responses_producer" | "survey_responses_consumer";
+
+export interface ManagedSurveyResponseGateway {
+  checkRateLimit(input: {
+    table: SurveyTable;
+    ip: string;
+    windowMinutes: number;
+    maxPerIp: number;
+    now: Date;
+  }): Promise<"allowed" | "limited" | "unavailable">;
+  insert(input: {
+    table: SurveyTable;
+    responseData: Record<string, unknown>;
+    ip: string | null;
+    userAgent: string | null;
+  }): Promise<{ id: string } | null>;
+  updateEmailStatus(input: {
+    table: SurveyTable;
+    id: string;
+    sentAt: string | null;
+    error: string | null;
+  }): Promise<void>;
+}
+
+export interface ManagedSurveyResponseSubmitDeps {
+  renderNotificationHtml: (surveyType: "producer" | "consumer", responseData: Record<string, unknown>, id: string) => string;
+  notificationSubject: (surveyType: "producer" | "consumer", now: Date) => string;
+  gateway: ManagedSurveyResponseGateway;
+  delivery: PublicIntakeDeliveryPort;
+  notifyTo: string[];
+  fromEmail: string;
+  windowMinutes: number;
+  maxPerIp: number;
+  now?: () => Date;
+}
+
+export function createManagedSurveyResponseSubmit(deps: ManagedSurveyResponseSubmitDeps) {
+  const now = deps.now ?? (() => new Date());
+  return async (request: ResearchSurveySubmitRequest, headers?: Headers): Promise<ResearchSurveySubmitResponse> => {
+    if (!validRequest(request)) return { ok: false, error: "invalid_response_data" };
+    const table = request.surveyType === "producer" ? "survey_responses_producer" : "survey_responses_consumer";
+    const ip = readIp(headers);
+    const rate = await deps.gateway.checkRateLimit({ table, ip: ip ?? "unknown", windowMinutes: deps.windowMinutes, maxPerIp: deps.maxPerIp, now: now() });
+    if (rate === "unavailable") return { ok: false, error: "survey_rate_limit_unavailable" };
+    if (rate === "limited") return { ok: false, error: "survey_rate_limited" };
+
+    let inserted: { id: string } | null;
+    try {
+      inserted = await deps.gateway.insert({
+        table,
+        responseData: request.responseData,
+        ip,
+        userAgent: headers?.get("user-agent") || null,
+      });
+    } catch {
+      inserted = null;
+    }
+    if (!inserted) return { ok: false, error: "db_insert_failed" };
+
+    if (deps.notifyTo.length === 0) {
+      await updateEmailStatus(deps.gateway, table, inserted.id, null, "notification_recipient_not_configured");
+      return { ok: true, id: inserted.id, email_skipped: "notification_recipient_not_configured" };
+    }
+
+    const templateSlug = `survey_${request.surveyType}_notification`;
+    const policies = await Promise.all(deps.notifyTo.map((recipient, index) => deps.delivery.evaluatePolicy({
+      email: recipient,
+      purpose: "admin_notification",
+      source: "submit-survey-response",
+      recipientKind: "admin_internal",
+      metadata: {
+        template_slug: templateSlug,
+        survey_type: request.surveyType,
+        survey_response_id: inserted.id,
+        recipient_count: deps.notifyTo.length,
+        recipient_index: index,
+      },
+    })));
+    const recipients = deps.notifyTo.map((recipient, index) => ({ recipient, index, policy: policies[index]! }));
+    const allowedRecipients = recipients.filter(({ policy }) => policy.allowed);
+    if (allowedRecipients.length === 0) {
+      const reason = policies[0]?.reason ?? "policy_blocked";
+      await updateEmailStatus(deps.gateway, table, inserted.id, null, reason);
+      return { ok: true, id: inserted.id, email_skipped: reason };
+    }
+
+    const rendered = deps.renderNotificationHtml(request.surveyType, request.responseData, inserted.id);
+    const subject = deps.notificationSubject(request.surveyType, now());
+    const attempts = await Promise.all(allowedRecipients.map(({ recipient, index, policy }) => sendAndRecord(deps, {
+      recipient, source: "submit-survey-response", templateSlug, policyDecisionId: policy.decisionId,
+      policyReason: policy.reason, id: inserted.id, index, subject, html: rendered,
+    })));
+    const notAccepted = attempts.find((attempt) => !attempt.accepted);
+    await updateEmailStatus(
+      deps.gateway,
+      table,
+      inserted.id,
+      notAccepted ? null : now().toISOString(),
+      notAccepted?.error ?? notAccepted?.skip ?? null,
+    );
+    return { ok: true, id: inserted.id };
+  };
+}
+
+function validRequest(request: ResearchSurveySubmitRequest): boolean {
+  return (request.surveyType === "producer" || request.surveyType === "consumer")
+    && Boolean(request.responseData && typeof request.responseData === "object" && !Array.isArray(request.responseData) && Object.keys(request.responseData).length > 0);
+}
+
+function readIp(headers: Headers | undefined): string | null {
+  return headers?.get("x-forwarded-for")?.split(",")[0]?.trim() || headers?.get("cf-connecting-ip") || null;
+}
+
+async function updateEmailStatus(
+  gateway: ManagedSurveyResponseGateway,
+  table: SurveyTable,
+  id: string,
+  sentAt: string | null,
+  error: string | null,
+): Promise<void> {
+  try {
+    await gateway.updateEmailStatus({ table, id, sentAt, error });
+  } catch {
+    // The survey row is durable; email metadata remains explicitly best effort.
+  }
+}
+
+async function sendAndRecord(deps: ManagedSurveyResponseSubmitDeps, input: {
+  recipient: string; source: string; templateSlug: string; policyDecisionId: string | null; policyReason: string;
+  id: string; index: number; subject: string; html: string;
+}): Promise<PublicIntakeDeliveryResult> {
+  try {
+    return await deps.delivery.deliver({
+      source: input.source,
+      templateSlug: input.templateSlug,
+      policyDecisionId: input.policyDecisionId,
+      dedupeKey: `${input.templateSlug}:${input.id}:${input.index}`,
+      purpose: "admin_notification",
+      triggerEvent: "survey_response_submitted",
+      recipientEmail: input.recipient,
+      aggregateType: "survey_response",
+      aggregateId: input.id,
+      metadata: { surveyResponseId: input.id, policyReason: input.policyReason },
+      message: {
+        sender: deps.fromEmail,
+        to: input.recipient,
+        subject: input.subject,
+        html: input.html,
+      },
+    });
+  } catch {
+    return { accepted: false, messageId: null, skip: null, error: "email_ledger_unavailable" };
+  }
+}
+

package/src/marketing/server/research/surveyResponseSubmitHandler.ts

@@ -0,0 +1,57 @@
+import type { HttpRequest, HttpResponse } from "../../../http/index.js";
+import type { BffResponder } from "../../../bff/index.js";
+import {
+  researchSurveySubmitRequestSchema,
+  researchSurveySubmitResponseSchema,
+} from "@openlup/core/marketing/research";
+import type { MarketingResearchSurveySubmitPort } from "@openlup/core/marketing/research";
+
+export interface ResearchSurveySubmitHandlerDeps {
+  respond: BffResponder;
+  submitPort: MarketingResearchSurveySubmitPort;
+}
+
+export function createResearchSurveySubmitHandler({
+  respond,
+  submitPort,
+}: ResearchSurveySubmitHandlerDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    const request = researchSurveySubmitRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid research survey response request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await submitPort.submitSurveyResponse(request.data, {
+        headers: headersFromRequest(req),
+      });
+      const response = researchSurveySubmitResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Research survey submit returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Research survey submit failed");
+    }
+  };
+}
+
+function headersFromRequest(req: HttpRequest): Headers {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (typeof value === "string") headers.set(key, value);
+    else if (Array.isArray(value)) headers.set(key, value.join(", "));
+  }
+  return headers;
+}

package/src/marketing/validation.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };