@jini-ai/platform 0.6.12 → 0.6.15-rc.2

package/dist/mail/index.d.ts

@@ -1,8 +1,10 @@
 export type * from "./types.js";
 export type * from "./ports.js";
 export type * from "./adapter-module.js";
-export { wrapMailerWithPurposeGate } from "./purpose-scoped-mailer.js";
-export type { WrapMailerWithPurposeGateOptions } from "./purpose-scoped-mailer.js";
+export { createMailAdapterContext } from "./adapter-module.js";
+export type * from "./engine-contracts.js";
+export { wrapMailerWithPurposeGate, isPurposeGateOpen } from "./purpose-scoped-mailer.js";
+export type { WrapMailerWithPurposeGateOptions, PurposeGateRequired } from "./purpose-scoped-mailer.js";
 export { isMailDeliveryAvailable } from "./delivery-availability.js";
 export { createMailSenderIdentityResolver, NON_DELIVERING_MAIL_DRIVERS, SenderIdentityNotConfiguredError } from "./sender-identity.js";
 export type { ConfiguredMailSender, CreateMailSenderIdentityResolverOptional, MailSenderIdentityPort } from "./sender-identity.js";
@@ -15,4 +17,16 @@ export type { MailDeliveryPolicy, MailDeliveryPolicyDeps, MailDeliveryPolicyOpti
 export { createMailFeedbackIngest, suppressionScopeFor } from "./feedback.js";
 export type { MailFeedbackInboxPort, MailFeedbackIngestDeps, MailFeedbackIngestOptions, MailFeedbackResponse } from "./feedback.js";
 export { createSmtpMailProvider, createConsoleMailProvider, parseSmtpEndpoint } from "./builtin-providers.js";
+export { safeMailProviderText, credentialSecrets } from "./provider-error.js";
+export { readMailDomain, isDomainReadPermissionRefused } from "./domain-read.js";
+export type { MailDomainReadCredentialPort } from "./domain-read.js";
+export { createSenderDomainVerification } from "./sender-domain-verification.js";
+export type { SenderDomainVerificationDeps } from "./sender-domain-verification.js";
+export { createMailPolicyWrapper } from "./delivery-wrapper.js";
+export type { MailPolicyWrapperDeps, MailPolicyWrapperOptions, MailPolicyWrapperInput } from "./delivery-wrapper.js";
+export { createResolvedMailer } from "./resolve-mailer.js";
+export type { ResolveMailerDeps, ResolveMailerOptions, ResolvedMailer } from "./resolve-mailer.js";
+export { createTtlCache, MAIL_STATUS_TTL_MS } from "./mail-status-cache.js";
+export type { TtlCache } from "./mail-status-cache.js";
+export * from "./senders.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/mail/index.js

@@ -1,4 +1,5 @@
-export { wrapMailerWithPurposeGate } from "./purpose-scoped-mailer.js";
+export { createMailAdapterContext } from "./adapter-module.js";
+export { wrapMailerWithPurposeGate, isPurposeGateOpen } from "./purpose-scoped-mailer.js";
 export { isMailDeliveryAvailable } from "./delivery-availability.js";
 export { createMailSenderIdentityResolver, NON_DELIVERING_MAIL_DRIVERS, SenderIdentityNotConfiguredError } from "./sender-identity.js";
 export { createMailProviderRegistry, validateMailProvider, initialMailProviderSetting, computeMailStatus, MAIL_PROVIDER_SETTING_KEY } from "./provider.js";
@@ -6,4 +7,11 @@ export { createMailLaneLimiter } from "./rate-limit.js";
 export { createMailDeliveryPolicy, createPolicyMailer, laneForPurpose, hasOneClickUnsubscribe, mailPayloadHash, MAIL_RATE_LIMITED, isMailRateLimited } from "./policy.js";
 export { createMailFeedbackIngest, suppressionScopeFor } from "./feedback.js";
 export { createSmtpMailProvider, createConsoleMailProvider, parseSmtpEndpoint } from "./builtin-providers.js";
+export { safeMailProviderText, credentialSecrets } from "./provider-error.js";
+export { readMailDomain, isDomainReadPermissionRefused } from "./domain-read.js";
+export { createSenderDomainVerification } from "./sender-domain-verification.js";
+export { createMailPolicyWrapper } from "./delivery-wrapper.js";
+export { createResolvedMailer } from "./resolve-mailer.js";
+export { createTtlCache, MAIL_STATUS_TTL_MS } from "./mail-status-cache.js";
+export * from "./senders.js";
 //# sourceMappingURL=index.js.map

package/dist/mail/mail-status-cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file A short-TTL, single-flight cache for the mail status report.
+ * Building the report can call the provider (domain status) and decrypt keys, which took 4–9 s per
+ * admin page load; within the TTL every reader shares one result. `refresh` requests a fresh build,
+ * subject to the optional minimum refresh interval.
+ * `invalidate` drops the cached one (a provider switch or a key save). A failed build is never
+ * cached, and a build that started before an invalidation is not stored over it.
+ */
+/** Default freshness window for mail status. */
+export declare const MAIL_STATUS_TTL_MS = 30000;
+export interface TtlCache<T> {
+    get(optional?: {
+        refresh?: boolean;
+    }): Promise<T>;
+    invalidate(): void;
+}
+/**
+ * @param required.load - Builds a fresh value; its rejection reaches every concurrent caller.
+ * @param required.ttlMs - How long a built value is served.
+ * @param required.nowMs - Injected clock.
+ * @param optional.minRefreshIntervalMs - Ignore forced refresh inside this interval after a build
+ *   starts; zero preserves unrestricted superseding refreshes. Invalidation resets the interval.
+ * @complexity O(1) per call; ordinary reads share one pending load. Explicit refresh may supersede it.
+ * @example const cache = createTtlCache({ load, ttlMs: MAIL_STATUS_TTL_MS, nowMs }); await cache.get();
+ */
+export declare function createTtlCache<T>(required: {
+    load: () => Promise<T>;
+    ttlMs: number;
+    nowMs: () => number;
+}, optional?: {
+    minRefreshIntervalMs?: number;
+}): TtlCache<T>;
+//# sourceMappingURL=mail-status-cache.d.ts.map

package/dist/mail/mail-status-cache.js

@@ -0,0 +1,56 @@
+/**
+ * @file A short-TTL, single-flight cache for the mail status report.
+ * Building the report can call the provider (domain status) and decrypt keys, which took 4–9 s per
+ * admin page load; within the TTL every reader shares one result. `refresh` requests a fresh build,
+ * subject to the optional minimum refresh interval.
+ * `invalidate` drops the cached one (a provider switch or a key save). A failed build is never
+ * cached, and a build that started before an invalidation is not stored over it.
+ */
+/** Default freshness window for mail status. */
+export const MAIL_STATUS_TTL_MS = 30_000;
+/**
+ * @param required.load - Builds a fresh value; its rejection reaches every concurrent caller.
+ * @param required.ttlMs - How long a built value is served.
+ * @param required.nowMs - Injected clock.
+ * @param optional.minRefreshIntervalMs - Ignore forced refresh inside this interval after a build
+ *   starts; zero preserves unrestricted superseding refreshes. Invalidation resets the interval.
+ * @complexity O(1) per call; ordinary reads share one pending load. Explicit refresh may supersede it.
+ * @example const cache = createTtlCache({ load, ttlMs: MAIL_STATUS_TTL_MS, nowMs }); await cache.get();
+ */
+export function createTtlCache(required, optional = {}) {
+    let cached;
+    let inFlight;
+    let generation = 0;
+    let lastBuildAt = -Infinity;
+    const start = () => {
+        lastBuildAt = required.nowMs();
+        const startedIn = generation;
+        const started = required.load().then((value) => {
+            if (startedIn === generation)
+                cached = { value, expiresAt: required.nowMs() + required.ttlMs };
+            return value;
+        }).finally(() => { if (inFlight === started)
+            inFlight = undefined; });
+        inFlight = started;
+        return started;
+    };
+    const minRefreshIntervalMs = optional.minRefreshIntervalMs ?? 0;
+    return {
+        get: async (optional = {}) => {
+            if (optional.refresh && required.nowMs() - lastBuildAt >= minRefreshIntervalMs) {
+                generation += 1;
+                return start();
+            }
+            if (cached && required.nowMs() < cached.expiresAt)
+                return cached.value;
+            return inFlight ?? start();
+        },
+        invalidate: () => {
+            generation += 1;
+            cached = undefined;
+            inFlight = undefined;
+            lastBuildAt = -Infinity;
+        },
+    };
+}
+//# sourceMappingURL=mail-status-cache.js.map

package/dist/mail/prepare-sender-email.d.ts

@@ -0,0 +1,35 @@
+import { type EmailSender, type EmailSourceDescription, type EmailSourceField, type EmailSourceRequest, type EmailTemplatePort } from "./email-sender.js";
+import type { EmailAddress } from "./types.js";
+/** Refuses unsupported declarations and undeclared placeholders before activation or rendering.
+ * @complexity O(f + d + p) source fields, declarations and placeholders; no I/O. */
+export declare function validateEmailSourceTemplate(required: {
+    readonly fields: readonly EmailSourceField[];
+    readonly template: {
+        readonly fields: readonly string[];
+        readonly placeholders: readonly string[];
+    };
+}, _optional?: Record<string, never>): void;
+/** A preparation result is suitable for freezing in the sender's existing job, never a new queue. */
+export interface PreparedSenderEmail {
+    readonly bindingId: string;
+    readonly templateId: string;
+    readonly templateVersion: string;
+    readonly to: EmailAddress;
+    readonly replyTo: EmailAddress;
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+    readonly purpose: EmailSourceDescription["purpose"];
+    readonly lane: EmailSourceDescription["lane"];
+    readonly warnings: readonly string[];
+}
+/** Resolves authoritative event data and the saved binding, then calls the existing renderer.
+ * No preview samples, envelope overrides or delivery effects enter this operation.
+ * @throws EmailSenderError for ownership, inactive/pre-activation events, readiness, compatibility or missing data; port errors propagate.
+ * @complexity O(fields + declarations + placeholders); one describe, resolve and render per event. */
+export declare function prepareSenderEmail(required: EmailSourceRequest & {
+    readonly sender: EmailSender;
+    readonly templates: EmailTemplatePort;
+    readonly eventId: string;
+}, _optional?: Record<string, never>): Promise<PreparedSenderEmail>;
+//# sourceMappingURL=prepare-sender-email.d.ts.map

package/dist/mail/prepare-sender-email.js

@@ -0,0 +1,68 @@
+import { EmailSenderError } from "./email-sender.js";
+/** Refuses unsupported declarations and undeclared placeholders before activation or rendering.
+ * @complexity O(f + d + p) source fields, declarations and placeholders; no I/O. */
+export function validateEmailSourceTemplate(required, _optional = {}) {
+    const available = new Set(required.fields.map(field => field.token));
+    const declared = new Set(required.template.fields);
+    if (required.template.fields.some(token => !available.has(token)))
+        throw new EmailSenderError({ code: "incompatible" });
+    if (required.template.placeholders.some(token => !declared.has(token)))
+        throw new EmailSenderError({ code: "incompatible" });
+}
+/** Selects declared values, refusing missing required answers and warning on absent optional ones. */
+function templateValues(required, _optional = {}) {
+    const fields = new Map(required.fields.map(field => [field.token, field]));
+    const warnings = [];
+    const values = Object.fromEntries(required.tokens.map(token => {
+        const value = Object.hasOwn(required.values, token) ? required.values[token] : undefined;
+        if (typeof value === "string" && value !== "")
+            return [token, value];
+        if (fields.get(token)?.required)
+            throw new EmailSenderError({ code: "missing_value" });
+        warnings.push(token);
+        return [token, ""];
+    }));
+    return { values, warnings };
+}
+/** Resolves only a source-permitted recipient; configuration and missing answers fail separately.
+ * @complexity O(permitted choices + resolved recipients); no I/O. */
+function recipientAddress({ source, resolved, recipientId }, _optional = {}) {
+    if (!source.permittedRecipients.some(choice => choice.id === recipientId))
+        throw new EmailSenderError({ code: "configuration" });
+    const recipient = resolved.recipients.find(choice => choice.id === recipientId);
+    if (!recipient)
+        throw new EmailSenderError({ code: "missing_value" });
+    return recipient.address;
+}
+/** Resolves authoritative event data and the saved binding, then calls the existing renderer.
+ * No preview samples, envelope overrides or delivery effects enter this operation.
+ * @throws EmailSenderError for ownership, inactive/pre-activation events, readiness, compatibility or missing data; port errors propagate.
+ * @complexity O(fields + declarations + placeholders); one describe, resolve and render per event. */
+export async function prepareSenderEmail(required, _optional = {}) {
+    const { sender, templates, workspaceId, principalId, sourceId, eventId } = required;
+    const context = { workspaceId, principalId, sourceId };
+    const source = await sender.describeSource(context);
+    if (source.senderId !== sender.id || source.sourceId !== sourceId)
+        throw new EmailSenderError({ code: "ownership" });
+    const binding = source.binding;
+    if (!binding?.enabled)
+        throw new EmailSenderError({ code: "configuration" });
+    if (!source.readiness.ready)
+        throw new EmailSenderError({ code: "not_ready" });
+    const templateContext = { workspaceId, principalId, templateId: binding.templateId };
+    const template = await templates.describe(templateContext);
+    validateEmailSourceTemplate({ fields: source.fields, template });
+    const resolved = await sender.resolveEvent({ ...context, eventId });
+    // MOVE: Compare against the latest activation so re-enabling cannot revive a backlog.
+    if (!binding.activatedAt || !(Date.parse(resolved.occurredAt) >= Date.parse(binding.activatedAt)))
+        throw new EmailSenderError({ code: "configuration" });
+    const to = recipientAddress({ source, resolved, recipientId: binding.recipientId });
+    const { values, warnings } = templateValues({ fields: source.fields, tokens: template.fields, values: resolved.values });
+    const rendered = await templates.render({ ...templateContext, version: template.version, values });
+    if (rendered.missingFields.length > 0)
+        throw new EmailSenderError({ code: "missing_value" });
+    return { bindingId: binding.bindingId, templateId: binding.templateId, templateVersion: template.version, to,
+        replyTo: { email: binding.replyTo }, subject: rendered.subject, html: rendered.html, text: rendered.text,
+        purpose: source.purpose, lane: source.lane, warnings };
+}
+//# sourceMappingURL=prepare-sender-email.js.map

package/dist/mail/provider.js

@@ -21,11 +21,14 @@ export function validateMailProvider({ provider }) {
     // A capability claim without the code behind it is how Resend once advertised feedback with no route.
     if (caps.feedback !== (provider.feedback !== undefined))
         return "capabilities.feedback must match the presence of a feedback parser";
-    const hasDomain = typeof provider.domainRequirements === "function" && typeof provider.domainStatus === "function";
+    const hasDomain = hasDomainVerification(provider);
     if (caps.domainVerification !== hasDomain)
         return "capabilities.domainVerification must match domainRequirements + domainStatus";
     return undefined;
 }
+function hasDomainVerification(provider) {
+    return typeof provider.domainRequirements === "function" && typeof provider.domainStatus === "function";
+}
 /** Mail registry over the shared keyed registry; built-ins throw on a bad registration, plugins are refused. */
 export function createMailProviderRegistry(_required = {}, optional = {}) {
     const seed = (optional.builtins ?? []).map((provider) => ({ id: provider.id, provider, label: provider.label }));

package/dist/mail/resolve-mailer.d.ts

@@ -0,0 +1,95 @@
+import type { HttpClientPort } from "@jini-ai/core/primitives";
+import type { DomainRequirement } from "@jini-ai/core/provider-registry";
+import type { MailAdapterCredential } from "./adapter-module.js";
+import { type MailDomainReadCredentialPort } from "./domain-read.js";
+import type { MailCredentialFact, MailCredentialPort, MailProviderCatalog, MailProviderCheck, MailProviderConfigurationReport, MailProviderSettingPort, MailStatusReport, SenderDomainVerificationPort } from "./engine-contracts.js";
+import type { MailDeliveryLane, MailerPort } from "./ports.js";
+import { type MailProviderModule, type MailProviderSetting } from "./provider.js";
+/** Required host boundaries. HTTP is passed through unchanged; the engine never calls it. */
+export interface ResolveMailerDeps<TRecord extends MailCredentialFact = MailCredentialFact> {
+    workspaceId: string;
+    mode: "local" | "production";
+    providerSetting: MailProviderSettingPort;
+    credentials: MailCredentialPort;
+    /** Metadata only. Preserve the host's row shape for its projection (e.g. SMTP username presence);
+     * the engine only interprets the separate readFact fingerprint. No decryption here. */
+    listCredentialFacts: (required: Record<string, never>) => Promise<readonly TRecord[]>;
+    loadCatalog: (required: Record<string, never>) => Promise<MailProviderCatalog>;
+    httpClient: HttpClientPort;
+    /** Host retains provider ABI binding and credential-aware scrubbing of results/throws. */
+    createProviderMailer: (required: {
+        provider: MailProviderModule;
+        credential: MailAdapterCredential;
+    }) => MailerPort;
+    /** Synchronous safe DTO projection; labels, setup forms and product copy stay in the host. */
+    describeProviders: (required: {
+        catalog: MailProviderCatalog;
+        records: readonly TRecord[];
+        setting: MailProviderSetting;
+    }) => MailProviderConfigurationReport;
+    unconfiguredMessage: (required: {
+        lane: MailDeliveryLane;
+    }) => string;
+    missingCredentialReason: (required: {
+        label: string;
+    }) => string;
+    credentialFailureReason: (required: {
+        label: string;
+        err: unknown;
+    }) => string;
+}
+export interface ResolveMailerOptions {
+    /** Delivery policy decorator; identity when absent. */
+    wrapProviderMailer?: (required: {
+        providerId: string;
+        provider: MailProviderModule;
+        mailer: MailerPort;
+    }) => MailerPort;
+    readSenderEmail?: () => Promise<string | undefined>;
+    resolveDomainReadCredential?: MailDomainReadCredentialPort;
+    warn?: (message: string) => void;
+    clock?: {
+        nowMs(): number;
+    };
+    statusTtlMs?: number;
+    domainRequirementsTimeoutMs?: number;
+}
+/** The control surface remains stable across host adoption, including invalidate on setting writes. */
+export interface ResolvedMailer {
+    /** Safe to use immediately; each send awaits its lane's resolution. */
+    mailer: MailerPort;
+    /** Resolves once the initial setting + transactional resolution settle (a test seam). */
+    ready: Promise<void>;
+    /** Refreshes unresolved configuration and awaits the current driver without sending. */
+    settle: () => Promise<void>;
+    /** Cached briefly; `refresh` rebuilds. Each report carries `checkedAt` and the live `lastError`. */
+    status: (optional?: {
+        refresh?: boolean;
+    }) => Promise<MailStatusReport>;
+    /** The host's safe per-provider configuration DTO. Never a secret. */
+    describeProviders: () => Promise<MailProviderConfigurationReport>;
+    /** Drops cached provider mailers and the cached status; the next send and read resolve fresh. */
+    invalidate: () => void;
+    laneReady: (required: {
+        lane: MailDeliveryLane;
+    }) => Promise<boolean>;
+    senderDomainVerification: SenderDomainVerificationPort;
+    /** Whether `id` may be selected: a registered hosted provider whose saved key resolves. Sends nothing. */
+    checkProvider: (required: {
+        id: string;
+    }) => Promise<MailProviderCheck>;
+    /** Null for another workspace, absent sender/provider/key or unsupported verification.
+     * Provider failures throw caller-safe ToolInputError; the deadline throws Error. */
+    domainRequirements: (required: {
+        workspaceId: string;
+    }) => Promise<DomainRequirement | null>;
+}
+/**
+ * Build a lane router and its control surface. The host binds catalogs, secrets, safe copy and DTOs.
+ * Each send reads selection and metadata; boot starts resolution synchronously. Selection faults
+ * refuse safely; status/description setup faults propagate and are never cached.
+ * @complexity O(providers) cached mailers/flights; status holds one report for its TTL.
+ * @example const control = createResolvedMailer(hostPorts, { clock }); await control.ready;
+ */
+export declare function createResolvedMailer<TRecord extends MailCredentialFact = MailCredentialFact>(required: ResolveMailerDeps<TRecord>, optional?: ResolveMailerOptions): ResolvedMailer;
+//# sourceMappingURL=resolve-mailer.d.ts.map