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.

db/products.json

{ "products": [ …​ ] } — products and curated-list products in one array, told apart by type.

db/bundles.json

{ "bundles": [ …​ ] } — bundles and curated-list manifests in one array, told apart by type.

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/" }
}

type

product, or curated-list for a list (see Curated list).

id

The store’s own record key (a UUID). Store-specific; never a cross-store identity.

name

The portable identity: a scoped package-style name, @scope/name. Two stores listing the same name list the same product. For an installable it equals the registry package name.

title, developer, publisher

Display claims. developer is required; publisher is optional.

description, tags, platforms, date_release

The facets that filter, search and sort operate on, uniform regardless of card style. platforms is what the thing runs on (Windows, macOS, Linux, browser, …​), not architectures. date_release must be an ISO 8601 date, YYYY-MM-DD; the NEW badge is derived from it.

display

The card style, one of { "type": "single-row" }, { "type": "ImgBanner230", "img": "<url>" } or { "type": "rendered", "html": "<html>" }.

price-block

currency (ISO 4217) and price are required. -1 means not commerce (plain INSTALL), 0 is Free through the bag, > 0 is the regular price. discounted-price is the current sale price; price stays the regular one and is rendered struck through, with the badge percentage derived. donate: true makes it pay-what-you-want, with price as the suggested amount.

install-spec

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.

registry

{ "method": "registry", "name": "@scope/name", "registry": "https://registry.npmjs.org/" } — an npm-protocol registry. name equals the product name. Optional pins vet exact versions per platform.

vendor

{ "method": "vendor", "name": "@scope/name", "pins": { …​ } } — a vendor-hosted artifact. pins is required, and every pin carries a url. Optional run-at: on-demand, user-initiated, logon or boot.

observable

{ "method": "observable", "cxn-pt": {} } — a curated list: the consumer polls a store endpoint instead of fetching a package. Author cxn-pt empty; the store fills in its own endpoint when it serves the record.

app-store

{ "method": "app-store", "storefront": "apple", "app_id": "…​" } — a third-party native store (apple, steam or epic) owns distribution and integrity.

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 } ] }
	]
}

type

bundle, the catalog kind, or manifest, the contents of a curated list (see Curated-list manifest).

id

The store’s own record key. For a manifest it is the id of the curated-list product whose contents it is.

name

The portable identity, @scope/name, as for a product. This store requires it on a bundle: that is how a reference resolves to it.

title, description, developer, publisher, date_updated

Both kinds. For a manifest, publisher is the list’s author.

date_release, display, price-block, oses

bundle only — the catalog face. A manifest must not carry them: a list is updated, not released, and its commerce and presentation live on its curated-list product.

refs

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:

http+json-rpc

The direct json-rpc endpoint, :9944.

ipsme+tcp+l4end

The IPSME reflector endpoint, :4998.

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"]}' `