API & Hook Catalogs

Two published catalogs define a plugin's entire surface. They are authorization contracts, not convenience indexes: an operation absent from a catalog is denied at runtime, whatever the manifest says.

The API/function catalog (dev-api-catalog-1.0) lists every operation a handler may invoke through arvexa.call(operationId, args). Fetch it with arvexa catalog list. Each entry carries the exact id to call, the required scopes, the allowed roles, its mutability (read, write, idempotent_write), a PII class, and an availability marker. Ids are exact — fn:platform.clock.now is a function entry, HTTP entries name a method and path — and there is no prefix or wildcard matching.

Below this guide you will find a live, module-wise listing of:

1. 1The current plugin-callable allowlist (what arvexa.call accepts today)
2. 2The full OpenAPI API modules (every documented Nest module/operation with playground links). Operations that are also on the allowlist are marked Plugin callable.

Read the required scopes from the catalog before writing your manifest. It is the difference between a manifest that is right the first time and one that produces a runtime denial in a sandbox run.

The hook catalog (plugin-hook-catalog-1.0) lists everything that may trigger a plugin. Fetch it with arvexa catalog list --kind hooks. Each entry carries its kind, the payload contract and version it delivers, required scopes, allowed roles, a PII class, a redaction policy, and the owning peer.

Hooks come in three kinds, and only two can be registered:

• observe — domain events; the payload is delivered, the plugin cannot alter the outcome
• lifecycle — plugin and platform lifecycle transitions
• action — reserved; registering one is rejected in V1

Some hook pairs are refused together. plugin.enabled and plugin.disabled cannot be co-registered, and the CLI reports the conflict locally instead of at upload time.

Derive from the payload before calling back. A hook payload already carries the event's data. Calling into the API to re-read what you were just handed spends one of the 32 API-call budget entries per invocation to learn something already in hand.

Handle a denial as a normal outcome. arvexa.call resolves with { ok: false, code, message } rather than throwing. A handler that assumes success turns a routine authorization denial into a HANDLER_ERROR, which is a strictly worse signal than the denial itself.

The SDK mirrors a small projection of both catalogs — identity, kind, required scopes, audiences — purely so arvexa plugin validate can work offline. Delivery timing, retry semantics, PII class, and peer wiring are host concerns and are deliberately not mirrored. A boundary spec in apps/api compares the projection against the host registries, so adding a hook host-side without updating the SDK fails that spec rather than drifting quietly.

Peer availability is reported honestly. Some extension points depend on peers that the Developer Platform does not wire in V1: binding succeeds, and delivery reports PEER_UNAVAILABLE. arvexa plugin validate warns when you declare one, so "bound but never delivered" is never a surprise.