@shoppexio/storefront-react 0.0.0 → 0.1.1

package/eject/account/account-reseller.ts

@@ -0,0 +1,685 @@
+/**
+ * Pure wire narrowing and basket quote helpers for the wholesale account tab.
+ *
+ * The shapes below follow the mapper functions in
+ * `apps/backend-elysia/src/routes/v1/customer-reseller.ts` exactly. They do not
+ * model what the UI wishes the API returned. A missing producer field fails the
+ * complete read, so Clean Minimal never renders a partly guessed money or order state.
+ */
+
+export type ResellerEnrollmentMode = "MANUAL" | "APPLICATION" | "OPEN";
+export type ResellerStatus =
+  | "INVITED"
+  | "APPLIED"
+  | "ACTIVE"
+  | "SUSPENDED"
+  | "REJECTED";
+export type ResellerAppliedOverride = "variant" | "product" | "tier";
+
+export interface ResellerTier {
+  id: string;
+  name: string | null;
+  discount_percent: number | null;
+}
+
+export interface ResellerRelationship {
+  id: string;
+  status: ResellerStatus;
+  tier: ResellerTier | null;
+  application_note: string | null;
+  lifetime_revenue: string;
+  lifetime_orders: number;
+  approved_at: string | null;
+  created_at: string;
+}
+
+export interface ResellerProgramState {
+  program_enabled: boolean;
+  enrollment_mode: ResellerEnrollmentMode;
+  application_message: string | null;
+  require_application_note: boolean;
+  reseller: ResellerRelationship | null;
+}
+
+export interface ResellerCatalogVariant {
+  variant_id: string;
+  title: string;
+  stock: number;
+  supplier_backed: boolean;
+  orderable: boolean;
+  base_price: string;
+  unit_price: string;
+  discount_percent: number;
+  applied_override: ResellerAppliedOverride;
+}
+
+export interface ResellerCatalogItem {
+  product_id: string;
+  uniqid: string;
+  title: string;
+  type: string;
+  stock: number;
+  supplier_backed: boolean;
+  orderable: boolean;
+  volume_discount_enabled: boolean;
+  base_price: string;
+  unit_price: string;
+  discount_percent: number;
+  applied_override: ResellerAppliedOverride;
+  variants: ResellerCatalogVariant[];
+}
+
+export interface ResellerCatalog {
+  currency: string;
+  total: number;
+  page: number;
+  per_page: number;
+  items: ResellerCatalogItem[];
+}
+
+export interface ResellerCatalogPayload {
+  tier: { id: string; name: string; discount_percent: number };
+  catalog: ResellerCatalog;
+}
+
+export interface ResellerOrderItemInput {
+  product_id: string;
+  variant_id?: string;
+  quantity: number;
+}
+
+/** Producer limits from `ResellerOrderItemSchema`. Quantities are units, not fractions. */
+export const RESELLER_QUANTITY_MIN_UNITS = 1;
+export const RESELLER_QUANTITY_MAX_UNITS = 100_000;
+
+export function isValidResellerQuantity(value: number): boolean {
+  return Number.isInteger(value)
+    && value >= RESELLER_QUANTITY_MIN_UNITS
+    && value <= RESELLER_QUANTITY_MAX_UNITS;
+}
+
+export interface ResellerQuoteItem {
+  product_id: string;
+  product_title: string;
+  product_type: string;
+  variant_id: string | null;
+  variant_title: string | null;
+  quantity: number;
+  base_price: string;
+  discount_percent: number;
+  unit_price: string;
+  line_total: string;
+  applied_override: ResellerAppliedOverride;
+  volume_discount_applied: string;
+}
+
+export interface ResellerQuote {
+  currency: string;
+  tier: { id: string; name: string; discount_percent: number };
+  items: ResellerQuoteItem[];
+  subtotal: string;
+  volume_discount_total: string;
+  total: string;
+  savings: string;
+}
+
+export interface ResellerOrderListItem {
+  uniqid: string;
+  status: string;
+  currency: string;
+  total: string;
+  item_count: number;
+  created_at: string;
+}
+
+export interface ResellerOrderList {
+  total: number;
+  page: number;
+  per_page: number;
+  items: ResellerOrderListItem[];
+}
+
+export interface ResellerOrderLine {
+  product_id: string | null;
+  product_title: string;
+  variant_id: string | null;
+  variant_title: string | null;
+  quantity: number;
+  unit_price: string;
+  total: string;
+  delivered: boolean;
+  delivered_at: string | null;
+  serials: string[];
+}
+
+export interface ResellerOrderDetail {
+  uniqid: string;
+  status: string;
+  currency: string;
+  total: string;
+  item_count: number;
+  created_at: string;
+  tier_name: string;
+  tier_discount_percent: number;
+  partially_delivered: boolean;
+  refunded_amount: string | null;
+  lines: ResellerOrderLine[];
+}
+
+export interface ResellerWallet {
+  currency: string;
+  balance: string;
+  hold_balance: string;
+  available: string;
+  is_active: boolean;
+}
+
+export interface ResellerApiKey {
+  id: string;
+  name: string;
+  key_last4: string;
+  last_used_at: string | null;
+  revoked_at: string | null;
+  created_at: string;
+}
+
+export type NarrowResult<T> = { ok: true; data: T } | { ok: false };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isEnrollmentMode(value: unknown): value is ResellerEnrollmentMode {
+  return value === "MANUAL" || value === "APPLICATION" || value === "OPEN";
+}
+
+function isResellerStatus(value: unknown): value is ResellerStatus {
+  return (
+    value === "INVITED" ||
+    value === "APPLIED" ||
+    value === "ACTIVE" ||
+    value === "SUSPENDED" ||
+    value === "REJECTED"
+  );
+}
+
+function isAppliedOverride(value: unknown): value is ResellerAppliedOverride {
+  return value === "variant" || value === "product" || value === "tier";
+}
+
+function narrowTier(
+  value: unknown,
+  nullableFields = false,
+): ResellerTier | null | undefined {
+  if (value === null) return null;
+  if (!isRecord(value) || typeof value.id !== "string") return undefined;
+  if (nullableFields) {
+    if (
+      !isNullableString(value.name) ||
+      !(
+        value.discount_percent === null ||
+        isFiniteNumber(value.discount_percent)
+      )
+    ) {
+      return undefined;
+    }
+    return {
+      id: value.id,
+      name: value.name,
+      discount_percent: value.discount_percent,
+    };
+  }
+  if (typeof value.name !== "string" || !isFiniteNumber(value.discount_percent))
+    return undefined;
+  return {
+    id: value.id,
+    name: value.name,
+    discount_percent: value.discount_percent,
+  };
+}
+
+function narrowRelationship(
+  value: unknown,
+): ResellerRelationship | null | undefined {
+  if (value === null) return null;
+  if (!isRecord(value)) return undefined;
+  const tier = narrowTier(value.tier, true);
+  if (
+    typeof value.id !== "string" ||
+    !isResellerStatus(value.status) ||
+    tier === undefined ||
+    !isNullableString(value.application_note) ||
+    typeof value.lifetime_revenue !== "string" ||
+    !isFiniteNumber(value.lifetime_orders) ||
+    !isNullableString(value.approved_at) ||
+    typeof value.created_at !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    id: value.id,
+    status: value.status,
+    tier,
+    application_note: value.application_note,
+    lifetime_revenue: value.lifetime_revenue,
+    lifetime_orders: value.lifetime_orders,
+    approved_at: value.approved_at,
+    created_at: value.created_at,
+  };
+}
+
+/** `GET /reseller`, written against the route's program response + mapReseller. */
+export function narrowResellerProgram(
+  payload: unknown,
+): NarrowResult<ResellerProgramState> {
+  if (!isRecord(payload)) return { ok: false };
+  const reseller = narrowRelationship(payload.reseller);
+  if (
+    typeof payload.program_enabled !== "boolean" ||
+    !isEnrollmentMode(payload.enrollment_mode) ||
+    !isNullableString(payload.application_message) ||
+    typeof payload.require_application_note !== "boolean" ||
+    reseller === undefined
+  ) {
+    return { ok: false };
+  }
+  return {
+    ok: true,
+    data: {
+      program_enabled: payload.program_enabled,
+      enrollment_mode: payload.enrollment_mode,
+      application_message: payload.application_message,
+      require_application_note: payload.require_application_note,
+      reseller,
+    },
+  };
+}
+
+/** Enrollment mutations answer `{ reseller: mapReseller(...) }`. */
+export function narrowResellerMutation(
+  payload: unknown,
+): NarrowResult<ResellerRelationship> {
+  if (!isRecord(payload)) return { ok: false };
+  const reseller = narrowRelationship(payload.reseller);
+  return reseller ? { ok: true, data: reseller } : { ok: false };
+}
+
+function narrowCatalogVariant(value: unknown): ResellerCatalogVariant | null {
+  if (!isRecord(value)) return null;
+  if (
+    typeof value.variant_id !== "string" ||
+    typeof value.title !== "string" ||
+    !isFiniteNumber(value.stock) ||
+    typeof value.supplier_backed !== "boolean" ||
+    typeof value.orderable !== "boolean" ||
+    typeof value.base_price !== "string" ||
+    typeof value.unit_price !== "string" ||
+    !isFiniteNumber(value.discount_percent) ||
+    !isAppliedOverride(value.applied_override)
+  )
+    return null;
+  return value as unknown as ResellerCatalogVariant;
+}
+
+function narrowCatalogItem(value: unknown): ResellerCatalogItem | null {
+  if (!isRecord(value) || !Array.isArray(value.variants)) return null;
+  const variants: ResellerCatalogVariant[] = [];
+  for (const raw of value.variants) {
+    const variant = narrowCatalogVariant(raw);
+    if (!variant) return null;
+    variants.push(variant);
+  }
+  if (
+    typeof value.product_id !== "string" ||
+    typeof value.uniqid !== "string" ||
+    typeof value.title !== "string" ||
+    typeof value.type !== "string" ||
+    !isFiniteNumber(value.stock) ||
+    typeof value.supplier_backed !== "boolean" ||
+    typeof value.orderable !== "boolean" ||
+    typeof value.volume_discount_enabled !== "boolean" ||
+    typeof value.base_price !== "string" ||
+    typeof value.unit_price !== "string" ||
+    !isFiniteNumber(value.discount_percent) ||
+    !isAppliedOverride(value.applied_override)
+  )
+    return null;
+  return {
+    product_id: value.product_id,
+    uniqid: value.uniqid,
+    title: value.title,
+    type: value.type,
+    stock: value.stock,
+    supplier_backed: value.supplier_backed,
+    orderable: value.orderable,
+    volume_discount_enabled: value.volume_discount_enabled,
+    base_price: value.base_price,
+    unit_price: value.unit_price,
+    discount_percent: value.discount_percent,
+    applied_override: value.applied_override,
+    variants,
+  };
+}
+
+/** `GET /reseller/catalog`, written against mapCatalog and its tier wrapper. */
+export function narrowResellerCatalog(
+  payload: unknown,
+): NarrowResult<ResellerCatalogPayload> {
+  if (!isRecord(payload) || !isRecord(payload.catalog)) return { ok: false };
+  const tier = narrowTier(payload.tier);
+  const raw = payload.catalog;
+  if (
+    !tier ||
+    typeof tier.name !== "string" ||
+    typeof tier.discount_percent !== "number" ||
+    typeof raw.currency !== "string" ||
+    !isFiniteNumber(raw.total) ||
+    !isFiniteNumber(raw.page) ||
+    !isFiniteNumber(raw.per_page) ||
+    !Array.isArray(raw.items)
+  )
+    return { ok: false };
+  const items: ResellerCatalogItem[] = [];
+  for (const entry of raw.items) {
+    const item = narrowCatalogItem(entry);
+    if (!item) return { ok: false };
+    items.push(item);
+  }
+  return {
+    ok: true,
+    data: {
+      tier: {
+        id: tier.id,
+        name: tier.name,
+        discount_percent: tier.discount_percent,
+      },
+      catalog: {
+        currency: raw.currency,
+        total: raw.total,
+        page: raw.page,
+        per_page: raw.per_page,
+        items,
+      },
+    },
+  };
+}
+
+function narrowQuoteItem(value: unknown): ResellerQuoteItem | null {
+  if (!isRecord(value)) return null;
+  if (
+    typeof value.product_id !== "string" ||
+    typeof value.product_title !== "string" ||
+    typeof value.product_type !== "string" ||
+    !isNullableString(value.variant_id) ||
+    !isNullableString(value.variant_title) ||
+    !isValidResellerQuantity(value.quantity as number) ||
+    typeof value.base_price !== "string" ||
+    !isFiniteNumber(value.discount_percent) ||
+    typeof value.unit_price !== "string" ||
+    typeof value.line_total !== "string" ||
+    !isAppliedOverride(value.applied_override) ||
+    typeof value.volume_discount_applied !== "string"
+  )
+    return null;
+  return value as unknown as ResellerQuoteItem;
+}
+
+/** `POST /reseller/orders/quote`, written against mapQuote. */
+export function narrowResellerQuote(
+  payload: unknown,
+): NarrowResult<ResellerQuote> {
+  if (!isRecord(payload) || !isRecord(payload.quote)) return { ok: false };
+  const raw = payload.quote;
+  const tier = narrowTier(raw.tier);
+  if (
+    !tier ||
+    typeof tier.name !== "string" ||
+    typeof tier.discount_percent !== "number" ||
+    typeof raw.currency !== "string" ||
+    !Array.isArray(raw.items) ||
+    typeof raw.subtotal !== "string" ||
+    typeof raw.volume_discount_total !== "string" ||
+    typeof raw.total !== "string" ||
+    typeof raw.savings !== "string"
+  )
+    return { ok: false };
+  const items: ResellerQuoteItem[] = [];
+  for (const entry of raw.items) {
+    const item = narrowQuoteItem(entry);
+    if (!item) return { ok: false };
+    items.push(item);
+  }
+  return {
+    ok: true,
+    data: {
+      currency: raw.currency,
+      tier: {
+        id: tier.id,
+        name: tier.name,
+        discount_percent: tier.discount_percent,
+      },
+      items,
+      subtotal: raw.subtotal,
+      volume_discount_total: raw.volume_discount_total,
+      total: raw.total,
+      savings: raw.savings,
+    },
+  };
+}
+
+function narrowOrderListItem(value: unknown): ResellerOrderListItem | null {
+  if (!isRecord(value)) return null;
+  if (
+    typeof value.uniqid !== "string" ||
+    typeof value.status !== "string" ||
+    typeof value.currency !== "string" ||
+    typeof value.total !== "string" ||
+    !isFiniteNumber(value.item_count) ||
+    typeof value.created_at !== "string"
+  )
+    return null;
+  return value as unknown as ResellerOrderListItem;
+}
+
+/** `GET /reseller/orders`, written against mapOrderList. */
+export function narrowResellerOrders(
+  payload: unknown,
+): NarrowResult<ResellerOrderList> {
+  if (!isRecord(payload) || !isRecord(payload.orders)) return { ok: false };
+  const raw = payload.orders;
+  if (
+    !isFiniteNumber(raw.total) ||
+    !isFiniteNumber(raw.page) ||
+    !isFiniteNumber(raw.per_page) ||
+    !Array.isArray(raw.items)
+  )
+    return { ok: false };
+  const items: ResellerOrderListItem[] = [];
+  for (const entry of raw.items) {
+    const item = narrowOrderListItem(entry);
+    if (!item) return { ok: false };
+    items.push(item);
+  }
+  return {
+    ok: true,
+    data: { total: raw.total, page: raw.page, per_page: raw.per_page, items },
+  };
+}
+
+function narrowOrderLine(value: unknown): ResellerOrderLine | null {
+  if (
+    !isRecord(value) ||
+    !Array.isArray(value.serials) ||
+    !value.serials.every((serial) => typeof serial === "string")
+  ) {
+    return null;
+  }
+  if (
+    !isNullableString(value.product_id) ||
+    typeof value.product_title !== "string" ||
+    !isNullableString(value.variant_id) ||
+    !isNullableString(value.variant_title) ||
+    !isValidResellerQuantity(value.quantity as number) ||
+    typeof value.unit_price !== "string" ||
+    typeof value.total !== "string" ||
+    typeof value.delivered !== "boolean" ||
+    !isNullableString(value.delivered_at)
+  )
+    return null;
+  return value as unknown as ResellerOrderLine;
+}
+
+/** `GET /reseller/orders/:uniqid`, written against mapOrderDetail. */
+export function narrowResellerOrderDetail(
+  payload: unknown,
+): NarrowResult<ResellerOrderDetail> {
+  if (!isRecord(payload) || !isRecord(payload.order)) return { ok: false };
+  const raw = payload.order;
+  if (
+    typeof raw.uniqid !== "string" ||
+    typeof raw.status !== "string" ||
+    typeof raw.currency !== "string" ||
+    typeof raw.total !== "string" ||
+    !isFiniteNumber(raw.item_count) ||
+    typeof raw.created_at !== "string" ||
+    typeof raw.tier_name !== "string" ||
+    !isFiniteNumber(raw.tier_discount_percent) ||
+    typeof raw.partially_delivered !== "boolean" ||
+    !isNullableString(raw.refunded_amount) ||
+    !Array.isArray(raw.lines)
+  )
+    return { ok: false };
+  const lines: ResellerOrderLine[] = [];
+  for (const entry of raw.lines) {
+    const line = narrowOrderLine(entry);
+    if (!line) return { ok: false };
+    lines.push(line);
+  }
+  return {
+    ok: true,
+    data: {
+      uniqid: raw.uniqid,
+      status: raw.status,
+      currency: raw.currency,
+      total: raw.total,
+      item_count: raw.item_count,
+      created_at: raw.created_at,
+      tier_name: raw.tier_name,
+      tier_discount_percent: raw.tier_discount_percent,
+      partially_delivered: raw.partially_delivered,
+      refunded_amount: raw.refunded_amount,
+      lines,
+    },
+  };
+}
+
+/** `GET /reseller/wallet`, narrowed against its route-local wallet mapper. */
+export function narrowResellerWallet(
+  payload: unknown,
+): NarrowResult<ResellerWallet> {
+  if (!isRecord(payload) || !isRecord(payload.wallet)) return { ok: false };
+  const raw = payload.wallet;
+  if (
+    typeof raw.currency !== "string" ||
+    typeof raw.balance !== "string" ||
+    typeof raw.hold_balance !== "string" ||
+    typeof raw.available !== "string" ||
+    typeof raw.is_active !== "boolean"
+  )
+    return { ok: false };
+  return { ok: true, data: raw as unknown as ResellerWallet };
+}
+
+function narrowApiKey(value: unknown): ResellerApiKey | null {
+  if (!isRecord(value)) return null;
+  if (
+    typeof value.id !== "string" ||
+    typeof value.name !== "string" ||
+    typeof value.key_last4 !== "string" ||
+    !isNullableString(value.last_used_at) ||
+    !isNullableString(value.revoked_at) ||
+    typeof value.created_at !== "string"
+  )
+    return null;
+  return value as unknown as ResellerApiKey;
+}
+
+/** `GET /reseller/api-keys`, written against mapApiKey. */
+export function narrowResellerApiKeys(
+  payload: unknown,
+): NarrowResult<ResellerApiKey[]> {
+  if (!isRecord(payload) || !Array.isArray(payload.api_keys))
+    return { ok: false };
+  const keys: ResellerApiKey[] = [];
+  for (const entry of payload.api_keys) {
+    const key = narrowApiKey(entry);
+    if (!key) return { ok: false };
+    keys.push(key);
+  }
+  return { ok: true, data: keys };
+}
+
+/** Stable identity of one basket version. Order is normalized for comparison. */
+export function resellerBasketKey(
+  items: readonly ResellerOrderItemInput[],
+): string {
+  for (const item of items) {
+    if (!isValidResellerQuantity(item.quantity)) {
+      throw new RangeError(
+        `Wholesale quantity must be a whole number from ${RESELLER_QUANTITY_MIN_UNITS} to ${RESELLER_QUANTITY_MAX_UNITS} units; received ${String(item.quantity)}.`,
+      );
+    }
+  }
+
+  return JSON.stringify(
+    [...items]
+      .map((item) => ({
+        product_id: item.product_id,
+        variant_id: item.variant_id ?? null,
+        quantity: item.quantity,
+      }))
+      .sort((left, right) => {
+        const product = left.product_id.localeCompare(right.product_id);
+        return (
+          product ||
+          (left.variant_id ?? "").localeCompare(right.variant_id ?? "")
+        );
+      }),
+  );
+}
+
+/**
+ * The one way into the program this buyer actually has.
+ *
+ * Normally the shop's enrolment mode decides. An invitation overrides it:
+ * `ResellerEnrollmentService.invite` requires an enabled program, not a MANUAL
+ * one, so a shop taking open sign-ups can still have invited someone. Offering
+ * that buyer the join button offers the one call the producer answers 409 to
+ * ("already part of the reseller program"), while the token in their mail has
+ * nowhere to go.
+ */
+export function resellerEntryMode(
+  program: ResellerProgramState,
+): ResellerEnrollmentMode {
+  return program.reseller?.status === "INVITED"
+    ? "MANUAL"
+    : program.enrollment_mode;
+}
+
+/** A quote is displayed only for the basket it priced. */
+export function quoteMatchesBasket(
+  quotedBasketKey: string | null,
+  items: readonly ResellerOrderItemInput[],
+): boolean {
+  return (
+    quotedBasketKey !== null && quotedBasketKey === resellerBasketKey(items)
+  );
+}