@q32/core 0.1.28 → 0.2.0

package/src/ses-sns.ts

@@ -0,0 +1,144 @@
+export type SnsEnvelope = {
+  Type?: string;
+  Message?: string;
+  MessageId?: string;
+  TopicArn?: string;
+  SubscribeURL?: string;
+};
+
+export type SesFeedbackMessage = {
+  eventType?: string;
+  notificationType?: string;
+  mail?: {
+    destination?: unknown;
+  };
+  bounce?: {
+    bouncedRecipients?: Array<{ emailAddress?: unknown }>;
+  };
+  complaint?: {
+    complainedRecipients?: Array<{ emailAddress?: unknown }>;
+  };
+};
+
+export type SesFeedbackEvent = {
+  eventType: string;
+  emails: string[];
+  messageId?: string;
+  topicArn?: string;
+};
+
+export type SesReceiptMessage = {
+  mail?: {
+    messageId?: string;
+    source?: string;
+    commonHeaders?: {
+      subject?: string;
+    };
+  };
+  receipt?: {
+    recipients?: string[];
+  };
+};
+
+export type SesReceiptEvent = {
+  messageId: string;
+  source?: string;
+  subject?: string;
+  recipients: string[];
+  snsMessageId?: string;
+  topicArn?: string;
+};
+
+export function parseSnsEnvelope(body: string): SnsEnvelope | null {
+  const parsed = parseJsonObject(body);
+  if (!parsed) return null;
+  return parsed as SnsEnvelope;
+}
+
+export function isTrustedSnsSubscribeUrl(raw: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return false;
+  }
+  return (
+    url.protocol === "https:" &&
+    (/^sns[.-][a-z0-9-]+\.amazonaws\.com$/i.test(url.hostname) ||
+      /^sns\.[a-z0-9-]+\.amazonaws\.com\.cn$/i.test(url.hostname))
+  );
+}
+
+export async function confirmSnsSubscription(envelope: SnsEnvelope, fetcher: typeof fetch = fetch): Promise<boolean> {
+  if (envelope.Type !== "SubscriptionConfirmation" || typeof envelope.SubscribeURL !== "string") return false;
+  if (!isTrustedSnsSubscribeUrl(envelope.SubscribeURL)) return false;
+  const response = await fetcher(envelope.SubscribeURL, { method: "GET" });
+  return response.ok;
+}
+
+export function parseSesFeedbackNotification(envelope: SnsEnvelope): SesFeedbackEvent | null {
+  if (envelope.Type !== "Notification" || typeof envelope.Message !== "string") return null;
+  const message = parseJsonObject(envelope.Message) as SesFeedbackMessage | null;
+  if (!message) return null;
+  const { eventType, emails } = extractSesFeedbackRecipients(message);
+  if (!eventType) return null;
+  return {
+    eventType,
+    emails,
+    ...(envelope.MessageId ? { messageId: envelope.MessageId } : {}),
+    ...(envelope.TopicArn ? { topicArn: envelope.TopicArn } : {}),
+  };
+}
+
+export function extractSesFeedbackRecipients(message: SesFeedbackMessage): { eventType: string; emails: string[] } {
+  const eventType = String(message.eventType ?? message.notificationType ?? "");
+  const normalized = eventType.toLowerCase();
+  if (normalized === "bounce") {
+    const recipients = message.bounce?.bouncedRecipients?.map((recipient) => recipient.emailAddress) ?? [];
+    return { eventType, emails: uniqueEmails(recipients.length > 0 ? recipients : fallbackDestination(message)) };
+  }
+  if (normalized === "complaint") {
+    const recipients = message.complaint?.complainedRecipients?.map((recipient) => recipient.emailAddress) ?? [];
+    return { eventType, emails: uniqueEmails(recipients.length > 0 ? recipients : fallbackDestination(message)) };
+  }
+  return { eventType, emails: [] };
+}
+
+export function parseSesReceiptNotification(envelope: SnsEnvelope): SesReceiptEvent | null {
+  if (envelope.Type !== "Notification" || typeof envelope.Message !== "string") return null;
+  const message = parseJsonObject(envelope.Message) as SesReceiptMessage | null;
+  const messageId = message?.mail?.messageId;
+  const recipients = message?.receipt?.recipients ?? [];
+  if (!messageId || recipients.length === 0) return null;
+  return {
+    messageId,
+    recipients,
+    ...(message.mail?.source ? { source: message.mail.source } : {}),
+    ...(message.mail?.commonHeaders?.subject ? { subject: message.mail.commonHeaders.subject } : {}),
+    ...(envelope.MessageId ? { snsMessageId: envelope.MessageId } : {}),
+    ...(envelope.TopicArn ? { topicArn: envelope.TopicArn } : {}),
+  };
+}
+
+function parseJsonObject(value: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+function fallbackDestination(message: SesFeedbackMessage): unknown[] {
+  return Array.isArray(message.mail?.destination) ? message.mail.destination : [];
+}
+
+function uniqueEmails(values: Iterable<unknown>): string[] {
+  const emails = new Set<string>();
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const email = value.trim().toLowerCase();
+    if (email.includes("@")) emails.add(email);
+  }
+  return [...emails];
+}

package/src/ses.ts

@@ -0,0 +1,180 @@
+import { awsFetch, createAwsConfigFromEnv, type AwsConfig, type AwsEnv } from "./aws.js";
+import { buildRawMimeMessage, formatEmailAddress, type EmailAddress, type SendEmailInput } from "./email.js";
+
+export type SesEmailInput = Omit<SendEmailInput, "from"> & {
+  from?: EmailAddress;
+  headers?: Record<string, string>;
+};
+
+export type SesSendResult = {
+  messageId: string;
+  provider: "ses";
+};
+
+export type SesMailer = {
+  readonly enabled: boolean;
+  send(input: SesEmailInput): Promise<SesSendResult>;
+};
+
+export type SesMailerEnv = AwsEnv & {
+  FROM_EMAIL?: string;
+  EMAIL_FROM?: string;
+  NOTIFICATION_FROM_EMAIL?: string;
+  POSTMARK_FROM_EMAIL?: string;
+  SES_FROM_EMAIL?: string;
+  EMAIL_REPLY_TO?: string;
+  NOTIFICATION_REPLY_TO?: string;
+};
+
+export type SesSendOptions = {
+  fetcher?: typeof fetch;
+};
+
+export class NoopSesMailer implements SesMailer {
+  readonly enabled = false;
+
+  async send(): Promise<SesSendResult> {
+    throw new Error("SES mailer is not configured.");
+  }
+}
+
+export class WorkerSesMailer implements SesMailer {
+  readonly enabled = true;
+
+  constructor(
+    private readonly config: AwsConfig,
+    private readonly defaults: {
+      from: EmailAddress;
+      replyTo?: EmailAddress[];
+      fetcher?: typeof fetch;
+    },
+  ) {}
+
+  send(input: SesEmailInput): Promise<SesSendResult> {
+    return sendSesEmail(this.config, {
+      ...input,
+      from: input.from ?? this.defaults.from,
+      replyTo: input.replyTo ?? this.defaults.replyTo,
+    }, { fetcher: this.defaults.fetcher });
+  }
+}
+
+export function createSesMailerFromEnv(
+  env: SesMailerEnv,
+  options: {
+    fromEmail?: string;
+    fromName?: string;
+    replyTo?: string | string[] | null;
+    fetcher?: typeof fetch;
+  } = {},
+): SesMailer {
+  const config = createAwsConfigFromEnv(env);
+  const fromEmail = options.fromEmail ?? env.FROM_EMAIL ?? env.EMAIL_FROM ?? env.NOTIFICATION_FROM_EMAIL ?? env.POSTMARK_FROM_EMAIL ?? env.SES_FROM_EMAIL;
+  if (!config || !fromEmail) return new NoopSesMailer();
+  const replyTo = options.replyTo ?? env.NOTIFICATION_REPLY_TO ?? env.EMAIL_REPLY_TO;
+  return new WorkerSesMailer(config, {
+    from: { email: fromEmail, name: options.fromName },
+    replyTo: typeof replyTo === "string"
+      ? [{ email: replyTo }]
+      : Array.isArray(replyTo)
+        ? replyTo.map((email) => ({ email }))
+        : undefined,
+    fetcher: options.fetcher,
+  });
+}
+
+export async function sendSesEmail(
+  config: AwsConfig,
+  input: SendEmailInput & { headers?: Record<string, string> },
+  options: SesSendOptions = {},
+): Promise<SesSendResult> {
+  const hasRawFeatures = Boolean(input.headers && Object.keys(input.headers).length > 0) || Boolean(input.attachments?.length);
+  const body = hasRawFeatures ? rawSesBody(input) : simpleSesBody(input);
+  const response = await awsFetch(config, `https://email.${config.region}.amazonaws.com/v2/email/outbound-emails`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  }, { service: "ses", fetcher: options.fetcher });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`SES send failed: ${response.status} ${text.slice(0, 300)}`);
+  const payload = parseJsonObject(text);
+  const messageId = stringValue(payload.MessageId) ?? stringValue(payload.messageId) ?? "";
+  return { provider: "ses", messageId };
+}
+
+export async function sesQuery(
+  config: AwsConfig,
+  params: Record<string, string>,
+  options: SesSendOptions = {},
+): Promise<string> {
+  const body = new URLSearchParams({ Version: "2010-12-01", ...params }).toString();
+  const response = await awsFetch(config, `https://email.${config.region}.amazonaws.com/`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body,
+  }, { service: "ses", fetcher: options.fetcher });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`SES ${params.Action ?? "query"} failed: ${response.status} ${text.slice(0, 300)}`);
+  return text;
+}
+
+export function inboundSesMxHost(region = "us-east-1"): string {
+  return `inbound-smtp.${region}.amazonaws.com`;
+}
+
+function simpleSesBody(input: SendEmailInput): Record<string, unknown> {
+  return {
+    FromEmailAddress: formatEmailAddress(input.from),
+    Destination: {
+      ToAddresses: input.to.map(formatEmailAddress),
+      ...(input.cc?.length ? { CcAddresses: input.cc.map(formatEmailAddress) } : {}),
+      ...(input.bcc?.length ? { BccAddresses: input.bcc.map(formatEmailAddress) } : {}),
+    },
+    ...(input.replyTo?.length ? { ReplyToAddresses: input.replyTo.map(formatEmailAddress) } : {}),
+    Content: {
+      Simple: {
+        Subject: { Data: input.subject, Charset: "UTF-8" },
+        Body: {
+          ...(input.text ? { Text: { Data: input.text, Charset: "UTF-8" } } : {}),
+          ...(input.html ? { Html: { Data: input.html, Charset: "UTF-8" } } : {}),
+        },
+      },
+    },
+  };
+}
+
+function rawSesBody(input: SendEmailInput & { headers?: Record<string, string> }): Record<string, unknown> {
+  return {
+    FromEmailAddress: formatEmailAddress(input.from),
+    Destination: {
+      ToAddresses: input.to.map(formatEmailAddress),
+      ...(input.cc?.length ? { CcAddresses: input.cc.map(formatEmailAddress) } : {}),
+      ...(input.bcc?.length ? { BccAddresses: input.bcc.map(formatEmailAddress) } : {}),
+    },
+    Content: {
+      Raw: {
+        Data: textToBase64(buildRawMimeMessage(input)),
+      },
+    },
+  };
+}
+
+function textToBase64(value: string): string {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function parseJsonObject(value: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+  } catch {
+    return {};
+  }
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}

package/docs/commonality-adgiro-relin-dirtsignal.md

@@ -1,28 +0,0 @@
-# Adgiro, Relin, and DirtSignal Commonality
-
-This is the current direction for `@q32/core`: choose the best reusable pattern across the projects, then move the projects toward it.
-
-## Chosen Defaults
-
-- Postgres access should use Kysely over raw SQL once a project has long-lived relational read models. DirtSignal has the largest raw `postgres` surface today, but Relin's Kysely layer is the better long-term default because it makes schema ownership, joins, transactions, and refactors safer.
-- Cloudflare Workers should create PG clients per request, queue invocation, cron tick, or script scope. Hyperdrive owns pooling in Worker runtime; Node scripts and tests should close clients explicitly.
-- PG connection resolution should prefer Hyperdrive, then `PG_URL`, then an explicit test fallback only when the caller opts in.
-- Non-local PG should use TLS by default. A provided `PG_CA_CERT` should be normalized and used for certificate verification.
-- PG migrations should be explicit, status/dry-run capable, and separated from runtime credentials. Relin's admin/runtime split is the better default; DirtSignal's typed migration-array model is better than ad hoc SQL file parsing for application-owned schema modules.
-- D1 remains the default for small control-plane state, but shared auth, jobs, and ops-event tables should be configurable D1 modules, not app-local forks.
-
-## Core Modules To Grow
-
-- `pg-kysely`: Kysely + `postgres.js` construction, Hyperdrive/PG_URL/CA-cert policy, and scoped `withKyselyPg`.
-- `pg-migrations`: one migration runner that can consume SQL files or typed migration arrays, with status, dry-run, reset guard, and configurable migrations table.
-- `d1-auth`: configurable users/orgs/memberships/identities/magic-link/session helpers. Apps keep policy and copy; core owns token hashing, one-time consume, identity upsert, and session persistence patterns.
-- `mcp-oauth-d1`: the common OAuth client/code/token/device-flow repository used by Relin and DirtSignal, with app-provided principal lookup and entitlement policy.
-- `d1-jobs`: Adgiro's richer job driver is closer to the target than the current minimal core job helper. Core should own enqueue policies, active locks, concurrency keys, delayed requeue, stale-running recovery, and linked ops events.
-- `queue`: a typed Cloudflare Queue publisher/consumer adapter with inline mode for tests and local single-process execution.
-- `ops-events`: converge on run IDs, event names, statuses/severity, target identifiers, metadata/error normalization, and best-effort writes.
-
-## Project Movement
-
-- Relin should keep using Kysely for PG and replace its local connection lifecycle with `@q32/core/pg-kysely`.
-- DirtSignal should migrate new PG repositories to Kysely first, then wrap existing raw `postgres` repositories behind Kysely-compatible interfaces as they change.
-- Adgiro should adopt the shared D1 job driver shape and ops-event schema before adding PG. If it adds PG, it should start on Kysely rather than raw `postgres`.

package/docs/evaluation.md

@@ -1,76 +0,0 @@
-# Suitability Evaluation
-
-This package was seeded from repeated infrastructure found across Erik/Q32 TypeScript projects, including `adgiro`, `bizsnipe`, `dirtsignal`, `getflight`, `graphilize`, `ipogrid`, `logtura`, `onwardtravel`, `relin`, `zura`, and the `domains/*` apps.
-
-## Replacement Matrix
-
-| Common pattern | Current module | Suitable replacement scope |
-| --- | --- | --- |
-| AI JSON helper conventions | `ai` | Standardize model request/response contracts and JSON extraction around official provider SDK calls. |
-| Typed environment helpers and app URL fallback | `env` | Replace local `getAppUrl`, required env, optional boolean, and binding guard helpers. |
-| Cloudflare binding checks | `cloudflare` | Replace repeated `DB`, `R2`, and Queue binding guard code in Workers. |
-| JSON responses, bearer/admin token checks, request body parsing | `http` | Replace repeated Worker/Hono-adjacent HTTP utility functions. |
-| Prefixed IDs, random tokens, base64url, SHA-256 | `ids` | Replace local `createId`, token, digest-key, and hash helpers. |
-| Signed session tokens and cookies | `session` | Replace small HMAC session implementations where full auth frameworks are unnecessary. |
-| Auth/session/MCP authorization policy | `auth` | Keep principal lookup, session verification, admin checks, OAuth authorization-code exchange, token verification, and refresh rotation independent of Hono, React Router, or any single app. |
-| Credential or provider-secret encryption | `crypto` | Replace local AES-GCM JSON encryption helpers backed by WebCrypto. |
-| D1-like database typing and explicit migrations | `d1` | Replace duplicated `D1DatabaseLike` types and simple migration runners. |
-| Postgres migration and JSON helpers | `pg` | Replace small pg migration scripts while still using official `pg` or `postgres` clients in apps. |
-| Background job table behavior | `jobs` | Replace D1 job enqueue/claim/run/requeue/succeed/fail loops in small Worker apps. |
-| Operator event recording and listing | `ops-events` | Replace repeated `ops_events` insert/list helpers. |
-| D1 fixed-window rate limits | `rate-limit` | Replace lead, login, public API, and admin throttle tables. |
-| R2 JSON payload/artifact storage | `r2-json` | Replace raw provider payload and generated artifact JSON storage helpers. |
-| SEO/static output conventions | `seo` | Replace ad hoc sitemap, robots, canonical, Open Graph, and noindex tag helpers. |
-| Email provider boundary | `email` | Standardize provider-independent send input/result shapes and address helpers. |
-| Billing plan/status checks | `billing` | Replace local plan rank and active subscription status helpers around Stripe-backed apps. |
-| Worker test helpers | `testing` | Replace small fake Queue/R2 helpers and JSON response assertions in unit tests; complements workerd/Miniflare integration tests. |
-| OAuth/MCP metadata and storage | `oauth`, `mcp` | Replace repeated discovery metadata, API-to-tool descriptors, and configurable D1 OAuth client/code/token repositories. |
-| API operation registries and discovery surfaces | `api` | Replace local operation registries, OpenAPI path generation, RFC 9727 API catalog linksets, Agent Skills indexes, and agent-discovery Link headers. |
-| MCP manifests and bearer challenges | `mcp` | Replace repeated server-card metadata, plain-GET MCP manifests, API-operation tool descriptors, tool annotations, and OAuth protected-resource challenge headers. |
-| Framework request adapters | `hono`, `react-router` | Translate Hono middleware and React Router loader/action requests into the same framework-neutral auth/API services. |
-
-## Current Fit
-
-The package is suitable for new Q32 Worker projects and for incremental replacement of local helpers in existing projects where the app-specific behavior is already separated from infrastructure primitives.
-
-Strong first replacement candidates:
-
-- D1-like interfaces duplicated in `relin` and `graphilize`.
-- `ops_events` helpers in `onwardtravel`, `bizsnipe`, `logtura`, and `bce.email`.
-- D1 jobs in `travelerideas`, `bizsnipe`, `logtura`, and smaller domain apps.
-- signed session, ID, token, and base64url helpers in `zura`, `relin`, `getflight`, and `adgiro`.
-- API operation metadata from `bce.email` and `relin`.
-- OAuth/MCP metadata and auth/token flow from `getflight`, `captcha`, `ipogrid`, `relin`, and `bce.email`.
-
-## Not Yet Complete
-
-The package intentionally does not yet replace:
-
-- complete app-specific login/account repositories
-- Stripe billing repositories
-- Postgres job runners and migration orchestration
-- email provider clients
-- Mantine app shells or SEO page components
-- OpenAI/provider retry adapters beyond the shared request/result contracts
-- Stripe webhook verification or Checkout/session creation, which should remain on the official Stripe SDK
-- Mantine app shells or React components
-
-Those should be added only after extracting one or two real migrations from existing apps so the shared API follows production usage rather than speculation.
-
-## Verification
-
-Current local gates:
-
-- `pnpm typecheck`
-- `pnpm test:coverage`
-- `pnpm build`
-- `pnpm pack --dry-run`
-
-Coverage threshold is enforced in `vitest.config.ts` and CI runs the same gates.
-
-Current coverage after the expanded common-module pass:
-
-- Statements: 89.26%
-- Branches: 75.25%
-- Functions: 96.66%
-- Lines: 95.15%

package/docs/goal-audit.md

@@ -1,28 +0,0 @@
-# Goal Audit
-
-Objective: working Q32 core libraries, with the common libraries discussed in the project inventory, a public repo at the `q32llc` org, working CI/CD, strong types and good test coverage, evaluated as suitable to replace much common code in existing projects.
-
-## Proven Complete
-
-| Requirement | Evidence |
-| --- | --- |
-| Public repo under `q32llc` | `https://github.com/q32llc/q32-core`, public, default branch `main`. |
-| Working local package | `pnpm build` succeeds and `pnpm pack --dry-run` produces a clean tarball. |
-| Strong TypeScript types | `pnpm typecheck` succeeds under `strict` TypeScript with generated declarations. |
-| Good test coverage | `pnpm test:coverage` succeeds with enforced thresholds; latest local coverage is 89.26% statements, 75.25% branches, 96.66% functions, 95.15% lines. |
-| Working CI | GitHub Actions CI passes on `main` and runs install, typecheck, coverage, build, and pack dry run. |
-| Common code surfaces | Modules exist for `api`, `ai`, `billing`, `cloudflare`, `crypto`, `d1`, `email`, `env`, `http`, `ids`, `jobs`, `mcp`, `oauth`, `ops-events`, `pg`, `r2-json`, `rate-limit`, `seo`, `session`, `testing`, and `time`. |
-| Suitability evaluation | `docs/evaluation.md` maps modules to common patterns found in existing projects and identifies first replacement candidates. |
-| Consumer install smoke | Packed tarball was installed into a clean temp project and imported successfully from `@q32/core`. |
-
-## Incomplete Or Externally Blocked
-
-| Requirement | Status |
-| --- | --- |
-| npm package published | Complete for `@q32/core@0.1.1`; npm reports `0.1.1` as the latest published version. |
-| npm publish step in CD | Trusted publishing is configured for `q32llc/q32-core` and `.github/workflows/release.yml`; verify on the next GitHub release. |
-| Proven replacement in existing apps | Not complete. The library is evaluated as suitable, but no existing app has been migrated to consume it yet. |
-
-## Recommended Next Proof Step
-
-Migrate one low-risk repeated slice in an existing app, such as replacing the duplicated `D1DatabaseLike` type in `relin` or `graphilize`, or replacing `ops_events` helpers in `onwardtravel`. That will validate the public API against production code and expose any ergonomics issues before broad adoption.