Versioning and permission changes

Version numbers

version is semver x.y.z, digits only. Every upload needs a version number the listing has not used before: once a version has been submitted, it cannot be changed, so bump version for every change.

A useful convention:

Add a changelog to each version, so reviewers (and owners) can see what changed:

dunea-plugin publish --changelog "Adds tracking links to Slack messages" --submit

Every version is reviewed

Every change to the manifest, including webhookUrl, panel, agentTools, usage, siteScripts, settings and pricing, is a new version and goes through review. When a version is approved, earlier approved versions become superseded.

A plugin or theme update that keeps the same permissions, events, endpoint origins, site scripts, AI tool text and prices (and, for themes, the same guide) can be fast-tracked: approved automatically, without waiting for a reviewer. dunea-plugin check tells you whether it qualifies.

Your backend is yours to deploy whenever you like; review covers the manifest and what your plugin does with it. Keep your service compatible with the currently approved manifest while a new version is in review. For example, keep your old webhook path working until the version with the new webhookUrl is approved.

Rolling back

If an approved version turns out to have a problem, make an earlier approved version current again, without review:

dunea-plugin release 1.4.1

New installs get that version, and installs that already granted its permissions move to it. Then ship the fix as a new, higher version: a rollback doesn't free up a version number. See Publishing.

Asking for new permissions

Owners approve permissions per install. If a new version asks for a permission an install has not granted, that install has to approve it again:

• The owner sees the new permission (in pendingPermissions on their install) and can approve it.
• Until they do, the install keeps only the permissions it already granted. Plugin API calls that need the new permission return 403 with missingPermission set.

Write your code for both cases:

import { DuneaClient, DuneaApiError, type ApiOrder } from '@dunea/plugin-sdk';

async function getOrder(dunea: DuneaClient, id: string): Promise<ApiOrder | null> {
  try {
    return await dunea.orders.get(id);
  } catch (error) {
    if (error instanceof DuneaApiError && error.status === 403) {
      // This install has not approved `error.missingPermission` yet.
      // Fall back to what the install can do, and tell the owner in your panel.
      return null;
    }
    throw error;
  }
}

plugin.installed tells you each install's grantedPermissions. Store them, and check them before you offer a feature that needs a permission the install may not have.

Removing things

• Removing a permission does not ask owners for anything. Remove it once no code path uses it.
• Removing or renaming an AI tool takes it away from the Dunea AI for every install. Rename by adding the new tool in one version and removing the old one in a later version.
• Removing a setting: do not reuse its key later for a different meaning.

Rotating your client secret

Rotate the secret from the developer portal (or POST /api/marketplace/dev/listings/:slug/rotate-secret). The new secret is shown once. Deploy it straight away, alongside the old one: createWebhookHandler, verifyWebhook and verifyPanelSession all take an array of secrets, so requests signed with either are accepted while the change rolls out. A webhook your server rejected in the meantime is retried. Remove the old secret once the new one is live everywhere. See Webhooks and signatures.