@jazzdev/dpd-local-sdk 1.0.13 → 1.1.1

package/dist/index.d.mts

@@ -260,6 +260,13 @@ interface CreateShipmentResult {
     labelUrl?: string;
     error?: string;
     errorCode?: string;
+    errorDetails?: {
+        status: number;
+        statusText: string;
+        error: unknown;
+        raw: string;
+        endpoint: string;
+    };
 }
 interface GenerateLabelParams {
     shipmentId: string | number;
@@ -316,6 +323,24 @@ interface LogFilters {
     endDate?: Date;
     limit?: number;
 }
+interface GeoSessionStorage {
+    get(): Promise<{
+        geoSession: string;
+        expiry: Date;
+    } | null>;
+    set(geoSession: string, expiry: Date): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class InMemoryGeoSessionStorage implements GeoSessionStorage {
+    private geoSession;
+    private expiry;
+    get(): Promise<{
+        geoSession: string;
+        expiry: Date;
+    } | null>;
+    set(geoSession: string, expiry: Date): Promise<void>;
+    clear(): Promise<void>;
+}
 
 declare const DPD_API: {
     readonly BASE_URL: "https://api.dpdlocal.co.uk";
@@ -408,6 +433,23 @@ declare function testConnection(credentials: DPDCredentials): Promise<{
     success: boolean;
     message: string;
 }>;
+declare class GeoSessionManager {
+    private credentials;
+    private storage;
+    private maxRetries;
+    private baseRetryDelay;
+    constructor(credentials: DPDCredentials, storage?: GeoSessionStorage, options?: {
+        maxRetries?: number;
+        baseRetryDelay?: number;
+    });
+    getValidGeoSession(): Promise<string>;
+    refreshGeoSession(): Promise<string>;
+    clearGeoSession(): Promise<void>;
+    private isSessionValid;
+    private authenticateWithRetry;
+    private authenticate;
+    private delay;
+}
 
 declare function createShipment(credentials: DPDCredentials, params: CreateShipmentParams, businessConfig: any): Promise<CreateShipmentResult>;
 declare function generateLabel(credentials: DPDCredentials, params: GenerateLabelParams): Promise<GenerateLabelResult>;
@@ -498,4 +540,4 @@ declare function loggedOperation<T>(params: {
     headers?: Record<string, string>;
 }>): Promise<T>;
 
-export { type BusinessConfig, type CreateShipmentParams, type CreateShipmentResult, type DPDAddress, type DPDAuthResponse, type DPDConsignment, type DPDContact, type DPDCredentials, type DPDError, type DPDLabelRequest, type DPDLabelResponse, type DPDLogDocument, type DPDModuleConfig, type DPDParcel, _default as DPDService, type DPDServiceCode, type DPDShipmentRequest, type DPDShipmentResponse, DPD_API, type DatabaseAdapter, type GenerateLabelParams, type GenerateLabelResult, type LabelConfig, type LogFilters, type NotificationConfig, type PricingConfig, SERVICE_DESCRIPTIONS, SERVICE_NAMES, type SavedAddress, type ServiceConfig, type ShipmentStatus, type ShipmentStatusUpdate, type ShippingData, type StorageAdapter, type TimestampType, type TrackShipmentParams, type TrackShipmentResult, type ValidateAddressParams, type ValidateAddressResult, authenticate, authenticatedRequest, calculateDPDCost, calculateDeliveryFee, calculateParcels, clearGeoSession, configureLogger, createCompleteShipment, createDPDConfig, createShipment, deleteSavedAddress, generateAndUploadLabel, generateConsignmentRef, generateLabel, getAuthStatus, getEstimatedDeliveryDate, getGeoSession, getLabelUrl, getNextCollectionDate, getSavedAddress, getSavedAddresses, getServiceDescription, getServiceName, getTokenExpiry, getTrackingUrl, hasValidToken, isValidServiceCode, logOperation, loggedOperation, meetsMinimumOrderValue, qualifiesForFreeDelivery, regenerateLabel, saveAddress, setLoggerAdapter, startTimer, testConnection, testDPDConnection, trackShipment, updateSavedAddress, validateAddress, validateDeliveryAddress, validateServiceCode };
+export { type BusinessConfig, type CreateShipmentParams, type CreateShipmentResult, type DPDAddress, type DPDAuthResponse, type DPDConsignment, type DPDContact, type DPDCredentials, type DPDError, type DPDLabelRequest, type DPDLabelResponse, type DPDLogDocument, type DPDModuleConfig, type DPDParcel, _default as DPDService, type DPDServiceCode, type DPDShipmentRequest, type DPDShipmentResponse, DPD_API, type DatabaseAdapter, type GenerateLabelParams, type GenerateLabelResult, GeoSessionManager, type GeoSessionStorage, InMemoryGeoSessionStorage, type LabelConfig, type LogFilters, type NotificationConfig, type PricingConfig, SERVICE_DESCRIPTIONS, SERVICE_NAMES, type SavedAddress, type ServiceConfig, type ShipmentStatus, type ShipmentStatusUpdate, type ShippingData, type StorageAdapter, type TimestampType, type TrackShipmentParams, type TrackShipmentResult, type ValidateAddressParams, type ValidateAddressResult, authenticate, authenticatedRequest, calculateDPDCost, calculateDeliveryFee, calculateParcels, clearGeoSession, configureLogger, createCompleteShipment, createDPDConfig, createShipment, deleteSavedAddress, generateAndUploadLabel, generateConsignmentRef, generateLabel, getAuthStatus, getEstimatedDeliveryDate, getGeoSession, getLabelUrl, getNextCollectionDate, getSavedAddress, getSavedAddresses, getServiceDescription, getServiceName, getTokenExpiry, getTrackingUrl, hasValidToken, isValidServiceCode, logOperation, loggedOperation, meetsMinimumOrderValue, qualifiesForFreeDelivery, regenerateLabel, saveAddress, setLoggerAdapter, startTimer, testConnection, testDPDConnection, trackShipment, updateSavedAddress, validateAddress, validateDeliveryAddress, validateServiceCode };

package/dist/index.d.ts

@@ -260,6 +260,13 @@ interface CreateShipmentResult {
     labelUrl?: string;
     error?: string;
     errorCode?: string;
+    errorDetails?: {
+        status: number;
+        statusText: string;
+        error: unknown;
+        raw: string;
+        endpoint: string;
+    };
 }
 interface GenerateLabelParams {
     shipmentId: string | number;
@@ -316,6 +323,24 @@ interface LogFilters {
     endDate?: Date;
     limit?: number;
 }
+interface GeoSessionStorage {
+    get(): Promise<{
+        geoSession: string;
+        expiry: Date;
+    } | null>;
+    set(geoSession: string, expiry: Date): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class InMemoryGeoSessionStorage implements GeoSessionStorage {
+    private geoSession;
+    private expiry;
+    get(): Promise<{
+        geoSession: string;
+        expiry: Date;
+    } | null>;
+    set(geoSession: string, expiry: Date): Promise<void>;
+    clear(): Promise<void>;
+}
 
 declare const DPD_API: {
     readonly BASE_URL: "https://api.dpdlocal.co.uk";
@@ -408,6 +433,23 @@ declare function testConnection(credentials: DPDCredentials): Promise<{
     success: boolean;
     message: string;
 }>;
+declare class GeoSessionManager {
+    private credentials;
+    private storage;
+    private maxRetries;
+    private baseRetryDelay;
+    constructor(credentials: DPDCredentials, storage?: GeoSessionStorage, options?: {
+        maxRetries?: number;
+        baseRetryDelay?: number;
+    });
+    getValidGeoSession(): Promise<string>;
+    refreshGeoSession(): Promise<string>;
+    clearGeoSession(): Promise<void>;
+    private isSessionValid;
+    private authenticateWithRetry;
+    private authenticate;
+    private delay;
+}
 
 declare function createShipment(credentials: DPDCredentials, params: CreateShipmentParams, businessConfig: any): Promise<CreateShipmentResult>;
 declare function generateLabel(credentials: DPDCredentials, params: GenerateLabelParams): Promise<GenerateLabelResult>;
@@ -498,4 +540,4 @@ declare function loggedOperation<T>(params: {
     headers?: Record<string, string>;
 }>): Promise<T>;
 
-export { type BusinessConfig, type CreateShipmentParams, type CreateShipmentResult, type DPDAddress, type DPDAuthResponse, type DPDConsignment, type DPDContact, type DPDCredentials, type DPDError, type DPDLabelRequest, type DPDLabelResponse, type DPDLogDocument, type DPDModuleConfig, type DPDParcel, _default as DPDService, type DPDServiceCode, type DPDShipmentRequest, type DPDShipmentResponse, DPD_API, type DatabaseAdapter, type GenerateLabelParams, type GenerateLabelResult, type LabelConfig, type LogFilters, type NotificationConfig, type PricingConfig, SERVICE_DESCRIPTIONS, SERVICE_NAMES, type SavedAddress, type ServiceConfig, type ShipmentStatus, type ShipmentStatusUpdate, type ShippingData, type StorageAdapter, type TimestampType, type TrackShipmentParams, type TrackShipmentResult, type ValidateAddressParams, type ValidateAddressResult, authenticate, authenticatedRequest, calculateDPDCost, calculateDeliveryFee, calculateParcels, clearGeoSession, configureLogger, createCompleteShipment, createDPDConfig, createShipment, deleteSavedAddress, generateAndUploadLabel, generateConsignmentRef, generateLabel, getAuthStatus, getEstimatedDeliveryDate, getGeoSession, getLabelUrl, getNextCollectionDate, getSavedAddress, getSavedAddresses, getServiceDescription, getServiceName, getTokenExpiry, getTrackingUrl, hasValidToken, isValidServiceCode, logOperation, loggedOperation, meetsMinimumOrderValue, qualifiesForFreeDelivery, regenerateLabel, saveAddress, setLoggerAdapter, startTimer, testConnection, testDPDConnection, trackShipment, updateSavedAddress, validateAddress, validateDeliveryAddress, validateServiceCode };
+export { type BusinessConfig, type CreateShipmentParams, type CreateShipmentResult, type DPDAddress, type DPDAuthResponse, type DPDConsignment, type DPDContact, type DPDCredentials, type DPDError, type DPDLabelRequest, type DPDLabelResponse, type DPDLogDocument, type DPDModuleConfig, type DPDParcel, _default as DPDService, type DPDServiceCode, type DPDShipmentRequest, type DPDShipmentResponse, DPD_API, type DatabaseAdapter, type GenerateLabelParams, type GenerateLabelResult, GeoSessionManager, type GeoSessionStorage, InMemoryGeoSessionStorage, type LabelConfig, type LogFilters, type NotificationConfig, type PricingConfig, SERVICE_DESCRIPTIONS, SERVICE_NAMES, type SavedAddress, type ServiceConfig, type ShipmentStatus, type ShipmentStatusUpdate, type ShippingData, type StorageAdapter, type TimestampType, type TrackShipmentParams, type TrackShipmentResult, type ValidateAddressParams, type ValidateAddressResult, authenticate, authenticatedRequest, calculateDPDCost, calculateDeliveryFee, calculateParcels, clearGeoSession, configureLogger, createCompleteShipment, createDPDConfig, createShipment, deleteSavedAddress, generateAndUploadLabel, generateConsignmentRef, generateLabel, getAuthStatus, getEstimatedDeliveryDate, getGeoSession, getLabelUrl, getNextCollectionDate, getSavedAddress, getSavedAddresses, getServiceDescription, getServiceName, getTokenExpiry, getTrackingUrl, hasValidToken, isValidServiceCode, logOperation, loggedOperation, meetsMinimumOrderValue, qualifiesForFreeDelivery, regenerateLabel, saveAddress, setLoggerAdapter, startTimer, testConnection, testDPDConnection, trackShipment, updateSavedAddress, validateAddress, validateDeliveryAddress, validateServiceCode };

package/dist/index.js

@@ -22,6 +22,8 @@ var index_exports = {};
 __export(index_exports, {
   DPDService: () => dpd_service_default,
   DPD_API: () => DPD_API,
+  GeoSessionManager: () => GeoSessionManager,
+  InMemoryGeoSessionStorage: () => InMemoryGeoSessionStorage,
   SERVICE_DESCRIPTIONS: () => SERVICE_DESCRIPTIONS,
   SERVICE_NAMES: () => SERVICE_NAMES,
   authenticate: () => authenticate,
@@ -69,6 +71,28 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/types/index.ts
+var InMemoryGeoSessionStorage = class {
+  constructor() {
+    this.geoSession = null;
+    this.expiry = null;
+  }
+  async get() {
+    if (!this.geoSession || !this.expiry) {
+      return null;
+    }
+    return { geoSession: this.geoSession, expiry: this.expiry };
+  }
+  async set(geoSession, expiry) {
+    this.geoSession = geoSession;
+    this.expiry = expiry;
+  }
+  async clear() {
+    this.geoSession = null;
+    this.expiry = null;
+  }
+};
+
 // src/config/index.ts
 var DPD_API = {
   BASE_URL: "https://api.dpdlocal.co.uk",
@@ -376,9 +400,18 @@ async function authenticatedRequest(credentials, options) {
           await delay(DPD_API.RETRY_DELAY * (attempt + 1));
           continue;
         }
-        throw new Error(
+        const err = new Error(
           data?.error?.errorMessage ?? data?.error?.errorAction ?? data?.error?.obj ?? JSON.stringify(data?.error) ?? `Request failed: ${response.statusText}`
         );
+        err.name = "DPD_API_ERROR";
+        err.dpd = {
+          status: response.status,
+          statusText: response.statusText,
+          error: data?.error,
+          raw,
+          endpoint: url
+        };
+        throw err;
       }
       if (hasError && hasData) {
         console.warn(`
@@ -421,6 +454,164 @@ async function testConnection(credentials) {
     };
   }
 }
+var GeoSessionManager = class {
+  /**
+   * Create a new Geo Session Manager
+   *
+   * @param credentials - DPD API credentials
+   * @param storage - Storage adapter for persistence (optional, defaults to in-memory)
+   * @param options - Configuration options
+   */
+  constructor(credentials, storage, options) {
+    this.credentials = credentials;
+    this.storage = storage || new InMemoryGeoSessionStorage();
+    this.maxRetries = options?.maxRetries ?? 3;
+    this.baseRetryDelay = options?.baseRetryDelay ?? 2e3;
+  }
+  /**
+   * Get a valid geo session token
+   *
+   * - Loads from persistent storage if available and valid
+   * - Automatically refreshes if expired or not found
+   * - Retries with exponential backoff on failure
+   * - Saves to persistent storage after refresh
+   *
+   * @returns Valid geo session token
+   * @throws Error if authentication fails after retries
+   */
+  async getValidGeoSession() {
+    try {
+      const stored = await this.storage.get();
+      if (stored && this.isSessionValid(stored.geoSession, stored.expiry)) {
+        console.log("\u2705 Using cached geo session from storage");
+        return stored.geoSession;
+      }
+      console.log("\u{1F504} Fetching new geo session from DPD API...");
+      const { geoSession, expiry } = await this.authenticateWithRetry();
+      console.log("\u2705 Successfully fetched new geo session");
+      await this.storage.set(geoSession, expiry);
+      return geoSession;
+    } catch (error) {
+      console.error("\u274C Error managing geo session:", error);
+      throw new Error(
+        `Failed to get valid geo session: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Force refresh the geo session
+   * Clears cache and fetches a new token
+   *
+   * @returns New geo session token
+   */
+  async refreshGeoSession() {
+    await this.storage.clear();
+    return this.getValidGeoSession();
+  }
+  /**
+   * Clear stored geo session
+   */
+  async clearGeoSession() {
+    await this.storage.clear();
+  }
+  /**
+   * Check if a session is valid
+   */
+  isSessionValid(geoSession, expiry) {
+    if (!geoSession || !expiry) {
+      return false;
+    }
+    const now = /* @__PURE__ */ new Date();
+    const expiryDate = expiry instanceof Date ? expiry : new Date(expiry);
+    if (expiryDate <= now) {
+      return false;
+    }
+    const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const expiryStartOfDay = new Date(
+      expiryDate.getFullYear(),
+      expiryDate.getMonth(),
+      expiryDate.getDate()
+    );
+    if (expiryStartOfDay.getTime() === startOfToday.getTime()) {
+      const sessionCreatedAt = new Date(expiryDate.getTime() - 90 * 60 * 1e3);
+      const hoursSinceCreation = (now.getTime() - sessionCreatedAt.getTime()) / (1e3 * 60 * 60);
+      if (hoursSinceCreation > 12) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Authenticate with retry logic and exponential backoff
+   */
+  async authenticateWithRetry() {
+    let lastError = null;
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        console.log(`\u{1F4E1} Attempt ${attempt}/${this.maxRetries} to fetch geo session...`);
+        const geoSession = await this.authenticate();
+        const expiry = new Date(Date.now() + 90 * 60 * 1e3);
+        return { geoSession, expiry };
+      } catch (error) {
+        lastError = error;
+        console.error(`\u274C Attempt ${attempt}/${this.maxRetries} failed:`, error);
+        if (attempt < this.maxRetries) {
+          const delay2 = this.baseRetryDelay * Math.pow(2, attempt - 1);
+          console.log(`\u23F3 Retrying in ${delay2}ms...`);
+          await this.delay(delay2);
+        }
+      }
+    }
+    throw new Error(
+      `Failed to authenticate after ${this.maxRetries} attempts: ${lastError?.message || "Unknown error"}`
+    );
+  }
+  /**
+   * Authenticate with DPD API
+   */
+  async authenticate() {
+    const { username, password } = this.credentials;
+    const authHeader = Buffer.from(`${username}:${password}`).toString("base64");
+    const response = await fetch(`${DPD_API.BASE_URL}${DPD_API.ENDPOINTS.AUTH}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Authorization: `Basic ${authHeader}`
+      },
+      signal: AbortSignal.timeout(DPD_API.TIMEOUT)
+    });
+    const raw = await response.text();
+    let payload;
+    try {
+      payload = raw ? JSON.parse(raw) : null;
+    } catch {
+      if (!response.ok) {
+        throw new Error(`Authentication failed: ${raw || response.statusText}`);
+      }
+      throw new Error("Invalid JSON response from DPD API");
+    }
+    if (!response.ok) {
+      throw new Error(
+        payload?.error?.errorMessage ?? `Authentication failed: ${response.status} ${response.statusText}`
+      );
+    }
+    if (payload?.error) {
+      throw new Error(payload.error.errorMessage ?? "Authentication failed");
+    }
+    const geoSession = payload?.data?.geoSession;
+    if (!geoSession) {
+      throw new Error("No GeoSession token received from DPD");
+    }
+    return geoSession;
+  }
+  /**
+   * Delay helper for retry backoff
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
 
 // src/utils/getAcceptHeader.ts
 function getAcceptHeader(format) {
@@ -540,10 +731,12 @@ async function createShipment(credentials, params, businessConfig) {
       trackingUrl
     };
   } catch (error) {
+    const errorDetails = error instanceof Error ? error.dpd : void 0;
     return {
       success: false,
       error: error instanceof Error ? error.message : "Unknown error",
-      errorCode: "SHIPMENT_CREATION_FAILED"
+      errorCode: "SHIPMENT_CREATION_FAILED",
+      errorDetails
     };
   }
 }
@@ -1073,6 +1266,8 @@ function logToConsole(logData) {
 0 && (module.exports = {
   DPDService,
   DPD_API,
+  GeoSessionManager,
+  InMemoryGeoSessionStorage,
   SERVICE_DESCRIPTIONS,
   SERVICE_NAMES,
   authenticate,
@@ -1125,7 +1320,7 @@ function logToConsole(logData) {
  * Database-agnostic and framework-independent
  *
  * @package @jazzdev/dpd-local-sdk
- * @version 1.0.12
+ * @version 1.1.0
  * @author Taiow Babarinde <babsman4all@gmail.com>
  * @license MIT
  */

package/dist/index.mjs

@@ -1,3 +1,25 @@
+// src/types/index.ts
+var InMemoryGeoSessionStorage = class {
+  constructor() {
+    this.geoSession = null;
+    this.expiry = null;
+  }
+  async get() {
+    if (!this.geoSession || !this.expiry) {
+      return null;
+    }
+    return { geoSession: this.geoSession, expiry: this.expiry };
+  }
+  async set(geoSession, expiry) {
+    this.geoSession = geoSession;
+    this.expiry = expiry;
+  }
+  async clear() {
+    this.geoSession = null;
+    this.expiry = null;
+  }
+};
+
 // src/config/index.ts
 var DPD_API = {
   BASE_URL: "https://api.dpdlocal.co.uk",
@@ -305,9 +327,18 @@ async function authenticatedRequest(credentials, options) {
           await delay(DPD_API.RETRY_DELAY * (attempt + 1));
           continue;
         }
-        throw new Error(
+        const err = new Error(
           data?.error?.errorMessage ?? data?.error?.errorAction ?? data?.error?.obj ?? JSON.stringify(data?.error) ?? `Request failed: ${response.statusText}`
         );
+        err.name = "DPD_API_ERROR";
+        err.dpd = {
+          status: response.status,
+          statusText: response.statusText,
+          error: data?.error,
+          raw,
+          endpoint: url
+        };
+        throw err;
       }
       if (hasError && hasData) {
         console.warn(`
@@ -350,6 +381,164 @@ async function testConnection(credentials) {
     };
   }
 }
+var GeoSessionManager = class {
+  /**
+   * Create a new Geo Session Manager
+   *
+   * @param credentials - DPD API credentials
+   * @param storage - Storage adapter for persistence (optional, defaults to in-memory)
+   * @param options - Configuration options
+   */
+  constructor(credentials, storage, options) {
+    this.credentials = credentials;
+    this.storage = storage || new InMemoryGeoSessionStorage();
+    this.maxRetries = options?.maxRetries ?? 3;
+    this.baseRetryDelay = options?.baseRetryDelay ?? 2e3;
+  }
+  /**
+   * Get a valid geo session token
+   *
+   * - Loads from persistent storage if available and valid
+   * - Automatically refreshes if expired or not found
+   * - Retries with exponential backoff on failure
+   * - Saves to persistent storage after refresh
+   *
+   * @returns Valid geo session token
+   * @throws Error if authentication fails after retries
+   */
+  async getValidGeoSession() {
+    try {
+      const stored = await this.storage.get();
+      if (stored && this.isSessionValid(stored.geoSession, stored.expiry)) {
+        console.log("\u2705 Using cached geo session from storage");
+        return stored.geoSession;
+      }
+      console.log("\u{1F504} Fetching new geo session from DPD API...");
+      const { geoSession, expiry } = await this.authenticateWithRetry();
+      console.log("\u2705 Successfully fetched new geo session");
+      await this.storage.set(geoSession, expiry);
+      return geoSession;
+    } catch (error) {
+      console.error("\u274C Error managing geo session:", error);
+      throw new Error(
+        `Failed to get valid geo session: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Force refresh the geo session
+   * Clears cache and fetches a new token
+   *
+   * @returns New geo session token
+   */
+  async refreshGeoSession() {
+    await this.storage.clear();
+    return this.getValidGeoSession();
+  }
+  /**
+   * Clear stored geo session
+   */
+  async clearGeoSession() {
+    await this.storage.clear();
+  }
+  /**
+   * Check if a session is valid
+   */
+  isSessionValid(geoSession, expiry) {
+    if (!geoSession || !expiry) {
+      return false;
+    }
+    const now = /* @__PURE__ */ new Date();
+    const expiryDate = expiry instanceof Date ? expiry : new Date(expiry);
+    if (expiryDate <= now) {
+      return false;
+    }
+    const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const expiryStartOfDay = new Date(
+      expiryDate.getFullYear(),
+      expiryDate.getMonth(),
+      expiryDate.getDate()
+    );
+    if (expiryStartOfDay.getTime() === startOfToday.getTime()) {
+      const sessionCreatedAt = new Date(expiryDate.getTime() - 90 * 60 * 1e3);
+      const hoursSinceCreation = (now.getTime() - sessionCreatedAt.getTime()) / (1e3 * 60 * 60);
+      if (hoursSinceCreation > 12) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Authenticate with retry logic and exponential backoff
+   */
+  async authenticateWithRetry() {
+    let lastError = null;
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        console.log(`\u{1F4E1} Attempt ${attempt}/${this.maxRetries} to fetch geo session...`);
+        const geoSession = await this.authenticate();
+        const expiry = new Date(Date.now() + 90 * 60 * 1e3);
+        return { geoSession, expiry };
+      } catch (error) {
+        lastError = error;
+        console.error(`\u274C Attempt ${attempt}/${this.maxRetries} failed:`, error);
+        if (attempt < this.maxRetries) {
+          const delay2 = this.baseRetryDelay * Math.pow(2, attempt - 1);
+          console.log(`\u23F3 Retrying in ${delay2}ms...`);
+          await this.delay(delay2);
+        }
+      }
+    }
+    throw new Error(
+      `Failed to authenticate after ${this.maxRetries} attempts: ${lastError?.message || "Unknown error"}`
+    );
+  }
+  /**
+   * Authenticate with DPD API
+   */
+  async authenticate() {
+    const { username, password } = this.credentials;
+    const authHeader = Buffer.from(`${username}:${password}`).toString("base64");
+    const response = await fetch(`${DPD_API.BASE_URL}${DPD_API.ENDPOINTS.AUTH}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Authorization: `Basic ${authHeader}`
+      },
+      signal: AbortSignal.timeout(DPD_API.TIMEOUT)
+    });
+    const raw = await response.text();
+    let payload;
+    try {
+      payload = raw ? JSON.parse(raw) : null;
+    } catch {
+      if (!response.ok) {
+        throw new Error(`Authentication failed: ${raw || response.statusText}`);
+      }
+      throw new Error("Invalid JSON response from DPD API");
+    }
+    if (!response.ok) {
+      throw new Error(
+        payload?.error?.errorMessage ?? `Authentication failed: ${response.status} ${response.statusText}`
+      );
+    }
+    if (payload?.error) {
+      throw new Error(payload.error.errorMessage ?? "Authentication failed");
+    }
+    const geoSession = payload?.data?.geoSession;
+    if (!geoSession) {
+      throw new Error("No GeoSession token received from DPD");
+    }
+    return geoSession;
+  }
+  /**
+   * Delay helper for retry backoff
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
 
 // src/utils/getAcceptHeader.ts
 function getAcceptHeader(format) {
@@ -469,10 +658,12 @@ async function createShipment(credentials, params, businessConfig) {
       trackingUrl
     };
   } catch (error) {
+    const errorDetails = error instanceof Error ? error.dpd : void 0;
     return {
       success: false,
       error: error instanceof Error ? error.message : "Unknown error",
-      errorCode: "SHIPMENT_CREATION_FAILED"
+      errorCode: "SHIPMENT_CREATION_FAILED",
+      errorDetails
     };
   }
 }
@@ -1001,6 +1192,8 @@ function logToConsole(logData) {
 export {
   dpd_service_default as DPDService,
   DPD_API,
+  GeoSessionManager,
+  InMemoryGeoSessionStorage,
   SERVICE_DESCRIPTIONS,
   SERVICE_NAMES,
   authenticate,
@@ -1053,7 +1246,7 @@ export {
  * Database-agnostic and framework-independent
  *
  * @package @jazzdev/dpd-local-sdk
- * @version 1.0.12
+ * @version 1.1.0
  * @author Taiow Babarinde <babsman4all@gmail.com>
  * @license MIT
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jazzdev/dpd-local-sdk",
-  "version": "1.0.13",
+  "version": "1.1.1",
   "description": "TypeScript SDK for DPD Local shipping API integration - database-agnostic and framework-independent",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",