Get started

App marketplace

Mercentia’s app marketplace lets external developers ship extensions (workflow plugins, UI panels, scheduled jobs) that merchants can install into their stores. The schema lives in migration 0100_app_submissions.sql.

Submitter flow

Developers sign in to Mercentia with a developer account and use the Developer Hub to:

  1. Click Submit new app. Provide name, slug, category, short pitch (≤140 chars), long description, icon (PNG, 512×512), screenshots, repo URL, and the manifest JSON.
  2. Mercentia validates the manifest against the @mercentia/app-manifest schema (Zod). Any required field missing returns a structured validation report — fix and re-submit.
  3. The submission lands in the platform-admin review queue with status pending.

Manifest

The manifest declares the app’s entry points and required permissions:

{
  "id": "com.acme.referral-engine",
  "name": "Referral Engine",
  "version": "1.0.0",
  "entryPoints": {
    "ui": [{ "slot": "marketing.tab", "url": "https://app.acme.io/mercentia/panel" }],
    "workflows": [
      { "trigger": "order.paid", "url": "https://app.acme.io/mercentia/workflows/order-paid" }
    ]
  },
  "scopes": ["read:orders", "write:customers"]
}

Mercentia signs every workflow call to the developer’s URL with HMAC-SHA256 over the request body, using a per-installation secret — see API auth for the same signature scheme used elsewhere.

Review queue (platform admin)

Platform admins (x-platform-admin: 1) open the queue at /platform/apps. Each submission shows:

  • Submitter identity + history (prior approvals / rejections).
  • Manifest validation result.
  • A sandboxed install button — installs the app into the platform admin’s own demo store for hands-on testing.

Reviewers can:

  • Approve — moves status to published, indexes the app in the merchant-facing marketplace.
  • Request changes — moves to changes_requested with a comment; the developer is notified by email.
  • Reject — terminal state, reason recorded in audit log.

Installation lifecycle

A merchant installs an app from Apps → Marketplace. The gateway:

  1. Records the install row (tenant_app_installs).
  2. Mints a per-installation secret used for HMAC signing.
  3. Provisions any UI extension slots declared in the manifest.

Uninstall reverses these. See packages/app-registry/src/index.ts for the registry surface the dashboard consumes.

Security

  • Apps may only request scopes within the @mercentia/shared/scopes catalog. Custom scopes are rejected at submission.
  • Egress from app workflow callbacks is sandboxed at the network layer — apps can’t talk to Mercentia’s internal infrastructure.
  • The marketplace is curated. Mercentia can revoke a published app at any time; revocation suspends all merchant installs and refunds in-app purchases for the last billing period.