{"_id":"@bnomei/emdash-mika","_rev":"2-d89fc5f97458813fac5cac00dde3a005","name":"@bnomei/emdash-mika","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@bnomei/emdash-mika","version":"0.1.0","keywords":["agentic-commerce","astro","cart","cms","commerce","ecommerce","emdash","emdash-plugin","headless-commerce","subscription","typescript"],"author":{"url":"https://bnomei.com","name":"Bruno Meilick","email":"b@bnomei.com"},"license":"MIT","_id":"@bnomei/emdash-mika@0.1.0","maintainers":[{"name":"bnomei","email":"b@bnomei.com"}],"homepage":"https://github.com/bnomei/emdash-mika#readme","bugs":{"url":"https://github.com/bnomei/emdash-mika/issues"},"dist":{"shasum":"ece6be4239055658f36b330fc0f462e7e70ddebb","tarball":"https://registry.npmjs.org/@bnomei/emdash-mika/-/emdash-mika-0.1.0.tgz","fileCount":183,"integrity":"sha512-2wXbd9VppUy5yLuarefkclWzJk3Tv9yh8rqF3XzDn/1O1kZzF5akzZBjqczWSZQ+Jc9t7UoI4A71w1/dKVRI2Q==","signatures":[{"sig":"MEYCIQD+7sWoLqSVy+QUjGoCDs0wEa0z4xhx4tzrvdlTGWZDUwIhAIXh31Uiy3pW7Sks05Y767loqz3LF6nxUFZJusNelJpj","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2656587},"main":"./dist/index.mjs","type":"module","types":"./dist/index.d.mts","engines":{"node":">=22.12.0"},"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"},"./acp":{"types":"./dist/acp.d.mts","import":"./dist/acp.mjs"},"./admin":{"types":"./dist/admin.d.mts","import":"./dist/admin.mjs"},"./agent":{"types":"./dist/agent.d.mts","import":"./dist/agent.mjs"},"./astro":{"types":"./dist/astro.d.mts","import":"./dist/astro.mjs"},"./email":{"types":"./dist/email.d.mts","import":"./dist/email.mjs"},"./react":{"types":"./dist/react.d.mts","import":"./dist/react.mjs"},"./types":{"types":"./dist/types/index.d.mts","import":"./dist/types/index.mjs"},"./client":{"types":"./dist/api/client.d.mts","import":"./dist/api/client.mjs"},"./server":{"types":"./dist/server.d.mts","import":"./dist/server.mjs"},"./stripe":{"types":"./dist/stripe.d.mts","import":"./dist/stripe.mjs"},"./provider":{"types":"./dist/provider.d.mts","import":"./dist/provider.mjs"},"./server/email":{"types":"./dist/server/email.d.mts","import":"./dist/server/email.mjs"},"./server/ports":{"types":"./dist/server/ports.d.mts","import":"./dist/server/ports.mjs"},"./astro-actions":{"types":"./dist/astro-actions.d.mts","import":"./dist/astro-actions.mjs"},"./types/documents":{"types":"./dist/types/documents.d.mts","import":"./dist/types/documents.mjs"},"./types/aggregates":{"types":"./dist/types/aggregates.d.mts","import":"./dist/types/aggregates.mjs"},"./types/primitives":{"types":"./dist/types/primitives-entry.d.mts","import":"./dist/types/primitives-entry.mjs"},"./templates/astro/*":"./src/templates/astro/*","./types/operational":{"types":"./dist/types/operational.d.mts","import":"./dist/types/operational.mjs"},"./server/maintenance":{"types":"./dist/server/maintenance.d.mts","import":"./dist/server/maintenance.mjs"}},"gitHead":"4083ff4ddb7fc3fbc4509890f46ff90f968251c3","scripts":{"test":"vp test run test/*.test.ts && tsc -p test/tsconfig.json","build":"npm run build:pack -- --clean","check":"vp check .","prepack":"npm run build","precheck":"npm run build","typecheck":"tsc --noEmit","build:pack":"vp pack src/index.ts src/acp.ts src/agent.ts src/admin.ts src/astro.ts src/astro-actions.ts src/api/client.ts src/email.ts src/provider.ts src/react.ts src/server.ts src/server/ports.ts src/server/maintenance.ts src/server/email.ts src/stripe.ts src/types/index.ts src/types/primitives-entry.ts src/types/aggregates.ts src/types/documents.ts src/types/operational.ts --format esm --dts --tsconfig tsconfig.json --deps.never-bundle astro/zod --deps.never-bundle react --deps.never-bundle stripe","pack:check":"npm run build:pack -- --clean --publint","types:check":"attw --pack . --profile esm-only --no-summary && tsc -p test/package-exports.tsconfig.json","release:check":"node scripts/check-release.mjs","prepublishOnly":"npm run check && npm run typecheck && npm run test && npm run templates:check && npm run pack:check && npm run types:check","templates:check":"astro check --root test/fixtures/astro-template-check"},"_npmUser":{"name":"bnomei","email":"b@bnomei.com"},"repository":{"url":"git+https://github.com/bnomei/emdash-mika.git","type":"git"},"_npmVersion":"11.16.0","description":"Agent-ready commerce primitives for content-led storefronts.","directories":{},"sideEffects":false,"_nodeVersion":"24.19.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"npm@11.16.0","devDependencies":{"ajv":"^8.20.0","astro":"^7.2.0","react":"^19.2.3","emdash":"^0.22.0","kysely":"^0.28.0","publint":"^0.3.21","react-dom":"^19.2.7","vite-plus":"^0.1.24","typescript":"^6.0.3","ajv-formats":"^3.0.1","@types/react":"^19.2.7","@astrojs/check":"^0.9.9","@astrojs/react":"^6.0.2","@cloudflare/kumo":"^2.5.2","@arethetypeswrong/cli":"^0.18.3","@libsql/kysely-libsql":"^0.4.1","@phosphor-icons/react":"^2.1.10"},"peerDependencies":{"astro":"^7.0.0","react":"^18.3.0 || ^19.0.0","emdash":">=0.22.0 <1.0.0","stripe":">=16.0.0 <21.0.0","react-dom":"^18.3.0 || ^19.0.0","@cloudflare/kumo":"^2.5.2","@phosphor-icons/react":"^2.1.10"},"peerDependenciesMeta":{"react":{"optional":true},"stripe":{"optional":true},"react-dom":{"optional":true},"@cloudflare/kumo":{"optional":true},"@phosphor-icons/react":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/emdash-mika_0.1.0_1786381725576_0.3065275861699974","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bnomei/emdash-mika","version":"0.1.1","description":"Agent-ready commerce primitives for content-led storefronts.","keywords":["agentic-commerce","astro","cart","cms","commerce","ecommerce","emdash","emdash-plugin","headless-commerce","subscription","typescript"],"homepage":"https://github.com/bnomei/emdash-mika#readme","bugs":{"url":"https://github.com/bnomei/emdash-mika/issues"},"license":"MIT","author":{"name":"Bruno Meilick","email":"b@bnomei.com","url":"https://bnomei.com"},"repository":{"type":"git","url":"git+https://github.com/bnomei/emdash-mika.git"},"type":"module","sideEffects":false,"main":"./dist/index.mjs","types":"./dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"},"./acp":{"types":"./dist/acp.d.mts","import":"./dist/acp.mjs"},"./agent":{"types":"./dist/agent.d.mts","import":"./dist/agent.mjs"},"./admin":{"types":"./dist/admin.d.mts","import":"./dist/admin.mjs"},"./astro":{"types":"./dist/astro.d.mts","import":"./dist/astro.mjs"},"./astro-actions":{"types":"./dist/astro-actions.d.mts","import":"./dist/astro-actions.mjs"},"./client":{"types":"./dist/api/client.d.mts","import":"./dist/api/client.mjs"},"./email":{"types":"./dist/email.d.mts","import":"./dist/email.mjs"},"./provider":{"types":"./dist/provider.d.mts","import":"./dist/provider.mjs"},"./react":{"types":"./dist/react.d.mts","import":"./dist/react.mjs"},"./server":{"types":"./dist/server.d.mts","import":"./dist/server.mjs"},"./server/ports":{"types":"./dist/server/ports.d.mts","import":"./dist/server/ports.mjs"},"./server/maintenance":{"types":"./dist/server/maintenance.d.mts","import":"./dist/server/maintenance.mjs"},"./server/email":{"types":"./dist/server/email.d.mts","import":"./dist/server/email.mjs"},"./stripe":{"types":"./dist/stripe.d.mts","import":"./dist/stripe.mjs"},"./templates/astro/*":"./src/templates/astro/*","./types":{"types":"./dist/types/index.d.mts","import":"./dist/types/index.mjs"},"./types/primitives":{"types":"./dist/types/primitives-entry.d.mts","import":"./dist/types/primitives-entry.mjs"},"./types/aggregates":{"types":"./dist/types/aggregates.d.mts","import":"./dist/types/aggregates.mjs"},"./types/documents":{"types":"./dist/types/documents.d.mts","import":"./dist/types/documents.mjs"},"./types/operational":{"types":"./dist/types/operational.d.mts","import":"./dist/types/operational.mjs"}},"publishConfig":{"access":"public"},"scripts":{"build":"npm run build:pack -- --clean","build:pack":"vp pack src/index.ts src/acp.ts src/agent.ts src/admin.ts src/astro.ts src/astro-actions.ts src/api/client.ts src/email.ts src/provider.ts src/react.ts src/server.ts src/server/ports.ts src/server/maintenance.ts src/server/email.ts src/stripe.ts src/types/index.ts src/types/primitives-entry.ts src/types/aggregates.ts src/types/documents.ts src/types/operational.ts --format esm --dts --tsconfig tsconfig.json --deps.never-bundle astro/zod --deps.never-bundle react --deps.never-bundle stripe","precheck":"npm run build","check":"vp check .","pack:check":"npm run build:pack -- --clean --publint","prepack":"npm run build","prepublishOnly":"npm run check && npm run typecheck && npm run test && npm run templates:check && npm run pack:check && npm run types:check","release:check":"node scripts/check-release.mjs","templates:check":"astro check --root test/fixtures/astro-template-check","test":"vp test run test/*.test.ts && tsc -p test/tsconfig.json","typecheck":"tsc --noEmit","types:check":"attw --pack . --profile esm-only --no-summary && tsc -p test/package-exports.tsconfig.json"},"devDependencies":{"@arethetypeswrong/cli":"^0.18.3","@astrojs/check":"^0.9.9","@astrojs/react":"^6.0.2","@cloudflare/kumo":"^2.5.2","@libsql/kysely-libsql":"^0.4.1","@phosphor-icons/react":"^2.1.10","@types/react":"^19.2.7","ajv":"^8.20.0","ajv-formats":"^3.0.1","astro":"^7.2.0","emdash":"^0.22.0","kysely":"^0.28.0","publint":"^0.3.21","react":"^19.2.3","react-dom":"^19.2.7","typescript":"^6.0.3","vite-plus":"^0.1.24"},"peerDependencies":{"@cloudflare/kumo":"^2.5.2","@phosphor-icons/react":"^2.1.10","astro":"^7.0.0","emdash":">=0.22.0 <1.0.0","react":"^18.3.0 || ^19.0.0","react-dom":"^18.3.0 || ^19.0.0","stripe":">=16.0.0 <21.0.0"},"peerDependenciesMeta":{"@cloudflare/kumo":{"optional":true},"@phosphor-icons/react":{"optional":true},"react":{"optional":true},"react-dom":{"optional":true},"stripe":{"optional":true}},"engines":{"node":">=22.12.0"},"packageManager":"npm@11.16.0","gitHead":"8e620ddfbb666b810014f5cef3fb962502bd0daf","_id":"@bnomei/emdash-mika@0.1.1","_nodeVersion":"24.19.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-AKUJUxFdnzYIj7stDvUsKKEkSxBHxrgm5DoGniysz9Z94eKXGTTNxpfcYFkc9thHLjmPSellAMufb34O5bSWFQ==","shasum":"44ccdbdf1b17de269500b5e32d8902d8c957c093","tarball":"https://registry.npmjs.org/@bnomei/emdash-mika/-/emdash-mika-0.1.1.tgz","fileCount":183,"unpackedSize":2656248,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDEAbu/fc5F5kOiGEnKcFJEQio4BSH23Xik9AB1PVoRYAIgQSldC32gPqIT5ghV1WiQpWcbkEQXdlPjZsCVdJegEmo="}]},"_npmUser":{"name":"bnomei","email":"b@bnomei.com"},"directories":{},"maintainers":[{"name":"bnomei","email":"b@bnomei.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/emdash-mika_0.1.1_1786383560069_0.9532906491843602"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-10T17:08:45.424Z","modified":"2026-08-10T17:39:20.427Z","0.1.0":"2026-08-10T17:08:45.759Z","0.1.1":"2026-08-10T17:39:20.275Z"},"bugs":{"url":"https://github.com/bnomei/emdash-mika/issues"},"author":{"name":"Bruno Meilick","email":"b@bnomei.com","url":"https://bnomei.com"},"license":"MIT","homepage":"https://github.com/bnomei/emdash-mika#readme","keywords":["agentic-commerce","astro","cart","cms","commerce","ecommerce","emdash","emdash-plugin","headless-commerce","subscription","typescript"],"repository":{"type":"git","url":"git+https://github.com/bnomei/emdash-mika.git"},"description":"Agent-ready commerce primitives for content-led storefronts.","maintainers":[{"name":"bnomei","email":"b@bnomei.com"}],"readme":"# @bnomei/emdash-mika\n\n[![documentation](https://img.shields.io/badge/docs-mika.bnomei.com-2563eb.svg)](https://mika.bnomei.com/)\n[![npm version](https://img.shields.io/npm/v/@bnomei/emdash-mika.svg)](https://www.npmjs.com/package/@bnomei/emdash-mika)\n[![npm downloads](https://img.shields.io/npm/dm/@bnomei/emdash-mika.svg)](https://www.npmjs.com/package/@bnomei/emdash-mika)\n[![license](https://img.shields.io/npm/l/@bnomei/emdash-mika.svg)](https://www.npmjs.com/package/@bnomei/emdash-mika)\n[![types](https://img.shields.io/badge/types-included-blue.svg)](./package.json)\n[![source](https://img.shields.io/badge/source-GitHub-181717.svg?logo=github)](https://github.com/bnomei/emdash-mika)\n\n**Start here: [Mika documentation](https://mika.bnomei.com/)**\n\nAgent-ready commerce primitives for content-led storefronts.\n\nMika is a native EmDash plugin shell for content-led Astro storefronts that\nneed carts, wishlists, checkout handoff, account links, subscriptions,\ndownloads, license-key fulfillment, stock-aware product variants, provider\nwebhooks, and agent-readable commerce metadata without adopting a full\ncommerce platform.\n\nEmDash and Astro are the first implementation surface. The larger job is making\nheadless and content-managed storefronts understandable to agents, search\ncrawlers, and checkout surfaces while keeping the merchant in control of the\nsite, payment provider, fulfillment, support, and customer relationship.\n\nIt is intentionally narrow. Mika provides typed commerce primitives, route\ncontracts, provider interfaces, Astro Actions, server helpers, operation\ndescriptors, and copyable Kumo-backed Astro templates. The host project still\nowns product content, frontend layout, payment-provider wiring, auth/session\npolicy, rate limits, tax/shipping rules, and final backend behavior.\n\nUse the [Mika documentation](https://mika.bnomei.com/) for the guided path from\ninstallation through backend wiring, storefront integration, deployment, and\nthe complete package reference. This README is the compact package overview.\n\n## What It Can Do\n\nStorefront flows:\n\n- Product purchase forms for one-time payments and subscriptions.\n- Stock-aware variants, quantity caps, low-stock notices, and unavailable\n  states.\n- Cart, wishlist, save-for-later, coupon, checkout start, token-bound checkout\n  return, and account portal flows through Astro Actions.\n- Magic-link account access, orders, subscriptions, downloads, account export,\n  and account delete request examples.\n\nBackend flows:\n\n- Host-owned `MikaApi` composition through explicit method overrides or\n  `createMikaBackendApi()`.\n- Provider contracts for hosted checkout, portal sessions, protected invoice\n  lookup, subscriptions, refunds, catalog sync, and signed webhooks.\n- Paid-order fulfillment side effects for entitlement documents, download refs,\n  and hashed license-key records.\n- Stock reservation lifecycle, email outbox delivery, account-delete cleanup,\n  and scheduled maintenance through the EmDash plugin lifecycle. The default\n  maintenance cron releases expired stock reservations out of the box; to also\n  drain the email outbox, purge expired ephemeral records, and process\n  account-delete batches, pass `maintenance.repositories` and\n  `maintenance.emailOutboxRunner` to `createMikaPlugin` from\n  `@bnomei/emdash-mika/server` in the host entrypoint module (otherwise those\n  tasks report `skipped`).\n- Admin operation descriptors and runner helpers for EmDash action UIs.\n\nAgent-ready commerce flows:\n\n- Public operation descriptors under `@bnomei/emdash-mika/agent`.\n- Copyable JSON-LD `Product`/`ProductGroup`/`Offer` metadata.\n- Copyable root `llms.txt` and `.well-known/mika-agent.json` examples.\n- ACP product-feed serializers and checkout endpoint handlers under\n  `@bnomei/emdash-mika/acp`.\n- Source material for host-owned UCP, MCP, OpenAPI, AP2, MPP, x402, or other\n  protocol projections.\n\nMika is not a catalog manager, page builder, tax engine, shipping-rate engine,\nmarketplace platform, hosted OAuth provider, MCP server, or bundled payment\nprovider SDK. Provider adapters and protocol projections should preserve\nMika's semantic core instead of leaking a single platform's field names into the\npackage.\n\n## Install\n\nFollow the [installation guide](https://mika.bnomei.com/getting-started/install/)\nfor prerequisites, workspace setup, and the first integration steps.\n\n```sh\nnpm install @bnomei/emdash-mika\n```\n\nPublished package contents are `dist/` plus copyable `src/templates` (see\n`package.json` `files`). Declaration maps (`.d.mts.map`) are emitted for monorepo\n/ path-mapped consumers that resolve into this repo’s `src/`; they do **not**\nprovide jump-to-source for plain npm installs of the published tarball alone.\n\n### Peer requirements\n\n| Peer                                         | Range             | Notes                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| -------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **astro**                                    | `^7.0.0`          | **Required** for the schema stack (`astro/zod` in validation and Actions). Hosts that only import `/server` still need Astro installed so Zod resolves from the same major as Actions. Developed and CI-tested on **Astro 7 only** (Vite 8, Rust compiler). Do not use reserved `src/fetch.ts` for app code under Astro 7 advanced routing. Cart/account/checkout routes must not use route caching (session/cookie variance). |\n| **emdash**                                   | `>=0.22.0 <1.0.0` | Required for native plugin registration.                                                                                                                                                                                                                                                                                                                                                                                       |\n| react / react-dom / stripe / kumo / phosphor | optional          | Only when using the matching subpath (`/react`, `/stripe`, templates with Kumo).                                                                                                                                                                                                                                                                                                                                               |\n\n## Three host faces\n\nHosts interact with Mika through three complementary faces. Pick the face that\nmatches the trust boundary; do not expand the browser client to authenticated\nmutations. The [integration map](https://mika.bnomei.com/concepts/integration-map/)\nexplains how these faces fit together in a host application.\n\n| Face               | Package surface                                                                                                                                 | When to use                                                                                                                                |\n| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| **1. Backend API** | `@bnomei/emdash-mika/server` — `MikaApi`, `createMikaBackendApi()`, overrides                                                                   | Compose commerce behavior once (repos, providers, notifications). Injected into the EmDash plugin entrypoint and shared by routes/actions. |\n| **2. In-process**  | `@bnomei/emdash-mika/astro` (`createMika`) and `@bnomei/emdash-mika/astro-actions` (`createMikaActions`)                                        | Astro pages and form/JSON Actions on the server. Same `MikaApi` instance; no extra HTTP hop.                                               |\n| **3. HTTP**        | `@bnomei/emdash-mika/client` (`createMikaClient` — public catalog/stock only) and `createMikaServerClient` on `/server` (full operation facade) | Browser-safe public reads, or server-to-plugin HTTP when you need the route surface without importing the full backend graph.              |\n\nSupporting entrypoints stay projections of the same semantic core: `/agent`\n(manifest), `/acp` (ACP feed/handlers), `/admin`, `/provider`, `/stripe`,\n`/email`, `/types` (plus `/types/primitives`), and discoverability re-exports\n`/server/ports`, `/server/maintenance`, `/server/email`. The root package export\nis **descriptor-only** (`mikaPlugin`); live `api` wiring never belongs on the\nJSON-safe root.\n\nCreate a host entrypoint module that merges the live backend api:\n\n```ts\n// src/lib/mika-plugin.ts — EmDash plugin entrypoint\n// (copyable template: src/templates/astro/lib/mika-plugin.ts)\nimport { createMikaPlugin, type MikaCreatePluginOptions } from \"@bnomei/emdash-mika/server\";\nimport { api } from \"./mika-api\";\n\nexport function createPlugin(options: MikaCreatePluginOptions = {}) {\n  return createMikaPlugin({ ...options, api });\n}\n```\n\nThen register it in `astro.config.mjs`:\n\n```ts\nimport { fileURLToPath } from \"node:url\";\nimport { defineConfig } from \"astro/config\";\nimport { emdash } from \"emdash/astro\";\nimport { mikaPlugin } from \"@bnomei/emdash-mika\";\n\nexport default defineConfig({\n  integrations: [\n    emdash({\n      plugins: [\n        mikaPlugin({\n          entrypoint: fileURLToPath(new URL(\"./src/lib/mika-plugin.ts\", import.meta.url)),\n        }),\n      ],\n    }),\n  ],\n});\n```\n\n`api` is the host-owned Mika backend implementation. It can be built from\nrepositories and provider adapters with `createMikaBackendApi()`, or supplied as\nexplicit `MikaApi` method overrides.\n\nPlugin construction asserts every `MikaApi` method is wired and throws\notherwise — unwired methods would answer `501` on every route at runtime. Pass\n`assertWired: [\"cart\", \"checkout.start\"]` to assert a subset, or\n`assertWired: false` to accept partial wiring.\n\n## Host-owned business quotes\n\nMika's built-in quote reprices catalog lines, applies the configured coupon\nresolver, and checks availability. It deliberately does not calculate tax,\nshipping, or business-specific fees. Hosts that need those values should pass\none `quoteResolver` to `createMikaBackendApi()` and return them through\n`CartQuoteDTO.tax`, `.shipping`, `.adjustments`, and `.total`.\n\nThe resolver runs inside Mika's shared quote path. Its result is reused by cart\nquote, checkout preview, delegated-payment proof, checkout provider handoff,\nand persisted checkout/order totals. Do not override only `cart.quote` to add\nbusiness amounts: operation overrides remain available for replacing complete\nworkflows, but a display-only override cannot change checkout's charge.\nProvider adapters must apply the authoritative total or reject it. Mika's\nbuilt-in delegated Stripe path charges it directly; the hosted Stripe adapter\nrejects host-added amounts because its line/coupon projection cannot represent\nthem without host-specific Stripe configuration.\n\n`CartQuoteLineDTO.fulfillmentKind` carries provider-neutral classification into\nthe quote. Use `external` for physical or otherwise host-fulfilled lines; the\nhost still owns addresses, rates, carriers, delivery, and policy decisions.\nMika's built-in delegated-payment proof binds the quote items, subtotal,\ndiscount, tax, shipping, adjustments, and total before provider handoff.\n\nThe compile-checked\n[`business-quote-resolver.ts`](./test/fixtures/business-quote-resolver.ts)\nfixture and its\n[`business-quote.test.ts`](./test/business-quote.test.ts) proof show tax,\nshipping, a fee, and mixed download/external fulfillment using only public\npackage exports. They are integration scaffolding, not a tax or shipping\nimplementation.\n\n## Errors\n\nBranch on `error.code` from failed {@link MikaApiResult} envelopes — never parse\n`error.message` for control flow. Codes are stable and additive\n(`MIKA_ERROR_CODES` on `@bnomei/emdash-mika/types`). New codes include\n`IDEMPOTENCY_MISMATCH`, `WEBHOOK_DEFERRED`, and `STOCK_CONFLICT` for\ncallers that previously over-used generic `CONFLICT`.\n\n## Maintenance wiring\n\nSee the [deployment and maintenance guide](https://mika.bnomei.com/guides/deployment-maintenance/)\nfor the production checklist and scheduling model.\n\nThe default EmDash maintenance cron only **releases expired stock reservations**\nunless the host injects more ports:\n\n```ts\n// src/lib/mika-plugin.ts\nimport {\n  createMikaPlugin,\n  createMikaEmailOutboxRunner,\n  type MikaCreatePluginOptions,\n} from \"@bnomei/emdash-mika/server\";\nimport { api } from \"./mika-api\";\n\nexport function createPlugin(options: MikaCreatePluginOptions = {}) {\n  return createMikaPlugin({\n    ...options,\n    api,\n    maintenance: {\n      repositories: {\n        // stock is usually already required for commerce; pass the same ports\n        // you wired into createMikaBackendApi for email/ephemeral/account-delete\n      },\n      emailOutboxRunner: createMikaEmailOutboxRunner({\n        /* host sender + repos */\n      }),\n    },\n  });\n}\n```\n\nWithout those injects, outbox drain, ephemeral purge, and account-delete batches\nreport `skipped` in maintenance results (stock release still runs).\n\nThe entrypoint module exists because the EmDash host JSON-serializes descriptor\noptions into a generated module — function values like a live `api` or\n`operationPolicy` are silently dropped, so `mikaPlugin()` rejects them at\nconfig time. Only JSON-safe options (`maintenance.enabled`,\n`maintenance.schedule`, `assertWired`) flow through the descriptor and arrive\nin the entrypoint's `options`. Use `fileURLToPath` from `node:url` rather than\n`URL.pathname` — `pathname` produces `/C:/...` paths that fail module\nresolution on Windows. The host imports the entrypoint from a generated\nvirtual module, so it must be an absolute path or a bare package specifier,\nnot a config-relative `./` path.\n\n## Examples\n\nFor the shortest runnable path, start with the\n[template quickstart](https://mika.bnomei.com/getting-started/quick-start-template/).\nThe [template map](https://mika.bnomei.com/examples/template-map/) explains what\nto copy and what the host is expected to own.\n\nThe package includes copyable Astro templates and stable example docs under:\n\n```txt\nsrc/templates/astro/actions\nsrc/templates/astro/components\nsrc/templates/astro/lib\nsrc/templates/astro/pages\nsrc/templates/astro/styles\nsrc/templates/astro/examples\nsrc/templates/astro/README.md\n```\n\nStart with:\n\n- [First release slice](./src/templates/astro/examples/release-slice.md) for\n  what should ship first and what should stay out of scope.\n- [Astro storefront](./src/templates/astro/examples/astro-storefront.md) for\n  plugin registration, actions, product pages, cart, wishlist, checkout,\n  account, downloads, and webhook copy paths.\n- [Backend and provider wiring](./src/templates/astro/examples/backend-provider.md)\n  for repositories, provider adapters, email delivery, and maintenance.\n- [Agent-ready storefront](./src/templates/astro/examples/agent-ready-storefront.md)\n  for JSON-LD, `llms.txt`, `.well-known/mika-agent.json`, and protected agent\n  flow boundaries.\n- [Astro template README](./src/templates/astro/README.md) for the directory\n  map, copy paths, imports, route shape, sessions, and security boundary.\n\n## High-Level Usage\n\nCopy the template action files into the host app:\n\n```txt\nsrc/actions/index.ts\nsrc/actions/mika.ts\n```\n\nThen expose Mika's Astro Actions, passing the same `api` the entrypoint\nmodule merges:\n\n```ts\nimport { createMikaActions } from \"./mika\";\nimport { api } from \"../lib/mika-api\";\n\nexport const server = {\n  mika: createMikaActions({ api }),\n};\n```\n\nBrowser forms submit to action names such as `actions.mika.cart.add`,\n`actions.mika.checkout.start`, and `actions.mika.wishlist.add`. Host projects\ncan pass a `guard` option to apply rate limits, auth checks, bot checks, or\nfeature locks before a Mika action reaches the request-bound backend API.\n\nStorefront pages use the request-bound Astro helper, also wired with `api`:\n\n```ts\nimport { createMika } from \"@bnomei/emdash-mika/astro\";\nimport { api } from \"../lib/mika-api\";\n\nconst Mika = createMika(Astro, { api });\nconst sellablesResult = await Mika.catalog.sellables(\"products\", productId);\n```\n\nNeither helper has a process-global default `api` — every call site imports\nit explicitly. This keeps behavior local to each module and safe for hosts\nthat construct more than one Mika-backed integration in the same process.\n\nProduct UI is copyable Astro, not a hidden route system. Copy only the pages and\ncomponents the host project needs, then keep localization and product routing in\nthe host app. The template UI uses Kumo components and Kumo semantic tokens.\n\nCheckout success and cancel pages are return surfaces for the browser. Treat\ncancel redirects as UX only, and confirm final payment/order state through the\nhost's provider-backed checkout and order APIs.\n\n## Agent-Ready Commerce\n\nThe [agent-ready storefront guide](https://mika.bnomei.com/guides/agent-ready-storefront/)\ncovers the public discovery surfaces and the protected-operation boundary.\n\nMika exposes a semantic operation manifest for hosts that want to make a\nstorefront available to agents without moving OAuth, payment credentials, or\nprotocol hosting into Mika:\n\n```ts\nimport { createMikaAgentManifest, mikaAgentManifestJsonSchema } from \"@bnomei/emdash-mika/agent\";\n\nexport const manifest = createMikaAgentManifest();\nexport const schema = mikaAgentManifestJsonSchema;\n```\n\nThe manifest describes operation names, capabilities, side effects, risk,\nrequired actor shape, scopes, confirmation policy, idempotency expectations,\nproof refs, resources, and public route hints. Public storefront examples\nexpose safe catalog and stock reads. Protected cart, checkout, account, order,\npayment, admin, and agent-tool flows still require host-owned OAuth or session\npolicy, confirmation, replay storage, rate limits, provider wiring, and payment\nrail verification.\n\nMika's agent-ready path starts with accurate storefront metadata and stable\ncommerce semantics. ACP, UCP, MCP, OpenAPI, AP2, MPP, x402, and other agent or\npayment protocols should be generated as host-owned projections from those\ncontracts rather than becoming the core product model.\n\nACP and Stripe are optional edge surfaces:\n\n```ts\nimport { createMikaAcpCheckoutHandlers, createMikaAcpProductFeed } from \"@bnomei/emdash-mika/acp\";\nimport { createMikaStripeProvider } from \"@bnomei/emdash-mika/stripe\";\n```\n\nThe ACP helpers serialize Mika catalog/sellable facts into OpenAI-compatible\nproduct-feed shapes and expose checkout session handlers for host Astro\nendpoints. The Stripe helper adapts a host-owned Stripe SDK client to Mika's\nprovider contract, including hosted Checkout Sessions, paid-state webhook\nnormalization, signed webhooks, protected invoice lookup, and delegated\ncheckout metadata for Stripe Shared Payment Tokens.\n\nMika's checkout handlers support `API-Version: 2025-09-12` and pin conformance\nto the official ACP `2025-09-29` checkout schema snapshot. This surface supports\nStripe delegated payments only. Mika advertises digital fulfillment only when\nevery quoted line is explicitly classified as a download, license, or\nentitlement; external, mixed, unavailable, and otherwise unknown fulfillment\nis omitted because Mika does not invent shipping rates, carriers, or delivery\nwindows. Upgrade the API version and schema snapshot together.\n\n## Notifications And Email\n\nTrusted backends can pass a notification hook to `createMikaBackendApi()`:\n\n```ts\nimport type { MikaNotificationHook } from \"@bnomei/emdash-mika/server\";\n\nconst handleNotification: MikaNotificationHook = async (intent) => {\n  if (intent.kind === \"order.confirmed\") {\n    await queueHostEmail(intent);\n    return { handled: true };\n  }\n};\n```\n\nThe hook receives typed `MikaNotificationIntent` objects for commerce events\nsuch as `magic_link.requested`, `order.confirmed`,\n`checkout.payment_failed`, `download.ready`, `license.issued`,\nsubscription lifecycle events, account export/delete events, and webhook\nfailures. `undefined` or `{ handled: false }` lets Mika continue default\nhandling when one exists. `{ handled: true }` suppresses Mika's built-in email\nfor that intent. Hook exceptions are swallowed and default delivery still\nruns — only an explicit `{ handled: true }` suppresses it. A throwing hook is\nnot retried and does not fail the backend operation, so hosts should queue\ntheir own notification/email work durably inside the hook rather than relying\non backend retries.\n\nMika currently ships default email rows and renderers for magic links and order\nconfirmations only. Other notification kinds are host hooks; they do not create\nMika email outbox rows until a default renderer is intentionally added. The\nexisting email outbox runner remains compatible with Mika's queued\n`magic_link` and `order_confirmation` email documents.\n\n## Digital Delivery Boundary\n\nSee [accounts and downloads](https://mika.bnomei.com/guides/account-downloads/)\nfor the complete host integration flow.\n\nMika records digital fulfillment without owning private storage or raw secrets.\nA built-in download produces an opaque `download:*` reference. After token\nauthorization, `DownloadResolutionDTO.downloadRef` exposes that evidence;\n`redirectUrl` is absent until host code explicitly maps the reference to a real\nasset. Treat the reference as an identifier, never as a URL or storage path.\n\nA production host can wrap the existing `download.resolve` and\n`download.confirm` operations. Resolve through Mika first to retain order,\nentitlement/license, expiry, and revocation checks; map `downloadRef` to a\nshort-lived HTTPS URL; then let Mika consume the token during confirmation.\nResolve/sign before consuming so a storage failure does not burn the buyer's\none-time token, and never let the signed URL outlive Mika's token expiry. The compile-checked\n[`digital-delivery.ts`](./test/fixtures/digital-delivery.ts) fixture shows this\nusing public package exports only.\n\nLicense fulfillment is evidence-only too. Mika stores a deterministic hash and\ndisplay suffix and emits `license.issued` with IDs and the suffix—never a raw\nkey. Queue a durable host job from that notification; the worker can generate,\nstore, and deliver the raw credential in a secret-capable system. Use\n`licenseId` as the idempotency anchor.\n\nHosts must authorize before asset resolution, keep signed URLs short-lived,\npreserve Mika's single-use confirmation and replay errors, and redact tokens,\nraw keys, signed URLs, and provider secrets from logs. Mika intentionally ships\nno object-storage adapter, URL signer, license server, or digital-delivery email\nprovider.\n\n## Package Surface\n\nThe [package exports reference](https://mika.bnomei.com/reference/package-exports/)\nis the canonical entrypoint guide.\n\n- ESM entry: `@bnomei/emdash-mika` for descriptor-focused plugin registration.\n- ACP feed and checkout projection helpers: `@bnomei/emdash-mika/acp`.\n- Agent descriptors, proof refs, actor contracts, and agent vocabulary:\n  `@bnomei/emdash-mika/agent`.\n- Admin action helpers: `@bnomei/emdash-mika/admin`.\n- Astro helpers: `@bnomei/emdash-mika/astro`.\n- Astro Actions: `@bnomei/emdash-mika/astro-actions`.\n- Browser-safe catalog and stock client: `@bnomei/emdash-mika/client`.\n- Email helpers: `@bnomei/emdash-mika/email`.\n- Provider contracts: `@bnomei/emdash-mika/provider`.\n- React headless helpers: `@bnomei/emdash-mika/react`.\n- Server runtime plugin activation, server contracts, and trusted JSON client:\n  `@bnomei/emdash-mika/server`.\n- Optional Stripe provider adapter: `@bnomei/emdash-mika/stripe`.\n- DTO, input/result, and branded primitive types: `@bnomei/emdash-mika/types`.\n- Public aggregate, document, and operational type barrels:\n  `@bnomei/emdash-mika/types/aggregates`,\n  `@bnomei/emdash-mika/types/documents`, and\n  `@bnomei/emdash-mika/types/operational`.\n- Copyable files: `@bnomei/emdash-mika/templates/astro/*`.\n\nThe package intentionally does not expose a public `storage` subpath. Storage\nrepositories, migrations, and SQL statements are implementation details until\nthe backend service layer is stable enough to support as public API.\n\n## Documentation\n\nThe complete documentation lives at **[mika.bnomei.com](https://mika.bnomei.com/)**:\n\n- [Getting started](https://mika.bnomei.com/getting-started/)\n- [Concepts and architecture](https://mika.bnomei.com/concepts/)\n- [Integration guides](https://mika.bnomei.com/guides/)\n- [Examples](https://mika.bnomei.com/examples/)\n- [Package reference](https://mika.bnomei.com/reference/)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}