@minipim/sdk 0.3.0 → 0.4.0

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);
 
@@ -148,16 +155,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

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

package/dist/index.js

@@ -103,15 +103,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 };

package/dist/modifiers.js

@@ -0,0 +1,87 @@
+// 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}%`;
+}
+export {
+  applyPriceAdjuster,
+  asModifierConfig,
+  asPriceAdjuster,
+  formatPriceAdjuster,
+  getModifierChoices,
+  getModifierPriceAdjuster,
+  priceAdjusterCents
+};

package/dist/openapi.d.cts

@@ -29,6 +29,7 @@ interface paths {
                         "application/json": {
                             status: string;
                             service: string;
+                            version: string;
                         };
                     };
                 };
@@ -80,6 +81,57 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/changelog": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Release changelog
+         * @description Structured release notes, newest first. The `version` of the first entry is the deployed version (also reported by /healthz).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            version: string;
+                            entries: {
+                                version: string;
+                                date: string;
+                                title: string;
+                                highlights: {
+                                    /** @enum {string} */
+                                    type: "feature" | "fix" | "perf" | "docs";
+                                    text: string;
+                                }[];
+                            }[];
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/organizations": {
         parameters: {
             query?: never;
@@ -1174,6 +1226,7 @@ interface paths {
                     familyId?: string;
                     categoryId?: string;
                     brand?: string;
+                    tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
                     sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
@@ -1215,6 +1268,7 @@ interface paths {
                                 attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                     [key: string]: unknown;
                                 };
+                                tags: string[];
                                 /** Format: uuid */
                                 createdBy: string | null;
                                 /** Format: uuid */
@@ -1263,6 +1317,8 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
+                        /** @default [] */
+                        tags?: string[];
                     };
                 };
             };
@@ -1291,6 +1347,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
                             /** Format: uuid */
@@ -1340,6 +1397,7 @@ interface paths {
                     familyId?: string;
                     categoryId?: string;
                     brand?: string;
+                    tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
                     sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
@@ -1383,6 +1441,10 @@ interface paths {
                                 value: string;
                                 count: number;
                             }[];
+                            tags: {
+                                value: string;
+                                count: number;
+                            }[];
                             connectors: {
                                 /** Format: uuid */
                                 connectorId: string;
@@ -1403,6 +1465,48 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/products/tags": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List all product tags in use, with counts
+         * @description Every distinct tag currently on at least one product, ordered by usage. Tags are free-form, normalized to lowercase slugs on write (`Featured` → `featured`). Filter products by tag with `GET /v1/products?tag=<tag>` (repeatable; multiple tags AND together).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            value: string;
+                            count: number;
+                        }[];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/products/{id}": {
         parameters: {
             query?: never;
@@ -1499,6 +1603,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
                             /** Format: uuid */
@@ -1619,6 +1724,7 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
+                        tags?: string[];
                     };
                 };
             };
@@ -1647,6 +1753,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
                             /** Format: uuid */
@@ -2092,6 +2199,61 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/products/bulk-set-tags": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Bulk-modify tags across products
+         * @description `mode=add` unions the listed tags into each product, `mode=remove` strips them, `mode=replace` overwrites the full list. Tags are normalized (slugified + deduped) exactly like single-product writes.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        productIds: string[];
+                        /** @enum {string} */
+                        mode: "add" | "remove" | "replace";
+                        tags: string[];
+                    };
+                };
+            };
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            results: {
+                                /** Format: uuid */
+                                productId: string;
+                                ok: boolean;
+                                error?: string;
+                            }[];
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/products/{id}/variants": {
         parameters: {
             query?: never;

package/dist/openapi.d.ts

@@ -29,6 +29,7 @@ interface paths {
                         "application/json": {
                             status: string;
                             service: string;
+                            version: string;
                         };
                     };
                 };
@@ -80,6 +81,57 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/changelog": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Release changelog
+         * @description Structured release notes, newest first. The `version` of the first entry is the deployed version (also reported by /healthz).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            version: string;
+                            entries: {
+                                version: string;
+                                date: string;
+                                title: string;
+                                highlights: {
+                                    /** @enum {string} */
+                                    type: "feature" | "fix" | "perf" | "docs";
+                                    text: string;
+                                }[];
+                            }[];
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/organizations": {
         parameters: {
             query?: never;
@@ -1174,6 +1226,7 @@ interface paths {
                     familyId?: string;
                     categoryId?: string;
                     brand?: string;
+                    tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
                     sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
@@ -1215,6 +1268,7 @@ interface paths {
                                 attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                     [key: string]: unknown;
                                 };
+                                tags: string[];
                                 /** Format: uuid */
                                 createdBy: string | null;
                                 /** Format: uuid */
@@ -1263,6 +1317,8 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
+                        /** @default [] */
+                        tags?: string[];
                     };
                 };
             };
@@ -1291,6 +1347,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
                             /** Format: uuid */
@@ -1340,6 +1397,7 @@ interface paths {
                     familyId?: string;
                     categoryId?: string;
                     brand?: string;
+                    tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
                     sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
@@ -1383,6 +1441,10 @@ interface paths {
                                 value: string;
                                 count: number;
                             }[];
+                            tags: {
+                                value: string;
+                                count: number;
+                            }[];
                             connectors: {
                                 /** Format: uuid */
                                 connectorId: string;
@@ -1403,6 +1465,48 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/products/tags": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List all product tags in use, with counts
+         * @description Every distinct tag currently on at least one product, ordered by usage. Tags are free-form, normalized to lowercase slugs on write (`Featured` → `featured`). Filter products by tag with `GET /v1/products?tag=<tag>` (repeatable; multiple tags AND together).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            value: string;
+                            count: number;
+                        }[];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/products/{id}": {
         parameters: {
             query?: never;
@@ -1499,6 +1603,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
                             /** Format: uuid */
@@ -1619,6 +1724,7 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
+                        tags?: string[];
                     };
                 };
             };
@@ -1647,6 +1753,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
                             /** Format: uuid */
@@ -2092,6 +2199,61 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/products/bulk-set-tags": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Bulk-modify tags across products
+         * @description `mode=add` unions the listed tags into each product, `mode=remove` strips them, `mode=replace` overwrites the full list. Tags are normalized (slugified + deduped) exactly like single-product writes.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        productIds: string[];
+                        /** @enum {string} */
+                        mode: "add" | "remove" | "replace";
+                        tags: string[];
+                    };
+                };
+            };
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            results: {
+                                /** Format: uuid */
+                                productId: string;
+                                ok: boolean;
+                                error?: string;
+                            }[];
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/products/{id}/variants": {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minipim/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Typed TypeScript client for the MiniPim API.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Epic-Design-Labs/minipim",
@@ -54,6 +54,16 @@
         "default": "./dist/attributes.cjs"
       }
     },
+    "./modifiers": {
+      "import": {
+        "types": "./dist/modifiers.d.ts",
+        "default": "./dist/modifiers.js"
+      },
+      "require": {
+        "types": "./dist/modifiers.d.cts",
+        "default": "./dist/modifiers.cjs"
+      }
+    },
     "./openapi": {
       "import": {
         "types": "./dist/openapi.d.ts",
@@ -84,7 +94,8 @@
   "devDependencies": {
     "openapi-typescript": "^7.5.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
   },
   "publishConfig": {
     "access": "public"
@@ -93,6 +104,7 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "gen": "openapi-typescript https://api.minipim.com/docs/json -o src/openapi.ts"
   }
 }