Packages and imports

Adocommerce Kit has eleven public packages. The workspace manifests currently use the lockstep 1.3.0-0 prerelease version; regional packages retain a @adocommercekit/core@^1.1.0 capability floor, but every public package publishes together. Install matching exact versions and review stability and compatibility before deployment.

@adocommercekit/core

The core package owns the domain contract and Adonis integration. It includes:

• host-owned migrations for channels, catalog and product images, customers, pricing, carts, fulfillment, taxes, orders, inventory, deferred/COD payments, payment instructions, idempotency, event outbox, and workflow state;
• Lucid models, product/variant image relationships, and a runtime model registry;
• catalog, product-image, customer, pricing, cart, static and dynamic shipping, fulfillment, tax, inventory, order, payment, checkout, idempotency, and event-outbox services;
• money, parcel, capability, state-machine, workflow, event, transformer, job, storage-driver, and error primitives;
• the Commerce service provider and Ace commands.

Install and configure it first:

pnpm add @adocommercekit/core
node ace configure @adocommercekit/core
node ace migration:run
node ace commerce:doctor

Public entrypoints

Prefer these documented entrypoints. Files below them are package internals and are not part of the published export map.

@adocommercekit/storefront-api

This optional package publishes a REST storefront into the host application. It does not mount runtime code from node_modules.

pnpm add @adocommercekit/storefront-api
node ace configure @adocommercekit/storefront-api

The configurator publishes:

• product, cart, checkout, order, and payment-webhook controllers;
• request validators and serialization helpers;
• commerce error, fixed-window rate-limit, and raw-body middleware;
• 14 routes below /api/commerce, including authorized payment-instruction reads;
• upgrade baselines in .commercekit/publications.

The generated code is intentionally editable. Keep the route names if other application code depends on them, but otherwise treat the files like normal host code.

Public entrypoints

See the REST API reference before changing the published contract.

@adocommercekit/admin-api

This optional package publishes a REST management surface and the admin service layer into the host application. It does not mount runtime code from node_modules. Headless hosts stop here; @adocommercekit/admin consumes it.

pnpm add @adocommercekit/admin-api @adonisjs/bouncer
node ace configure @adocommercekit/admin-api
node ace migration:run

The configurator aborts unless @adocommercekit/core is already configured, then publishes:

• one controller group per resource under app/controllers/commerce_admin/;
• request validators and a serialization/idempotency/audit helper service;
• authentication, ability, and actor-keyed rate-limit middleware;
• a deny-by-default Bouncer policy per resource group under app/policies/commerce/;
• 42 routes below /api/commerce/admin, every one behind an ability from the frozen catalog;
• the append-only admin_audit_entries migration;
• upgrade baselines in .commercekit/publications.

Every ability denies until the host implements commerceAdminRoles() in app/policies/commerce/main.ts; commerce:doctor fails while it is unmapped.

Public entrypoints

See the Admin REST API reference before changing the published contract.

@adocommercekit/admin

This optional package publishes an Inertia + React management panel into the host application at /admin/commerce. It depends on @adocommercekit/admin-api for its service layer and for the metrics endpoints its charts refetch.

pnpm add @adocommercekit/admin
node ace configure @adocommercekit/admin

The configurator aborts unless @adocommercekit/admin-api and @adonisjs/inertia are configured and every UI runtime dependency is already in the host package.json — it prints the exact pnpm add line and installs nothing. It performs no network access: the coss and Bklit component trees are vendored inside the tarball. It then publishes:

• Inertia controllers under app/controllers/commerce_admin_panel/, a shared-props/ability/mutation seam, and panel validators;
• 31 routes below /admin/commerce, every one behind an ability from the frozen catalog and the same rate-limit buckets as the REST mutations;
• the eight page surfaces of the closed page inventory under inertia/pages/admin/commerce/;
• 43 vendored coss primitives and 87 vendored Bklit chart files under inertia/components/commerce/, plus registry_provenance.json recording their upstream revisions, licenses, and content hashes;
• money/date/ability/query helpers, the English i18n catalog, and one self-contained Tailwind v4 token layer;
• upgrade baselines in .commercekit/publications.

The page inventory, the coss primitive set, and the Bklit chart set are closed lists; extending any of them is a specification change. Every panel capability is also reachable through @adocommercekit/admin-api with the same ability and the same audit entry.

Public entrypoints

See the admin panel guide for install, customization, theming, and the vendored-file story.

@adocommercekit/stripe

This optional package implements the core PaymentProvider port with Stripe PaymentIntents.

pnpm add @adocommercekit/stripe
node ace configure @adocommercekit/stripe

The configure hook adds STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET to the Adonis environment schema. You must still register stripe() in config/commerce.ts.

Public entrypoints

See Stripe setup for registration, checkout, webhook, and local testing instructions.

@adocommercekit/midtrans

Midtrans Core API v2 deferred payments for QRIS, BCA/BNI/BRI virtual accounts, Mandiri bill-key, Permata VA, GoPay, Indomaret, and Alfamart. Configure one factory per checkout method so the selected channel is explicit.

pnpm add @adocommercekit/midtrans
node ace configure @adocommercekit/midtrans

The package exports midtrans(), MidtransPaymentProvider, the per-channel MIDTRANS_REFUND_CAPABILITIES matrix, and MidtransManualRefundRequiredError. Automatic refunds are offered only for QRIS and GoPay; other channels require an operator-recorded manual-transfer reference. Notifications use Midtrans’s exact SHA-512 formula, then re-query current transaction status before returning a normalized event.

@adocommercekit/xendit

Xendit Payment Requests API 2024-11-11 deferred payments for QRIS, BCA/BNI/BRI/Mandiri virtual accounts, OVO, and DANA-compatible redirect flows.

pnpm add @adocommercekit/xendit
node ace configure @adocommercekit/xendit

The package exports xendit(), XenditPaymentProvider, and XENDIT_API_VERSION. It uses Basic secret-key API authentication and constant-time x-callback-token webhook verification; Midtrans signature rules do not apply.

@adocommercekit/id

The Indonesia bundle provides kode-unik payments, an importer-only administrative-region store, opt-in Indonesian address validation and host-published typeahead routes, PMK 131/2024 PPN calculation and audit export, idempotent COD remittance import, UU PDP consent/rights/retention mechanisms, and reviewed-key regional catalogs.

pnpm add @adocommercekit/id
node ace configure @adocommercekit/id
node ace migration:run

No copyrighted region rows are bundled. commerce:id:regions-import --file accepts a host-licensed JSON source with source URL, retrieval date, version, license URL, checksum, corrections, and region records. The configure hook publishes the portable regional/PDP/COD tables plus reviewable host-owned config, validator, controller, and route stubs, records their publication bases, and exposes @adocommercekit/id/upgrade so later commerce:upgrade runs produce reviewable no-op/update/conflict plans. The host must approve the source’s distribution and update terms before import.

kodeUnik() allocates visible codes 001–999 with a normal unique key on (receiving_account, code). ppnCalculator() records the statutory rate, DPP fraction and amount, rounding, price mode, category, and tax in adjustment metadata; PPnBM is not calculated. CustomerService.export() supplies the minimized core portability document, while PdpRightsService adds consent and request receipts behind a mandatory host authorizer. Start with Build commerce for Indonesia and the PDP operations runbook.

@adocommercekit/biteship

Biteship API v1 dynamic rates and fulfillment through the generic quote and fulfillment ports. Full parcel values, weight, dimensions, destination, COD, insurance, currency, and provider options participate in quote/cache identity. Preparation requires the selected courier:service, creates the waybill, and keeps handoff separate.

pnpm add @adocommercekit/biteship
node ace configure @adocommercekit/biteship

The package exports biteship(), BiteshipProvider, BITESHIP_API_VERSION, and typed failures. Rate cache TTL is capped at 60 seconds. Tracking webhooks fail closed unless the host supplies a verifier matching its pinned Biteship contract.

@adocommercekit/rajaongkir

Komerce RajaOngkir API v1 rates and available tracking provide the second generic quote implementation.

pnpm add @adocommercekit/rajaongkir
node ace configure @adocommercekit/rajaongkir

The package exports rajaOngkir() and RajaOngkirProvider. Its capability declaration explicitly reports waybill creation, fulfillment, COD, and insurance as unsupported rather than emulating them.

@adocommercekit/whatsapp

Opt-in WhatsApp Business Cloud template notifications for order, payment, and shipment events.

pnpm add @adocommercekit/whatsapp
node ace configure @adocommercekit/whatsapp

The package requires a caller-pinned Graph API version and current purpose/notice consent both before enqueue and before send. Delivery retries use the jobs port; unapproved templates and retry exhaustion call only a host-configured fallback. Default configuration is disabled and assumes no email or fallback notifier.

Choosing a package set

Related

• Build a store in an afternoon
• Build commerce for Indonesia
• Configuration reference
• Stability and compatibility