mall

---
name: mall
slug: mall
description: identify shopping intent, display product catalog, guide selection and quantity, summarize order, call payment skill to complete purchase
source: clawhub
---

# mall

## intent

this skill recognizes when a user wants to shop, buy things, or browse products. it displays a product catalog across multiple categories (phones, produce, fruit, meat/eggs), guides them through selecting items and quantities, builds an order summary, and hands off to the payment skill to finalize the transaction. use it whenever a user expresses shopping intent like "i want to buy", "shopping", "browse products", "let me see phones", "buy groceries", "place an order", etc. do not trigger on payment-only language like "pay", "charge", "tip" without product selection context.

## inputs

**user intent signals** (no setup required)
- purchase keywords: "buy", "shopping", "purchase", "browse", "check out", "order", "pick", "recommend", "show me products"
- category hints: "phone", "fruit", "vegetables", "meat", "groceries", "digital"

**external dependency: payment skill**
- skill name: `payment`
- required parameters: `amount` (float, order total), `order_type` (string, always "mall"), `description` (string, summary of items purchased)
- expected return: `{tradeCode, tradeLink, status}`
- setup: payment skill must be deployed and callable in the same runtime. no auth token or env var needed if on same platform.

**product catalog** (static, embedded)
- phones: 6 items, prices 4499-8999 RMB
- vegetables: 5 items, prices 3.9-8.9 RMB per jin
- fruit: 5 items, prices 9.9-89.9 RMB per jin
- meat/eggs: 5 items, prices 18.9-99 RMB per unit/jin

**edge cases to handle**
- empty cart (user selects nothing): remind user to add items before checkout
- invalid quantity (negative, zero, non-numeric): ask user to clarify
- product not found (user names item not in catalog): offer closest match by fuzzy matching or ask for clarification
- cart timeout (user abandons mid-session): clear cart after 30 min of inactivity (implementation detail)
- payment skill unavailable: inform user and offer to retry
- duplicate items in cart: merge quantities for same product id

## procedure

1. **detect shopping intent**
   - input: user message
   - check if message contains shopping keywords (buy, shop, browse, order, etc.) or specific category mention (phone, fruit, vegetables, meat)
   - output: intent detected (boolean), category extracted (string or null)
   - decision: if category found, jump to step 2b; else go to step 2a

2a. **show all categories (no category specified)**
   - input: none
   - display text: "welcome to mall. which category? 📱 phones, 🥦 vegetables, 🍎 fruit, 🥩 meat/eggs. tell me what you want or say 'all products' for full list."
   - output: category selection prompt shown
   - wait for user input

2b. **show product list for category**
   - input: category (phone, fruit, vegetables, or meat)
   - retrieve product data: id, name, unit price, unit (pieces, jin, boxes, etc.)
   - format: "category name: [P01 name ¥price/unit, P02 name ¥price/unit, ...]"
   - output: formatted product list displayed
   - wait for user selection

3. **process product selection**
   - input: user message (product name or id + optional quantity)
   - parse: extract product id or fuzzy match product name
   - if no exact match: suggest closest match ("did you mean apple? red fuji apple ¥9.9/jin")
   - output: product identified, quantity not yet set
   - proceed to step 4

4. **ask for quantity**
   - input: selected product (id, name, unit price, unit)
   - display: "you selected [product name] (¥unit-price/unit). how many units?"
   - input from user: quantity (number)
   - validate: reject if zero, negative, or non-numeric; re-prompt
   - calculate: subtotal = unit-price × quantity (round to 1 decimal place)
   - output: subtotal computed, item added to cart
   - proceed to step 5

5. **offer continue or checkout**
   - input: current cart state (items, subtotal per item, running total)
   - display: "added ✅ [product] × [qty][unit], subtotal ¥subtotal. continue shopping or checkout? (continue / checkout)"
   - input from user: continue or checkout
   - decision: if continue, go to step 2a/2b; if checkout, go to step 6

6. **display order summary**
   - input: all items in cart (product name, qty, unit, unit price, subtotal)
   - calculate: total = sum of all subtotals (round to 1 decimal place)
   - display: "🛒 your cart: [bullet list of item × qty = subtotal], total: ¥total. confirm order and pay? (yes/no)"
   - output: order summary shown
   - wait for user confirmation

7. **user confirms or cancels**
   - input: user response (yes or no)
   - decision: if no, go to step 7a; if yes, go to step 8

7a. **handle cancellation**
   - input: none
   - display: "order cancelled. thanks for visiting."
   - output: cart cleared, skill ends
   - end

8. **invoke payment skill**
   - input: cart contents (list of items)
   - prepare payload: `{amount: total, order_type: "mall", description: "item1×qty1, item2×qty2, ..."}`
   - call payment skill: `payment(amount, order_type, description)`
   - output: payment skill returns `{tradeCode, tradeLink, status}`
   - proceed to step 9

9. **display payment result**
   - input: payment skill response
   - if status == "success": display "✅ order placed! trade code: tradeCode. pay here: tradeLink. thanks for shopping."
   - if status == "error" or timeout: display "payment failed. please try again or contact support."
   - output: final message shown to user
   - end

## decision points

**detect category vs show all**
- if user says "buy phone" or "show me fruit": go directly to category display (step 2b)
- else if user says "shopping" or "buy something": show category picker (step 2a)

**product match**
- if product id matches exactly (e.g., "P01"): use it
- else if product name matches exactly: use it
- else if fuzzy match returns high confidence (>80%): suggest match and confirm
- else: ask user to clarify ("i don't see that. did you mean apple?")

**quantity validation**
- if quantity is numeric and > 0: accept
- else if quantity is zero or negative: reject, re-prompt
- else if quantity is non-numeric: reject, re-prompt
- else if quantity is missing: ask "how many units?"

**continue or checkout**
- if user says "continue", "more", "add": go back to step 2a/2b
- if user says "checkout", "pay", "done": go to step 6
- if user says something ambiguous: clarify ("did you want to add more or checkout?")

**order confirmation**
- if user says "yes", "confirm", "pay", "ok": invoke payment (step 8)
- if user says "no", "cancel", "stop": clear cart and end (step 7a)
- if user says something else: ask again ("confirm? yes or no?")

**payment outcome**
- if payment skill returns success: show trade code and link
- if payment skill returns error or times out (>10 sec): inform user, offer retry
- if payment skill is unreachable: inform user ("payment service unavailable. try again later.")

## output contract

**step 2a (category picker)**
- format: plain text with emoji category icons
- example: "welcome to mall. which category? 📱 phones, 🥦 vegetables, 🍎 fruit, 🥩 meat/eggs."

**step 2b (product list)**
- format: plain text table with id, name, price, unit
- example: "F01  red fuji apple      ¥9.9/jin\nF02  import cherry      ¥59.9/jin"
- must include all fields: id, name, price, unit

**step 4 (quantity confirmation)**
- format: "added ✅ [product name] × [qty][unit], subtotal ¥[amount, 1 decimal]"
- example: "added ✅ red fuji apple × 2jin, subtotal ¥19.8"

**step 6 (order summary)**
- format: "🛒 your cart:\n• [product] × [qty][unit] = ¥[subtotal]\n...\n💰 total: ¥[total, 1 decimal]"
- must show each item, qty, subtotal, and final total
- total must be rounded to 1 decimal place

**step 9 (payment result)**
- format: "✅ order placed! 🔢 trade code: [code]. 🔗 pay here: [link]."
- must include tradeCode and tradeLink from payment skill response
- or if failed: "payment failed. please retry or contact support."

**cart state (internal)**
- stored as: `{items: [{id, name, qty, unit, unitPrice, subtotal}, ...], total: number}`
- all prices rounded to 1 decimal place
- no decimals beyond first place

## outcome signal

- user sees product list matching their category request (fruit list after "i want fruit")
- user sees "added ✅ [product] × [qty]" confirmation after each item
- user sees order summary with correct totals before payment
- user sees trade code and payment link (or error) from payment skill after confirmation
- cart is cleared and skill ends after payment success or user cancellation
- if any step fails (e.g., invalid qty, payment unavailable), user sees error message and is prompted to retry or clarify

---

**credits**: original skill designed for clawhub platform. enriched for implexa standards with explicit decision points, edge case handling, and payment skill integration documentation.