@spinekit/promo

@spinekit/promo

Promotions — programs, vouchers, rules, rewards, and cart evaluation — as composable arc resources.

Part of Spine, Classytic's ERP — the arc-module layer that composes the framework-agnostic @classytic/promo kernel into an @classytic/arc application via createApp({ modules }).

Install

npm install @spinekit/promo @classytic/promo @classytic/arc @classytic/mongokit mongoose zod

Kernels and the framework are peer dependencies — the host installs a single copy; this module bundles nothing.

Usage

import { createApp } from '@classytic/arc/factory';
import { createPromoModule } from '@spinekit/promo';
import { createPromoEngine } from '@classytic/promo';

const engine = createPromoEngine({ mongoose: connection, tenant: false });
const app = await createApp({
  modules: [
    createPromoModule({
      engine,                        // BYO — carries tenancy + event transport
      permissions,                   // granular gates per entity (see PromoPermissions)
      // resolveActor, prefixes, extraRoutes as needed
    }),
  ],
});

Mounts /promotions/{programs,vouchers,rules,rewards,evaluate} — adapter CRUD, Stripe-pattern FSM actions (activate/pause/archive, cancel, commit/rollback), code-centric voucher routes, and preview/evaluate.

Company-wide by default (tenantField: false): in a single-tenant multi-branch deployment, a voucher generated at one branch redeems at any other. Wire-error contract included: the kernel's hierarchical codes map to stable UPPER_SNAKE codes + HTTP statuses (PROMO_CODE_TO_WIRE) so every host serves the identical public contract.

The engine is exported at fastify.arc.modules.promo — order-placement choreography (reserve → commit/rollback) stays host policy over that export.

License

MIT Classytic