hermes-shop

Hermes Shop

Overview

Hermes Shop is a standalone shop app that Hermes can operate conversationally. It should help a user create products, edit products, upload product images, configure site copy, and manage per-shop Stripe checkout plus Shippo shipping/labels.

Important reference:

• references/stripe-onboarding-and-product-model-ui.md — session learning on per-shop Stripe onboarding, product model visibility, and avoiding Jungle framing.

Current test deployment:

• App: /home/avalon/apps/hermes-shop
• URL: https://shop.apps.poofc.com
• PM2: hermes-shop
• Port: 4039
• Data: /home/avalon/apps/hermes-shop/data/shop.json

This skill is for operating Hermes Shop directly and for shaping the future Hermes Spawn optional shop add-on.

Conversational Rule

Be short and practical. If the user did not provide enough information, ask only for the missing fields needed for the next action. For setup/onboarding flows, use one clear next step at a time and avoid long explanatory checklists unless Alex asks for a plan.

Good:

I can add it. I need the product name, price, and whether it ships.

Good for Stripe:

I can connect Stripe. I need the Stripe account or permission to start a new Connect onboarding link.

Bad:

To create a comprehensive commerce object, please provide...

Product Model

A product can include:

• title — required
• description
• type — physical, digital, or service
• status — draft, active, or archived
• priceCents, currency, taxable, compareAtCents, costCents
• sku, barcode, inventory
• tags
• images[] — { id, url, alt, role }
• variants[] — { id, title, options, priceCents, sku, inventory, imageUrl, active, stripePriceId }
• shipping — package/weight/origin fields
• stripe — product/price/checkout fields
• shippo — provider defaults for rates/labels
• fulfillment — tracking/label/status fields
• metadata — flexible extra data

UI rule: product cards must expose readable model details in the app, not only JSON/API output. At minimum show type, status, SKU, inventory, Stripe product/price state, Shippo state, fulfillment state, and optional raw JSON.

Required Fields by Action

Create simple draft product

Need:

• product title
• price
• product type, if not obvious

If missing, ask:

What should I call it, and what price should it be?

Publish / activate product

Need:

• title
• price
• at least one image or explicit approval to publish without image
• Stripe checkout ready, if taking payment now
• for physical products: weight/package details or explicit manual shipping choice

If missing, ask one compact question listing only missing pieces.

Upload product image

Need:

• product id/title
• image file, URL, or data URL
• optional alt text

Use:

curl -fsS -X POST http://127.0.0.1:4039/api/products/<id>/images \
  -H 'Content-Type: application/json' \
  --data-binary '{"dataUrl":"data:image/jpeg;base64,...","alt":"Front of product"}'

Edit product info

Need:

• product id/title
• fields to change

Use PUT /api/products/:id with only changed fields.

API Quick Reference

GET    /api/health
GET    /api/shop
GET    /api/products
GET    /api/products/:id
PUT    /api/site
GET    /api/stripe/config
PUT    /api/stripe/config
POST   /api/stripe/onboarding-link
POST   /api/products
PUT    /api/products/:id
DELETE /api/products/:id
POST   /api/products/:id/images

Base URL:

http://127.0.0.1:4039

Recipes

Inspect current shop

curl -fsS http://127.0.0.1:4039/api/shop | jq .

Create or update a product

curl -fsS -X POST http://127.0.0.1:4039/api/products \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "title":"Example Product",
    "type":"physical",
    "status":"draft",
    "priceCents":2500,
    "currency":"USD",
    "inventory":5,
    "shipping":{"requiresShipping":true,"weightValue":8,"weightUnit":"oz"}
  }' | jq .product

Archive a product

curl -fsS -X PUT http://127.0.0.1:4039/api/products/<id> \
  -H 'Content-Type: application/json' \
  --data-binary '{"status":"archived"}' | jq .product

Update site config

curl -fsS -X PUT http://127.0.0.1:4039/api/site \
  -H 'Content-Type: application/json' \
  --data-binary '{"headline":"New headline","statusText":"Live"}' | jq .site

Site Hero / Storefront Copy

The storefront hero is intentionally minimal and image-led. Site config supports:

• name
• eyebrow
• headline
• subheadline
• statusText
• ctaLabel
• heroImage — optional URL/path for the hero background

Current frontend fallback order for the hero background:

1. site.heroImage
2. first available product primary image
3. /shop-hero.svg

For “clean up the hero” requests, prefer one big background image, a short eyebrow/title, and a single product-scroll CTA. Avoid restoring multiple parallel CTAs or verbose descriptive subcopy in the hero unless asked. If Alex asks for “featured product” language, set the hero title to a concise product feature label such as Feature product one instead of repeating Hermes Shop.

Shop Navigation and Modal UI Pattern

Hermes Shop should separate customer-facing browsing from operator/configuration screens:

• Keep the storefront/product grid as the default view.
• Put a hamburger menu in the top corner for secondary views.
• Move Stripe configuration/onboarding into its own view reachable from the side panel; do not leave it inline between hero and products.
• Move raw JSON / edit config tooling into its own view reachable from the side panel; label it clearly as Edit config or similar.
• Product cards should open a modal/detail overlay instead of expanding inline on the page.

Reusable modal direction:

• Prefer a small shared React component (e.g. OverlayModal) inside Hermes Shop for product details and future shop overlays.
• Style it after Hermes Creative overlays: fixed dim/blur backdrop, cream rounded panel, sticky top bar, and black circular close button.
• On mobile product/detail modals should be true full-screen app surfaces: no top gap, no side gutters, inset:0, padding:0 on the backdrop, full viewport-height panel, and safe-area padding inside the panel only.
• Product modals should show the product image or placeholder, description, price/action, readable model fields, and optional raw JSON.
• Keep the modal component generic enough to reuse for other Hermes Shop panels later, rather than hard-coding only product behavior.

Performance and motion rules for reusable overlays:

• Do not make product/detail modals feel like clunky popups. Opening/closing should be subtle, fast, and component-quality because this pattern will be reused.
• Avoid immediate unmount on close. Keep an internal rendered/is-closing state so the close animation plays, then unmount after the transition.
• Animate only cheap compositor properties (transform, opacity) with a short duration (~180–220ms) and will-change; avoid heavy blur/backdrop-filter transitions on modal surfaces.
• Preserve the last selected product/content during the closing state so text/media do not disappear before the animation finishes.
• Include a prefers-reduced-motion: reduce override.
• Make the close affordance large enough for mobile use (roughly 54–56px circular button, larger ×).

Product grid sizing rules:

• Below the hero, product cards should feel substantial, not tiny. Prefer a two-column grid for the main product shelf rather than switching to three narrow columns at tablet/desktop browser widths.
• Use square/large product art (aspect-ratio: 1/1) and slightly larger card padding/title sizing on wider viewports, with tighter spacing only on narrow mobile.

Stripe Direction

Stripe is a payment processor, not the catalog source of truth. Each Hermes Shop gets its own Stripe configuration under integrations.stripe; never treat Stripe as one global account for all tenant shops.

Current config operations:

curl -fsS http://127.0.0.1:4039/api/stripe/config | jq .

curl -fsS -X PUT http://127.0.0.1:4039/api/stripe/config \
  -H 'Content-Type: application/json' \
  --data-binary '{"mode":"test","businessName":"Example Shop","accountId":"acct_...","publishableKey":"pk_test_...","onboardingComplete":true}' | jq .

The UI has a Stripe onboarding panel. Stripe Connect Standard OAuth is wired through POST /api/stripe/onboarding-link and GET /api/stripe/oauth/callback. It requires platform env vars STRIPE_SECRET_KEY and STRIPE_CONNECT_CLIENT_ID (or STRIPE_CLIENT_ID).

Current live operations when env is configured:

• create Stripe Standard OAuth connect URL per shop/tenant
• store connected acct_... and publishable key under integrations.stripe
• sync product → Stripe Product in the connected account
• sync price → Stripe Price in the connected account
• create Checkout Session in the connected account via POST /api/checkout/:id
• store Stripe ids under product.stripe / variant.stripePriceId
• never store card data in Hermes Shop
• store provider secrets in env/secret storage, not product JSON

Do not claim live checkout is enabled unless the Stripe account is connected and a checkout/session endpoint is verified.

Shippo Direction

Shippo handles shipping rates, labels, and tracking.

Planned operations:

• create shipment from product package + customer address
• fetch rates
• buy label
• store label/tracking fields under fulfillment
• refresh tracking status
• use environment variables for Shippo secrets

For physical products, ask for package weight/dimensions before enabling shipping automation.

Spawn Add-on Direction

When this becomes a Spawn add-on:

1. Provision a shop per tenant or a multi-tenant shop service.
2. Seed site config from tenant name/brand.
3. Give tenant Hermes this skill with its own base URL/data path.
4. Keep shop app separate from the Spawn control plane UI.
5. Store provider secrets in tenant env/config, not in product JSON.
6. Let Hermes manage catalog and site config through APIs.

Scoped Spawn Broker Artifact

When packaging a standalone Hermes Shop build for the scoped Spawn deployment broker:

1. Put the compiled dist/, tenant data/shop.json, product uploads, and a dependency-free server.js at the artifact root.
2. The broker starts exactly node server.js; if server.js uses ESM imports, include a root package.json with {"private":true,"type":"module"}.
3. Include a root deployment-manifest.json with all required identity/runtime fields:

{
  "tenantId": "tenant-id",
  "appName": "shop-app-name",
  "runtime": "node",
  "start": "node server.js",
  "healthPath": "/healthz",
  "hostnames": ["shop.example.com"]
}

4. The submit request needs matching appName, artifact path, SHA-256, verification.healthPath, and requested hostnames. Manifest hostnames may be a superset, but every requested hostname must be declared.
5. Verify the checksum after copying the archive into the tenant container, then submit from inside the tenant with /data/hermes/bin/spawn-deploy <request.json>.
6. A successful application deployment may return dns_pending; that means PM2/local nginx are live but authoritative DNS/TLS is not ready. Verify localHealth, every localNginx result, PM2 status, and authoritative DNS separately.

Build / Deploy

cd /home/avalon/apps/hermes-shop
npm run build
pm2 restart /home/avalon/apps/ecosystem.config.js --only hermes-shop --update-env
pm2 save
npm run smoke
curl -fsS https://shop.apps.poofc.com/api/health

Pitfall: restarting by bare PM2 process name (pm2 restart hermes-shop --update-env) can pick up the caller's current environment instead of the ecosystem file and may drop the configured PORT=4039. Use the ecosystem restart form above for deploys.

Verification Checklist

• [ ] npm run build passes.
• [ ] npm run smoke passes.
• [ ] PM2 hermes-shop is online on port 4039.
• [ ] Public health endpoint returns ok: true.
• [ ] Product/site changes persist in data/shop.json.
• [ ] For image uploads, returned URL loads publicly under /uploads/....
• [ ] Do not claim Stripe or Shippo live behavior unless the endpoint and provider credentials are verified.