// Actual response schema for POST /commerce/shipments/{shipmentNumber}/packages
{
  "packageId": "a1b2c3d4e5f6",
  "packagingType": "Custom",
  "measurements": {
    "weight": { "value": 5, "unit": "lbs" },
    "length": { "value": 12, "unit": "in" },
    "width": { "value": 10, "unit": "in" },
    "height": { "value": 8, "unit": "in" }
  },
  "items": [
    {
      "productCode": "SHIRT-BLUE-M",
      "quantity": 1
    }
  ]
}

// Actual error schema from Kibo
{
    "message": "The shipment is not in a valid state to create a package. Current status is 'Pending'.",
    "errorCode": "VALIDATION_ERROR",
    "correlationId": "e0b5b9b0-a5f1-4f1e-9a0c-12345abcdef"
}

// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance.
// 2. **API Client Instantiation**: Create a client for the Shipments API.
// 3. **Data Preparation**: Construct the request body for the new Package, detailing its contents and measurements.
// 4. **API Call**: Use the instantiated client to call the `newShipmentPackage` method.

// Essential imports for Shipment Package operations.
import { Configuration } from "@kibocommerce/rest-sdk";
import { ShipmentPackagesApi } from "@kibocommerce/rest-sdk/clients/Fulfillment";
import { Package } from "@kibocommerce/rest-sdk/models/Fulfillment";

const configuration = new Configuration({
    tenantId: process.env.KIBO_TENANT_ID,
    siteId: process.env.KIBO_SITE_ID,
    clientId: process.env.KIBO_CLIENT_ID,
    sharedSecret: process.env.KIBO_SHARED_SECRET,
    authHost: process.env.KIBO_AUTH_HOST,
});

// Complete working example that ACTUALLY WORKS with the Kibo API
// This function creates a new package for a given shipment.

async function createNewPackage(
    shipmentNumber: number,
    packageDetails: Package
): Promise<Package> {
    console.log(`Creating a new package for shipment ${shipmentNumber}...`);

    // 1. Instantiate a dedicated client for the Shipment Packages API.
    const shipmentPackagesApi = new ShipmentPackagesApi(configuration);

    // 2. The packageDetails object is our request payload.
    // It must match the schema defined in the Kibo API documentation.

    // 3. Call the method on the client.
    try {
        const newPackage = await shipmentPackagesApi.newPackage({
            shipmentNumber,
            packageDto: packageDetails,
        });
        console.log(`Success! Package with ID "${newPackage.packageId}" created.`);
        return newPackage;
    } catch (error) {
        console.error("API Error creating package:", JSON.stringify(error, null, 2));
        throw error;
    }
}

// Example usage:
// Assume shipment #10052 has one item: { productCode: 'TSHIRT-BLK-L', quantity: 2 }
// We are packing both items into one box.
// const newPackagePayload: ModelPackage = {
//     packagingType: "Custom",
//     measurements: {
//         weight: { value: 2.5, unit: "lbs" },
//         length: { value: 12, unit: "in" },
//         width: { value: 12, unit: "in" },
//         height: { value: 4, unit: "in" }
//     },
//     items: [
//         {
//             productCode: "TSHIRT-BLK-L",
//             quantity: 2
//         }
//     ]
// };
// createNewPackage(10052, newPackagePayload);

// This function updates an existing package. Note: PUT is a full replacement.
async function updatePackageDetails(
    shipmentNumber: number,
    packageId: string,
    updatedPackageDetails: Package
): Promise<Package> {
    const shipmentPackagesApi = new ShipmentPackagesApi(configuration);
    console.log(`Updating package ${packageId}...`);
    try {
        // As with other Kibo PUT operations, this performs a full replacement.
        // It's safest to GET the package first, modify it, then PUT it back.
        const updatedPackage = await shipmentPackagesApi.updatePackage({
            shipmentNumber,
            packageId,
            packageDto: updatedPackageDetails,
        });
        console.log("Package updated successfully.");
        return updatedPackage;
    } catch (error) {
        console.error("API Error updating package:", JSON.stringify(error, null, 2));
        throw error;
    }
}

// This function deletes a package from a shipment.
async function deletePackage(shipmentNumber: number, packageId: string): Promise<void> {
    const shipmentClient = new ShipmentApi(configuration);
    console.log(`Deleting package ${packageId}...`);
    try {
        // This call returns a 204 No Content on success.
        await shipmentClient.deleteShipmentPackage({
            shipmentNumber,
            packageId,
        });
        console.log("Package deleted successfully.");
    } catch (error) {
        console.error("API Error deleting package:", JSON.stringify(error, null, 2));
        throw error;
    }
}

async function splitShipmentIntoTwoPackages(shipmentNumber: number) {
    // Assume shipment #10053 has two items:
    const item1 = { productCode: 'MUG-01', quantity: 1 };
    const item2 = { productCode: 'BOOK-02', quantity: 1 };

    // Package 1: Just the mug
    const package1Payload: ModelPackage = {
        packagingType: "Custom",
        measurements: { weight: { value: 2, unit: "lbs" }, /*...dims...*/ },
        items: [item1]
    };
    const package1 = await createNewPackage(shipmentNumber, package1Payload);

    // Package 2: Just the book
    const package2Payload: ModelPackage = {
        packagingType: "Custom",
        measurements: { weight: { value: 3, unit: "lbs" }, /*...dims...*/ },
        items: [item2]
    };
    const package2 = await createNewPackage(shipmentNumber, package2Payload);

    console.log(`Shipment ${shipmentNumber} successfully split into two packages: ${package1.packageId} and ${package2.packageId}`);
}

interface KiboApiError {
  errorCode: string;      // Specific error codes from apidocs.kibocommerce.com
  message: string;          // Error description
  correlationId: string;  // For support tracking
}