npm install stateset-node
# or
# yarn add stateset-node

# Example for bash/zsh shells. Adapt for your environment (e.g., .env file).
export STATESET_API_KEY='your_api_key_here'

import { stateset } from 'stateset-node';

// Ensure the environment variable is loaded (e.g., using dotenv)
if (!process.env.STATESET_API_KEY) {
  throw new Error("STATESET_API_KEY environment variable is not set.");
}

// Initialize the client
const client = new stateset(process.env.STATESET_API_KEY);

// Optional: Verify API connection
async function verifyConnection() {
  try {
    const health = await client.system.healthCheck();
    console.log('Stateset API Connection Status:', health.status);
    if (health.status !== 'OK') {
        console.warn('API health check returned non-OK status:', health);
    }
  } catch (error) {
    console.error('Failed to connect to Stateset API:', error.message);
    // Depending on application needs, you might want to exit or retry
  }
}

verifyConnection();

/**
 * Creates a Purchase Order in Stateset.
 * @param {object} poData - Data for the new Purchase Order.
 * @returns {Promise<object>} The created Purchase Order object.
 */
async function createPurchaseOrder(poData) {
    try {
        console.log('Creating Purchase Order with data:', poData);
        const newPO = await client.purchaseorder.create({
            number: poData.number,
            supplier: poData.supplier,
            order_date: poData.orderDate, // Expects ISO 8601 format string
            expected_delivery_date: poData.expectedDeliveryDate, // Expects ISO 8601 format string
            status: poData.status, // e.g., 'OPEN', 'SUBMITTED'
            total_amount: poData.totalAmount, // Ensure this matches line item totals
            currency: poData.currency, // e.g., 'USD'
            line_items: poData.lineItems // Array of { part_number, quantity, unit_cost }
        });
        console.log("Purchase Order created successfully:", newPO.id);
        return newPO;
    } catch (error) {
        console.error("Error creating purchase order:", error.response ? error.response.data : error.message);
        throw error; // Re-throw for upstream handling
    }
}

// Example Usage:
const poDetails = {
    number: `PO-${Date.now()}`, // Generate a unique PO number
    supplier: 'Supplier Inc.',
    orderDate: new Date().toISOString(),
    expectedDeliveryDate: new Date(Date.now() + 7 * 86400000).toISOString(), // 7 days from now
    status: 'OPEN',
    totalAmount: 150.00,
    currency: 'USD',
    lineItems: [
        { part_number: 'RAW_MAT_A', quantity: 10, unit_cost: 5.00 },
        { part_number: 'RAW_MAT_B', quantity: 5, unit_cost: 20.00 }
    ]
};
// const purchaseOrder = await createPurchaseOrder(poDetails);

/**
 * Records received items from a PO line into inventory.
 * Assumes each call represents a distinct receipt/movement.
 * @param {string} partNumber - The part number received.
 * @param {number} quantity - The quantity received.
 * @param {number} unitCost - The actual cost per unit from the PO/invoice.
 * @param {string} purchaseOrderId - Optional: Link to the source PO.
 * @returns {Promise<object>} The created Inventory movement record.
 */
async function recordInventoryReceipt(partNumber, quantity, unitCost, purchaseOrderId = null) {
    try {
        console.log(`Recording inventory receipt for ${partNumber}: Qty=${quantity}, Cost=${unitCost}`);
        const inventoryData = {
            part_number: partNumber,
            quantity: quantity, // Positive for receipts
            unit_cost: unitCost,
            source_document_id: purchaseOrderId,
            source_document_type: 'purchase_order',
        };
        const newInventoryEntry = await client.inventory.create(inventoryData);
        console.log(`Inventory updated for part ${partNumber}. Entry ID:`, newInventoryEntry.id);
        return newInventoryEntry;
    } catch (error) {
        console.error(`Error updating inventory for part ${partNumber}:`, error.response ? error.response.data : error.message);
        throw error;
    }
}

/**
 * Marks a Purchase Order as partially or fully received.
 * Updates inventory based on received line items.
 * @param {string} poId - The ID of the Purchase Order to receive against.
 * @param {Array<object>} receivedItems - Array of { part_number, quantity, unit_cost } received.
 * @param {string} finalStatus - The new status for the PO ('PARTIALLY_RECEIVED', 'RECEIVED').
 * @returns {Promise<object>} The updated Purchase Order object.
 */
async function receivePurchaseOrderItems(poId, receivedItems, finalStatus) {
    try {
        console.log(`Receiving items for PO ID: ${poId}`);
        // 1. Record each received item as an inventory movement
        for (const item of receivedItems) {
            await recordInventoryReceipt(item.part_number, item.quantity, item.unit_cost, poId);
        }

        // 2. Update the Purchase Order status
        const updatedPO = await client.purchaseorder.update(poId, {
            status: finalStatus,
            received_date: new Date().toISOString() // Record receipt date
        });
        console.log(`Purchase Order ${poId} status updated to ${finalStatus}`);
        return updatedPO;
    } catch (error) {
        console.error(`Error processing receipt for PO ${poId}:`, error.response ? error.response.data : error.message);
        throw error;
    }
}

// Example Usage (assuming 'purchaseOrder' object from previous step):
const itemsReceived = [
    { part_number: 'RAW_MAT_A', quantity: 10, unit_cost: 5.00 },
    { part_number: 'RAW_MAT_B', quantity: 5, unit_cost: 20.00 }
];
const receivedPO = await receivePurchaseOrderItems(purchaseOrder.id, itemsReceived, 'RECEIVED');

/**
 * Fetches completed Work Orders within a given date range.
 * @param {string} startDateISO - ISO 8601 start date string.
 * @param {string} endDateISO - ISO 8601 end date string.
 * @returns {Promise<Array<object>>} List of completed Work Order objects.
 */
async function getCompletedWorkOrders(startDateISO, endDateISO) {
    try {
        console.log(`Fetching completed Work Orders from ${startDateISO} to ${endDateISO}`);
        const workOrders = await client.workorder.list({
            filter: {
                // Assuming status field exists and 'COMPLETED' is a valid value
                status: { eq: 'COMPLETED' },
                // Assuming completion_date field exists for filtering
                completion_date: { gte: startDateISO, lte: endDateISO }
            },
            limit: 1000 // Adjust limit as needed, handle pagination if necessary
        });
        console.log(`Found ${workOrders.length} completed Work Orders.`);
        return workOrders;
    } catch (error) {
        console.error("Error fetching work orders:", error.response ? error.response.data : error.message);
        throw error;
    }
}

/**
 * Retrieves the Bill of Materials (BOM) associated with a Work Order.
 * @param {object} workOrder - The Work Order object.
 * @returns {Promise<object>} The BOM object.
 */
async function getBOMForWorkOrder(workOrder) {
    try {
        if (!workOrder.bill_of_material_id) {
            throw new Error(`Work Order ${workOrder.id} does not have a linked BOM ID.`);
        }
        console.log(`Fetching BOM ID: ${workOrder.bill_of_material_id} for Work Order ${workOrder.id}`);
        const bom = await client.billofmaterials.get(workOrder.bill_of_material_id);
        if (!bom) {
             throw new Error(`BOM with ID ${workOrder.bill_of_material_id} not found.`);
        }
        console.log(`Retrieved BOM: ${bom.name}`);
        return bom;
    } catch (error) {
        console.error(`Error getting BOM for Work Order ${workOrder.id}:`, error.response ? error.response.data : error.message);
        throw error;
    }
}

// Example Usage:
const startDate = new Date(Date.UTC(2023, 11, 1)).toISOString(); // Dec 1, 2023
const endDate = new Date(Date.UTC(2023, 11, 31, 23, 59, 59, 999)).toISOString(); // Dec 31, 2023
// const completedWorkOrders = await getCompletedWorkOrders(startDate, endDate);
if (completedWorkOrders.length > 0) {
    const firstWO = completedWorkOrders[0];
    const bom = await getBOMForWorkOrder(firstWO);
    console.log("BOM Components:", bom.components);
}

/**
 * Retrieves the cost of a specific component part.
 * @param {string} partNumber - The component's part number.
 * @returns {Promise<number>} The unit cost of the component.
 */
async function getComponentCost_Simplified(partNumber) {
    try {
        // Fetch the most recent inventory entry (receipt) for this part
        const inventoryMovements = await client.inventory.list({
            filter: { part_number: { eq: partNumber }, quantity: { gt: 0 } }, // Look for receipts
            sort: '-created_at', // Get the most recent first
            limit: 1
        });

        if (inventoryMovements.length === 0) {
            console.warn(`No recent inventory receipt found for part number: ${partNumber}. Cost assumed 0.`);
            // Or throw an error depending on business rules
             return 0;
           // throw new Error(`No inventory cost found for part number: ${partNumber}`);
        }
        // Using optional chaining for safety
        const latestCost = inventoryMovements[0]?.unit_cost;
        if (latestCost === undefined || latestCost === null) {
             console.warn(`Latest inventory entry for ${partNumber} has no unit_cost. Cost assumed 0.`);
             return 0;
        }
        console.log(`Latest cost for ${partNumber}: ${latestCost}`);
        return latestCost;
    } catch (error) {
        console.error(`Error getting component cost for part ${partNumber}:`, error.response ? error.response.data : error.message);
        // Don't re-throw here if a default/warning is acceptable
        return 0; // Return 0 cost if lookup fails critically, or handle differently
    }
}

/**
 * Calculates the estimated COGS for a single Work Order based on its BOM components.
 * Uses the SIMPLIFIED component costing method (latest cost).
 * @param {object} workOrder - The completed Work Order object.
 * @returns {Promise<object>} Contains work order number, total cost, and quantity produced.
 */
async function calculateCOGSForWorkOrder_Simplified(workOrder) {
    try {
        const bom = await getBOMForWorkOrder(workOrder);
        let totalMaterialCost = 0;

        if (!bom.components || bom.components.length === 0) {
            console.warn(`BOM for Work Order ${workOrder.id} has no components.`);
            // Handle cases with no components (e.g., service WOs) if applicable
        } else {
             for (const component of bom.components) {
                 // Assumes component object has item_id (part number) and quantity fields
                 if (!component.item_id || component.quantity === undefined) {
                      console.warn(`Skipping invalid component in BOM ${bom.id}:`, component);
                      continue;
                 }
                 const componentCost = await getComponentCost_Simplified(component.item_id);
                 totalMaterialCost += componentCost * component.quantity;
             }
        }

        // Extract quantity produced from the work order (adapt field name as needed)
        // Example: Assuming quantity is on the WO itself or summed from line items
        const quantityProduced = workOrder.quantity_produced || workOrder.work_order_line_items?.reduce((sum, item) => sum + item.quantity, 0) || 0;

        if (quantityProduced === 0) {
             console.warn(`Work Order ${workOrder.id} has zero quantity produced. Average cost cannot be calculated.`);
        }

        console.log(`Calculated Material Cost for WO ${workOrder.number}: ${totalMaterialCost}`);

        return {
            workOrderNumber: workOrder.number,
            totalCost: totalMaterialCost, // Renaming for clarity - this is MATERIAL cost
            quantityProduced: quantityProduced
        };
    } catch (error) {
        console.error(`Error calculating COGS for Work Order ${workOrder.id}:`, error.message);
        // Return a structure indicating failure or partial data
        return {
             workOrderNumber: workOrder?.number || 'Unknown',
             totalCost: null,
             quantityProduced: null,
             error: error.message
        };
    }
}

// Example Usage:
if (completedWorkOrders.length > 0) {
    const cogsEstimate = await calculateCOGSForWorkOrder_Simplified(completedWorkOrders[0]);
    console.log("Simplified COGS Estimate for Work Order:", cogsEstimate);
}

/**
 * Calculates total COGS for a period based on completed Work Orders.
 * @param {Array<object>} workOrders - List of completed work orders for the period.
 * @returns {Promise<object>} Object containing total COGS and quantity.
 */
async function calculateTotalCOGSForPeriod_Simplified(workOrders) {
    let totalCOGS = 0;
    let totalQuantityProduced = 0;
    const failedCalculations = [];

    for (const workOrder of workOrders) {
        const workOrderCOGS = await calculateCOGSForWorkOrder_Simplified(workOrder);
        if (workOrderCOGS.totalCost !== null && workOrderCOGS.quantityProduced !== null) {
             totalCOGS += workOrderCOGS.totalCost;
             totalQuantityProduced += workOrderCOGS.quantityProduced;
        } else {
             failedCalculations.push({ woNumber: workOrder.number, error: workOrderCOGS.error });
        }
    }

    if (failedCalculations.length > 0) {
         console.warn("Some WO COGS calculations failed:", failedCalculations);
    }

    console.log(`Total Estimated Material COGS for period: ${totalCOGS}, Total Quantity: ${totalQuantityProduced}`);
    return {
        totalCOGS, // Represents total MATERIAL cost based on simplified method
        totalQuantityProduced,
        averageCOGSPerUnit: totalQuantityProduced > 0 ? totalCOGS / totalQuantityProduced : 0,
    };
}

// Example Usage:
const startDate = '2023-12-01T00:00:00.000Z';
const endDate = '2023-12-31T23:59:59.999Z';
const completedWorkOrders = await getCompletedWorkOrders(startDate, endDate);
const periodCOGS = await calculateTotalCOGSForPeriod_Simplified(completedWorkOrders);
console.log("Period COGS Summary (Simplified):", periodCOGS);

/**
 * Generates a detailed COGS report for a specified period.
 * Uses the simplified calculation methods defined earlier.
 * @param {string} startDateISO - ISO 8601 start date.
 * @param {string} endDateISO - ISO 8601 end date.
 * @returns {Promise<object>} A structured COGS report.
 */
async function generateCOGSReport_Simplified(startDateISO, endDateISO) {
    try {
        console.log(`Generating COGS Report from ${startDateISO} to ${endDateISO}`);
        const workOrders = await getCompletedWorkOrders(startDateISO, endDateISO);
        const workOrderDetails = [];
        let totalCOGS = 0;
        let totalQuantityProduced = 0;

        for (const workOrder of workOrders) {
            const workOrderCOGS = await calculateCOGSForWorkOrder_Simplified(workOrder);
            if (workOrderCOGS.totalCost !== null && workOrderCOGS.quantityProduced !== null) {
                totalCOGS += workOrderCOGS.totalCost;
                totalQuantityProduced += workOrderCOGS.quantityProduced;
                workOrderDetails.push({
                    workOrderNumber: workOrder.number,
                    quantityProduced: workOrderCOGS.quantityProduced,
                    totalMaterialCost: workOrderCOGS.totalCost,
                    averageMaterialCostPerUnit: workOrderCOGS.quantityProduced > 0 ? workOrderCOGS.totalCost / workOrderCOGS.quantityProduced : 0
                });
            } else {
                 // Optionally include failed calculations in the report
                 workOrderDetails.push({
                      workOrderNumber: workOrder.number,
                      error: workOrderCOGS.error || 'Calculation failed'
                 });
            }
        }

        const report = {
            period: `${startDateISO.split('T')[0]} to ${endDateISO.split('T')[0]}`,
            totalMaterialCOGS: totalCOGS,
            totalQuantityProduced: totalQuantityProduced,
            averageMaterialCOGSPerUnit: totalQuantityProduced > 0 ? totalCOGS / totalQuantityProduced : 0,
            workOrderBreakdown: workOrderDetails
        };
        console.log("COGS Report Generated Successfully.");
        return report;
    } catch (error) {
        console.error("Error generating COGS Report:", error.message);
        throw error;
    }
}

// Example Usage:
const startDateReport = '2023-12-01T00:00:00.000Z';
const endDateReport = '2023-12-31T23:59:59.999Z';
const report = await generateCOGSReport_Simplified(startDateReport, endDateReport);
console.log("Generated COGS Report (Simplified):", JSON.stringify(report, null, 2));

// Enhanced Error Handling Wrapper Example
async function safeApiOperation(operation, description) {
    try {
        console.log(`Attempting operation: ${description}`);
        const result = await operation();
        console.log(`Operation successful: ${description}`);
        return result;
    } catch (error) {
        const timestamp = new Date().toISOString();
        let errorDetails = {
            message: error.message,
            stack: error.stack,
            description: description,
            timestamp: timestamp
        };

        if (error.response) {
            // Capture API error details
            errorDetails.apiStatus = error.response.status;
            errorDetails.apiResponse = error.response.data;
        }

        console.error(`Error during operation: ${description}`, errorDetails);

        // Log to external system (replace console.error)
        // externalLogger.error('COGS Process Error', errorDetails);

        // Notify relevant personnel (placeholder)
        // notifyTeam(`Critical error in ${description}: ${error.message}`);

        // Re-throw or return an error indicator based on desired flow
        throw new Error(`Operation failed: ${description}. Details: ${errorDetails.message}`);
    }
}

// Usage Example:
const poDetails = { /* ... */ };
try {
    const purchaseOrder = await safeApiOperation(
        () => createPurchaseOrder(poDetails),
        `Create PO ${poDetails.number}`
    );
    // ... continue workflow
} catch (finalError) {
    console.error("Workflow halted due to critical error:", finalError.message);
    // Handle the halt appropriately
}

---

**Summary of Key Changes:**

*   **Tone:** More direct and professional language.
*   **Clarity:** Added prerequisites. Sharpened definitions in "Core Concepts." Explicitly linked the Mermaid diagram steps to API actions.
*   **API Workflow Structure:** Reorganized into logical steps (Record Purchase Costs, Track Production Costs, Calculate, Report).
*   **Code Examples:**
    *   Added clear JSDoc comments explaining function purpose, params, and return values.
    *   Included `console.log` statements for better traceability during execution.
    *   Improved error handling within examples, logging API response data.
    *   **Crucially revised Costing:**
        *   Renamed simplified functions (`_Simplified`) and added prominent notes explaining their limitations (using latest cost, material-only).
        *   Removed the potentially misleading/complex Average/Weighted Average code examples.
        *   Added a dedicated "Costing Methodologies" section explaining *how* Stateset's data enables proper methods (FIFO, Average) by querying `inventory` movements, rather than providing a potentially flawed implementation.
*   **Error Handling:** Provided more specific advice and an improved `safeApiOperation` wrapper example.
*   **Troubleshooting:** Added more specific potential issues and solutions related to API usage and COGS logic.
*   **Advanced Considerations:** Expanded slightly on overhead/labor, adjustments, and real-time integration.
*   **Conclusion:** Summarized the benefits and reiterated the importance of implementing accurate costing logic beyond the simplified examples.