@openlup/platform 0.17.0 → 0.18.0

package/dist/communications/newsletterIntegrationContracts.d.ts

@@ -21,8 +21,8 @@ export declare const newsletterSyncEventTypeSchema: z.ZodEnum<{
     suppress: "suppress";
 }>;
 export declare const newsletterWebhookEventTypeSchema: z.ZodEnum<{
-    email_change: "email_change";
     update: "update";
+    email_change: "email_change";
     subscribe: "subscribe";
     unsubscribe: "unsubscribe";
     suppress: "suppress";
@@ -46,8 +46,8 @@ export declare const canonicalNewsletterWebhookEventSchema: z.ZodObject<{
     providerKind: z.ZodString;
     providerEventId: z.ZodString;
     eventType: z.ZodEnum<{
-        email_change: "email_change";
         update: "update";
+        email_change: "email_change";
         subscribe: "subscribe";
         unsubscribe: "unsubscribe";
         suppress: "suppress";
@@ -85,8 +85,8 @@ export declare function createNewsletterIntegrationSchemas<Purpose extends strin
         providerKind: z.ZodString;
         providerEventId: z.ZodString;
         eventType: z.ZodEnum<{
-            email_change: "email_change";
             update: "update";
+            email_change: "email_change";
             subscribe: "subscribe";
             unsubscribe: "unsubscribe";
             suppress: "suppress";

package/dist/communications/resend/index.d.ts

@@ -0,0 +1,40 @@
+import { type EmailEgressPolicy } from "../emailEgress.js";
+import type { EmailTransport } from "../emailTransport.js";
+import { type EmailObservationPort } from "../emailObservation.js";
+import { type DeliveryReconciliationPort, type DeliveryReconciliationResult } from "../deliveryReconciliation.js";
+/** Opt-in Node sender. Every send obtains a fresh validated host egress decision. */
+export declare function createResendTransport(input: {
+    policy: EmailEgressPolicy;
+    environmentTagName: string;
+    fetch?: typeof fetch;
+}): EmailTransport;
+/** Poll existing IDs through the neutral runner; never retries a send. */
+export declare function runResendDeliveryReconciliation(input: {
+    port: DeliveryReconciliationPort;
+    now: string;
+    graceMinutes: number;
+    limit: number;
+    apiKey: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<DeliveryReconciliationResult>;
+/** Authenticate untouched bytes before decoding. now returns UTC seconds; receiver defaults to non-production. */
+export declare function createResendWebhookHandler(input: {
+    port: EmailObservationPort;
+    webhookSecret: string;
+    environmentTagName: string;
+    resolveReceiverEnvironmentTag?: () => "production" | "non_production";
+    now?: () => number;
+    receivedAt?: () => Date;
+}): (request: {
+    method?: string;
+    rawBody: string | Uint8Array;
+    headers: {
+        webhookId?: string;
+        timestamp?: string;
+        signature?: string;
+    };
+}) => Promise<{
+    status: number;
+    body: Record<string, unknown> | "ok";
+}>;

package/dist/communications/resend/index.js

@@ -0,0 +1,310 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createGuardedEmailTransport } from "../emailEgress.js";
+import { processEmailObservation } from "../emailObservation.js";
+import { runDeliveryReconciliation } from "../deliveryReconciliation.js";
+/** Opt-in Node sender. Every send obtains a fresh validated host egress decision. */
+export function createResendTransport(input) {
+    return createGuardedEmailTransport({
+        providerKind: "resend",
+        policy: input.policy,
+        send: (message, context) => postResendEmail(message, context, input.environmentTagName, input.fetch ?? fetch),
+    });
+}
+const RESEND_ENDPOINT = "https://api.resend.com/emails";
+const PROVIDER_ERROR_MAX = 240;
+const PROVIDER_ERROR_CODE_MAX = 80;
+const EMAIL_ADDRESS_PATTERN = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max - 1)}...` : value;
+}
+function sanitizeProviderText(value) {
+    return truncate(value.replace(EMAIL_ADDRESS_PATTERN, "[email]").replace(/\s+/g, " ").trim(), PROVIDER_ERROR_MAX);
+}
+function sanitizeProviderCode(value) {
+    return truncate(value.replace(/[^A-Za-z0-9._:-]/g, "_"), PROVIDER_ERROR_CODE_MAX);
+}
+function providerErrorFromBody(body, httpStatus) {
+    const errField = body.error;
+    if (typeof errField === "string")
+        return sanitizeProviderText(errField);
+    if (errField && typeof errField === "object") {
+        const message = errField.message;
+        if (typeof message === "string")
+            return sanitizeProviderText(message);
+    }
+    if (typeof body.message === "string")
+        return sanitizeProviderText(body.message);
+    return `Resend HTTP ${httpStatus}`;
+}
+function providerErrorCodeFromBody(body) {
+    const errField = body.error;
+    const errorRecord = errField && typeof errField === "object"
+        ? errField
+        : {};
+    const candidates = [
+        errorRecord.code,
+        errorRecord.name,
+        errorRecord.type,
+        body.code,
+        body.name,
+        body.type,
+    ];
+    const value = candidates.find((candidate) => typeof candidate === "string" && candidate.trim() !== "");
+    return typeof value === "string" ? sanitizeProviderCode(value) : null;
+}
+function providerErrorResponse(body, httpStatus) {
+    const providerErrorMessage = providerErrorFromBody(body, httpStatus);
+    const providerErrorCode = providerErrorCodeFromBody(body);
+    return {
+        http_status: httpStatus,
+        provider_error_message: providerErrorMessage,
+        ...(providerErrorCode ? { provider_error_code: providerErrorCode } : {}),
+    };
+}
+async function postResendEmail(input, context, environmentTagName, fetcher) {
+    const headers = {
+        Authorization: `Bearer ${context.credential}`,
+        "Content-Type": "application/json",
+    };
+    if (input.idempotencyKey !== undefined)
+        headers["Idempotency-Key"] = input.idempotencyKey;
+    if (context.mode === "sandbox_sink")
+        headers["X-Original-Recipient"] = context.intendedRecipient;
+    try {
+        const res = await fetcher(RESEND_ENDPOINT, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                from: input.from,
+                to: [context.recipient],
+                subject: input.subject,
+                html: input.html,
+                ...(input.text === undefined ? {} : { text: input.text }),
+                ...(input.replyTo === undefined ? {} : { reply_to: input.replyTo }),
+                ...(input.attachments === undefined ? {} : { attachments: input.attachments }),
+                tags: [{
+                        name: environmentTagName,
+                        value: context.environmentTag,
+                    }],
+            }),
+            signal: input.signal,
+        });
+        const parsed = await res.json().catch(() => ({}));
+        const body = typeof parsed === "object" && parsed !== null
+            ? parsed
+            : {};
+        if (!res.ok) {
+            const providerErrorMessage = providerErrorFromBody(body, res.status);
+            const providerErrorCode = providerErrorCodeFromBody(body);
+            return {
+                outcome: {
+                    ok: false,
+                    resendId: null,
+                    httpStatus: res.status,
+                    providerError: providerErrorMessage,
+                    providerErrorCode,
+                    aborted: false,
+                    egressMode: context.mode,
+                    egressReason: context.reason,
+                },
+                providerResponse: providerErrorResponse(body, res.status),
+            };
+        }
+        const id = typeof body.id === "string" ? body.id : null;
+        return {
+            outcome: {
+                ok: true,
+                resendId: id,
+                httpStatus: res.status,
+                providerError: null,
+                aborted: false,
+                egressMode: context.mode,
+                egressReason: context.reason,
+            },
+            providerResponse: { id },
+        };
+    }
+    catch (err) {
+        const aborted = input.signal?.aborted === true ||
+            (err instanceof Error && err.name === "AbortError");
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            outcome: {
+                ok: false,
+                resendId: null,
+                httpStatus: 0,
+                providerError: sanitizeProviderText(msg),
+                aborted,
+                egressMode: context.mode,
+                egressReason: context.reason,
+            },
+            providerResponse: { exception: true, aborted },
+        };
+    }
+}
+function readFirstRecipient(value) {
+    if (typeof value === "string" && value.includes("@"))
+        return value;
+    if (!Array.isArray(value))
+        return null;
+    return value.find((recipient) => typeof recipient === "string" && recipient.includes("@")) ?? null;
+}
+// Read-only status retrieval for the delivery reconciliation poller
+// (docs/platform/RUNTIME_AND_SELF_HOSTING.md Wave 4). No egress gating needed: this never
+// sends mail — it only reads the provider's view of an already-sent message.
+async function getResendEmail(input, fetcher) {
+    try {
+        const res = await fetcher(`${RESEND_ENDPOINT}/${encodeURIComponent(input.resendId)}`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${input.apiKey}` },
+            signal: input.signal,
+        });
+        const parsed = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            return {
+                ok: false,
+                httpStatus: res.status,
+                lastEvent: null,
+                recipientEmail: null,
+                providerError: providerErrorFromBody(parsed, res.status),
+            };
+        }
+        const lastEvent = typeof parsed.last_event === "string" ? parsed.last_event : null;
+        return {
+            ok: true,
+            httpStatus: res.status,
+            lastEvent,
+            recipientEmail: readFirstRecipient(parsed.to),
+            providerError: null,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            httpStatus: 0,
+            lastEvent: null,
+            recipientEmail: null,
+            providerError: error instanceof Error ? sanitizeProviderCode(error.message) : "fetch_failed",
+        };
+    }
+}
+/** Poll existing IDs through the neutral runner; never retries a send. */
+export function runResendDeliveryReconciliation(input) {
+    return runDeliveryReconciliation({
+        port: input.port, now: input.now, graceMinutes: input.graceMinutes, limit: input.limit,
+        readEmail: messageId => getResendEmail({ apiKey: input.apiKey, resendId: messageId, signal: input.signal }, input.fetch ?? fetch),
+        observationFor: read => {
+            const status = read.lastEvent;
+            if (!status || !["delivered", "delivery_delayed", "bounced", "complained", "failed"].includes(status))
+                return null;
+            return { eventType: `email.${status}`, terminal: ["bounced", "complained", "failed"].includes(status) };
+        },
+    });
+}
+const eventKinds = new Map([
+    ["email.sent", "sent"], ["email.delivered", "delivered"], ["email.delivery_delayed", "delivery_delayed"],
+    ["email.opened", "open"], ["email.clicked", "click"], ["email.bounced", "bounce"],
+    ["email.complained", "complaint"], ["email.failed", "failed"], ["email.suppressed", "suppressed"], ["email.scheduled", "scheduled"],
+]);
+/** Authenticate untouched bytes before decoding. now returns UTC seconds; receiver defaults to non-production. */
+export function createResendWebhookHandler(input) {
+    return async (request) => {
+        if (request.method === "OPTIONS")
+            return { status: 200, body: "ok" };
+        if (!verifyResendWebhookSignature({ ...request.headers, rawBody: request.rawBody, secret: input.webhookSecret, now: input.now })) {
+            return { status: 401, body: { error: "Invalid signature" } };
+        }
+        try {
+            const payload = JSON.parse(typeof request.rawBody === "string" ? request.rawBody : Buffer.from(request.rawBody).toString("utf8"));
+            const type = isRecord(payload) ? payload.type : null;
+            const data = isRecord(payload) ? payload.data : null;
+            if (typeof type !== "string" || !eventKinds.has(type))
+                return { status: 200, body: { ignored: true } };
+            const messageId = isRecord(data) && typeof data.email_id === "string" ? data.email_id : null;
+            if (!messageId)
+                return { status: 200, body: { ignored: true, reason: "missing_email_id" } };
+            const tag = readEnvironmentTag(data, input.environmentTagName);
+            if (tag && tag !== (input.resolveReceiverEnvironmentTag?.() ?? "non_production")) {
+                return { status: 200, body: { ignored: true, reason: "foreign_send_not_found" } };
+            }
+            const disposition = await processEmailObservation({
+                port: input.port, messageId,
+                observation: () => {
+                    const time = resolveEventTime(isRecord(payload) ? payload.created_at : null, request.headers.timestamp, input.receivedAt?.() ?? new Date());
+                    return { eventType: type, eventAt: time.eventAt, metadata: {
+                            providerEventId: request.headers.webhookId ?? null, eventMetadata: data ?? {},
+                            link: isRecord(data) && isRecord(data.click) && typeof data.click.link === "string" ? data.click.link : null,
+                            source: "resend-webhook", eventTimeSource: time.source,
+                        } };
+                },
+            });
+            return disposition.outcome === "send_not_found"
+                ? { status: 200, body: { ignored: true, reason: "send_not_found" } }
+                : { status: 200, body: { success: true } };
+        }
+        catch {
+            return { status: 500, body: { error: "Webhook processing failed" } };
+        }
+    };
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function readEnvironmentTag(data, tagName) {
+    if (!isRecord(data))
+        return null;
+    const tags = data.tags;
+    const value = Array.isArray(tags)
+        ? tags.find(entry => isRecord(entry) && entry.name === tagName)?.value
+        : isRecord(tags) ? tags[tagName] : null;
+    return value === "production" || value === "non_production" ? value : null;
+}
+function resolveEventTime(createdAt, timestamp, receivedAt) {
+    if (typeof createdAt === "string" && Number.isFinite(Date.parse(createdAt))) {
+        return { eventAt: new Date(createdAt).toISOString(), source: "provider_created_at" };
+    }
+    const seconds = Number(timestamp);
+    if (Number.isFinite(seconds) && seconds > 0)
+        return { eventAt: new Date(seconds * 1000).toISOString(), source: "svix_timestamp" };
+    return { eventAt: receivedAt.toISOString(), source: "received_at" };
+}
+function verifyResendWebhookSignature(input) {
+    const { webhookId, timestamp, signature, rawBody, secret } = input;
+    if (!webhookId || !timestamp || !signature || !secret)
+        return false;
+    const timestampSeconds = Number(timestamp);
+    if (!Number.isFinite(timestampSeconds))
+        return false;
+    const now = input.now ?? (() => Math.floor(Date.now() / 1000));
+    if (Math.abs(now() - timestampSeconds) > 300)
+        return false;
+    const secretKey = signingSecret(secret);
+    if (secretKey === null)
+        return false;
+    const expected = createHmac("sha256", secretKey)
+        .update(`${webhookId}.${timestamp}.`).update(rawBody)
+        .digest("base64");
+    return signature.split(" ").some((member) => timingSafeStringEqual(member, `v1,${expected}`) || timingSafeStringEqual(member, expected));
+}
+function signingSecret(secret) {
+    if (!secret.startsWith("whsec_"))
+        return secret;
+    // Svix encodes endpoint secrets after the whsec_ prefix. Buffer preserves the
+    // decoded bytes for node:crypto rather than treating the base64 text as a key.
+    // Buffer.from(base64) is deliberately permissive, so reject empty, malformed,
+    // or non-canonical input before it can silently become an empty/partial key.
+    const encoded = secret.slice("whsec_".length);
+    if (!encoded || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 === 1)
+        return null;
+    const decoded = Buffer.from(encoded, "base64");
+    if (decoded.length === 0)
+        return null;
+    const canonicalPadded = decoded.toString("base64");
+    const canonicalUnpadded = canonicalPadded.replace(/=+$/, "");
+    return encoded === canonicalPadded || encoded === canonicalUnpadded ? decoded : null;
+}
+function timingSafeStringEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/dist/composition/catalogContribution.d.ts

@@ -0,0 +1,18 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+/** Actual selected callables, supplied by the host; declarations never activate them. */
+export interface CatalogContributionInput {
+    version: string;
+    requiredSchema: RequiredSchema;
+    catalog: Readonly<Record<string, (...args: never[]) => unknown>>;
+    pricing: Readonly<Record<string, (...args: never[]) => unknown>>;
+    promotions: Readonly<Record<string, (...args: never[]) => unknown>>;
+    routes: Contribution["routes"];
+}
+/** Thin structural declarations under the existing logical module identities. */
+export declare function createCatalogContribution(input: CatalogContributionInput): {
+    contributions: Contribution[];
+    ports: Record<string, unknown>;
+    routes: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+};

package/dist/composition/catalogContribution.js

@@ -0,0 +1,21 @@
+/** Thin structural declarations under the existing logical module identities. */
+export function createCatalogContribution(input) {
+    const contributions = [];
+    const ports = {};
+    for (const module of ["catalog", "pricing", "promotions"]) {
+        const selected = input[module];
+        for (const [name, callable] of Object.entries(selected))
+            ports[`@openlup/platform/${module}:${name}`] = callable;
+        contributions.push({
+            manifest: {
+                name: "@openlup/platform", version: input.version, kind: "rail",
+                module: { id: module, kind: "capability", provides: [`./${module}`], dependsOn: [] },
+                emits: [], handles: [], schedules: [], env: [], requiredPorts: Object.keys(selected),
+                routes: module === "catalog" ? input.routes.map(route => route.id) : [],
+                ...(module === "catalog" ? { requiredSchema: input.requiredSchema } : {}),
+            },
+            handlers: [], schedules: [], routes: module === "catalog" ? input.routes : [],
+        });
+    }
+    return { contributions, ports, routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/catalog:${route.id}`, route.handle])) };
+}

package/dist/composition/index.d.ts

@@ -1,3 +1,4 @@
 export { createBundleComposer, type ComposeBundle, type PlatformBundle, type PlatformBundleBinders, type PlatformBundlePorts, } from "./composeBundle.js";
 export { bindNodeHttpPort, createScheduledEntrypointResolver } from "./httpBinding.js";
 export { createNodeHost, type NodeHost, type NodeHostAdmission, type NodeHostDependencies, type NodeSchedulerProfile, type ServeNodeOptions, type ServeNodeResult, } from "./nodeHost.js";
+export { createCatalogContribution, type CatalogContributionInput } from "./catalogContribution.js";

package/dist/composition/index.js

@@ -1,3 +1,4 @@
 export { createBundleComposer, } from "./composeBundle.js";
 export { bindNodeHttpPort, createScheduledEntrypointResolver } from "./httpBinding.js";
 export { createNodeHost, } from "./nodeHost.js";
+export { createCatalogContribution } from "./catalogContribution.js";

package/dist/identity/customerContracts.d.ts

@@ -1,9 +1,9 @@
 import { z } from "zod";
 export declare const customerLifecycleStageSchema: z.ZodEnum<{
+    inactive: "inactive";
     lead: "lead";
     tester: "tester";
     customer: "customer";
-    inactive: "inactive";
 }>;
 export declare const customerMeRequestSchema: z.ZodObject<{}, z.core.$strict>;
 export declare const customerMeResponseSchema: z.ZodObject<{
@@ -12,10 +12,10 @@ export declare const customerMeResponseSchema: z.ZodObject<{
     firstName: z.ZodNullable<z.ZodString>;
     lastName: z.ZodNullable<z.ZodString>;
     lifecycleStage: z.ZodEnum<{
+        inactive: "inactive";
         lead: "lead";
         tester: "tester";
         customer: "customer";
-        inactive: "inactive";
     }>;
     subscriptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         subscriptionId: z.ZodGUID;

package/dist/inventory/adminInventory.d.ts

@@ -0,0 +1,13 @@
+import type { z } from "zod";
+import { type InventoryMutationPort, type InventoryReadPort } from "./ports.js";
+interface PgQueryExecutor {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/** Operator readback over the same public stock and reservation rail used by renewal. */
+export declare function createPostgresAdminInventoryPort(executor: PgQueryExecutor, config: {
+    stockMasterProvider: string;
+    providerSchema: z.ZodType<string>;
+}, now?: () => string): InventoryReadPort & InventoryMutationPort;
+export {};