Skip to content
Emdash Mika Docs

Server API

Use @bnomei/emdash-mika/server from trusted backend code.

Choose the surface by mode:

Need Start with
Fixture or partial test API createMikaApi(overrides) or direct MikaApiOverrides
Production backend over repositories/providers createMikaBackendApi(input)
Trusted server-to-plugin HTTP calls createMikaServerClient(options)

Important surfaces include:

  • createMikaRequestContext();
  • MikaRequestContext;
  • MikaSessionAccess;
  • MikaApi;
  • MikaApiOverrides;
  • createMikaApi();
  • assertMikaApiWired();
  • mikaApiMethodNames;
  • createMikaBackendApi();
  • createMikaServerClient();
  • notification hook types;
  • email outbox and maintenance runners;
  • operation policy types.

Do not expose server APIs directly to browsers.

API Modes

Section titled “API Modes”
Mode Use it when
createMikaApi(overrides) You want a partial or test API surface. Missing methods return 501 NOT_IMPLEMENTED.
createMikaBackendApi(input) You want a fully wired backend over repositories, providers, ids, hashing, clocks, config, defaults, and notification hooks.
createMikaServerClient(options) Trusted server code needs to call Mika plugin HTTP routes, including admin and webhook operations.

assertMikaApiWired(api, { scope }) throws if requested namespaces or fully-qualified methods still point to the not-implemented stub. Use it in host setup or tests to catch missing backend wiring before a route is hit.

Namespaces

Section titled “Namespaces”

MikaApi is grouped into these namespaces:

  • catalog;
  • stock;
  • cart;
  • wishlist;
  • checkout;
  • magicLink;
  • account;
  • subscription;
  • download;
  • order;
  • webhook;
  • admin.

Methods that mutate session, checkout, account, subscription, order, webhook, or admin state receive a MikaRequestContext when request identity matters.

Request Context

Section titled “Request Context”

createMikaRequestContext() normalizes host request data into:

  • request, url, and method;
  • actor, scopes, auth subject, and auth issuer;
  • correlation id and idempotency key;
  • session id and MikaSessionAccess;
  • customer/user ids;
  • locale;
  • now as an ISO timestamp.

Astro route handlers and Actions normally build this context from the incoming request/session. Backend jobs can also create one explicitly with a synthetic clock, actor, or session id.

Backend Dependencies

Section titled “Backend Dependencies”

createMikaBackendApi() expects host-owned infrastructure:

  • repositories for catalog, session/cart/wishlist/checkout, stock, ledger, account, ops, and other persisted commerce records;
  • provider registry;
  • createId, hash, now, and optional isoNow;
  • config for TTLs, success/cancel URLs, magic-link paths, metadata, and token lifetimes;
  • defaults such as currency, locale, and provider;
  • optional notification hook.

This is the package boundary where Mika becomes a working commerce backend. The package does not create credentials, databases, mail transport, provider accounts, auth, tax rules, or shipping rates for the host.

Server Client

Section titled “Server Client”

createMikaServerClient() builds a fetch-based client over plugin routes. It includes the public browser client operations plus trusted admin and webhook facades, and it exposes a routes builder for plugin route URLs. It forwards same-origin cookies from the incoming request by default; use forwardCrossOriginCookies only when the host has decided that is safe.

Source Anchors

Section titled “Source Anchors”
  • ⓟ ../emdash-mika/src/server.ts
  • ⓟ ../emdash-mika/src/api/server.ts
  • ⓟ ../emdash-mika/src/api/context.ts
  • ⓟ ../emdash-mika/src/api/backend.ts
  • ⓟ ../emdash-mika/src/api/server-client.ts
  • ⓟ ../emdash-mika/src/api/email-outbox.ts
  • ⓟ ../emdash-mika/src/api/maintenance.ts