@minipim/sdk 0.3.1 → 0.4.1

package/README.md

@@ -153,6 +153,34 @@ const weight = asMeasurement(getAttribute(product.attributes, 'weight')); // { a
 
 Also available at the `@minipim/sdk/attributes` subpath.
 
+## Modifier helpers
+
+Modifiers are order-line options that don't create a SKU (engraving, add-ons, print/hardware choices). They live at `GET /v1/products/{id}/modifiers` and `GET /v1/modifiers/{id}` — product *detail* only flags their presence via `modifierCount` / `hasRequiredModifiers`, so a PDP with required options must fetch the list. Price deltas are in `config.priceAdjusters`, keyed by choice value slug; **money deltas are integer cents + ISO currency** (not dollars) and percentage deltas are integer basis points. These helpers resolve and price them:
+
+```ts
+import {
+  getModifierChoices, getModifierPriceAdjuster, applyPriceAdjuster, formatPriceAdjuster,
+  getAttribute, asMoney, formatMoney,
+} from '@minipim/sdk';
+
+const [mod] = await pim.GET('/v1/products/{id}/modifiers', { params: { path: { id } } }).then((r) => r.data);
+
+// choices joined with their structured delta
+for (const c of getModifierChoices(mod)) {
+  // c.priceAdjuster is null for free choices (and product_list modifiers, whose
+  // price lives on a referenced product — see DEVELOPERS.md)
+  const suffix = c.priceAdjuster ? ` (${formatPriceAdjuster(c.priceAdjuster)})` : '';
+  console.log(`${c.label}${suffix}`);   // "Pair of LED Lights (+$170.00)"
+}
+
+// price a selected choice against the base price
+const base = asMoney(getAttribute(product.attributes, 'price'));  // { amount_cents, currency }
+const chosen = getModifierPriceAdjuster(mod, 'pair_of_led_lights');
+if (base && chosen) formatMoney(applyPriceAdjuster(base, chosen)); // "$869.00"
+```
+
+`asPriceAdjuster` / `asModifierConfig` narrow the opaque `config`; they **reject the pre-2026-07 legacy shape** (bare `value` in dollars) so the SDK never misreads dollars as cents. Also available at the `@minipim/sdk/modifiers` subpath.
+
 ## Error handling
 
 `res.error` is a per-path union that's awkward to narrow. Use the shared guard:

package/dist/index.cjs

@@ -30,16 +30,23 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  applyPriceAdjuster: () => applyPriceAdjuster,
   asMeasurement: () => asMeasurement,
+  asModifierConfig: () => asModifierConfig,
   asMoney: () => asMoney,
+  asPriceAdjuster: () => asPriceAdjuster,
   collectAll: () => collectAll,
   createMinipimClient: () => createMinipimClient,
   flattenAttributes: () => flattenAttributes,
   formatMoney: () => formatMoney,
+  formatPriceAdjuster: () => formatPriceAdjuster,
   getAttribute: () => getAttribute,
   getErrorMessage: () => getErrorMessage,
+  getModifierChoices: () => getModifierChoices,
+  getModifierPriceAdjuster: () => getModifierPriceAdjuster,
   isMinipimError: () => isMinipimError,
-  paginate: () => paginate
+  paginate: () => paginate,
+  priceAdjusterCents: () => priceAdjusterCents
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -47,11 +54,15 @@ module.exports = __toCommonJS(src_exports);
 var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
 function createMinipimClient(opts) {
   const headers = {
-    "x-organization-id": opts.organizationId,
+    // Conditional rather than relying on openapi-fetch to drop the undefined.
+    // It does (mergeHeaders skips undefined values), so this is belt-and-braces
+    // for the type, not a behaviour change — but it keeps the intent local
+    // instead of depending on a transitive dependency's merge semantics.
+    ...opts.organizationId ? { "x-organization-id": opts.organizationId } : {},
     ...opts.headers ?? {}
   };
   if (opts.apiKey) headers["Authorization"] = `Bearer ${opts.apiKey}`;
-  if (opts.userId) headers["x-pim-user-id"] = opts.userId;
+  if (opts.userId) headers["x-user-id"] = opts.userId;
   return (0, import_openapi_fetch.default)({
     baseUrl: opts.baseUrl.replace(/\/$/, ""),
     fetch: opts.fetch,
@@ -148,16 +159,94 @@ function formatMoney(money, locale = "en-US") {
     currency: money.currency
   }).format(money.amount_cents / 100);
 }
+
+// src/modifiers.ts
+function asPriceAdjuster(value) {
+  if (!value || typeof value !== "object") return null;
+  const a = value;
+  if (a.adjuster === "fixed" && typeof a.amount_cents === "number" && typeof a.currency === "string") {
+    return { adjuster: "fixed", amount_cents: a.amount_cents, currency: a.currency };
+  }
+  if (a.adjuster === "percentage" && typeof a.basis_points === "number") {
+    return { adjuster: "percentage", basis_points: a.basis_points };
+  }
+  return null;
+}
+function asModifierConfig(config) {
+  if (!config || typeof config !== "object") return null;
+  const rawAdjusters = config.priceAdjusters;
+  if (!rawAdjusters || typeof rawAdjusters !== "object") return null;
+  const priceAdjusters = {};
+  for (const [key, raw] of Object.entries(rawAdjusters)) {
+    const pa = asPriceAdjuster(raw);
+    if (pa) priceAdjusters[key] = pa;
+  }
+  if (Object.keys(priceAdjusters).length === 0) return null;
+  const schemaVersion = config.schemaVersion;
+  return {
+    ...typeof schemaVersion === "number" ? { schemaVersion } : {},
+    priceAdjusters
+  };
+}
+function getModifierPriceAdjuster(modifier, choiceValue) {
+  return asModifierConfig(modifier.config)?.priceAdjusters[choiceValue] ?? null;
+}
+function getModifierChoices(modifier) {
+  const { validation } = modifier;
+  const options = validation && typeof validation === "object" ? validation.options : void 0;
+  if (!Array.isArray(options)) return [];
+  const adjusters = asModifierConfig(modifier.config)?.priceAdjusters ?? {};
+  const out = [];
+  for (const opt of options) {
+    if (!opt || typeof opt !== "object") continue;
+    const value = opt.value;
+    if (typeof value !== "string") continue;
+    const label = opt.label;
+    out.push({
+      value,
+      label: typeof label === "string" ? label : value,
+      priceAdjuster: adjusters[value] ?? null
+    });
+  }
+  return out;
+}
+function priceAdjusterCents(base, adjuster) {
+  return adjuster.adjuster === "fixed" ? adjuster.amount_cents : Math.round(base.amount_cents * adjuster.basis_points / 1e4);
+}
+function applyPriceAdjuster(base, adjuster) {
+  return {
+    amount_cents: base.amount_cents + priceAdjusterCents(base, adjuster),
+    currency: base.currency
+  };
+}
+function formatPriceAdjuster(adjuster, locale = "en-US") {
+  if (adjuster.adjuster === "fixed") {
+    const money = formatMoney(
+      { amount_cents: adjuster.amount_cents, currency: adjuster.currency },
+      locale
+    );
+    return adjuster.amount_cents > 0 ? `+${money}` : money;
+  }
+  const percent = adjuster.basis_points / 100;
+  return percent > 0 ? `+${percent}%` : `${percent}%`;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  applyPriceAdjuster,
   asMeasurement,
+  asModifierConfig,
   asMoney,
+  asPriceAdjuster,
   collectAll,
   createMinipimClient,
   flattenAttributes,
   formatMoney,
+  formatPriceAdjuster,
   getAttribute,
   getErrorMessage,
+  getModifierChoices,
+  getModifierPriceAdjuster,
   isMinipimError,
-  paginate
+  paginate,
+  priceAdjusterCents
 });

package/dist/index.d.cts

@@ -2,6 +2,7 @@ import { Client } from 'openapi-fetch';
 import { paths } from './openapi.cjs';
 export { components, operations } from './openapi.cjs';
 export { AttributeValueRecord, AttributesPayload, Measurement, Money, ResolveOptions, asMeasurement, asMoney, flattenAttributes, formatMoney, getAttribute } from './attributes.cjs';
+export { ModifierChoice, ModifierConfig, ModifierLike, PriceAdjuster, applyPriceAdjuster, asModifierConfig, asPriceAdjuster, formatPriceAdjuster, getModifierChoices, getModifierPriceAdjuster, priceAdjusterCents } from './modifiers.cjs';
 
 /**
  * Thin wrapper around `openapi-fetch` that pre-binds the tenancy header and
@@ -17,11 +18,16 @@ interface CreateMinipimClientOptions {
      */
     baseUrl: string;
     /**
-     * Tenant the client speaks for. Required — every authenticated endpoint
-     * needs `x-organization-id`. API keys identify the principal, not the
-     * tenant.
+     * Tenant the client speaks for, sent as `x-organization-id`.
+     *
+     * Optional when `apiKey` is set: an API key carries its own tenant, and the
+     * server resolves the org from the key row and ignores this header entirely
+     * (see the api-key auth provider — it returns the key's `organizationId`,
+     * and the auth plugin short-circuits before it ever reads the header).
+     *
+     * Required for session/`header`-mode auth, where the caller asserts the org.
      */
-    organizationId: string;
+    organizationId?: string;
     /**
      * Bearer API key (e.g. `pim_abc123…`). Issue one in the admin under
      * /api-keys. If you're running in dev with `PIM_AUTH=header`, omit this
@@ -29,8 +35,10 @@ interface CreateMinipimClientOptions {
      */
     apiKey?: string;
     /**
-     * Dev-only header (`x-pim-user-id`). Only set when the deployment is in
-     * `header` auth mode. Ignored in `jwt` / `clerk` deployments.
+     * Dev-only header (`x-user-id`). Only set when the deployment is in `header`
+     * auth mode, where it must be paired with `organizationId`. Ignored in
+     * `jwt` / `clerk` deployments. The instance falls back to its own
+     * `defaultUserSubject` when this is absent.
      */
     userId?: string;
     /**

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Client } from 'openapi-fetch';
 import { paths } from './openapi.js';
 export { components, operations } from './openapi.js';
 export { AttributeValueRecord, AttributesPayload, Measurement, Money, ResolveOptions, asMeasurement, asMoney, flattenAttributes, formatMoney, getAttribute } from './attributes.js';
+export { ModifierChoice, ModifierConfig, ModifierLike, PriceAdjuster, applyPriceAdjuster, asModifierConfig, asPriceAdjuster, formatPriceAdjuster, getModifierChoices, getModifierPriceAdjuster, priceAdjusterCents } from './modifiers.js';
 
 /**
  * Thin wrapper around `openapi-fetch` that pre-binds the tenancy header and
@@ -17,11 +18,16 @@ interface CreateMinipimClientOptions {
      */
     baseUrl: string;
     /**
-     * Tenant the client speaks for. Required — every authenticated endpoint
-     * needs `x-organization-id`. API keys identify the principal, not the
-     * tenant.
+     * Tenant the client speaks for, sent as `x-organization-id`.
+     *
+     * Optional when `apiKey` is set: an API key carries its own tenant, and the
+     * server resolves the org from the key row and ignores this header entirely
+     * (see the api-key auth provider — it returns the key's `organizationId`,
+     * and the auth plugin short-circuits before it ever reads the header).
+     *
+     * Required for session/`header`-mode auth, where the caller asserts the org.
      */
-    organizationId: string;
+    organizationId?: string;
     /**
      * Bearer API key (e.g. `pim_abc123…`). Issue one in the admin under
      * /api-keys. If you're running in dev with `PIM_AUTH=header`, omit this
@@ -29,8 +35,10 @@ interface CreateMinipimClientOptions {
      */
     apiKey?: string;
     /**
-     * Dev-only header (`x-pim-user-id`). Only set when the deployment is in
-     * `header` auth mode. Ignored in `jwt` / `clerk` deployments.
+     * Dev-only header (`x-user-id`). Only set when the deployment is in `header`
+     * auth mode, where it must be paired with `organizationId`. Ignored in
+     * `jwt` / `clerk` deployments. The instance falls back to its own
+     * `defaultUserSubject` when this is absent.
      */
     userId?: string;
     /**

package/dist/index.js

@@ -2,11 +2,15 @@
 import createClient from "openapi-fetch";
 function createMinipimClient(opts) {
   const headers = {
-    "x-organization-id": opts.organizationId,
+    // Conditional rather than relying on openapi-fetch to drop the undefined.
+    // It does (mergeHeaders skips undefined values), so this is belt-and-braces
+    // for the type, not a behaviour change — but it keeps the intent local
+    // instead of depending on a transitive dependency's merge semantics.
+    ...opts.organizationId ? { "x-organization-id": opts.organizationId } : {},
     ...opts.headers ?? {}
   };
   if (opts.apiKey) headers["Authorization"] = `Bearer ${opts.apiKey}`;
-  if (opts.userId) headers["x-pim-user-id"] = opts.userId;
+  if (opts.userId) headers["x-user-id"] = opts.userId;
   return createClient({
     baseUrl: opts.baseUrl.replace(/\/$/, ""),
     fetch: opts.fetch,
@@ -103,15 +107,93 @@ function formatMoney(money, locale = "en-US") {
     currency: money.currency
   }).format(money.amount_cents / 100);
 }
+
+// src/modifiers.ts
+function asPriceAdjuster(value) {
+  if (!value || typeof value !== "object") return null;
+  const a = value;
+  if (a.adjuster === "fixed" && typeof a.amount_cents === "number" && typeof a.currency === "string") {
+    return { adjuster: "fixed", amount_cents: a.amount_cents, currency: a.currency };
+  }
+  if (a.adjuster === "percentage" && typeof a.basis_points === "number") {
+    return { adjuster: "percentage", basis_points: a.basis_points };
+  }
+  return null;
+}
+function asModifierConfig(config) {
+  if (!config || typeof config !== "object") return null;
+  const rawAdjusters = config.priceAdjusters;
+  if (!rawAdjusters || typeof rawAdjusters !== "object") return null;
+  const priceAdjusters = {};
+  for (const [key, raw] of Object.entries(rawAdjusters)) {
+    const pa = asPriceAdjuster(raw);
+    if (pa) priceAdjusters[key] = pa;
+  }
+  if (Object.keys(priceAdjusters).length === 0) return null;
+  const schemaVersion = config.schemaVersion;
+  return {
+    ...typeof schemaVersion === "number" ? { schemaVersion } : {},
+    priceAdjusters
+  };
+}
+function getModifierPriceAdjuster(modifier, choiceValue) {
+  return asModifierConfig(modifier.config)?.priceAdjusters[choiceValue] ?? null;
+}
+function getModifierChoices(modifier) {
+  const { validation } = modifier;
+  const options = validation && typeof validation === "object" ? validation.options : void 0;
+  if (!Array.isArray(options)) return [];
+  const adjusters = asModifierConfig(modifier.config)?.priceAdjusters ?? {};
+  const out = [];
+  for (const opt of options) {
+    if (!opt || typeof opt !== "object") continue;
+    const value = opt.value;
+    if (typeof value !== "string") continue;
+    const label = opt.label;
+    out.push({
+      value,
+      label: typeof label === "string" ? label : value,
+      priceAdjuster: adjusters[value] ?? null
+    });
+  }
+  return out;
+}
+function priceAdjusterCents(base, adjuster) {
+  return adjuster.adjuster === "fixed" ? adjuster.amount_cents : Math.round(base.amount_cents * adjuster.basis_points / 1e4);
+}
+function applyPriceAdjuster(base, adjuster) {
+  return {
+    amount_cents: base.amount_cents + priceAdjusterCents(base, adjuster),
+    currency: base.currency
+  };
+}
+function formatPriceAdjuster(adjuster, locale = "en-US") {
+  if (adjuster.adjuster === "fixed") {
+    const money = formatMoney(
+      { amount_cents: adjuster.amount_cents, currency: adjuster.currency },
+      locale
+    );
+    return adjuster.amount_cents > 0 ? `+${money}` : money;
+  }
+  const percent = adjuster.basis_points / 100;
+  return percent > 0 ? `+${percent}%` : `${percent}%`;
+}
 export {
+  applyPriceAdjuster,
   asMeasurement,
+  asModifierConfig,
   asMoney,
+  asPriceAdjuster,
   collectAll,
   createMinipimClient,
   flattenAttributes,
   formatMoney,
+  formatPriceAdjuster,
   getAttribute,
   getErrorMessage,
+  getModifierChoices,
+  getModifierPriceAdjuster,
   isMinipimError,
-  paginate
+  paginate,
+  priceAdjusterCents
 };

package/dist/modifiers.cjs

@@ -0,0 +1,120 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/modifiers.ts
+var modifiers_exports = {};
+__export(modifiers_exports, {
+  applyPriceAdjuster: () => applyPriceAdjuster,
+  asModifierConfig: () => asModifierConfig,
+  asPriceAdjuster: () => asPriceAdjuster,
+  formatPriceAdjuster: () => formatPriceAdjuster,
+  getModifierChoices: () => getModifierChoices,
+  getModifierPriceAdjuster: () => getModifierPriceAdjuster,
+  priceAdjusterCents: () => priceAdjusterCents
+});
+module.exports = __toCommonJS(modifiers_exports);
+
+// src/attributes.ts
+function formatMoney(money, locale = "en-US") {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: money.currency
+  }).format(money.amount_cents / 100);
+}
+
+// src/modifiers.ts
+function asPriceAdjuster(value) {
+  if (!value || typeof value !== "object") return null;
+  const a = value;
+  if (a.adjuster === "fixed" && typeof a.amount_cents === "number" && typeof a.currency === "string") {
+    return { adjuster: "fixed", amount_cents: a.amount_cents, currency: a.currency };
+  }
+  if (a.adjuster === "percentage" && typeof a.basis_points === "number") {
+    return { adjuster: "percentage", basis_points: a.basis_points };
+  }
+  return null;
+}
+function asModifierConfig(config) {
+  if (!config || typeof config !== "object") return null;
+  const rawAdjusters = config.priceAdjusters;
+  if (!rawAdjusters || typeof rawAdjusters !== "object") return null;
+  const priceAdjusters = {};
+  for (const [key, raw] of Object.entries(rawAdjusters)) {
+    const pa = asPriceAdjuster(raw);
+    if (pa) priceAdjusters[key] = pa;
+  }
+  if (Object.keys(priceAdjusters).length === 0) return null;
+  const schemaVersion = config.schemaVersion;
+  return {
+    ...typeof schemaVersion === "number" ? { schemaVersion } : {},
+    priceAdjusters
+  };
+}
+function getModifierPriceAdjuster(modifier, choiceValue) {
+  return asModifierConfig(modifier.config)?.priceAdjusters[choiceValue] ?? null;
+}
+function getModifierChoices(modifier) {
+  const { validation } = modifier;
+  const options = validation && typeof validation === "object" ? validation.options : void 0;
+  if (!Array.isArray(options)) return [];
+  const adjusters = asModifierConfig(modifier.config)?.priceAdjusters ?? {};
+  const out = [];
+  for (const opt of options) {
+    if (!opt || typeof opt !== "object") continue;
+    const value = opt.value;
+    if (typeof value !== "string") continue;
+    const label = opt.label;
+    out.push({
+      value,
+      label: typeof label === "string" ? label : value,
+      priceAdjuster: adjusters[value] ?? null
+    });
+  }
+  return out;
+}
+function priceAdjusterCents(base, adjuster) {
+  return adjuster.adjuster === "fixed" ? adjuster.amount_cents : Math.round(base.amount_cents * adjuster.basis_points / 1e4);
+}
+function applyPriceAdjuster(base, adjuster) {
+  return {
+    amount_cents: base.amount_cents + priceAdjusterCents(base, adjuster),
+    currency: base.currency
+  };
+}
+function formatPriceAdjuster(adjuster, locale = "en-US") {
+  if (adjuster.adjuster === "fixed") {
+    const money = formatMoney(
+      { amount_cents: adjuster.amount_cents, currency: adjuster.currency },
+      locale
+    );
+    return adjuster.amount_cents > 0 ? `+${money}` : money;
+  }
+  const percent = adjuster.basis_points / 100;
+  return percent > 0 ? `+${percent}%` : `${percent}%`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyPriceAdjuster,
+  asModifierConfig,
+  asPriceAdjuster,
+  formatPriceAdjuster,
+  getModifierChoices,
+  getModifierPriceAdjuster,
+  priceAdjusterCents
+});

package/dist/modifiers.d.cts

@@ -0,0 +1,88 @@
+import { Money } from './attributes.cjs';
+
+/**
+ * Modifier helpers. Modifiers are order-line options that do NOT produce a new
+ * SKU — engraving, gift wrap, print/hardware choices, add-ons. Their price
+ * deltas live in `config.priceAdjusters`, keyed by choice value slug: money
+ * deltas are integer cents + ISO currency (the same Money convention as
+ * everywhere else), percentage deltas are integer basis points.
+ *
+ * The API exposes modifiers at `GET /v1/products/{id}/modifiers` and
+ * `GET /v1/modifiers/{id}`. Product *detail* only flags their presence
+ * (`modifierCount`, `hasRequiredModifiers`) — fetch the list to price a PDP.
+ *
+ * The generated OpenAPI types model `config`/`validation` as opaque JSON, so
+ * these helpers define the structured shapes and narrow into them — the same
+ * pattern as `asMoney` in ./attributes. Legacy pre-cents adjusters (a bare
+ * `value` in dollars, no `schemaVersion`) are intentionally ignored by
+ * `asPriceAdjuster`, so the SDK never misreads dollars as cents.
+ */
+
+/** A structured modifier price delta for one choice. */
+type PriceAdjuster = {
+    adjuster: 'fixed';
+    amount_cents: number;
+    currency: string;
+} | {
+    adjuster: 'percentage';
+    basis_points: number;
+};
+/** The `config` object on a modifier definition (schemaVersion 2+). */
+interface ModifierConfig {
+    schemaVersion?: number;
+    priceAdjusters: Record<string, PriceAdjuster>;
+}
+/** A modifier choice, joined with its structured price delta (if any). */
+interface ModifierChoice {
+    /** Choice value slug — matches `config.priceAdjusters` keys. */
+    value: string;
+    /** Human label (option labels are stored un-localized). */
+    label: string;
+    /** Structured delta, or null for free choices / product_list modifiers. */
+    priceAdjuster: PriceAdjuster | null;
+}
+/**
+ * Minimal structural shape of a modifier payload — just the fields these
+ * helpers read. Accepts a full modifier from the API directly (its extra
+ * fields are ignored).
+ */
+interface ModifierLike {
+    validation?: unknown;
+    config?: unknown;
+}
+/** Narrow a raw value to a PriceAdjuster, or null if it isn't one. */
+declare function asPriceAdjuster(value: unknown): PriceAdjuster | null;
+/**
+ * Narrow a raw modifier `config` to a typed ModifierConfig, or null when it
+ * carries no structured price (free modifiers, or product_list modifiers whose
+ * price lives on a referenced product). `priceAdjusters` only contains entries
+ * that parse — legacy/unknown shapes are dropped.
+ */
+declare function asModifierConfig(config: unknown): ModifierConfig | null;
+/** The structured price adjuster for a given choice value, or null. */
+declare function getModifierPriceAdjuster(modifier: ModifierLike, choiceValue: string): PriceAdjuster | null;
+/**
+ * Resolve a modifier's choices, each joined with its structured price delta.
+ * Returns `[]` for modifiers with no choice list (free-text, number, file).
+ */
+declare function getModifierChoices(modifier: ModifierLike): ModifierChoice[];
+/**
+ * The signed cent delta a price adjuster applies to a base price. `fixed`
+ * ignores the base (returns its `amount_cents`); `percentage` is `basis_points`
+ * of `base.amount_cents`, rounded to the nearest cent.
+ */
+declare function priceAdjusterCents(base: Money, adjuster: PriceAdjuster): number;
+/**
+ * Apply a price adjuster to a base Money, returning the adjusted total in the
+ * base currency. A `fixed` adjuster's currency is assumed to match the base
+ * (modifiers are same-currency in practice); only its cent delta is used.
+ */
+declare function applyPriceAdjuster(base: Money, adjuster: PriceAdjuster): Money;
+/**
+ * Human-readable, always-signed delta string: `+$170.00`, `-$2.70`, `+10%`.
+ * `fixed` uses `formatMoney` (locale-correct negatives); `percentage` renders
+ * basis points as a percent.
+ */
+declare function formatPriceAdjuster(adjuster: PriceAdjuster, locale?: string): string;
+
+export { type ModifierChoice, type ModifierConfig, type ModifierLike, type PriceAdjuster, applyPriceAdjuster, asModifierConfig, asPriceAdjuster, formatPriceAdjuster, getModifierChoices, getModifierPriceAdjuster, priceAdjusterCents };

package/dist/modifiers.d.ts

@@ -0,0 +1,88 @@
+import { Money } from './attributes.js';
+
+/**
+ * Modifier helpers. Modifiers are order-line options that do NOT produce a new
+ * SKU — engraving, gift wrap, print/hardware choices, add-ons. Their price
+ * deltas live in `config.priceAdjusters`, keyed by choice value slug: money
+ * deltas are integer cents + ISO currency (the same Money convention as
+ * everywhere else), percentage deltas are integer basis points.
+ *
+ * The API exposes modifiers at `GET /v1/products/{id}/modifiers` and
+ * `GET /v1/modifiers/{id}`. Product *detail* only flags their presence
+ * (`modifierCount`, `hasRequiredModifiers`) — fetch the list to price a PDP.
+ *
+ * The generated OpenAPI types model `config`/`validation` as opaque JSON, so
+ * these helpers define the structured shapes and narrow into them — the same
+ * pattern as `asMoney` in ./attributes. Legacy pre-cents adjusters (a bare
+ * `value` in dollars, no `schemaVersion`) are intentionally ignored by
+ * `asPriceAdjuster`, so the SDK never misreads dollars as cents.
+ */
+
+/** A structured modifier price delta for one choice. */
+type PriceAdjuster = {
+    adjuster: 'fixed';
+    amount_cents: number;
+    currency: string;
+} | {
+    adjuster: 'percentage';
+    basis_points: number;
+};
+/** The `config` object on a modifier definition (schemaVersion 2+). */
+interface ModifierConfig {
+    schemaVersion?: number;
+    priceAdjusters: Record<string, PriceAdjuster>;
+}
+/** A modifier choice, joined with its structured price delta (if any). */
+interface ModifierChoice {
+    /** Choice value slug — matches `config.priceAdjusters` keys. */
+    value: string;
+    /** Human label (option labels are stored un-localized). */
+    label: string;
+    /** Structured delta, or null for free choices / product_list modifiers. */
+    priceAdjuster: PriceAdjuster | null;
+}
+/**
+ * Minimal structural shape of a modifier payload — just the fields these
+ * helpers read. Accepts a full modifier from the API directly (its extra
+ * fields are ignored).
+ */
+interface ModifierLike {
+    validation?: unknown;
+    config?: unknown;
+}
+/** Narrow a raw value to a PriceAdjuster, or null if it isn't one. */
+declare function asPriceAdjuster(value: unknown): PriceAdjuster | null;
+/**
+ * Narrow a raw modifier `config` to a typed ModifierConfig, or null when it
+ * carries no structured price (free modifiers, or product_list modifiers whose
+ * price lives on a referenced product). `priceAdjusters` only contains entries
+ * that parse — legacy/unknown shapes are dropped.
+ */
+declare function asModifierConfig(config: unknown): ModifierConfig | null;
+/** The structured price adjuster for a given choice value, or null. */
+declare function getModifierPriceAdjuster(modifier: ModifierLike, choiceValue: string): PriceAdjuster | null;
+/**
+ * Resolve a modifier's choices, each joined with its structured price delta.
+ * Returns `[]` for modifiers with no choice list (free-text, number, file).
+ */
+declare function getModifierChoices(modifier: ModifierLike): ModifierChoice[];
+/**
+ * The signed cent delta a price adjuster applies to a base price. `fixed`
+ * ignores the base (returns its `amount_cents`); `percentage` is `basis_points`
+ * of `base.amount_cents`, rounded to the nearest cent.
+ */
+declare function priceAdjusterCents(base: Money, adjuster: PriceAdjuster): number;
+/**
+ * Apply a price adjuster to a base Money, returning the adjusted total in the
+ * base currency. A `fixed` adjuster's currency is assumed to match the base
+ * (modifiers are same-currency in practice); only its cent delta is used.
+ */
+declare function applyPriceAdjuster(base: Money, adjuster: PriceAdjuster): Money;
+/**
+ * Human-readable, always-signed delta string: `+$170.00`, `-$2.70`, `+10%`.
+ * `fixed` uses `formatMoney` (locale-correct negatives); `percentage` renders
+ * basis points as a percent.
+ */
+declare function formatPriceAdjuster(adjuster: PriceAdjuster, locale?: string): string;
+
+export { type ModifierChoice, type ModifierConfig, type ModifierLike, type PriceAdjuster, applyPriceAdjuster, asModifierConfig, asPriceAdjuster, formatPriceAdjuster, getModifierChoices, getModifierPriceAdjuster, priceAdjusterCents };