Skip to content
Emdash Mika Docs

Admin Action Reference

Use @bnomei/emdash-mika/admin for EmDash actions provider wiring.

This subpath is declarative. It exports the action catalog, manifest helpers, route constants, and field-button option helpers. The runner endpoint is registered by the Mika plugin runtime and resolves those action IDs to Mika operations in src/api/admin-action-runner.ts.

The host also installs @bnomei/emdash-actions and registers its plugin with Mika’s provider config. Mika does not render the EmDash admin UI by itself.

Important surfaces include:

  • createMikaActionsProviderConfig();
  • createMikaAdminActionsManifest();
  • mikaAdminActionDefinitions;
  • MikaAdminActionId;
  • MikaAdminActionsManifest;
  • MikaActionsProviderConfig;
  • createMikaActionButtonOptions();
  • createMikaCatalogSyncActionButtonOptions();
  • createMikaStockAdjustActionButtonOptions();
  • MIKA_ACTIONS_MANIFEST_ROUTE (.well-known/actions);
  • MIKA_ACTIONS_RUNNER_ROUTE (.well-known/actions/run);
  • action IDs under mika.*.

Admin action execution is runner-backed and must remain trusted.

Use this subpath when an Astro + EmDash host needs to register Mika as an actions provider or add an actions:button field to an admin schema. Do not use it as a public storefront API. The action runner can trigger provider syncs, refunds, stock adjustments, entitlement changes, download issuance, and email resends.

Route Roles

Section titled “Route Roles”
Route Role
/_emdash/api/plugins/mika/.well-known/actions Manifest route. Returns action descriptors for EmDash admin/UI clients.
/_emdash/api/plugins/mika/.well-known/actions/run Runner route. Executes the selected action through Mika’s trusted admin operation mapping.
/api/mika-action-contract.json in the seeded repo Host testbed endpoint that reads back the action provider contract; not part of Mika’s package API.

The route strings are relative to Mika’s EmDash plugin route root. They are not Astro pages copied into src/pages/; they are plugin JSON routes registered through the EmDash plugin runtime.

Helper Roles

Section titled “Helper Roles”
Helper Role
createMikaActionsProviderConfig() Produces the EmDash actions provider config for plugin id mika, label Mika, and the manifest/runner well-known routes.
createMikaAdminActionsManifest() Serializes dashboard and field actions into a manifest. Pass includeDashboardActions, includeFieldActions, or disabled to trim the manifest.
createMikaActionButtonOptions(actionId) Merges a built-in action definition with field-button overrides for an actions:button field.
createMikaCatalogSyncActionButtonOptions() Preset for mika.catalog.syncEntry.
createMikaStockAdjustActionButtonOptions() Preset for mika.stock.adjust.

The seeded template consumes these helpers in src/emdash/mika-action-fields.ts and exports fields such as mika_catalog_syncField, mikaStockAdjustField, and mikaOrderRefundField. Those fields are host-owned EmDash schema snippets, not hidden package behavior.

createMikaActionsProviderConfig() defaults to plugin id mika, label Mika, manifest route .well-known/actions, runner route .well-known/actions/run, and an empty allowedTargetPluginIds list.

Common Action IDs

Section titled “Common Action IDs”
ID Surface Operation family
mika.provider.health Dashboard Provider health check.
mika.provider.sync Dashboard Provider product/customer/subscription sync.
mika.stock.releaseExpiredReservations Dashboard Expired stock reservation release.
mika.catalog.syncEntry Entry or field Entry-scoped catalog sync.
mika.stock.adjust Field row Stock adjustment with quantityDelta and optional reason.
mika.webhook.replay Field row Failed webhook replay.
mika.order.refund Field row Provider-backed order refund.
mika.order.cancel Field row Provider-backed order cancellation where supported.
mika.entitlement.grant Field row Manual entitlement grant.
mika.entitlement.revoke Field row Manual or provider-backed entitlement revoke.
mika.email.resend Field row Queue email resend.
mika.license.revoke Field row License revoke.
mika.download.issue Field row Issue a download token/action.

Runner inputs are derived from the action payload, form fields, and EmDash button context. Field-row actions commonly read IDs from the field value, for example stockItemId, orderId, webhookId, entitlementId, emailId, licenseId, or download-related order/entitlement IDs.

Runner Execution

Section titled “Runner Execution”

The runner route is non-public plugin JSON and accepts POST only. It validates the action id, target, and input before policy/API dispatch. mika.catalog.syncEntry maps to admin.providerSync with scope: "entry" and a content ref resolved from the EmDash target; the other action IDs map to their corresponding admin.* operation.

For required-idempotency admin operations, Mika reads the Idempotency-Key header first and falls back to invocation invocationId. If neither is present, the runner returns 409 before policy or API execution. Host auth is supplied by the EmDash/admin route boundary and optional operationPolicy, not by a Mika runner-specific Authorization header.

Source Anchors

Section titled “Source Anchors”
  • ⓟ ../emdash-mika/src/admin.ts
  • ⓟ ../emdash-mika/src/api/admin-action-runner.ts
  • ⓣ ../emdash-mika-template/src/emdash/mika-action-fields.ts
  • ⓣ ../emdash-mika-template/src/pages/api/mika-action-contract.json.ts