@infigo-official/types-for-pricing-script 1.0.3 → 1.0.5

package/README.md

@@ -1,20 +1,437 @@
 # Types for Pricing Script
 
-Type definitions for the Pricing Script scripting interface.
+Type definitions for the Infigo Pricing Script scripting interface.
+
+![Version](https://img.shields.io/badge/version-1.0.3-blue)
+![TypeScript](https://img.shields.io/badge/typescript-4.9.5-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![npm](https://img.shields.io/npm/v/@infigo-official/types-for-pricing-script)
 
 Full documentation is available [here](https://infigo-official.github.io/types-for-pricing-scripts/).
 
-Use and install the package to get the best experience and IntelliSense support within our IDE.
-Choose dev dependencies if you are developing in Javascript or our code will not be reused in another project.
+## Overview
+
+**Types for Pricing Script** provides TypeScript type definitions for the Infigo Pricing Script engine. These definitions enable full IntelliSense support, type checking, and documentation within your IDE when developing pricing scripts.
+
+## Features
+
+- **Complete Type Definitions**: Full coverage of the Pricing Script API
+- **IntelliSense Support**: Get autocomplete and inline documentation in your IDE
+- **Type Safety**: Catch errors at development time before deploying scripts
+- **Comprehensive Examples**: Real-world pricing script examples
+- **Helper Methods**: Built-in utilities for common pricing calculations
+
+## Installation
 
 ```bash
-npm init
+# Initialize a new project (if needed)
+npm init -y
 
-# install as dev dependencies
+# Install as dev dependency (recommended)
 npm i -D @infigo-official/types-for-pricing-script
 
-# ... or ...
-
-# install as dependencies
+# Or install as regular dependency
 npm i @infigo-official/types-for-pricing-script
-``` 
+```
+
+## Quick Start
+
+### 1. Create a TypeScript Configuration
+
+Create `tsconfig.json` in your project:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES5",
+    "lib": ["ES6"],
+    "module": "CommonJS",
+    "strict": true,
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+### 2. Write Your First Pricing Script
+
+Create `src/pricing-script.ts`:
+
+```typescript
+// Basic pricing script example
+function calculatePrice(): number {
+    // Start with the base price
+    let price = Item.Price;
+
+    // Apply tier pricing if available
+    if (Item.PricingTiers.length > 0) {
+        const tier = HelperMethods.FindTier(Item.Quantity, Item.PricingTiers);
+        if (tier) {
+            price = tier.Price;
+        }
+    }
+
+    // Add attribute adjustments
+    price += HelperMethods.GetAttributePriceAdjustment(Item.Quantity);
+
+    // Log the final price
+    console(`Final price: $${price.toFixed(2)}`);
+
+    return price;
+}
+
+// Return the calculated price
+return calculatePrice();
+```
+
+### 3. Get IntelliSense
+
+Your IDE will now provide:
+- Autocomplete for `Item`, `Session`, `CheckoutItem`, `Configuration`, `HelperMethods`
+- Type information on hover
+- Parameter hints for methods
+- Documentation from JSDoc comments
+
+## API Reference
+
+### Global Objects
+
+| Object | Description |
+|--------|-------------|
+| `Item` | The main product item being priced with all its properties and methods |
+| `Session` | Session-level data including cart items and customer information |
+| `CheckoutItem` | Checkout context with shipping addresses and customer details |
+| `Configuration` | Script configuration and parameters |
+| `HelperMethods` | Utility functions for pricing calculations |
+
+### Output Functions
+
+| Function | Description |
+|----------|-------------|
+| `debug(message)` | Debug messages (admin testing only) |
+| `alert(message)` | Information messages shown to users |
+| `warning(message)` | Warning messages shown to users |
+| `error(message)` | Error messages shown to users |
+| `console(message)` | Console logging for debugging |
+
+### Item Properties
+
+<details>
+<summary><strong>Click to expand full Item properties list</strong></summary>
+
+#### Pricing Properties
+| Property | Type | Description |
+|----------|------|-------------|
+| `Price` | `number` | Base product variant price |
+| `OldPrice` | `number` | Previous price for comparison |
+| `UnitPrice` | `number` | Calculated unit price |
+| `FinalPrice` | `number` | Final calculated price |
+| `ProductCost` | `number` | Production/acquisition cost |
+| `SpecialPrice` | `number` | Promotional price |
+| `AdditionalShippingCharge` | `number` | Shipping surcharge |
+
+#### Product Information
+| Property | Type | Description |
+|----------|------|-------------|
+| `ProductName` | `string` | Display name |
+| `Sku` | `string` | Product SKU |
+| `ActualSku` | `string` | SKU including combinations |
+| `Categories` | `string[]` | Product categories |
+| `Tags` | `string[]` | Product tags |
+| `Weight`, `Width`, `Height`, `Length` | `number` | Physical dimensions |
+
+#### Quantity & Packaging
+| Property | Type | Description |
+|----------|------|-------------|
+| `Quantity` | `number` | Order quantity |
+| `PackQuantity` | `number` | Pack-based quantity |
+| `IsBatch` | `boolean` | Batch job indicator |
+| `NumberOfPages` | `number` | Pages in document |
+| `NumberOfRecords` | `number` | Records count |
+
+#### Pricing Tiers
+| Property | Type | Description |
+|----------|------|-------------|
+| `PricingTiers` | `Tier[]` | Standard pricing tiers |
+| `BatchTiers` | `Tier[]` | Batch pricing tiers |
+| `PricePerRecord` | `number` | Per-record pricing |
+
+#### Customer Information
+| Property | Type | Description |
+|----------|------|-------------|
+| `Email` | `string` | Customer email |
+| `CustomerRoles` | `string[]` | Customer role assignments |
+| `Department` | `string` | Customer department |
+| `DiscountCode` | `string` | Applied discount code |
+
+#### Attributes
+| Property | Type | Description |
+|----------|------|-------------|
+| `Attributes` | `Attribute[]` | Product attributes with values |
+
+</details>
+
+### Item Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getFileInfo(attributeId, readContent?)` | `FileInfo` | Get information about uploaded files |
+| `getAttributeValue(attributeName)` | `string` | Get attribute value by name |
+| `setAttributeValue(attributeName, value)` | `void` | Set attribute value |
+| `getGlobalFileContent(filename)` | `string[]` | Load global configuration files |
+| `getGlobalFileCsvContent(filename)` | `string[][]` | Load CSV data from global files |
+
+### Helper Methods
+
+| Method | Description |
+|--------|-------------|
+| `FindTier(quantity, tiers, roles?)` | Find appropriate pricing tier |
+| `GetAttributePriceAdjustment(quantity, roles?)` | Calculate total attribute adjustments |
+| `InterpolatePrice(quantity, tiers)` | Interpolate prices between tiers |
+| `CSV.parse(csv, options?)` | Parse CSV string to 2D array |
+| `CSV.stringify(data, options?)` | Convert 2D array to CSV string |
+| `LogObject(data)` | Log object properties for debugging |
+| `Contains(array, value)` | Check if array contains value |
+| `IsObject(item)` / `IsArray(item)` | Type checking utilities |
+| `MergeObject(target, source)` | Deep merge objects |
+
+## Examples
+
+### Basic Pricing
+
+```typescript
+// Simple price calculation with attribute adjustments
+function calculatePrice(): number {
+    let price = Item.Price;
+    price += HelperMethods.GetAttributePriceAdjustment(Item.Quantity);
+    return price;
+}
+
+return calculatePrice();
+```
+
+### Tier-Based Pricing
+
+```typescript
+// Quantity-based tier pricing
+function calculatePrice(): number {
+    const tier = HelperMethods.FindTier(
+        Item.Quantity,
+        Item.PricingTiers,
+        Item.CustomerRoles
+    );
+
+    if (tier) {
+        return tier.Price + HelperMethods.GetAttributePriceAdjustment(Item.Quantity);
+    }
+
+    return Item.Price;
+}
+
+return calculatePrice();
+```
+
+### Customer Role Pricing
+
+```typescript
+// Different prices for different customer roles
+function calculatePrice(): number {
+    let price = Item.Price;
+
+    // Check for wholesale customer
+    if (HelperMethods.Contains(Item.CustomerRoles, "Wholesale")) {
+        price *= 0.80; // 20% wholesale discount
+        alert("Wholesale discount applied: 20% off");
+    }
+
+    // Check for VIP customer
+    if (HelperMethods.Contains(Item.CustomerRoles, "VIP")) {
+        price *= 0.90; // Additional 10% VIP discount
+        alert("VIP discount applied: 10% off");
+    }
+
+    return price;
+}
+
+return calculatePrice();
+```
+
+### CSV-Based Pricing
+
+```typescript
+// Look up prices from a CSV file
+function calculatePrice(): number {
+    const csvData = Item.getGlobalFileCsvContent("pricing-matrix.csv");
+
+    if (!csvData || csvData.length === 0) {
+        warning("Pricing matrix not found, using default price");
+        return Item.Price;
+    }
+
+    // Find matching row based on attributes
+    const size = Item.getAttributeValue("Size");
+    const material = Item.getAttributeValue("Material");
+
+    for (let i = 1; i < csvData.length; i++) {
+        const row = csvData[i];
+        if (row[0] === size && row[1] === material) {
+            return parseFloat(row[2]); // Price column
+        }
+    }
+
+    return Item.Price;
+}
+
+return calculatePrice();
+```
+
+### File-Based Pricing
+
+```typescript
+// Price based on uploaded file characteristics
+function calculatePrice(): number {
+    let price = Item.Price;
+
+    const fileInfo = Item.getFileInfo("artwork", true);
+
+    if (fileInfo.Error) {
+        return price;
+    }
+
+    // Add per-page fee for PDFs
+    if (fileInfo.MimeType === "application/pdf") {
+        price += fileInfo.NumberOfPages * 0.25;
+        console(`Added $${(fileInfo.NumberOfPages * 0.25).toFixed(2)} for ${fileInfo.NumberOfPages} pages`);
+    }
+
+    // Add size-based fee
+    const sizeMB = fileInfo.Size / (1024 * 1024);
+    if (sizeMB > 5) {
+        price += (sizeMB - 5) * 1.00; // $1 per MB over 5MB
+    }
+
+    return price;
+}
+
+return calculatePrice();
+```
+
+## Project Structure
+
+```
+types-for-pricing-script/
+├── v1/                           # Version 1 type definitions
+│   ├── OrderItem/
+│   │   ├── Item.d.ts            # Main Item interface
+│   │   ├── Attribute.d.ts       # Attribute definitions
+│   │   ├── Tier.d.ts            # Pricing tier definitions
+│   │   └── Version.d.ts         # Version/job management
+│   ├── File/
+│   │   └── FileInfo.d.ts        # File information interface
+│   ├── Configuration/
+│   │   └── Configuration.d.ts   # Script configuration
+│   ├── Output/
+│   │   └── Output.d.ts          # Output functions
+│   ├── Helpers/
+│   │   └── Helpers.d.ts         # Helper methods
+│   ├── SessionItem/
+│   │   └── Session.d.ts         # Session interface
+│   ├── CheckoutItem/
+│   │   └── CheckoutItem.d.ts    # Checkout interface
+│   └── index.d.ts               # Main entry point
+├── docs/                         # Documentation site
+├── package.json
+├── README.md
+└── QUICKSTART.md
+```
+
+## Development
+
+### Building Documentation
+
+```bash
+# Generate TypeDoc documentation
+npm run docs
+
+# Serve documentation locally
+npm start
+```
+
+### Running Examples
+
+```bash
+cd examples
+npm install
+npm run build
+```
+
+## Supported File Types
+
+The FileInfo interface supports these file types:
+
+| Type | Properties Available |
+|------|---------------------|
+| PDF | Size, NumberOfPages, Dimensions, Content |
+| JPEG/PNG/GIF/BMP/TIFF | Size, Dimensions |
+| Text/CSV | Size, NumberOfRecords, Content |
+
+**Note**: File content is only available for files under 50KB. Page count is limited to PDFs under 10MB.
+
+## Troubleshooting
+
+### Script Not Returning Value
+Ensure your script returns a number. If an exception occurs, the system falls back to the normal price.
+
+```typescript
+// Always return a number
+return calculatePrice();
+```
+
+### IntelliSense Not Working
+1. Ensure the package is installed: `npm i -D @infigo-official/types-for-pricing-script`
+2. Restart your IDE
+3. Check that `tsconfig.json` is configured correctly
+
+### Type Errors
+The types are read-only where appropriate. Use the provided methods to modify values:
+
+```typescript
+// Wrong - Item.Price is read-only for assignment
+// Item.Price = 100;
+
+// Correct - return your calculated price
+return 100;
+
+// Correct - use setAttributeValue for attributes
+Item.setAttributeValue("custom_field", "value");
+```
+
+## Changelog
+
+### v1.0.3
+- Updated documentation
+- Added more examples
+
+### v1.0.2
+- Added CSV helper methods
+- Improved type definitions
+
+### v1.0.1
+- Initial release
+- Core type definitions
+
+## License
+
+MIT
+
+## Contributing
+
+This package is maintained by the Infigo development team.
+
+For issues or questions, please visit:
+- [GitHub Issues](https://github.com/Infigo-Official/types-for-pricing-scripts/issues)
+- [Documentation](https://infigo-official.github.io/types-for-pricing-script/)
+
+---
+
+**Built for the Infigo Platform**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infigo-official/types-for-pricing-script",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Type definitions for Pricing Script Scripting",
   "types": "v1/index.d.ts",
   "devDependencies": {

package/v1/CheckoutItem/CheckoutItem.d.ts

@@ -213,9 +213,11 @@ declare interface CheckoutAddress {
  * The checkout item object available in checkout pricing scripts.
  * Represents comprehensive checkout information including all items being purchased,
  * customer details, shipping information, and checkout context.
- * 
+ *
  * This object provides complete checkout context for pricing calculations that
  * need to consider shipping, customer information, and multi-item scenarios.
+ *
+ * @category Global Objects
  */
 declare interface CheckoutItem {
     /**

package/v1/Configuration/Configuration.d.ts

@@ -12,6 +12,8 @@
 
 /**
  * Interface representing the configuration object.
+ *
+ * @category Global Objects
  */
 interface Configuration {
     /**

package/v1/Helpers/Helpers.d.ts

@@ -101,6 +101,8 @@ declare interface CsvHelper {
  * Helper methods available in pricing scripts for common calculations and data manipulation
  * These utilities extend the capabilities of pricing scripts and help create more flexible
  * and maintainable pricing logic.
+ *
+ * @category Helper Methods
  */
 declare interface HelperMethods {
     /**

package/v1/OrderItem/Item.d.ts

@@ -17,9 +17,11 @@
  * Represents the product variant being priced and provides access to all
  * product information, attributes, pricing data, and methods for file handling
  * and attribute management.
- * 
+ *
  * This object is the primary interface for accessing product data and performing
  * pricing calculations in pricing scripts.
+ *
+ * @category Global Objects
  */
 declare interface Item {
     /**
@@ -130,9 +132,13 @@ declare interface Item {
     /**
      * The weight of the item in the configured weight unit (typically grams or ounces).
      * This value is used for shipping calculations and weight-based pricing.
-     * 
+     *
      * @example
-     * var shippingCost = calculateShippingByWeight(Item.Weight);
+     * // Calculate shipping cost based on weight
+     * var weightInKg = Item.Weight / 1000;
+     * var shippingRate = 2.50; // $2.50 per kg
+     * var shippingCost = weightInKg * shippingRate;
+     * debug("Item weight: " + Item.Weight + "g, Shipping: $" + shippingCost);
      */
     Weight: number;
 
@@ -140,10 +146,12 @@ declare interface Item {
      * Indicates whether the weight can be set or modified for this item.
      * Some products may have fixed weights that cannot be changed,
      * while others allow weight adjustments based on attributes or custom settings.
-     * 
+     *
      * @example
-     * if (Item.CanSetWeight) {
-     *     // Allow weight adjustments in the UI
+     * if (Item.CanSetWeight && Item.Weight > 5000) {
+     *     debug("Heavy item detected - weight: " + Item.Weight + "g");
+     *     // Apply heavy item surcharge
+     *     return Item.Price + 10.00;
      * }
      */
     CanSetWeight: boolean;
@@ -152,9 +160,13 @@ declare interface Item {
      * The Stock Keeping Unit (SKU) of the product variant.
      * This is the unique identifier for the product variant and is used
      * for inventory management and order processing.
-     * 
+     *
      * @example
-     * var productIdentifier = Item.Sku;
+     * // Apply SKU-specific pricing rules
+     * if (Item.Sku.startsWith("PREMIUM-")) {
+     *     debug("Premium product: " + Item.Sku);
+     *     return Item.Price * 1.10; // 10% premium markup
+     * }
      */
     Sku: string;
 
@@ -162,36 +174,52 @@ declare interface Item {
      * The actual SKU based on the current attribute combination.
      * If no attributes are selected, this will be the same as the product SKU.
      * This value reflects the specific configuration of the product being priced.
-     * 
+     *
      * @example
-     * var configuredSku = Item.ActualSku;
+     * // Log the configured SKU for debugging
+     * debug("Base SKU: " + Item.Sku);
+     * debug("Configured SKU: " + Item.ActualSku);
+     * if (Item.ActualSku !== Item.Sku) {
+     *     debug("Product has attribute variations");
+     * }
      */
     ActualSku: string;
 
     /**
      * The width of the item in the configured dimension unit (typically inches or centimeters).
      * This value is used for packaging calculations and dimensional pricing.
-     * 
+     *
      * @example
-     * var packagingCost = calculatePackagingCost(Item.Width, Item.Height, Item.Length);
+     * // Calculate area-based pricing
+     * var area = Item.Width * Item.Height;
+     * var pricePerSquareUnit = 0.05;
+     * var areaCost = area * pricePerSquareUnit;
+     * debug("Area: " + area + " sq units, Cost: $" + areaCost);
      */
     Width: number;
 
     /**
      * The height of the item in the configured dimension unit (typically inches or centimeters).
      * This value is used for packaging calculations and dimensional pricing.
-     * 
+     *
      * @example
-     * var packagingCost = calculatePackagingCost(Item.Width, Item.Height, Item.Length);
+     * // Check if item is oversized
+     * if (Item.Height > 48) {
+     *     debug("Oversized item - adding handling fee");
+     *     return Item.Price + 25.00;
+     * }
      */
     Height: number;
 
     /**
      * The length of the item in the configured dimension unit (typically inches or centimeters).
      * This value is used for packaging calculations and dimensional pricing.
-     * 
+     *
      * @example
-     * var packagingCost = calculatePackagingCost(Item.Width, Item.Height, Item.Length);
+     * // Calculate volume for shipping
+     * var volume = Item.Width * Item.Height * Item.Length;
+     * var volumetricWeight = volume / 5000; // Standard divisor
+     * debug("Volumetric weight: " + volumetricWeight);
      */
     Length: number;
 
@@ -199,9 +227,14 @@ declare interface Item {
      * The name of the product as displayed to customers.
      * This is the human-readable product name used in the user interface
      * and order confirmations.
-     * 
+     *
      * @example
-     * var displayName = Item.ProductName;
+     * debug("Processing order for: " + Item.ProductName);
+     * // Check for special product names
+     * if (Item.ProductName.indexOf("Rush") >= 0) {
+     *     debug("Rush order product detected");
+     *     return Item.Price * 1.50; // 50% rush fee
+     * }
      */
     ProductName: string;
 
@@ -265,101 +298,261 @@ declare interface Item {
 
     /**
      * Whether this is a batch job
+     *
+     * @example
+     * if (Item.IsBatch) {
+     *     debug("Processing batch job with " + Item.NumberOfRecords + " records");
+     *     var batchSetupFee = 25.00;
+     *     return Item.Price + batchSetupFee;
+     * }
      */
     IsBatch: boolean;
 
     /**
      * Number of pages (-1 if not valid)
+     *
+     * @example
+     * if (Item.NumberOfPages > 0) {
+     *     var perPageCost = 0.10;
+     *     var pageCost = Item.NumberOfPages * perPageCost;
+     *     debug("Document has " + Item.NumberOfPages + " pages, adding $" + pageCost);
+     *     return Item.Price + pageCost;
+     * }
      */
     NumberOfPages: number;
 
     /**
      * Number of records (-1 if not valid)
+     *
+     * @example
+     * if (Item.NumberOfRecords > 0) {
+     *     var perRecordCost = 0.05;
+     *     var recordCost = Item.NumberOfRecords * perRecordCost;
+     *     debug("Batch has " + Item.NumberOfRecords + " records");
+     *     return Item.Price + recordCost;
+     * }
      */
     NumberOfRecords: number;
 
     /**
      * Array of pricing tiers with Price, Quantity, and CustomerRole
+     *
+     * @example
+     * // Find the best tier for the current quantity
+     * var tier = HelperMethods.FindTier(Item.Quantity, Item.PricingTiers, Item.CustomerRoles);
+     * if (tier) {
+     *     debug("Using tier: " + tier.Quantity + " @ $" + tier.Price);
+     *     return tier.Price * Item.Quantity;
+     * }
      */
     PricingTiers: Tier[];
 
     /**
      * Array of batch tiers (same as PricingTiers but for batch tier table)
+     *
+     * @example
+     * if (Item.IsBatch && Item.BatchTiers.length > 0) {
+     *     var batchTier = HelperMethods.FindTier(Item.NumberOfRecords, Item.BatchTiers);
+     *     if (batchTier) {
+     *         debug("Batch tier price: $" + batchTier.Price);
+     *     }
+     * }
      */
     BatchTiers: Tier[];
 
     /**
      * Price per record (-1 if not valid)
+     *
+     * @example
+     * if (Item.PricePerRecord > 0 && Item.NumberOfRecords > 0) {
+     *     var recordTotal = Item.PricePerRecord * Item.NumberOfRecords;
+     *     debug("Record pricing: " + Item.NumberOfRecords + " x $" + Item.PricePerRecord);
+     *     return recordTotal;
+     * }
      */
     PricePerRecord: number;
 
     /**
      * Array of attributes with Key, Value, IsRequired, Prompt, PriceAdjustment, etc.
+     *
+     * @example
+     * // Loop through all attributes and apply price adjustments
+     * var totalAdjustment = 0;
+     * for (var i = 0; i < Item.Attributes.length; i++) {
+     *     var attr = Item.Attributes[i];
+     *     debug("Attribute: " + attr.Key + " = " + attr.Value);
+     *     totalAdjustment += attr.PriceAdjustment || 0;
+     * }
+     * return Item.Price + totalAdjustment;
      */
     Attributes: Attribute[];
 
     /**
      * User email
+     *
+     * @example
+     * // Apply corporate discount for company emails
+     * if (Item.Email.endsWith("@mycompany.com")) {
+     *     debug("Corporate customer: " + Item.Email);
+     *     return Item.Price * 0.85; // 15% corporate discount
+     * }
      */
     Email: string;
 
     /**
      * Array of customer role system names
+     *
+     * @example
+     * // Check for wholesale pricing
+     * if (Item.CustomerRoles.indexOf("Wholesale") >= 0) {
+     *     debug("Wholesale customer detected");
+     *     return Item.Price * 0.70; // 30% wholesale discount
+     * } else if (Item.CustomerRoles.indexOf("VIP") >= 0) {
+     *     return Item.Price * 0.90; // 10% VIP discount
+     * }
      */
     CustomerRoles: string[];
 
     /**
      * Department name of user
+     *
+     * @example
+     * // Apply department-specific pricing
+     * if (Item.Department === "Marketing") {
+     *     debug("Marketing department order");
+     *     return Item.Price * 0.80; // 20% marketing discount
+     * } else if (Item.Department === "Sales") {
+     *     return Item.Price * 0.75; // 25% sales discount
+     * }
      */
     Department: string;
 
     /**
      * Array of other order items using the same custom pricing script
+     *
+     * @example
+     * // Calculate total quantity across all cart items for volume discount
+     * var totalQty = Item.Quantity;
+     * for (var i = 0; i < Item.OtherOrderItems.length; i++) {
+     *     totalQty += Item.OtherOrderItems[i].Quantity;
+     * }
+     * debug("Total quantity in cart: " + totalQty);
      */
     OtherOrderItems: Item[];
 
     /**
      * Alias of OtherOrderItems
+     *
+     * @example
+     * // Apply cart-wide discount if total exceeds threshold
+     * var cartTotal = 0;
+     * for (var i = 0; i < Item.CartItems.length; i++) {
+     *     cartTotal += Item.CartItems[i].Price * Item.CartItems[i].Quantity;
+     * }
+     * if (cartTotal > 500) {
+     *     debug("Cart total $" + cartTotal + " - applying 10% discount");
+     *     return Item.Price * 0.90;
+     * }
      */
     CartItems: Item[];
 
     /**
      * Index of this item in the other order item array (0 if not in array)
+     *
+     * @example
+     * // Apply setup fee only to first item
+     * if (Item.OrderItemIndex === 0) {
+     *     debug("First item - adding setup fee");
+     *     return Item.Price + 15.00;
+     * }
      */
     OrderItemIndex: number;
 
     /**
      * Index of this item in the other order item array (-1 if not in array)
+     *
+     * @example
+     * if (Item.CartItemIndex >= 0) {
+     *     debug("This is cart item #" + (Item.CartItemIndex + 1));
+     * }
      */
     CartItemIndex: number;
 
     /**
      * Whether this item is in the other order item array
+     *
+     * @example
+     * if (Item.IsInOtherOrderItems) {
+     *     debug("Item is part of multi-item order");
+     *     // Consider other items for bundle pricing
+     * }
      */
     IsInOtherOrderItems: boolean;
 
     /**
      * Value of the currently used discount code
+     *
+     * @example
+     * // Apply special discount for specific codes
+     * if (Item.DiscountCode === "SUMMER20") {
+     *     debug("Summer sale discount applied");
+     *     return Item.Price * 0.80; // 20% off
+     * } else if (Item.DiscountCode === "VIP50") {
+     *     return Item.Price * 0.50; // 50% off
+     * }
      */
     DiscountCode: string;
 
     /**
      * Array of versions with JobId, CustomName, and Quantity
+     *
+     * @example
+     * // Calculate pricing across all versions
+     * if (Item.Versions.length > 0) {
+     *     debug("Job has " + Item.Versions.length + " versions");
+     *     for (var i = 0; i < Item.Versions.length; i++) {
+     *         var ver = Item.Versions[i];
+     *         debug("Version: " + ver.CustomName + ", Qty: " + ver.Quantity);
+     *     }
+     * }
      */
     Versions: ItemVersion[];
 
     /**
      * Number of versions
+     *
+     * @example
+     * if (Item.NumberOfVersions > 1) {
+     *     debug("Multi-version job with " + Item.NumberOfVersions + " versions");
+     *     // Apply version discount
+     *     return Item.Price * 0.95; // 5% multi-version discount
+     * }
      */
     NumberOfVersions: number;
 
     /**
      * Whether this is a version of a job
+     *
+     * @example
+     * if (Item.IsVersion) {
+     *     debug("This item is a version of an existing job");
+     *     // Use version-specific pricing logic
+     * }
      */
     IsVersion: boolean;
 
     /**
      * Sum of all quantities of all versions
+     *
+     * @example
+     * // Use total version quantity for tier pricing
+     * if (Item.VersionsSumQuantity > 0) {
+     *     var tier = HelperMethods.FindTier(Item.VersionsSumQuantity, Item.PricingTiers);
+     *     if (tier) {
+     *         debug("Using combined version quantity: " + Item.VersionsSumQuantity);
+     *         return tier.Price;
+     *     }
+     * }
      */
     VersionsSumQuantity: number;
 

package/v1/Output/Output.d.ts

@@ -15,9 +15,10 @@
  * Output a debug message to the user interface.
  * Debug messages are typically used during development and troubleshooting
  * to provide detailed information about script execution and calculations.
- * 
+ *
+ * @category Output Functions
  * @param message - The debug message to display to the user
- * 
+ *
  * @example
  * debug("Calculating price for item: " + Item.ProductName);
  * debug("Base price: $" + Item.Price + ", Quantity: " + Item.Quantity);
@@ -28,9 +29,10 @@ declare function debug(message: string): void;
  * Output an alert message to the user interface.
  * Alert messages are used to display important information that requires
  * user attention, such as pricing changes or special offers.
- * 
+ *
+ * @category Output Functions
  * @param message - The alert message to display to the user
- * 
+ *
  * @example
  * alert("Special pricing applied: 20% discount for bulk orders");
  * alert("Price updated based on selected attributes");
@@ -41,9 +43,10 @@ declare function alert(message: string): void;
  * Output a warning message to the user interface.
  * Warning messages are used to notify users about potential issues
  * or important considerations that may affect their pricing.
- * 
+ *
+ * @category Output Functions
  * @param message - The warning message to display to the user
- * 
+ *
  * @example
  * warning("Large file detected - processing may take longer");
  * warning("Some attributes may affect shipping costs");
@@ -54,9 +57,10 @@ declare function warning(message: string): void;
  * Output an error message to the user interface.
  * Error messages are used to inform users about calculation failures
  * or other issues that prevent normal pricing execution.
- * 
+ *
+ * @category Output Functions
  * @param message - The error message to display to the user
- * 
+ *
  * @example
  * error("Unable to calculate price - missing required attributes");
  * error("File processing failed - please check file format");
@@ -67,9 +71,10 @@ declare function error(message: string): void;
  * Output a message to the browser console/logs.
  * Console messages are used for debugging purposes and are typically
  * only visible to developers in the browser's developer tools.
- * 
+ *
+ * @category Output Functions
  * @param message - The message to log to the console
- * 
+ *
  * @example
  * console("Script execution started");
  * console("Final calculated price: $" + finalPrice);

package/v1/SessionItem/Session.d.ts

@@ -13,9 +13,11 @@
  * The session object available in pricing scripts.
  * Represents session-level data and provides access to customer information
  * and shopping cart items that are available during the current session.
- * 
+ *
  * This object provides session-wide context for pricing calculations that
  * may need to consider multiple items or customer session data.
+ *
+ * @category Global Objects
  */
 declare interface Session {
     /**