khalidadil
0 Followers · 0 Following
  • Joined on 2025-08-25
Repositories
3
 Projects Packages Public Activity Starred Repositories

@khalidadil/commerce-manager (0.2.0)

Published 2026-09-02 02:15:06 +00:00 by khalidadil

Installation

@khalidadil:registry=
npm install @khalidadil/commerce-manager@0.2.0
"@khalidadil/commerce-manager": "0.2.0"

About this package

@khalidadil/commerce-manager

Generic shop-logic module for any Node web app: server-backed multi-currency carts, checkout orchestration, an order state machine, discount codes, inventory, transactional email, customer order history, and webhook processing — Postgres-backed (module-owned commerce schema), SureCart-powered via @khalidadil/surecart-commerce.

The host keeps what's host-shaped: the product catalog (a resolveItem adapter), identity (any auth), fulfillment execution (event handlers), the admin UI (this module ships the admin API), and the brand/storefront.

Install

npm config set @khalidadil:registry https://git.kadil.dev/api/packages/khalidadil/npm/
npm install @khalidadil/commerce-manager

Wire-up (the whole contract)

import { createCommerce } from '@khalidadil/commerce-manager';
import { createCommerceRouter } from '@khalidadil/commerce-manager/express';

const commerce = createCommerce({
  db: pgPool,                      // module migrates its own `commerce` schema
  surecart: checkoutService,       // from @khalidadil/surecart-commerce
  catalog: { resolveItem(ref, currency) { /* host catalog → name/amount/pricing */ } },
  shipping: { flatRateCents: { usd: 600 }, freeThresholdCents: { usd: 20_000 }, skeletonPriceId },
  email: { sender: resendSender({ apiKey, from }) },
  webhooks: { signingSecret },     // enables the raw-body receiver
  config: { currencies: ['usd'], mode: 'test', approvalGate: 'auto' },
});
await commerce.migrate();
app.use('/api/shop', createCommerceRouter(commerce, { identity: (req) => host.auth(req) }));
commerce.events.on('order.paid', ({ order }) => startFulfillment(order));

A complete runnable host lives in examples/store.mjs; test/live/http.live.test.ts drives the same surface end-to-end against the real SureCart API (test mode): cart → checkout → mock payment → reconcile → history → admin fulfillment.

The rules the module enforces

  • Prices are never trusted from storage — every cart write AND checkout re-resolves through the catalog in the cart's pinned currency; the module never converts FX.
  • Discounts are computed here and reach SureCart as adjusted ad-hoc amounts (quantity-1, line-total) on skeleton prices — because SureCart silently ignores ad_hoc_amount on regular prices (probe-verified). A discounted item without an adHoc.skeletonPriceId fails loudly.
  • Orders move through pending_payment → paid → approved → fulfilling → fulfilled → completed (plus payment_failed / cancelled / refunded), every transition validated and ledgered in order_events. markPaid is idempotent: webhook-truth totals, inventory consumption, discount redemption, and the approval gate run exactly once.
  • Webhooks verify (HMAC scheme from surecart-commerce), dedup by (provider, event_id), and process tolerantly; reconcilePendingOrders() is the missed-webhook fallback (also exposed as POST /admin/reconcile).
  • Inventory is an opt-in oversell guard (consumed on paid, restocked on refund) — reservations are a later concern.

Test layout

npm run build
npm run test:db    # services vs the dedicated Postgres (commerce-pg:5434, test DB)
npm run test:live  # real SureCart test-mode e2e; needs SURECART_API_TOKEN in .env

Deliberate v0.1 boundaries

  • Async work (emails, webhook processing) is synchronous; pg-boss queueing is the planned 0.2 upgrade.
  • Storefront React components are 0.2 — payment UI already ships in @khalidadil/surecart-commerce/react.
  • Refunds are full-order; SureCart's production webhook event names still need confirmation against a real delivery (the processor's event lists are configurable for exactly that reason).
  • One SureCart store = one currency (API-verified): multi-currency deployments run one store per currency and one CheckoutService per store.

Dependencies

Dependencies

ID Version
@khalidadil/surecart-commerce ^0.1.0
pg ^8.13.1

Development Dependencies

ID Version
@types/express ^4.17.21
@types/pg ^8.11.10
express ^4.21.2
tsx ^4.19.2
typescript ^5.7.3

Peer Dependencies

ID Version
express ^4.18.0 || ^5.0.0
Details
npm
2026-09-02 02:15:06 +00:00
0
39 KiB
Assets (1)
commerce-manager-0.2.0.tgz 39 KiB
Versions (5) View all
0.4.0 2026-09-02
0.3.1 2026-09-02
0.3.0 2026-09-02
0.2.0 2026-09-02
0.1.0 2026-09-01