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

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

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.