feat(api): export error classes and interfaces for advanced usage 🚀

- Add advanced error handling documentation with import examples and instanceof checks
- Export error classes for specific error handling (ValidationError, TokenExpiredError, etc.)
- Export TypeScript interfaces for type safety (JWTOptions, EncryptionAlgo, etc.)
- Update version to 1.4.1 for patch release

Author: NeaByteLab

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.4.1] - 2025-09-06
+
+### Added
+- **Error class exports**: Export custom error classes for advanced error handling
+- **Interface type exports**: Export TypeScript interfaces for type safety and development
+- **Advanced error handling documentation**: Examples with import statements and instanceof checks
+
+### Changed
+- **Type safety**: Exported interfaces enable better TypeScript development experience
+
+---
+
 ## [1.4.0] - 2025-09-06
 
 ### Added

README.md

@@ -181,6 +181,8 @@ Extracts data from token, throws on error.
 
 ## ❌ Error Handling
 
+### Basic Error Handling
+
 ```javascript
 // Using verify() - returns boolean
 const isValid = jwt.verify(token)
@@ -205,6 +207,58 @@ try {
 }
 ```
 
+### Advanced Error Handling
+
+```javascript
+import { 
+  SecureJWT, 
+  TokenExpiredError, 
+  ValidationError,
+  EncryptionError,
+  DecryptionError,
+  PayloadTooLargeError,
+  TokenInvalidError,
+  VersionMismatchError
+} from '@neabyte/secure-jwt'
+
+const jwt = new SecureJWT({
+  secret: 'your-secret-key',
+  expireIn: '1h'
+})
+
+// Specific error handling
+try {
+  jwt.verifyStrict(token)
+  console.log('Token is valid')
+} catch (error) {
+  if (error instanceof TokenExpiredError) {
+    console.log('Token expired:', error.message)
+    // Handle expired token - redirect to login
+  } else if (error instanceof ValidationError) {
+    console.log('Invalid token format:', error.message)
+    // Handle invalid format - show error message
+  } else if (error instanceof VersionMismatchError) {
+    console.log('Token version mismatch:', error.message)
+    // Handle version mismatch - force re-login
+  } else if (error instanceof PayloadTooLargeError) {
+    console.log('Payload too large:', error.message)
+    // Handle oversized payload - reduce data size
+  } else {
+    console.log('Unknown error:', error.message)
+  }
+}
+
+// Error properties
+try {
+  jwt.verifyStrict(token)
+} catch (error) {
+  console.log('Error type:', error.constructor.name)
+  console.log('Error code:', error.code)               // e.g., 'TOKEN_EXPIRED'
+  console.log('Status code:', error.statusCode)        // e.g., 401
+  console.log('Error message:', error.message)         // Human-readable message
+}
+```
+
 ---
 
 ## 🏗️ Architecture

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neabyte/secure-jwt",
   "description": "Secure JWT with AES-256-GCM & ChaCha20-Poly1305 encryption, built-in caching, tamper detection, and TypeScript support",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

src/index.ts

@@ -327,3 +327,31 @@ export default class SecureJWT {
     }
   }
 }
+
+/**
+ * Export interfaces for external use
+ * @see {@link @interfaces/index}
+ */
+export type {
+  EncryptionAlgo,
+  JWTOptions,
+  JWTPayload,
+  KeyDerivationAlgo,
+  TimeUnit
+} from '@interfaces/index'
+
+/**
+ * Export error classes for external use
+ * @see {@link @utils/index}
+ */
+export {
+  ValidationError,
+  EncryptionError,
+  DecryptionError,
+  PayloadTooLargeError,
+  TokenExpiredError,
+  VersionMismatchError,
+  TokenInvalidError,
+  TimeFormatError,
+  SecretKeyError
+} from '@utils/index'