Operator guide

​

What gets deployed

​

Routing, and the trap in it

"rewrites": [
  { "source": "/discovery/resources", "destination": "/api/discovery/resources" },
  { "source": "/discovery/search",    "destination": "/api/discovery/search" },
  { "source": "/discovery/health",    "destination": "/api/discovery/health" },
  { "source": "/discovery/:path*",    "destination": "/api/discovery/unknown" },
  … 5 facilitator rules (/supported, /verify, /settle, /health, /events) → /api/facilitator
  … 2 seller rules (/v1/:path*, /.well-known/x402)                      → /api/seller
  { "source": "/(.*)",                "destination": "/index.html" }
]

​

First deploy

• Root Directory — the repository root (not apps/web). The api/ directory and packages/index both live above apps/web; pointing the root at apps/web hides them and the discovery endpoints will 404.
• Framework Preset — Other. vercel.json already pins buildCommand, installCommand and outputDirectory.
• Node.js version — 22.x.

​

The custom domain

The CNAME target is per-project. Vercel issues a unique hostname such as d1d4fc829fe7bc7c.vercel-dns-017.com. Older guides say cname.vercel-dns.com — do not paste that from memory, and do not reuse a value from another project. The same goes for the apex A record: read both off the project’s Domains screen.

dig @<registrar-ns> stellarsight.xyz A +short
curl -s https://stellarsight.xyz/discovery/health | jq '.mode, .records, .build.commitShort'

​

Environment variables

​

The faucet’s blast radius

​

Caller authentication, metering and rate limiting

• Durable when a store is configured, per-instance when it is not. The transport is whatever createKv() resolves, the same Redis the catalog uses.
• Fails open. If the store is unreachable the request is counted per-instance and the response carries X-RateLimit-Degraded: per-instance instead of being refused. A limiter that 500s when Redis blinks is a worse outage than the one it prevents.
• The raw IP is never stored or logged — only a truncated SHA-256 of the first x-forwarded-for hop becomes a key.
• A refusal is machine-readable, like every other rejection here: 429 with Retry-After, code: "STELLARSIGHT_RATE_LIMITED" and a non-null reason naming the limit, the window and when to retry.

curl -s https://stellarsight.xyz/health | grep -o '"rateLimit":{[^}]*}'
# {"rateLimit":{"enabled":true,"perCallerPerWindow":120,"globalPerWindow":null,"windowSeconds":60}}

​

The business model

​

Two ways to reach Redis, and which one you get

• REST — KV_REST_API_URL + KV_REST_API_TOKEN. An HTTPS API, stateless, no connection to hold. Vercel KV and Upstash both expose it. Preferred when present, because a function that may be frozen mid-request is a bad place to own a TCP socket.
• Redis protocol — KV_REDIS_URL, e.g. rediss://default:<password>@<host>.example.com:6379. Spoken over TCP through the redis package.

Prefix tip. Connecting a Marketplace database asks for an environment-variable prefix. KV is the convenient one: the REST pair lands as KV_REST_API_URL / KV_REST_API_TOKEN and, on providers that expose it, the protocol URL lands as KV_REDIS_URL — all three names this code already reads. Whatever prefix you choose, check the generated names against the table above; a URL under any other name (KV_URL, REDIS_TLS_URL, a provider-specific one) is invisible to this code until you add KV_REDIS_URL or REDIS_URL yourself pointing at the same value.

Adding the variables is not enough on its own. Vercel binds environment variables at deploy time, so a deployment created before you attached the database keeps running without them and /discovery/health will keep reporting mode: seed with durableStore.configured: false. Redeploy — push a commit, or use Redeploy in the dashboard — and check health again. This is the single most common reason a correctly configured store appears not to work.

​

Catalog state: the two modes

​

seed — the zero-configuration default

​

kv — durable and shared

• Cold start: seed corpus first, then every record in the store. Store records win on a shared id, and because seeded is re-derived on each upsert, a real announcement clears the seed flag — the same ordering apps/facilitator relies on locally.
• Storage: one Redis hash, id -> JSON(record). A hash rather than one blob because HSET on a field is atomic, so two function instances cataloging different resources concurrently cannot clobber each other.
• Propagation: a write forces the next read on that instance to reload; other instances pick it up within STELLARSIGHT_KV_TTL_MS.

​

Verifying a deployment with curl

# 1. Which mode is live, how many records, which commit
curl -s https://stellarsight.xyz/discovery/health | jq

# 2. Search — ranked, with the score breakdown. NOTE the array is `resources`, not
#    `items`: the search and list envelopes differ deliberately (see CONTRACT.md).
curl -s 'https://stellarsight.xyz/discovery/search?query=invoice%20ocr&limit=3' | jq \
  '.resources[] | {resource, name: .serviceName, score: ._score, price: .accepts[0].amount}'

# 3. The full _explain on the top hit
curl -s 'https://stellarsight.xyz/discovery/search?query=invoice%20ocr&limit=1' \
  | jq '.resources[0]._explain'

# 4. List with filters — the LIST endpoint uses `items` and offset pagination
curl -s 'https://stellarsight.xyz/discovery/resources?type=mcp&limit=5' | jq '.total, .items[].resource'

# 5. Cursor pagination
CURSOR=$(curl -s 'https://stellarsight.xyz/discovery/search?query=stellar&limit=2' | jq -r .pagination.cursor)
curl -s "https://stellarsight.xyz/discovery/search?query=stellar&limit=2&cursor=$CURSOR" | jq '.resources[].id'

# 5b. What a stock consumer sees: the payable offer, straight off a search hit
curl -s 'https://stellarsight.xyz/discovery/search?query=invoice%20ocr&limit=1' \
  | jq '.resources[0] | {resource, x402Version, lastUpdated, accepts}'

# 6. CORS preflight — must answer 204 with Access-Control-Allow-Origin: *
curl -s -i -X OPTIONS https://stellarsight.xyz/discovery/resources | head -8

# 7. The SPA catch-all must NOT shadow the API: this must be JSON, not text/html
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' \
  'https://stellarsight.xyz/discovery/search?query=test'

# 8. Write path (kv mode + STELLARSIGHT_WRITE_TOKEN only)
curl -s -X POST https://stellarsight.xyz/discovery/resources \
  -H "Authorization: Bearer $STELLARSIGHT_WRITE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"resource":{"url":"https://api.example.com/v1/thing","serviceName":"Thing",
        "description":"Does a thing, described well enough to be discoverable.",
        "tags":["thing"]},
       "type":"http","payTo":"G...","asset":"C...","maxAmountRequired":"1000",
       "input":{"type":"http","method":"GET"},"output":{"type":"json"},
       "extensions":["bazaar"]}' | jq

​

Verifying before you deploy

npm run verify:api

docker run -d -p 6399:6379 redis:7-alpine
STELLARSIGHT_TEST_REDIS_URL=redis://127.0.0.1:6399 npm test

​

The web console: LIVE vs DEMO

• VITE_INDEX_URL if set (an explicit override wins everywhere),
• otherwise '' in a production build — a same-origin relative base, so the deployed console calls its own /discovery/* with no CORS hop and no configuration,
• otherwise http://localhost:4022 in the dev server.

​

Known behaviour

• /discovery/integrity returns 404. The console probes it opportunistically for a live validation ledger; no build of the index exposes it yet (the local index on :4022 does not either), so the console falls back to its baked ledger. The probe is wrapped in a try/catch and the 404 is expected.
• GET /discovery/search without a query parameter is a 400, per the bazaar spec. A present-but-empty query is a browse over the whole filtered catalog.
• Cold starts. The first request after an idle period pays for module load plus seeding. The console allows 4s in production before falling back to DEMO.