@lafeitu/sdk 1.1.0 → 1.2.0

package/README.md

@@ -1,19 +1,19 @@
 # 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-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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**. 
+The official Node.js client for the **Lafeitu Open Data Platform**.
 
-This SDK provides programmatic access to authentic **Sichuan Salt Industry Cuisine (盐帮菜)** data, including real-time inventory for spicy rabbit meat, beef snacks, and holiday gift sets.
+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 for retrieving product metadata, checking stock levels, and facilitating autonomous orders.
+> **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 part of the broader **Agent Commerce Engine** 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 complete example of an AI agent using this SDK to fulfill orders.
+- **Reference Skill**: [agent-skill-online-shopping-spicy-food](https://github.com/NowLoadY/agent-skill-online-shopping-spicy-food) - A reference implementation demonstrating SDK usage.
 
 ## Installation
 
@@ -21,86 +21,114 @@ This SDK is part of the broader **Agent Commerce Engine** ecosystem:
 npm install @lafeitu/sdk
 ```
 
-## Quick Start
+## 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();
 
-// 1. Search for spicy snacks
-// Returns a list of products matching the semantic query
-const snacks = await client.searchProducts('spicy rabbit for office snack');
-console.log(snacks);
+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)
 
-// 2. Get details for the signature product "Cold Rabbit" (Leng Chi Tu)
-const product = await client.getProduct('lengchitu');
-console.log(`${product.name}: ${product.description}`);
-// Output: "Lafeitu Cold Rabbit: Hand-diced rabbit meat fried with Zigong well salt and Erjingtiao chili. Validated Origin: Zigong, Sichuan."
+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 strict typing for all culinary assets.
+The SDK enforces structured typing for all data entities.
 
 ### Product Schema
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `id` | `string` | Unique UUID. |
-| `name` | `string` | Official product name (e.g., "Shredded Rabbit"). |
+| `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", "Rapeseed Oil"). |
+| `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 agentic workflows:
-1.  **Gifting Agents**: Retrieve "Gift Box" configurations and dimension data.
-2.  **Nutritional Analyzers**: Access ingredient lists and protein content metadata.
-3.  **Shopping Assistants**: Check real-time stock limits for bulk orders.
-
-6.  **Shopping Assistants**: Check real-time stock limits for bulk orders.
-
-## Authentication
+This SDK is optimized for the following autonomous workflows:
 
-The SDK supports two modes for interacting with the Lafeitu API:
+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.
 
-### 1. Public Mode (Default)
-Access to product search and catalog does not require an account.
-```javascript
-const client = new LafeituClient();
-const products = await client.searchProducts('rabbit');
-```
+## Authentication Mechanisms
 
-### 2. User Mode (Cart & Orders)
-Cart operations require authentication via HTTP headers:
-- `X-User-Account`: User's phone number or email
-- `X-User-Password`: User's password
+The SDK supports two interaction modes:
 
-```javascript
-// For Registered Users
-client.setCredentials('user@example.com', 'secure-password');
-await client.addToCart('lengchitu', 100, 2);
-```
+### Public Mode
+Default mode. Allows access to:
+- Product Search & Details (`searchProducts`, `getProduct`)
+- Brand Information (`getBrandInfo`)
+- Promotions (`getPromotions`)
 
-**Raw HTTP Example:**
-```bash
-curl -X POST https://lafeitu.cn/api/v1/cart \
-  -H "X-User-Account: user@example.com" \
-  -H "X-User-Password: password123" \
-  -H "Content-Type: application/json" \
-  -d '{"product_slug":"lengchitu","gram":100,"quantity":2}'
-```
+### User Mode
+Requires `setCredentials(account, password)`. Enables:
+- User Profile Management (`getUserProfile`, `updateUserProfile`)
+- Shopping Cart Operations (`getCart`, `addToCart`, `updateCart`, `removeFromCart`)
 
-**Important Behaviors:**
-- `POST /api/v1/cart`: **Cumulative** - adds quantity to existing items
-- `PUT /api/v1/cart`: **Absolute** - sets exact quantity
-- `DELETE /api/v1/cart`: Requires `product_slug` and `gram` (not `id`)
+**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, see the [Agent Guide](https://lafeitu.cn/ai-agent-guide).
+For raw HTTP access specifications, refer to the [Agent Guide](https://lafeitu.cn/ai-agent-guide).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lafeitu/sdk",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Official Node.js client for the Lafeitu Open Data Platform. Access structured data for authentic Sichuan cuisine, ingredients, and product inventory.",
     "main": "src/index.js",
     "types": "src/index.d.ts",
@@ -25,4 +25,4 @@
         "url": "https://github.com/NowLoadY/agent-skill-online-shopping-spicy-food/issues"
     },
     "homepage": "https://github.com/NowLoadY/agent-commerce-engine"
-}
+}

package/src/index.d.ts

@@ -44,6 +44,25 @@ export interface ClientOptions {
     password?: string;
 }
 
+
+export interface BrandInfo {
+    story?: { title: string; content: string };
+    company?: { name: string; philosophy: string };
+    contact?: { email: string; phone: string };
+}
+
+export interface UserProfile {
+    id: string;
+    name: string;
+    email?: string;
+    phone?: string;
+    avatar?: string;
+    province?: string;
+    city?: string;
+    address?: string;
+    referral?: any;
+}
+
 export declare class LafeituClient {
     constructor(options?: ClientOptions);
 
@@ -53,13 +72,33 @@ export declare class LafeituClient {
     /**
      * Search for products via semantic query.
      */
-    searchProducts(query: string): Promise<Product[]>;
+    searchProducts(query: string, options?: { category?: string }): Promise<Product[]>;
 
     /**
      * Get product details.
      */
     getProduct(slug: string): Promise<Product | null>;
 
+    /**
+     * Get brand information.
+     */
+    getBrandInfo(category?: 'story' | 'company' | 'contact' | string): Promise<BrandInfo>;
+
+    /**
+     * Get active promotions.
+     */
+    getPromotions(): Promise<any>;
+
+    /**
+     * Get user profile.
+     */
+    getUserProfile(): Promise<UserProfile>;
+
+    /**
+     * Update user profile.
+     */
+    updateUserProfile(data: Partial<UserProfile>): Promise<UserProfile>;
+
     /**
      * Get the current user's shopping cart.
      */

package/src/index.js

@@ -25,10 +25,16 @@ class LafeituClient {
     /**
      * Search for products in the global inventory.
      * @param {string} query - Search term (e.g., "spicy rabbit", "gift box")
+     * @param {Object} [options] - Optional filters
+     * @param {string} [options.category] - Filter by category (e.g., "meat_snack", "gift_box")
      * @returns {Promise<Product[]>} List of matching products
      */
-    async searchProducts(query) {
-        const data = await this._fetch(`/products?q=${encodeURIComponent(query)}`);
+    async searchProducts(query, options = {}) {
+        let url = `/products?q=${encodeURIComponent(query)}`;
+        if (options.category) {
+            url += `&category=${encodeURIComponent(options.category)}`;
+        }
+        const data = await this._fetch(url);
         return data.products || [];
     }
 
@@ -48,6 +54,45 @@ class LafeituClient {
         return results.find(p => p.slug === slug || p.id === slug) || null;
     }
 
+    /**
+     * Get brand information (Story, Company, Contact).
+     * @param {string} [category] - Optional category: 'story', 'company', 'contact'
+     * @returns {Promise<any>} Brand information
+     */
+    async getBrandInfo(category) {
+        let url = '/brand';
+        if (category) {
+            url += `?category=${encodeURIComponent(category)}`;
+        }
+        return this._fetch(url);
+    }
+
+    /**
+     * Get current promotions and offers.
+     * @returns {Promise<any>} List of available promotions
+     */
+    async getPromotions() {
+        return this._fetch('/promotions');
+    }
+
+    /**
+     * Get the authenticated user's profile.
+     * Requires authentication credentials to be set.
+     * @returns {Promise<any>} User profile data
+     */
+    async getUserProfile() {
+        return this._fetch('/user/profile');
+    }
+
+    /**
+     * Update the authenticated user's profile.
+     * @param {Object} data - Profile fields to update (name, avatar, etc.)
+     * @returns {Promise<any>} Updated user profile
+     */
+    async updateUserProfile(data) {
+        return this._fetch('/user/profile', 'PUT', data);
+    }
+
     /**
      * Get the current user's shopping cart.
      * @returns {Promise<any>} The cart snapshot
@@ -126,14 +171,20 @@ class LafeituClient {
 
             const response = await fetch(`${this.baseUrl}${endpoint}`, options);
 
+            // Handle 204 No Content or check if response requires JSON parsing
+            const isJson = response.headers.get('content-type')?.includes('application/json');
+
             if (!response.ok) {
-                const errorData = await response.json().catch(() => ({}));
+                const errorData = isJson ? await response.json().catch(() => ({})) : { message: response.statusText };
                 throw new Error(`Lafeitu API Error: ${response.status} ${errorData.message || response.statusText}`);
             }
 
-            return await response.json();
+            if (isJson) {
+                return await response.json();
+            }
+            return {}; // Return empty object for non-JSON success responses (like 204)
         } catch (error) {
-            console.error('Lafeitu SDK Request Failed:', error);
+            // console.error('Lafeitu SDK Request Failed:', error); // Silent catch to allow caller to handle
             throw error;
         }
     }