Build an imdone provider

Use Provider Contract V1 when your issue tracker is not one of imdone’s built-in providers. A provider is an installed Node.js package that exports a versioned manifest and a factory. Imdone resolves only packages you explicitly configure.

See the generated Provider Contract V1 API reference for every public imdone-cli/provider-sdk export and the capability-to-method requirements. The package build regenerates that reference from source API comments.

Install and configure

Install the provider in the software project that contains .imdone-cli.yml:

npm install @your-scope/imdone-provider

Add the package and provider query under the backlog’s .imdone/config.yml. Keep authentication tokens out of both committed and personal imdone configuration. Providers should read credentials from environment variables or an operating-system/external secret manager and document the variable names they require.

settings:
  plugins:
    JiraPlugin:
      externalProviders:
        - packageName: "@your-scope/imdone-provider"
          query: "state = open"
          config:
            endpoint: "https://issues.example.com"

Loading a provider executes third-party code with the same operating-system permissions as imdone. Imdone does not discover, download, sign, audit, or sandbox external providers. Install and configure only packages you trust.

Export Contract V1

Your package must export imdoneProvider and createProvider. testConnection is always required. Other methods are required only when their capability is true.

export const imdoneProvider = {
  contractVersion: 1,
  providerName: 'acme',
  displayName: 'Acme Issues',
  capabilities: {
    readIssues: true,
    createIssue: true,
    updateIssue: true,
    transitionIssue: true,
    comments: true,
    attachments: true
  },
  configSchema: {
    required: ['endpoint'],
    properties: {
      endpoint: { type: 'string' }
    }
  }
}

export function createProvider({ config, projectPath }) {
  const token = process.env.ACME_API_TOKEN
  if (!token) throw new Error('ACME_API_TOKEN is required')

  return {
    async testConnection() {},
    async listIssues(query) {},
    async getIssue(key) {},
    async createIssue(input) {},
    async updateIssue(input) {},
    async listTransitions(key) {},
    async transitionIssue(input) {},
    async addComment(input) {},
    async listAttachments(key) {},
    async downloadAttachment(input) {},
    async uploadAttachment(input) {},
    async deleteAttachment(input) {}
  }
}

createProvider receives a frozen object containing only the provider configuration and backlog project path. Do not import files from imdone-cli/src or depend on its internal adapter classes.

In this example, endpoint is ordinary provider configuration while ACME_API_TOKEN is runtime secret material. Never ask users to place authentication tokens directly in externalProviders[].config, .imdone/config.yml, or .imdone/config.personal.yml. Prefer a narrowly scoped environment variable backed by the user’s secret manager, and never return its value in errors or diagnostics.

The independently packaged example provider follows this rule directly: it reads IMDONE_EXAMPLE_PROVIDER_TOKEN from ~/.env, and its manifest exposes no token configuration field.

Normalized issues and results

listIssues returns an array of normalized issues; getIssue returns one. Each issue requires string values for key, title, description, status, and url. labels is an optional array and meta is an optional object.

createIssue and updateIssue return { key, url }. Transitions use { id, name, status }; transitionIssue returns the resulting { key, status }. Comment and attachment result objects must include the stable identifiers imdone needs to reconcile later operations.

Validate and troubleshoot

Import conformance helpers only from the public package entry point:

import {
  getProviderConformanceReport,
  validateProviderModule
} from 'imdone-cli/provider-sdk'

Then validate the installed provider from the project:

imdone test --format json
imdone pull --provider acme --format json

Structured validation output identifies the provider, safe package name, contract version, capabilities, configuration state, failure stage, success state, and sanitized error code. It never includes provider configuration values or the underlying error cause.

Common stages are resolve, import, manifest, config, factory, capability, connection, and operation stages such as read, create, update, transition, comment, or attachment.

For questions or contract feedback, email support@imdone.io, open an issue, or join Discord.