imdone-cli docs

Provider Contract V1 API reference

Reference the public SDK exports and capability method requirements for external providers.

Generated from public Provider SDK source during the package build. Edit the API comments in src/providers/provider-contract.mjs, not this file.

Import the helpers below from imdone-cli/provider-sdk. External provider packages export imdoneProvider and createProvider; see the provider-author guide for an installable example, configuration, runtime secrets, and feedback channels.

Provider instance methods

Every provider implements testConnection. Enabled capabilities require these additional methods:

Capability Required methods
readIssues listIssues, getIssue
createIssue createIssue
updateIssue updateIssue
transitionIssue listTransitions, transitionIssue
comments addComment
attachments listAttachments, downloadAttachment, uploadAttachment, deleteAttachment
changelog getChangelog
permissions getCurrentUser, getPermissions
issueTypes listIssueTypes
sprints listSprints, addIssueToSprint
resolutions listResolutions, getIssueResolution, setIssueResolution

Public SDK exports

PROVIDER_BASE_METHODS

Methods every provider instance must implement, regardless of declared capabilities.

PROVIDER_CAPABILITY_METHODS

Capability names and the instance methods required when each capability is enabled.

PROVIDER_CONTRACT_VERSION

Current major version accepted by the host for external provider manifests.

ProviderContractError

A contract failure with safe provider identity, stage, and code fields for diagnostics.

enabledProviderCapabilities

List capability names whose manifest value is true.

  • manifest (object): A provider manifest.
  • Returns string[]: Enabled capability names.

getProviderConformanceReport

Validate a manifest and instance, then report identity, enabled capabilities, and required methods.

  • input (object): { manifest, provider, packageName }.
  • Returns object: A successful Contract V1 conformance report.

requireProviderCapability

Fail before mutation when a provider does not declare a requested capability.

  • manifest (object): A provider manifest.
  • capability (string): Capability required by the operation.
  • Returns true: When the capability is enabled.

requiredProviderMethods

Collect baseline and capability-dependent method names without duplicates.

  • manifest (object): A provider manifest.
  • Returns string[]: Method names required on the provider instance.

toProviderDiagnostic

Convert a contract failure to a sanitized diagnostic safe for structured CLI output. Unknown errors use a generic code and message; causes and configuration values are omitted.

  • error (Error): Failure to summarize.
  • Returns object: Safe stage, code, message, and optional identity fields.

validateNormalizedIssue

Validate an issue returned by listIssues or getIssue. Required string fields are key, title, description, status, and url; optional labels is an array and optional meta is an object.

  • value (object): Provider-owned normalized issue.
  • Returns object: The original issue when valid.

validateProviderConfig

Validate project configuration against a manifest’s required fields and property types. Secret values must be supplied at runtime, not serialized into imdone configuration.

  • manifest (object): A validated provider manifest.
  • config (object): Provider configuration from the project.
  • Returns object: { valid: true } when the configuration passes.

validateProviderInstance

Require testConnection and each method implied by enabled capabilities.

  • manifest (object): A validated provider manifest.
  • provider (object): The object returned by createProvider.
  • Returns object: The validated provider instance.

validateProviderIssueReference

Validate the { key, url } result returned by issue create or update operations.

  • value (object): Provider issue reference.
  • Returns object: The original reference when valid.

validateProviderManifest

Validate a Contract V1 manifest and return a frozen normalized manifest. The manifest requires contractVersion, a lowercase providerName, and boolean capabilities. Optional displayName and configSchema describe presentation and non-secret configuration.

  • value (object): The package’s imdoneProvider export.
  • options (object): Optional safe package identity for diagnostics.
  • Returns object: The frozen normalized manifest.

validateProviderModule

Validate the package exports imdoneProvider and createProvider.

  • providerModule (object): Imported external package module.
  • options (object): Optional safe package identity for diagnostics.
  • Returns object: The normalized manifest and provider factory.