fix(logs): enhance error handling in log processing and export functions

- Replaced generic error messages with structured ORPCError instances for better clarity and debugging.
- Updated error handling in `getOneLogWithReconstruction` and `exportResponseByIdAndFormat` to include detailed messages and status codes.
- Improved test coverage for error mapping in the Deepcrawl SDK, ensuring accurate error type handling.

Author: lumpinif

.changeset/bright-taxis-remain.md

@@ -0,0 +1,6 @@
+---
+'deepcrawl': patch
+---
+
+fix: align worker error codes with typed SDK errors
+

apps/workers/v0/src/routers/logs/logs.processor.ts

@@ -366,7 +366,11 @@ export async function getOneLogWithReconstruction(
     .limit(1);
 
   if (result.length === 0) {
-    throw new Error('Activity log not found');
+    throw new ORPCError('NOT_FOUND', {
+      status: 404,
+      message: 'Activity log not found',
+      data: { id },
+    });
   }
 
   const log = result[0];
@@ -444,26 +448,29 @@ export async function exportResponseByIdAndFormat(
           if (readResponse.markdown) {
             return readResponse.markdown;
           }
+          const message =
+            'No markdown content available for this request. The original request did not include markdown extraction.';
           throw new ORPCError('INVALID_EXPORT_FORMAT', {
             status: 400,
-            message:
-              'No markdown content available for this request. The original request did not include markdown extraction.',
-            data: { id, path: activity.path },
+            message,
+            data: { id, path: activity.path, message },
           });
         }
         // Error response
+        const message = 'Cannot export markdown from error response';
         throw new ORPCError('INVALID_EXPORT_FORMAT', {
           status: 400,
-          message: 'Cannot export markdown from error response',
-          data: { id, path: activity.path },
+          message,
+          data: { id, path: activity.path, message },
         });
       }
 
       // Links endpoints don't have markdown
+      const message = `Markdown export is not supported for ${activity.path} endpoint`;
       throw new ORPCError('INVALID_EXPORT_FORMAT', {
         status: 400,
-        message: `Markdown export is not supported for ${activity.path} endpoint`,
-        data: { id, path: activity.path },
+        message,
+        data: { id, path: activity.path, message },
       });
     }
 
@@ -479,34 +486,39 @@ export async function exportResponseByIdAndFormat(
           if ('tree' in linksResponse && linksResponse.tree) {
             return linksResponse.tree;
           }
+          const message =
+            'No links tree available for this request. The original request did not include tree generation.';
           throw new ORPCError('INVALID_EXPORT_FORMAT', {
             status: 400,
-            message:
-              'No links tree available for this request. The original request did not include tree generation.',
-            data: { id, path: activity.path },
+            message,
+            data: { id, path: activity.path, message },
           });
         }
         // Error response
+        const message = 'Cannot export links from error response';
         throw new ORPCError('INVALID_EXPORT_FORMAT', {
           status: 400,
-          message: 'Cannot export links from error response',
-          data: { id, path: activity.path },
+          message,
+          data: { id, path: activity.path, message },
         });
       }
 
       // Read endpoints don't have links tree
+      const message = `Links export is not supported for ${activity.path} endpoint`;
       throw new ORPCError('INVALID_EXPORT_FORMAT', {
         status: 400,
-        message: `Links export is not supported for ${activity.path} endpoint`,
-        data: { id, path: activity.path },
+        message,
+        data: { id, path: activity.path, message },
       });
     }
 
-    default:
+    default: {
+      const message = `Unsupported export format: ${format}`;
       throw new ORPCError('INVALID_EXPORT_FORMAT', {
         status: 400,
-        message: `Unsupported export format: ${format}`,
-        data: { id, format },
+        message,
+        data: { id, format, message },
       });
+    }
   }
 }

packages/sdks/js-ts/src/__tests__/deepcrawl.test.ts

@@ -1,5 +1,9 @@
+import { ORPCError } from '@orpc/client';
 import { describe, expect, it } from 'vitest';
-import { DeepcrawlAuthError } from '../_types';
+import {
+  DeepcrawlAuthError,
+  DeepcrawlInvalidExportFormatError,
+} from '../_types';
 import { DeepcrawlApp } from '../deepcrawl';
 
 describe('DeepcrawlApp', () => {
@@ -117,23 +121,30 @@ describe('DeepcrawlApp', () => {
       code: string;
       status: number;
       message: string;
+      data?: unknown;
     };
 
     type FakeSafeClient = {
-      read: {
+      read?: {
         getMarkdown: () => Promise<[FakeOrpcError, null]>;
       };
+      logs?: {
+        exportResponse: () => Promise<[FakeOrpcError, null]>;
+      };
     };
 
-    type DeepcrawlAppWithSafeClient = DeepcrawlApp & {
-      safeClient: FakeSafeClient;
-    };
+    function setSafeClient(app: DeepcrawlApp, safeClient: FakeSafeClient) {
+      const appWithSafeClient = app as unknown as {
+        safeClient: FakeSafeClient;
+      };
+      appWithSafeClient.safeClient = safeClient;
+    }
 
     it('should map UNAUTHORIZED ORPC errors to DeepcrawlAuthError', async () => {
       const app = new DeepcrawlApp({ apiKey: 'test-key' });
 
       // Override the internal safe client to simulate oRPC errors without network calls.
-      (app as unknown as DeepcrawlAppWithSafeClient).safeClient = {
+      setSafeClient(app, {
         read: {
           getMarkdown: async () => [
             {
@@ -144,7 +155,7 @@ describe('DeepcrawlApp', () => {
             null,
           ],
         },
-      };
+      });
 
       try {
         await app.getMarkdown('https://example.com');
@@ -159,32 +170,45 @@ describe('DeepcrawlApp', () => {
       }
     });
 
-    it('should map legacy UNAUTHORIZED: ORPC errors to DeepcrawlAuthError', async () => {
+    it('should map INVALID_EXPORT_FORMAT ORPC errors to DeepcrawlInvalidExportFormatError', async () => {
       const app = new DeepcrawlApp({ apiKey: 'test-key' });
 
-      // Backward-compat with a previously incorrect server error code.
-      (app as unknown as DeepcrawlAppWithSafeClient).safeClient = {
-        read: {
-          getMarkdown: async () => [
-            {
-              code: 'UNAUTHORIZED:',
-              status: 401,
-              message: 'Authentication failed',
-            },
-            null,
-          ],
+      const orpcError = new ORPCError('INVALID_EXPORT_FORMAT', {
+        defined: true,
+        status: 400,
+        message: 'Invalid export format',
+        data: {
+          id: 'log-123',
+          format: 'markdown',
+          path: 'read-readUrl',
+          message: 'Cannot export markdown from error response',
         },
-      };
+      });
+
+      setSafeClient(app, {
+        logs: {
+          exportResponse: async () => [orpcError, null],
+        },
+      });
 
       try {
-        await app.getMarkdown('https://example.com');
-        throw new Error('Expected getMarkdown() to throw');
+        await app.exportResponse({ id: 'log-123', format: 'markdown' });
+        throw new Error('Expected exportResponse() to throw');
       } catch (error) {
-        expect(error).toBeInstanceOf(DeepcrawlAuthError);
-        expect((error as DeepcrawlAuthError).code).toBe('UNAUTHORIZED');
-        expect((error as DeepcrawlAuthError).status).toBe(401);
-        expect((error as DeepcrawlAuthError).message).toBe(
-          'Authentication failed',
+        expect(error).toBeInstanceOf(DeepcrawlInvalidExportFormatError);
+        expect((error as DeepcrawlInvalidExportFormatError).code).toBe(
+          'INVALID_EXPORT_FORMAT',
+        );
+        expect((error as DeepcrawlInvalidExportFormatError).status).toBe(400);
+        expect((error as DeepcrawlInvalidExportFormatError).message).toBe(
+          'Cannot export markdown from error response',
+        );
+        expect((error as DeepcrawlInvalidExportFormatError).id).toBe('log-123');
+        expect((error as DeepcrawlInvalidExportFormatError).format).toBe(
+          'markdown',
+        );
+        expect((error as DeepcrawlInvalidExportFormatError).path).toBe(
+          'read-readUrl',
         );
       }
     });

packages/sdks/js-ts/src/__tests__/types.test.ts

@@ -28,7 +28,7 @@ describe('Error Classes', () => {
       expect(error.message).toBe('Failed to read page');
       expect(error.name).toBe('DeepcrawlReadError');
       expect(error.code).toBe('READ_ERROR_RESPONSE');
-      expect(error.status).toBe(400);
+      expect(error.status).toBe(500);
       expect(error.targetUrl).toBe('https://example.com');
       expect(error.success).toBe(false);
       expect(error).toBeInstanceOf(DeepcrawlError);
@@ -49,7 +49,7 @@ describe('Error Classes', () => {
       expect(error.message).toBe('Failed to extract links');
       expect(error.name).toBe('DeepcrawlLinksError');
       expect(error.code).toBe('LINKS_ERROR_RESPONSE');
-      expect(error.status).toBe(400);
+      expect(error.status).toBe(500);
       expect(error.targetUrl).toBe('https://example.com');
       expect(error.timestamp).toBe('2024-01-01T00:00:00Z');
       expect(error).toBeInstanceOf(DeepcrawlError);

packages/sdks/js-ts/src/_types/index.ts

@@ -213,7 +213,7 @@ export abstract class DeepcrawlError<TData = unknown> extends Error {
 export class DeepcrawlReadError extends DeepcrawlError<ReadErrorResponse> {
   constructor(data: ReadErrorResponse) {
     // Pass data.error as the message for consistency with JavaScript Error patterns
-    super('READ_ERROR_RESPONSE', data.error, data, 400, true);
+    super('READ_ERROR_RESPONSE', data.error, data, 500, true);
   }
 
   get userMessage(): string {
@@ -240,7 +240,7 @@ export class DeepcrawlReadError extends DeepcrawlError<ReadErrorResponse> {
 export class DeepcrawlLinksError extends DeepcrawlError<LinksErrorResponse> {
   constructor(data: LinksErrorResponse) {
     // Pass data.error as the message for consistency with JavaScript Error patterns
-    super('LINKS_ERROR_RESPONSE', data.error, data, 400, true);
+    super('LINKS_ERROR_RESPONSE', data.error, data, 500, true);
   }
 
   get userMessage(): string {

packages/sdks/js-ts/src/deepcrawl.ts

@@ -173,7 +173,6 @@ function handleDeepcrawlError(
     // Handle infrastructure errors (rate limiting, auth, etc.)
     switch (error.code) {
       case 'UNAUTHORIZED':
-      case 'UNAUTHORIZED:':
         throw new DeepcrawlAuthError(error.message || 'Unauthorized');
       case 'BAD_REQUEST':
         throw new DeepcrawlValidationError(error.message || 'Bad request');