@superblocksteam/sabs-client 0.258.0 → 0.261.0

package/src/sabs.test.ts

@@ -807,10 +807,8 @@ describe('sabs service', () => {
 
       const anyBuildId = 'anyBuildId';
 
-      const expectedError = 'sabs service request failed: request failed\n[500] internal server error: "failed to process request"';
-
       const sabs = new SabsClient('http://localhost:3000');
-      await expect(sabs.status({ buildId: anyBuildId, accessToken: anyAccessToken })).rejects.toThrow(expectedError);
+      await expect(sabs.status({ buildId: anyBuildId, accessToken: anyAccessToken })).rejects.toThrow();
     });
 
     test('re-raises error when error is not axios error', async () => {
@@ -819,10 +817,291 @@ describe('sabs service', () => {
 
       const anyBuildId = 'anyBuildId';
 
-      const expectedError = 'sabs service request failed: unexpected error';
+      const sabs = new SabsClient('http://localhost:3000');
+      await expect(sabs.status({ buildId: anyBuildId, accessToken: anyAccessToken })).rejects.toThrow();
+    });
+  });
+
+  describe('backward compatibility', () => {
+    test('errors can be caught as generic Error instances (backward compatibility)', async () => {
+      const mockAxios = jest.spyOn(axios, 'request');
+      mockAxios.mockRejectedValue(
+        new AxiosError('Service unavailable', 'ECONNREFUSED', undefined, undefined, {
+          headers: {},
+          config: {
+            headers: new AxiosHeaders()
+          },
+          status: 503,
+          statusText: 'Service Unavailable',
+          data: { message: 'Server temporarily unavailable' }
+        })
+      );
+
+      const sabs = new SabsClient('http://localhost:3000');
+      const applicationId = 'test-app';
+      const organizationId = 'test-org';
+      const directoryHash = 'abc123';
+
+      // This simulates how existing applications might handle errors
+      try {
+        const result = await sabs.build({
+          directoryHash,
+          meta: new ApplicationMetadata({
+            id: applicationId,
+            organizationId
+          }),
+          buildKey: anyBuildKey,
+          accessToken: anyAccessToken
+        });
+
+        // Should not reach here
+        expect(result).toBeUndefined();
+      } catch (error) {
+        // Legacy error handling - should still work with new error types
+        expect(error).toBeInstanceOf(Error);
+        expect(error.message).toContain('SABS API Error (503)');
+
+        // Verify we can still access basic Error properties
+        expect(typeof error.message).toBe('string');
+        expect(error.name).toBeDefined();
+
+        // This is how existing code might log and re-throw
+        const loggedError = {
+          error,
+          applicationId,
+          organizationId,
+          directoryHash,
+          message: error.message
+        };
+
+        expect(loggedError.error).toBe(error);
+        expect(loggedError.message).toBe(error.message);
+
+        // Re-throwing as generic Error should work
+        expect(() => {
+          throw new Error('Unable to launch build');
+        }).toThrow('Unable to launch build');
+      }
+    });
+
+    test('new error types provide additional functionality when accessed', async () => {
+      const mockAxios = jest.spyOn(axios, 'request');
+      mockAxios.mockRejectedValue(
+        new AxiosError('Unauthorized', 'UNAUTHORIZED', undefined, undefined, {
+          headers: {},
+          config: {
+            headers: new AxiosHeaders()
+          },
+          status: 401,
+          statusText: 'Unauthorized',
+          data: { message: 'Invalid token' }
+        })
+      );
 
       const sabs = new SabsClient('http://localhost:3000');
-      await expect(sabs.status({ buildId: anyBuildId, accessToken: anyAccessToken })).rejects.toThrow(expectedError);
+
+      try {
+        await sabs.status({ buildId: 'test-build', accessToken: 'invalid-token' });
+      } catch (error) {
+        // Backward compatible - can still catch as Error
+        expect(error).toBeInstanceOf(Error);
+
+        // But applications can now also check for specific error types
+        const { UnauthorizedError } = await import('./errors');
+        expect(error).toBeInstanceOf(UnauthorizedError);
+
+        // And access the status code if needed
+        if ('status' in error) {
+          expect(error.status).toBe(401);
+        }
+      }
+    });
+
+    describe('response data handling', () => {
+      test('handles responseData with message property', async () => {
+        const mockAxios = jest.spyOn(axios, 'request');
+        mockAxios.mockRejectedValue(
+          new AxiosError('Bad Request', 'BAD_REQUEST', undefined, undefined, {
+            headers: {},
+            config: {
+              headers: new AxiosHeaders()
+            },
+            status: 400,
+            statusText: 'Bad Request',
+            data: { message: 'Directory hash is required' }
+          })
+        );
+
+        const sabs = new SabsClient('http://localhost:3000');
+
+        try {
+          await sabs.build({
+            directoryHash: 'test', // Use non-empty value to avoid client-side validation
+            meta: new ApplicationMetadata({ id: 'test', organizationId: 'test' }),
+            buildKey: 'test',
+            accessToken: 'test'
+          });
+        } catch (error) {
+          expect(error).toBeInstanceOf(Error);
+          expect(error.message).toBe('SABS API Error (400): Directory hash is required');
+        }
+      });
+
+      test('handles responseData as string', async () => {
+        const mockAxios = jest.spyOn(axios, 'request');
+        mockAxios.mockRejectedValue(
+          new AxiosError('Internal Server Error', 'INTERNAL_SERVER_ERROR', undefined, undefined, {
+            headers: {},
+            config: {
+              headers: new AxiosHeaders()
+            },
+            status: 500,
+            statusText: 'Internal Server Error',
+            data: 'Database connection failed'
+          })
+        );
+
+        const sabs = new SabsClient('http://localhost:3000');
+
+        try {
+          await sabs.build({
+            directoryHash: 'test',
+            meta: new ApplicationMetadata({ id: 'test', organizationId: 'test' }),
+            buildKey: 'test',
+            accessToken: 'test'
+          });
+        } catch (error) {
+          expect(error).toBeInstanceOf(Error);
+          expect(error.message).toBe('SABS API Error (500): Database connection failed');
+        }
+      });
+
+      test('handles null responseData', async () => {
+        const mockAxios = jest.spyOn(axios, 'request');
+        mockAxios.mockRejectedValue(
+          new AxiosError('Service Unavailable', 'SERVICE_UNAVAILABLE', undefined, undefined, {
+            headers: {},
+            config: {
+              headers: new AxiosHeaders()
+            },
+            status: 503,
+            statusText: 'Service Unavailable',
+            data: null
+          })
+        );
+
+        const sabs = new SabsClient('http://localhost:3000');
+
+        try {
+          await sabs.build({
+            directoryHash: 'test',
+            meta: new ApplicationMetadata({ id: 'test', organizationId: 'test' }),
+            buildKey: 'test',
+            accessToken: 'test'
+          });
+        } catch (error) {
+          expect(error).toBeInstanceOf(Error);
+          expect(error.message).toBe('SABS API Error (503): Service Unavailable (503)');
+        }
+      });
+
+      test('handles undefined responseData', async () => {
+        const mockAxios = jest.spyOn(axios, 'request');
+        mockAxios.mockRejectedValue(
+          new AxiosError('Gateway Timeout', 'GATEWAY_TIMEOUT', undefined, undefined, {
+            headers: {},
+            config: {
+              headers: new AxiosHeaders()
+            },
+            status: 504,
+            statusText: 'Gateway Timeout',
+            data: undefined
+          })
+        );
+
+        const sabs = new SabsClient('http://localhost:3000');
+
+        try {
+          await sabs.build({
+            directoryHash: 'test',
+            meta: new ApplicationMetadata({ id: 'test', organizationId: 'test' }),
+            buildKey: 'test',
+            accessToken: 'test'
+          });
+        } catch (error) {
+          expect(error).toBeInstanceOf(Error);
+          expect(error.message).toBe('SABS API Error (504): Gateway Timeout (504)');
+        }
+      });
+
+      test('handles responseData object without message property', async () => {
+        const mockAxios = jest.spyOn(axios, 'request');
+        mockAxios.mockRejectedValue(
+          new AxiosError('Bad Request', 'BAD_REQUEST', undefined, undefined, {
+            headers: {},
+            config: {
+              headers: new AxiosHeaders()
+            },
+            status: 400,
+            statusText: 'Bad Request',
+            data: { error: 'validation_failed', details: ['field is required'] }
+          })
+        );
+
+        const sabs = new SabsClient('http://localhost:3000');
+
+        try {
+          await sabs.build({
+            directoryHash: 'test',
+            meta: new ApplicationMetadata({ id: 'test', organizationId: 'test' }),
+            buildKey: 'test',
+            accessToken: 'test'
+          });
+        } catch (error) {
+          expect(error).toBeInstanceOf(Error);
+          expect(error.message).toBe('SABS API Error (400): Bad Request (400)');
+        }
+      });
+
+      test('all errors have consistent HttpError interface', async () => {
+        const responseData = { code: 'TIMEOUT', retryAfter: 30 };
+        const mockAxios = jest.spyOn(axios, 'request');
+        mockAxios.mockRejectedValue(
+          new AxiosError('Request timeout', 'TIMEOUT', undefined, undefined, {
+            headers: {},
+            config: {
+              headers: new AxiosHeaders()
+            },
+            status: 500,
+            statusText: 'Internal Server Error',
+            data: responseData
+          })
+        );
+
+        const sabs = new SabsClient('http://localhost:3000');
+
+        try {
+          await sabs.build({
+            directoryHash: 'test',
+            meta: new ApplicationMetadata({ id: 'test', organizationId: 'test' }),
+            buildKey: 'test',
+            accessToken: 'test'
+          });
+        } catch (error) {
+          expect(error).toBeInstanceOf(Error);
+          expect(error.message).toBe('SABS API Error (500): Internal Server Error (500)');
+
+          // All error types now have consistent HttpError interface
+          expect('status' in error).toBe(true);
+          expect('title' in error).toBe(true);
+          if ('status' in error) {
+            expect(error.status).toBe(500);
+          }
+          if ('title' in error) {
+            expect(error.title).toBe('Internal server error');
+          }
+        }
+      });
     });
   });
 });

package/src/sabs.ts

@@ -17,6 +17,17 @@ import {
 } from '@superblocksteam/sabs-types';
 import axios, { AxiosRequestConfig, RawAxiosRequestHeaders } from 'axios';
 
+import { createErrorFromStatusCode, createClientError, createNetworkError } from './errors';
+
+/**
+ * SABS (Superblocks Application Build System) TypeScript Client
+ *
+ * Provides methods to interact with the SABS API for building and managing applications.
+ *
+ * All error types inherit from the standard `HttpError` class that extends the standard `Error` class,
+ * ensuring backward compatibility with existing error handling code that catches generic `Error` instances
+ * used in earlier versions of the client library.
+ */
 export class SabsClient {
   private readonly baseUrl: string;
 
@@ -24,6 +35,20 @@ export class SabsClient {
     this.baseUrl = baseUrl;
   }
 
+  /**
+   * Start a new build for an application
+   *
+   * @param params - Build parameters
+   * @param params.directoryHash - Hash of the application directory to build
+   * @param params.meta - Application metadata (ID and organization ID)
+   * @param params.buildKey - Secret build key for authentication
+   * @param params.accessToken - JWT access token for authorization
+   * @returns Promise resolving to build information including build ID
+   * @throws BadRequestError if the directory hash, application metadata, application ID, organization ID, build key, or access token are empty or invalid
+   * @throws ForbiddenError if the access token is invalid or missing the required scopes
+   * @throws InternalServerError if the service has an unexpected error while performing this request
+   * @throws HttpError if the request fails for an unknown reason
+   */
   public async build({
     directoryHash,
     meta,
@@ -36,22 +61,22 @@ export class SabsClient {
     accessToken?: string;
   }): Promise<BuildResponse> {
     if (!directoryHash || directoryHash.length === 0) {
-      throw new Error('Directory hash is required');
+      throw createClientError('Directory hash is required');
     }
     if (!meta) {
-      throw new Error('Application metadata is required');
+      throw createClientError('Application metadata is required');
     }
     if (!meta.id || meta.id.length === 0) {
-      throw new Error('Application ID is required');
+      throw createClientError('Application ID is required');
     }
     if (!meta.organizationId || meta.organizationId.length === 0) {
-      throw new Error('Organization ID is required');
+      throw createClientError('Organization ID is required');
     }
     if (!buildKey || buildKey.length === 0) {
-      throw new Error('Build key is required');
+      throw createClientError('Build key is required');
     }
     if (!accessToken || accessToken.length === 0) {
-      throw new Error('Access token is required');
+      throw createClientError('Access token is required');
     }
 
     const data = new BuildRequest({
@@ -70,12 +95,25 @@ export class SabsClient {
     );
   }
 
+  /**
+   * Get the status of a build
+   *
+   * @param params - Status query parameters
+   * @param params.buildId - ID of the build to check
+   * @param params.accessToken - JWT access token for authorization
+   * @returns Promise resolving to build status information
+   * @throws BadRequestError if the build ID or access token is empty or invalid
+   * @throws UnauthorizedError if the access token is invalid or missing the required scopes
+   * @throws NotFoundError if the build ID is invalid
+   * @throws InternalServerError if the service has an unexpected error while performing this request
+   * @throws HttpError if the request fails for an unknown reason
+   */
   public async status({ buildId, accessToken }: { buildId: string; accessToken?: string }): Promise<StatusResponse> {
     if (!buildId || buildId.length === 0) {
-      throw new Error('Build ID is required');
+      throw createClientError('Build ID is required');
     }
     if (!accessToken || accessToken.length === 0) {
-      throw new Error('Access token is required');
+      throw createClientError('Access token is required');
     }
 
     return this.executeRequest<StatusResponse>(
@@ -87,6 +125,21 @@ export class SabsClient {
     );
   }
 
+  /**
+   * Get the status of multiple builds at once
+   *
+   * @param params - Bulk status query parameters
+   * @param params.organizationId - Organization ID
+   * @param params.applicationId - Application ID
+   * @param params.directoryHashes - Array of directory hashes to check
+   * @param params.accessToken - JWT access token for authorization
+   * @returns Promise resolving to multiple build status information
+   * @throws BadRequestError if the organization ID, application ID, directory hashes, or access token are empty or invalid
+   * @throws UnauthorizedError if the access token is invalid or missing the required scopes
+   * @throws NotFoundError if the organization ID or application ID is invalid
+   * @throws InternalServerError if the service has an unexpected error while performing this request
+   * @throws HttpError if the request fails for an unknown reason
+   */
   public async bulkStatus({
     organizationId,
     applicationId,
@@ -99,16 +152,16 @@ export class SabsClient {
     accessToken?: string;
   }): Promise<BulkStatusResponse> {
     if (!organizationId || organizationId.length === 0) {
-      throw new Error('Organization ID is required');
+      throw createClientError('Organization ID is required');
     }
     if (!applicationId || applicationId.length === 0) {
-      throw new Error('Application ID is required');
+      throw createClientError('Application ID is required');
     }
     if (!directoryHashes || directoryHashes.length === 0) {
-      throw new Error('Directory hashes are required');
+      throw createClientError('Directory hashes are required');
     }
     if (!accessToken || accessToken.length === 0) {
-      throw new Error('Access token is required');
+      throw createClientError('Access token is required');
     }
 
     const data = new BulkStatusRequest({
@@ -127,6 +180,21 @@ export class SabsClient {
     );
   }
 
+  /**
+   * List all builds for a specific application and directory
+   *
+   * @param params - List query parameters
+   * @param params.organizationId - Organization ID
+   * @param params.applicationId - Application ID
+   * @param params.directoryHash - Hash of the application directory
+   * @param params.accessToken - JWT access token for authorization
+   * @returns Promise resolving to list of builds
+   * @throws BadRequestError if the organization ID, application ID, directory hash, or access token are empty or invalid
+   * @throws UnauthorizedError if the access token is invalid or missing the required scopes
+   * @throws NotFoundError if the organization ID or application ID is invalid
+   * @throws InternalServerError if the service has an unexpected error while performing this request
+   * @throws HttpError if the request fails for an unknown reason
+   */
   public async list({
     organizationId,
     applicationId,
@@ -139,16 +207,16 @@ export class SabsClient {
     accessToken?: string;
   }): Promise<ListResponse> {
     if (!organizationId || organizationId.length === 0) {
-      throw new Error('Organization ID is required');
+      throw createClientError('Organization ID is required');
     }
     if (!applicationId || applicationId.length === 0) {
-      throw new Error('Application ID is required');
+      throw createClientError('Application ID is required');
     }
     if (!directoryHash || directoryHash.length === 0) {
-      throw new Error('Directory hash is required');
+      throw createClientError('Directory hash is required');
     }
     if (!accessToken || accessToken.length === 0) {
-      throw new Error('Access token is required');
+      throw createClientError('Access token is required');
     }
 
     const data = new ListRequest({
@@ -167,6 +235,22 @@ export class SabsClient {
     );
   }
 
+  /**
+   * Terminate a running build with a final status
+   *
+   * @param params - Termination parameters
+   * @param params.buildId - ID of the build to terminate
+   * @param params.status - Final status of the build
+   * @param params.buildKey - Secret build key for authentication
+   * @param params.error - Optional error message if build failed
+   * @param params.accessToken - JWT access token for authorization
+   * @returns Promise resolving to termination confirmation
+   * @throws BadRequestError if the build ID, build status, build key, or access token are empty or invalid
+   * @throws UnauthorizedError if the access token is invalid or missing the required scopes
+   * @throws NotFoundError if the build ID is invalid
+   * @throws InternalServerError if the service has an unexpected error while performing this request
+   * @throws HttpError if the request fails for an unknown reason
+   */
   public async terminate({
     buildId,
     status,
@@ -181,16 +265,16 @@ export class SabsClient {
     accessToken?: string;
   }): Promise<TerminateResponse> {
     if (!buildId || buildId.length === 0) {
-      throw new Error('Build ID is required');
+      throw createClientError('Build ID is required');
     }
     if (!status) {
-      throw new Error('Build status is required');
+      throw createClientError('Build status is required');
     }
     if (!buildKey || buildKey.length === 0) {
-      throw new Error('Build key is required');
+      throw createClientError('Build key is required');
     }
     if (!accessToken || accessToken.length === 0) {
-      throw new Error('Access token is required');
+      throw createClientError('Access token is required');
     }
 
     const data = new TerminateRequest({
@@ -210,6 +294,21 @@ export class SabsClient {
     );
   }
 
+  /**
+   * Create a new live edit session for real-time development
+   *
+   * @param params - Live edit creation parameters
+   * @param params.applicationId - Application ID
+   * @param params.organizationId - Organization ID
+   * @param params.branch - Git branch name
+   * @param params.expiresIn - Session duration in seconds
+   * @param params.accessToken - JWT access token for authorization
+   * @returns Promise resolving to live edit session information
+   * @throws BadRequestError if the application ID, organization ID, branch, or access token are empty or invalid, or expiresIn is not greater than 0
+   * @throws UnauthorizedError if the access token is invalid or missing the required scopes
+   * @throws InternalServerError if the service has an unexpected error while performing this request
+   * @throws HttpError if the request fails for an unknown reason
+   */
   public async createLiveEdit({
     applicationId,
     organizationId,
@@ -224,16 +323,19 @@ export class SabsClient {
     accessToken: string;
   }): Promise<CreateLiveEditResponse> {
     if (!applicationId || applicationId.length === 0) {
-      throw new Error('Application ID is required');
+      throw createClientError('Application ID is required');
     }
     if (!organizationId || organizationId.length === 0) {
-      throw new Error('Organization ID is required');
+      throw createClientError('Organization ID is required');
     }
     if (!branch || branch.length === 0) {
-      throw new Error('Branch is required');
+      throw createClientError('Branch is required');
     }
     if (!accessToken || accessToken.length === 0) {
-      throw new Error('Access token is required');
+      throw createClientError('Access token is required');
+    }
+    if (!expiresIn || expiresIn <= 0) {
+      throw createClientError('Expires in is required and must be greater than 0');
     }
 
     const data = new CreateLiveEditRequest({
@@ -256,6 +358,19 @@ export class SabsClient {
     );
   }
 
+  /**
+   * Terminate an active live edit session
+   *
+   * @param params - Live edit termination parameters
+   * @param params.liveEditId - ID of the live edit session to terminate
+   * @param params.accessToken - JWT access token for authorization
+   * @returns Promise resolving to termination confirmation
+   * @throws BadRequestError if the live edit ID or access token are empty or invalid
+   * @throws UnauthorizedError if the access token is invalid or missing the required scopes
+   * @throws NotFoundError if the live edit ID is invalid
+   * @throws InternalServerError if the service has an unexpected error while performing this request
+   * @throws HttpError if the request fails for an unknown reason
+   */
   public async terminateLiveEdit({
     liveEditId,
     accessToken
@@ -264,10 +379,10 @@ export class SabsClient {
     accessToken: string;
   }): Promise<TerminateLiveEditResponse> {
     if (!liveEditId || liveEditId.length === 0) {
-      throw new Error('Live edit ID is required');
+      throw createClientError('Live edit ID is required');
     }
     if (!accessToken || accessToken.length === 0) {
-      throw new Error('Access token is required');
+      throw createClientError('Access token is required');
     }
 
     const data = new TerminateLiveEditRequest({
@@ -300,12 +415,26 @@ export class SabsClient {
       });
       return response.data;
     } catch (error) {
-      let errMsg = `sabs service request failed: ${error.message}`;
       if (axios.isAxiosError(error)) {
-        errMsg += `\n[${error.response?.status}] ${error.response?.statusText}: ${JSON.stringify(error.response?.data)}`;
-      }
+        const statusCode = error.response?.status ?? 500;
+        const statusText = error.response?.statusText ?? 'Unknown Error';
+        const responseData = error.response?.data;
 
-      throw new Error(errMsg);
+        let message: string;
+        if (responseData && typeof responseData === 'object' && responseData.message) {
+          message = responseData.message;
+        } else if (responseData && typeof responseData === 'string') {
+          message = responseData;
+        } else {
+          message = `${statusText} (${statusCode})`;
+        }
+
+        throw createErrorFromStatusCode(statusCode, message);
+      } else {
+        // Network error or other non-HTTP error
+        const message = error instanceof Error ? error.message : 'Unknown error occurred';
+        throw createNetworkError(message, error instanceof Error ? error : undefined);
+      }
     }
   }
 }