npm - @shamanic-technologies/email-domain-contract - Versions diffs - 1.0.1 - Mend

@shamanic-technologies/email-domain-contract 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Shamanic Technologies
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,79 @@
+# @shamanic-technologies/email-domain-contract
+Single source of truth for the cross-provider canonical shapes used by the email-domain services:
+- [postmark-service](https://github.com/shamanic-technologies/postmark-service) — transactional email via Postmark
+- [instantly-service](https://github.com/shamanic-technologies/instantly-service) — broadcast email via Instantly.ai
+- [email-gateway-service](https://github.com/shamanic-technologies/email-gateway-service) — domain-level router + cross-provider stats/status projection
+## Why this exists
+The three services historically duplicated Zod schemas (`StatusScope`, `RecipientStats`, `EmailStats`, `RepliesDetail`, `StepStats`, `ChannelStats`, `ProviderStatus`, `GlobalStatus`, `ReplyClassification`). Drift emerged: instantly-service had `cancelled` and `notSending`, postmark-service did not, email-gateway dropped them silently. This package puts the canonical shapes in one place so a change in one service forces a discussion across all of them.
+## Install
+```bash
+npm install @shamanic-technologies/email-domain-contract
+```
+Published to the public npm registry — no `.npmrc` override or auth token needed.
+## Usage
+```ts
+import {
+  StatusScopeSchema,
+  RecipientStatsSchema,
+  EmailStatsSchema,
+  type StatusScope,
+  type RecipientStats,
+} from "@shamanic-technologies/email-domain-contract";
+// Validate at trust boundaries (incoming webhooks, cross-service replies)
+const validated = StatusScopeSchema.parse(rawResponse);
+// Or type-only when the data was already validated upstream
+function process(scope: StatusScope): void { /* ... */ }
+```
+## Exported schemas + types
+| Schema | Type | Description |
+|--------|------|-------------|
+| `ReplyClassificationSchema` | `ReplyClassification` | `"positive" \| "negative" \| "neutral"` |
+| `RepliesDetailSchema` | `RepliesDetail` | Granular reply breakdown (9 keys) |
+| `RecipientStatsSchema` | `RecipientStats` | Recipient-level stats (COUNT DISTINCT lead) |
+| `StepStatsSchema` | `StepStats` | Per-step breakdown (broadcast sequences) |
+| `EmailStatsSchema` | `EmailStats` | Email-level stats (COUNT *) |
+| `ChannelStatsSchema` | `ChannelStats` | `{ recipientStats, emailStats }` |
+| `StatusScopeSchema` | `StatusScope` | Per-scope delivery state for one recipient |
+| `GlobalStatusSchema` | `GlobalStatus` | Org-wide bounce/unsubscribe signals |
+| `ProviderStatusSchema` | `ProviderStatus` | Full status payload from one provider |
+## Provider-specific fields
+Two fields are currently provider-specific:
+- `cancelled` (on `StatusScope` and `RecipientStats`) — Instantly only (retry-stuck cancellation)
+- `notSending` (on `RecipientStats`) — Instantly only (`not_sending_status` diagnostic)
+In v1 they are **optional** so postmark-service can return responses without them. v2 will tighten them to **required** once postmark-service ships padding (`cancelled: false`, `notSending: 0`).
+## Versioning
+[Semantic Versioning](https://semver.org/). Breaking changes to any schema = major bump. Additions = minor.
+## Publish
+Pushing a `v*` tag triggers `.github/workflows/publish.yml`, which runs tests, builds, and publishes to the public npm registry with provenance attestation.
+```bash
+npm version major | minor | patch
+git push --follow-tags
+```
+Bootstrap publish uses a granular NPM token stored as the `NPM_TOKEN` repo secret. Once the package exists on the registry, configure [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) on npmjs.com so subsequent releases use OIDC instead — then revoke `NPM_TOKEN`.
+## License
+MIT

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+export { ReplyClassificationSchema, RepliesDetailSchema, RecipientStatsSchema, StepStatsSchema, EmailStatsSchema, ChannelStatsSchema, StatusScopeSchema, GlobalStatusSchema, ProviderStatusSchema, } from "./schemas";
+export type { ReplyClassification, RepliesDetail, RecipientStats, StepStats, EmailStats, ChannelStats, StatusScope, GlobalStatus, ProviderStatus, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,SAAS,EACT,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC"}

package/dist/index.js ADDED Viewed

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderStatusSchema = exports.GlobalStatusSchema = exports.StatusScopeSchema = exports.ChannelStatsSchema = exports.EmailStatsSchema = exports.StepStatsSchema = exports.RecipientStatsSchema = exports.RepliesDetailSchema = exports.ReplyClassificationSchema = void 0;
+var schemas_1 = require("./schemas");
+Object.defineProperty(exports, "ReplyClassificationSchema", { enumerable: true, get: function () { return schemas_1.ReplyClassificationSchema; } });
+Object.defineProperty(exports, "RepliesDetailSchema", { enumerable: true, get: function () { return schemas_1.RepliesDetailSchema; } });
+Object.defineProperty(exports, "RecipientStatsSchema", { enumerable: true, get: function () { return schemas_1.RecipientStatsSchema; } });
+Object.defineProperty(exports, "StepStatsSchema", { enumerable: true, get: function () { return schemas_1.StepStatsSchema; } });
+Object.defineProperty(exports, "EmailStatsSchema", { enumerable: true, get: function () { return schemas_1.EmailStatsSchema; } });
+Object.defineProperty(exports, "ChannelStatsSchema", { enumerable: true, get: function () { return schemas_1.ChannelStatsSchema; } });
+Object.defineProperty(exports, "StatusScopeSchema", { enumerable: true, get: function () { return schemas_1.StatusScopeSchema; } });
+Object.defineProperty(exports, "GlobalStatusSchema", { enumerable: true, get: function () { return schemas_1.GlobalStatusSchema; } });
+Object.defineProperty(exports, "ProviderStatusSchema", { enumerable: true, get: function () { return schemas_1.ProviderStatusSchema; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qCAUmB;AATjB,oHAAA,yBAAyB,OAAA;AACzB,8GAAA,mBAAmB,OAAA;AACnB,+GAAA,oBAAoB,OAAA;AACpB,0GAAA,eAAe,OAAA;AACf,2GAAA,gBAAgB,OAAA;AAChB,6GAAA,kBAAkB,OAAA;AAClB,4GAAA,iBAAiB,OAAA;AACjB,6GAAA,kBAAkB,OAAA;AAClB,+GAAA,oBAAoB,OAAA"}

package/dist/schemas.d.ts ADDED Viewed

@@ -0,0 +1,242 @@
+import { z } from "zod";
+export declare const ReplyClassificationSchema: z.ZodEnum<{
+    positive: "positive";
+    negative: "negative";
+    neutral: "neutral";
+}>;
+export declare const RepliesDetailSchema: z.ZodObject<{
+    interested: z.ZodNumber;
+    meetingBooked: z.ZodNumber;
+    closed: z.ZodNumber;
+    notInterested: z.ZodNumber;
+    wrongPerson: z.ZodNumber;
+    unsubscribe: z.ZodNumber;
+    neutral: z.ZodNumber;
+    autoReply: z.ZodNumber;
+    outOfOffice: z.ZodNumber;
+}, z.core.$strip>;
+export declare const RecipientStatsSchema: z.ZodObject<{
+    contacted: z.ZodNumber;
+    sent: z.ZodNumber;
+    delivered: z.ZodNumber;
+    opened: z.ZodNumber;
+    bounced: z.ZodNumber;
+    clicked: z.ZodNumber;
+    unsubscribed: z.ZodNumber;
+    notSending: z.ZodOptional<z.ZodNumber>;
+    cancelled: z.ZodOptional<z.ZodNumber>;
+    repliesPositive: z.ZodNumber;
+    repliesNegative: z.ZodNumber;
+    repliesNeutral: z.ZodNumber;
+    repliesAutoReply: z.ZodNumber;
+    repliesDetail: z.ZodObject<{
+        interested: z.ZodNumber;
+        meetingBooked: z.ZodNumber;
+        closed: z.ZodNumber;
+        notInterested: z.ZodNumber;
+        wrongPerson: z.ZodNumber;
+        unsubscribe: z.ZodNumber;
+        neutral: z.ZodNumber;
+        autoReply: z.ZodNumber;
+        outOfOffice: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const StepStatsSchema: z.ZodObject<{
+    step: z.ZodNumber;
+    sent: z.ZodNumber;
+    delivered: z.ZodNumber;
+    opened: z.ZodNumber;
+    clicked: z.ZodNumber;
+    bounced: z.ZodNumber;
+    unsubscribed: z.ZodNumber;
+    repliesPositive: z.ZodNumber;
+    repliesNegative: z.ZodNumber;
+    repliesNeutral: z.ZodNumber;
+    repliesAutoReply: z.ZodNumber;
+    repliesDetail: z.ZodObject<{
+        interested: z.ZodNumber;
+        meetingBooked: z.ZodNumber;
+        closed: z.ZodNumber;
+        notInterested: z.ZodNumber;
+        wrongPerson: z.ZodNumber;
+        unsubscribe: z.ZodNumber;
+        neutral: z.ZodNumber;
+        autoReply: z.ZodNumber;
+        outOfOffice: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const EmailStatsSchema: z.ZodObject<{
+    sent: z.ZodNumber;
+    delivered: z.ZodNumber;
+    opened: z.ZodNumber;
+    clicked: z.ZodNumber;
+    bounced: z.ZodNumber;
+    unsubscribed: z.ZodNumber;
+    stepStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        step: z.ZodNumber;
+        sent: z.ZodNumber;
+        delivered: z.ZodNumber;
+        opened: z.ZodNumber;
+        clicked: z.ZodNumber;
+        bounced: z.ZodNumber;
+        unsubscribed: z.ZodNumber;
+        repliesPositive: z.ZodNumber;
+        repliesNegative: z.ZodNumber;
+        repliesNeutral: z.ZodNumber;
+        repliesAutoReply: z.ZodNumber;
+        repliesDetail: z.ZodObject<{
+            interested: z.ZodNumber;
+            meetingBooked: z.ZodNumber;
+            closed: z.ZodNumber;
+            notInterested: z.ZodNumber;
+            wrongPerson: z.ZodNumber;
+            unsubscribe: z.ZodNumber;
+            neutral: z.ZodNumber;
+            autoReply: z.ZodNumber;
+            outOfOffice: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const ChannelStatsSchema: z.ZodObject<{
+    recipientStats: z.ZodObject<{
+        contacted: z.ZodNumber;
+        sent: z.ZodNumber;
+        delivered: z.ZodNumber;
+        opened: z.ZodNumber;
+        bounced: z.ZodNumber;
+        clicked: z.ZodNumber;
+        unsubscribed: z.ZodNumber;
+        notSending: z.ZodOptional<z.ZodNumber>;
+        cancelled: z.ZodOptional<z.ZodNumber>;
+        repliesPositive: z.ZodNumber;
+        repliesNegative: z.ZodNumber;
+        repliesNeutral: z.ZodNumber;
+        repliesAutoReply: z.ZodNumber;
+        repliesDetail: z.ZodObject<{
+            interested: z.ZodNumber;
+            meetingBooked: z.ZodNumber;
+            closed: z.ZodNumber;
+            notInterested: z.ZodNumber;
+            wrongPerson: z.ZodNumber;
+            unsubscribe: z.ZodNumber;
+            neutral: z.ZodNumber;
+            autoReply: z.ZodNumber;
+            outOfOffice: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    emailStats: z.ZodObject<{
+        sent: z.ZodNumber;
+        delivered: z.ZodNumber;
+        opened: z.ZodNumber;
+        clicked: z.ZodNumber;
+        bounced: z.ZodNumber;
+        unsubscribed: z.ZodNumber;
+        stepStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            step: z.ZodNumber;
+            sent: z.ZodNumber;
+            delivered: z.ZodNumber;
+            opened: z.ZodNumber;
+            clicked: z.ZodNumber;
+            bounced: z.ZodNumber;
+            unsubscribed: z.ZodNumber;
+            repliesPositive: z.ZodNumber;
+            repliesNegative: z.ZodNumber;
+            repliesNeutral: z.ZodNumber;
+            repliesAutoReply: z.ZodNumber;
+            repliesDetail: z.ZodObject<{
+                interested: z.ZodNumber;
+                meetingBooked: z.ZodNumber;
+                closed: z.ZodNumber;
+                notInterested: z.ZodNumber;
+                wrongPerson: z.ZodNumber;
+                unsubscribe: z.ZodNumber;
+                neutral: z.ZodNumber;
+                autoReply: z.ZodNumber;
+                outOfOffice: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const StatusScopeSchema: z.ZodObject<{
+    contacted: z.ZodBoolean;
+    sent: z.ZodBoolean;
+    delivered: z.ZodBoolean;
+    opened: z.ZodBoolean;
+    clicked: z.ZodBoolean;
+    replied: z.ZodBoolean;
+    replyClassification: z.ZodNullable<z.ZodEnum<{
+        positive: "positive";
+        negative: "negative";
+        neutral: "neutral";
+    }>>;
+    bounced: z.ZodBoolean;
+    unsubscribed: z.ZodBoolean;
+    cancelled: z.ZodOptional<z.ZodBoolean>;
+    lastDeliveredAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const GlobalStatusSchema: z.ZodObject<{
+    email: z.ZodObject<{
+        bounced: z.ZodBoolean;
+        unsubscribed: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const ProviderStatusSchema: z.ZodObject<{
+    byCampaign: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodObject<{
+        contacted: z.ZodBoolean;
+        sent: z.ZodBoolean;
+        delivered: z.ZodBoolean;
+        opened: z.ZodBoolean;
+        clicked: z.ZodBoolean;
+        replied: z.ZodBoolean;
+        replyClassification: z.ZodNullable<z.ZodEnum<{
+            positive: "positive";
+            negative: "negative";
+            neutral: "neutral";
+        }>>;
+        bounced: z.ZodBoolean;
+        unsubscribed: z.ZodBoolean;
+        cancelled: z.ZodOptional<z.ZodBoolean>;
+        lastDeliveredAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+    campaign: z.ZodNullable<z.ZodObject<{
+        contacted: z.ZodBoolean;
+        sent: z.ZodBoolean;
+        delivered: z.ZodBoolean;
+        opened: z.ZodBoolean;
+        clicked: z.ZodBoolean;
+        replied: z.ZodBoolean;
+        replyClassification: z.ZodNullable<z.ZodEnum<{
+            positive: "positive";
+            negative: "negative";
+            neutral: "neutral";
+        }>>;
+        bounced: z.ZodBoolean;
+        unsubscribed: z.ZodBoolean;
+        cancelled: z.ZodOptional<z.ZodBoolean>;
+        lastDeliveredAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    brand: z.ZodNullable<z.ZodObject<{
+        contacted: z.ZodBoolean;
+        sent: z.ZodBoolean;
+        delivered: z.ZodBoolean;
+        opened: z.ZodBoolean;
+        clicked: z.ZodBoolean;
+        replied: z.ZodBoolean;
+        replyClassification: z.ZodNullable<z.ZodEnum<{
+            positive: "positive";
+            negative: "negative";
+            neutral: "neutral";
+        }>>;
+        bounced: z.ZodBoolean;
+        unsubscribed: z.ZodBoolean;
+        cancelled: z.ZodOptional<z.ZodBoolean>;
+        lastDeliveredAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    global: z.ZodObject<{
+        email: z.ZodObject<{
+            bounced: z.ZodBoolean;
+            unsubscribed: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,yBAAyB;;;;EAIpC,CAAC;AAMH,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAU9B,CAAC;AAMH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;iBAgC/B,CAAC;AAOH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;iBAiB1B,CAAC;AAMH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiB3B,CAAC;AAMH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK7B,CAAC;AAOH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;iBAyC5B,CAAC;AAMH,eAAO,MAAM,kBAAkB;;;;;iBAW7B,CAAC;AAMH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgB/B,CAAC"}

package/dist/schemas.js ADDED Viewed

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderStatusSchema = exports.GlobalStatusSchema = exports.StatusScopeSchema = exports.ChannelStatsSchema = exports.EmailStatsSchema = exports.StepStatsSchema = exports.RecipientStatsSchema = exports.RepliesDetailSchema = exports.ReplyClassificationSchema = void 0;
+const zod_1 = require("zod");
+// ---------------------------------------------------------------------------
+// Reply classification
+// ---------------------------------------------------------------------------
+exports.ReplyClassificationSchema = zod_1.z.enum([
+    "positive",
+    "negative",
+    "neutral",
+]);
+// ---------------------------------------------------------------------------
+// Replies detail — granular reply breakdown by classification
+// ---------------------------------------------------------------------------
+exports.RepliesDetailSchema = zod_1.z.object({
+    interested: zod_1.z.number().describe("lead_interested events"),
+    meetingBooked: zod_1.z.number().describe("lead_meeting_booked events"),
+    closed: zod_1.z.number().describe("lead_closed events"),
+    notInterested: zod_1.z.number().describe("lead_not_interested events"),
+    wrongPerson: zod_1.z.number().describe("lead_wrong_person events"),
+    unsubscribe: zod_1.z.number().describe("lead_unsubscribed events"),
+    neutral: zod_1.z.number().describe("lead_neutral events"),
+    autoReply: zod_1.z.number().describe("auto_reply_received events"),
+    outOfOffice: zod_1.z.number().describe("lead_out_of_office events"),
+});
+// ---------------------------------------------------------------------------
+// Recipient-level stats (COUNT DISTINCT lead)
+// ---------------------------------------------------------------------------
+exports.RecipientStatsSchema = zod_1.z.object({
+    contacted: zod_1.z
+        .number()
+        .describe("Leads added to a campaign / send attempted"),
+    sent: zod_1.z.number().describe("Leads with at least 1 email sent (COUNT DISTINCT lead)"),
+    delivered: zod_1.z.number().describe("Leads delivered (sent - bounced)"),
+    opened: zod_1.z.number().describe("Leads who opened at least 1 email"),
+    bounced: zod_1.z.number().describe("Leads with at least 1 bounce"),
+    clicked: zod_1.z.number().describe("Leads who clicked at least 1 link"),
+    unsubscribed: zod_1.z.number().describe("Leads who unsubscribed"),
+    // Provider-specific (instantly-only today; postmark padding follow-up will add).
+    notSending: zod_1.z
+        .number()
+        .optional()
+        .describe("Leads in campaigns currently flagged with Instantly's not_sending_status diagnostic. Optional in contract v1; will be required in v2 after postmark padding ships."),
+    cancelled: zod_1.z
+        .number()
+        .optional()
+        .describe("Leads whose campaign was cancelled by the retry-stuck job (delivery_status='cancelled'). Optional in contract v1; will be required in v2 after postmark padding ships."),
+    repliesPositive: zod_1.z.number().describe("interested + meetingBooked + closed"),
+    repliesNegative: zod_1.z
+        .number()
+        .describe("notInterested + wrongPerson + unsubscribe"),
+    repliesNeutral: zod_1.z.number().describe("neutral (lead_neutral events only)"),
+    repliesAutoReply: zod_1.z.number().describe("autoReply + outOfOffice"),
+    repliesDetail: exports.RepliesDetailSchema.describe("Granular reply breakdown by classification"),
+});
+// ---------------------------------------------------------------------------
+// Step stats — per-step breakdown (used by Instantly broadcast sequences;
+// always empty array for Postmark since transactional has no step concept)
+// ---------------------------------------------------------------------------
+exports.StepStatsSchema = zod_1.z.object({
+    step: zod_1.z.number().describe("Step number (1-based)"),
+    sent: zod_1.z.number().describe("Emails sent at this step"),
+    delivered: zod_1.z.number().describe("Delivered at this step (sent - bounced)"),
+    opened: zod_1.z.number().describe("Emails opened at this step"),
+    clicked: zod_1.z.number().describe("Link clicks at this step"),
+    bounced: zod_1.z.number().describe("Emails bounced at this step"),
+    unsubscribed: zod_1.z.number().describe("Unsubscribes at this step"),
+    repliesPositive: zod_1.z.number().describe("interested + meetingBooked + closed"),
+    repliesNegative: zod_1.z
+        .number()
+        .describe("notInterested + wrongPerson + unsubscribe"),
+    repliesNeutral: zod_1.z.number().describe("neutral (lead_neutral events only)"),
+    repliesAutoReply: zod_1.z.number().describe("autoReply + outOfOffice"),
+    repliesDetail: exports.RepliesDetailSchema.describe("Granular reply breakdown by classification"),
+});
+// ---------------------------------------------------------------------------
+// Email-level stats (COUNT *)
+// ---------------------------------------------------------------------------
+exports.EmailStatsSchema = zod_1.z.object({
+    sent: zod_1.z.number().describe("Total emails sent (COUNT *, all steps)"),
+    delivered: zod_1.z.number().describe("Total emails delivered (sent - bounced)"),
+    opened: zod_1.z
+        .number()
+        .describe("Unique emails opened at least once (COUNT DISTINCT)"),
+    clicked: zod_1.z
+        .number()
+        .describe("Unique emails with at least 1 click (COUNT DISTINCT)"),
+    bounced: zod_1.z.number().describe("Total emails bounced"),
+    unsubscribed: zod_1.z.number().describe("Total unsubscribe events"),
+    stepStats: zod_1.z
+        .array(exports.StepStatsSchema)
+        .optional()
+        .describe("Per-step breakdown (instantly broadcast only; empty/omitted for postmark transactional)"),
+});
+// ---------------------------------------------------------------------------
+// Channel stats — wraps recipient + email
+// ---------------------------------------------------------------------------
+exports.ChannelStatsSchema = zod_1.z.object({
+    recipientStats: exports.RecipientStatsSchema.describe("Recipient-level stats (COUNT DISTINCT lead)"),
+    emailStats: exports.EmailStatsSchema.describe("Email-level stats (COUNT *)"),
+});
+// ---------------------------------------------------------------------------
+// Status scope — delivery state for one recipient in a given scope
+// (per-campaign, per-brand aggregate, or per-campaign single)
+// ---------------------------------------------------------------------------
+exports.StatusScopeSchema = zod_1.z.object({
+    contacted: zod_1.z
+        .boolean()
+        .describe("Whether at least one sending exists in this scope"),
+    sent: zod_1.z.boolean().describe("Whether an email was sent in this scope"),
+    delivered: zod_1.z
+        .boolean()
+        .describe("Whether an email was delivered in this scope (sent AND not bounced)"),
+    opened: zod_1.z
+        .boolean()
+        .describe("Whether the recipient opened any email in this scope"),
+    clicked: zod_1.z
+        .boolean()
+        .describe("Whether the recipient clicked any link in this scope"),
+    replied: zod_1.z
+        .boolean()
+        .describe("Whether the recipient replied in this scope (always false for postmark — no reply tracking)"),
+    replyClassification: exports.ReplyClassificationSchema.nullable().describe("Classification of most recent reply: positive / negative / neutral, or null if no reply (always null for postmark)"),
+    bounced: zod_1.z.boolean().describe("Whether an email bounced in this scope"),
+    unsubscribed: zod_1.z
+        .boolean()
+        .describe("Whether the recipient unsubscribed in this scope"),
+    // Provider-specific (instantly-only today; postmark padding follow-up).
+    cancelled: zod_1.z
+        .boolean()
+        .optional()
+        .describe("Whether the campaign was cancelled by the retry-stuck job. Optional in contract v1; required in v2 after postmark padding ships."),
+    lastDeliveredAt: zod_1.z
+        .string()
+        .nullable()
+        .describe("ISO 8601 timestamp of last delivery in this scope; null if none"),
+});
+// ---------------------------------------------------------------------------
+// Global status — org-wide bounce / unsubscribe signals
+// ---------------------------------------------------------------------------
+exports.GlobalStatusSchema = zod_1.z.object({
+    email: zod_1.z
+        .object({
+        bounced: zod_1.z
+            .boolean()
+            .describe("True if this email bounced anywhere in the org"),
+        unsubscribed: zod_1.z
+            .boolean()
+            .describe("True if this email unsubscribed anywhere in the org"),
+    })
+        .describe("Global email signals (technical/legal)"),
+});
+// ---------------------------------------------------------------------------
+// Provider status — full status payload from one provider for one email
+// ---------------------------------------------------------------------------
+exports.ProviderStatusSchema = zod_1.z.object({
+    byCampaign: zod_1.z
+        .record(zod_1.z.string(), exports.StatusScopeSchema)
+        .nullable()
+        .describe("Per-campaign breakdown keyed by campaignId — present in brand mode, null otherwise"),
+    campaign: exports.StatusScopeSchema.nullable().describe("Status scoped to the given campaign — present in campaign mode, null otherwise"),
+    brand: exports.StatusScopeSchema.nullable().describe("Aggregated status across all campaigns for the brand — present in brand mode, null otherwise"),
+    global: exports.GlobalStatusSchema.describe("Global signals across all brands and campaigns (always present)"),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import type { z } from "zod";
+import { ReplyClassificationSchema, RepliesDetailSchema, RecipientStatsSchema, StepStatsSchema, EmailStatsSchema, ChannelStatsSchema, StatusScopeSchema, GlobalStatusSchema, ProviderStatusSchema } from "./schemas";
+export type ReplyClassification = z.infer<typeof ReplyClassificationSchema>;
+export type RepliesDetail = z.infer<typeof RepliesDetailSchema>;
+export type RecipientStats = z.infer<typeof RecipientStatsSchema>;
+export type StepStats = z.infer<typeof StepStatsSchema>;
+export type EmailStats = z.infer<typeof EmailStatsSchema>;
+export type ChannelStats = z.infer<typeof ChannelStatsSchema>;
+export type StatusScope = z.infer<typeof StatusScopeSchema>;
+export type GlobalStatus = z.infer<typeof GlobalStatusSchema>;
+export type ProviderStatus = z.infer<typeof ProviderStatusSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,WAAW,CAAC;AAEnB,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/types.js ADDED Viewed

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json ADDED Viewed

@@ -0,0 +1,47 @@
+{
+  "name": "@shamanic-technologies/email-domain-contract",
+  "version": "1.0.1",
+  "description": "Shared Zod schemas for the email domain (postmark-service, instantly-service, email-gateway). Single source of truth for cross-provider canonical shapes.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "email",
+    "zod",
+    "contract",
+    "schema",
+    "postmark",
+    "instantly"
+  ],
+  "author": "Shamanic Technologies",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shamanic-technologies/email-domain-contract.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shamanic-technologies/email-domain-contract/issues"
+  },
+  "homepage": "https://github.com/shamanic-technologies/email-domain-contract#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5",
+    "zod": "^4.3.6"
+  }
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,23 @@
+export {
+  ReplyClassificationSchema,
+  RepliesDetailSchema,
+  RecipientStatsSchema,
+  StepStatsSchema,
+  EmailStatsSchema,
+  ChannelStatsSchema,
+  StatusScopeSchema,
+  GlobalStatusSchema,
+  ProviderStatusSchema,
+} from "./schemas";
+export type {
+  ReplyClassification,
+  RepliesDetail,
+  RecipientStats,
+  StepStats,
+  EmailStats,
+  ChannelStats,
+  StatusScope,
+  GlobalStatus,
+  ProviderStatus,
+} from "./types";

package/src/schemas.ts ADDED Viewed

@@ -0,0 +1,210 @@
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Reply classification
+// ---------------------------------------------------------------------------
+export const ReplyClassificationSchema = z.enum([
+  "positive",
+  "negative",
+  "neutral",
+]);
+// ---------------------------------------------------------------------------
+// Replies detail — granular reply breakdown by classification
+// ---------------------------------------------------------------------------
+export const RepliesDetailSchema = z.object({
+  interested: z.number().describe("lead_interested events"),
+  meetingBooked: z.number().describe("lead_meeting_booked events"),
+  closed: z.number().describe("lead_closed events"),
+  notInterested: z.number().describe("lead_not_interested events"),
+  wrongPerson: z.number().describe("lead_wrong_person events"),
+  unsubscribe: z.number().describe("lead_unsubscribed events"),
+  neutral: z.number().describe("lead_neutral events"),
+  autoReply: z.number().describe("auto_reply_received events"),
+  outOfOffice: z.number().describe("lead_out_of_office events"),
+});
+// ---------------------------------------------------------------------------
+// Recipient-level stats (COUNT DISTINCT lead)
+// ---------------------------------------------------------------------------
+export const RecipientStatsSchema = z.object({
+  contacted: z
+    .number()
+    .describe("Leads added to a campaign / send attempted"),
+  sent: z.number().describe("Leads with at least 1 email sent (COUNT DISTINCT lead)"),
+  delivered: z.number().describe("Leads delivered (sent - bounced)"),
+  opened: z.number().describe("Leads who opened at least 1 email"),
+  bounced: z.number().describe("Leads with at least 1 bounce"),
+  clicked: z.number().describe("Leads who clicked at least 1 link"),
+  unsubscribed: z.number().describe("Leads who unsubscribed"),
+  // Provider-specific (instantly-only today; postmark padding follow-up will add).
+  notSending: z
+    .number()
+    .optional()
+    .describe(
+      "Leads in campaigns currently flagged with Instantly's not_sending_status diagnostic. Optional in contract v1; will be required in v2 after postmark padding ships.",
+    ),
+  cancelled: z
+    .number()
+    .optional()
+    .describe(
+      "Leads whose campaign was cancelled by the retry-stuck job (delivery_status='cancelled'). Optional in contract v1; will be required in v2 after postmark padding ships.",
+    ),
+  repliesPositive: z.number().describe("interested + meetingBooked + closed"),
+  repliesNegative: z
+    .number()
+    .describe("notInterested + wrongPerson + unsubscribe"),
+  repliesNeutral: z.number().describe("neutral (lead_neutral events only)"),
+  repliesAutoReply: z.number().describe("autoReply + outOfOffice"),
+  repliesDetail: RepliesDetailSchema.describe(
+    "Granular reply breakdown by classification",
+  ),
+});
+// ---------------------------------------------------------------------------
+// Step stats — per-step breakdown (used by Instantly broadcast sequences;
+// always empty array for Postmark since transactional has no step concept)
+// ---------------------------------------------------------------------------
+export const StepStatsSchema = z.object({
+  step: z.number().describe("Step number (1-based)"),
+  sent: z.number().describe("Emails sent at this step"),
+  delivered: z.number().describe("Delivered at this step (sent - bounced)"),
+  opened: z.number().describe("Emails opened at this step"),
+  clicked: z.number().describe("Link clicks at this step"),
+  bounced: z.number().describe("Emails bounced at this step"),
+  unsubscribed: z.number().describe("Unsubscribes at this step"),
+  repliesPositive: z.number().describe("interested + meetingBooked + closed"),
+  repliesNegative: z
+    .number()
+    .describe("notInterested + wrongPerson + unsubscribe"),
+  repliesNeutral: z.number().describe("neutral (lead_neutral events only)"),
+  repliesAutoReply: z.number().describe("autoReply + outOfOffice"),
+  repliesDetail: RepliesDetailSchema.describe(
+    "Granular reply breakdown by classification",
+  ),
+});
+// ---------------------------------------------------------------------------
+// Email-level stats (COUNT *)
+// ---------------------------------------------------------------------------
+export const EmailStatsSchema = z.object({
+  sent: z.number().describe("Total emails sent (COUNT *, all steps)"),
+  delivered: z.number().describe("Total emails delivered (sent - bounced)"),
+  opened: z
+    .number()
+    .describe("Unique emails opened at least once (COUNT DISTINCT)"),
+  clicked: z
+    .number()
+    .describe("Unique emails with at least 1 click (COUNT DISTINCT)"),
+  bounced: z.number().describe("Total emails bounced"),
+  unsubscribed: z.number().describe("Total unsubscribe events"),
+  stepStats: z
+    .array(StepStatsSchema)
+    .optional()
+    .describe(
+      "Per-step breakdown (instantly broadcast only; empty/omitted for postmark transactional)",
+    ),
+});
+// ---------------------------------------------------------------------------
+// Channel stats — wraps recipient + email
+// ---------------------------------------------------------------------------
+export const ChannelStatsSchema = z.object({
+  recipientStats: RecipientStatsSchema.describe(
+    "Recipient-level stats (COUNT DISTINCT lead)",
+  ),
+  emailStats: EmailStatsSchema.describe("Email-level stats (COUNT *)"),
+});
+// ---------------------------------------------------------------------------
+// Status scope — delivery state for one recipient in a given scope
+// (per-campaign, per-brand aggregate, or per-campaign single)
+// ---------------------------------------------------------------------------
+export const StatusScopeSchema = z.object({
+  contacted: z
+    .boolean()
+    .describe("Whether at least one sending exists in this scope"),
+  sent: z.boolean().describe("Whether an email was sent in this scope"),
+  delivered: z
+    .boolean()
+    .describe(
+      "Whether an email was delivered in this scope (sent AND not bounced)",
+    ),
+  opened: z
+    .boolean()
+    .describe("Whether the recipient opened any email in this scope"),
+  clicked: z
+    .boolean()
+    .describe("Whether the recipient clicked any link in this scope"),
+  replied: z
+    .boolean()
+    .describe(
+      "Whether the recipient replied in this scope (always false for postmark — no reply tracking)",
+    ),
+  replyClassification: ReplyClassificationSchema.nullable().describe(
+    "Classification of most recent reply: positive / negative / neutral, or null if no reply (always null for postmark)",
+  ),
+  bounced: z.boolean().describe("Whether an email bounced in this scope"),
+  unsubscribed: z
+    .boolean()
+    .describe("Whether the recipient unsubscribed in this scope"),
+  // Provider-specific (instantly-only today; postmark padding follow-up).
+  cancelled: z
+    .boolean()
+    .optional()
+    .describe(
+      "Whether the campaign was cancelled by the retry-stuck job. Optional in contract v1; required in v2 after postmark padding ships.",
+    ),
+  lastDeliveredAt: z
+    .string()
+    .nullable()
+    .describe(
+      "ISO 8601 timestamp of last delivery in this scope; null if none",
+    ),
+});
+// ---------------------------------------------------------------------------
+// Global status — org-wide bounce / unsubscribe signals
+// ---------------------------------------------------------------------------
+export const GlobalStatusSchema = z.object({
+  email: z
+    .object({
+      bounced: z
+        .boolean()
+        .describe("True if this email bounced anywhere in the org"),
+      unsubscribed: z
+        .boolean()
+        .describe("True if this email unsubscribed anywhere in the org"),
+    })
+    .describe("Global email signals (technical/legal)"),
+});
+// ---------------------------------------------------------------------------
+// Provider status — full status payload from one provider for one email
+// ---------------------------------------------------------------------------
+export const ProviderStatusSchema = z.object({
+  byCampaign: z
+    .record(z.string(), StatusScopeSchema)
+    .nullable()
+    .describe(
+      "Per-campaign breakdown keyed by campaignId — present in brand mode, null otherwise",
+    ),
+  campaign: StatusScopeSchema.nullable().describe(
+    "Status scoped to the given campaign — present in campaign mode, null otherwise",
+  ),
+  brand: StatusScopeSchema.nullable().describe(
+    "Aggregated status across all campaigns for the brand — present in brand mode, null otherwise",
+  ),
+  global: GlobalStatusSchema.describe(
+    "Global signals across all brands and campaigns (always present)",
+  ),
+});

package/src/types.ts ADDED Viewed

@@ -0,0 +1,22 @@
+import type { z } from "zod";
+import {
+  ReplyClassificationSchema,
+  RepliesDetailSchema,
+  RecipientStatsSchema,
+  StepStatsSchema,
+  EmailStatsSchema,
+  ChannelStatsSchema,
+  StatusScopeSchema,
+  GlobalStatusSchema,
+  ProviderStatusSchema,
+} from "./schemas";
+export type ReplyClassification = z.infer<typeof ReplyClassificationSchema>;
+export type RepliesDetail = z.infer<typeof RepliesDetailSchema>;
+export type RecipientStats = z.infer<typeof RecipientStatsSchema>;
+export type StepStats = z.infer<typeof StepStatsSchema>;
+export type EmailStats = z.infer<typeof EmailStatsSchema>;
+export type ChannelStats = z.infer<typeof ChannelStatsSchema>;
+export type StatusScope = z.infer<typeof StatusScopeSchema>;
+export type GlobalStatus = z.infer<typeof GlobalStatusSchema>;
+export type ProviderStatus = z.infer<typeof ProviderStatusSchema>;