@jazzdev/dpd-local-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,525 @@
+type TimestampType = Date | {
+    toDate(): Date;
+} | string;
+interface DPDModuleConfig {
+    credentials: DPDCredentials;
+    business: BusinessConfig;
+    services: ServiceConfig;
+    pricing: PricingConfig;
+    labels: LabelConfig;
+    notifications: NotificationConfig;
+    testMode: boolean;
+}
+interface DPDCredentials {
+    accountNumber: string;
+    username: string;
+    password: string;
+    geoSession?: string;
+    geoSessionExpiry?: Date;
+}
+interface BusinessConfig {
+    name: string;
+    collectionAddress: {
+        organisation: string;
+        property: string;
+        street: string;
+        locality: string;
+        town: string;
+        county: string;
+        postcode: string;
+        countryCode: string;
+    };
+    contactName: string;
+    contactPhone: string;
+    contactEmail: string;
+}
+interface ServiceConfig {
+    enabled: DPDServiceCode[];
+    default: DPDServiceCode;
+}
+interface PricingConfig {
+    freeDeliveryThreshold: number;
+    flatDeliveryFee: number;
+    minimumOrderValue: number;
+    services: {
+        [key in DPDServiceCode]?: {
+            basePrice: number;
+            perKgPrice: number;
+            customerPrice: number;
+        };
+    };
+}
+interface LabelConfig {
+    format: "thermal" | "a4";
+    printer: {
+        model: string;
+        dpi: number;
+        speed: number;
+        connection: "USB" | "Network";
+    };
+}
+interface NotificationConfig {
+    email: {
+        enabled: boolean;
+        provider: "resend" | "sendgrid" | "ses";
+        fromEmail: string;
+        adminEmail: string;
+    };
+    sms: {
+        enabled: boolean;
+        provider: "dpd";
+    };
+}
+type DPDServiceCode = "12" | "07";
+interface DPDAuthResponse {
+    data: {
+        geoSession: string;
+    };
+}
+interface DPDAddress {
+    organisation: string;
+    property: string;
+    street: string;
+    locality: string;
+    town: string;
+    county: string;
+    postcode: string;
+    countryCode: string;
+}
+interface DPDContact {
+    name: string;
+    telephone: string;
+    email?: string;
+}
+interface DPDParcel {
+    weight: number;
+    width?: number;
+    height?: number;
+    depth?: number;
+}
+interface DPDShipmentRequest {
+    jobId: string | null;
+    collectionOnDelivery: boolean;
+    invoice: null;
+    collectionDate: string;
+    consolidate: boolean;
+    consignment: DPDConsignment[];
+}
+interface DPDConsignment {
+    consignmentNumber: string | null;
+    consignmentRef: string;
+    parcel: DPDParcel[];
+    collectionDetails: {
+        address: DPDAddress;
+        contactDetails: DPDContact;
+    };
+    deliveryDetails: {
+        address: DPDAddress;
+        contactDetails: DPDContact;
+        notificationDetails: {
+            email?: string;
+            mobile?: string;
+        };
+    };
+    networkCode: DPDServiceCode;
+    numberOfParcels: number;
+    totalWeight: number;
+    shippingRef1: string;
+    shippingRef2?: string;
+    shippingRef3?: string;
+    deliveryInstructions?: string;
+    liabilityValue?: number;
+    liability?: boolean;
+}
+interface DPDShipmentResponse {
+    data?: {
+        shipmentId: number | string;
+        consolidated: boolean;
+        consignmentDetail?: Array<{
+            consignmentNumber: string;
+            parcelNumbers: string[];
+        }>;
+        consignment?: Array<{
+            consignmentNumber: string;
+        }>;
+    };
+    error?: DPDError | null;
+}
+interface DPDLabelRequest {
+    consignment: {
+        consignmentNumber: string;
+    };
+}
+interface DPDLabelResponse {
+    data: string;
+    error?: DPDError;
+}
+interface DPDError {
+    errorCode: string;
+    errorMessage: string;
+    obj: string;
+    errorType: string;
+}
+interface ShippingData {
+    provider: "dpd";
+    service: DPDServiceCode;
+    shipmentId: string | number;
+    consignmentNumber: string;
+    parcelNumber: string;
+    trackingUrl: string;
+    labelUrl: string;
+    status: ShipmentStatus;
+    statusHistory: ShipmentStatusUpdate[];
+    cost: {
+        basePrice: number;
+        weightCharge: number;
+        totalCost: number;
+        customerCharge: number;
+    };
+    weight: {
+        total: number;
+        unit: "kg";
+    };
+    parcels: number;
+    collectionDate: string;
+    estimatedDelivery: string;
+    actualDelivery?: string;
+    createdAt: TimestampType;
+    updatedAt: TimestampType;
+}
+type ShipmentStatus = "created" | "label_generated" | "collected" | "in_transit" | "out_for_delivery" | "delivered" | "failed" | "cancelled";
+interface ShipmentStatusUpdate {
+    status: ShipmentStatus;
+    timestamp: TimestampType;
+    message?: string;
+    location?: string;
+}
+interface SavedAddress {
+    id: string;
+    userId: string;
+    isDefault: boolean;
+    label?: string;
+    organisation?: string;
+    property: string;
+    street: string;
+    locality?: string;
+    town: string;
+    county?: string;
+    postcode: string;
+    countryCode: string;
+    contactName: string;
+    contactPhone: string;
+    validated: boolean;
+    validatedAt?: TimestampType;
+    createdAt: TimestampType;
+    updatedAt: TimestampType;
+}
+interface DPDLogDocument {
+    id: string;
+    orderId: string;
+    consignmentNumber?: string;
+    operation: "auth" | "validate_address" | "create_shipment" | "generate_label" | "track_shipment" | "webhook";
+    request: {
+        endpoint: string;
+        method: string;
+        headers?: Record<string, string>;
+        body?: any;
+    };
+    response: {
+        status: number;
+        headers?: Record<string, string>;
+        body?: any;
+    };
+    duration: number;
+    success: boolean;
+    error?: {
+        code: string;
+        message: string;
+        stack?: string;
+    };
+    createdAt: TimestampType;
+}
+interface CreateShipmentParams {
+    orderId: string;
+    orderRef: string;
+    service: DPDServiceCode;
+    deliveryAddress: SavedAddress;
+    totalWeight: number;
+    numberOfParcels: number;
+    customerEmail: string;
+    customerPhone?: string;
+    deliveryInstructions?: string;
+    collectionDate: string;
+}
+interface CreateShipmentResult {
+    success: boolean;
+    shipmentId?: string | number;
+    consignmentNumber?: string;
+    parcelNumber?: string;
+    trackingUrl?: string;
+    labelUrl?: string;
+    error?: string;
+    errorCode?: string;
+}
+interface GenerateLabelParams {
+    shipmentId: string | number;
+    format: "thermal" | "a4";
+}
+interface GenerateLabelResult {
+    success: boolean;
+    labelUrl?: string;
+    labelData?: string;
+    error?: string;
+}
+interface ValidateAddressParams {
+    postcode: string;
+    town: string;
+}
+interface ValidateAddressResult {
+    valid: boolean;
+    serviceable: boolean;
+    message?: string;
+}
+interface TrackShipmentParams {
+    consignmentNumber: string;
+}
+interface TrackShipmentResult {
+    success: boolean;
+    status?: ShipmentStatus;
+    statusHistory?: ShipmentStatusUpdate[];
+    estimatedDelivery?: string;
+    actualDelivery?: string;
+    error?: string;
+}
+interface DatabaseAdapter {
+    getOrder(orderId: string): Promise<any>;
+    updateOrder(orderId: string, data: any): Promise<void>;
+    getSavedAddresses(userId: string): Promise<SavedAddress[]>;
+    getSavedAddress(addressId: string): Promise<SavedAddress | null>;
+    createSavedAddress(address: Omit<SavedAddress, "id">): Promise<string>;
+    updateSavedAddress(addressId: string, data: Partial<SavedAddress>): Promise<void>;
+    deleteSavedAddress(addressId: string): Promise<void>;
+    createDPDLog(log: Omit<DPDLogDocument, "id">): Promise<string>;
+    getDPDLogs(filters: LogFilters): Promise<DPDLogDocument[]>;
+}
+interface StorageAdapter {
+    uploadLabel(labelData: string, fileName: string): Promise<string>;
+    getLabel(fileName: string): Promise<string>;
+    deleteLabel(fileName: string): Promise<void>;
+}
+interface LogFilters {
+    orderId?: string;
+    consignmentNumber?: string;
+    operation?: DPDLogDocument["operation"];
+    success?: boolean;
+    startDate?: Date;
+    endDate?: Date;
+    limit?: number;
+}
+
+declare const DPD_API: {
+    readonly BASE_URL: "https://api.dpdlocal.co.uk";
+    readonly ENDPOINTS: {
+        readonly AUTH: "/user/?action=login";
+        readonly SHIPMENT: "/shipping/shipment";
+        readonly LABEL: "/shipping/shipment";
+        readonly TRACKING: "/shipping/network/";
+    };
+    readonly TIMEOUT: 30000;
+    readonly RETRY_ATTEMPTS: 3;
+    readonly RETRY_DELAY: 1000;
+};
+declare const SERVICE_NAMES: Record<DPDServiceCode, string>;
+declare const SERVICE_DESCRIPTIONS: Record<DPDServiceCode, string>;
+interface CreateDPDConfigOptions {
+    credentials: DPDCredentials;
+    business: BusinessConfig;
+    pricing?: {
+        freeDeliveryThreshold?: number;
+        flatDeliveryFee?: number;
+        minimumOrderValue?: number;
+        services?: {
+            "12"?: {
+                basePrice: number;
+                perKgPrice: number;
+                customerPrice: number;
+            };
+            "07"?: {
+                basePrice: number;
+                perKgPrice: number;
+                customerPrice: number;
+            };
+        };
+    };
+    services?: {
+        enabled?: DPDServiceCode[];
+        default?: DPDServiceCode;
+    };
+    labels?: {
+        format?: "thermal" | "a4";
+        printer?: {
+            model: string;
+            dpi: number;
+            speed: number;
+            connection: "USB" | "Network";
+        };
+    };
+    notifications?: {
+        email?: {
+            enabled: boolean;
+            provider: "resend" | "sendgrid" | "ses";
+            fromEmail: string;
+            adminEmail: string;
+        };
+        sms?: {
+            enabled: boolean;
+            provider: "dpd";
+        };
+    };
+    testMode?: boolean;
+}
+declare function createDPDConfig(options: CreateDPDConfigOptions): DPDModuleConfig;
+declare const calculateDeliveryFee: (subtotal: number, service: DPDServiceCode | undefined, config: DPDModuleConfig) => number;
+declare const calculateDPDCost: (weight: number, service: DPDServiceCode, config: DPDModuleConfig) => number;
+declare const qualifiesForFreeDelivery: (subtotal: number, config: DPDModuleConfig) => boolean;
+declare const meetsMinimumOrderValue: (subtotal: number, config: DPDModuleConfig) => boolean;
+declare const getNextCollectionDate: () => string;
+declare const getEstimatedDeliveryDate: (_service: DPDServiceCode, collectionDate?: string) => string;
+declare const getTrackingUrl: (parcelNumber: string) => string;
+declare const isValidServiceCode: (code: string, config: DPDModuleConfig) => code is DPDServiceCode;
+declare const getServiceName: (code: DPDServiceCode) => string;
+declare const getServiceDescription: (code: DPDServiceCode) => string;
+
+declare function authenticate(credentials: DPDCredentials): Promise<string>;
+declare function getGeoSession(credentials: DPDCredentials, forceRefresh?: boolean): Promise<string>;
+declare function clearGeoSession(): void;
+declare function hasValidToken(): boolean;
+declare function getTokenExpiry(): Date | null;
+interface DPDRequestOptions {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    endpoint: string;
+    body?: any;
+    headers?: Record<string, string>;
+    retry?: boolean;
+    retryAttempts?: number;
+}
+declare function authenticatedRequest<T = unknown>(credentials: DPDCredentials, options: DPDRequestOptions): Promise<T>;
+declare function testConnection(credentials: DPDCredentials): Promise<{
+    success: boolean;
+    message: string;
+}>;
+
+declare function createShipment(credentials: DPDCredentials, params: CreateShipmentParams, businessConfig: any): Promise<CreateShipmentResult>;
+declare function generateLabel(credentials: DPDCredentials, params: GenerateLabelParams): Promise<GenerateLabelResult>;
+declare function validateAddress(_credentials: DPDCredentials, params: ValidateAddressParams): Promise<ValidateAddressResult>;
+declare function trackShipment(credentials: DPDCredentials, params: TrackShipmentParams): Promise<TrackShipmentResult>;
+declare function calculateParcels(totalWeight: number): number;
+declare function validateServiceCode(code: string): code is DPDServiceCode;
+declare function generateConsignmentRef(orderId: string): string;
+
+declare function createCompleteShipment(orderId: string, params: Omit<CreateShipmentParams, "orderId">, config: DPDModuleConfig, dbAdapter: DatabaseAdapter, storageAdapter: StorageAdapter): Promise<CreateShipmentResult & {
+    labelUrl?: string;
+}>;
+declare function generateAndUploadLabel(shipmentId: string | number, consignmentNumber: string, format: "thermal" | "a4" | undefined, credentials: DPDCredentials, storageAdapter: StorageAdapter): Promise<GenerateLabelResult>;
+declare function validateDeliveryAddress(params: ValidateAddressParams, credentials: DPDCredentials): Promise<ValidateAddressResult>;
+declare function saveAddress(userId: string, address: Omit<SavedAddress, "id" | "userId" | "createdAt" | "updatedAt">, credentials: DPDCredentials, dbAdapter: DatabaseAdapter): Promise<string>;
+declare function getSavedAddresses(userId: string, dbAdapter: DatabaseAdapter): Promise<SavedAddress[]>;
+declare function getSavedAddress(addressId: string, dbAdapter: DatabaseAdapter): Promise<SavedAddress | null>;
+declare function updateSavedAddress(addressId: string, data: Partial<SavedAddress>, dbAdapter: DatabaseAdapter): Promise<void>;
+declare function deleteSavedAddress(addressId: string, dbAdapter: DatabaseAdapter): Promise<void>;
+declare function getLabelUrl(consignmentNumber: string, storageAdapter: StorageAdapter): Promise<string | null>;
+declare function regenerateLabel(shipmentId: string | number, consignmentNumber: string, format: "thermal" | "a4" | undefined, credentials: DPDCredentials, storageAdapter: StorageAdapter): Promise<GenerateLabelResult>;
+declare function testDPDConnection(credentials: DPDCredentials): Promise<{
+    success: boolean;
+    message: string;
+}>;
+declare function getAuthStatus(credentials: DPDCredentials): Promise<{
+    authenticated: boolean;
+    expiresAt?: Date | null;
+}>;
+declare const _default: {
+    createCompleteShipment: typeof createCompleteShipment;
+    generateAndUploadLabel: typeof generateAndUploadLabel;
+    validateDeliveryAddress: typeof validateDeliveryAddress;
+    saveAddress: typeof saveAddress;
+    getSavedAddresses: typeof getSavedAddresses;
+    getSavedAddress: typeof getSavedAddress;
+    updateSavedAddress: typeof updateSavedAddress;
+    deleteSavedAddress: typeof deleteSavedAddress;
+    getLabelUrl: typeof getLabelUrl;
+    regenerateLabel: typeof regenerateLabel;
+    testDPDConnection: typeof testDPDConnection;
+    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;
+    logToDatabase: boolean;
+    adapter?: DatabaseAdapter;
+}
+declare function configureLogger(newConfig: Partial<LoggerConfig>): void;
+declare function setLoggerAdapter(adapter: DatabaseAdapter): void;
+interface LogParams {
+    orderId: string;
+    consignmentNumber?: string;
+    operation: DPDLogDocument["operation"];
+    request: {
+        endpoint: string;
+        method: string;
+        headers?: Record<string, string>;
+        body?: any;
+    };
+    response: {
+        status: number;
+        headers?: Record<string, string>;
+        body?: any;
+    };
+    duration: number;
+    success: boolean;
+    error?: {
+        code: string;
+        message: string;
+        stack?: string;
+    };
+}
+declare function logOperation(params: LogParams): Promise<void>;
+declare function startTimer(): () => number;
+declare function loggedOperation<T>(params: {
+    orderId: string;
+    consignmentNumber?: string;
+    operation: DPDLogDocument["operation"];
+    endpoint: string;
+    method: string;
+    requestBody?: any;
+}, operation: () => Promise<{
+    data: T;
+    status: number;
+    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 };