Operations
Mika operation descriptors are the internal source of truth for operation names, namespaces, methods, schemas, route metadata, action metadata, public visibility, request-context requirements, and agent metadata.
Use the descriptors to look up operation metadata; import public package surfaces instead of internal dispatch helpers.
Use this page when you need the exact operation name, route key, route path, Action type, or request-context boundary. Do not use it as a list of browser-callable endpoints: only public: true routes are safe public plugin JSON reads.
The first two operation families are the only public plugin JSON reads. Everything after stock.availability needs an Astro Action, a copied host page, a trusted runner, or a host-owned protected endpoint.
Each descriptor carries:
| Field | Meaning |
|---|---|
namespace and method |
The API name, such as checkout.start. |
routeKey and routePath |
The EmDash plugin route key and path segment. |
httpMethod and transport |
How plugin-route input is parsed when a host exposes that route. |
public |
Whether the route can be exposed without session/auth requirements. |
requiresRequestContext |
Whether the operation receives request/session/locale context. |
action |
Optional Astro Action client metadata, either form or json. |
agent |
Visibility, capability, risk, confirmation, proof, and idempotency metadata. |
Operation Families
Section titled “Operation Families”| Family | Public plugin JSON route? | Astro Action? | Notes |
|---|---|---|---|
catalog.sellables |
Yes, GET catalog/sellables with collection, id, locale search params. |
JSON action. | Public read for content refs. |
stock.availability |
Yes, GET sellables/availability with sellableId. |
JSON action. | Public read for sellable stock state. |
cart.* |
No. | Form actions for add/update/remove/merge/coupons; quote is operation-only. |
Requires request context and host policy. |
wishlist.* |
No. | Form actions for add/remove/move/save/merge. | Requires request context and host policy. |
checkout.* |
No. | start is a form action; status is a JSON action; preview/cancel are operation/plugin route surfaces. |
Checkout handoff requires confirmation/payment boundary and idempotency in protected projections. |
magicLink.* |
No. | Form actions for request/verify. | Host owns auth/session policy and delivery. |
account.* |
No. | Form actions for export/delete/portal; JSON action for export status. | Export download has separate protected GET/read and POST/consume route operations. Invoice-style reads are protected route/helper surfaces. |
subscription.* |
No. | Form actions for cancel/change/renew. | Trusted/customer operation family. |
download.resolve / download.confirm |
No. | download.confirm is a form action. |
resolve is the GET/read operation for agents or custom endpoints; confirm is the copied interstitial POST that consumes a single-use token after user intent. |
order.invoice |
No. | No copied Astro Action. | Protected invoice link resolution. |
webhook.receive |
No. | No copied Astro Action. | Hidden service operation used by host webhook endpoint with provider verification. |
admin.* |
No. | No storefront Astro Actions. | Trusted EmDash action runner and admin operation family. |
The only public: true plugin JSON routes are catalog.sellables and stock.availability. Every mutation, account read, webhook, and admin operation needs host-owned policy before exposure.
Operation Matrix
Section titled “Operation Matrix”| Operation | Route key | Plugin route | Public | Request context | Action |
|---|---|---|---|---|---|
catalog.sellables |
catalogSellables |
GET catalog/sellables (collection, id, locale) |
Yes | No | json |
stock.availability |
sellableAvailability |
GET sellables/availability (sellableId) |
Yes | No | json |
cart.get |
cart |
GET cart |
No | Yes | none |
cart.quote |
cartQuote |
POST cart/quote |
No | Yes | none |
cart.add |
cartItems |
POST cart/items |
No | Yes | form |
cart.update |
cartItem |
PATCH cart/item |
No | Yes | form |
cart.remove |
cartItem |
DELETE cart/item |
No | Yes | form |
cart.merge |
cartMerge |
POST cart/merge |
No | Yes | form |
cart.applyCoupon |
cartCoupon |
POST cart/coupon |
No | Yes | form |
cart.removeCoupon |
cartCoupon |
DELETE cart/coupon |
No | Yes | form |
wishlist.get |
wishlist |
GET wishlist |
No | Yes | none |
wishlist.add |
wishlistItems |
POST wishlist/items |
No | Yes | form |
wishlist.remove |
wishlistItem |
DELETE wishlist/item |
No | Yes | form |
wishlist.moveToCart |
wishlistMoveToCart |
POST wishlist/move-to-cart |
No | Yes | form |
wishlist.saveForLater |
wishlistSaveForLater |
POST wishlist/save-for-later |
No | Yes | form |
wishlist.merge |
wishlistMerge |
POST wishlist/merge |
No | Yes | form |
checkout.start |
checkout |
POST checkout |
No | Yes | form |
checkout.preview |
checkoutPreview |
POST checkout/preview |
No | Yes | none |
checkout.status |
checkoutStatus |
GET checkout/status (checkoutId, token) |
No | Yes | json |
checkout.cancel |
checkoutAbandon |
POST checkout/abandon |
No | Yes | none |
magicLink.request |
magicLink |
POST magic-link |
No | Yes | form |
magicLink.verify |
magicLinkVerify |
POST magic-link/verify |
No | Yes | form |
account.get |
account |
GET account |
No | Yes | none |
account.export |
accountExport |
POST account/export |
No | Yes | form |
account.exportStatus |
accountExportStatus |
GET account/export/status (exportId) |
No | Yes | json |
account.exportDownload |
accountExportDownload |
GET account/export/download (exportId, token) |
No | Yes | none |
account.exportDownloadConsume |
accountExportDownload |
POST account/export/download |
No | Yes | none |
account.delete |
accountDelete |
POST account/delete |
No | Yes | form |
account.portal |
accountPortal |
POST account/portal |
No | Yes | form |
subscription.cancel |
subscriptionCancel |
POST subscriptions/cancel |
No | Yes | form |
subscription.change |
subscriptionChange |
POST subscriptions/change |
No | Yes | form |
subscription.renew |
subscriptionRenew |
POST subscriptions/renew |
No | Yes | form |
download.resolve |
download |
GET download (token) |
No | No | none |
download.confirm |
downloadConfirm |
POST download/confirm |
No | No | form |
order.invoice |
orderInvoice |
GET orders/invoice (orderId, token, returnTo) |
No | Yes | none |
webhook.receive |
webhook |
POST webhooks |
No | Yes | none |
admin.providerHealth |
adminProviderHealth |
POST admin/provider/health |
No | No | none |
admin.providerSync |
adminProviderSync |
POST admin/provider/sync |
No | No | none |
admin.stockAdjust |
adminStockAdjust |
POST admin/stock/adjust |
No | No | none |
admin.releaseExpiredReservations |
adminStockReleaseExpiredReservations |
POST admin/stock/release-expired-reservations |
No | No | none |
admin.webhookReplay |
adminWebhookReplay |
POST admin/webhooks/replay |
No | No | none |
admin.orderRefund |
adminOrderRefund |
POST admin/orders/refund |
No | No | none |
admin.orderCancel |
adminOrderCancel |
POST admin/orders/cancel |
No | No | none |
admin.entitlementGrant |
adminEntitlementGrant |
POST admin/entitlements/grant |
No | No | none |
admin.entitlementRevoke |
adminEntitlementRevoke |
POST admin/entitlements/revoke |
No | No | none |
admin.emailResend |
adminEmailResend |
POST admin/emails/resend |
No | No | none |
admin.licenseRevoke |
adminLicenseRevoke |
POST admin/licenses/revoke |
No | No | none |
admin.downloadIssue |
adminDownloadIssue |
POST admin/downloads/issue |
No | No | none |
Agent Visibility And Idempotency
Section titled “Agent Visibility And Idempotency”Mika agent metadata is attached to the same operation descriptors. The preset classes in operation-agent-metadata.ts keep these boundaries explicit:
| Class | Visibility | Capability pattern | Idempotency |
|---|---|---|---|
| Catalog and stock reads | public |
catalog:read, stock:read |
not_needed |
| Cart, wishlist, checkout, account, subscription, download, and order flows | trusted |
Customer or session capabilities | not_needed, recommended, or required depending on effect. |
| Provider webhooks | hidden |
webhook:receive |
required |
| Admin reads and writes | admin |
admin:read, admin:write |
Writes are required; reads are not_needed. |
The idempotency key metadata uses the Idempotency-Key header, replay mode same_key_same_input, and owner host. Mika describes that expectation; the host must persist and enforce it for protected projections.
Action Tree
Section titled “Action Tree”src/api/action-tree.ts derives the actions.mika.* namespace tree from descriptors with action metadata. The tree is used by createMikaActions(); it is not a separate public routing system.
Source Anchors
Section titled “Source Anchors”- ⓟ
../emdash-mika/src/api/operations.ts - ⓟ
../emdash-mika/src/api/action-tree.ts - ⓟ
../emdash-mika/src/api/operation-agent-metadata.ts