@openlup/platform 0.28.0 → 0.30.0

package/dist/marketing/server/acquisitionCaseHandlers.d.ts

@@ -0,0 +1,28 @@
+import type { AcquisitionCaseListRequest } from "../contracts/index.js";
+import { type AcquisitionCaseSubmitRequest, type AcquisitionCaseTransitionRequest } from "./acquisitionCasePorts.js";
+import type { AcquisitionCasePort } from "./acquisitionCasePorts.js";
+export interface AcquisitionCaseHandlerOptions {
+    now?: () => string;
+}
+export declare function createAcquisitionCaseHandlers(port: AcquisitionCasePort, options?: AcquisitionCaseHandlerOptions): {
+    submit(request: AcquisitionCaseSubmitRequest, context: {
+        idempotencyKey: string;
+        requesterKey: string;
+    }): Promise<import("./acquisitionCasePorts.js").AcquisitionCaseResult<import("../contracts/acquisition.js").AcquisitionCaseProjection>>;
+    list(actorRef: string, request: AcquisitionCaseListRequest): Promise<import("./acquisitionCasePorts.js").AcquisitionCaseResult<import("../contracts/acquisition.js").AcquisitionCaseListResponse>>;
+    get(actorRef: string, caseRef: string): Promise<import("./acquisitionCasePorts.js").AcquisitionCaseResult<import("../contracts/acquisition.js").AcquisitionCaseProjection>>;
+    transition(actorRef: string, idempotencyKey: string, request: AcquisitionCaseTransitionRequest): Promise<import("./acquisitionCasePorts.js").AcquisitionCaseResult<import("../contracts/acquisition.js").AcquisitionCaseProjection>>;
+    activeCount(): Promise<{
+        ok: false;
+        error: {
+            kind: import("./acquisitionCasePorts.js").AcquisitionCaseFailureKind;
+        };
+    } | {
+        ok: true;
+        value: {
+            activeTesterCount: number;
+        };
+    }>;
+    contractVersion: "tester_application_v1";
+};
+export type AcquisitionCaseHandlers = ReturnType<typeof createAcquisitionCaseHandlers>;

package/dist/marketing/server/acquisitionCaseHandlers.js

@@ -0,0 +1,40 @@
+import { ACQUISITION_CASE_CONTRACT_VERSION, ACQUISITION_CASE_SOURCE } from "../acquisitionCaseSchemas.js";
+const SCOPE = "public_tester_application";
+export function createAcquisitionCaseHandlers(port, options = {}) {
+    const now = options.now ?? (() => new Date().toISOString());
+    return {
+        submit(request, context) {
+            return port.submit({
+                scope: SCOPE,
+                sourceKind: ACQUISITION_CASE_SOURCE,
+                idempotencyKey: context.idempotencyKey,
+                requesterKey: `${SCOPE}:${context.requesterKey}`,
+                acceptedAt: now(),
+                sourcePath: "/tester-application",
+                request,
+            });
+        },
+        list(actorRef, request) {
+            return port.list({
+                actorRef,
+                scope: SCOPE,
+                ...(request.cursor ? { cursor: request.cursor } : {}),
+                limit: request.limit,
+            });
+        },
+        get(actorRef, caseRef) {
+            return port.get({ actorRef, scope: SCOPE, caseRef });
+        },
+        transition(actorRef, idempotencyKey, request) {
+            return port.transition({ actorRef, scope: SCOPE, idempotencyKey, request });
+        },
+        async activeCount() {
+            const result = await port.activeCount(SCOPE);
+            return result.ok === false ? result : {
+                ok: true,
+                value: { activeTesterCount: result.value },
+            };
+        },
+        contractVersion: ACQUISITION_CASE_CONTRACT_VERSION,
+    };
+}

package/dist/marketing/server/acquisitionCasePorts.d.ts

@@ -0,0 +1,42 @@
+import type { AcquisitionCaseProjection, AcquisitionCaseResult, AcquisitionCasePort as PortableAcquisitionCasePort } from "../contracts/index.js";
+import type { AcquisitionAddressReference, AcquisitionCaseProjection as Projection } from "../contracts/index.js";
+/** Historical commands retained by the server adapter; public admission routes remain host-owned. */
+export interface AcquisitionCaseSubmitRequest {
+    contact: {
+        email: string;
+    };
+    consent: {
+        accepted: true;
+        consentVersion: string;
+        policyVersion: string;
+        locale: Projection["consent"]["locale"];
+    };
+    addressReference: AcquisitionAddressReference;
+}
+export interface AcquisitionCaseTransitionRequest {
+    view: "acquisition_case_v1";
+    caseRef: string;
+    expectedVersion: number;
+    transition: "approve" | "activate" | "reject" | "withdraw";
+    reason?: string | undefined;
+}
+export interface AcquisitionCaseSubmitCommand {
+    scope: "public_tester_application";
+    sourceKind: "tester_application";
+    idempotencyKey: string;
+    requesterKey: string;
+    acceptedAt: string;
+    sourcePath: "/tester-application";
+    request: AcquisitionCaseSubmitRequest;
+}
+export interface AcquisitionCaseTransitionCommand {
+    actorRef: string;
+    scope: "public_tester_application";
+    idempotencyKey: string;
+    request: AcquisitionCaseTransitionRequest;
+}
+export interface AcquisitionCasePort extends PortableAcquisitionCasePort {
+    submit(command: AcquisitionCaseSubmitCommand): Promise<AcquisitionCaseResult<AcquisitionCaseProjection>>;
+    transition(command: AcquisitionCaseTransitionCommand): Promise<AcquisitionCaseResult<AcquisitionCaseProjection>>;
+}
+export type { AcquisitionCaseFailureKind, AcquisitionCaseResult, AcquisitionCaseListQuery, AcquisitionCaseGetQuery, } from "../contracts/index.js";

package/dist/marketing/server/acquisitionCasePorts.js

@@ -0,0 +1 @@
+export {};

package/dist/marketing/server/acquisitionEvidenceDirect.d.ts

@@ -0,0 +1,5 @@
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { AcquisitionEvidenceDirectDeps } from "./directPorts.js";
+export declare function createAcquisitionSurveySubmitDirectHandler(options: AcquisitionEvidenceDirectDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAcquisitionSurveyListDirectHandler(options: AcquisitionEvidenceDirectDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export declare function createAcquisitionNewsletterConsentDirectHandler(options: AcquisitionEvidenceDirectDeps): (value: unknown, res: HttpResponse) => Promise<void>;

package/dist/marketing/server/acquisitionEvidenceDirect.js

@@ -0,0 +1,100 @@
+import { acquisitionNewsletterConsentEventSchema, acquisitionSurveyListQuerySchema, acquisitionSurveySubmitSchema } from "../acquisitionEvidenceSchemas.js";
+export function createAcquisitionSurveySubmitDirectHandler(options) {
+    const { respond, resolveBinding } = options;
+    const { sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async (req, res) => {
+        if (req.method !== "POST")
+            return sendMethodNotAllowed(res, ["POST"]);
+        const request = acquisitionSurveySubmitSchema.safeParse(req.body);
+        const idempotencyKey = firstHeader(req.headers["idempotency-key"]);
+        if (!request.success || !idempotencyKey)
+            return badRequest(res, respond, request.success ? undefined : request.error.flatten());
+        const binding = await bindingOrError(res, respond, resolveBinding);
+        if (!binding)
+            return;
+        const result = await safeOperation(() => binding.submitSurvey({ ...request.data, idempotencyKey }));
+        if (!result)
+            return unavailable(res, respond);
+        if (result.ok === false)
+            return failure(res, respond, result.error.kind);
+        sendBffSuccess(res, result.value);
+    };
+}
+export function createAcquisitionSurveyListDirectHandler(options) {
+    const { respond, authorize, resolveBinding } = options;
+    const { sendBffSuccess, sendMethodNotAllowed } = respond;
+    return async (req, res) => {
+        if (req.method !== "GET")
+            return sendMethodNotAllowed(res, ["GET"]);
+        const actorReference = await authorize(req, res);
+        if (!actorReference)
+            return;
+        const request = acquisitionSurveyListQuerySchema.safeParse({
+            view: first(req.query.view), surveyType: first(req.query.surveyType), limit: first(req.query.limit) ?? "50",
+        });
+        if (!request.success)
+            return badRequest(res, respond, request.error.flatten());
+        const binding = await bindingOrError(res, respond, resolveBinding);
+        if (!binding)
+            return;
+        const result = await safeOperation(() => binding.listSurveys({ ...request.data, actorReference }));
+        if (!result)
+            return unavailable(res, respond);
+        if (result.ok === false)
+            return failure(res, respond, result.error.kind);
+        sendBffSuccess(res, result.value);
+    };
+}
+export function createAcquisitionNewsletterConsentDirectHandler(options) {
+    const { respond, resolveBinding } = options;
+    const { sendBffSuccess } = respond;
+    return async (value, res) => {
+        const request = acquisitionNewsletterConsentEventSchema.safeParse(value);
+        if (!request.success)
+            return badRequest(res, respond, request.error.flatten());
+        const binding = await bindingOrError(res, respond, resolveBinding);
+        if (!binding)
+            return;
+        const result = await safeOperation(() => binding.applyNewsletterConsent(request.data));
+        if (!result)
+            return unavailable(res, respond);
+        if (result.ok === false)
+            return failure(res, respond, result.error.kind);
+        sendBffSuccess(res, result.value);
+    };
+}
+async function bindingOrError(res, respond, resolve) {
+    try {
+        const binding = await resolve();
+        if (binding)
+            return binding;
+    }
+    catch { /* fail closed below */ }
+    unavailable(res, respond);
+    return null;
+}
+async function safeOperation(work) {
+    try {
+        return await work();
+    }
+    catch {
+        return null;
+    }
+}
+function failure(res, respond, kind) {
+    if (kind === "invalid")
+        return badRequest(res, respond);
+    if (kind === "not_found")
+        return respond.sendBffError(res, "NOT_FOUND", "Acquisition evidence subject not found");
+    if (kind === "conflict")
+        return respond.sendBffError(res, "CONFLICT", "Acquisition evidence request conflicts with prior state");
+    unavailable(res, respond);
+}
+function badRequest(res, respond, details) {
+    respond.sendBffError(res, "BAD_REQUEST", "Invalid acquisition evidence request", { details });
+}
+function unavailable(res, respond) {
+    respond.sendBffError(res, "UPSTREAM_UNAVAILABLE", "Acquisition evidence service unavailable");
+}
+function first(value) { return Array.isArray(value) ? value[0] : value; }
+function firstHeader(value) { return first(value); }

package/dist/marketing/server/analyticsContext.d.ts

@@ -0,0 +1,3 @@
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { AnalyticsContextHandlerDeps } from "./analyticsContextPorts.js";
+export declare function createAnalyticsContextHandler(deps: AnalyticsContextHandlerDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/marketing/server/analyticsContext.js

@@ -0,0 +1,65 @@
+import { z } from "../validation.js";
+export function createAnalyticsContextHandler(deps) {
+    const { respond, isEnabled, resolveStore, readAccessToken, resolveTrustedSubject, capabilityCrypto, cookieName, clientIdField } = deps;
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = respond;
+    const requestSchema = z.object({
+        granted: z.boolean(),
+        [clientIdField]: z.string().regex(/^\d+\.\d+$/).max(64).optional(),
+        explicitGrant: z.boolean().default(false),
+    }).strict();
+    return async (req, res) => {
+        if (req.method !== "POST")
+            return sendMethodNotAllowed(res, ["POST"]);
+        if (!isEnabled())
+            return sendBffError(res, "NOT_FOUND", "Analytics context unavailable");
+        // No URL, IP, contact, session, form or account data is accepted or logged.
+        const origin = typeof req.headers.origin === "string" ? req.headers.origin : "";
+        if (!origin || origin !== `https://${req.headers.host}`)
+            return sendBffError(res, "FORBIDDEN", "Same-origin request required");
+        const parsed = requestSchema.safeParse(req.body);
+        const clientId = parsed.success ? parsed.data[clientIdField] : undefined;
+        if (!parsed.success || (parsed.data.granted && !clientId))
+            return sendBffError(res, "BAD_REQUEST", "Invalid analytics context");
+        const store = resolveStore();
+        if (!store)
+            return sendBffError(res, "UPSTREAM_UNAVAILABLE", "Analytics context unavailable");
+        // The computed shape key widens inference; the strict schema validates these fixed fields.
+        const data = parsed.data;
+        let hash = contextHash(typeof req.headers.cookie === "string" ? req.headers.cookie : undefined, cookieName, (value) => capabilityCrypto.hashToken(value));
+        // Explicit user re-consent gets a new capability; withdrawn old bindings stay withdrawn.
+        let token = null;
+        if (data.granted && !hash) {
+            token = capabilityCrypto.mintToken();
+            hash = capabilityCrypto.hashToken(token);
+        }
+        if (!hash) {
+            sendBffSuccess(res, { active: false });
+            return;
+        }
+        try {
+            const accessToken = readAccessToken(req);
+            const subject = data.granted && accessToken ? await resolveTrustedSubject(accessToken) : null;
+            if (accessToken && data.granted && !subject)
+                return sendBffError(res, "UNAUTHORIZED", "Customer session required");
+            let active = await store.syncContext({ tokenHash: hash, granted: data.granted, clientId: clientId ?? null });
+            if (active !== true && data.granted && data.explicitGrant && !token) {
+                token = capabilityCrypto.mintToken();
+                hash = capabilityCrypto.hashToken(token);
+                active = await store.syncContext({ tokenHash: hash, granted: true, clientId: clientId });
+            }
+            if (active === true && subject)
+                await store.enrollSubscriptions({ subject, contextHash: hash });
+            if (token && active === true)
+                res.setHeader("Set-Cookie", `${cookieName}=${token}; Path=/; Max-Age=31536000; HttpOnly; Secure; SameSite=Lax`);
+            res.setHeader("Cache-Control", "no-store");
+            sendBffSuccess(res, { active: active === true });
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Analytics context unavailable");
+        }
+    };
+}
+function contextHash(cookie, cookieName, hashToken) {
+    const token = cookie?.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${cookieName}=`))?.split("=")[1];
+    return token && /^[a-f0-9]{64}$/.test(token) ? hashToken(token) : null;
+}

package/dist/marketing/server/analyticsContextPorts.d.ts

@@ -0,0 +1,31 @@
+import type { HttpRequest } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+/** Host persistence rejects on failure; only literal true means an active context. */
+export interface AnalyticsContextPersistencePort {
+    syncContext(input: {
+        tokenHash: string;
+        granted: boolean;
+        clientId: string | null;
+    }): Promise<unknown>;
+    enrollSubscriptions(input: {
+        subject: string;
+        contextHash: string;
+    }): Promise<unknown>;
+}
+export type AnalyticsContextStoreResolver = () => AnalyticsContextPersistencePort | null;
+/** The host supplies opaque 32-byte hexadecimal tokens and their cryptographic hash. */
+export interface AnalyticsContextCapabilityCrypto {
+    mintToken(): string;
+    hashToken(token: string): string;
+}
+export interface AnalyticsContextHandlerDeps {
+    respond: BffResponder;
+    isEnabled: () => boolean;
+    resolveStore: AnalyticsContextStoreResolver;
+    readAccessToken: (req: HttpRequest) => string | null;
+    resolveTrustedSubject: (accessToken: string) => Promise<string | null>;
+    capabilityCrypto: AnalyticsContextCapabilityCrypto;
+    cookieName: string;
+    /** Historical request field name supplied by the host. */
+    clientIdField: string;
+}

package/dist/marketing/server/analyticsContextPorts.js

@@ -0,0 +1 @@
+export {};

package/dist/marketing/server/bindings.d.ts

@@ -0,0 +1,14 @@
+import type { ReadinessIssue } from "@openlup/core/readiness";
+import { type MarketingPrivacyContributor, type MarketingPrivacyDependencies } from "./privacyContributor.js";
+/** Select one fully bound privacy contributor; absent activation leaves the host registry unchanged. */
+export declare function createMarketingPrivacyBindings<Context>(input: MarketingPrivacyDependencies<Context> & {
+    enabled?: boolean;
+}): {
+    contributor: MarketingPrivacyContributor<Context> | null;
+    issues: ReadinessIssue[];
+    callables: Readonly<{
+        exportPersonalData: MarketingPrivacyContributor<Context>["export"] | null;
+        assessErasure: MarketingPrivacyContributor<Context>["assessErasure"] | null;
+        eraseOrRetain: MarketingPrivacyContributor<Context>["eraseOrRetain"] | null;
+    }>;
+};

package/dist/marketing/server/bindings.js

@@ -0,0 +1,18 @@
+import { createMarketingPrivacyContributor } from "./privacyContributor.js";
+/** Select one fully bound privacy contributor; absent activation leaves the host registry unchanged. */
+export function createMarketingPrivacyBindings(input) {
+    const acquisition = input.acquisition && [input.acquisition.export, input.acquisition.assessErasure, input.acquisition.eraseOrRetain].every(fn => typeof fn === "function") ? input.acquisition : null;
+    const remoteErasure = input.remoteErasure && [input.remoteErasure.read, input.remoteErasure.openAndFence].every(fn => typeof fn === "function") ? input.remoteErasure : null;
+    const issues = [];
+    for (const [name, port] of [["acquisition", acquisition], ["remoteErasure", remoteErasure]]) {
+        if (!port)
+            issues.push({ code: "OPENLUP_E_PORT_MISSING", package: "@openlup/platform", module: "marketing", subject: name, fix: `Bind the marketing ${name} owner port.` });
+    }
+    const selected = input.enabled === true && issues.length === 0
+        ? createMarketingPrivacyContributor({ ...input, acquisition, remoteErasure }) : null;
+    return { contributor: selected, issues, callables: Object.freeze({
+            exportPersonalData: selected ? selected.export : null,
+            assessErasure: selected ? selected.assessErasure : null,
+            eraseOrRetain: selected ? selected.eraseOrRetain : null,
+        }) };
+}

package/dist/marketing/server/directPorts.d.ts

@@ -0,0 +1,26 @@
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { AcquisitionCaseHandlers } from "./acquisitionCaseHandlers.js";
+import type { AcquisitionEvidencePort } from "../contracts/index.js";
+export interface AcquisitionCaseReadBinding {
+    handlers: Pick<AcquisitionCaseHandlers, "list" | "get" | "activeCount">;
+}
+export type AcquisitionCaseBindingResolver = () => Promise<AcquisitionCaseReadBinding | null>;
+export type AcquisitionEvidenceBindingResolver = () => Promise<AcquisitionEvidencePort | null>;
+export type AcquisitionAuthorize = (req: HttpRequest, res: HttpResponse) => Promise<string | null>;
+export interface AcquisitionCaseDirectDeps {
+    respond: BffResponder;
+    authorize: AcquisitionAuthorize;
+    resolveBinding: AcquisitionCaseBindingResolver;
+    isDirect: () => boolean;
+}
+export interface PrelaunchAcquisitionDirectDeps {
+    respond: BffResponder;
+    authorize: AcquisitionAuthorize;
+    resolveBinding: AcquisitionCaseBindingResolver;
+}
+export interface AcquisitionEvidenceDirectDeps {
+    respond: BffResponder;
+    authorize: AcquisitionAuthorize;
+    resolveBinding: AcquisitionEvidenceBindingResolver;
+}

package/dist/marketing/server/directPorts.js

@@ -0,0 +1 @@
+export {};

package/dist/marketing/server/index.d.ts

@@ -0,0 +1,14 @@
+/** Node-only acquisition and research algorithms. Hosts own routing, authorization and presentation. */
+export * from "./acquisitionCaseHandlers.js";
+export type * from "./acquisitionCasePorts.js";
+export type * from "./directPorts.js";
+export * from "./acquisitionCaseDirect.js";
+export * from "./prelaunchAcquisitionDirect.js";
+export * from "./acquisitionEvidenceDirect.js";
+export * from "./research/surveyResponseSubmitHandler.js";
+export * from "./research/adminSurveyResponsesHandler.js";
+export * from "./research/managedSurveyResponseSubmit.js";
+export { createAnalyticsContextHandler } from "./analyticsContext.js";
+export type * from "./analyticsContextPorts.js";
+export * from "./privacyContributor.js";
+export * from "./bindings.js";

package/dist/marketing/server/index.js

@@ -0,0 +1,11 @@
+/** Node-only acquisition and research algorithms. Hosts own routing, authorization and presentation. */
+export * from "./acquisitionCaseHandlers.js";
+export * from "./acquisitionCaseDirect.js";
+export * from "./prelaunchAcquisitionDirect.js";
+export * from "./acquisitionEvidenceDirect.js";
+export * from "./research/surveyResponseSubmitHandler.js";
+export * from "./research/adminSurveyResponsesHandler.js";
+export * from "./research/managedSurveyResponseSubmit.js";
+export { createAnalyticsContextHandler } from "./analyticsContext.js";
+export * from "./privacyContributor.js";
+export * from "./bindings.js";

package/dist/marketing/server/postgres/acquisitionCaseRoutines.d.ts

@@ -0,0 +1,10 @@
+import { Pool } from "pg";
+import type { AcquisitionCasePort } from "../acquisitionCasePorts.js";
+type Env = {
+    connectionString: string;
+};
+type Options = {
+    poolFactory?: (env: Env) => Pool | Promise<Pool>;
+};
+export declare function createPostgresAcquisitionCasePort(env: Env, options?: Options): AcquisitionCasePort;
+export {};

package/dist/marketing/server/postgres/acquisitionCaseRoutines.js

@@ -0,0 +1,204 @@
+import { Buffer } from "node:buffer";
+import { Pool } from "pg";
+import { ACQUISITION_CASE_CONTRACT_VERSION, acquisitionCaseListResponseSchema, acquisitionCaseProjectionSchema } from "../../acquisitionCaseSchemas.js";
+const ROLE = "SET LOCAL ROLE platform_acquisition_runtime";
+const SUBMIT = `SELECT public.acquisition_case_submit_v1(
+  $1::text,$2::text,$3::text,$4::text,$5::boolean,$6::text,$7::text,
+  $8::text,$9::text,$10::text,$11::text,$12::text,$13::text,$14::timestamptz
+) AS response`;
+const LIST = "SELECT public.acquisition_case_operator_list_v1($1::uuid,$2::timestamptz,$3::uuid,$4::integer) AS response";
+const GET = "SELECT public.acquisition_case_operator_get_v1($1::uuid,$2::text) AS response";
+const TRANSITION = `SELECT public.acquisition_case_transition_v1(
+  $1::uuid,$2::text,$3::bigint,$4::text,$5::text,$6::text,$7::timestamptz
+) AS response`;
+const ACTIVE_COUNT = "SELECT public.acquisition_case_active_count_v1() AS response";
+export function createPostgresAcquisitionCasePort(env, options = {}) {
+    if (!env.connectionString.trim())
+        throw new Error("acquisition_case_database_url_required");
+    let poolPromise = null;
+    const pool = () => poolPromise ??= Promise.resolve(options.poolFactory ? options.poolFactory(env) : new Pool({ connectionString: env.connectionString }));
+    const call = async (sql, values) => withRole(await pool(), async (client) => {
+        const result = await client.query(sql, values);
+        return object(result.rows[0])?.response ?? null;
+    });
+    return {
+        async submit(command) {
+            if (command.scope !== "public_tester_application" || command.sourceKind !== "tester_application") {
+                return failure("invalid");
+            }
+            try {
+                const request = command.request;
+                const response = object(await call(SUBMIT, [
+                    command.idempotencyKey,
+                    command.requesterKey,
+                    request.contact.email.trim().toLowerCase(),
+                    null,
+                    request.consent.accepted,
+                    request.consent.consentVersion,
+                    request.consent.policyVersion,
+                    request.consent.locale,
+                    command.sourcePath,
+                    request.addressReference.source,
+                    request.addressReference.reference,
+                    request.addressReference.revision,
+                    request.addressReference.provenance,
+                    command.acceptedAt,
+                ]));
+                return projectionResult(response);
+            }
+            catch (error) {
+                return databaseFailure(error);
+            }
+        },
+        async list(query) {
+            if (query.scope !== "public_tester_application")
+                return failure("invalid");
+            const cursor = decodeCursor(query.cursor);
+            if (cursor === undefined)
+                return failure("invalid");
+            try {
+                const response = object(await call(LIST, [
+                    query.actorRef,
+                    cursor?.createdAt ?? null,
+                    cursor?.id ?? null,
+                    query.limit,
+                ]));
+                if (!response || !Array.isArray(response.cases))
+                    return failure("unavailable");
+                const parsed = acquisitionCaseListResponseSchema.safeParse({
+                    contractVersion: response.contractVersion ?? ACQUISITION_CASE_CONTRACT_VERSION,
+                    cases: response.cases,
+                    nextCursor: response.nextCursor === null ? null : encodeCursor(response.nextCursor),
+                });
+                return parsed.success ? { ok: true, value: parsed.data } : failure("unavailable");
+            }
+            catch (error) {
+                return databaseFailure(error);
+            }
+        },
+        async get(query) {
+            if (query.scope !== "public_tester_application")
+                return failure("invalid");
+            try {
+                const response = object(await call(GET, [query.actorRef, query.caseRef]));
+                if (response?.outcome === "not_found")
+                    return failure("not_found");
+                return projectionResult(response);
+            }
+            catch (error) {
+                return databaseFailure(error);
+            }
+        },
+        async transition(command) {
+            if (command.scope !== "public_tester_application")
+                return failure("invalid");
+            const target = transitionTarget(command);
+            try {
+                const response = object(await call(TRANSITION, [
+                    command.actorRef,
+                    command.request.caseRef,
+                    command.request.expectedVersion,
+                    target,
+                    command.request.reason ?? null,
+                    command.idempotencyKey,
+                    new Date().toISOString(),
+                ]));
+                return projectionResult(response);
+            }
+            catch (error) {
+                return databaseFailure(error);
+            }
+        },
+        async activeCount(scope) {
+            if (scope !== "public_tester_application")
+                return failure("invalid");
+            try {
+                const raw = await call(ACTIVE_COUNT, []);
+                const count = typeof raw === "number" ? raw : Number(raw);
+                return Number.isSafeInteger(count) && count >= 0
+                    ? { ok: true, value: count }
+                    : failure("unavailable");
+            }
+            catch (error) {
+                return databaseFailure(error);
+            }
+        },
+        async close() {
+            if (poolPromise)
+                await (await poolPromise).end();
+        },
+    };
+}
+async function withRole(pool, work) {
+    const client = await pool.connect();
+    try {
+        await client.query("BEGIN");
+        await client.query(ROLE);
+        const value = await work(client);
+        await client.query("COMMIT");
+        return value;
+    }
+    catch (error) {
+        await client.query("ROLLBACK").catch(() => { });
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+function projectionResult(response) {
+    if (!response)
+        return failure("unavailable");
+    const outcome = response.outcome;
+    if (outcome === "created" || outcome === "replayed" || outcome === "transitioned" || outcome === "found") {
+        const parsed = acquisitionCaseProjectionSchema.safeParse(response.acquisitionCase);
+        return parsed.success
+            ? { ok: true, value: parsed.data, replayed: response.replayed === true }
+            : failure("unavailable");
+    }
+    return failure(outcomeFailure(outcome));
+}
+function outcomeFailure(outcome) {
+    if (outcome === "invalid_address")
+        return "invalid";
+    if (outcome === "rate_limited")
+        return "rate_limited";
+    if (outcome === "not_found")
+        return "not_found";
+    if (outcome === "idempotency_conflict" || outcome === "contact_conflict"
+        || outcome === "version_conflict" || outcome === "transition_conflict")
+        return "conflict";
+    return "unavailable";
+}
+function databaseFailure(error) {
+    return failure(object(error)?.code === "22023" ? "invalid" : "unavailable");
+}
+function failure(kind) {
+    return { ok: false, error: { kind } };
+}
+function transitionTarget(command) {
+    return { approve: "approved", activate: "active", reject: "rejected", withdraw: "withdrawn" }[command.request.transition];
+}
+function encodeCursor(value) {
+    const cursor = object(value);
+    if (!cursor || typeof cursor.createdAt !== "string" || typeof cursor.id !== "string") {
+        throw new Error("acquisition_case_cursor_invalid");
+    }
+    return Buffer.from(JSON.stringify({ createdAt: cursor.createdAt, id: cursor.id }), "utf8").toString("base64url");
+}
+function decodeCursor(value) {
+    if (value === undefined)
+        return null;
+    try {
+        const parsed = object(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
+        return parsed && typeof parsed.createdAt === "string" && typeof parsed.id === "string"
+            ? { createdAt: parsed.createdAt, id: parsed.id }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}

package/dist/marketing/server/postgres/acquisitionEvidenceRoutines.d.ts

@@ -0,0 +1,10 @@
+import { Pool } from "pg";
+import type { AcquisitionEvidencePort } from "../../contracts/index.js";
+type Env = {
+    connectionString: string;
+};
+type Options = {
+    poolFactory?: (env: Env) => Pool | Promise<Pool>;
+};
+export declare function createPostgresAcquisitionEvidencePort(env: Env, options?: Options): AcquisitionEvidencePort;
+export {};