Skip to content
Emdash Mika Docs

Astro Actions

Use @bnomei/emdash-mika/astro-actions from src/actions/.

Astro expects actions to be exported from a server object in src/actions/index.ts. Mika’s copyable src/actions/mika.ts keeps the package import isolated, then src/actions/index.ts decides how to expose and guard the tree:

src/actions/mika.ts
export { createMikaActions, mika } from "@bnomei/emdash-mika/astro-actions";
src/actions/index.ts
import { createMikaActions } from "./mika";


export const server = {
  mika: createMikaActions(),
};

The action tree covers:

  • catalog sellables;
  • stock availability;
  • cart add/update/remove/merge/coupons;
  • wishlist add/remove/move/save/merge;
  • checkout start/status;
  • magic-link request/verify;
  • account export/delete/portal;
  • subscription cancel/change/renew.
  • download confirmation for the copied download interstitial.

Use the guard option for host policy such as rate limits, auth checks, bot checks, or feature locks.

guard runs before the selected Astro Action dispatches to Mika. Use it for browser-action concerns tied to Astro’s action context. operationPolicy runs at the Mika operation layer and is better when the same rule should also apply to plugin routes or trusted runner projections.

The package also exports mika, a default createMikaActions() instance. Copied templates usually call createMikaActions() so the host can pass guard, api, or operationPolicy later without changing form components.

Common first actions:

Task Action
Add a product to cart actions.mika.cart.add
Start checkout actions.mika.checkout.start
Add to wishlist actions.mika.wishlist.add
Request magic link actions.mika.magicLink.request
Confirm a download token actions.mika.download.confirm

Form Versus JSON Actions

Section titled “Form Versus JSON Actions”

Most browser mutations are form actions because copied templates are HTML-first:

Action path Accept Returns
actions.mika.catalog.sellables json readonly SellableDTO[]
actions.mika.stock.availability json AvailabilityDTO
actions.mika.cart.add form CartDTO
actions.mika.cart.update form CartDTO
actions.mika.cart.remove form CartDTO
actions.mika.cart.merge form CartDTO
actions.mika.cart.applyCoupon form CartDTO
actions.mika.cart.removeCoupon form CartDTO
actions.mika.wishlist.add form WishlistDTO
actions.mika.wishlist.remove form WishlistDTO
actions.mika.wishlist.moveToCart form CartDTO
actions.mika.wishlist.saveForLater form WishlistDTO
actions.mika.wishlist.merge form WishlistDTO
actions.mika.checkout.start form CheckoutSessionDTO
actions.mika.checkout.status json CheckoutSessionDTO
actions.mika.magicLink.request form { sent: boolean }
actions.mika.magicLink.verify form AccountDTO
actions.mika.account.export form AccountExportDTO
actions.mika.account.exportStatus json AccountExportDTO
actions.mika.account.delete form { requested: boolean }
actions.mika.account.portal form { redirectUrl: string }
actions.mika.subscription.cancel form AccountDTO
actions.mika.subscription.change form AccountDTO
actions.mika.subscription.renew form AccountDTO
actions.mika.download.confirm form DownloadResolutionDTO

JSON action clients exist for typed read/status calls such as catalog sellables, stock availability, checkout status, and account export status. Do not treat JSON action clients as permission to expose protected browser JSON mutation routes.

actions.mika.download.confirm is deliberately separate from download.resolve. The package template pages/download/[token].astro renders a GET interstitial and consumes the single-use token only after a user submits the POST form, so link scanners, previews, and browser prefetch cannot burn the token.

Error Mapping

Section titled “Error Mapping”

createMikaActions() unwraps MikaApiResult envelopes. Successful results become Action data. Failed results become Astro ActionError values mapped from HTTP-like status:

Mika status Astro code
401 UNAUTHORIZED
403 FORBIDDEN
404 NOT_FOUND
409 CONFLICT
410 GONE
422 UNPROCESSABLE_CONTENT
429 TOO_MANY_REQUESTS
500 or other 5xx INTERNAL_SERVER_ERROR
501 NOT_IMPLEMENTED
503 SERVICE_UNAVAILABLE
other status values BAD_REQUEST

External References

Section titled “External References”

Source Anchors

Section titled “Source Anchors”
  • ⓟ ../emdash-mika/src/astro-actions.ts
  • ⓟ ../emdash-mika/src/api/action-tree.ts
  • ⓟ ../emdash-mika/src/api/operation-policy.ts
  • ⓐ ../emdash-mika/src/templates/astro/actions/mika.ts
  • ⓐ ../emdash-mika/src/templates/astro/actions/index.ts
  • ⓐ ../emdash-mika/src/templates/astro/pages/download/[token].astro