Xendit Sandbox onto catalog_product

A per-org converter migrates 300 Xendit fee products onto a composite-price model and threads them through the publish seam — without changing behavior for any other org.

1. Why this exists

Xendit Sandbox runs on Dealops 2 today: 305 V2 productSpecs and 1342 datapoints describing payment fee structures. Each product carries up to six fee components — list and cost variants of a processing fee, a rate, and a flat fee. The goal is to move this catalog onto the Dealops 3 catalog_product data model so that the V3 admin / catalog UI can manage it, without disturbing the live V2 publish path for any other org.

This PR is the output of the roundtrip-catalog-migration skill (also added on this branch). It is the code-only stage: converter + migration + verifier + the publish-seam wiring. No drafts are written and no catalog is published. Both of those are deliberately separate, explicit, later steps.

2. The data model

One SKU per Xendit productId. Up to six fee components are split between price.composite_price (sell side) and flat scalar keys in customAttributes (cost side). The cost split exists because the catalog price column is sell-only and the attribute map allows only scalar values.

The pricebookId and metric tags are not stored per component. They were verified constant across each product's datapoints (zero mismatch in the source data), so they live once on the spec and get re-injected on rebuild. The COGS currency is reconstructed from the product's listPriceCurrencies[0]; a guard in the planner fails the migration loudly if any product's COGS currency disagrees with its list currency — no silent USD fallback.

2.1 The fee taxonomy at a glance

3. The publish seam — a default-preserving dispatch

The publish path used to hardcode one converter. Two call sites in trpc/router/v3Admin/ are now routed through getOrgCatalogConverter(orgSlug), which returns the existing shared behavior for every org except those explicitly registered.

// _helpers.ts
const v2SpecData =
  convertDealopsCatalogToV2PricingSpec(v3Spec);

// publishDrafts.ts
const derived = deriveV3Datasheet(...);
await syncDataSheetToV2AsNewVersion(
  organizationId, derived, userId, msg
);

// _helpers.ts
const v2SpecData =
  getOrgCatalogConverter(orgSlug).pricingSpecToV2(v3Spec);

// publishDrafts.ts
const v2Datapoints =
  getOrgCatalogConverter(orgSlug).catalogToV2Datapoints({
    orgId: organizationId,
    liveSpecs: await loadLiveProductSpecs(organizationId),
    baseDatasheet: baseDatasheet as V3DataSheet,
  });
await syncV2DatapointsAsNewVersion(
  organizationId, v2Datapoints, userId, msg
);

The registry

// migration/_utils/registry.ts
const DEFAULT_CONVERTER: OrgCatalogConverter = {
  pricingSpecToV2: convertDealopsCatalogToV2PricingSpec,
  catalogToV2Datapoints: ({ orgId, liveSpecs, baseDatasheet }) =>
    convertToV2DataSheet(deriveV3Datasheet(orgId, liveSpecs, baseDatasheet)),
};

const REGISTRY: Record<string, OrgCatalogConverter> = {
  'xendit-sandbox': {
    pricingSpecToV2: xenditCatalogToV2PricingSpec,
    catalogToV2Datapoints: xenditCatalogToV2Datapoints,
  },
};

export function getOrgCatalogConverter(orgSlug: string | null | undefined) {
  return (orgSlug && REGISTRY[orgSlug]) || DEFAULT_CONVERTER;
}

A new helper, syncV2DatapointsAsNewVersion, was extracted so a per-org converter can produce V2 datapoints directly instead of going through the V3 datasheet model. This is the seam Xendit needs because its fee types can't pass through the shared deriveV3Datasheet.

4. The Xendit converter

The forward path (V2 → catalog rows) is in planXenditCatalogRows; the reverse path (catalog → V2) splits into xenditCatalogToV2PricingSpec (shared, no-collapse) and xenditCatalogToV2Datapoints (rebuilds the six fee datapoints from price + customAttributes).

Three safety guards

All three guards have hard-guard unit-test coverage in xenditCatalogConverter.test.ts — pure, in-memory, no DB. Sample assertions:

// #1
assert.throws(
  () => assertWritablePlan(planWith(2), /* allowExclusions */ false),
  /Refusing to --write an incomplete catalog: 2 product/,
);

// #2 — unknown type is EXCLUDED, never silently dropped
const plan = planXenditCatalogRows({ v2Spec: specWith('USD'),
  v2Datapoints: [sellDp('USD'), dp('WEIRD_FEE', cur(1, 'USD'), {...})] });
assert.strictEqual(plan.rows.length, 0);
assert.ok(plan.excluded[0].reasons.some(r => r.startsWith('unsupported-type:')));

// #3 — IDR list product with USD COGS fails planning
assert.throws(
  () => planXenditCatalogRows({ v2Spec: specWith('IDR'),
    v2Datapoints: [sellDp('IDR'), cogsDp('USD')] }),
  /COGS currency mismatch/,
);

5. The five excluded products

Five Xendit products have malformed source data — datapoints missing pricebookId or their metric tag, or sitting on pageId: 'cogs'. The migration excludes them by design and surfaces them for data cleanup, instead of pretending they round-tripped.

6. Shared additive extensions

A literal 1-1 round trip required four fields that the V2↔V3 pricingSpec converter was silently dropping. They are now carried verbatim, guarded so an org that never set them does not gain a default.

The composite-component value type also gains a percent member, so LIST_RATE components (and only those — the cost-side rate stays a flat scalar) can be persisted in price.composite_price:

// catalogProduct/price/types.ts
export const componentValueSchema = z.union([
  numberCurrencySchema,
  numberPercentSchema,        // ← new
  tieredCurrencyValueSchema,
]);

7. Client: edit drawer round-trips COGS and tolerates model-less products

The catalog edit drawer needed two adjustments so a Xendit SKU survives a save without corrupting the migrated row.

On the V2 sync side, the V3→V2 converter also drops pricingModel when it isn't a valid V2 PricingModel, using PricingModelSchema.safeParse as the gate:

// pricingSpec/v2Converter.ts
...(PricingModelSchema.safeParse(attrs.pricingModel).success && {
  pricingModel: attrs.pricingModel as CalculationSpec['pricingModel'],
}),

8. Operational guardrails on the publish transaction

publishDrafts.ts already wraps the org-level flip in a single interactive transaction. With ~300 SKUs, one create/update per SKU over Neon latency was running past Prisma's 5s default. The fix raises the ceiling rather than batching:

await prisma.$transaction(
  async (tx) => { /* lock org, flip drafts to live, etc. */ },
  // big first publish (~hundreds of SKUs) can exceed Prisma's 5s default
  { timeout: 120_000, maxWait: 20_000 },
);

Smaller catalogs finish well under the ceiling and are unaffected. The comment explicitly flags createMany batching as a follow-up.

9. The verifier

verify.ts is the proof. It is read-only and DB-free: it consumes a directory containing the org's V2 pricingSpec.json and datasheet.json and runs:

1. planXenditCatalogRows → catalog rows (excluding the 5 buggy products).
2. rowToValidatedProductSpec on every row — the same schema gate loadLiveProductSpecs applies at publish.
3. getOrgCatalogConverter('xendit-sandbox') for both reverse calls — the actual dispatched seam, not a parallel copy.
4. Canonical-JSON diff over the clean products' specs, and by-selectorTags diff over the clean datapoints.

Diffs are classified explicitly. An "attributes mirror only" product diff counts as acceptable (the engine-neutral mirror that convertToV2ProductSpec adds to every product). A regenerated datapoint id counts as cosmetic (the engine matches on selectorTags, never the id). Anything else is must-resolve.

10. What this PR doesn't change

11. Risks and open questions