@volter/twin-postmark 0.1.0

package/dist/src/postmark-conformance.d.ts

@@ -0,0 +1,33 @@
+import { specConformance } from '@volter/world-tooling';
+type JsonSchema = specConformance.JsonSchema;
+type KnownDeviation = specConformance.KnownDeviation;
+type SpecViolation = specConformance.SpecViolation;
+export type PostmarkViolation = SpecViolation & {
+    object: string;
+    id: string;
+};
+export type PostmarkConformanceReport = {
+    ok: boolean;
+    resourcesChecked: number;
+    fieldsChecked: number;
+    violations: PostmarkViolation[];
+    knownIgnored: number;
+};
+export declare function loadPostmarkSchemas(): Record<string, JsonSchema>;
+/**
+ * Validate every Postmark resource the twin serves (in `root`) against its schema. A wrong
+ * type, an undeclared missing-required field, or an enum violation fails the report.
+ * Soft-deleted rows are skipped — a tombstone is not a served resource.
+ */
+export declare function checkPostmarkConformance(opts?: {
+    root?: string;
+    known?: KnownDeviation[];
+}): PostmarkConformanceReport;
+export type PostmarkCoverageReport = specConformance.SpecCoverageReport & {
+    object: string;
+};
+/** Per-object coverage: of the fields each Postmark object declares, which does the twin emit? */
+export declare function postmarkCoverage(opts?: {
+    root?: string;
+}): PostmarkCoverageReport[];
+export {};

package/dist/src/postmark-conformance.js

@@ -0,0 +1,265 @@
+// Postmark twin conformance — spec-true validation of the resources the twin serves against
+// per-object JSON Schemas (required fields, types, enums), offline (no key).
+//
+// The schemas below are transcribed from the OFFICIAL `postmark` SDK's own TypeScript models
+// (node_modules/postmark/dist/client/models/**/*.d.ts) — a first-party artifact naming every
+// field and its type. Postmark's API cannot be dual-run against a live sandbox in CI, so
+// those published shapes carry the weight here.
+//
+// For every resource the twin emits, validate its body via the shared specConformance
+// harness: declared TYPES, REQUIRED fields (omission), ENUMS. Twin-internal `_`-prefixed
+// fields are exempt; polymorphic/nested blocks (Triggers, Metadata, MessageEvents, DNS
+// detail) are left untyped to avoid false positives.
+import { twinResources } from '@volter/world-core';
+import { specConformance } from '@volter/world-tooling';
+const SCHEMAS = {
+    // SDK: models/messages/OutboundMessage.d.ts
+    message: {
+        type: 'object',
+        required: ['MessageID', 'From', 'Recipients', 'ReceivedAt', 'Status', 'MessageStream'],
+        properties: {
+            MessageID: { type: 'string' },
+            From: { type: 'string' },
+            Subject: { type: 'string' },
+            To: { type: 'array' },
+            Cc: { type: 'array' },
+            Bcc: { type: 'array' },
+            Recipients: { type: 'array' },
+            Attachments: { type: 'array' },
+            ReceivedAt: { type: 'string' },
+            Tag: { type: 'string' },
+            Status: { type: 'string', enum: ['Sent', 'Queued', 'Processed'] },
+            TrackOpens: { type: 'boolean' },
+            TrackLinks: { type: 'string', enum: ['None', 'HtmlAndText', 'HtmlOnly', 'TextOnly'] },
+            MessageStream: { type: 'string' },
+            Sandboxed: { type: 'boolean' },
+            MessageEvents: { type: 'array' },
+        },
+    },
+    // SDK: models/bounces/Bounce.d.ts (+ BounceType / BounceTypeCode enums)
+    bounce: {
+        type: 'object',
+        required: ['RecordType', 'ID', 'Type', 'TypeCode', 'Name', 'Email', 'BouncedAt', 'MessageStream'],
+        properties: {
+            RecordType: { type: 'string', enum: ['Bounce'] },
+            ID: { type: 'number' },
+            Type: { type: 'string', enum: ['HardBounce', 'Transient', 'SoftBounce', 'SpamComplaint', 'SpamNotification', 'Unsubscribe', 'AutoResponder', 'DnsError', 'BadEmailAddress', 'Blocked', 'ManuallyDeactivated', 'Unknown'] },
+            TypeCode: { type: 'number' },
+            Name: { type: 'string' },
+            Tag: { type: 'string' },
+            MessageID: { type: 'string' },
+            ServerID: { type: 'number' },
+            Description: { type: 'string' },
+            Details: { type: 'string' },
+            Email: { type: 'string' },
+            From: { type: 'string' },
+            BouncedAt: { type: 'string' },
+            DumpAvailable: { type: 'boolean' },
+            Inactive: { type: 'boolean' },
+            CanActivate: { type: 'boolean' },
+            Subject: { type: 'string' },
+            MessageStream: { type: 'string' },
+        },
+    },
+    // SDK: models/templates/Template.d.ts (+ TemplateTypes enum)
+    template: {
+        type: 'object',
+        required: ['TemplateId', 'Name', 'TemplateType', 'Active'],
+        properties: {
+            TemplateId: { type: 'number' },
+            Name: { type: 'string' },
+            TemplateType: { type: 'string', enum: ['Standard', 'Layout'] },
+            Subject: { type: 'string' },
+            Active: { type: 'boolean' },
+            AssociatedServerId: { type: 'number' },
+        },
+    },
+    // SDK: models/streams/MessageStream.d.ts
+    message_stream: {
+        type: 'object',
+        required: ['ID', 'ServerID', 'Name', 'MessageStreamType', 'CreatedAt'],
+        properties: {
+            ID: { type: 'string' },
+            ServerID: { type: 'number' },
+            Name: { type: 'string' },
+            Description: { type: 'string' },
+            MessageStreamType: { type: 'string', enum: ['Transactional', 'Broadcast', 'Inbound'] },
+            CreatedAt: { type: 'string' },
+        },
+    },
+    // SDK: models/webhooks/Webhook.d.ts
+    webhook: {
+        type: 'object',
+        required: ['ID', 'Url', 'MessageStream'],
+        properties: {
+            ID: { type: 'number' },
+            Url: { type: 'string' },
+            MessageStream: { type: 'string' },
+            HttpHeaders: { type: 'array' },
+        },
+    },
+    // SDK: models/suppressions/Suppression.d.ts (+ SuppressionReason / SuppressionOrigin enums)
+    suppression: {
+        type: 'object',
+        required: ['EmailAddress', 'SuppressionReason', 'Origin', 'CreatedAt'],
+        properties: {
+            EmailAddress: { type: 'string' },
+            SuppressionReason: { type: 'string', enum: ['HardBounce', 'SpamComplaint', 'ManualSuppression'] },
+            Origin: { type: 'string', enum: ['Recipient', 'Customer', 'Admin'] },
+            CreatedAt: { type: 'string' },
+            MessageStream: { type: 'string' },
+        },
+    },
+    // SDK: models/server/Server.d.ts (+ ServerDeliveryTypes enum)
+    server: {
+        type: 'object',
+        required: ['ID', 'Name', 'DeliveryType'],
+        properties: {
+            ID: { type: 'number' },
+            Name: { type: 'string' },
+            ApiTokens: { type: 'array' },
+            ServerLink: { type: 'string' },
+            Color: { type: 'string' },
+            SmtpApiActivated: { type: 'boolean' },
+            RawEmailEnabled: { type: 'boolean' },
+            DeliveryType: { type: 'string', enum: ['Live', 'Sandbox'] },
+            InboundAddress: { type: 'string' },
+            InboundHash: { type: 'string' },
+            InboundSpamThreshold: { type: 'number' },
+            TrackOpens: { type: 'boolean' },
+            TrackLinks: { type: 'string', enum: ['None', 'HtmlAndText', 'HtmlOnly', 'TextOnly'] },
+            PostFirstOpenOnly: { type: 'boolean' },
+        },
+    },
+    // SDK: models/domains/Domain.d.ts (DomainDetails)
+    domain: {
+        type: 'object',
+        required: ['ID', 'Name', 'SPFVerified', 'DKIMVerified', 'ReturnPathDomainVerified'],
+        properties: {
+            ID: { type: 'number' },
+            Name: { type: 'string' },
+            SPFVerified: { type: 'boolean' },
+            DKIMVerified: { type: 'boolean' },
+            WeakDKIM: { type: 'boolean' },
+            ReturnPathDomainVerified: { type: 'boolean' },
+            SPFHost: { type: 'string' },
+            SPFTextValue: { type: 'string' },
+            DKIMHost: { type: 'string' },
+            DKIMTextValue: { type: 'string' },
+            DKIMUpdateStatus: { type: 'string' },
+            ReturnPathDomain: { type: 'string' },
+            ReturnPathDomainCNAMEValue: { type: 'string' },
+        },
+    },
+    // SDK: models/senders/Signature.d.ts (SignatureDetails extends DomainDetails)
+    sender_signature: {
+        type: 'object',
+        required: ['ID', 'Domain', 'EmailAddress', 'Name', 'Confirmed'],
+        properties: {
+            ID: { type: 'number' },
+            Domain: { type: 'string' },
+            EmailAddress: { type: 'string' },
+            ReplyToEmailAddress: { type: 'string' },
+            Name: { type: 'string' },
+            Confirmed: { type: 'boolean' },
+            ConfirmationPersonalNote: { type: 'string' },
+        },
+    },
+    // SDK: models/triggers/InboundRule.d.ts
+    inbound_rule: {
+        type: 'object',
+        required: ['ID', 'Rule'],
+        properties: { ID: { type: 'number' }, Rule: { type: 'string' } },
+    },
+    // SDK: models/messages/InboundMessage.d.ts
+    inbound_message: {
+        type: 'object',
+        required: ['MessageID', 'From', 'To', 'Date', 'Status', 'MessageStream'],
+        properties: {
+            MessageID: { type: 'string' },
+            From: { type: 'string' },
+            FromName: { type: 'string' },
+            To: { type: 'string' },
+            Cc: { type: 'string' },
+            Bcc: { type: 'string' },
+            Subject: { type: 'string' },
+            Date: { type: 'string' },
+            MailboxHash: { type: 'string' },
+            Tag: { type: 'string' },
+            Status: { type: 'string', enum: ['queued', 'sent', 'processed', 'blocked', 'failed', 'scheduled', 'Queued', 'Sent', 'Processed', 'Blocked', 'Failed', 'Scheduled'] },
+            Attachments: { type: 'array' },
+            MessageStream: { type: 'string' },
+        },
+    },
+    // SDK: models/data_removal/DataRemoval.d.ts
+    data_removal: {
+        type: 'object',
+        required: ['ID', 'Status'],
+        properties: {
+            ID: { type: 'number' },
+            Status: { type: 'string', enum: ['Pending', 'Done'] },
+            RequestedBy: { type: 'string' },
+            RequestedFor: { type: 'string' },
+            NotifyWhenCompleted: { type: 'boolean' },
+        },
+    },
+};
+// twin resource type → schema key (1:1 here).
+const TYPE_TO_OBJECT = Object.fromEntries(Object.keys(SCHEMAS).map((k) => [k, k]));
+const isTwinExtra = (k) => k.startsWith('_');
+/** The emitted body: drop kernel meta + twin-internal fields. */
+function emitted(r) {
+    const out = {};
+    for (const [k, v] of Object.entries(r)) {
+        if (k === 'type' || k === 'id' || k === 'updatedAt' || k.startsWith('_'))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+export function loadPostmarkSchemas() {
+    return SCHEMAS;
+}
+/**
+ * Validate every Postmark resource the twin serves (in `root`) against its schema. A wrong
+ * type, an undeclared missing-required field, or an enum violation fails the report.
+ * Soft-deleted rows are skipped — a tombstone is not a served resource.
+ */
+export function checkPostmarkConformance(opts = {}) {
+    const resources = twinResources('postmark', opts.root)
+        .filter((r) => !r.type.startsWith('_') && r.deleted !== true);
+    const violations = [];
+    let fieldsChecked = 0;
+    let knownIgnored = 0;
+    for (const r of resources) {
+        const objectName = TYPE_TO_OBJECT[r.type];
+        if (!objectName)
+            continue;
+        const schema = SCHEMAS[objectName];
+        if (!schema)
+            continue;
+        const rep = specConformance.checkSpecConformance(emitted(r), schema, { exemptKey: isTwinExtra, known: opts.known ?? [], flagExtra: false });
+        fieldsChecked += rep.fieldsChecked;
+        knownIgnored += rep.knownIgnored;
+        for (const v of rep.violations)
+            violations.push({ ...v, object: objectName, id: r.id });
+    }
+    return { ok: violations.length === 0, resourcesChecked: resources.length, fieldsChecked, violations, knownIgnored };
+}
+/** Per-object coverage: of the fields each Postmark object declares, which does the twin emit? */
+export function postmarkCoverage(opts = {}) {
+    const byType = new Map();
+    for (const r of twinResources('postmark', opts.root)) {
+        if (!r.type.startsWith('_') && !byType.has(r.type) && r.deleted !== true)
+            byType.set(r.type, r);
+    }
+    const out = [];
+    for (const [type, r] of byType) {
+        const objectName = TYPE_TO_OBJECT[type];
+        const schema = objectName ? SCHEMAS[objectName] : undefined;
+        if (!objectName || !schema)
+            continue;
+        out.push({ object: objectName, ...specConformance.specCoverage(schema, emitted(r), { exemptKey: isTwinExtra }) });
+    }
+    return out;
+}

package/dist/src/postmark-connector.d.ts

@@ -0,0 +1,167 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+/**
+ * The injected real-Postmark boundary — the subset of `postmark`'s `ServerClient` this
+ * connector uses. A real `new ServerClient(token)` is structurally assignable; tests pass a
+ * fake. Only the methods the connector calls are declared, so the surface stays honest.
+ * Unlike Resend's `{data, error}` envelope, the Postmark SDK RESOLVES with the payload and
+ * REJECTS with a typed `PostmarkError` — this interface mirrors that.
+ */
+export interface PostmarkClient {
+    getOutboundMessages(filter?: Record<string, unknown>): Promise<{
+        TotalCount: number | string;
+        Messages: PostmarkOutboundMessage[];
+    }>;
+    getBounces(filter?: Record<string, unknown>): Promise<{
+        TotalCount: number;
+        Bounces: PostmarkBounce[];
+    }>;
+    getTemplates(filter?: Record<string, unknown>): Promise<{
+        TotalCount: number;
+        Templates: PostmarkTemplate[];
+    }>;
+    getMessageStreams(filter?: Record<string, unknown>): Promise<{
+        TotalCount: number;
+        MessageStreams: PostmarkMessageStream[];
+    }>;
+    getWebhooks(filter?: Record<string, unknown>): Promise<{
+        Webhooks: PostmarkWebhookConfig[];
+    }>;
+    getServer(): Promise<PostmarkServer>;
+    sendEmail(message: Record<string, unknown>): Promise<{
+        MessageID: string;
+        ErrorCode: number;
+        Message: string;
+    }>;
+    createTemplate(options: Record<string, unknown>): Promise<{
+        TemplateId: number;
+    }>;
+    createWebhook(options: Record<string, unknown>): Promise<{
+        ID: number;
+    }>;
+    createMessageStream(options: Record<string, unknown>): Promise<{
+        ID: string;
+    }>;
+}
+export type PostmarkRecipient = {
+    Email?: string;
+    Name?: string;
+};
+export type PostmarkOutboundMessage = {
+    MessageID: string;
+    Tag?: string;
+    To?: PostmarkRecipient[];
+    Cc?: PostmarkRecipient[];
+    Bcc?: PostmarkRecipient[];
+    Recipients?: string[];
+    ReceivedAt?: string;
+    From?: string;
+    Subject?: string;
+    Attachments?: string[];
+    Status?: string;
+    TrackOpens?: boolean;
+    TrackLinks?: string;
+    Metadata?: Record<string, string>;
+    MessageStream?: string;
+    Sandboxed?: boolean;
+};
+export type PostmarkBounce = {
+    ID: number;
+    Type?: string;
+    TypeCode?: number;
+    Name?: string;
+    Tag?: string;
+    MessageID?: string;
+    ServerID?: number;
+    Description?: string;
+    Details?: string;
+    Email?: string;
+    From?: string;
+    BouncedAt?: string;
+    DumpAvailable?: boolean;
+    Inactive?: boolean;
+    CanActivate?: boolean;
+    Subject?: string;
+    MessageStream?: string;
+};
+export type PostmarkTemplate = {
+    TemplateId: number;
+    Name?: string;
+    Alias?: string | null;
+    TemplateType?: string;
+    Active?: boolean;
+    LayoutTemplate?: string | null;
+    Subject?: string;
+    HtmlBody?: string | null;
+    TextBody?: string | null;
+};
+export type PostmarkMessageStream = {
+    ID: string;
+    ServerID?: number;
+    Name?: string;
+    Description?: string;
+    MessageStreamType?: string;
+    CreatedAt?: string;
+    UpdatedAt?: string | null;
+    ArchivedAt?: string | null;
+    SubscriptionManagementConfiguration?: Record<string, unknown>;
+};
+export type PostmarkWebhookConfig = {
+    ID: number;
+    Url?: string;
+    MessageStream?: string;
+    HttpAuth?: Record<string, unknown> | null;
+    HttpHeaders?: Array<Record<string, unknown>>;
+    Triggers?: Record<string, unknown>;
+};
+export type PostmarkServer = {
+    ID: number;
+    Name?: string;
+    Color?: string;
+    DeliveryType?: string;
+    TrackOpens?: boolean;
+    TrackLinks?: string;
+    InboundAddress?: string;
+    ServerLink?: string;
+    SmtpApiActivated?: boolean;
+};
+export declare function mapMessage(m: PostmarkOutboundMessage): SyncResource;
+export declare function mapBounce(b: PostmarkBounce): SyncResource;
+export declare function mapTemplate(t: PostmarkTemplate): SyncResource;
+export declare function mapMessageStream(s: PostmarkMessageStream): SyncResource;
+export declare function mapWebhook(w: PostmarkWebhookConfig): SyncResource;
+export declare function mapServer(s: PostmarkServer): SyncResource;
+export declare function pullPostmarkMessages(client: PostmarkClient): Promise<SyncResource[]>;
+export declare function pullPostmarkBounces(client: PostmarkClient): Promise<SyncResource[]>;
+export declare function pullPostmarkTemplates(client: PostmarkClient): Promise<SyncResource[]>;
+export declare function pullPostmarkMessageStreams(client: PostmarkClient): Promise<SyncResource[]>;
+export declare function pullPostmarkWebhooks(client: PostmarkClient): Promise<SyncResource[]>;
+export declare function pullPostmarkServer(client: PostmarkClient): Promise<SyncResource[]>;
+/**
+ * D7 entry point: pull from real Postmark and fold everything into the twin (mirror seeding).
+ * Callers never have to know the per-domain `pull*` mechanics.
+ */
+export declare function syncPostmarkFromReal(client: PostmarkClient, opts: {
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * Push ONE pending action to REAL Postmark via the injected client. Returns the real external
+ * id (the Postmark object id from the response). WRITES TO THE REAL ACCOUNT (sends real email).
+ */
+export declare function pushPostmarkAction(client: PostmarkClient, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>): Promise<{
+    externalId: string;
+}>;
+/** A PostmarkClient over the kernel's executor. At a REAL boundary the kernel's executor sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export declare function postmarkClientOver(execute: RemoteExecute): PostmarkClient;
+/** The refresh adapter: pull the account's state through the executor and fold it into the root. */
+export declare function syncPostmarkFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<ReturnType<typeof syncPostmarkFromReal>>;
+/** The perform adapter: a message send crosses; everything else is the twin's own record. */
+export declare function performPostmarkAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;