discovered-store
Store Catalog
The store’s catalog is authored as plain JSON in the db/ directory. Adding a product or a bundle is a file edit, not a recompile. Every record follows the ProductsAndBundles interface, and the store validates everything it serves against it.
|
|
|---|---|
|
|
The files are read per request, so an edit is served on the next call. In the docker deployment db/ is bind-mounted read-only into the container (DISCOVERED_DB_DIR in docker/compose.yaml), so no image rebuild is needed either. On start-up the store serves everything in db/ once and validates it: a missing file, malformed JSON, or a record that fails the schema aborts the boot (visible in the docker logs) rather than being served around.
Add a Product
Append an object to the products array of db/products.json. Required by the interface: type, id, title, developer, platforms, price-block and install-spec. The identity fields (type, id, name) are immutable for the product’s lifetime — changing one makes it a different product.
{
"type": "product", "id": "7D4E1F2A-9C3B-4A5D-8E6F-0B1C2D3E4F5A", "name": "@scope/my-translator", "title": "my-translator",
"developer": "Developer AB", "date_release": "2026-11-03", "platforms": [ "Windows", "macOS" ],
"description": "One line describing the product; this is what full-text search operates on.",
"tags": [ "IPSME", "Translator" ],
"display": { "type": "single-row" },
"price-block": { "currency": "USD", "price": -1 },
"install-spec": { "method": "registry", "name": "@scope/my-translator", "registry": "https://registry.npmjs.org/" }
}
|
|
|---|---|
|
The store’s own record key (a UUID). Store-specific; never a cross-store identity. |
|
The portable identity: a scoped package-style name, |
|
Display claims. |
|
The facets that filter, search and sort operate on, uniform regardless of card style. |
|
The card style, one of |
|
|
|
How to get and verify the product; validated against the InstallSpec interface. See below. |
name is optional in the interface, but this store requires it: references resolve by name, so a record without one is rejected at boot, and a name must be unique across db/products.json and db/bundles.json together.
|
install-spec
method selects one of four shapes.
|
|
|---|---|
|
|
|
|
|
|
pins is keyed by platform (win32, darwin, linux, or * for all), each an append-ordered list of vetted versions. A pin carries the exact version, the whole-file sha2-384 (shasum -a 384) and the artifact role: self-contained (the payload is the app), self-exe (the payload installs the app) or os-package. A vendor pin adds url and optionally format.
"pins": {
"win32": [ { "version": "1.0.0-win32", "artifact": "self-contained", "sha2-384": "<hex>" } ],
"darwin": [ { "version": "1.0.0-darwin", "artifact": "self-contained", "sha2-384": "<hex>" } ]
}
Curated list
A curated list is a product with type: "curated-list" and an observable install-spec. The product carries the list’s identity, presentation and commerce; its contents live in a manifest bundle with the same id in db/bundles.json (see Curated-list manifest).
{
"type": "curated-list", "id": "CL-0003-MY-LIST", "name": "@scope/my-list", "title": "My List",
"developer": "Developer AB", "date_release": "2026-11-03", "platforms": [ "browser" ],
"description": "What this list collects.",
"tags": [ "Curated List" ],
"display": { "type": "single-row" },
"price-block": { "currency": "USD", "price": -1 },
"install-spec": { "method": "observable", "cxn-pt": {} }
}
Check that the record is served through the store’s direct json-rpc endpoint:
`
$ curl -s -X POST http://<own-host>:9944/rpc -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"get_products","params":[["@scope/my-translator"]]}'
`
Add a Bundle
Append an object to the bundles array of db/bundles.json. A bundle is a collection of references (refs) to products or bundles by their portable name. Required by the interface: type, id and refs. It is one object with two kinds, discriminated by type.
{
"type": "bundle", "id": "3F8A6B1C-2D4E-4F5A-9B7C-8D9E0F1A2B3C", "name": "@scope/my-stack", "title": "My Stack",
"developer": "Developer AB", "date_release": "2026-11-03",
"description": "A set of products offered together.",
"display": { "type": "single-row" },
"price-block": { "currency": "USD", "price": 99, "discounted-price": 49 },
"refs": [
{ "name": "@scope/my-translator", "cxn-pts": [ { "protocol": "http+json-rpc" }, { "protocol": "ipsme+tcp+l4end" } ] },
{ "name": "@other/their-product", "cxn-pts": [ { "protocol": "http+json-rpc", "address": "store.example.com", "port": 9944 } ] }
]
}
|
|
|---|---|
|
The store’s own record key. For a |
|
The portable identity, |
|
Both kinds. For a |
|
|
|
The contents, as references. See below. |
refs
Each reference is a name plus cxn-pts, the connection points where that product or bundle can be fetched. The name is the portable identity, never the store-specific id, and may name something this store does not host; the consumer resolves it through the cxn-pts. A connection point follows the ConnectionPoint interface: either a string, protocol://address:port, or an object, { "protocol", "address", "port" }.
For products this store hosts itself, author only the protocol: { "protocol": "http+json-rpc" } or "http+json-rpc://:". The store fills in its own address and port when it serves the reference. It hosts two transports:
|
The direct json-rpc endpoint, |
|---|---|
|
The IPSME reflector endpoint, |
A connection point that already carries an address, or names a protocol this store does not host, is left untouched.
Curated-list manifest
The contents of a curated list are a bundle of kind manifest, whose id equals the id of the curated-list product in db/products.json (see Curated list). It is served inside the CuratedList envelope and never in results.
{
"type": "manifest", "id": "CL-0003-MY-LIST", "name": "@scope/my-list", "title": "My List",
"publisher": "Developer AB", "date_updated": "2026-11-03",
"description": "What this list collects.",
"refs": [
{ "name": "@scope/my-translator", "cxn-pts": [ { "protocol": "http+json-rpc" }, { "protocol": "ipsme+tcp+l4end" } ] },
{ "name": "@scope/my-stack", "cxn-pts": [ { "protocol": "http+json-rpc" }, { "protocol": "ipsme+tcp+l4end" } ] }
]
}
Check that the manifest is served, by the list’s id:
`
$ curl -s -X POST http://<own-host>:9944/rpc -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"get_curated_list_contents","params":["CL-0003-MY-LIST"]}'
`