Improve Sentry error capture for Actions

Author: webstackdev

src/actions/newsletter/__tests__/action.spec.ts

@@ -300,7 +300,82 @@ describe('newsletter.subscribe.handler', () => {
 
     expect(throwActionError).toHaveBeenCalledWith(
       expect.any(Error),
-      { route: '/_actions/newsletter/subscribe', operation: 'subscribe' }
+      expect.objectContaining({
+        route: '/_actions/newsletter/subscribe',
+        operation: 'subscribe',
+        extra: expect.objectContaining({
+          stage: 'buildRequestFingerprint',
+          source: 'newsletter_form',
+          input: expect.objectContaining({
+            consentGiven: true,
+            emailDomain: 'example.com',
+            hasDataSubjectId: false,
+            hasFirstName: false,
+            subjectIdSource: 'pending',
+          }),
+        }),
+      })
+    )
+  })
+
+  it('logs handled action errors with subscribe stage context', async () => {
+    vi.resetModules()
+
+    const { createPendingSubscription } = await import('@actions/newsletter/domain')
+    vi.mocked(createPendingSubscription).mockRejectedValueOnce(
+      new (await import('@actions/utils/errors')).ActionsFunctionError('db unavailable', {
+        status: 500,
+      })
+    )
+
+    const { newsletter } = await import('../action')
+    const { handleActionsFunctionError } = await import('@actions/utils/errors')
+
+    const context = {
+      request: new Request('https://example.com/_actions/newsletter/subscribe', {
+        method: 'POST',
+        headers: { 'user-agent': 'ua-6' },
+      }),
+      cookies: {} as unknown,
+      clientAddress: '203.0.113.16',
+    }
+
+    await expect(
+      getMockedHandler<NewsletterSubscribeInput, NewsletterSubscribeOutput>(newsletter.subscribe)(
+        { email: 'test@example.com', consentGiven: true },
+        context
+      )
+    ).rejects.toMatchObject({
+      name: 'ActionsFunctionError',
+      status: 500,
+      message: 'db unavailable',
+    })
+
+    expect(handleActionsFunctionError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: 'ActionsFunctionError',
+        status: 500,
+      }),
+      expect.objectContaining({
+        route: '/_actions/newsletter/subscribe',
+        operation: 'subscribe',
+        extra: expect.objectContaining({
+          stage: 'createPendingSubscription',
+          fingerprint: 'fingerprint-1',
+          source: 'newsletter_form',
+          input: expect.objectContaining({
+            emailDomain: 'example.com',
+            emailLength: 16,
+            consentGiven: true,
+            subjectIdSource: 'generated',
+          }),
+          request: expect.objectContaining({
+            hasClientAddress: true,
+            hasUserAgent: true,
+            rateLimitIdentifier: 'newsletter:consent:fingerprint-1',
+          }),
+        }),
+      })
     )
   })
 })

src/actions/newsletter/action.ts

@@ -26,6 +26,61 @@ const confirmSchema = z.object({
   token: z.string().min(1),
 })
 
+type NewsletterSubscribeStage =
+  | 'buildRequestFingerprint'
+  | 'checkRateLimit'
+  | 'validateEmail'
+  | 'validateConsent'
+  | 'resolveDataSubjectId'
+  | 'createConsentRecord'
+  | 'createPendingSubscription'
+  | 'sendConfirmationEmail'
+
+const getEmailDomain = (email: string): string | undefined => {
+  const normalizedEmail = email.trim().toLowerCase()
+  const atIndex = normalizedEmail.lastIndexOf('@')
+
+  if (atIndex === -1 || atIndex === normalizedEmail.length - 1) {
+    return undefined
+  }
+
+  return normalizedEmail.slice(atIndex + 1)
+}
+
+const buildSubscribeErrorExtra = (options: {
+  body: z.infer<typeof subscribeSchema>
+  fingerprint?: string
+  consentFunctional: boolean
+  stage: NewsletterSubscribeStage
+  userAgent: string
+  clientAddress?: string
+  rateLimitIdentifier?: string
+  subjectIdSource: 'generated' | 'provided' | 'pending'
+}): Record<string, unknown> => {
+  return {
+    stage: options.stage,
+    source: 'newsletter_form',
+    consentFunctional: options.consentFunctional,
+    fingerprint: options.fingerprint,
+    request: {
+      hasClientAddress:
+        typeof options.clientAddress === 'string' && options.clientAddress !== 'unknown',
+      hasUserAgent: options.userAgent !== 'unknown',
+      rateLimitIdentifier: options.rateLimitIdentifier,
+    },
+    input: {
+      emailDomain: getEmailDomain(options.body.email),
+      emailLength: options.body.email.trim().length,
+      consentGiven: Boolean(options.body.consentGiven),
+      hasFirstName:
+        typeof options.body.firstName === 'string' && options.body.firstName.trim().length > 0,
+      hasDataSubjectId:
+        typeof options.body.DataSubjectId === 'string' && options.body.DataSubjectId.length > 0,
+      subjectIdSource: options.subjectIdSource,
+    },
+  }
+}
+
 export const newsletter = {
   subscribe: defineAction({
     accept: 'json',
@@ -35,16 +90,26 @@ export const newsletter = {
       context
     ): Promise<{ success: true; message: string; requiresConfirmation: true }> => {
       const route = '/_actions/newsletter/subscribe'
+      let stage: NewsletterSubscribeStage = 'buildRequestFingerprint'
+      let fingerprint: string | undefined
+      let consentFunctional = false
+      let rateLimitIdentifier: string | undefined
+      let subjectIdSource: 'generated' | 'provided' | 'pending' = 'pending'
+      const userAgent = context.request.headers.get('user-agent') || 'unknown'
 
       try {
-        const { fingerprint } = buildRequestFingerprint({
+        const requestFingerprint = buildRequestFingerprint({
           route,
           request: context.request,
           cookies: context.cookies,
           clientAddress: context.clientAddress,
         })
 
-        const rateLimitIdentifier = createRateLimitIdentifier('newsletter:consent', fingerprint)
+        fingerprint = requestFingerprint.fingerprint
+        consentFunctional = requestFingerprint.consentFunctional
+
+        stage = 'checkRateLimit'
+        rateLimitIdentifier = createRateLimitIdentifier('newsletter:consent', fingerprint)
         const { success, reset } = await checkRateLimit(rateLimiters.consent, rateLimitIdentifier)
 
         if (!success) {
@@ -53,24 +118,29 @@ export const newsletter = {
           throw new ActionsFunctionError(`Try again in ${retryAfterSeconds}s`, { status: 429 })
         }
 
+        stage = 'validateEmail'
         const validatedEmail = validateEmail(body.email)
 
+        stage = 'validateConsent'
         if (!body.consentGiven) {
           throw new ActionsFunctionError(
             'You must consent to receive marketing emails to subscribe.',
             { status: 400 }
           )
         }
 
-        const userAgent = context.request.headers.get('user-agent') || 'unknown'
-
+        stage = 'resolveDataSubjectId'
         let subjectId = body.DataSubjectId
         if (!subjectId) {
           subjectId = uuidv4()
+          subjectIdSource = 'generated'
         } else if (!uuidValidate(subjectId)) {
           throw new ActionsFunctionError('Invalid DataSubjectId format', { status: 400 })
+        } else {
+          subjectIdSource = 'provided'
         }
 
+        stage = 'createConsentRecord'
         await createConsentRecord({
           dataSubjectId: subjectId,
           email: validatedEmail,
@@ -86,6 +156,7 @@ export const newsletter = {
           verified: false,
         })
 
+        stage = 'createPendingSubscription'
         const token = await createPendingSubscription({
           email: validatedEmail,
           ...(body.firstName && { firstName: body.firstName }),
@@ -96,6 +167,7 @@ export const newsletter = {
           source: 'newsletter_form',
         })
 
+        stage = 'sendConfirmationEmail'
         await sendConfirmationEmail(validatedEmail, token, body.firstName)
 
         return {
@@ -104,10 +176,27 @@ export const newsletter = {
           requiresConfirmation: true,
         }
       } catch (error) {
+        const errorContext = {
+          route,
+          operation: 'subscribe',
+          extra: buildSubscribeErrorExtra({
+            body,
+            fingerprint,
+            consentFunctional,
+            stage,
+            userAgent,
+            clientAddress: context.clientAddress,
+            rateLimitIdentifier,
+            subjectIdSource,
+          }),
+        } as const
+
         if (error instanceof ActionsFunctionError) {
+          handleActionsFunctionError(error, errorContext)
           throw error
         }
-        throwActionError(error, { route, operation: 'subscribe' })
+
+        throwActionError(error, errorContext)
       }
     },
   }),

src/actions/utils/errors/__tests__/actionsFunctionHandler.spec.ts

@@ -1,4 +1,16 @@
-import { describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const captureExceptionMock = vi.fn()
+const setTagsMock = vi.fn()
+const setTagMock = vi.fn()
+const setExtrasMock = vi.fn()
+const withScopeMock = vi.fn((callback: (_scope: unknown) => void) => {
+  callback({
+    setTags: setTagsMock,
+    setTag: setTagMock,
+    setExtras: setExtrasMock,
+  })
+})
 
 vi.mock('astro:actions', () => {
   class ActionError extends Error {
@@ -26,10 +38,18 @@ vi.mock('@actions/utils/sentry', () => ({
 }))
 
 vi.mock('@sentry/astro', () => ({
-  captureException: () => undefined,
-  withScope: (_fn: (_scope: unknown) => void) => undefined,
+  captureException: captureExceptionMock,
+  withScope: withScopeMock,
 }))
 
+beforeEach(() => {
+  captureExceptionMock.mockReset()
+  setTagsMock.mockReset()
+  setTagMock.mockReset()
+  setExtrasMock.mockReset()
+  withScopeMock.mockClear()
+})
+
 describe('actionsFunctionHandler', () => {
   it('converts server errors into ActionError with fallback message', async () => {
     const { ActionsFunctionError } = await import('../ActionsFunctionError')
@@ -64,4 +84,71 @@ describe('actionsFunctionHandler', () => {
     expect(normalized.status).toBe(500)
     expect(normalized.message).toBe('boom')
   })
+
+  it('includes merged details in structured logs', async () => {
+    const { ActionsFunctionError } = await import('../ActionsFunctionError')
+    const { formatActionsErrorLogEntry } = await import('../actionsFunctionHandler')
+
+    const error = new ActionsFunctionError('DB exploded', {
+      status: 500,
+      route: 'actions:test',
+      appCode: 'DB_WRITE_FAILED',
+      details: { stage: 'createPendingSubscription' },
+    })
+
+    const entry = formatActionsErrorLogEntry(error, {
+      route: 'actions:test',
+      operation: 'subscribe',
+      extra: { fingerprint: 'fingerprint-1' },
+    })
+
+    expect(entry.appCode).toBe('DB_WRITE_FAILED')
+    expect(entry.details).toEqual({
+      stage: 'createPendingSubscription',
+      fingerprint: 'fingerprint-1',
+    })
+  })
+
+  it('forwards merged details and appCode to sentry in production', async () => {
+    vi.resetModules()
+
+    vi.doMock('@actions/utils/environment/environmentActions', () => ({
+      isDev: () => false,
+      isProd: () => true,
+      isTest: () => false,
+      isUnitTest: () => false,
+    }))
+
+    const { ActionsFunctionError } = await import('../ActionsFunctionError')
+    const { handleActionsFunctionError } = await import('../actionsFunctionHandler')
+
+    const error = new ActionsFunctionError('DB exploded', {
+      status: 500,
+      route: 'actions:test',
+      appCode: 'DB_WRITE_FAILED',
+      details: { stage: 'persist' },
+    })
+
+    const normalized = handleActionsFunctionError(error, {
+      route: 'actions:test',
+      operation: 'subscribe',
+      extra: { fingerprint: 'fingerprint-1' },
+    })
+
+    expect(normalized).toBeInstanceOf(ActionsFunctionError)
+    expect(setTagsMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        route: 'actions:test',
+        status: '500',
+        retryable: 'true',
+        appCode: 'DB_WRITE_FAILED',
+        operation: 'subscribe',
+      })
+    )
+    expect(setExtrasMock).toHaveBeenCalledWith({
+      stage: 'persist',
+      fingerprint: 'fingerprint-1',
+    })
+    expect(captureExceptionMock).toHaveBeenCalledWith(expect.any(ActionsFunctionError))
+  })
 })