feat(sdk): add structured error hierarchy with AuthenticationError

- Add BaseError, AuthenticationError, APIError, ConfigurationError classes
- Replace generic Error with AuthenticationError for tokenProvider failures

Author: santi698

ATTRIBUTIONS.md

@@ -37887,7 +37887,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 
 ## zod
 
-**Version:** 4.0.5  
+**Version:** 4.0.17  
 **License:** MIT
 
 ```

package-lock.json

@@ -39,7 +39,8 @@
   "author": "Aignostics",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.11.0"
+    "axios": "^1.11.0",
+    "zod": "^4.0.17"
   },
   "engines": {
     "node": ">=18.0.0"

packages/sdk/package.json

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { BaseError, AuthenticationError, APIError, ConfigurationError } from './errors.js';
+
+describe('Error Classes', () => {
+  describe('BaseError', () => {
+    it('should create a BaseError with all properties', () => {
+      const context = { userId: '123', action: 'test' };
+      const error = new BaseError('Test message', 'UNEXPECTED_ERROR', { context });
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(BaseError);
+      expect(error.message).toBe('Test message');
+      expect(error.code).toBe('UNEXPECTED_ERROR');
+      expect(error.context).toEqual(context);
+      expect(error.name).toBe('BaseError');
+    });
+
+    it('should create a BaseError without context', () => {
+      const error = new BaseError('Test message', 'UNEXPECTED_ERROR');
+
+      expect(error.message).toBe('Test message');
+      expect(error.code).toBe('UNEXPECTED_ERROR');
+      expect(error.context).toBeUndefined();
+    });
+
+    it('should maintain proper stack trace', () => {
+      const error = new BaseError('Test message', 'UNEXPECTED_ERROR');
+      expect(error.stack).toBeDefined();
+      expect(error.stack).toContain('BaseError');
+    });
+  });
+
+  describe('AuthenticationError', () => {
+    it('should create an AuthenticationError with proper inheritance', () => {
+      const error = new AuthenticationError('Invalid token');
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(BaseError);
+      expect(error).toBeInstanceOf(AuthenticationError);
+      expect(error.message).toBe('Invalid token');
+      expect(error.code).toBe('AUTHENTICATION_ERROR');
+      expect(error.name).toBe('AuthenticationError');
+    });
+
+    it('should create an AuthenticationError with context', () => {
+      const context = { tokenType: 'Bearer', expiry: '2024-01-01' };
+      const error = new AuthenticationError('Token expired', { context });
+
+      expect(error.message).toBe('Token expired');
+      expect(error.context).toEqual(context);
+    });
+  });
+
+  describe('APIError', () => {
+    it('should create an APIError with status code', () => {
+      const error = new APIError('Server error', { statusCode: 500 });
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(BaseError);
+      expect(error).toBeInstanceOf(APIError);
+      expect(error.message).toBe('Server error');
+      expect(error.code).toBe('API_ERROR');
+      expect(error.statusCode).toBe(500);
+      expect(error.name).toBe('APIError');
+    });
+
+    it('should create an APIError without status code', () => {
+      const error = new APIError('Network error');
+
+      expect(error.message).toBe('Network error');
+      expect(error.statusCode).toBeUndefined();
+    });
+
+    it('should create an APIError with context and status code', () => {
+      const context = { endpoint: '/api/test', method: 'GET' };
+      const error = new APIError('Bad request', { context, statusCode: 400 });
+
+      expect(error.statusCode).toBe(400);
+      expect(error.context).toEqual(context);
+    });
+  });
+
+  describe('ConfigurationError', () => {
+    it('should create a ConfigurationError with proper inheritance', () => {
+      const error = new ConfigurationError('Missing API key');
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(BaseError);
+      expect(error).toBeInstanceOf(ConfigurationError);
+      expect(error.message).toBe('Missing API key');
+      expect(error.code).toBe('CONFIGURATION_ERROR');
+      expect(error.name).toBe('ConfigurationError');
+    });
+
+    it('should create a ConfigurationError with context', () => {
+      const context = { configFile: 'config.json', requiredFields: ['apiKey'] };
+      const error = new ConfigurationError('Invalid configuration', { context });
+
+      expect(error.message).toBe('Invalid configuration');
+      expect(error.context).toEqual(context);
+    });
+  });
+
+  describe('Error serialization', () => {
+    it('should serialize errors properly', () => {
+      const context = { test: 'value' };
+      const error = new AuthenticationError('Test error', { context });
+
+      // Test that the error can be converted to JSON (useful for logging)
+      const serialized = JSON.stringify({
+        name: error.name,
+        message: error.message,
+        code: error.code,
+        context: error.context,
+      });
+
+      const parsed = JSON.parse(serialized) as {
+        name: string;
+        message: string;
+        code: string;
+        context: Record<string, unknown>;
+      };
+      expect(parsed.name).toBe('AuthenticationError');
+      expect(parsed.message).toBe('Test error');
+      expect(parsed.code).toBe('AUTHENTICATION_ERROR');
+      expect(parsed.context).toEqual(context);
+    });
+  });
+});

packages/sdk/src/errors.test.ts

@@ -0,0 +1,126 @@
+export type ErrorCode =
+  | 'AUTHENTICATION_ERROR'
+  | 'API_ERROR'
+  | 'CONFIGURATION_ERROR'
+  | 'UNEXPECTED_ERROR';
+
+interface BaseErrorOptions {
+  context?: Record<string, unknown>;
+  originalError?: unknown;
+}
+/**
+ * Base error class for all SDK-related errors
+ *
+ * This class serves as the foundation for all custom error types in the SDK,
+ * providing consistent error handling and additional context information.
+ */
+export class BaseError extends Error {
+  /**
+   * Error code for programmatic error handling
+   */
+  public readonly code: ErrorCode;
+
+  /**
+   * Additional context or metadata related to the error
+   */
+  public readonly context?: Record<string, unknown>;
+
+  /**
+   * Original error that caused this error, if applicable
+   */
+  public readonly originalError?: unknown;
+
+  /**
+   * Creates a new BaseError instance
+   *
+   * @param message - Human-readable error message
+   * @param code - Error code for programmatic handling
+   * @param context - Additional error context or metadata
+   */
+  constructor(message: string, code: ErrorCode, { context, originalError }: BaseErrorOptions = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.context = context;
+    this.originalError = originalError;
+
+    // Maintains proper stack trace for where our error was thrown (Node.js only)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Authentication-related error
+ *
+ * Thrown when authentication fails or when no valid authentication
+ * credentials are available for API requests.
+ */
+export class AuthenticationError extends BaseError {
+  /**
+   * Creates a new AuthenticationError instance
+   *
+   * @param message - Human-readable error message describing the authentication issue
+   * @param options - Additional options about the authentication failure
+   * @param options.context - Additional context about the authentication failure
+   * @param options.originalError - Original error that caused this authentication error
+   */
+  constructor(message: string, options: BaseErrorOptions = {}) {
+    super(message, 'AUTHENTICATION_ERROR', options);
+  }
+}
+
+/**
+ * API-related error
+ *
+ * Thrown when API requests fail due to server errors, network issues,
+ * or invalid responses from the Aignostics Platform API.
+ */
+export class APIError extends BaseError {
+  /**
+   * HTTP status code from the failed API request
+   */
+  public readonly statusCode?: number;
+
+  /**
+   * Creates a new APIError instance
+   *
+   * @param message - Human-readable error message describing the API issue
+   * @param statusCode - HTTP status code from the failed request
+   * @param context - Additional context about the API failure
+   */
+  constructor(message: string, options: BaseErrorOptions & { statusCode?: number } = {}) {
+    super(message, 'API_ERROR', options);
+    this.statusCode = options.statusCode;
+  }
+}
+
+/**
+ * Configuration-related error
+ *
+ * Thrown when SDK configuration is invalid or missing required parameters.
+ */
+export class ConfigurationError extends BaseError {
+  /**
+   * Creates a new ConfigurationError instance
+   *
+   * @param message - Human-readable error message describing the configuration issue
+   * @param context - Additional context about the configuration problem
+   */
+  constructor(message: string, options: BaseErrorOptions = {}) {
+    super(message, 'CONFIGURATION_ERROR', options);
+  }
+}
+
+export class UnexpectedError extends BaseError {
+  /**
+   * Creates a new UnexpectedError instance
+   *
+   * @param message - Human-readable error message describing the unexpected issue
+   * @param context - Additional context about the unexpected error
+   */
+  constructor(message: string, options: BaseErrorOptions = {}) {
+    super(message, 'UNEXPECTED_ERROR', options);
+  }
+}

packages/sdk/src/errors.ts

@@ -3,6 +3,9 @@ import { PlatformSDKHttp } from './platform-sdk.js';
 // Export generated API types and client when available
 export * from './generated/index.js';
 
+// Export error classes
+export { BaseError, AuthenticationError, APIError, ConfigurationError } from './errors.js';
+
 // Export main SDK and types
 export {
   PlatformSDKHttp,