@masivo/admin

Server-side Masivo SDK. Use this from host backends (Node) — not from the React Native / browser CLIENT bundles (@masivo/rn, @masivo/client, @masivo/core).

Today this package exposes local cart / reward / coupon condition validation (sync, no HTTP). Future admin APIs that talk to Masivo with a SERVER key will live here as well.

Install

npm install @masivo/admin
# or
pnpm add @masivo/admin

Migration from @masivo/core / @masivo/rn

Cart validation used to live on client.rules in core/rn. It was moved here (breaking). Update imports:

// Before
import { createRNClient } from "@masivo/rn";
const masivo = createRNClient({ apiKey: "..." });
masivo.rules.validateRewardConditions({ reward, context });

// After
import { createAdminClient } from "@masivo/admin";
// or: import { validateRewardConditions } from "@masivo/admin";

const admin = createAdminClient();
admin.rules.validateRewardConditions({ reward, context });

Local cart / reward / coupon conditions (no HTTP, no DB)

Conditions already come on the reward / campaign payload you have — you do not need an extra request to look up the rule text.

Custom errors set in the Masivo dashboard (invalidMessage on each condition) are returned in result.reason when that condition fails. result.isCustomError is true when the message came from the dashboard.

Rewards (wallet / catalog)

import { createAdminClient } from "@masivo/admin";

const admin = createAdminClient();

const result = admin.rules.validateRewardConditions({
  reward: benefit.reward, // has reward.conditions (OR of ANDs)
  context: {
    orderValue: subtotalWithoutRewardProduct,
    products: cartProducts.map(p => ({
      sku: `${p.attributes?.externalId ?? p.productId}`,
      amount: p.amount,
      ids: [`${p.productId}`, `${p.attributes?.externalId ?? ""}`]
    })),
    storeId: selectedStoreId,
    storeIds: [externalStoreCode].filter(Boolean),
    channelId: selectedCatalogueId,
    platform: "app"
  },
  defaultMessage: "This reward cannot be applied"
});

if (!result.ok) {
  // show result.reason — custom invalidMessage when the user set one
}

Coupons (campaigns)

Coupon conditions live on campaign rules. Resolve the code against campaigns you already loaded, then validate the cart before calling redeem (local UX only; redeem stays source of truth on the server):

const campaign = campaignsByCode.get(typedCode.toUpperCase());
if (!campaign) {
  showToast("Invalid coupon code");
  return;
}

const result = admin.rules.validateCampaignRules({
  rules: campaign.rules,
  context: {
    orderValue: cartSubtotal,
    products: cartProducts.map(p => ({
      sku: `${p.sku}`,
      amount: p.quantity,
      ids: p.ids
    })),
    storeId: selectedStoreId,
    channelId: selectedChannelId,
    platform: "app"
  },
  defaultMessage: "Conditions not met"
});

if (!result.ok) {
  showToast(result.reason);
  return;
}
// optional: proceed to POST /coupons/redeem

Raw conditions array

admin.rules.validateConditions({
  conditions: benefit.reward.conditions,
  context: {
    /* same cart snapshot */
  },
  defaultMessage: "This reward cannot be applied"
});

Pass a ValidationContext snapshot (no HTTP at validate time):

• Cart: orderValue, products, storeId / storeIds, channelId, platform, paymentMethod, brandId
• Optional customer: tierId, gender, platforms, audienceIds, devicePlatforms
• Optional wallet: totals (points by reward id)

Supported locally: channel, order value, includes product, platform, store, payment method, brands, customer tier / points / gender / platform / audience / device OS.

Unknown types, or types that need customer / wallet when those are missing, fail (ok: false) and are listed in result.unsupported. They are not treated as pass.

Also available as standalones: validateConditions, validateRewardConditions, validateCampaignRules, readCustomError, createRulesManager.

Compatibility

• Node.js >= 18
• Zero runtime dependencies

Links

• Masivo Documentation
• Masivo Dashboard
• @masivo/core — client event tracking
• @masivo/rn — React Native CLIENT SDK

License

MIT