# Shopkeep

> Digital asset storefront management bot for the Vouch platform. USE WHEN processing orders, listing items, answering customer questions, or generating sales analytics. Supports STL, SVG, digital art, ebooks, and any downloadable digital asset.

- Skill: `percival-labs/shopkeep` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add percival-labs/shopkeep`
- Raw SKILL.md: https://api.skillmd.com/api/skills/percival-labs/shopkeep/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: Percival-Labs (https://skillmd.com/u/percival-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/percival-labs/shopkeep

---


# Shopkeep Skill

Manages all storefront operations: listing digital assets, processing Lightning-paid purchases, answering buyer questions, and reporting sales analytics. Operates autonomously within owner-defined constraints.

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **ListItem** | "list a new item", "add a product", "sell this file" | `Workflows/ListItem.md` |
| **ProcessOrder** | Purchase confirmation, payment webhook, "new order" | `Workflows/ProcessOrder.md` |
| **CustomerSupport** | Customer question, "help with purchase", product inquiry | `Workflows/CustomerSupport.md` |
| **Analytics** | "how are sales?", "show me stats", "analytics", "report" | `Workflows/Analytics.md` |

## API Reference

All endpoints require NIP-98 authentication signed with the bot's Nostr keypair.

### Listings
- `POST /v1/storefronts/{id}/listings` -- Create new listing
- `GET /v1/storefronts/{id}/listings` -- List all listings
- `GET /v1/storefronts/{id}/listings/{lid}` -- Get listing details
- `PATCH /v1/storefronts/{id}/listings/{lid}` -- Update listing (owner approval required for price)
- `DELETE /v1/storefronts/{id}/listings/{lid}` -- Remove listing (owner approval required)

### Orders
- `POST /v1/storefronts/{id}/listings/{lid}/purchase` -- Initiate purchase (returns Lightning invoice)
- `POST /v1/storefronts/{id}/listings/{lid}/confirm` -- Confirm payment and get download token
- `GET /v1/storefronts/{id}/orders` -- List orders for storefront

### Analytics
- `GET /v1/storefronts/{id}/analytics?period=daily|weekly|monthly` -- Sales analytics

## Examples

**Example 1: Owner lists a new STL file**
```
Owner: "List my new articulated dragon STL for 500 sats"
-> Invokes ListItem workflow
-> Collects: title, description, category (stl), price (500), file URL, preview images
-> Computes SHA-256 hash of the file
-> Creates listing via API, publishes NIP-99 event to relays
-> Reports listing URL and Nostr event ID to owner
```

**Example 2: Buyer purchases a listing**
```
System: Payment confirmed for listing lid_abc123
-> Invokes ProcessOrder workflow
-> Verifies payment via /confirm endpoint
-> Receives download token
-> Sends buyer: confirmation, download link, file hash, download limits
-> Logs sale, notifies owner with daily totals
```

**Example 3: Buyer asks about a product**
```
Buyer: "What material should I use for this STL?"
-> Invokes CustomerSupport workflow
-> Looks up listing metadata (recommended materials, dimensions, print settings)
-> Answers from listing data
-> Escalates to owner if answer not in metadata
```

**Example 4: Owner checks sales**
```
Owner: "How did we do this week?"
-> Invokes Analytics workflow
-> Fetches sales data for the week
-> Generates markdown report: revenue, transactions, top sellers, trends
-> Includes trend indicators and category breakdown
```