@jazzdev/dpd-local-sdk 1.0.12 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 > TypeScript SDK for integrating DPD Local shipping services into your application. Database-agnostic, framework-independent, and production-ready.
 
-[![npm version](https://badge.fury.io/js/%40your-org%2Fdpd-local-sdk.svg)](https://www.npmjs.com/package/@jazzdev/dpd-local-sdk)
+[![npm version](https://badge.fury.io/js/%40jazzdev%2Fdpd-local-sdk.svg)](https://www.npmjs.com/package/@jazzdev/dpd-local-sdk)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -419,30 +419,25 @@ app.post('/api/shipping/create', async (req, res) => {
 });
 ```
 
-## Environment Variables
+## Configuration
 
-```env
-# DPD Credentials (Required)
-DPD_ACCOUNT_NUMBER=your_account_number
-DPD_USERNAME=your_username
-DPD_PASSWORD=your_password
-
-# Encryption (Required in production)
-DPD_ENCRYPTION_KEY=your_32_byte_hex_key
-
-# Optional
-NODE_ENV=production
-```
-
-### Generating Encryption Key
+The SDK requires DPD credentials which you pass directly to the configuration:
 
 ```typescript
-import { generateEncryptionKey } from '@jazzdev/dpd-local-sdk';
-
-const key = generateEncryptionKey();
-console.log('DPD_ENCRYPTION_KEY=' + key);
+const config = createDPDConfig({
+  credentials: {
+    accountNumber: 'YOUR_ACCOUNT_NUMBER',
+    username: 'YOUR_USERNAME',
+    password: 'YOUR_PASSWORD',
+  },
+  business: {
+    // Your business details
+  }
+});
 ```
 
+**Important**: Credentials are passed programmatically - the SDK itself doesn't read from environment variables. How you store and retrieve credentials in your application is up to you.
+
 ## Adapter Examples
 
 Complete adapter examples are available in the `examples/` directory:
@@ -498,7 +493,7 @@ import type {
 
 ## Contributing
 
-Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/TheJazzDev/dpd-local-sdk).
 
 ## License
 
@@ -507,8 +502,8 @@ MIT © [Taiow Babarinde](https://github.com/TheJazzDev)
 ## Support
 
 - 📧 Email: babsman4all@gmail.com
-- 🐛 Issues: [GitHub Issues](https://github.com/TheJazzDev/dpd-local-sdk.git/issues)
+- 🐛 Issues: [GitHub Issues](https://github.com/TheJazzDev/dpd-local-sdk/issues)
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for release history.
+See [CHANGELOG.md](https://github.com/TheJazzDev/dpd-local-sdk/blob/main/CHANGELOG.md) for release history.

package/dist/index.d.mts

@@ -316,6 +316,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 +426,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>;
@@ -452,30 +487,6 @@ declare const _default: {
     getAuthStatus: typeof getAuthStatus;
 };
 
-declare function generateEncryptionKey(): string;
-declare function encrypt(text: string): string;
-declare function decrypt(encryptedHex: string): string;
-declare function encryptCredentials(credentials: {
-    accountNumber: string;
-    username: string;
-    password: string;
-}): {
-    accountNumber: string;
-    username: string;
-    passwordHash: string;
-};
-declare function decryptCredentials(encryptedCredentials: {
-    accountNumber: string;
-    username: string;
-    passwordHash: string;
-}): {
-    accountNumber: string;
-    username: string;
-    password: string;
-};
-declare function hash(data: string): string;
-declare function verifyHash(data: string, hashToVerify: string): boolean;
-
 interface LoggerConfig {
     enabled: boolean;
     logToConsole: boolean;
@@ -522,4 +533,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, decrypt, decryptCredentials, deleteSavedAddress, encrypt, encryptCredentials, generateAndUploadLabel, generateConsignmentRef, generateEncryptionKey, generateLabel, getAuthStatus, getEstimatedDeliveryDate, getGeoSession, getLabelUrl, getNextCollectionDate, getSavedAddress, getSavedAddresses, getServiceDescription, getServiceName, getTokenExpiry, getTrackingUrl, hasValidToken, hash, isValidServiceCode, logOperation, loggedOperation, meetsMinimumOrderValue, qualifiesForFreeDelivery, regenerateLabel, saveAddress, setLoggerAdapter, startTimer, testConnection, testDPDConnection, trackShipment, updateSavedAddress, validateAddress, validateDeliveryAddress, validateServiceCode, verifyHash };
+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

@@ -316,6 +316,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 +426,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>;
@@ -452,30 +487,6 @@ declare const _default: {
     getAuthStatus: typeof getAuthStatus;
 };
 
-declare function generateEncryptionKey(): string;
-declare function encrypt(text: string): string;
-declare function decrypt(encryptedHex: string): string;
-declare function encryptCredentials(credentials: {
-    accountNumber: string;
-    username: string;
-    password: string;
-}): {
-    accountNumber: string;
-    username: string;
-    passwordHash: string;
-};
-declare function decryptCredentials(encryptedCredentials: {
-    accountNumber: string;
-    username: string;
-    passwordHash: string;
-}): {
-    accountNumber: string;
-    username: string;
-    password: string;
-};
-declare function hash(data: string): string;
-declare function verifyHash(data: string, hashToVerify: string): boolean;
-
 interface LoggerConfig {
     enabled: boolean;
     logToConsole: boolean;
@@ -522,4 +533,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, decrypt, decryptCredentials, deleteSavedAddress, encrypt, encryptCredentials, generateAndUploadLabel, generateConsignmentRef, generateEncryptionKey, generateLabel, getAuthStatus, getEstimatedDeliveryDate, getGeoSession, getLabelUrl, getNextCollectionDate, getSavedAddress, getSavedAddresses, getServiceDescription, getServiceName, getTokenExpiry, getTrackingUrl, hasValidToken, hash, isValidServiceCode, logOperation, loggedOperation, meetsMinimumOrderValue, qualifiesForFreeDelivery, regenerateLabel, saveAddress, setLoggerAdapter, startTimer, testConnection, testDPDConnection, trackShipment, updateSavedAddress, validateAddress, validateDeliveryAddress, validateServiceCode, verifyHash };
+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

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,14 +15,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -32,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,
@@ -44,14 +36,9 @@ __export(index_exports, {
   createCompleteShipment: () => createCompleteShipment,
   createDPDConfig: () => createDPDConfig,
   createShipment: () => createShipment,
-  decrypt: () => decrypt,
-  decryptCredentials: () => decryptCredentials,
   deleteSavedAddress: () => deleteSavedAddress,
-  encrypt: () => encrypt,
-  encryptCredentials: () => encryptCredentials,
   generateAndUploadLabel: () => generateAndUploadLabel,
   generateConsignmentRef: () => generateConsignmentRef,
-  generateEncryptionKey: () => generateEncryptionKey,
   generateLabel: () => generateLabel,
   getAuthStatus: () => getAuthStatus,
   getEstimatedDeliveryDate: () => getEstimatedDeliveryDate,
@@ -65,7 +52,6 @@ __export(index_exports, {
   getTokenExpiry: () => getTokenExpiry,
   getTrackingUrl: () => getTrackingUrl,
   hasValidToken: () => hasValidToken,
-  hash: () => hash,
   isValidServiceCode: () => isValidServiceCode,
   logOperation: () => logOperation,
   loggedOperation: () => loggedOperation,
@@ -81,11 +67,32 @@ __export(index_exports, {
   updateSavedAddress: () => updateSavedAddress,
   validateAddress: () => validateAddress,
   validateDeliveryAddress: () => validateDeliveryAddress,
-  validateServiceCode: () => validateServiceCode,
-  verifyHash: () => verifyHash
+  validateServiceCode: () => validateServiceCode
 });
 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",
@@ -438,6 +445,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) {
@@ -923,97 +1088,6 @@ var dpd_service_default = {
   getAuthStatus
 };
 
-// src/utils/encryption.ts
-var import_crypto = __toESM(require("crypto"));
-var ALGORITHM = "aes-256-gcm";
-var KEY_LENGTH = 32;
-var IV_LENGTH = 16;
-var SALT_LENGTH = 64;
-var TAG_LENGTH = 16;
-var TAG_POSITION = SALT_LENGTH + IV_LENGTH;
-var ENCRYPTED_POSITION = TAG_POSITION + TAG_LENGTH;
-function getEncryptionKey() {
-  const envKey = process.env.DPD_ENCRYPTION_KEY;
-  if (envKey) {
-    return Buffer.from(envKey, "hex");
-  }
-  if (process.env.NODE_ENV !== "production") {
-    console.warn(
-      "\u26A0\uFE0F  Using default encryption key. Set DPD_ENCRYPTION_KEY in production!"
-    );
-    return import_crypto.default.scryptSync("dpd-dev-key", "salt", KEY_LENGTH);
-  }
-  throw new Error(
-    "DPD_ENCRYPTION_KEY environment variable is required in production"
-  );
-}
-function generateEncryptionKey() {
-  const key = import_crypto.default.randomBytes(KEY_LENGTH);
-  return key.toString("hex");
-}
-function encrypt(text) {
-  try {
-    const salt = import_crypto.default.randomBytes(SALT_LENGTH);
-    const iv = import_crypto.default.randomBytes(IV_LENGTH);
-    const key = import_crypto.default.scryptSync(getEncryptionKey(), salt, KEY_LENGTH);
-    const cipher = import_crypto.default.createCipheriv(ALGORITHM, key, iv);
-    const encrypted = Buffer.concat([
-      cipher.update(text, "utf8"),
-      cipher.final()
-    ]);
-    const tag = cipher.getAuthTag();
-    const result = Buffer.concat([salt, iv, tag, encrypted]);
-    return result.toString("hex");
-  } catch (error) {
-    console.error("Encryption error:", error);
-    throw new Error("Failed to encrypt data");
-  }
-}
-function decrypt(encryptedHex) {
-  try {
-    const data = Buffer.from(encryptedHex, "hex");
-    const salt = data.subarray(0, SALT_LENGTH);
-    const iv = data.subarray(SALT_LENGTH, TAG_POSITION);
-    const tag = data.subarray(TAG_POSITION, ENCRYPTED_POSITION);
-    const encrypted = data.subarray(ENCRYPTED_POSITION);
-    const key = import_crypto.default.scryptSync(getEncryptionKey(), salt, KEY_LENGTH);
-    const decipher = import_crypto.default.createDecipheriv(ALGORITHM, key, iv);
-    decipher.setAuthTag(tag);
-    const decrypted = Buffer.concat([
-      decipher.update(encrypted),
-      decipher.final()
-    ]);
-    return decrypted.toString("utf8");
-  } catch (error) {
-    console.error("Decryption error:", error);
-    throw new Error("Failed to decrypt data");
-  }
-}
-function encryptCredentials(credentials) {
-  return {
-    accountNumber: credentials.accountNumber,
-    username: credentials.username,
-    passwordHash: encrypt(credentials.password)
-  };
-}
-function decryptCredentials(encryptedCredentials) {
-  return {
-    accountNumber: encryptedCredentials.accountNumber,
-    username: encryptedCredentials.username,
-    password: decrypt(encryptedCredentials.passwordHash)
-  };
-}
-function hash(data) {
-  return import_crypto.default.createHash("sha256").update(data).digest("hex");
-}
-function verifyHash(data, hashToVerify) {
-  const computed = hash(data);
-  return import_crypto.default.timingSafeEqual(
-    Buffer.from(computed),
-    Buffer.from(hashToVerify)
-  );
-}
-
 // src/utils/logger.ts
 var defaultConfig = {
   enabled: true,
@@ -1181,6 +1255,8 @@ function logToConsole(logData) {
 0 && (module.exports = {
   DPDService,
   DPD_API,
+  GeoSessionManager,
+  InMemoryGeoSessionStorage,
   SERVICE_DESCRIPTIONS,
   SERVICE_NAMES,
   authenticate,
@@ -1193,14 +1269,9 @@ function logToConsole(logData) {
   createCompleteShipment,
   createDPDConfig,
   createShipment,
-  decrypt,
-  decryptCredentials,
   deleteSavedAddress,
-  encrypt,
-  encryptCredentials,
   generateAndUploadLabel,
   generateConsignmentRef,
-  generateEncryptionKey,
   generateLabel,
   getAuthStatus,
   getEstimatedDeliveryDate,
@@ -1214,7 +1285,6 @@ function logToConsole(logData) {
   getTokenExpiry,
   getTrackingUrl,
   hasValidToken,
-  hash,
   isValidServiceCode,
   logOperation,
   loggedOperation,
@@ -1230,8 +1300,7 @@ function logToConsole(logData) {
   updateSavedAddress,
   validateAddress,
   validateDeliveryAddress,
-  validateServiceCode,
-  verifyHash
+  validateServiceCode
 });
 /**
  * DPD Local SDK
@@ -1240,7 +1309,7 @@ function logToConsole(logData) {
  * Database-agnostic and framework-independent
  *
  * @package @jazzdev/dpd-local-sdk
- * @version 1.0.0
- * @author Your Name
+ * @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",
@@ -350,6 +372,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) {
@@ -835,97 +1015,6 @@ var dpd_service_default = {
   getAuthStatus
 };
 
-// src/utils/encryption.ts
-import crypto from "crypto";
-var ALGORITHM = "aes-256-gcm";
-var KEY_LENGTH = 32;
-var IV_LENGTH = 16;
-var SALT_LENGTH = 64;
-var TAG_LENGTH = 16;
-var TAG_POSITION = SALT_LENGTH + IV_LENGTH;
-var ENCRYPTED_POSITION = TAG_POSITION + TAG_LENGTH;
-function getEncryptionKey() {
-  const envKey = process.env.DPD_ENCRYPTION_KEY;
-  if (envKey) {
-    return Buffer.from(envKey, "hex");
-  }
-  if (process.env.NODE_ENV !== "production") {
-    console.warn(
-      "\u26A0\uFE0F  Using default encryption key. Set DPD_ENCRYPTION_KEY in production!"
-    );
-    return crypto.scryptSync("dpd-dev-key", "salt", KEY_LENGTH);
-  }
-  throw new Error(
-    "DPD_ENCRYPTION_KEY environment variable is required in production"
-  );
-}
-function generateEncryptionKey() {
-  const key = crypto.randomBytes(KEY_LENGTH);
-  return key.toString("hex");
-}
-function encrypt(text) {
-  try {
-    const salt = crypto.randomBytes(SALT_LENGTH);
-    const iv = crypto.randomBytes(IV_LENGTH);
-    const key = crypto.scryptSync(getEncryptionKey(), salt, KEY_LENGTH);
-    const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
-    const encrypted = Buffer.concat([
-      cipher.update(text, "utf8"),
-      cipher.final()
-    ]);
-    const tag = cipher.getAuthTag();
-    const result = Buffer.concat([salt, iv, tag, encrypted]);
-    return result.toString("hex");
-  } catch (error) {
-    console.error("Encryption error:", error);
-    throw new Error("Failed to encrypt data");
-  }
-}
-function decrypt(encryptedHex) {
-  try {
-    const data = Buffer.from(encryptedHex, "hex");
-    const salt = data.subarray(0, SALT_LENGTH);
-    const iv = data.subarray(SALT_LENGTH, TAG_POSITION);
-    const tag = data.subarray(TAG_POSITION, ENCRYPTED_POSITION);
-    const encrypted = data.subarray(ENCRYPTED_POSITION);
-    const key = crypto.scryptSync(getEncryptionKey(), salt, KEY_LENGTH);
-    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
-    decipher.setAuthTag(tag);
-    const decrypted = Buffer.concat([
-      decipher.update(encrypted),
-      decipher.final()
-    ]);
-    return decrypted.toString("utf8");
-  } catch (error) {
-    console.error("Decryption error:", error);
-    throw new Error("Failed to decrypt data");
-  }
-}
-function encryptCredentials(credentials) {
-  return {
-    accountNumber: credentials.accountNumber,
-    username: credentials.username,
-    passwordHash: encrypt(credentials.password)
-  };
-}
-function decryptCredentials(encryptedCredentials) {
-  return {
-    accountNumber: encryptedCredentials.accountNumber,
-    username: encryptedCredentials.username,
-    password: decrypt(encryptedCredentials.passwordHash)
-  };
-}
-function hash(data) {
-  return crypto.createHash("sha256").update(data).digest("hex");
-}
-function verifyHash(data, hashToVerify) {
-  const computed = hash(data);
-  return crypto.timingSafeEqual(
-    Buffer.from(computed),
-    Buffer.from(hashToVerify)
-  );
-}
-
 // src/utils/logger.ts
 var defaultConfig = {
   enabled: true,
@@ -1092,6 +1181,8 @@ function logToConsole(logData) {
 export {
   dpd_service_default as DPDService,
   DPD_API,
+  GeoSessionManager,
+  InMemoryGeoSessionStorage,
   SERVICE_DESCRIPTIONS,
   SERVICE_NAMES,
   authenticate,
@@ -1104,14 +1195,9 @@ export {
   createCompleteShipment,
   createDPDConfig,
   createShipment,
-  decrypt,
-  decryptCredentials,
   deleteSavedAddress,
-  encrypt,
-  encryptCredentials,
   generateAndUploadLabel,
   generateConsignmentRef,
-  generateEncryptionKey,
   generateLabel,
   getAuthStatus,
   getEstimatedDeliveryDate,
@@ -1125,7 +1211,6 @@ export {
   getTokenExpiry,
   getTrackingUrl,
   hasValidToken,
-  hash,
   isValidServiceCode,
   logOperation,
   loggedOperation,
@@ -1141,8 +1226,7 @@ export {
   updateSavedAddress,
   validateAddress,
   validateDeliveryAddress,
-  validateServiceCode,
-  verifyHash
+  validateServiceCode
 };
 /**
  * DPD Local SDK
@@ -1151,7 +1235,7 @@ export {
  * Database-agnostic and framework-independent
  *
  * @package @jazzdev/dpd-local-sdk
- * @version 1.0.0
- * @author Your Name
+ * @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.12",
+  "version": "1.1.0",
   "description": "TypeScript SDK for DPD Local shipping API integration - database-agnostic and framework-independent",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -15,8 +15,7 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
@@ -43,12 +42,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/TheJazzDev/dpd-local-sdk.git"
+    "url": "https://github.com/TheJazzDev/dpd-local-sdk"
   },
   "bugs": {
-    "url": "https://github.com/TheJazzDev/dpd-local-sdk.git/issues"
+    "url": "https://github.com/TheJazzDev/dpd-local-sdk/issues"
   },
-  "homepage": "https://github.com/TheJazzDev/dpd-local-sdk.git#readme",
+  "homepage": "https://github.com/TheJazzDev/dpd-local-sdk#readme",
   "devDependencies": {
     "@types/node": "^20.0.0",
     "dotenv": "^17.2.3",

package/CHANGELOG.md

@@ -1,38 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.0.0] - 2024-01-04
-
-### Added
-- Initial release of DPD Local SDK
-- Complete DPD API integration (authentication, shipments, labels, tracking)
-- Database-agnostic adapter pattern
-- TypeScript-first design with full type definitions
-- Address validation using postcodes.io API
-- Automatic token management and caching
-- Request retry logic with exponential backoff
-- Comprehensive error handling
-- Detailed logging system
-- Encryption utilities for sensitive data
-- Configuration factory function
-- Helper functions for pricing, dates, and tracking
-- Example adapters for Firestore and Firebase Storage
-- Complete documentation and usage examples
-
-### Features
-- ✅ Create shipments with DPD
-- ✅ Generate and upload shipping labels (thermal/A4)
-- ✅ Validate UK delivery addresses
-- ✅ Save and manage customer addresses
-- ✅ Calculate shipping costs and delivery fees
-- ✅ Track shipments
-- ✅ Multi-parcel support
-- ✅ Service selection (Next Day, By 12 PM)
-- ✅ Customer notifications (email, SMS via DPD)
-- ✅ Comprehensive logging and audit trail
-
-[1.0.0]: https://github.com/your-org/dpd-local-sdk/releases/tag/v1.0.0