feat: expose user-friendly parse error for opportunity parsing

When Brokkr detects invalid document format (e.g., multiple job
opportunities in a single file), save the error message as
parseErrorUserMessage in opportunity flags and expose it via GraphQL
so the frontend can show it instead of a generic error.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: capJavert

__tests__/helpers.ts

@@ -561,6 +561,19 @@ export const createMockBrokkrTransport = ({
     });
   });
 
+export const createMockBrokkrParseGeneralErrorTransport = (
+  errorMessage: string,
+) =>
+  createRouterTransport(({ service }) => {
+    service(BrokkrService, {
+      parseOpportunity: () => {
+        return new ParseOpportunityResponse({
+          errors: [new ParseError({ field: 'general', message: errorMessage })],
+        });
+      },
+    });
+  });
+
 export const createMockNjordTransport = () => {
   return createRouterTransport(({ service }) => {
     const accounts: Record<

__tests__/workers/opportunity/parseOpportunity.ts

@@ -2,6 +2,7 @@ import {
   expectSuccessfulTypedBackground,
   saveFixtures,
   createMockBrokkrTransport,
+  createMockBrokkrParseGeneralErrorTransport,
   createGarmrMock,
 } from '../../helpers';
 import { parseOpportunityWorker as worker } from '../../../src/workers/opportunity/parseOpportunity';
@@ -285,6 +286,7 @@ describe('parseOpportunity worker', () => {
 
     expect(opportunity!.state).toBe(OpportunityState.ERROR);
     expect(opportunity!.flags?.parseError).toContain('Brokkr parsing failed');
+    expect(opportunity!.flags?.parseErrorUserMessage).toBeUndefined();
   });
 
   it('should skip if state is not PARSING', async () => {
@@ -609,6 +611,60 @@ describe('parseOpportunity worker', () => {
     expect(recruiter).toBeNull();
   });
 
+  it('should set ERROR state with parseError when Brokkr returns general error', async () => {
+    jest.restoreAllMocks();
+
+    const transport = createMockBrokkrParseGeneralErrorTransport(
+      'The document is a list of multiple job opportunities, not a detailed description of a single one',
+    );
+
+    jest.spyOn(brokkrCommon, 'getBrokkrClient').mockImplementation(
+      (): ServiceClient<typeof BrokkrService> => ({
+        instance: createClient(BrokkrService, transport),
+        garmr: createGarmrMock(),
+      }),
+    );
+
+    mockStorageDownload.mockResolvedValue([Buffer.from('mock-pdf-content')]);
+    mockStorageExists.mockResolvedValue([true]);
+
+    await con.getRepository(OpportunityJob).save({
+      id: testOpportunityId,
+      type: OpportunityType.JOB,
+      state: OpportunityState.PARSING,
+      title: 'Processing...',
+      tldr: '',
+      content: new OpportunityContent({}),
+      flags: {
+        batchSize: 100,
+        file: {
+          blobName: testBlobName,
+          bucketName: RESUME_BUCKET_NAME,
+          mimeType: 'application/pdf',
+          extension: 'pdf',
+          userId: testUserId,
+          trackingId: 'anon1',
+        },
+      },
+    });
+
+    await expectSuccessfulTypedBackground<'api.v1.opportunity-parse'>(worker, {
+      opportunityId: testOpportunityId,
+    });
+
+    const opportunity = await con.getRepository(OpportunityJob).findOne({
+      where: { id: testOpportunityId },
+    });
+
+    expect(opportunity!.state).toBe(OpportunityState.ERROR);
+    expect(opportunity!.flags?.parseError).toBe(
+      'The document is a list of multiple job opportunities, not a detailed description of a single one',
+    );
+    expect(opportunity!.flags?.parseErrorUserMessage).toBe(
+      'The document is a list of multiple job opportunities, not a detailed description of a single one',
+    );
+  });
+
   it('should assign Europe as continent when no country specified', async () => {
     // Create a custom mock with just continent: 'Europe' (no country)
     const transport = createMockBrokkrTransport({

src/common/opportunity/parse.ts

@@ -12,6 +12,7 @@ import {
 
 import { getBufferFromStream } from '../utils';
 import { ValidationError } from 'apollo-server-errors';
+import { ParseOpportunityError } from '../../errors';
 import { garmScraperService } from '../scraper';
 import { acceptedOpportunityFileTypes } from '../../types';
 import { getBrokkrClient } from '../brokkr';
@@ -210,6 +211,12 @@ export async function parseOpportunityWithBrokkr({
 
   logger.info(result, 'brokkrParseOpportunityResponse');
 
+  const generalError = result.errors?.find((e) => e.field === 'general');
+
+  if (generalError) {
+    throw new ParseOpportunityError(generalError.message);
+  }
+
   // Sanitize Brokkr response - filter out invalid locations
   const sanitizedOpportunity = {
     ...result.opportunity,

src/entity/opportunities/Opportunity.ts

@@ -44,6 +44,7 @@ export type OpportunityFlags = Partial<{
     trackingId?: string;
   } | null;
   parseError: string | null;
+  parseErrorUserMessage: string | null;
   isTrial: boolean;
   public_draft: boolean;
   sourceUrl: string | null;
@@ -52,7 +53,7 @@ export type OpportunityFlags = Partial<{
 
 export type OpportunityFlagsPublic = Pick<
   OpportunityFlags,
-  'batchSize' | 'plan' | 'showSlack' | 'showFeedback'
+  'batchSize' | 'plan' | 'showSlack' | 'showFeedback' | 'parseErrorUserMessage'
 >;
 
 @Entity()

src/errors.ts

@@ -228,6 +228,13 @@ export class PaymentRequiredError extends ApolloError {
   }
 }
 
+export class ParseOpportunityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ParseOpportunityError';
+  }
+}
+
 export class ServiceError extends Error {
   data?: JsonValue;
   statusCode?: number;

src/graphorm/index.ts

@@ -75,7 +75,10 @@ import { extractHandleFromUrl } from '../common/schema/socials';
 import type { GCSBlob } from '../common/schema/userCandidate';
 import { QuestionType } from '../entity/questions/types';
 import { snotraClient } from '../integrations/snotra';
-import type { OpportunityFlagsPublic } from '../entity/opportunities/Opportunity';
+import type {
+  OpportunityFlags,
+  OpportunityFlagsPublic,
+} from '../entity/opportunities/Opportunity';
 import { isNullOrUndefined } from '../common/object';
 
 export enum LocationVerificationStatus {
@@ -1903,12 +1906,13 @@ const obj = new GraphORM({
       },
       flags: {
         jsonType: true,
-        transform: (value: OpportunityFlagsPublic): OpportunityFlagsPublic => {
+        transform: (value: OpportunityFlags): OpportunityFlagsPublic => {
           return {
             batchSize: value?.batchSize ?? opportunityMatchBatchSize,
             plan: value?.plan,
             showSlack: value?.showSlack ?? false,
             showFeedback: value?.showFeedback ?? false,
+            parseErrorUserMessage: value?.parseErrorUserMessage,
           };
         },
       },

src/schema/opportunity.ts

@@ -309,6 +309,7 @@ export const typeDefs = /* GraphQL */ `
     plan: String
     showSlack: Boolean
     showFeedback: Boolean
+    parseErrorUserMessage: String
   }
 
   """

src/workers/opportunity/parseOpportunity.ts

@@ -7,6 +7,7 @@ import {
   createOpportunityFromParsedData,
 } from '../../common/opportunity/parse';
 import { updateFlagsStatement } from '../../common';
+import { ParseOpportunityError } from '../../errors';
 import { deleteBlobFromGCS } from '../../common/googleCloud';
 import z from 'zod';
 import { performance } from 'perf_hooks';
@@ -167,6 +168,9 @@ export const parseOpportunityWorker: TypedWorker<'api.v1.opportunity-parse'> = {
       const errorMessage =
         error instanceof Error ? error.message : 'Unknown error';
 
+      const parseError =
+        error instanceof z.ZodError ? z.prettifyError(error) : errorMessage;
+
       await con
         .getRepository(OpportunityJob)
         .createQueryBuilder()
@@ -178,10 +182,9 @@ export const parseOpportunityWorker: TypedWorker<'api.v1.opportunity-parse'> = {
         .setParameter(
           'flagsJson',
           JSON.stringify({
-            parseError:
-              error instanceof z.ZodError
-                ? z.prettifyError(error)
-                : errorMessage,
+            parseError,
+            parseErrorUserMessage:
+              error instanceof ParseOpportunityError ? errorMessage : undefined,
           }),
         )
         .execute();