Plugin fulfilment

The Socket.IO contract, atomic claim, and crash-safe fulfilment acknowledgement.

The official plugin uses the Socket.IO /plugin namespace on the public app/API origin. The game server always initiates the connection and exposes no inbound port.

The legacy REST polling endpoints GET /orders/plugin/.../pending and POST /orders/plugin/.../complete have been retired. They could not provide a safe atomic claim across multiple instances or protect the ambiguous crash window. Use the current plugin and protocol below.

Authentication

The namespace handshake sends:

{ "apiKey": "isk_<64 hex characters>", "serverId": "<24 hex characters>" }

The backend accepts only an active plugin key with orders:write. The key is shop-bound, serverId must belong to that shop, and the key owner must still have shop access. Any invalid connection gets the same unauthorized error without revealing which check failed.

Protocol v1 events

Direction	Event	Data / ACK
plugin → app	hello	{ platform, version }
app → plugin	ready	{ serverId, serverName }
app → plugin	order:deliver	{ v: 1, id, player, status, commands[], requireOnline }
plugin → app	order:claim	{ orderId }; the winner’s ACK carries a fresh command snapshot
plugin → app	order:release	voluntarily returns a claim when a fresh delivery gate is not met
plugin → app	order:verify	rechecks the current status of a delivery parked for a long time
plugin → app	order:complete	{ orderId }; ACK permits deleting AWAITING_ACK locally
plugin → app	order:uncertain	reports recovered EXECUTING; response is manual-review, retry, or complete
plugin → app	orders:pull	rate-limited request for a full outstanding-order replay
plugin → app	players:update	{ online, max, players?[] }; values are filtered and capped server-side
plugin → app	ping:app	diagnostic ACK with application time

The backend replays all outstanding deliveries on every connection and pushes after payment or status changes. Duplicate order:deliver events are expected: execution authority comes from the atomic claim and local journal, not from merely receiving an event.

Safety states

1. paid or dispute → processing: only one instance wins the conditional database transition.
2. The plugin writes and fsyncs EXECUTING before the first command.
3. After the final command it writes and fsyncs AWAITING_ACK.
4. order:complete changes the order to completed; only its ACK removes the local entry.
5. A restart with AWAITING_ACK retries only the ACK. A restart with EXECUTING never replays commands and starts manual review.

Do not delete the journal to “unstick” an order. Check the actual player/server state and resolve it in the panel. retry clears the server-side claim and allows a new push; complete accepts the delivery without replaying commands.

Command formatting

The API formats product commands before returning the claim winner’s fresh snapshot:

Placeholder	Replaced with
{PLAYER} / {NICK}	the order’s validated nickname
{QUANTITY}	quantity
{PRODUCT}	product name
{QUANTITY*1.5:2}	an allowed math expression rounded to 2 places

Math expressions use a restricted parser and are never evaluated as code. quantityTiers, the command variant, and package bonuses are resolved by the API. The plugin additionally rejects any command whose first word appears in blockedCommands.

If a product requires the player online, an instance executes only after seeing the exact nickname on an allowed server. A locally parked delivery is checked through order:verify so an order cancelled or refunded in the meantime cannot run from a stale event.