@moifort/stack 0.0.0-stage → 0.1.0

package/templates/backend/server/domain/user/infrastructure/graphql/mutations.ts

@@ -0,0 +1,40 @@
+import { builder } from '~/domain/shared/graphql/builder'
+import * as UserCommand from '~/domain/user/command'
+import * as UserQuery from '~/domain/user/query'
+import * as UserUseCase from '~/domain/user/use-case'
+import { CompleteOnboardingInput } from './inputs'
+import { MeType } from './types'
+
+builder.mutationField('completeOnboarding', (t) =>
+  t.field({
+    type: MeType,
+    description:
+      'Finish onboarding: save the profile. Returns the updated `Me`, with ' +
+      '`onboardingCompleted` now true. Reachable again afterwards, so a user can change ' +
+      'the name they are addressed by.',
+    args: {
+      input: t.arg({
+        type: CompleteOnboardingInput,
+        required: true,
+        description: 'The first name to persist.',
+      }),
+    },
+    resolve: async (_root, { input }, { userId }) => {
+      await UserCommand.completeOnboarding(userId, input.firstName)
+      return UserQuery.me(userId)
+    },
+  }),
+)
+
+builder.mutationField('deleteAccount', (t) =>
+  t.boolean({
+    description:
+      'Permanently delete the signed-in account and all of its data. Irreversible. ' +
+      'Required by App Store guideline 5.1.1(v). Does NOT cancel an active App Store ' +
+      'subscription: Apple owns that lifecycle. Always returns `true`.',
+    resolve: async (_root, _args, { userId }) => {
+      await UserUseCase.deleteAccount(userId)
+      return true
+    },
+  }),
+)

package/templates/backend/server/domain/user/infrastructure/graphql/queries.ts

@@ -0,0 +1,13 @@
+import { builder } from '~/domain/shared/graphql/builder'
+import * as UserQuery from '~/domain/user/query'
+import { MeType } from './types'
+
+builder.queryField('me', (t) =>
+  t.field({
+    type: MeType,
+    description:
+      'The signed-in user, resolved from the auth token. Always returns a `Me`, even ' +
+      'before onboarding: a fresh account comes back with only `userId` set.',
+    resolve: (_root, _args, { userId }) => UserQuery.me(userId),
+  }),
+)

package/templates/backend/server/domain/user/infrastructure/graphql/types.ts

@@ -0,0 +1,35 @@
+import { builder } from '~/domain/shared/graphql/builder'
+import type { MeView } from '~/domain/user/types'
+
+export const MeType = builder.objectRef<MeView>('Me').implement({
+  description:
+    'The signed-in user: their identity and onboarding state.\n\n' +
+    'Always resolvable from the auth token, so `userId` is always present. Every other ' +
+    'field is null until the onboarding completes, which lets the app route a fresh ' +
+    'account into onboarding.',
+  fields: (t) => ({
+    userId: t.expose('userId', {
+      type: 'UserId',
+      description: 'The Firebase Auth user id, also the id of the profile document.',
+    }),
+    firstName: t.expose('firstName', {
+      type: 'PersonName',
+      nullable: true,
+      description: "The user's first name, set during onboarding; null before it is done.",
+    }),
+    onboardingCompletedAt: t.expose('onboardingCompletedAt', {
+      type: 'DateTime',
+      nullable: true,
+      description: 'When onboarding finished, or null if it never has.',
+    }),
+    onboardingCompleted: t.boolean({
+      description: 'The flag the app routes on: true once onboarding is done.',
+      resolve: (me) => me.onboardingCompletedAt != null,
+    }),
+    isAdmin: t.expose('admin', {
+      type: 'Boolean',
+      description:
+        'Whether this account may open the in-app admin screen. Set by hand on the profile document.',
+    }),
+  }),
+})

package/templates/backend/server/domain/user/infrastructure/repository.ts

@@ -0,0 +1,59 @@
+import type { UserId } from '~/domain/shared/types'
+import type { UserProfile } from '~/domain/user/types'
+import { db } from '~/system/firebase'
+import { deleteAuthUser } from '~/system/identity'
+import { evictFromRequestCache, memoizedPerRequest } from '~/system/request-cache'
+import { genericDataConverter } from '~/utils/firestore'
+
+const profiles = () => db().collection('users').withConverter(genericDataConverter<UserProfile>())
+
+const cacheKey = (userId: UserId) => `user:profile:${userId}`
+
+/** A user's profile, at most one: the document id IS the userId. Memoized: the
+ *  auth gate reads it on every launch, so it must cost a single read per request. */
+export const findProfile = (userId: UserId): Promise<UserProfile | null> =>
+  memoizedPerRequest(cacheKey(userId), async () => {
+    const doc = await profiles().doc(userId).get()
+    return doc.data() ?? null
+  })
+
+/** The names behind a list of ids, in one getAll rather than a lookup per row. */
+export const findProfiles = async (userIds: readonly UserId[]): Promise<UserProfile[]> => {
+  if (userIds.length === 0) return []
+  const refs = [...new Set(userIds)].map((userId) => profiles().doc(userId))
+  const docs = await db().getAll(...refs)
+  return docs.flatMap((doc) => {
+    const profile = doc.data() as UserProfile | undefined
+    return profile ? [profile] : []
+  })
+}
+
+/** Every profile, for a scheduled pass: a scan, read once per run. */
+export const findAllProfiles = async (): Promise<UserProfile[]> =>
+  (await profiles().get()).docs.map((doc) => doc.data())
+
+/** How many accounts have a profile: one billed aggregate, never a scan. */
+export const countProfiles = async (): Promise<number> =>
+  (await profiles().count().get()).data().count
+
+export const countProfilesSince = async (since: Date): Promise<number> =>
+  (await profiles().where('onboardingCompletedAt', '>=', since).count().get()).data().count
+
+export const saveProfile = async (profile: UserProfile): Promise<UserProfile> => {
+  await profiles().doc(profile.userId).set(profile)
+  // The onboarding read the profile to know whether it was the first time, then
+  // answers with what it just wrote: the absence it saw must not be read back.
+  evictFromRequestCache(cacheKey(profile.userId))
+  return profile
+}
+
+/** Idempotent: an already-absent profile is a no-op, so a retried deletion never errors. */
+export const removeProfile = async (userId: UserId): Promise<void> => {
+  await profiles().doc(userId).delete()
+  evictFromRequestCache(cacheKey(userId))
+}
+
+/** The one place the auth provider is touched: external access stays in the storage layer. */
+export const removeAuthUser = async (userId: UserId): Promise<void> => {
+  await deleteAuthUser(userId)
+}

package/templates/backend/server/domain/user/mutations.feat.test.ts

@@ -0,0 +1,42 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test'
+import { graphql } from 'graphql'
+import type { UserId } from '~/domain/shared/types'
+import { fakeDb, resetFakeFirestore } from '~/test/fake-firestore'
+
+mock.module('~/system/firebase', () => ({ db: fakeDb }))
+mock.module('~/system/identity', () => ({ deleteAuthUser: async () => {} }))
+
+const { schema } = await import('~/domain/shared/graphql/schema')
+
+const run = (source: string, userId = 'u1') =>
+  graphql({ schema, source, contextValue: { event: undefined, userId: userId as UserId } })
+
+beforeEach(() => {
+  resetFakeFirestore()
+})
+
+describe('the user API contract', () => {
+  test('me answers the id alone before onboarding, then the profile after it', async () => {
+    const before = await run('{ me { userId firstName onboardingCompleted } }')
+    expect(before.errors).toBeUndefined()
+    expect(before.data?.me).toEqual({ userId: 'u1', firstName: null, onboardingCompleted: false })
+
+    const done = await run(
+      'mutation { completeOnboarding(input: { firstName: "Ada" }) { firstName onboardingCompleted } }',
+    )
+    expect(done.data?.completeOnboarding).toEqual({ firstName: 'Ada', onboardingCompleted: true })
+  })
+
+  test('an invalid name is a BAD_USER_INPUT, not a 500', async () => {
+    const result = await run('mutation { completeOnboarding(input: { firstName: "" }) { userId } }')
+    expect(result.errors?.[0]?.extensions?.code).toBe('BAD_USER_INPUT')
+  })
+
+  test('deleteAccount answers true and leaves no profile', async () => {
+    await run('mutation { completeOnboarding(input: { firstName: "Ada" }) { userId } }')
+    const deleted = await run('mutation { deleteAccount }')
+    expect(deleted.data?.deleteAccount).toBe(true)
+    const after = await run('{ me { onboardingCompleted } }')
+    expect(after.data?.me).toEqual({ onboardingCompleted: false })
+  })
+})

package/templates/backend/server/domain/user/query.int.test.ts

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test'
+import type { PersonName, UserId } from '~/domain/shared/types'
+import type { UserProfile } from '~/domain/user/types'
+import { fakeDb, resetFakeFirestore } from '~/test/fake-firestore'
+
+mock.module('~/system/firebase', () => ({ db: fakeDb }))
+
+const UserQuery = await import('~/domain/user/query')
+const UserCommand = await import('~/domain/user/command')
+
+const user = (id: string) => id as UserId
+
+let fake = resetFakeFirestore()
+
+beforeEach(() => {
+  fake = resetFakeFirestore()
+})
+
+describe('UserQuery.me', () => {
+  test('returns nulls when no profile exists, so the app routes to onboarding', async () => {
+    const me = await UserQuery.me(user('u1'))
+    expect(me.userId).toBe(user('u1'))
+    expect(me.firstName).toBeUndefined()
+    expect(me.onboardingCompletedAt).toBeUndefined()
+    expect(fake.docReads).toBe(1)
+    expect(fake.queryReads).toBe(0)
+  })
+
+  test('returns the first name and the timestamp once a profile is saved', async () => {
+    const profile: UserProfile = {
+      userId: user('u1'),
+      firstName: 'Ada' as PersonName,
+      onboardingCompletedAt: new Date('2026-01-01'),
+    }
+    fake.seed('users', 'u1', profile)
+    const me = await UserQuery.me(user('u1'))
+    expect(me.firstName as string).toBe('Ada')
+    expect(me.onboardingCompletedAt).toEqual(new Date('2026-01-01'))
+  })
+})
+
+describe('UserCommand.completeOnboarding', () => {
+  test('writes the profile and the same request reads it back', async () => {
+    await UserCommand.completeOnboarding(user('u1'), 'Ada' as PersonName)
+    const me = await UserQuery.me(user('u1'))
+    expect(me.firstName as string).toBe('Ada')
+    expect(me.onboardingCompletedAt).toBeInstanceOf(Date)
+  })
+})

package/templates/backend/server/domain/user/query.ts

@@ -0,0 +1,34 @@
+import { Count } from '~/domain/shared/primitives'
+import type { Count as CountType, UserId } from '~/domain/shared/types'
+import * as repository from '~/domain/user/infrastructure/repository'
+import type { MeView } from '~/domain/user/types'
+
+/** The signed-in user's identity and onboarding state. Nulls when no profile
+ *  exists yet: the app routes to onboarding on a missing timestamp. */
+export const me = async (userId: UserId): Promise<MeView> => {
+  const profile = await repository.findProfile(userId)
+  return {
+    userId,
+    firstName: profile?.firstName,
+    onboardingCompletedAt: profile?.onboardingCompletedAt,
+    admin: profile?.admin === true,
+  }
+}
+
+/** The first names behind a set of ids, for a list that names people. */
+export const namesOf = async (userIds: readonly UserId[]): Promise<Map<UserId, string>> =>
+  new Map(
+    (await repository.findProfiles(userIds)).map((profile) => [
+      profile.userId,
+      String(profile.firstName),
+    ]),
+  )
+
+/** Every account, for the scheduled passes that look after each user. */
+export const allIds = async (): Promise<UserId[]> =>
+  (await repository.findAllProfiles()).map((profile) => profile.userId)
+
+export const total = async (): Promise<CountType> => Count(await repository.countProfiles())
+
+export const joinedSince = async (since: Date): Promise<CountType> =>
+  Count(await repository.countProfilesSince(since))

package/templates/backend/server/domain/user/types.ts

@@ -0,0 +1,20 @@
+import type { PersonName, UserId } from '~/domain/shared/types'
+
+/** A user's profile, written once onboarding completes. The document id IS the
+ *  userId, so a user has at most one profile. `admin` opens the in-app admin
+ *  screen; it is only ever set by hand in the Firestore console, never by code. */
+export type UserProfile = {
+  userId: UserId
+  firstName: PersonName
+  onboardingCompletedAt: Date
+  admin?: boolean
+}
+
+/** The signed-in user's identity and onboarding state. Every field but the id is
+ *  optional so the app can route to onboarding when no profile exists yet. */
+export type MeView = {
+  userId: UserId
+  firstName?: PersonName
+  onboardingCompletedAt?: Date
+  admin: boolean
+}

package/templates/backend/server/domain/user/use-case.ts

@@ -0,0 +1,18 @@
+import type { UserId } from '~/domain/shared/types'
+import * as UserCommand from '~/domain/user/command'
+
+/** Delete the account and every trace of it. Each step reaches a domain through
+ *  its public command surface, never a repository. Idempotent, so a retry after a
+ *  partial failure is safe, and the order matters: every per-user collection
+ *  first, in parallel; then the profile; then the Firebase Auth user LAST. If an
+ *  earlier step fails the user is still signed in and can retry, whereas deleting
+ *  auth first would strand the data with nobody able to reach it.
+ *
+ *  Add each new domain's `deleteAllForUser` to the parallel block as it ships. */
+export const deleteAccount = async (userId: UserId) => {
+  await Promise.all([
+    // <domain>Command.deleteAllForUser(userId),
+  ])
+  await UserCommand.deleteProfile(userId)
+  await UserCommand.deleteAuthAccount(userId)
+}

package/templates/backend/server/middleware/auth.ts

@@ -0,0 +1,54 @@
+import { getAuth } from 'firebase-admin/auth'
+import { UserId } from '~/domain/shared/primitives'
+// Side-effect import: ensures firebase-admin is initialized before verifyIdToken.
+import '~/system/firebase'
+import { config } from '~/system/config'
+
+export default defineEventHandler(async (event) => {
+  const path = event.path ?? ''
+
+  // Admin endpoints: a separate token, never a Firebase user. Cloud Scheduler
+  // and the Deploy workflow call them.
+  if (path.startsWith('/admin/')) {
+    const auth = getHeader(event, 'authorization')
+    const adminToken = config().adminToken
+    if (!adminToken || auth !== `Bearer ${adminToken}`)
+      throw createError({ statusCode: 401, statusMessage: 'Unauthorized' })
+    return
+  }
+
+  // Public app configuration: read by the update gate, possibly signed out.
+  if (path === '/app-config' || path.startsWith('/app-config?')) return
+
+  // Everything else (incl. /graphql): require a valid Firebase ID token.
+  const auth = getHeader(event, 'authorization')
+
+  // Dev-only: let a browser reach Apollo Sandbox without a Firebase token.
+  // import.meta.dev is compile-time, so this block is tree-shaken out of prod builds.
+  if (import.meta.dev && !auth) {
+    const devUserId = config().devUserId
+    if (!devUserId)
+      throw createError({
+        statusCode: 401,
+        statusMessage: 'Dev auth bypass needs NITRO_DEV_USER_ID in .env (a Firebase UID)',
+      })
+    event.context.userId = UserId(devUserId)
+    return
+  }
+
+  const token = auth?.startsWith('Bearer ') ? auth.slice(7) : null
+  if (!token) throw createError({ statusCode: 401, statusMessage: 'Missing bearer token' })
+
+  try {
+    const decoded = await getAuth().verifyIdToken(token)
+    event.context.userId = UserId(decoded.uid)
+  } catch {
+    throw createError({ statusCode: 401, statusMessage: 'Invalid token' })
+  }
+})
+
+declare module 'h3' {
+  interface H3EventContext {
+    userId?: ReturnType<typeof UserId>
+  }
+}

package/templates/backend/server/plugins/00-sentry.ts

@@ -0,0 +1,74 @@
+import * as Sentry from '@sentry/node'
+import { config } from '~/system/config/index'
+import { flushReports } from '~/system/logger'
+
+export default defineNitroPlugin((nitroApp) => {
+  // Mirrors the iOS `#if DEBUG` gate in the app: only the deployed
+  // build reports, so a local run never pollutes the production project.
+  // import.meta.dev is compile-time, so the guard costs nothing in the prod bundle
+  // and everything below it is tree-shaken out of dev builds.
+  if (import.meta.dev) return
+
+  const { sentryDsn, sentryRelease } = config()
+  if (!sentryDsn) return
+
+  Sentry.init({
+    dsn: sentryDsn,
+    environment: 'production',
+    release: sentryRelease,
+    // Only performance traces are sampled — errors are always sent in full, and
+    // each one carries its trace id, so an app error and the resolver that threw
+    // still line up in the same trace at a tenth of the transaction volume.
+    tracesSampleRate: 0.1,
+  })
+
+  const originalHandler = nitroApp.h3App.handler
+  nitroApp.h3App.handler = ((event) =>
+    // The app sends its own trace headers, so the request continues the trace the
+    // tap on screen started instead of opening a fresh one. That is what puts the
+    // iOS error and the backend error it caused side by side in Sentry.
+    Sentry.continueTrace(
+      {
+        sentryTrace: getHeader(event, 'sentry-trace'),
+        baggage: getHeader(event, 'baggage'),
+      },
+      () =>
+        Sentry.startSpan(
+          { name: `${event.method} ${event.path}`, op: 'http.server' },
+          async (span) => {
+            try {
+              const result = await originalHandler(event)
+              const route = event.context.matchedRoute?.path
+              if (route) span.updateName(`${event.method} ${route}`)
+              return result
+            } finally {
+              // What the loggers reported while serving — a model call that
+              // failed and was recovered from — leaves before the response
+              // does, since Cloud Functions throttles the CPU right after.
+              await flushReports()
+            }
+          },
+        ),
+    )) as typeof originalHandler
+
+  nitroApp.hooks.hook('error', async (error, { event }) => {
+    const statusCode = (error as { statusCode?: number }).statusCode
+    if (statusCode && statusCode >= 400 && statusCode < 500) return
+
+    // The uid rides on the event rather than a global scope: the function serves
+    // up to 80 requests at once, so a shared scope would credit an error to
+    // whoever happened to be in flight. It turns "an error" into "how many
+    // accounts are affected", and points straight at the documents to inspect.
+    const userId = event?.context.userId
+    Sentry.captureException(error, {
+      user: userId ? { id: userId } : undefined,
+      extra: {
+        path: event?.path,
+        method: event?.method,
+      },
+    })
+    // Cloud Functions gen2 throttles the CPU once the response is sent —
+    // flush now or the event may never leave the instance.
+    await Sentry.flush(2000)
+  })
+})

package/templates/backend/server/plugins/01-request-log.ts

@@ -0,0 +1,28 @@
+import { createLogger } from '~/system/logger'
+
+const logger = createLogger('request')
+
+/**
+ * Logs one line per request with its duration, in dev only.
+ *
+ * The end-to-end gate had the app stuck on a loading state with no way to tell
+ * whether the request never left, never came back, or came back with an error:
+ * `nitro dev` prints nothing per request, so the server log showed a clean boot
+ * either way. `import.meta.dev` is compile-time, so none of this is in the
+ * deployed bundle.
+ */
+export default defineNitroPlugin((nitroApp) => {
+  if (!import.meta.dev) return
+
+  const started = new WeakMap<object, number>()
+
+  nitroApp.hooks.hook('request', (event) => {
+    started.set(event, Date.now())
+  })
+
+  nitroApp.hooks.hook('afterResponse', (event) => {
+    const at = started.get(event)
+    const elapsed = at ? `${Date.now() - at}ms` : '?'
+    logger.info(`${event.method} ${event.path} → ${event.node.res.statusCode} in ${elapsed}`)
+  })
+})

package/templates/backend/server/plugins/02-graphql.ts

@@ -0,0 +1,69 @@
+import { ApolloServer, type ApolloServerPlugin } from '@apollo/server'
+import { ApolloServerPluginLandingPageLocalDefault } from '@apollo/server/plugin/landingPage/default'
+import * as Sentry from '@sentry/node'
+import { GraphQLError } from 'graphql'
+import type { GraphQLContext } from '~/domain/shared/graphql/builder'
+import { schema } from '~/domain/shared/graphql/schema'
+import { createLogger } from '~/system/logger'
+import { startReadMeter } from '~/system/read-meter'
+import { setApollo } from '~/utils/apollo'
+
+const logger = createLogger('graphql')
+
+// Apollo answers resolver exceptions with HTTP 200 + errors[], so Nitro's
+// `error` hook never sees them. Capture unexpected ones (anything that is not
+// a deliberate GraphQLError thrown by a resolver or scalar) here instead.
+const sentryErrorCapture = {
+  requestDidStart: async () => ({
+    didEncounterErrors: async ({ errors }: { errors: readonly GraphQLError[] }) => {
+      const unexpected = errors
+        .map((error) => error.originalError)
+        .filter((cause): cause is Error => cause !== undefined && !(cause instanceof GraphQLError))
+      if (unexpected.length === 0) return
+      for (const cause of unexpected) Sentry.captureException(cause)
+      // Cloud Functions gen2 throttles the CPU once the response is sent —
+      // flush now or the event may never leave the instance.
+      await Sentry.flush(2000)
+    },
+  }),
+}
+
+// One line per operation, to find the slow screens: which operation, how long
+// it took, and the Firestore reads it made. Info level, so never sent to Sentry;
+// in a built bundle the context keys land under `jsonPayload`, where Cloud
+// Logging can sum them per operation.
+const operationMetrics: ApolloServerPlugin<GraphQLContext> = {
+  requestDidStart: async ({ contextValue }) => {
+    const started = performance.now()
+    const reads = startReadMeter(contextValue.event.context)
+    return {
+      willSendResponse: async ({ operationName, operation, errors }) => {
+        logger.info('operation served', {
+          operation: operationName ?? 'anonymous',
+          type: operation?.operation,
+          durationMs: Math.round(performance.now() - started),
+          ...reads,
+          reads: reads.docReads + reads.queryDocs,
+          errors: errors?.length ?? 0,
+        })
+      },
+    }
+  },
+}
+
+export default defineNitroPlugin(async () => {
+  const plugins: ApolloServerPlugin<GraphQLContext>[] = [sentryErrorCapture, operationMetrics]
+  // Dev-only: serve the embedded Apollo Sandbox on GET /graphql (Accept: text/html).
+  if (import.meta.dev) plugins.push(ApolloServerPluginLandingPageLocalDefault({ embed: true }))
+  const apollo = new ApolloServer<GraphQLContext>({
+    schema,
+    introspection: true,
+    plugins,
+    // Apollo is externalized in the bundle, so it would otherwise decide this from the
+    // runtime NODE_ENV, which nothing in infra/function.tf sets. Pin it to the
+    // compile-time flag so prod never returns stack traces to a client.
+    includeStacktraceInErrorResponses: import.meta.dev,
+  })
+  await apollo.start()
+  setApollo(apollo)
+})

package/templates/backend/server/plugins/03-boot-time.ts

@@ -0,0 +1,21 @@
+import { createLogger } from '~/system/logger'
+
+const logger = createLogger('boot')
+
+/**
+ * Logs, once per instance, how long the process took to load the bundle.
+ *
+ * Cloud Run's `container/startup_latencies` measured about 6 s per cold start
+ * on 2026-10-15, but it lumps Google's share (scheduling the instance, starting
+ * Node and the Functions Framework) with ours (importing the bundle). Plugins run
+ * once every module is loaded, so the process's uptime here is our share; the
+ * metric minus this figure is Google's. Scale-to-zero is deliberate, so this is
+ * for watching the trend, not for keeping instances warm.
+ */
+export default defineNitroPlugin(() => {
+  if (import.meta.dev) return
+  logger.info('server ready', {
+    uptimeMs: Math.round(process.uptime() * 1000),
+    revision: process.env.K_REVISION,
+  })
+})

package/templates/backend/server/routes/admin/migrate.post.ts

@@ -0,0 +1,9 @@
+import { migrations } from '~/system/migration/migrations'
+import { runMigrations } from '~/system/migration/runner'
+
+export default defineEventHandler(async (event) => {
+  const result = await runMigrations(migrations)
+  // A failed migration must fail the CI deploy step (curl -fsS gates on the status).
+  if (result.outcome === 'failed') setResponseStatus(event, 500)
+  return result
+})

package/templates/backend/server/routes/app-config.get.ts

@@ -0,0 +1,15 @@
+import { APP_STORE_URL, MINIMUM_SUPPORTED_IOS_BUILD } from '~/system/app-support'
+
+/**
+ * Public client configuration, read by the iOS app at launch (before any
+ * sign-in, so this route is whitelisted in the auth middleware). Drives the
+ * force-update gate: builds below `minimumSupportedIOSBuild` are blocked.
+ */
+export default defineEventHandler((event) => {
+  // A cached floor would defeat the foreground re-check on already-open apps.
+  setResponseHeader(event, 'cache-control', 'no-store')
+  return {
+    minimumSupportedIOSBuild: MINIMUM_SUPPORTED_IOS_BUILD,
+    appStoreUrl: APP_STORE_URL,
+  }
+})

package/templates/backend/server/routes/graphql.ts

@@ -0,0 +1,52 @@
+import { type ApolloServer, HeaderMap } from '@apollo/server'
+import type { UserId } from '~/domain/shared/types'
+
+export default defineEventHandler(async (event) => {
+  const apollo = useApollo()
+  const userId = (event.context as { userId?: UserId }).userId
+  if (!userId) throw createError({ statusCode: 401, statusMessage: 'Missing user context' })
+  // No loader set: a book carries its series name and volume number, so grouping
+  // a library reads no catalogue document. The request cache in the repositories
+  // covers the rest.
+  const context = async () => ({ event, userId })
+
+  const headerMap = new HeaderMap()
+  for (const [key, value] of Object.entries(getHeaders(event))) {
+    if (value !== undefined) headerMap.set(key, value)
+  }
+
+  if (event.method === 'GET') {
+    const query = getQuery(event)
+    const search = new URLSearchParams()
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined) search.set(key, String(value))
+    }
+    const response = await apollo.executeHTTPGraphQLRequest({
+      httpGraphQLRequest: {
+        method: 'GET',
+        headers: headerMap,
+        body: undefined,
+        search: search.toString(),
+      },
+      context,
+    })
+    return sendApolloResponse(event, response)
+  }
+
+  const body = await readBody(event)
+  const response = await apollo.executeHTTPGraphQLRequest({
+    httpGraphQLRequest: { method: 'POST', headers: headerMap, body, search: '' },
+    context,
+  })
+  return sendApolloResponse(event, response)
+})
+
+function sendApolloResponse(
+  event: Parameters<typeof setResponseStatus>[0],
+  response: Awaited<ReturnType<ApolloServer['executeHTTPGraphQLRequest']>>,
+) {
+  setResponseStatus(event, response.status || 200)
+  for (const [key, value] of response.headers) setResponseHeader(event, key, value)
+  if (response.body.kind === 'complete') return response.body.string
+  throw createError({ statusCode: 500, statusMessage: 'Chunked responses not supported' })
+}