@jazzdev/dpd-local-sdk 1.0.10 → 1.0.12

package/README.md

@@ -201,6 +201,9 @@ const result = await createCompleteShipment(
 
 if (result.success) {
   console.log('Shipment created!');
+  console.log('Shipment ID:', result.shipmentId); // Save this for label regeneration
+  console.log('Consignment Number:', result.consignmentNumber); // 10-digit reference
+  console.log('Parcel Number:', result.parcelNumber); // 14-digit tracking number
   console.log('Tracking URL:', result.trackingUrl);
   console.log('Label URL:', result.labelUrl);
 } else {
@@ -208,6 +211,71 @@ if (result.success) {
 }
 ```
 
+## Understanding DPD Identifiers
+
+When you create a shipment with DPD, you receive three different identifiers:
+
+1. **shipmentId** - DPD's internal shipment identifier (numeric)
+   - Required for label regeneration
+   - Save this in your database!
+
+2. **consignmentNumber** - 10-digit reference number (e.g., `6504286395`)
+   - Used for internal tracking
+
+3. **parcelNumber** - 14-digit tracking number (e.g., `15976504286395`)
+   - What customers use to track their delivery
+   - Used in the tracking URL
+
+```typescript
+// When creating a shipment, save ALL identifiers:
+const result = await createCompleteShipment(...);
+
+if (result.success) {
+  await saveToDatabase({
+    shipmentId: result.shipmentId,           // Save for label regeneration
+    consignmentNumber: result.consignmentNumber,
+    parcelNumber: result.parcelNumber,       // Give to customer for tracking
+    trackingUrl: result.trackingUrl,
+  });
+}
+```
+
+### Regenerating Labels
+
+If you need to regenerate a label (e.g., printer jam), use the `shipmentId`:
+
+```typescript
+import { generateLabel } from '@jazzdev/dpd-local-sdk';
+
+const result = await generateLabel(credentials, {
+  shipmentId: '12345678',  // Use the shipmentId, not consignment/parcel number
+  labelFormat: 'zpl'       // or 'clp', 'html'
+});
+```
+
+### Testing Label Generation
+
+A test script is included to verify label generation:
+
+```bash
+# Using npm script
+npm run test:label <shipmentId> [format]
+
+# Or directly with tsx
+npx tsx test-label-generation.ts <shipmentId> [format]
+
+# Examples
+npm run test:label 12345678
+npm run test:label 12345678 html
+npm run test:label 12345678 zpl
+```
+
+The script will:
+- Validate your DPD credentials
+- Generate the label in the specified format
+- Save it to a file (`label-<shipmentId>.<format>`)
+- Display a preview of the label content
+
 ## API Reference
 
 ### Configuration
@@ -379,11 +447,12 @@ console.log('DPD_ENCRYPTION_KEY=' + key);
 
 Complete adapter examples are available in the `examples/` directory:
 
-- `examples/firestore-adapter.ts` - Firestore implementation
-- `examples/mongodb-adapter.ts` - MongoDB implementation
-- `examples/postgresql-adapter.ts` - PostgreSQL implementation
-- `examples/firebase-storage-adapter.ts` - Firebase Storage implementation
-- `examples/s3-storage-adapter.ts` - AWS S3 implementation
+- `examples/basic-usage.ts` - Complete workflow example
+- `examples/regenerate-label.ts` - Label regeneration example
+- `examples/firestore-adapter.ts` - Firestore database adapter
+- `examples/firebase-storage-adapter.ts` - Firebase Storage adapter
+
+For other databases (MongoDB, PostgreSQL, etc.), implement the `DatabaseAdapter` interface following the Firestore example as a reference. The adapter pattern is database-agnostic by design.
 
 ## Error Handling
 

package/dist/index.js

@@ -336,9 +336,13 @@ async function authenticatedRequest(credentials, options) {
             let errorMessage = "Label generation failed";
             let errorCode = "UNKNOWN";
             if (errorObj) {
-              if (errorObj.errorMessage) {
+              if (Array.isArray(errorObj)) {
+                const firstError = errorObj[0];
+                errorMessage = firstError?.errorMessage || errorMessage;
+                errorCode = firstError?.errorCode || errorCode;
+              } else if (errorObj.errorMessage) {
                 errorMessage = errorObj.errorMessage;
-                errorCode = errorObj.errorCode || errorObj.name || "UNKNOWN";
+                errorCode = errorObj.errorCode || errorObj.name || errorCode;
               } else if (errorObj.name) {
                 errorMessage = errorObj.name;
                 errorCode = errorObj.name;
@@ -563,12 +567,7 @@ async function createShipment(credentials, params, businessConfig) {
 async function generateLabel(credentials, params) {
   try {
     const { shipmentId, labelFormat } = params;
-    console.log("\n\u{1F3F7}\uFE0F [SDK generateLabel] Starting label generation");
-    console.log(`   Shipment ID: ${shipmentId} (type: ${typeof shipmentId})`);
-    console.log(`   Format: ${labelFormat}`);
-    console.log(`   Accept Header: ${getAcceptHeader(labelFormat)}`);
     const endpoint = `${DPD_API.ENDPOINTS.LABEL}/${shipmentId}/label/`;
-    console.log(`   Endpoint: ${endpoint}`);
     const response = await authenticatedRequest(credentials, {
       method: "GET",
       endpoint,
@@ -576,35 +575,17 @@ async function generateLabel(credentials, params) {
         Accept: getAcceptHeader(labelFormat)
       }
     });
-    console.log("\u{1F4E6} [SDK generateLabel] Raw response type:", typeof response);
-    console.log(
-      "\u{1F4E6} [SDK generateLabel] Raw response:",
-      typeof response === "string" ? `String (${response.length} chars): ${response.substring(0, 200)}...` : response
-    );
-    if (typeof response === "object" && response.error) {
-      const errorObj = response.error;
-      console.error("\u274C [SDK generateLabel] DPD returned error object:", errorObj);
-      const errorMessage = errorObj.errorMessage || errorObj.name || JSON.stringify(errorObj);
-      return {
-        success: false,
-        error: `DPD API error: ${errorMessage}`
-      };
-    }
-    if (!response || typeof response === "object" && !response.data) {
-      console.error("\u274C [SDK generateLabel] No label data in response");
+    if (!response || typeof response !== "string") {
       return {
         success: false,
         error: "No label data received from DPD"
       };
     }
-    const labelData = typeof response === "string" ? response : response.data;
-    console.log(`\u2705 [SDK generateLabel] Success! Label data length: ${labelData.length} chars`);
     return {
       success: true,
-      labelData
+      labelData: response
     };
   } catch (error) {
-    console.error("\u{1F4A5} [SDK generateLabel] Exception:", error);
     return {
       success: false,
       error: error instanceof Error ? error.message : "Unknown error"
@@ -749,7 +730,7 @@ async function createCompleteShipment(orderId, params, config2, dbAdapter, stora
     }
     const labelResult = await generateAndUploadLabel(
       shipmentResult.shipmentId,
-      "zpl",
+      config2.labels.format,
       config2.credentials,
       storageAdapter
     );

package/dist/index.mjs

@@ -248,9 +248,13 @@ async function authenticatedRequest(credentials, options) {
             let errorMessage = "Label generation failed";
             let errorCode = "UNKNOWN";
             if (errorObj) {
-              if (errorObj.errorMessage) {
+              if (Array.isArray(errorObj)) {
+                const firstError = errorObj[0];
+                errorMessage = firstError?.errorMessage || errorMessage;
+                errorCode = firstError?.errorCode || errorCode;
+              } else if (errorObj.errorMessage) {
                 errorMessage = errorObj.errorMessage;
-                errorCode = errorObj.errorCode || errorObj.name || "UNKNOWN";
+                errorCode = errorObj.errorCode || errorObj.name || errorCode;
               } else if (errorObj.name) {
                 errorMessage = errorObj.name;
                 errorCode = errorObj.name;
@@ -475,12 +479,7 @@ async function createShipment(credentials, params, businessConfig) {
 async function generateLabel(credentials, params) {
   try {
     const { shipmentId, labelFormat } = params;
-    console.log("\n\u{1F3F7}\uFE0F [SDK generateLabel] Starting label generation");
-    console.log(`   Shipment ID: ${shipmentId} (type: ${typeof shipmentId})`);
-    console.log(`   Format: ${labelFormat}`);
-    console.log(`   Accept Header: ${getAcceptHeader(labelFormat)}`);
     const endpoint = `${DPD_API.ENDPOINTS.LABEL}/${shipmentId}/label/`;
-    console.log(`   Endpoint: ${endpoint}`);
     const response = await authenticatedRequest(credentials, {
       method: "GET",
       endpoint,
@@ -488,35 +487,17 @@ async function generateLabel(credentials, params) {
         Accept: getAcceptHeader(labelFormat)
       }
     });
-    console.log("\u{1F4E6} [SDK generateLabel] Raw response type:", typeof response);
-    console.log(
-      "\u{1F4E6} [SDK generateLabel] Raw response:",
-      typeof response === "string" ? `String (${response.length} chars): ${response.substring(0, 200)}...` : response
-    );
-    if (typeof response === "object" && response.error) {
-      const errorObj = response.error;
-      console.error("\u274C [SDK generateLabel] DPD returned error object:", errorObj);
-      const errorMessage = errorObj.errorMessage || errorObj.name || JSON.stringify(errorObj);
-      return {
-        success: false,
-        error: `DPD API error: ${errorMessage}`
-      };
-    }
-    if (!response || typeof response === "object" && !response.data) {
-      console.error("\u274C [SDK generateLabel] No label data in response");
+    if (!response || typeof response !== "string") {
       return {
         success: false,
         error: "No label data received from DPD"
       };
     }
-    const labelData = typeof response === "string" ? response : response.data;
-    console.log(`\u2705 [SDK generateLabel] Success! Label data length: ${labelData.length} chars`);
     return {
       success: true,
-      labelData
+      labelData: response
     };
   } catch (error) {
-    console.error("\u{1F4A5} [SDK generateLabel] Exception:", error);
     return {
       success: false,
       error: error instanceof Error ? error.message : "Unknown error"
@@ -661,7 +642,7 @@ async function createCompleteShipment(orderId, params, config2, dbAdapter, stora
     }
     const labelResult = await generateAndUploadLabel(
       shipmentResult.shipmentId,
-      "zpl",
+      config2.labels.format,
       config2.credentials,
       storageAdapter
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jazzdev/dpd-local-sdk",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "TypeScript SDK for DPD Local shipping API integration - database-agnostic and framework-independent",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -22,7 +22,8 @@
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test:label": "tsx test-label-generation.ts"
   },
   "keywords": [
     "dpd",