Skip to content
Emdash Mika Docs

Admin Actions

Use this guide when adding Mika operation buttons to the EmDash admin UI.

Prerequisites

Section titled “Prerequisites”
  • EmDash admin is configured.
  • Mika plugin is registered.
  • The host API implements the admin operations the host exposes.
  • Runner execution stays behind the EmDash/admin boundary.

@bnomei/emdash-actions is the EmDash plugin that turns action provider manifests into admin buttons. A provider describes which actions exist, which fields they need, and where the button can appear. The admin UI can then render contextual controls beside entries or JSON records, such as “Sync catalog”, “Refund order”, “Revoke license”, or “Issue download”.

Install the actions plugin in the host app:

Terminal window
npm install @bnomei/emdash-actions

Mika supplies a provider manifest for its admin operations plus helper options for field buttons. The button is only the UI trigger: execution still goes through the trusted action runner, the host-owned Mika API, and Mika’s idempotency requirements. The goal is contextual controls inside EmDash, not a separate Mika admin app and not public browser mutation routes.

ⓣ Seeded GitHub template repo smoke paths:

  • /_emdash/admin
  • /api/mika-action-contract.json

Mika’s admin action integration has three separate pieces:

Piece Where it lives What it does
Action provider config astro.config.mjs Registers Mika’s manifest and runner routes with @bnomei/emdash-actions.
Field button options EmDash field config, for example src/emdash/mika-action-fields.ts Tells an EmDash field or dashboard where a button appears and which action ID it invokes.
Runner execution /_emdash/api/plugins/mika/.well-known/actions/run Executes trusted Mika admin operations through the host-owned API.

The seeded route /api/mika-action-contract.json is a testbed/readback endpoint in ../emdash-mika-template, not the production runner. Use it to inspect the provider contract while developing the template.

Common action IDs include:

  • mika.provider.health
  • mika.provider.sync
  • mika.stock.adjust
  • mika.order.refund

See Admin Action Reference for the full action ID list.

Field-Button Wiring

Section titled “Field-Button Wiring”

Mika admin operations surface as EmDash action buttons beside entries, not as a separate app. Two pieces wire them.

Register the action provider in astro.config.mjs:

import { actionsPlugin } from "@bnomei/emdash-actions";
import { createMikaActionsProviderConfig } from "@bnomei/emdash-mika/admin";
import { mikaPlugin } from "@bnomei/emdash-mika";


const mikaActionProvider = createMikaActionsProviderConfig();
// to restrict targets: { ...createMikaActionsProviderConfig(), allowedTargetPluginIds: [...] }


// emdash({
//   plugins: [
//     actionsPlugin({ providers: [mikaActionProvider] }),
//     mikaPlugin({ api }),
//   ],
// })

Attach a button to a collection field with the matching options helper:

import {
  createMikaActionButtonOptions,
  createMikaStockAdjustActionButtonOptions,
} from "@bnomei/emdash-mika/admin";


export const mikaStockAdjustField = {
  slug: "stock_adjust",
  type: "json",
  widget: "actions:button",
  options: createMikaStockAdjustActionButtonOptions(),
};
// generic actions: createMikaActionButtonOptions("mika.order.refund")

The seeded template registers actionsPlugin({ providers: [mikaActionProvider] }) and mikaPlugin({ entrypoint: "#mika-template-plugin" }) side by side. The actions provider draws buttons; the Mika plugin owns the manifest and runner route implementation.

Admin and agent-runner paths require an idempotency key wherever Mika marks one required. For the EmDash runner route, Mika reads Idempotency-Key first and falls back to the invocation invocationId. Required-idempotency admin operations without either value return 409 before policy/API dispatch.

Manifest And Runner Routes

Section titled “Manifest And Runner Routes”

The provider manifest is read-only metadata. The route constant is MIKA_ACTIONS_MANIFEST_ROUTE, value .well-known/actions. It lists action labels, fields, placement, confirmation text, feedback strings, and runner metadata:

/_emdash/api/plugins/mika/.well-known/actions

The runner route constant is MIKA_ACTIONS_RUNNER_ROUTE, value .well-known/actions/run. It is the trusted execution surface and accepts POST:

/_emdash/api/plugins/mika/.well-known/actions/run

Do not expose the runner as a storefront route. EmDash action buttons call it with the selected action ID and contextual payload; Mika maps that invocation to an admin operation and then calls the host-owned MikaApi. Host authentication is the EmDash/admin route boundary plus optional operationPolicy; Mika’s runner does not define a separate Authorization header scheme.

Verify

Section titled “Verify”
  • The EmDash actions provider can read /_emdash/api/plugins/mika/.well-known/actions.
  • Runner calls use POST and carry an idempotency key or invocation id for operations that require replay safety.
  • The runner remains behind trusted EmDash/admin surfaces, not a public storefront route.

Next: Admin Action Reference lists action IDs and runner behavior. Operations shows visibility, risk, and idempotency metadata.

External References

Section titled “External References”

Source Anchors

Section titled “Source Anchors”
  • ⓟ ../emdash-mika/src/admin.ts
  • ⓟ ../emdash-mika/src/api/admin-action-runner.ts
  • ⓟ ../emdash-mika/src/api/route-handlers.ts
  • ⓣ ../emdash-mika-template/src/emdash/mika-action-fields.ts
  • ⓣ ../emdash-mika-template/astro.config.mjs
  • ⓣ ../emdash-mika-template/src/pages/api/mika-action-contract.json.ts
  • ⓣ ../emdash-mika-template/docs/usage.md
  • ⓣ ../emdash-mika-template/seed/mika-actions.seed.json