From dbd64f7fafc29c847d9a315f4d2cf1e679e863de Mon Sep 17 00:00:00 2001 From: Ben Weeks Date: Tue, 23 Dec 2025 12:53:21 +0000 Subject: [PATCH 1/8] feat: improve shipping zone UX MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove asterisks from UK/US country names (#153) - Remove unclear "Flat rate" option (#153) - Alphabetize country list, move China to correct position (#153) - Rename "Unit" to "Currency" (#154) - Rename cost label to "Default shipping cost" (#154) - Add currency suffix to cost field (#154) - Add hint about per-product shipping costs (#154) - Add validation for whole number sats (#155) - Disable submit button when sats validation fails (#155) - Show error message for invalid sats values (#155) Closes #153, #154, #155 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 104 ++++++++++++++++++ static/components/shipping-zones.js | 11 +- .../components/shipping-zones.html | 10 +- 3 files changed, 116 insertions(+), 9 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..db2ef06 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,104 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Nostr Market is an LNbits extension implementing NIP-15 (decentralized marketplace protocol) on Nostr. It enables merchants to create webshops (stalls) and sell products with Lightning Network payments, featuring encrypted customer-merchant communication via NIP-04. + +**Prerequisites:** Requires the LNbits [nostrclient](https://github.com/lnbits/nostrclient) extension to be installed and configured. + +## Common Commands + +All commands are in the Makefile: + +```bash +make format # Run prettier, black, and ruff formatters +make check # Run mypy, pyright, black check, ruff check, prettier check +make test # Run pytest with debug mode +make all # Run format and check +``` + +Individual tools: + +```bash +make black # Format Python files +make ruff # Check and fix Python linting +make mypy # Static type checking +make pyright # Python static type checker +make prettier # Format JS/HTML/CSS files +``` + +## Local Development Setup + +To run checks locally, install dependencies: + +```bash +# Install Python autotools dependencies (needed for secp256k1) +sudo apt-get install -y automake autoconf libtool + +# Install Python dependencies +uv sync + +# Install Node dependencies (for prettier) +npm install + +# Run all checks +make check +``` + +## Architecture + +### Core Layers + +1. **API Layer** (`views_api.py`) - REST endpoints for merchants, stalls, products, zones, orders, direct messages +2. **Business Logic** (`services.py`) - Order processing, Nostr event signing/publishing, message routing, invoice handling +3. **Data Layer** (`crud.py`) - Async SQLite operations via LNbits db module +4. **Models** (`models.py`) - Pydantic models for all entities + +### Nostr Integration (`nostr/`) + +- `nostr_client.py` - WebSocket client connecting to nostrclient extension for relay communication +- `event.py` - Nostr event model, serialization, ID computation (SHA256), Schnorr signatures + +### Background Tasks (`__init__.py`, `tasks.py`) + +Three permanent async tasks: + +- `wait_for_paid_invoices()` - Lightning payment listener +- `wait_for_nostr_events()` - Incoming Nostr message processor +- `_subscribe_to_nostr_client()` - WebSocket connection manager + +### Frontend (`static/`, `templates/`) + +- Merchant dashboard: `templates/nostrmarket/index.html` +- Customer marketplace: `templates/nostrmarket/market.html` with Vue.js/Quasar in `static/market/` +- Use Quasar UI components when possible: https://quasar.dev/components + +### Key Data Models + +- **Merchant** - Shop owner with Nostr keypair, handles event signing and DM encryption +- **Stall** - Individual shop with products and shipping zones (kind 30017) +- **Product** - Items for sale with categories, images, quantity (kind 30018) +- **Zone** - Shipping configuration by region +- **Order** - Customer purchases with Lightning invoice tracking +- **DirectMessage** - Encrypted chat (NIP-04) +- **Customer** - Buyer profile with Nostr pubkey + +### Key Patterns + +- **Nostrable Interface** - Base class for models convertible to Nostr events (`to_nostr_event()`, `to_nostr_delete_event()`) +- **Parameterized Replaceable Events** - Stalls (kind 30017) and Products (kind 30018) per NIP-33 +- **AES-256 Encryption** - Customer-merchant DMs use shared secret from ECDH +- **JSON Meta Fields** - Complex data (zones, items, config) stored as JSON in database + +### Cryptography (`helpers.py`) + +- Schnorr signatures for Nostr events +- NIP-04 encryption/decryption +- Key derivation and bech32 encoding (npub/nsec) + +## Workflow + +- Always check GitHub Actions after pushing to verify CI passes +- Run `make check` locally before pushing to catch issues early diff --git a/static/components/shipping-zones.js b/static/components/shipping-zones.js index 742021a..13f0357 100644 --- a/static/components/shipping-zones.js +++ b/static/components/shipping-zones.js @@ -19,7 +19,6 @@ window.app.component('shipping-zones', { currencies: [], shippingZoneOptions: [ 'Free (digital)', - 'Flat rate', 'Worldwide', 'Europe', 'Australia', @@ -27,6 +26,7 @@ window.app.component('shipping-zones', { 'Belgium', 'Brazil', 'Canada', + 'China', 'Denmark', 'Finland', 'France', @@ -34,8 +34,8 @@ window.app.component('shipping-zones', { 'Greece', 'Hong Kong', 'Hungary', - 'Ireland', 'Indonesia', + 'Ireland', 'Israel', 'Italy', 'Japan', @@ -59,10 +59,9 @@ window.app.component('shipping-zones', { 'Thailand', 'Turkey', 'Ukraine', - 'United Kingdom**', - 'United States***', - 'Vietnam', - 'China' + 'United Kingdom', + 'United States', + 'Vietnam' ] } }, diff --git a/templates/nostrmarket/components/shipping-zones.html b/templates/nostrmarket/components/shipping-zones.html index 3f0fd08..fcbeac3 100644 --- a/templates/nostrmarket/components/shipping-zones.html +++ b/templates/nostrmarket/components/shipping-zones.html @@ -55,18 +55,22 @@ dense v-model="zoneDialog.data.currency" type="text" - label="Unit" + label="Currency" :options="currencies" >
@@ -83,7 +87,7 @@ Create Shipping Zone From d51a66cd6912aca7dab20a94eb798bec7be13b03 Mon Sep 17 00:00:00 2001 From: Ben Weeks Date: Tue, 23 Dec 2025 12:58:00 +0000 Subject: [PATCH 2/8] feat: move currency dropdown inline with cost field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Layout now shows: [Default shipping cost] [Currency ▼] 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../components/shipping-zones.html | 54 ++++++++++--------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/templates/nostrmarket/components/shipping-zones.html b/templates/nostrmarket/components/shipping-zones.html index fcbeac3..de1b22c 100644 --- a/templates/nostrmarket/components/shipping-zones.html +++ b/templates/nostrmarket/components/shipping-zones.html @@ -48,30 +48,36 @@ label="Countries" v-model="zoneDialog.data.countries" > - - +
+
+ +
+
+ +
+
Update From 4dad0a0029ac29eda428d0be6c29a66df5767555 Mon Sep 17 00:00:00 2001 From: Ben Weeks Date: Tue, 23 Dec 2025 12:59:41 +0000 Subject: [PATCH 3/8] fix: remove extra left padding on cost field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- templates/nostrmarket/components/shipping-zones.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/nostrmarket/components/shipping-zones.html b/templates/nostrmarket/components/shipping-zones.html index de1b22c..32f8b0e 100644 --- a/templates/nostrmarket/components/shipping-zones.html +++ b/templates/nostrmarket/components/shipping-zones.html @@ -48,8 +48,8 @@ label="Countries" v-model="zoneDialog.data.countries" > -
-
+
+
Date: Tue, 23 Dec 2025 13:03:29 +0000 Subject: [PATCH 4/8] chore: add CLAUDE.md to gitignore MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index f3a8853..056489e 100644 --- a/.gitignore +++ b/.gitignore @@ -22,4 +22,7 @@ node_modules *.swp *.pyo *.pyc -*.env \ No newline at end of file +*.env + +# Claude Code config +CLAUDE.md \ No newline at end of file From bcdd001e1bf359cf84067c1fb1fb6f2559136d87 Mon Sep 17 00:00:00 2001 From: Ben Weeks Date: Tue, 23 Dec 2025 13:04:34 +0000 Subject: [PATCH 5/8] feat: add validation for max 2 decimal places on non-sat currencies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- templates/nostrmarket/components/shipping-zones.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/templates/nostrmarket/components/shipping-zones.html b/templates/nostrmarket/components/shipping-zones.html index 32f8b0e..b72e46e 100644 --- a/templates/nostrmarket/components/shipping-zones.html +++ b/templates/nostrmarket/components/shipping-zones.html @@ -59,8 +59,8 @@ :step="zoneDialog.data.currency != 'sat' ? '0.01' : '1'" type="number" v-model.trim="zoneDialog.data.cost" - :error="zoneDialog.data.currency === 'sat' && zoneDialog.data.cost % 1 !== 0" - error-message="Satoshis must be whole numbers" + :error="(zoneDialog.data.currency === 'sat' && zoneDialog.data.cost % 1 !== 0) || (zoneDialog.data.currency !== 'sat' && (zoneDialog.data.cost * 100) % 1 !== 0)" + :error-message="zoneDialog.data.currency === 'sat' ? 'Satoshis must be whole numbers' : 'Maximum 2 decimal places allowed'" hint="Additional costs can be set per product" >
@@ -93,7 +93,7 @@ Create Shipping Zone From 284608e73cc27435af474fa8680a9669bb2c4032 Mon Sep 17 00:00:00 2001 From: Ben Weeks Date: Tue, 23 Dec 2025 13:07:29 +0000 Subject: [PATCH 6/8] feat: disable Create Shipping Zone button if no name entered MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- templates/nostrmarket/components/shipping-zones.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/nostrmarket/components/shipping-zones.html b/templates/nostrmarket/components/shipping-zones.html index b72e46e..b0dbc34 100644 --- a/templates/nostrmarket/components/shipping-zones.html +++ b/templates/nostrmarket/components/shipping-zones.html @@ -93,7 +93,7 @@ Create Shipping Zone From c4f0eb4d9166de5e7c3e264e14fc971ff099f1bf Mon Sep 17 00:00:00 2001 From: Ben Weeks Date: Tue, 23 Dec 2025 16:27:01 +0000 Subject: [PATCH 7/8] feat: enhance extension info card with Nostr introduction and resources MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Nostrich banner image at top of card - Change title to "Nostr Market" with intro description - Add expandable sections: What is Nostr?, Getting Started, For Merchants, For Customers, Contributors - Add links: Market Client, API Documentation, NIP-15 Specification, GitHub Issues - Add Ben Weeks to contributors - Mention NIP-15 interoperability with other marketplaces (Amethyst, Plebeian Market) Closes #159 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- templates/nostrmarket/_api_docs.html | 245 ++++++++++++++++++++++----- templates/nostrmarket/index.html | 16 +- 2 files changed, 219 insertions(+), 42 deletions(-) diff --git a/templates/nostrmarket/_api_docs.html b/templates/nostrmarket/_api_docs.html index 6bce480..e61cd62 100644 --- a/templates/nostrmarket/_api_docs.html +++ b/templates/nostrmarket/_api_docs.html @@ -1,44 +1,213 @@ - - -

- Nostr Market
- - Created by, + + + +

+ Nostr (Notes and Other Stuff Transmitted by Relays) is + a decentralized protocol for censorship-resistant communication. Unlike + traditional platforms, your identity and data aren't controlled by any + single company. +

+

+ Your Nostr identity is a cryptographic key pair - a public key (npub) + that others use to find you, and a private key (nsec) that proves you + are you. Keep your nsec safe and never share it! +

+ + + + + + + +

1. Generate or Import Keys

+

+ Create a new Nostr identity or import an existing one using your nsec. + Your keys are used to sign all marketplace events. +

+

2. Create a Stall

+

+ A stall is your shop. Give it a name, description, and configure + shipping zones for delivery. +

+

3. Add Products

+

+ List items for sale with images, descriptions, and prices in your + preferred currency. +

+

4. Publish to Nostr

+

+ Your stall and products are published to Nostr relays where customers + can discover them using any compatible marketplace client. +

+ + + + + + + +

+ Decentralized Commerce - Your shop exists on Nostr + relays, not a single server. No platform fees, no deplatforming risk. +

+

+ Lightning Payments - Accept instant, low-fee Bitcoin + payments via the Lightning Network. +

+

+ Encrypted Messages - Communicate privately with + customers using NIP-04 encrypted direct messages. +

+

+ Portable Identity - Your merchant reputation travels + with your Nostr keys across any compatible marketplace. +

+

+ Global Reach - Your stalls and products are + automatically visible on any Nostr marketplace client that supports + NIP-15, including Amethyst, Plebeian Market, and others. +

+ + + + + + + +

+ Browse the Market - Use the Market Client to discover + stalls and products from merchants around the world. +

+

+ Pay with Lightning - Fast, private payments with + minimal fees using Bitcoin's Lightning Network. +

+

+ Direct Communication - Message merchants directly via + encrypted Nostr DMs for questions, custom orders, or support. +

+ + + + + + + +

This extension was created by:

+
Tal Vasconcelos - + Tal Vasconcelos + + Ben Arc - + Ben Arc + + motorina0 -

- Swagger REST API Documentation - - - Visit the market clientMarket client - - + target="_blank" + class="text-decoration-none" + > + motorina0 + + + Ben Weeks + +
+ + + + + + + + + + + + Market Client + Browse and shop from stalls + + + + + + + + + + + + API Documentation + Swagger REST API reference + + + + + + + + + + + + NIP-15 Specification + Nostr Marketplace protocol + + + + + + + + + + + + Report Issues / Feedback + GitHub Issues + + + + + diff --git a/templates/nostrmarket/index.html b/templates/nostrmarket/index.html index d95d965..a646eee 100644 --- a/templates/nostrmarket/index.html +++ b/templates/nostrmarket/index.html @@ -166,13 +166,21 @@
+ -
- {{SITE_TITLE}} Nostr Market Extension -
+
Nostr Market
+
+ A decentralized marketplace extension for LNbits implementing the + NIP-15 protocol. Create stalls, list products, and accept Lightning + payments while communicating with customers via encrypted Nostr + direct messages. +
- {% include "nostrmarket/_api_docs.html" %} From 65a6bb3786f5eecde7079c2ff5e8af6a8beac286 Mon Sep 17 00:00:00 2001 From: Ben Weeks Date: Tue, 23 Dec 2025 16:28:05 +0000 Subject: [PATCH 8/8] fix: correct Ben Arc's GitHub URL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- templates/nostrmarket/_api_docs.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/nostrmarket/_api_docs.html b/templates/nostrmarket/_api_docs.html index e61cd62..664d6ba 100644 --- a/templates/nostrmarket/_api_docs.html +++ b/templates/nostrmarket/_api_docs.html @@ -123,7 +123,7 @@ Tal Vasconcelos