better-ship 0.13.0 → 0.15.0

package/dist/{webhook-verification-CyBoERFz.d.ts.map → webhook-verification-D7DIhH6C.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"webhook-verification-CyBoERFz.d.ts","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"mappings":";;;cAGa,iCAAiC;WAMjC;WALF;WACA;;EAGT,YACW,qEACT;;;KAOQ,oBAAoB;WACjB;WAA2B,OAAO;;WAClC;WAA6B;;WAC7B;WAA8B,OAAO;;;UAGnC,gBAAgB;;EAE/B,OAAO,cAAc,SAAS,UAAU,QAAQ,oBAAoB"}
+{"version":3,"file":"webhook-verification-D7DIhH6C.d.ts","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"mappings":";;;cAGa,iCAAiC;WAMjC;WALF;WACA;;EAGT,YACW,qEACT;;;KAOQ,oBAAoB;WACjB;WAA2B,OAAO;;WAClC;WAA6B;;WAC7B;WAA8B,OAAO;;;UAGnC,gBAAgB;;EAE/B,OAAO,cAAc,SAAS,UAAU,QAAQ,oBAAoB"}

package/dist/{webhook-verification-CeXUJXVP.js → webhook-verification-trEgyz7I.js}

@@ -1,4 +1,4 @@
-import { $ as AppError } from "./core-BiqdOMwU.js";
+import { tt as AppError } from "./core-hdaNiCOU.js";
 
 //#region src/infrastructure/http/webhook-verification.ts
 /** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */
@@ -15,4 +15,4 @@ var WebhookVerificationError = class extends AppError {
 
 //#endregion
 export { WebhookVerificationError as t };
-//# sourceMappingURL=webhook-verification-CeXUJXVP.js.map
+//# sourceMappingURL=webhook-verification-trEgyz7I.js.map

package/dist/{webhook-verification-CeXUJXVP.js.map → webhook-verification-trEgyz7I.js.map}

@@ -1 +1 @@
-{"version":3,"file":"webhook-verification-CeXUJXVP.js","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"sourcesContent":["import { AppError } from '@/core'\n\n/** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */\nexport class WebhookVerificationError extends AppError {\n  readonly _tag = 'WebhookVerificationError'\n  readonly classification = 'terminal'\n\n  /** Keep secrets and payload details out of the public message. */\n  constructor(\n    readonly reason: 'missing_headers' | 'invalid_signature' | 'invalid_payload',\n    cause?: unknown,\n  ) {\n    super(`Webhook rejected: ${reason}`, { cause })\n  }\n}\n\n/** A verified event, an ignored event, or an invalid request. */\nexport type WebhookVerification<Event> =\n  | { readonly outcome: 'event'; readonly event: Event }\n  | { readonly outcome: 'ignored'; readonly type: string }\n  | { readonly outcome: 'rejected'; readonly error: WebhookVerificationError }\n\n/** The provider owns signature verification, timestamp tolerance, and payload parsing. */\nexport interface WebhookVerifier<Event> {\n  /** Verify the exact body before parsing it. Return invalid requests; throw operational failures. */\n  verify(body: string, headers: Headers): Promise<WebhookVerification<Event>>\n}\n"],"mappings":";;;;AAGA,IAAa,2BAAb,cAA8C,SAAS;CAM1C;CALX,AAAS,OAAO;CAChB,AAAS,iBAAiB;;CAG1B,YACE,AAAS,QACT,OACA;EACA,MAAM,qBAAqB,UAAU,EAAE,MAAM,CAAC;EAHrC;CAIX;AACF"}
+{"version":3,"file":"webhook-verification-trEgyz7I.js","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"sourcesContent":["import { AppError } from '@/core'\n\n/** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */\nexport class WebhookVerificationError extends AppError {\n  readonly _tag = 'WebhookVerificationError'\n  readonly classification = 'terminal'\n\n  /** Keep secrets and payload details out of the public message. */\n  constructor(\n    readonly reason: 'missing_headers' | 'invalid_signature' | 'invalid_payload',\n    cause?: unknown,\n  ) {\n    super(`Webhook rejected: ${reason}`, { cause })\n  }\n}\n\n/** A verified event, an ignored event, or an invalid request. */\nexport type WebhookVerification<Event> =\n  | { readonly outcome: 'event'; readonly event: Event }\n  | { readonly outcome: 'ignored'; readonly type: string }\n  | { readonly outcome: 'rejected'; readonly error: WebhookVerificationError }\n\n/** The provider owns signature verification, timestamp tolerance, and payload parsing. */\nexport interface WebhookVerifier<Event> {\n  /** Verify the exact body before parsing it. Return invalid requests; throw operational failures. */\n  verify(body: string, headers: Headers): Promise<WebhookVerification<Event>>\n}\n"],"mappings":";;;;AAGA,IAAa,2BAAb,cAA8C,SAAS;CAM1C;CALX,AAAS,OAAO;CAChB,AAAS,iBAAiB;;CAG1B,YACE,AAAS,QACT,OACA;EACA,MAAM,qBAAqB,UAAU,EAAE,MAAM,CAAC;EAHrC;CAIX;AACF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -24,12 +24,21 @@
     "./better-auth/stripe": "./dist/better-auth/stripe.js",
     "./cloudflare": "./dist/cloudflare.js",
     "./cloudflare/auth-secondary-storage": "./dist/cloudflare/auth-secondary-storage.js",
+    "./cloudflare/durable-object-client": "./dist/cloudflare/durable-object-client.js",
+    "./cloudflare/durable-object-errors": "./dist/cloudflare/durable-object-errors.js",
     "./cloudflare/queue": "./dist/cloudflare/queue.js",
     "./cloudflare/scheduled": "./dist/cloudflare/scheduled.js",
     "./core": "./dist/core.js",
     "./http": "./dist/http.js",
     "./postgres": "./dist/postgres.js",
+    "./posthog/client": "./dist/posthog/client.js",
+    "./posthog/metrics": "./dist/posthog/metrics.js",
+    "./posthog/proxy": "./dist/posthog/proxy.js",
+    "./posthog/server": "./dist/posthog/server.js",
     "./resend": "./dist/resend.js",
+    "./sentry/client": "./dist/sentry/client.js",
+    "./sentry/server": "./dist/sentry/server.js",
+    "./sentry/vite": "./dist/sentry/vite.js",
     "./tanstack": "./dist/tanstack.js",
     "./tanstack/server": "./dist/tanstack/server.js",
     "./testing/outbox-repository": "./dist/testing/outbox-repository.js",
@@ -58,7 +67,7 @@
     "@tanstack/start-storage-context": "^1.167.31",
     "@types/node": "^26.5.1",
     "@types/react": "^19.3.0",
-    "@vitest/browser-playwright": "^5.0.0",
+    "@vitest/browser-playwright": "^4.1.11",
     "auth": "^1.7.4",
     "better-auth": "^1.7.4",
     "drizzle-kit": "^0.31.10",

package/src/application/analytics-service.ts

@@ -0,0 +1,21 @@
+import type { AnalyticsEventIdentity, AnalyticsEventInput, AnalyticsProperties } from '@/core'
+
+/** Product analytics without an SDK dependency, ported from Typist and Porte. */
+export interface AnalyticsService<TEvent extends AnalyticsEventInput = AnalyticsEventInput> {
+  /** Attach traits to one person. */
+  identify(distinctId: string, properties?: AnalyticsProperties): void
+  /** Merge a previous ID into this person; the application must establish that both identify the same person. */
+  alias(distinctId: string, previousDistinctId: string): void
+  /** Schedule an event for a person; returning does not confirm remote acceptance. */
+  track(event: TEvent, distinctId: string, identity?: AnalyticsEventIdentity): void
+  /** Schedule an event without creating a person profile for its distinct ID. */
+  trackAnonymous(event: TEvent, distinctId: string, identity?: AnalyticsEventIdentity): void
+}
+
+/** Reports to nobody. The composition root selects this service when analytics is disabled. */
+export const NULL_ANALYTICS: AnalyticsService = {
+  identify: () => {},
+  alias: () => {},
+  track: () => {},
+  trackAnonymous: () => {},
+}

package/src/application/email-service.ts

@@ -22,8 +22,8 @@ export type OutboundEmail = {
   readonly to: string | readonly string[]
   readonly subject: string
   readonly html: string
-  /** The stable identity of this send. Resend deduplicates it for 24 hours. */
-  readonly idempotencyKey: EmailIdempotencyKey
+  /** Optional stable identity of this send. Resend deduplicates supplied keys for 24 hours. */
+  readonly idempotencyKey?: EmailIdempotencyKey
   /** Resend generates plain text from html when omitted. An empty string disables that generation. */
   readonly text?: string
   readonly replyTo?: string

package/src/application/index.ts

@@ -1,4 +1,17 @@
 export type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
+export { NULL_ANALYTICS, type AnalyticsService } from './analytics-service.ts'
+export {
+  NULL_METRICS_SERVICE,
+  type MetricsService,
+  type MetricOptions,
+  type MetricAttributes,
+  type MetricAttributeValue,
+} from './metrics-service.ts'
+export type {
+  ObservabilityService,
+  ObservabilityScope,
+  ObservabilityUser,
+} from './observability-service.ts'
 export {
   RecordingEmailService,
   type IEmailService,

package/src/application/metrics-service.ts

@@ -0,0 +1,28 @@
+/** A metric dimension; use a small, bounded value set and never user or request IDs. */
+export type MetricAttributeValue = string | number | boolean
+
+/** Dimensions shared by observations in one time series. */
+export type MetricAttributes = Readonly<Record<string, MetricAttributeValue>>
+
+/** Unit and dimensions for an operational measurement. */
+export interface MetricOptions {
+  readonly attributes?: MetricAttributes
+  readonly unit?: string
+}
+
+/** Operational measurements, ported from Typist's metrics-service.ts; applications own metric names. */
+export interface MetricsService<TName extends string = string> {
+  /** Add a nonnegative value to a total; the default increment is one. */
+  count(name: TName, value?: number, options?: MetricOptions): void
+  /** Record a current value. */
+  gauge(name: TName, value: number, options?: MetricOptions): void
+  /** Record one observation in a distribution. */
+  histogram(name: TName, value: number, options?: MetricOptions): void
+}
+
+/** Records nothing when the composition root disables metrics. */
+export const NULL_METRICS_SERVICE: MetricsService = {
+  count: () => {},
+  gauge: () => {},
+  histogram: () => {},
+}

package/src/application/observability-service.ts

@@ -0,0 +1,16 @@
+/** The identity an error report belongs to. */
+export interface ObservabilityUser {
+  readonly id: string
+}
+
+/** Identity within one isolated execution. */
+export interface ObservabilityScope {
+  /** Attribute reports in this scope to one person. */
+  setUser(user: ObservabilityUser): void
+}
+
+/** Error identity and isolation, ported from Porte's sentry-observability-service.ts. */
+export interface ObservabilityService extends ObservabilityScope {
+  /** Await work in its own scope so concurrent executions do not share identity. */
+  withIsolationScope<T>(callback: (scope: ObservabilityScope) => T | Promise<T>): Promise<T>
+}

package/src/core/analytics-event.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod'
+
+/** An event name and its application-owned properties, ported from Typist's analytics/types.ts. */
+export interface AnalyticsEventInput<
+  TName extends string = string,
+  TProperties extends object = object,
+> {
+  readonly name: TName
+  readonly properties: TProperties
+}
+
+/** A value supported by analytics person properties. */
+export type AnalyticsProperty =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | readonly AnalyticsProperty[]
+  | AnalyticsProperties
+
+/** Person properties supplied by the application. */
+export interface AnalyticsProperties {
+  readonly [name: string]: AnalyticsProperty
+}
+
+/** Parse a persisted analytics event UUID; the SDK generates ordinary event UUIDs itself. */
+export const AnalyticsEventIdSchema = z.uuid().brand<'AnalyticsEventId'>()
+
+/** The identity of one analytics event across repeated application deliveries. */
+export type AnalyticsEventId = z.infer<typeof AnalyticsEventIdSchema>
+
+/** Supply both original values when replaying one event; never share them across different occurrences. */
+export interface AnalyticsEventIdentity {
+  readonly uuid: AnalyticsEventId
+  readonly timestamp: Date
+}

package/src/core/index.ts

@@ -1,4 +1,13 @@
 export { AppError } from './app-error.ts'
+export { MissingConfigurationError } from './missing-configuration.error.ts'
+export {
+  AnalyticsEventIdSchema,
+  type AnalyticsEventId,
+  type AnalyticsEventIdentity,
+  type AnalyticsEventInput,
+  type AnalyticsProperties,
+  type AnalyticsProperty,
+} from './analytics-event.ts'
 export { EmailAddressSchema, type EmailAddress } from './email-address.ts'
 export {
   emailIdempotencyKey,

package/src/core/missing-configuration.error.ts

@@ -0,0 +1,12 @@
+import { AppError } from './app-error.ts'
+
+/** Required configuration is absent. Ported from Porte's configuration.errors.ts. */
+export class MissingConfigurationError extends AppError {
+  readonly _tag = 'MissingConfigurationError'
+  readonly classification = 'terminal'
+
+  /** Name the missing setting without including its value. */
+  constructor(readonly key: string) {
+    super(`${key} is required`)
+  }
+}

package/src/infrastructure/cloudflare/durable-object-client.ts

@@ -0,0 +1,70 @@
+import { Result } from 'better-result'
+
+import { isAbortError, shouldRetryFailure } from '@/core'
+
+import {
+  classifyDurableObjectError,
+  DurableObjectCallError,
+  isClassifiedDurableObjectError,
+} from './durable-object-errors.ts'
+
+/** Resolve a fresh stub on every call, including calls after a failed attempt. */
+export type DurableObjectResolver<Object extends object> = {
+  getByName(name: string): Object | Promise<Object>
+}
+
+type Call<Object extends object, R> = (object: Object) => Promise<R>
+
+/** Product clients name operations and establish repeat safety; this client owns transport retries. */
+export abstract class DurableObjectClient<
+  T extends Rpc.DurableObjectBranded,
+  Object extends object = DurableObjectStub<T>,
+> {
+  constructor(private readonly objects: DurableObjectResolver<Object>) {}
+
+  /** Retry transient failures only when repeating the entire callback is safe. */
+  protected repeatable<R>(name: string, work: Call<Object, R>): Promise<R> {
+    return this.run(name, work, true)
+  }
+
+  /** Make one attempt when repetition is unsafe or another caller owns retries. */
+  protected once<R>(name: string, work: Call<Object, R>): Promise<R> {
+    return this.run(name, work, false)
+  }
+
+  private async run<R>(name: string, work: Call<Object, R>, repeatSafe: boolean): Promise<R> {
+    const result = await Result.tryPromise(
+      {
+        // A failed RPC can break the stub permanently, so every attempt resolves it again.
+        try: async () => work(await this.objects.getByName(name)),
+        catch: (cause) => cause,
+      },
+      {
+        retry: {
+          times: 2,
+          delayMs: 25,
+          backoff: 'exponential',
+          jitter: true,
+          shouldRetry: (cause) => {
+            if (isAbortError(cause) || isClassifiedDurableObjectError(cause)) return false
+            return shouldRetryFailure({
+              classification: classifyDurableObjectError(cause),
+              repeatSafe,
+              owner: 'immediate',
+            })
+          },
+        },
+      },
+    )
+    if (result.isOk()) return result.value
+    if (
+      isAbortError(result.error) ||
+      isClassifiedDurableObjectError(result.error) ||
+      classifyDurableObjectError(result.error) === 'unknown'
+    ) {
+      // oxlint-disable-next-line typescript/only-throw-error -- Preserve raw failures for the owning error boundary.
+      throw result.error
+    }
+    throw new DurableObjectCallError({ cause: result.error })
+  }
+}

package/src/infrastructure/cloudflare/durable-object-errors.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod'
+
+import {
+  AppError,
+  isAbortError,
+  isCloudflareOverloadedError,
+  isCloudflareRetryableError,
+  isTransientCloudflareRuntimeError,
+  isTransientTransportError,
+  type FailureClassification,
+} from '@/core'
+
+/** Stable tag for a failed Durable Object call. */
+export const DURABLE_OBJECT_CALL_ERROR = 'DurableObjectCallError'
+
+const RemoteClassifiedErrorSchema = z.object({
+  _tag: z.string(),
+  classification: z.enum(['transient', 'terminal', 'unknown']),
+  remote: z.literal(true),
+})
+
+const RemoteCallErrorSchema = RemoteClassifiedErrorSchema.extend({
+  _tag: z.literal(DURABLE_OBJECT_CALL_ERROR),
+  cause: z.unknown(),
+})
+
+/** Recognize a judged local or remote error without admitting its tag to the public error table. */
+export function isClassifiedDurableObjectError(
+  cause: unknown,
+): cause is AppError | (Error & z.output<typeof RemoteClassifiedErrorSchema>) {
+  return (
+    cause instanceof AppError ||
+    (cause instanceof Error && RemoteClassifiedErrorSchema.safeParse(cause).success)
+  )
+}
+
+/** Classify the error itself. Its cause remains diagnostic evidence, not a second retry decision. */
+export function classifyDurableObjectError(cause: unknown): FailureClassification {
+  if (isAbortError(cause)) return 'terminal'
+  if (isClassifiedDurableObjectError(cause)) return cause.classification
+  if (isCloudflareOverloadedError(cause)) return 'terminal'
+  if (
+    isCloudflareRetryableError(cause) ||
+    isTransientCloudflareRuntimeError(cause) ||
+    isTransientTransportError(cause)
+  )
+    return 'transient'
+  return 'unknown'
+}
+
+/** Identify a local call error or its validated Workers RPC representation. */
+export function isDurableObjectCallError(
+  cause: unknown,
+): cause is DurableObjectCallError | (Error & z.output<typeof RemoteCallErrorSchema>) {
+  return (
+    cause instanceof DurableObjectCallError ||
+    (cause instanceof Error && RemoteCallErrorSchema.safeParse(cause).success)
+  )
+}
+
+/** A call failed after retries stopped. Classification does not establish repeat safety. */
+export class DurableObjectCallError extends AppError {
+  readonly _tag = DURABLE_OBJECT_CALL_ERROR
+  readonly classification: FailureClassification
+
+  constructor(args: { readonly cause: unknown }) {
+    super('Durable Object call failed', { cause: args.cause })
+    this.classification = classifyDurableObjectError(args.cause)
+  }
+}

package/src/infrastructure/posthog/client.ts

@@ -0,0 +1,41 @@
+import posthog, { type PostHog, type PostHogConfig } from 'posthog-js'
+
+/** The application controls enablement; disabled initialization needs no project key. */
+export type PostHogClientConfig =
+  | { readonly enabled: false }
+  | {
+      readonly enabled: true
+      readonly apiKey: string
+      readonly environment: string
+      readonly source: string
+      readonly options?: Partial<PostHogConfig>
+    }
+
+/** Browser options from Typist and Porte; SDK option names and application overrides stay intact. */
+export function createPostHogClientOptions(
+  config: Extract<PostHogClientConfig, { enabled: true }>,
+): Partial<PostHogConfig> {
+  return {
+    api_host: '/relay',
+    ui_host: 'https://us.posthog.com',
+    person_profiles: 'identified_only',
+    defaults: '2026-08-29',
+    disable_surveys: true,
+    advanced_disable_feature_flags: true,
+    capture_performance: { web_vitals: false },
+    ...config.options,
+    loaded: (client) => {
+      client.register({ environment: config.environment, source: config.source })
+      config.options?.loaded?.(client)
+    },
+  }
+}
+
+/** Initialize once in the browser entrypoint; pass the returned SDK client to PostHogProvider. */
+export function initializePostHog(config: PostHogClientConfig): PostHog {
+  if (!config.enabled) return posthog
+  posthog.init(config.apiKey, createPostHogClientOptions(config))
+  return posthog
+}
+
+export { PostHogProvider, usePostHog } from '@posthog/react'

package/src/infrastructure/posthog/metrics.ts

@@ -0,0 +1,30 @@
+import type { PostHog } from 'posthog-node'
+
+import type { MetricOptions, MetricsService } from '@/application'
+
+/** PostHog Metrics with Worker lifetime management, ported from Typist's metrics-service.ts. */
+export class PostHogMetricsService implements MetricsService {
+  /** Use the analytics client's metrics; the runtime owns each flush promise. */
+  constructor(
+    private readonly client: Pick<PostHog, 'metrics'>,
+    private readonly waitUntil: (promise: Promise<unknown>) => void,
+  ) {}
+
+  /** Record a total and schedule its flush. */
+  count(name: string, value = 1, options?: MetricOptions): void {
+    this.client.metrics.count(name, value, options)
+    this.waitUntil(this.client.metrics.flush())
+  }
+
+  /** Record a current value and schedule its flush. */
+  gauge(name: string, value: number, options?: MetricOptions): void {
+    this.client.metrics.gauge(name, value, options)
+    this.waitUntil(this.client.metrics.flush())
+  }
+
+  /** Record an observation and schedule its flush. */
+  histogram(name: string, value: number, options?: MetricOptions): void {
+    this.client.metrics.histogram(name, value, options)
+    this.waitUntil(this.client.metrics.flush())
+  }
+}

package/src/infrastructure/posthog/proxy.ts

@@ -0,0 +1,47 @@
+/** Runtime resources and deployment hosts for Typist's same-origin proxy. */
+export interface PostHogProxyOptions {
+  readonly cache: Pick<Cache, 'match' | 'put'>
+  readonly waitUntil: (promise: Promise<void>) => void
+  readonly basePath?: string
+  readonly ingestHost?: string
+  readonly assetHost?: string
+  readonly fetch?: typeof globalThis.fetch
+}
+
+/**
+ * Mount at /relay/$ with GET, POST, and OPTIONS handlers. Supply Cloudflare's asset cache and waitUntil.
+ * The application must use the same base path in the browser's api_host option.
+ */
+export async function proxyPostHogRequest(
+  request: Request,
+  options: PostHogProxyOptions,
+): Promise<Response> {
+  const url = new URL(request.url)
+  const basePath = options.basePath ?? '/relay'
+  if (!url.pathname.startsWith(`${basePath}/`)) return new Response(null, { status: 404 })
+  const pathname = url.pathname.slice(basePath.length)
+  const pathWithSearch = pathname + url.search
+  const send = options.fetch ?? globalThis.fetch
+
+  if (pathname.startsWith('/static/') || pathname.startsWith('/array/')) {
+    const cached = await options.cache.match(request)
+    if (cached) return cached
+    const response = await send(
+      `https://${options.assetHost ?? 'us-assets.i.posthog.com'}${pathWithSearch}`,
+    )
+    options.waitUntil(options.cache.put(request, response.clone()))
+    return response
+  }
+
+  const headers = new Headers(request.headers)
+  headers.delete('cookie')
+  headers.delete('authorization')
+  headers.set('X-Forwarded-For', request.headers.get('CF-Connecting-IP') ?? '')
+  return await send(`https://${options.ingestHost ?? 'us.i.posthog.com'}${pathWithSearch}`, {
+    method: request.method,
+    headers,
+    body:
+      request.method !== 'GET' && request.method !== 'HEAD' ? await request.arrayBuffer() : null,
+    redirect: request.redirect,
+  })
+}

package/src/infrastructure/posthog/server.ts

@@ -0,0 +1,107 @@
+import { PostHog, type PostHogOptions } from 'posthog-node'
+
+import type { AnalyticsService } from '@/application'
+import {
+  MissingConfigurationError,
+  type AnalyticsEventIdentity,
+  type AnalyticsEventInput,
+  type AnalyticsProperties,
+} from '@/core'
+
+import { PostHogMetricsService } from './metrics.ts'
+
+/** Deployment values and SDK options; the runtime owns delivery promises. */
+export interface PostHogAnalyticsConfig {
+  readonly apiKey: string
+  readonly environment: string
+  readonly source: string
+  readonly waitUntil: (promise: Promise<unknown>) => void
+  readonly options?: Omit<
+    PostHogOptions,
+    'waitUntil' | 'flushAt' | 'flushInterval' | 'metrics' | 'disabled'
+  > & {
+    readonly metrics?: Omit<NonNullable<PostHogOptions['metrics']>, 'serviceName' | 'environment'>
+  }
+}
+
+/** Worker analytics ported from Typist; disabled applications select Porte's NULL_ANALYTICS instead. */
+export class PostHogAnalyticsService implements AnalyticsService {
+  /** Metrics share this service's SDK client and delivery lifetime. */
+  readonly metrics: PostHogMetricsService
+
+  private constructor(
+    /** Raw SDK access for integrations such as PostHog AI tracing. */
+    readonly posthog: PostHog,
+    private readonly waitUntil: (promise: Promise<unknown>) => void,
+  ) {
+    this.metrics = new PostHogMetricsService(posthog, waitUntil)
+  }
+
+  /** Construct once per Worker invocation; a blank key throws MissingConfigurationError. */
+  static create(config: PostHogAnalyticsConfig): PostHogAnalyticsService {
+    const apiKey = config.apiKey.trim()
+    if (apiKey.length === 0) throw new MissingConfigurationError('POSTHOG_API_KEY')
+    const client = new PostHog(apiKey, {
+      host: 'https://us.i.posthog.com',
+      ...config.options,
+      flushAt: 1,
+      flushInterval: 0,
+      waitUntil: config.waitUntil,
+      metrics: {
+        ...config.options?.metrics,
+        environment: config.environment,
+        serviceName: config.source,
+      },
+    })
+    // The SDK applies in-memory super properties synchronously before this promise resolves.
+    void client.register({ environment: config.environment, source: config.source })
+    return new PostHogAnalyticsService(client, config.waitUntil)
+  }
+
+  /** Schedule person properties; the SDK's waitUntil option protects queued delivery. */
+  identify(distinctId: string, properties?: AnalyticsProperties): void {
+    const payload: Parameters<PostHog['identify']>[0] = { distinctId }
+    if (properties !== undefined) payload.properties = properties
+    this.posthog.identify(payload)
+  }
+
+  /** Schedule an irreversible person merge; only alias IDs the application proves belong to one person. */
+  alias(distinctId: string, previousDistinctId: string): void {
+    this.waitUntil(this.posthog.aliasImmediate({ distinctId, alias: previousDistinctId }))
+  }
+
+  /** Schedule an event; omit identity for SDK-generated UUID and capture time. */
+  track(event: AnalyticsEventInput, distinctId: string, identity?: AnalyticsEventIdentity): void {
+    this.capture(event, distinctId, 'person', identity)
+  }
+
+  /** Schedule an event without creating a person profile for an attempt or resource ID. */
+  trackAnonymous(
+    event: AnalyticsEventInput,
+    distinctId: string,
+    identity?: AnalyticsEventIdentity,
+  ): void {
+    this.capture(event, distinctId, 'anonymous', identity)
+  }
+
+  private capture(
+    event: AnalyticsEventInput,
+    distinctId: string,
+    profile: 'person' | 'anonymous',
+    identity?: AnalyticsEventIdentity,
+  ): void {
+    const properties = { ...event.properties }
+    const payload: Parameters<PostHog['captureImmediate']>[0] = {
+      distinctId,
+      event: event.name,
+      properties,
+    }
+    if (profile === 'anonymous')
+      payload.properties = { ...properties, $process_person_profile: false }
+    if (identity !== undefined) {
+      payload.uuid = identity.uuid
+      payload.timestamp = identity.timestamp
+    }
+    this.waitUntil(this.posthog.captureImmediate(payload))
+  }
+}

package/src/infrastructure/resend/resend-email-service.ts

@@ -109,7 +109,10 @@ export class ResendEmailService implements IEmailService {
     if (email.tags !== undefined)
       payload.tags = Object.entries(email.tags).map(([name, value]) => ({ name, value }))
     if (email.attachments !== undefined) payload.attachments = email.attachments.map(toAttachment)
-    const result = await client.emails.send(payload, { idempotencyKey: email.idempotencyKey })
+    const result = await client.emails.send(
+      payload,
+      email.idempotencyKey === undefined ? undefined : { idempotencyKey: email.idempotencyKey },
+    )
     if (result.error !== null) {
       throw new EmailServiceError({
         reason: reasonFromResend(result.error),