Release: v0.2.0

.env.example

@@ -71,6 +71,16 @@ CFP_JWT_SIGNING_KEY=change-me-to-a-random-string-at-least-32-chars
 # PEM-encoded certificate matching SAML_PRIVATE_KEY.
 # SAML_CERTIFICATE=-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----
 
+# Stable IdP entity ID — also the <Issuer> on every assertion. Slack stores
+# this at setup, so it must NOT change when CFP_SITE_HOST flips at cutover.
+# Leave unset unless registering a separate IdP with a different workspace.
+# See specs/api/saml.md#idp-identity-and-hosts.
+# SAML_ENTITY_ID=https://codeforphilly.org/api/saml/slack/metadata
+
+# Slack workspace host. Drives the ACS URL, NameID NameQualifier, and the
+# /chat + /launch redirects. Never used for our own entity ID or endpoints.
+# SLACK_TEAM_HOST=codeforphilly.slack.com
+
 # ---------------------------------------------------------------------------
 # Static SPA serving (production only)
 # ---------------------------------------------------------------------------
@@ -92,14 +102,19 @@ CFP_JWT_SIGNING_KEY=change-me-to-a-random-string-at-least-32-chars
 # CFP_SITE_HOST=codeforphilly.org
 
 # ---------------------------------------------------------------------------
-# Outbound notifications (Resend)
+# Outbound notifications (Postmark)
 # ---------------------------------------------------------------------------
 
-# Resend API key for the help-wanted email notifier. When unset, the
-# notifier falls back to a no-op LoggingNotifier so dev + tests work
-# without an account. See plans/notifier-email.md.
-# RESEND_API_KEY=re_…
+# Postmark server token for the email notifier (help-wanted, welcome,
+# password-reset). When unset, the notifier falls back to a no-op
+# LoggingNotifier so dev + tests work without an account. See
+# plans/postmark-notifier.md and docs/operations/secrets.md.
+# POSTMARK_SERVER_TOKEN=…
+
+# Postmark message stream to send on. Defaults to `outbound`, the
+# transactional stream every Postmark server ships with.
+# POSTMARK_MESSAGE_STREAM=outbound
 
 # From-address for outbound notifications. RFC 5322 form.
-# Only used when RESEND_API_KEY is set.
+# Only used when POSTMARK_SERVER_TOKEN is set.
 # CFP_NOTIFICATION_FROM="Code for Philly <notifications@codeforphilly.org>"

apps/api/package.json

@@ -35,9 +35,9 @@
     "bcryptjs": "^3.0.3",
     "better-sqlite3": "^12.10.0",
     "fastify": "^5.8.5",
-    "gitsheets": "^1.4.1",
+    "gitsheets": "^2.2.0",
     "jose": "^6.2.3",
-    "resend": "^6.12.4",
+    "postmark": "^5.1.0",
     "samlify": "^2.13.0",
     "sharp": "^0.34.5",
     "uuidv7": "^1.2.1",

apps/api/scripts/cutover-mailout.ts

@@ -6,22 +6,26 @@
  * them to sign in and claim their account. Run manually at T+90 per
  * specs/behaviors/account-migration.md#cutover-window-policy.
  *
- * --dry-run prints the would-be send list and exits — no Resend calls, no
+ * --dry-run prints the would-be send list and exits — no Postmark calls, no
  * disk writes. The CI test exercises only --dry-run.
  *
  * Usage:
  *   npm run -w apps/api script:cutover-mailout -- --dry-run
  *   npm run -w apps/api script:cutover-mailout -- --send --from=hello@codeforphilly.org
  *
  * Env:
- *   RESEND_API_KEY    — required for actual sends (otherwise --send refuses)
+ *   POSTMARK_SERVER_TOKEN   — required for actual sends (otherwise --send refuses)
+ *   POSTMARK_MESSAGE_STREAM — optional; defaults to `outbound`
  *   CFP_PUBLIC_URL    — base URL used in the email body (defaults to
  *                       https://codeforphilly.org)
  *   CFP_DATA_REPO_PATH + STORAGE_BACKEND + bucket envs — same shape as the API
  */
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
+import { ServerClient } from 'postmark';
+
+import { PostmarkTransport } from '../src/notify/postmark-transport.js';
 import { openPublicStore, type PublicStore } from '../src/store/public.js';
 import {
   FilesystemPrivateStore,
@@ -195,7 +199,7 @@ export async function runMailout(opts: MailoutOptions): Promise<MailoutReport> {
 }
 
 // ---------------------------------------------------------------------------
-// Env wiring + Resend send
+// Env wiring + Postmark send
 // ---------------------------------------------------------------------------
 
 function requireEnv(name: string): string {
@@ -220,33 +224,19 @@ function buildPrivateStore(): PrivateStore {
   });
 }
 
-/** Resend HTTP send. Fetch-based to avoid adding a new dep at this stage. */
-async function resendSend(input: {
-  to: string;
-  from: string;
-  subject: string;
-  html: string;
-  text: string;
-}): Promise<void> {
-  const apiKey = requireEnv('RESEND_API_KEY');
-  const res = await fetch('https://api.resend.com/emails', {
-    method: 'POST',
-    headers: {
-      'authorization': `Bearer ${apiKey}`,
-      'content-type': 'application/json',
-    },
-    body: JSON.stringify({
-      from: input.from,
-      to: input.to,
-      subject: input.subject,
-      html: input.html,
-      text: input.text,
-    }),
+/**
+ * Postmark send via the same transport the API's notifier uses. The SDK
+ * throws on any non-2xx, which runMailout() records per-recipient in
+ * `failed` rather than aborting the run.
+ */
+function buildPostmarkSend(): NonNullable<MailoutOptions['send']> {
+  const transport = new PostmarkTransport({
+    client: new ServerClient(requireEnv('POSTMARK_SERVER_TOKEN')),
+    messageStream: process.env['POSTMARK_MESSAGE_STREAM'] || undefined,
   });
-  if (!res.ok) {
-    const body = await res.text();
-    throw new Error(`Resend ${res.status}: ${body.slice(0, 200)}`);
-  }
+  return async (input) => {
+    await transport.send(input);
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -299,7 +289,7 @@ async function main(): Promise<void> {
     mode: args.dryRun ? 'dry-run' : 'send',
     from: args.from,
     publicUrl: args.publicUrl ?? process.env['CFP_PUBLIC_URL'],
-    send: args.send ? resendSend : undefined,
+    send: args.send ? buildPostmarkSend() : undefined,
   });
 
   process.stderr.write(

apps/api/scripts/import-laddr/importer.ts

@@ -92,7 +92,7 @@ import {
   type TranslateCtx,
   type Warnings,
 } from './translators.js';
-import { BlobObject } from 'hologit';
+import type { BlobHandle } from 'gitsheets';
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -187,7 +187,7 @@ export async function importLaddrFromJson(opts: ImportOptions): Promise<ImportRe
   // -------------------------------------------------------------------------
   let store: PublicStore | null = null;
   // Gitsheets Repository — needed to write attachment blobs via
-  // BlobObject.write into the underlying git object DB.
+  // repo.writeBlob into the underlying git object DB.
   let publicRepo: Awaited<ReturnType<typeof openPublicStore>>['repo'] | null = null;
   let existingIds: ExistingIds;
 
@@ -500,7 +500,6 @@ export async function importLaddrFromJson(opts: ImportOptions): Promise<ImportRe
       if (publicRepo === null) {
         throw new Error('[import-laddr] internal: publicRepo not opened');
       }
-      const hologit = publicRepo.hologitRepo;
 
       log(`[import] clear + upsert tags (${tags.length})`);
       await tx.tags.clear();
@@ -513,8 +512,8 @@ export async function importLaddrFromJson(opts: ImportOptions): Promise<ImportRe
         if (avatar) {
           // Mirror POST /api/people/:slug/avatar: store original + 128 thumb
           // as attachments and point avatarKey at the conventional path.
-          const originalBlob = await BlobObject.write(hologit, avatar.original as unknown as string);
-          const thumbnailBlob = await BlobObject.write(hologit, avatar.thumbnail as unknown as string);
+          const originalBlob = await publicRepo.writeBlob(avatar.original);
+          const thumbnailBlob = await publicRepo.writeBlob(avatar.thumbnail);
           await tx.people.setAttachments(p, {
             'avatar.jpg': originalBlob,
             'avatar-128.jpg': thumbnailBlob,
@@ -580,16 +579,10 @@ export async function importLaddrFromJson(opts: ImportOptions): Promise<ImportRe
       for (const { record } of blogTranslations) {
         const artifacts = mediaArtifactsBySlug.get(record.slug) ?? [];
         if (artifacts.length > 0) {
-          const blobs: Record<string, BlobObject> = {};
+          const blobs: Record<string, BlobHandle> = {};
           for (const a of artifacts) {
-            // BlobObject.write hashes the buffer into the git object DB.
-            // Same `as unknown as string` cast as the avatar route — the
-            // declared signature is too narrow; the underlying
-            // git-client `$putBlob` accepts Buffer at runtime.
-            blobs[a.filename] = await BlobObject.write(
-              hologit,
-              a.bytes as unknown as string,
-            );
+            // repo.writeBlob hashes the Buffer into the git object DB.
+            blobs[a.filename] = await publicRepo.writeBlob(a.bytes);
           }
           await tx['blog-posts'].setAttachments(record, blobs);
         }

apps/api/src/env.ts

@@ -6,6 +6,12 @@
  */
 import { z } from 'zod';
 
+/**
+ * Default SAML IdP entity ID. Stable across hosts — see the SAML_ENTITY_ID
+ * field below and specs/api/saml.md#idp-identity-and-hosts.
+ */
+export const SAML_ENTITY_ID_DEFAULT = 'https://codeforphilly.org/api/saml/slack/metadata';
+
 export const EnvSchema = z.object({
   /** TCP port the Fastify server listens on. */
   PORT: z.coerce.number().default(3001),
@@ -49,8 +55,17 @@ export const EnvSchema = z.object({
   /** SAML IdP certificate (PEM) for the Slack SAML integration. */
   SAML_CERTIFICATE: z.string().optional(),
   /**
-   * Slack workspace host. Used as the SAML `NameQualifier` per
-   * specs/api/saml.md and shared with the `/chat` redirect handler.
+   * SAML IdP entity ID — the metadata `entityID` and the `<Issuer>` on every
+   * assertion. A stable logical identifier Slack stores at setup time, so it
+   * deliberately does NOT follow CFP_SITE_HOST: the pre-cutover
+   * `next.codeforphilly.org` deploy and the post-cutover `codeforphilly.org`
+   * deploy present the same issuer. Per specs/api/saml.md#idp-identity-and-hosts.
+   */
+  SAML_ENTITY_ID: z.url().default(SAML_ENTITY_ID_DEFAULT),
+  /**
+   * Slack workspace host. Used for the SAML ACS URL and `NameQualifier` per
+   * specs/api/saml.md and shared with the `/chat` redirect handler. Never
+   * used for our own IdP entity ID or endpoint URLs.
    */
   SLACK_TEAM_HOST: z.string().default('codeforphilly.slack.com'),
   /**
@@ -64,19 +79,27 @@ export const EnvSchema = z.object({
    * `next-v2.codeforphilly.org` in sandbox). Used by the server-side
    * markdown renderer to distinguish internal from external links — anchors
    * with a host different from this one get `target="_blank" rel="noopener
-   * nofollow"`. Per specs/behaviors/markdown-rendering.md.
+   * nofollow"`. Per specs/behaviors/markdown-rendering.md. Also the host the
+   * SAML IdP metadata advertises for its SSO endpoint Locations (per
+   * specs/api/saml.md#idp-identity-and-hosts).
    */
   CFP_SITE_HOST: z.string().default('codeforphilly.org'),
   /**
-   * Resend API key for the email notifier. When unset, the services plugin
-   * falls back to LoggingNotifier so dev + test runs don't need a real key.
-   * See plans/notifier-email.md.
+   * Postmark server token for the email notifier. When unset, the services
+   * plugin falls back to LoggingNotifier so dev + test runs don't need a
+   * real token. See plans/postmark-notifier.md.
+   */
+  POSTMARK_SERVER_TOKEN: z.string().optional(),
+  /**
+   * Postmark message stream outbound mail is sent on. `outbound` is the
+   * transactional default stream every Postmark server ships with. Only
+   * relevant when POSTMARK_SERVER_TOKEN is set.
    */
-  RESEND_API_KEY: z.string().optional(),
+  POSTMARK_MESSAGE_STREAM: z.string().default('outbound'),
   /**
    * From-address for outbound notifications. RFC 5322 form
    * (e.g. `"Code for Philly <notifications@codeforphilly.org>"`). Only
-   * relevant when RESEND_API_KEY is set.
+   * relevant when POSTMARK_SERVER_TOKEN is set.
    */
   CFP_NOTIFICATION_FROM: z
     .string()
@@ -115,10 +138,12 @@ export const envJsonSchema = {
     CFP_JWT_SIGNING_KEY: { type: 'string', minLength: 1 },
     SAML_PRIVATE_KEY: { type: 'string' },
     SAML_CERTIFICATE: { type: 'string' },
+    SAML_ENTITY_ID: { type: 'string', default: SAML_ENTITY_ID_DEFAULT },
     SLACK_TEAM_HOST: { type: 'string', default: 'codeforphilly.slack.com' },
     CFP_WEB_DIST_PATH: { type: 'string' },
     CFP_SITE_HOST: { type: 'string', default: 'codeforphilly.org' },
-    RESEND_API_KEY: { type: 'string' },
+    POSTMARK_SERVER_TOKEN: { type: 'string' },
+    POSTMARK_MESSAGE_STREAM: { type: 'string', default: 'outbound' },
     CFP_NOTIFICATION_FROM: {
       type: 'string',
       default: 'Code for Philly <notifications@codeforphilly.org>',