feat(newsletters): add superuser audience targeting

Author: Bill Leoutsakos

apps/sim/app/account/settings/[section]/page.tsx

@@ -11,7 +11,7 @@ import {
 } from '@/components/settings/navigation'
 import { getSession } from '@/lib/auth'
 import { isBillingEnabled } from '@/lib/core/config/env-flags'
-import { isPlatformAdmin } from '@/lib/permissions/super-user'
+import { isPlatformAdmin, verifyEffectiveSuperUser } from '@/lib/permissions/super-user'
 
 interface AccountSettingsSectionPageProps {
   params: Promise<{ section: string }>
@@ -50,6 +50,10 @@ export default async function AccountSettingsSectionPage({
     const isSuperUser = await isPlatformAdmin(session.user.id)
     if (!isSuperUser) notFound()
   }
+  if (parsed === 'newsletters') {
+    const { effectiveSuperUser } = await verifyEffectiveSuperUser(session.user.id)
+    if (!effectiveSuperUser) notFound()
+  }
 
   /**
    * Sections read URL query params via nuqs (which uses `useSearchParams`

apps/sim/app/account/settings/layout.tsx

@@ -1,15 +1,19 @@
 import { redirect } from 'next/navigation'
 import { StandaloneSettingsShell } from '@/components/settings/standalone-settings-shell'
 import { getSession } from '@/lib/auth'
-import { isPlatformAdmin } from '@/lib/permissions/super-user'
+import { verifyEffectiveSuperUser } from '@/lib/permissions/super-user'
 
 export default async function AccountSettingsLayout({ children }: { children: React.ReactNode }) {
   const session = await getSession()
   if (!session?.user) redirect('/login')
-  const isSuperUser = await isPlatformAdmin(session.user.id)
+  const { effectiveSuperUser, isSuperUser } = await verifyEffectiveSuperUser(session.user.id)
 
   return (
-    <StandaloneSettingsShell plane='account' isSuperUser={isSuperUser}>
+    <StandaloneSettingsShell
+      plane='account'
+      isSuperUser={isSuperUser}
+      isEffectiveSuperUser={effectiveSuperUser}
+    >
       {children}
     </StandaloneSettingsShell>
   )

apps/sim/app/api/superuser/newsletters/runs/[id]/export.csv/route.ts

@@ -0,0 +1,68 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { exportNewsletterRunCsvContract } from '@/lib/api/contracts/newsletters'
+import { parseRequest } from '@/lib/api/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { validateNewsletterSuperuser } from '@/lib/newsletters/auth'
+import { createNewsletterCsvExport } from '@/lib/newsletters/runs'
+
+const logger = createLogger('NewsletterCsvExportAPI')
+
+export const GET = withRouteHandler(
+  async (request: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    try {
+      const auth = await validateNewsletterSuperuser()
+      if (!auth.success) return auth.response
+
+      const parsed = await parseRequest(exportNewsletterRunCsvContract, request, context)
+      if (!parsed.success) return parsed.response
+
+      const { filename, lines } = await createNewsletterCsvExport(parsed.data.params.id)
+      const iterator = lines[Symbol.asyncIterator]()
+      const encoder = new TextEncoder()
+      const stream = new ReadableStream<Uint8Array>({
+        async pull(controller) {
+          try {
+            const next = await iterator.next()
+            if (next.done) {
+              controller.close()
+              return
+            }
+            controller.enqueue(encoder.encode(`${next.value}\n`))
+          } catch (error) {
+            logger.error('Failed while streaming newsletter CSV', {
+              error: getErrorMessage(error),
+            })
+            controller.error(error)
+          }
+        },
+        async cancel() {
+          await iterator.return?.(undefined)
+        },
+      })
+
+      return new NextResponse(stream, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/csv; charset=utf-8',
+          'Content-Disposition': `attachment; filename="${filename}"`,
+          'Cache-Control': 'no-store',
+        },
+      })
+    } catch (error) {
+      const message = getErrorMessage(error)
+      if (/not found/i.test(message)) {
+        return NextResponse.json({ error: 'Newsletter run not found' }, { status: 404 })
+      }
+      if (/Finalize/i.test(message)) {
+        return NextResponse.json({ error: message }, { status: 400 })
+      }
+      if (/RESEND_API_KEY|Resend .*list|Resend request/i.test(message)) {
+        return NextResponse.json({ error: message }, { status: 503 })
+      }
+      logger.error('Failed to export newsletter CSV', { error: message })
+      return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/superuser/newsletters/runs/[id]/finalize/route.ts

@@ -0,0 +1,45 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { finalizeNewsletterRunContract } from '@/lib/api/contracts/newsletters'
+import { parseRequest } from '@/lib/api/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { validateNewsletterSuperuser } from '@/lib/newsletters/auth'
+import { finalizeNewsletterRun } from '@/lib/newsletters/runs'
+
+const logger = createLogger('NewsletterFinalizeAPI')
+
+export const POST = withRouteHandler(
+  async (request: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    try {
+      const auth = await validateNewsletterSuperuser()
+      if (!auth.success) return auth.response
+
+      const parsed = await parseRequest(finalizeNewsletterRunContract, request, context)
+      if (!parsed.success) return parsed.response
+
+      const { run, oversized } = await finalizeNewsletterRun(parsed.data.params.id)
+      if (oversized) {
+        logger.warn('Newsletter audience exceeded the finalization safety limit', {
+          userId: auth.userId,
+          runId: run.id,
+          totalMatched: run.counts.totalMatched,
+        })
+      }
+      return NextResponse.json({ run })
+    } catch (error) {
+      const message = getErrorMessage(error)
+      if (/not found/i.test(message)) {
+        return NextResponse.json({ error: 'Newsletter run not found' }, { status: 404 })
+      }
+      if (/already in progress/i.test(message)) {
+        return NextResponse.json({ error: message }, { status: 409 })
+      }
+      if (/RESEND_API_KEY|Resend .*list|Resend request/i.test(message)) {
+        return NextResponse.json({ error: message }, { status: 503 })
+      }
+      logger.error('Failed to finalize newsletter run', { error: message })
+      return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/superuser/newsletters/runs/[id]/job/route.ts

@@ -0,0 +1,50 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { getNewsletterRunJobContract } from '@/lib/api/contracts/newsletters'
+import { parseRequest } from '@/lib/api/server'
+import { getJobQueue } from '@/lib/core/async-jobs'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { validateNewsletterSuperuser } from '@/lib/newsletters/auth'
+import { requireNewsletterRun } from '@/lib/newsletters/runs'
+
+const logger = createLogger('NewsletterJobAPI')
+
+export const GET = withRouteHandler(
+  async (request: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    try {
+      const auth = await validateNewsletterSuperuser()
+      if (!auth.success) return auth.response
+
+      const parsed = await parseRequest(getNewsletterRunJobContract, request, context)
+      if (!parsed.success) return parsed.response
+
+      const run = await requireNewsletterRun(parsed.data.params.id)
+      if (!run.resendSyncJobId) return NextResponse.json({ job: null })
+
+      const queue = await getJobQueue()
+      const job = await queue.getJob(run.resendSyncJobId)
+      return NextResponse.json({
+        job: job
+          ? {
+              id: job.id,
+              status: job.status,
+              attempts: job.attempts,
+              maxAttempts: job.maxAttempts,
+              error: job.error ?? null,
+              createdAt: job.createdAt.toISOString(),
+              startedAt: job.startedAt?.toISOString() ?? null,
+              completedAt: job.completedAt?.toISOString() ?? null,
+            }
+          : null,
+      })
+    } catch (error) {
+      const message = getErrorMessage(error)
+      if (/not found/i.test(message)) {
+        return NextResponse.json({ error: 'Newsletter run not found' }, { status: 404 })
+      }
+      logger.error('Failed to get newsletter job', { error: message })
+      return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/superuser/newsletters/runs/[id]/push-resend/route.ts

@@ -0,0 +1,48 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { pushNewsletterRunToResendContract } from '@/lib/api/contracts/newsletters'
+import { parseRequest } from '@/lib/api/server'
+import { isAsyncJobEnqueueError } from '@/lib/core/async-jobs'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { validateNewsletterSuperuser } from '@/lib/newsletters/auth'
+import { enqueueNewsletterResendSync } from '@/lib/newsletters/push-resend'
+
+const logger = createLogger('NewsletterPushResendAPI')
+
+export const POST = withRouteHandler(
+  async (request: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    try {
+      const auth = await validateNewsletterSuperuser()
+      if (!auth.success) return auth.response
+
+      const parsed = await parseRequest(pushNewsletterRunToResendContract, request, context)
+      if (!parsed.success) return parsed.response
+
+      const { run, jobId } = await enqueueNewsletterResendSync(parsed.data.params.id, auth.userId)
+      return NextResponse.json({ run, jobId })
+    } catch (error) {
+      const message = getErrorMessage(error)
+      if (/not found/i.test(message)) {
+        return NextResponse.json({ error: 'Newsletter run not found' }, { status: 404 })
+      }
+      if (/finalize|RESEND_API_KEY/i.test(message)) {
+        return NextResponse.json({ error: message }, { status: 400 })
+      }
+      if (isAsyncJobEnqueueError(error)) {
+        return NextResponse.json(
+          { error: 'Newsletter sync enqueue is uncertain; retry to resume the same attempt' },
+          { status: 503 }
+        )
+      }
+      if (/tracking persistence failed/i.test(message)) {
+        return NextResponse.json(
+          { error: 'Newsletter sync was accepted but job tracking is not yet available; retry' },
+          { status: 503 }
+        )
+      }
+      logger.error('Failed to enqueue newsletter Resend push', { error: message })
+      return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/superuser/newsletters/runs/[id]/route.ts

@@ -0,0 +1,29 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { getNewsletterRunContract } from '@/lib/api/contracts/newsletters'
+import { parseRequest } from '@/lib/api/server'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { validateNewsletterSuperuser } from '@/lib/newsletters/auth'
+import { getNewsletterRun } from '@/lib/newsletters/runs'
+
+const logger = createLogger('NewsletterRunAPI')
+
+export const GET = withRouteHandler(
+  async (request: NextRequest, context: { params: Promise<{ id: string }> }) => {
+    try {
+      const auth = await validateNewsletterSuperuser()
+      if (!auth.success) return auth.response
+
+      const parsed = await parseRequest(getNewsletterRunContract, request, context)
+      if (!parsed.success) return parsed.response
+
+      const run = await getNewsletterRun(parsed.data.params.id)
+      if (!run) return NextResponse.json({ error: 'Newsletter run not found' }, { status: 404 })
+      return NextResponse.json({ run })
+    } catch (error) {
+      logger.error('Failed to get newsletter run', { error: getErrorMessage(error) })
+      return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
+    }
+  }
+)

apps/sim/app/api/superuser/newsletters/runs/route.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @vitest-environment node
+ */
+import { createMockRequest } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockCreateNewsletterRun, mockListNewsletterRuns, mockValidateNewsletterSuperuser } =
+  vi.hoisted(() => ({
+    mockCreateNewsletterRun: vi.fn(),
+    mockListNewsletterRuns: vi.fn(),
+    mockValidateNewsletterSuperuser: vi.fn(),
+  }))
+
+vi.mock('@/lib/newsletters/auth', () => ({
+  validateNewsletterSuperuser: mockValidateNewsletterSuperuser,
+}))
+
+vi.mock('@/lib/newsletters/runs', () => ({
+  createNewsletterRun: mockCreateNewsletterRun,
+  listNewsletterRuns: mockListNewsletterRuns,
+}))
+
+import { NewsletterTargetingPromptError } from '@/lib/newsletters/targeting'
+import { POST } from '@/app/api/superuser/newsletters/runs/route'
+
+function createRequest(prompt = 'Everyone') {
+  return createMockRequest('POST', {
+    name: 'July launch',
+    prompt,
+  })
+}
+
+describe('newsletter runs POST', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockValidateNewsletterSuperuser.mockResolvedValue({
+      success: true,
+      userId: 'user-1',
+    })
+  })
+
+  it('returns the superuser authorization failure before creating a run', async () => {
+    mockValidateNewsletterSuperuser.mockResolvedValue({
+      success: false,
+      response: new Response(JSON.stringify({ error: 'Forbidden' }), { status: 403 }),
+    })
+
+    const response = await POST(createRequest())
+
+    expect(response.status).toBe(403)
+    expect(mockCreateNewsletterRun).not.toHaveBeenCalled()
+  })
+
+  it('creates a preview run for an authorized superuser', async () => {
+    const run = {
+      id: 'run-1',
+      name: 'July launch',
+      prompt: 'Everyone',
+    }
+    mockCreateNewsletterRun.mockResolvedValue(run)
+
+    const response = await POST(createRequest())
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ run })
+    expect(mockCreateNewsletterRun).toHaveBeenCalledWith({
+      name: 'July launch',
+      prompt: 'Everyone',
+      createdById: 'user-1',
+    })
+  })
+
+  it('returns a client error for an ambiguous targeting prompt', async () => {
+    mockCreateNewsletterRun.mockRejectedValue(new NewsletterTargetingPromptError())
+
+    const response = await POST(createRequest('Users interested in productivity'))
+
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toEqual({
+      error:
+        'Targeting prompt is ambiguous. Use everyone, an Instagram integration or chat target, or a recent activity window.',
+    })
+  })
+})