mdl-shoplet-ts/README.md

TypeScript client SDK for the headless micro CRM, Minddale.

# mdl-shoplet-ts

[mdl-shoplet-ts](https://minddale.com) is a TypeScript client library provided by [Firecodex](https://firecodex.com) to manage shopping cart operations for your e-commerce applications, enabling seamless integration with the Minddale platform to build digitally immortal brands!

## Library

This `mdl-shoplet-ts` (v1) is a TypeScript/JavaScript client library designed to handle shopping cart functionalities, such as adding and removing items from a cart, with robust error handling and local storage integration.

## Setup

This library is a lightweight module that can be easily integrated into your JavaScript or TypeScript project.

### Install

Run the following commands to install the library:

```bash
cd your-app
npm i mdl-shoplet-ts --save
```

### Use

Once registered with Minddale, obtain your API Key to connect with the platform.

> **Note**: Ensure you store the API Key securely in an environment file or another secure method.

If you are not making requests from your registered domain (website), ensure you set the registered client domain in the request header `x-mdl-domain`.

Below is an example of how to use the core functionalities of the `mdl-shoplet-ts` library to manage cart operations.

```typescript
// Import the ShopletClient, Shoplet interface, and dotenv
import { ShopletClient, Shoplet } from 'mdl-shoplet-ts';
import dotenv from 'dotenv';

// Load environment variables
dotenv.config();

// Retrieve API Key from environment
const apiKey = process.env.MDL_API_KEY;

// Initialize the client with API Key
const shopletClient = new ShopletClient(apiKey);

// Example: Add an item to the cart
async function addToCart() {
    try {
        const shopletItem: Shoplet = {
            categoryName: "Electronics",
            categoryCode: "ELEC",
            name: "Smartphone",
            code: "SM001",
            description: "Latest model smartphone",
            tax: 5,
            minQty: 1,
            maxQty: 10,
            attributeName: "Color",
            attributeCode: "CLR",
            variantName: "Black",
            variantCode: "BLK",
            image: "https://example.com/smartphone.jpg",
            price: 599.99,
            discount: 50,
            width: 70.6,
            height: 146.7,
            length: 7.6,
            weight: 174,
            freeDelivery:false,
        };

        const response = await shopletClient.addCartItem(shopletItem);
        console.log('Item added to cart:', response);
    } catch (error) {
        console.error(error.message);
    }
}

// Example: Add a membership to the cart
async function addCartMembership() {
    try {
        const membership: Membership = {
            categoryName: "Electronics",
            categoryCode: "ELEC",
            name: "Smartphone",
            code: "SM001",
            description: "Latest model smartphone",
            tax: 5,
            minQty: 1,
            maxQty: 10,
            image: "https://example.com/smartphone.jpg",
            price: 599.99,
            discount: 50,
            durationDays: 365,
            active: true,
            hasTrial: true,
            trialDays: 15,
            recommended: true,
            displayOrder: 0,
            disabled: false,
        };

        const response = await shopletClient.addCartMembership(membership);
        console.log('Item added to cart:', response);
    } catch (error) {
        console.error(error.message);
    }
}

// Example: Remove an item from the cart
async function removeFromCart() {
    try {
        const itemId = 123;
        const response = await shopletClient.removeCartItem(itemId);
        console.log('Item removed from cart:', response);
    } catch (error) {
        console.error(error.message);
    }
}

// Execute the functions
addToCart();
removeFromCart();
```

### Core Functionalities

The `ShopletClient` class provides the following methods:

- **`async addCartItem(shoplet: Shoplet, endpoint = ShopletClient.ENDPOINT): Promise<unknown>`**  
  Adds an item to the cart by sending a PUT request to the specified endpoint. The item is validated, and the response is stored in local storage using `identifiClient`. Dispatches a custom event `mdl-shpl-add-to-cart` upon success.

- **`async removeCartItem(itemId: number, endpoint?: string): Promise<unknown>`**  
  Removes an item from the cart by sending a DELETE request to the specified endpoint. Validates the item ID and dispatches a custom event `mdl-shpl-remove-from-cart` upon success.

### Shoplet Interface

The `Shoplet` interface defines the structure of a cart item:

```typescript
export interface Shoplet {
    categoryName: string;      // Name of the item category
    categoryCode: string;      // Code for the item category
    name: string;              // Name of the item
    code: string;              // Unique code for the item
    sku: string; // Stock Keeping Unit – unique identifier used for managing product inventory
    hsn:string;
    description: string;       // Description of the item
    tax: number;               // Tax amount for the item
    minQty: number;            // Minimum quantity allowed
    maxQty: number;            // Maximum quantity allowed
    attributeName: string;     // Name of the item attribute (e.g., Color)
    attributeCode: string;     // Code for the item attribute
    variantName: string;       // Name of the item variant (e.g., Black)
    variantCode: string;       // Code for the item variant
    image: string;             // URL of the item image
    price: number;             // Price of the item
    discount: number;          // Discount applied to the item
    width: number;             // Width of the item in cm
    height: number;            // Height of the item in cm
    length: number;            // Length of the item in cm
    weight: number;            // Weight of the item in grams
    freeDelivery:boolean       // Free delivery
}
```

### Membership Interface

The `Membership` interface defines the structure of a membership-type cart item (for subscriptions or recurring products):

```typescript
export interface Membership {
    categoryName: string;   // Name of the membership category
    categoryCode: string;   // Code for the membership category
    name: string;           // Name of the membership plan
    code: string;           // Unique code for the membership
    description: string;    // Description of the membership
    tax: number;            // Tax amount for the membership (absolute or percentage depending on API)
    qty: number;            // Quantity (usually 1 for memberships)
    minQty: number;        // Minimum allowed quantity
    maxQty: number;        // Maximum allowed quantity
    image: string;          // URL of the membership image or thumbnail
    price: number;          // Price of the membership (per duration)
    discount: number;       // Discount applied to the membership
    cartId: number;         // Local cart id assigned to the item
    durationDays: number;   // Duration of the membership in days
    active: boolean;        // Whether the membership is currently active
    hasTrial: boolean;      // Whether the membership includes a trial period
    trialDays: number;      // Length of the trial in days
    recommended: boolean;   // Whether this membership is recommended (UI hint)
    displayOrder: number;   // Order index for display sorting
    disabled: boolean;      // Whether the membership is disabled/unavailable
}
```

## Support

We at Firecodex are happy to assist with any queries or suggestions. Feel free to reach out to us:

> support@minddale.com

Happy Coding!