SDK Contracts Consumer Example

This example shows how to consume pm contracts programmatically in a script and validate action payload requirements before execution.

Files

• package.json -> installs @unbrained/pm-cli and script aliases
• inspect-contracts.mjs -> loads contracts + SDK helpers and prints required/optional parameter metadata
• parse-receipt.mjs -> executes a real create and parses its flat mutation receipt with the SDK

Run

cp -R docs/examples/sdk-contract-consumer /tmp/pm-sdk-contract-consumer
cd /tmp/pm-sdk-contract-consumer
# Local checkout (recommended while iterating on unreleased SDK changes):
PM_CLI_REPO_ROOT=/absolute/path/to/pm-cli
npm install "$PM_CLI_REPO_ROOT"

# Or use a published release once available:
# npm install @unbrained/pm-cli@latest

node inspect-contracts.mjs create
npm run parse:receipt

Expected output shape:

{
  "action": "create",
  "required_parameters": [
    "title",
    "description",
    "type",
    "status",
    "priority",
    "message"
  ],
  "optional_parameters": ["template", "createMode", "schedulePreset"],
  "any_of_required_groups": [],
  "runtime_available": true,
  "policy_state": null,
  "compatibility": {
    "current": "v2",
    "previous": ["v1"],
    "breaking_strategy": "versioned_breaking"
  },
  "manifest_versions": [1, 2]
}

You can inspect any action:

node inspect-contracts.mjs update
node inspect-contracts.mjs extension
node inspect-contracts.mjs extension-reload

Why This Pattern Works

• Uses isPmToolAction() for strict action validation.
• Uses PM_TOOL_ACTION_PARAMETER_CONTRACTS for deterministic required/optional metadata.
• Uses runtime pm contracts --json so extension-provided actions and command availability are reflected.
• Includes policy-state and compatibility metadata so CI/app callers can gate behavior during v1 -> v2 migrations.
• Uses parseMutationReceipt() at the process boundary instead of guessing that mutation output has the read-only { item: ... } wrapper.