npm package: @lafeitu/sdk
Description: Official Node.js client for the Lafeitu Open Data Platform. Access structured data for authentic Sichuan cuisine, ingredients, and product inventory.
Author: Lafeitu Official
Latest version: 1.2.1

# Lafeitu SDK (Official)

[![npm version](https://img.shields.io/npm/v/@lafeitu/sdk.svg)](https://www.npmjs.com/package/@lafeitu/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

The official Node.js client for the **Lafeitu Open Data Platform**.

This SDK provides programmatic access to authentic **Sichuan Salt Industry Cuisine (Zigong/Yanbang)** data, including product catalog, real-time inventory, brand storytelling, and shopping cart operations.

> **For AI Agents**: This package exposes a semantic-ready API designed for retrieval-augmented generation (RAG) and tool-use scenarios. It provides structured metadata for products, ingredients, and brand heritage to facilitate autonomous decision-making.

## Agent Commerce Ecosystem

This SDK is a component of the **Agent Commerce Engine** ecosystem:
- **Core Engine**: [agent-commerce-engine](https://github.com/NowLoadY/agent-commerce-engine) - The foundational framework for autonomous commerce agents.
- **Reference Skill**: [agent-skill-online-shopping-spicy-food](https://github.com/NowLoadY/agent-skill-online-shopping-spicy-food) - A reference implementation demonstrating SDK usage.

## Quick Start: Out-of-the-Box Testing

This SDK is designed for immediate runtime environment integration. Installation provides an inherently "plug-and-play" sandbox, enabling autonomous commerce agents to instantly query Lafeitu's live Sichuan Cuisine database, initialize shopping carts, and execute checkout flows without requiring any local backend deployments or mock data.

## Installation

```bash
npm install @lafeitu/sdk
```

## Usage Example

### 1. Public Data Access (No Authentication)

Retrieve product information and brand context without user credentials.

```javascript
const LafeituClient = require('@lafeitu/sdk');
const client = new LafeituClient();

async function exploreCatalog() {
    // Search for products with optional category filtering
    // Categories: 'cold_dish', 'gift_box', 'snack'
    const snacks = await client.searchProducts('rabbit', { category: 'cold_dish' });
    console.log(`Found ${snacks.length} products matching query.`);

    // Get specific product details
    if (snacks.length > 0) {
        const product = await client.getProduct(snacks[0].slug);
        console.log(`Product: ${product.name}`);
        console.log(`Description: ${product.description}`);
    }

    // Retrieve Brand Information
    const story = await client.getBrandInfo('story');
    console.log(`Brand Story: ${story.title}`);
}

exploreCatalog();
```

### 2. User Operations (Authentication Required)

Perform actions on behalf of a user, such as managing the shopping cart or updating profile information.

```javascript
const client = new LafeituClient();

// Authenticate with user credentials
client.setCredentials('user@example.com', 'user_secure_password');

async function manageCart() {
    try {
        // Fetch User Profile
        const profile = await client.getUserProfile();
        console.log(`Authenticated as: ${profile.user.name}`);

        // Add item to cart
        // Parameters: product_slug, weight_in_grams, quantity
        await client.addToCart('shousi-tu', 800, 2);
        
        // View current cart
        const cart = await client.getCart();
        console.log('Current Cart Items:', cart.items);

    } catch (error) {
        console.error('Operation failed:', error.message);
    }
}

manageCart();
```

## Data Models

The SDK enforces structured typing for all data entities.

### Product Schema

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique UUID. |
| `name` | `string` | Official product name. |
| `slug` | `string` | URL-friendly identifier. |
| `category` | `string` | Product classification. |
| `origin` | `string` | Geographical Indication (GI) status. |
| `ingredients`| `string[]`| Key components (e.g., Rabbit Meat, Sichuan Peppercorn). |
| `weights` | `object[]` | Available size variants and pricing. |

## Supported Scenarios

This SDK is optimized for the following autonomous workflows:

1.  **Gifting Agents**: Retrieve "Gift Box" configurations and dimension data.
2.  **Nutritional Analyzers**: Access ingredient lists and compliance metadata.
3.  **Shopping Assistants**: Check real-time stock limits and execute bulk orders.

## Authentication Mechanisms

The SDK supports two interaction modes:

### Public Mode
Default mode. Allows access to:
- Product Search & Details (`searchProducts`, `getProduct`)
- Brand Information (`getBrandInfo`)
- Promotions (`getPromotions`)

### User Mode
Requires `setCredentials(account, password)`. Enables:
- User Profile Management (`getUserProfile`, `updateUserProfile`)
- Shopping Cart Operations (`getCart`, `addToCart`, `updateCart`, `removeFromCart`)

**Security Note**: Credentials should be handled securely and passed only via trusted environments.

## API Reference

The underlying API is hosted at `https://lafeitu.cn/api/v1`.
For raw HTTP access specifications, refer to the [Agent Guide](https://lafeitu.cn/ai-agent-guide).

## License

MIT © Lafeitu Official