@hogsend/core 0.4.0 → 0.6.0

package/README.md

@@ -4,6 +4,17 @@ Core types, Zod schemas, the condition-evaluation engine, duration helpers, and
 the `JourneyRegistry` for [Hogsend](https://github.com/dougwithseismic/hogsend) —
 a code-first lifecycle orchestration engine for teams on PostHog + Resend.
 
+## Capability-provider contracts
+
+Core also **owns** the capability-provider contracts — `EmailProvider` (with its
+supporting `SendEmailOptions`, `BatchEmailItem`, `SendResult`, `WebhookEvent`,
+`WebhookEventType`, `WebhookHandlerMap`) and `PostHogService` (with
+`CaptureOptions`). These are the engine-owned contracts a swappable email/analytics
+implementation satisfies; they live here and are re-exported by `@hogsend/engine`
+(the canonical author import) and the vendor plugins (`@hogsend/plugin-resend`,
+`@hogsend/plugin-posthog`) for back-compat. See
+[docs/adr/0001-provider-boundary.md](https://github.com/dougwithseismic/hogsend/blob/main/docs/adr/0001-provider-boundary.md).
+
 This package ships raw TypeScript source; consumers bundle it via their own build
 (tsup `noExternal`). See the repo docs for the full architecture and the
 [release model](https://github.com/dougwithseismic/hogsend/blob/main/docs/RELEASING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./types": "./src/types/index.ts",
+    "./providers": "./src/providers/index.ts",
     "./registry": "./src/registry/index.ts",
     "./conditions": "./src/conditions/index.ts",
     "./schedule": "./src/schedule/index.ts",
@@ -31,10 +32,11 @@
     "drizzle-orm": "^0.45.2",
     "iana-db-timezones": "^0.3.0",
     "zod": "^4.4.3",
-    "@hogsend/db": "^0.4.0"
+    "@hogsend/db": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "latest",
+    "@types/react": "^19.2.16",
     "vitest": "^4.1.8",
     "@repo/typescript-config": "0.0.0"
   },

package/src/index.ts

@@ -15,6 +15,7 @@ export {
   hours,
   minutes,
 } from "./duration.js";
+export * from "./providers/index.js";
 export {
   BucketRegistry,
   collectEventNames,

package/src/providers/analytics.ts

@@ -0,0 +1,20 @@
+export interface PostHogService {
+  getPersonProperties(distinctId: string): Promise<Record<string, unknown>>;
+
+  captureEvent(opts: CaptureOptions): void;
+
+  identify(distinctId: string, properties: Record<string, unknown>): void;
+
+  isFeatureEnabled(opts: {
+    distinctId: string;
+    flag: string;
+  }): Promise<boolean>;
+
+  shutdown(): Promise<void>;
+}
+
+export interface CaptureOptions {
+  distinctId: string;
+  event: string;
+  properties?: Record<string, unknown>;
+}

package/src/providers/email.ts

@@ -0,0 +1,138 @@
+import type { ReactElement } from "react";
+
+// ---------------------------------------------------------------------------
+// Send options
+// ---------------------------------------------------------------------------
+
+export interface SendEmailOptions {
+  from: string;
+  to: string | string[];
+  subject: string;
+  react?: ReactElement;
+  html?: string;
+  replyTo?: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  scheduledAt?: string;
+  tags?: Array<{ name: string; value: string }>;
+  headers?: Record<string, string>;
+}
+
+export interface BatchEmailItem {
+  from: string;
+  to: string | string[];
+  subject: string;
+  react: ReactElement;
+  replyTo?: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  tags?: Array<{ name: string; value: string }>;
+  headers?: Record<string, string>;
+}
+
+export interface SendResult {
+  id: string;
+}
+
+// ---------------------------------------------------------------------------
+// Webhook events
+// ---------------------------------------------------------------------------
+
+interface WebhookEventBase {
+  created_at: string;
+  data: {
+    email_id: string;
+    from: string;
+    to: string[];
+    subject: string;
+    created_at: string;
+  };
+}
+
+export interface EmailSentEvent extends WebhookEventBase {
+  type: "email.sent";
+}
+
+export interface EmailDeliveredEvent extends WebhookEventBase {
+  type: "email.delivered";
+}
+
+export interface EmailBouncedEvent extends WebhookEventBase {
+  type: "email.bounced";
+  data: WebhookEventBase["data"] & {
+    bounce: {
+      message: string;
+      type: string;
+    };
+  };
+}
+
+export interface EmailComplainedEvent extends WebhookEventBase {
+  type: "email.complained";
+}
+
+export interface EmailDeliveryDelayedEvent extends WebhookEventBase {
+  type: "email.delivery_delayed";
+}
+
+export interface EmailOpenedEvent extends WebhookEventBase {
+  type: "email.opened";
+}
+
+export interface EmailClickedEvent extends WebhookEventBase {
+  type: "email.clicked";
+  data: WebhookEventBase["data"] & {
+    click: {
+      link: string;
+      timestamp: string;
+      ipAddress: string;
+      userAgent: string;
+    };
+  };
+}
+
+export type WebhookEvent =
+  | EmailSentEvent
+  | EmailDeliveredEvent
+  | EmailBouncedEvent
+  | EmailComplainedEvent
+  | EmailDeliveryDelayedEvent
+  | EmailOpenedEvent
+  | EmailClickedEvent;
+
+export type WebhookEventType = WebhookEvent["type"];
+
+export type WebhookHandlerMap = {
+  [K in WebhookEventType]?: (
+    event: Extract<WebhookEvent, { type: K }>,
+  ) => void | Promise<void>;
+};
+
+// ---------------------------------------------------------------------------
+// EmailProvider contract (the entire provider surface)
+// ---------------------------------------------------------------------------
+
+/**
+ * The dumb delivery + webhook parse/verify contract every email provider
+ * implements (Resend, Postmark, SES, …). All tracking, DB, preference, and
+ * render logic lives in the engine's `createTrackedMailer`, never here.
+ */
+export interface EmailProvider {
+  /** Deliver a single message. Returns the provider message id. */
+  send(options: SendEmailOptions): Promise<SendResult>;
+
+  /** Deliver a batch of messages. */
+  sendBatch(emails: BatchEmailItem[]): Promise<{ results: SendResult[] }>;
+
+  /**
+   * Verify a provider webhook signature and return the parsed event. Throws
+   * if the signature is missing/invalid.
+   */
+  verifyWebhook(opts: {
+    payload: string;
+    headers: Record<string, string>;
+  }): WebhookEvent;
+
+  /** Parse an unsigned webhook payload (used in trusted contexts/tests). */
+  parseWebhook(payload: string): WebhookEvent;
+}

package/src/providers/index.ts

@@ -0,0 +1,2 @@
+export * from "./analytics.js";
+export * from "./email.js";

package/src/schemas/journey.schema.ts

@@ -85,4 +85,17 @@ export const journeyMetaSchema = z.object({
     minutes: z.number().optional(),
     seconds: z.number().optional(),
   }),
+
+  // Bucket-reaction tagging. journeyMetaSchema.parse runs inside
+  // JourneyRegistry.register and STRIPS unknown keys, so these MUST be declared
+  // here or the dwell-cron lookup + Studio grouping silently break.
+  sourceBucketId: z.string().optional(),
+  reactionKind: z.enum(["enter", "leave", "dwell"]).optional(),
+  dwellSchedule: z
+    .object({
+      label: z.string(),
+      after: z.number().optional(),
+      every: z.number().optional(),
+    })
+    .optional(),
 });

package/src/types/journey.ts

@@ -21,6 +21,13 @@ export interface JourneyMeta {
   }>;
 
   suppress: DurationObject;
+
+  // Bucket-reaction tagging (set by buildBucketReaction). Generated reactions
+  // carry these so the worker's dwell-cron lookup and Studio bucket-detail
+  // grouping can discover owned reactions by sourceBucketId.
+  sourceBucketId?: string;
+  reactionKind?: "enter" | "leave" | "dwell";
+  dwellSchedule?: { label: string; after?: number; every?: number };
 }
 
 export interface JourneyUser {