The manifest

manifest.json is the only required file of a package and the whole contract between a module and the platform. Types live in core-lib entities/module.ts (mirrored into admin/src/components/form/schemas.ts); the validator is validateManifest in core-lib utils/module_manifest.ts, run by the server, the console's upload pre-flight and the starter's module:pack alike (§7).

2.1 ModuleManifest#

Two non-fields worth knowing: the module id becomes the install doc id on a store, so a store cannot hold two modules of one id from different owners (409 id_installed); and the registry key is {id} for a platform package and {org}~{id} for an organization package (~ is outside MODULE_ID_PATTERN, so keys never collide across owners).

hosting: 'none' — an elements module#

A module that is only an element library (.dev/plans/modules/elements-modules.md). validateManifest gives it the identity rows (id, name, description, category, version, vendor, tags) and these only:

{
  "id": "acme-blocks",
  "name": {"cs": "Acme bloky", "en": "Acme blocks"},
  "description": {"en": "Hero, pricing and FAQ sections in the Acme style."},
  "category": "elements",
  "version": "1.0.0",
  "vendor": {"name": "Acme Studio", "url": "https://acme.example"},
  "hosting": "none",
  "kits": ["blocks"]
}

The package is a subset of §7.1 — manifest.json, README.md / docs/{locale}.md, docs/elements.md (expected when a kit ships a global.js), CHANGELOG.md, kit/{kitId}/…, translations/ — and nothing that runs (static_file, §7.3). What the platform does with it: the check stops at stage 2 (no dry run); the install mounts the kits, the runtime doc and the translations and writes the install doc — no grants step, no handshake, no token, no custody, no setup/hooks entries, no setup/modules (§8.2); configure / verify / reroll and the API call verb answer 409 {error: 'not_applicable', hosting: 'none'}, logs an empty list; every entry point that would route to a module (Gateway.call, the storefront web leg behind /m/{id}, the hook ingress event leg) answers 404 module_static — except the unauthenticated inbound-webhook leg (/hook/module/{sid}/{id}/inbound/…), which answers the same 404 {error: 'not_found'} as an unknown module so a caller learns nothing about what is installed — and the scheduler / outbox / notifier skip such an install — so a hand-edited install doc can route nowhere. The hosting is fixed per module: a version that changes it is refused at upload (hosting_immutable, §7.3) and by update (409 hosting_changed, §8.3). enable / disable work as for every module and drive the render gate (§8.2a).

2.2 ModuleFieldSpec — config fields#

Non-secret values land on ModuleInstall.config and ride every envelope as config (§3), so a module never reads its own install doc per call. Secret values are stored write-only and the module reads them itself (§5).

2.3 Categories#

One category per module, from a closed list, so the catalog groups stably and the console can translate it (modules.category.* in both locale files). A module that spans two areas picks the one its primary extension point serves and puts the other in tags. The category has exactly one functional use — the setup pages' from modules shortcuts list the installed modules of that category; it grants nothing.

Rules: an unknown id is 422 manifest_invalid: category; the catalog (POST /api/module/catalog {category?}) filters and the Modules page groups by it; the catalog card shows category + tags. Adding a category = one entry in MODULE_CATEGORIES, two i18n keys, one row in the plan's table and one here; no data migration (installs snapshot the manifest).

2.4 provides — targeting a whole core contract#

Most manifest keys are seams: one place in the core that calls one point of the module. A carrier is not a seam, it is a contract — a setup card in a specific tab, a tag that delivery methods and orders carry, five verbs the order page calls in a fixed order, a poller with a per-carrier budget, a status machine that must not be bypassed. category: 'shipping' cannot stand in for it because the category is inert by design. provides[] is the manifest's way to say I implement contract X, so the core mounts the module wherever a built-in implementation of X would be mounted. One entry per kind; four kinds exist — carrier (built, below), invoicer (issuing built — Part A2, below), orders (the push / cancel / events runtime built — Part O1, below), payment (a redirect gateway — Part G2, below). The tag a store selects is always module:{id}.

A module providing both invoicer and orders (an ERP) is accounting. category still grants nothing; what a kind earns is decided by provides alone:

• Grants — the install token's access.module is never taken from manifest.access (it is stripped before the intersect); the install handler adds one sub-key per declared kind: shipment.events (carrier), invoice.{events, pending} (invoicer), payment.events (payment), order.events (orders). An update that adds a kind widens the grants (409 grants_pending until accepted).
• Selection — a store may pick a module provider only while it is installed, provides the kind, is enabled and verified: provider_tag_invalid 400, {kind}_unknown 400 (carrier_unknown), {kind}_unsupported 501, provider_disabled 409, provider_unverified
  409. For carriers this guards every enabled row of setup/delivery.methods (POST /api/admin/shipping/setup {methods}; a row saved enabled: false is parked and not checked) and its service must be one of the entry's services[].code (400 carrier_service_unknown).
• Call time — a disabled or unverified module provider fails closed before any call (409 module_disabled); the storefront's delivery options (POST /api/public/shipping/options, the tenant's POST /delivery/:locale) omit the methods of a module carrier that is not selectable, and an order naming one is 409 carrier_unavailable. Not covered: a client that reads the public setup/delivery doc directly, and the Studio preview — both still fail closed at order time.
• Gateway — the ten provider callbacks run with a 20 s deadline, a 64 KiB cap (invoice.pdf: 4 MiB, the label cap), the error fallback and no cache. Failures map through one table (refusalOf): a disabled / not installed module → module_disabled 409, a plan lapse → tier_required 403, a transport failure or any other platform refusal → module_failed 502, a body {ok: false, error?, message?, retry?} → the domain's own error (carrier_error for carriers).
• Disable / update / uninstall — see §8.3–§8.5: a disable answers warnings, an update may not drop a selected kind, an uninstall is refused while work the module owns is open.

The carrier entry:

{kind: 'carrier',
 services: Array<{code; name: Record<locale, string>; kind: 'home' | 'point' | 'box'; countries?: string[]; cod?: boolean; point_types?: string[]}>,
 label_formats: Array<'pdf' | 'zpl'>,     // what shipment.label can return
 points?: boolean, rates?: boolean, cancel?: boolean, manifest?: boolean,   // which optional verbs it implements
 tracking: {poll: {interval: '30m' | '1h' | '6h'; daily_quota?: number}; push?: boolean}}

A carrier entry requires category: 'shipping', callbacks ⊇ {shipment.createShipment, shipment.label, shipment.track}, and shipment.cancel / shipping.points / shipping.rates / shipment.manifest exactly when cancel / points / rates / manifest are set; points is required when any service is point / box. The carrier tag on orders and delivery methods is module:{id}. Every shipment.createShipment request carries key: '{oid}:s{n}' (n = the order's shipping.attempts, bumped by every cancel) — a carrier module must dedupe on it: a retried create with the same key answers the shipment it already made. A create that lost the race to a concurrent one cancels its own (different) shipment best-effort when the carrier has cancel. Named but not designed: mailer — a new kind is a plan amendment first.

How the core calls a carrier module (functions/src/modules/shipping/module_adapter.ts — ModuleCarrierAdapter, resolved by the carriers registry for any module:{id} tag). Each verb is ONE gateway callback, the carriers plan's own shapes as input, the answer as the top-level body:

A body {ok: false, error?, message?} is the module's own refusal (the order card shows message); a timeout / network failure is 502 module_failed, a disabled install 409 module_disabled. ShipmentRequest.items[].meta carries this module's own products.modules.{id} fields when the manifest lists products in data.entity_fields. Push tracking: POST /api/module/shipment/events {order, events} on the install token (the only /api/module/* route a module token calls — the install grants module.shipment.events to a carrier); the module id is read from the token, the order must carry shipping.service === 'module:{id}' (403 not_own_shipment), and the events go through the same tracker sink as a poll. The tracker polls a carrier module on tracking.poll.interval (the first rung of the 30 min → 1 h → 2 h → 6 h ladder; every 6 h with push: true) within daily_quota per store (429 quota_exhausted past it). Uninstall answers 409 shipments_open {module, orders ≤ 50} while an order it owns is in shipping / delivery (the composite index orders (shipping.service, status)), and disables (never deletes) the delivery methods that name it.

How the core calls an invoicer module (functions/src/modules/invoicing/ — ModuleInvoicer, Part A2). A store switches with POST /api/admin/invoicing/provider {provider: 'module:{id}'} (owner / master; the module must be selectable). From then on every issuing transition of an order (completed → period: 'once'; a subscription's start → its period end in seconds, else 'start'; a renewal → the new period end) writes a pending entry order.invoicing.{period} = {provider, key, reason, state: 'calling', attempts, at, covers?} and the token invoicer:module:{id} into order.providers_pending — in the same write as the status move — and ONE call runs from the providerCallTask queue (never inside a trigger, never retried by the platform):

pdf and send are called on demand by POST /api/public/invoice: invoice.pdf once, on the first PDF request for a document whose IssueResult.pdf was true (the platform keeps the copy), invoice.send when the invoice mail is requested and the document was issued with delivery: 'provider'. Every other surface of your document hands off to IssueResult.url — the buyer never sees a platform rendering of it.

Proformas — the advance document of a bank-transfer order. It is NOT an invoice: the answer becomes order.proforma (never invoices/ or order.invoices). It rides the same pending machinery under the period 'proforma' (retry, invoice/pending with request.reason === 'proforma', the issued event). Report its state with document: 'proforma' + order on the state events ({event: 'paid' | 'unpaid' | 'cancelled' | 'restored', number, document: 'proforma', order, paid_on?, amount?, currency?}) — paid settles the order, which then turns ready and asks for the final invoice at once with request.proforma = {number, ref?, paid_on?}: link or adopt your own final document (Fakturoid issues a paid final_invoice from the paid proforma itself). A proforma paid after the order closed only raises payment_alert: paid_after_close.

Dedupe on key ({oid}:{period}, …:r{n} after a manager's Reassign): a repeated key must answer the first document. number becomes the invoice doc id and order.invoices[] — ^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$ (put a printed form like 2026/0001 in label), ref ^[A-Za-z0-9_:-]{1,128}$, urls https; anything else is a failed issue (invoice_number_invalid, retry: false). A number another sale already holds is invoice_number_taken. {ok: false, error, message?, retry?} is your refusal (the entry shows error, retry is a hint on the order card, not a schedule). The platform then creates invoices/{number} with the whole document (provider: {id, ref, number, url, app_url, delivery, payment, warnings}) and clears the entry.

Recovery is yours or staff's: a timed-out or failed entry stays on the order (state: 'calling' | 'failed', provider_alert: true while failed). Your install token has two routes for it: POST /api/module/invoice/pending {limit?} → {pending: [{order, period, key, state, attempts, at, request}]} (your entries only; a calling entry younger than 120 s is left out; the request rebuilt by the platform), and POST /api/module/invoice/events {events ≤ 50} → {ok, applied, skipped: [{index, reason}]} with {event: 'issued', order, key, result} (accepted for your entry with that key in either state, else not_pending) and {event: 'paid' | 'unpaid' | 'cancelled' | 'restored', number, paid_on?, amount?} on documents you issued (else invoice_not_owned) — paid / unpaid also settle / unsettle an order paid offline (cash, on_delivery, transfer); a card order is left as it is. Events for your documents keep working after the store switched away from you. Staff have Retry now (POST /api/admin/invoicing/retry, the same key to your module) and Reassign (to the store's current provider). Uninstall answers 409 invoice_provider_active while the store's setup/invoice.provider names you and 409 provider_pending while an order still waits on you.

How the core calls an order-system module (functions/src/modules/store/order_processor.ts — ModuleOrdersAdapter, Part O1). The orders entry:

{kind: 'orders',
 reports: Array<'accepted' | 'packed' | 'shipped' | 'delivered' | 'returned' | 'cancelled'>,  // what you can report; may be []
 cancel?: boolean}                                                                          // you implement order.cancel

It needs callbacks ⊇ {order.push} (+ order.cancel exactly when cancel) and events subscribed to orders — everything after the push (items, address, note, payment state — a COD order settled later) reaches you only through that asynchronous event; diff what you care about. A store switches with POST /api/admin/orders/processor {processor: 'module:{id}'} (owner / master; selectable). From then on every order is pushed once: the trigger pass that first sees it ready or active with its number writes order.processing = {provider, key: '{oid}', reason: 'ready', state: 'calling', attempts: 1, at} + the token orders:module:{id} and ONE call runs from the providerCallTask queue. Orders already past ready when the store switched, and orders created ready with items, are pushed only by staff (Push now).

The answer is stored as order.processing.{ref, number, url, status: 'pushed', status_at, pushed_ms, warnings}. Dedupe on key (the order id — a retry, a staff Retry now and a Reassign back to you all reuse it): a repeated key must answer the order you already created (BaseLinker: keep it in an extra field of a dedicated source and look it up before addOrder). Map VAT percent to your rate classes and report what did not fit (truncated text, rounded quantity, an unmatched SKU, a pickup point you cannot hold) as warnings. A failure never blocks the store — the order is already ready; the entry shows failed with your error and retry hint and provider_alert: true.

Your channel back — POST /api/module/order/events {events: 1..50} with your install token (module.order.events), each {order, event, at (ms), note?, ref?, number?, url?, packages?, warning?} → {ok, applied, skipped: [{index, reason}]}:

Each event is recorded once ({event}:{at} — resend freely). The sink never writes order.status; the order moves by processingStatusTransition — shipped: ready → shipping; delivered: ready | shipping | delivery → completed; returned: shipping | delivery → returned; accepted, packed and cancelled never move (a cancelled system order alerts the store; the merchant decides) — and only when the order has no platform shipment and setup/order.processor_auto_status !== false. Report delivered only for delivery to the customer (an ERP's "dispatched" flag is shipped). Skips: order_not_found, not_own_order, not_pushed, event_undeclared, bad_event, bad_at (outside now − 90 d … now + 10 min), duplicate, bad_ref, unchanged, bad_packages, bad_warning; a disabled install is 409 module_disabled for the whole request. A store hears of a cancelled system order through an orders notification hook with filter: {'processing.status': ['cancelled']}, on: ['update']. Staff have Retry now / Push now / Reassign (POST /api/admin/orders/processing/retry). Uninstall answers 409 order_processor_active while setup/order.processor names you and 409 provider_pending while an order still waits on you.

The parts map — which key targets which part of a module:

How the core calls a payment module (functions/src/modules/payments/module_payments.ts — ModulePaymentAdapter, Part G2). The payment entry:

{kind: 'payment',
 methods: [{code, name: {locale: label}, kind: 'card' | 'bank' | 'wallet' | 'bnpl' | 'other',
            currencies: ['CZK', …], countries?, limits?: {CZK: {min?, max?, step?}},   // MAJOR units; step 1 = a whole-unit currency
            capture?: boolean}],                                                        // authorize now, capture later
 flows: ['redirect'],            // v1: exactly this
 notify: 'notify',               // one of your manifest's inbound routes, auth 'url_key'
 requires?: ['email' | 'name' | 'phone'],   // customer fields your gateway demands
 cancel?: boolean}               // you implement payment.cancel

It needs callbacks ⊇ {payment.create, payment.status} (+ payment.cancel exactly when cancel, payment.capture exactly when a method has capture) and no orders scope — the callbacks carry everything. A store offers your methods by adding rows to its payment catalog (POST /api/admin/payments/setup {op: 'set', methods: [{id, service: 'module:{id}', method: '<code>', name, …}]}); a checkout then sends the row's id as payment_method. Amounts in the contract are integer minor units with currency and unit.

PaymentState = {status: 'pending' | 'requires_capture' | 'succeeded' | 'canceled' | 'denied' | 'expired' | 'refunded', amount?, currency?, partial?, ref?, method?, reason?, paid_on?} — a paid state (succeeded, requires_capture) and refunded must carry amount + currency; for a paid state they must equal what payment.create asked for, exactly (otherwise the attempt is marked error and the order gets a payment_alert).

The flow. The buyer is redirected to redirect_url (stored as order.payment.service_intent.session) and returns to return_url (?o={order} appended). The return URL carries no trusted outcome: the storefront calls POST /api/process/payment/retrieve {order}, the core calls payment.status and answers {provider, state}. Your gateway's webhook reaches you on your inbound route; query the gateway, then report what the query says through POST /api/module/payment/events {events: [{order, key, state}]} (your install token; ≤ 50 events) → {ok, applied, skipped: [{index, reason}]}. Both legs go through one writer, so a late or repeated report is harmless: states are ranked (a paid payment is never un-paid by a canceled), a payment paid on an older attempt re-points the order to it, and money the core cannot act on is made visible on the order as payment_alert — paid_after_close, paid_unrecorded (the answer to your payment.create was lost: report the paid state with ref), refunded, amount_mismatch — never dropped. There is no refund verb: the merchant refunds in your gateway's portal. A failed payment.create is not retried by the core — the buyer picks another method. Capture and cancel reach you as one call each from the provider call queue (finalizing an order captures an authorized payment; closing an order cancels an attempt still waiting for the buyer). After the store's plan stops admitting your module, platform-catalog packages still receive inbound, schedule, payment.status, payment.capture and payment.cancel — payments in flight finish — while payment.create is refused and your methods are no longer offered.

2.5 A minimal connected manifest#

Everything a phase-1 module needs, and nothing that is not yet available. The canonical example is the echo fixture's own manifest.json (examples/module-echo/, §11); this is the shape:

{
  "id": "echo",
  "name": {"en": "Echo", "cs": "Echo"},
  "description": {"en": "Logs every envelope it receives.", "cs": "Zaznamená každou obálku."},
  "category": "tools",
  "tags": ["fixture"],
  "version": "1.0.0",
  "vendor": {"name": "inmake", "url": "https://inmake.dev"},
  "hosting": "connected",
  "endpoint": "https://echo.example.com",
  "access": {"admin": {"read": true, "list": true, "update": true, "create": true, "delete": true, "commit": true}, "secure": {"secret": true}},
  "scope": {"modules": {"echo": true}, "orders": {"*": true}},   // orders write: it annotates orders.modules.echo (entity_fields below)
  "events": ["orders", {"kind": "data", "collection": ["articles"], "on": ["create", "update"]}],
  "data": {"entity_fields": ["orders"]},
  "config": {
    "verify": true,
    "fields": [
      {"key": "account", "kind": "text",   "label": {"en": "Account", "cs": "Účet"}, "required": true},
      {"key": "api_key", "kind": "secret", "label": {"en": "API key", "cs": "API klíč"}, "required": true},
      {"key": "widget",  "kind": "text",   "label": {"en": "Widget key", "cs": "Klíč widgetu"}, "public": true}
    ]
  },
  "uninstall": "keep"
}

What the platform does with it at install: mints a token whose routes are access ∩ MODULE_MAX_ACCESS and whose paths are scope; writes one managed hook entry per distinct (filter, collection) of events; lets the module write orders.modules.echo and its own modules/echo/state|records; renders the three config fields on the card (the secret write-only, widget public through setup/modules); and calls verify with config after the handshake.