@hogsend/core 0.3.0 → 0.5.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.3.0",
+  "version": "0.5.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.3.0"
+    "@hogsend/db": "^0.5.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/types/journey-context.ts

@@ -96,12 +96,47 @@ export interface EmailHistoryResult {
   count: number;
 }
 
+export interface WaitForEventOptions {
+  /** Event name to wait for (use your `Events` constant). Matched verbatim. */
+  event: string;
+  /**
+   * Max time to wait before resolving as timed-out. Required: an unbounded wait
+   * is only capped by the task's execution timeout and would fail rather than
+   * resume. Keep it within the journey execution timeout (720h / 30 days).
+   */
+  timeout: DurationObject;
+  /** Optional observability label written to `currentNodeId` while waiting. */
+  label?: string;
+}
+
+export interface WaitForEventResult {
+  /** `true` when the `timeout` elapsed first; `false` when the event fired. */
+  timedOut: boolean;
+}
+
 export interface JourneyContext {
   sleep(opts: SleepOptions): Promise<SleepResult>;
 
   /** Durable sleep until an absolute instant (`Date` or ISO string). */
   sleepUntil(at: Date | string, opts?: SleepUntilOptions): Promise<SleepResult>;
 
+  /**
+   * Durably wait until THIS user emits `event`, or `timeout` elapses —
+   * whichever comes first. The state is marked `"waiting"` while suspended and
+   * `"active"` again on resume. Returns `{ timedOut }` so the journey can branch
+   * (e.g. send a nudge on timeout, do nothing if the event arrived).
+   *
+   * Forward-looking: only events emitted AFTER the wait is established count —
+   * use `ctx.history.hasEvent` to check whether something already happened.
+   *
+   * If the journey exits (via `exitOn`) or is cancelled while waiting, the run
+   * is aborted cleanly (a `JourneyExitedError` is thrown and handled by the
+   * engine) so no post-wait side effects fire. After a long wait you should
+   * still re-check `ctx.guard.isSubscribed()` before sending, since an
+   * unsubscribe does not exit the journey.
+   */
+  waitForEvent(opts: WaitForEventOptions): Promise<WaitForEventResult>;
+
   /** Timezone-bound fluent scheduler. Always terminates in a `Date`. */
   when: WhenBuilder;