@withpotter/lib 0.13.0-next.101

package/dist/product-types.d.ts

@@ -0,0 +1,311 @@
+/**
+ * Product Types — Platform-level type definitions for product CRUD.
+ *
+ * These types represent the fields that the API always accepts,
+ * independent of any template. Template-specific fields are stored
+ * in the generic `data` record.
+ */
+export declare enum ProductType {
+    PHYSICAL = "physical",
+    DIGITAL = "digital",
+    SERVICE = "service",
+    TICKET = "ticket",
+    PACKAGE = "package"
+}
+export declare const PRODUCT_TYPE_OPTIONS: readonly [{
+    readonly value: ProductType.PHYSICAL;
+    readonly label: "Physical product";
+}, {
+    readonly value: ProductType.DIGITAL;
+    readonly label: "Digital product";
+}, {
+    readonly value: ProductType.SERVICE;
+    readonly label: "Service";
+}, {
+    readonly value: ProductType.TICKET;
+    readonly label: "Ticket";
+}, {
+    readonly value: ProductType.PACKAGE;
+    readonly label: "Package";
+}];
+export interface ProductMedia {
+    url: string;
+    type?: 'image' | 'video';
+    alt?: string;
+    width?: number;
+    height?: number;
+    thumbnail?: string;
+    duration?: number;
+}
+/** @deprecated Use ProductMedia */
+export type ProductImage = ProductMedia;
+export interface ProductVariant {
+    id: string;
+    name: string;
+    sku?: string;
+    price?: number;
+    costPrice?: number | null;
+    quantity?: number;
+    image?: ProductMedia;
+    data?: Record<string, unknown>;
+}
+/** Base config — every behavior at minimum has an enabled flag */
+export interface BehaviorConfig {
+    enabled: boolean;
+}
+/** Nothing beyond `enabled` yet (return policy, restocking fee are future). */
+export type SellableConfig = BehaviorConfig;
+/**
+ * Where a booking actually happens.
+ *
+ * A service could say how long it takes, who does it and what it costs, and
+ * had nowhere to say where the customer should turn up. The only meeting link
+ * the engine knew about hung off the *ticketed* behaviour, so a consultation
+ * could only have a place by accident — connect a calendar and Google mints a
+ * Meet room. In person, a phone call, or "here is my own Zoom" were unsayable,
+ * and the confirmation went out with no answer to the one question the
+ * customer has.
+ *
+ * `google-meet` is the only kind that has no `value`: the room is minted per
+ * booking when the calendar is connected, which is also why it is the only one
+ * that can go wrong later — see the note on the field in the panel.
+ */
+export type BookingLocationKind = 'google-meet' | 'link' | 'in-person' | 'phone' | 'custom';
+export interface BookingLocation {
+    kind: BookingLocationKind;
+    /**
+     * The link, address or number the kind asks for. Empty on `google-meet`
+     * and on `custom`, which carry nothing and `instructions` respectively.
+     */
+    value?: string;
+    /** Anything else the customer needs — the buzzer, the parking, the door. */
+    instructions?: string;
+}
+export interface BookableConfig extends BehaviorConfig {
+    bookingMode?: 'duration' | 'date-range' | 'group';
+    durationMinutes?: number;
+    bufferBefore?: number;
+    bufferAfter?: number;
+    advanceBookingDays?: number;
+    maxCapacity?: number;
+    requiresDeposit?: boolean;
+    depositPercent?: number;
+    cancellationHours?: number;
+    assignmentStrategy?: 'auto-first' | 'auto-best' | 'customer-chooses' | 'round-robin' | 'pool' | 'sole-provider';
+    durationType?: 'fixed' | 'hourly' | 'nightly' | 'weekly' | 'monthly';
+    checkInTime?: string;
+    checkOutTime?: string;
+    minDuration?: number;
+    maxDuration?: number;
+    pricingUnit?: 'flat' | 'hourly';
+    location?: BookingLocation;
+}
+export interface ShippableConfig extends BehaviorConfig {
+    weight?: number;
+    dimensions?: {
+        l: number;
+        w: number;
+        h: number;
+    };
+    requiresAddress?: boolean;
+}
+export interface SubscribableConfig extends BehaviorConfig {
+    interval?: 'weekly' | 'biweekly' | 'monthly' | 'yearly';
+    trialDays?: number;
+    linkedPlanId?: string;
+    accessTags?: string[];
+}
+export interface DownloadableConfig extends BehaviorConfig {
+    fileUrl?: string;
+    fileSize?: number;
+    maxDownloads?: number;
+}
+/**
+ * Something let out to someone else for a while: a short-let, a vacation
+ * rental, a hall, a studio, a pitch. `pricingModel` decides the unit it is
+ * let by, and every length rule below is counted in that same unit.
+ */
+export interface RentableConfig extends BehaviorConfig {
+    pricingModel?: 'per-night' | 'per-hour' | 'flat-rate';
+    surchargeWeekend?: number;
+    securityDeposit?: number;
+    cleaningFee?: number;
+    maxGuests?: number;
+    /** Shortest booking accepted, in nights or hours per `pricingModel`. */
+    minUnits?: number;
+    /** Longest booking accepted, in the same unit. */
+    maxUnits?: number;
+    /** How many interchangeable copies of this listing exist — eight identical
+     *  studios sold as one product rather than eight. One by default. */
+    availableUnits?: number;
+    /** The listing this one is part of, by id. A house let both whole and by
+     *  the room shares one calendar, so letting either takes the other. */
+    partOf?: string;
+    /** Dates the owner has closed, as `YYYY-MM-DD`. Not sold, not booked: shut,
+     *  and refused on the storefront in words of its own. */
+    blockedDates?: string[];
+}
+/**
+ * A product that mints a gift card when it is paid for.
+ *
+ * Denominations are ordinary variants: the line's selling price becomes the
+ * card's face value, so a merchant offering ₦5,000 / ₦10,000 / ₦25,000 sets
+ * those up the way they set up any other variant. A parallel list of amounts
+ * here would be a second way to say the same thing, and the two would drift.
+ */
+export interface GiftCardConfig extends BehaviorConfig {
+    /** Days the issued card stays valid. Omit for a card that never expires. */
+    expiresAfterDays?: number;
+}
+/**
+ * One thing a customer can add to this item on the way to paying for it: the
+ * extra laces with the shoe, the airport pickup with the stay, the candles on
+ * the cake.
+ *
+ * Not a variant. A variant is a fork — you buy the S *or* the M, and the price
+ * replaces the item's. An add-on is a sum — you buy the shoe *and* the laces,
+ * and its price is added on top. That is why they cannot be the same control:
+ * three sizes are three prices to choose between, three add-ons are eight
+ * possible baskets.
+ */
+export interface AddOnItem {
+    id: string;
+    name: string;
+    description?: string;
+    /** Added to the line total, on top of the item (or the chosen variant). */
+    price: number;
+    /** Always included and not removable — a service charge, a deposit. */
+    required?: boolean;
+}
+export interface AddableConfig extends BehaviorConfig {
+    addOns: AddOnItem[];
+}
+export interface TicketedConfig extends BehaviorConfig {
+    eventDate?: string;
+    eventStartTime?: string;
+    eventEndTime?: string;
+    venueCapacity?: number;
+    seating?: 'assigned' | 'general-admission';
+    maxPerCustomer?: number;
+    salesDeadline?: string;
+    venueName?: string;
+    venueAddress?: string;
+    venueCity?: string;
+    venueState?: string;
+    venueCountry?: string;
+    venueCoordinates?: {
+        lat: number;
+        lng: number;
+    };
+    onlineEventUrl?: string;
+    tiers?: Array<{
+        id?: string;
+        name: string;
+        price: number;
+        quantity: number;
+        soldCount?: number;
+    }>;
+    recurrence?: EventRecurrenceRule;
+}
+/** Recurrence rule for generating event series occurrences */
+export interface EventRecurrenceRule {
+    frequency: 'daily' | 'weekly' | 'biweekly' | 'monthly';
+    interval?: number;
+    daysOfWeek?: number[];
+    endDate?: string;
+    occurrences?: number;
+}
+/**
+ * Backward-compatible: each behavior can be a simple boolean OR a config object.
+ * Old `{ sellable: true }` still works. New `{ bookable: { enabled: true, durationMinutes: 60 } }` also works.
+ */
+export interface ProductBehaviors {
+    sellable?: boolean | SellableConfig;
+    bookable?: boolean | BookableConfig;
+    subscribable?: boolean | SubscribableConfig;
+    /** Legacy tag-based content gate. Customer must have active sub granting ALL listed tags. */
+    gatedBy?: string[];
+    /** Plan-id content gate. Customer must have active sub to ANY of these plan IDs (OR'd with gatedBy). */
+    gatedByPlanIds?: string[];
+    reservable?: boolean;
+    downloadable?: boolean | DownloadableConfig;
+    shippable?: boolean | ShippableConfig;
+    rentable?: boolean | RentableConfig;
+    ticketed?: boolean | TicketedConfig;
+    giftcard?: boolean | GiftCardConfig;
+    /**
+     * Extras sold alongside this item. The engine has honoured these since the
+     * cart was written — `resolve-item-price` verifies every selected add-on
+     * against this list and prices it from here, never from the storefront — but
+     * nothing in the dashboard could put one here, so the list was always empty.
+     */
+    addable?: boolean | AddableConfig;
+}
+/**
+ * Check if a behavior is enabled regardless of boolean or config format.
+ *
+ * Takes `unknown` on purpose. Behaviours are read out of JSONB and reach these
+ * helpers as `unknown` far more often than as a typed union, so a narrow
+ * parameter did not make callers safer — it made forty of them write
+ * `isBehaviorEnabled(x as any)`, which asserts a shape nobody checked. The
+ * runtime narrowing below is the real guarantee, so let it be the only one.
+ */
+export declare function isBehaviorEnabled(value: unknown): boolean;
+/**
+ * Extract the config object from a behavior value. See isBehaviorEnabled for
+ * why this accepts `unknown`.
+ */
+export declare function getBehaviorConfig<T extends BehaviorConfig>(value: unknown): T | null;
+/**
+ * Platform fields — always accepted by POST /products.
+ * Template-specific fields go in `data`.
+ */
+export interface CreateProductPayload {
+    type: ProductType;
+    title: string;
+    slug: string;
+    description?: string;
+    shortDescription?: string;
+    category?: string;
+    tags?: string[];
+    featured?: boolean;
+    isActive?: boolean;
+    sortOrder?: number;
+    image?: ProductMedia;
+    gallery?: ProductMedia[];
+    price?: number;
+    compareAtPrice?: number;
+    costPrice?: number | null;
+    currency?: string;
+    trackInventory?: boolean;
+    quantity?: number;
+    lowStockThreshold?: number;
+    behaviors?: ProductBehaviors;
+    hasVariants?: boolean;
+    variants?: ProductVariant[];
+    /** Template-specific fields live here */
+    data?: Record<string, unknown>;
+    /** Semantic intent key — which business activity this item serves */
+    intent?: string;
+    /** Team member IDs (tenant_members.id) assigned as owners of this product. */
+    assigneeIds?: string[];
+}
+export type UpdateProductPayload = Partial<Omit<CreateProductPayload, 'type'>>;
+/**
+ * Full product as returned by GET /products/:id.
+ * Extends the create payload with server-generated fields.
+ */
+export interface Product extends CreateProductPayload {
+    id: string;
+    tenantId: string;
+    seriesId?: string | null;
+    reserved?: number;
+    available?: number;
+    status?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Generate a URL-safe slug from a title string.
+ */
+export declare function generateSlug(title: string): string;

package/dist/product-types.js

@@ -0,0 +1,38 @@
+var ProductType = /* @__PURE__ */ ((ProductType2) => {
+  ProductType2["PHYSICAL"] = "physical";
+  ProductType2["DIGITAL"] = "digital";
+  ProductType2["SERVICE"] = "service";
+  ProductType2["TICKET"] = "ticket";
+  ProductType2["PACKAGE"] = "package";
+  return ProductType2;
+})(ProductType || {});
+const PRODUCT_TYPE_OPTIONS = [
+  { value: "physical" /* PHYSICAL */, label: "Physical product" },
+  { value: "digital" /* DIGITAL */, label: "Digital product" },
+  { value: "service" /* SERVICE */, label: "Service" },
+  { value: "ticket" /* TICKET */, label: "Ticket" },
+  { value: "package" /* PACKAGE */, label: "Package" }
+];
+function isBehaviorEnabled(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "object" && value !== null && "enabled" in value) {
+    return Boolean(value.enabled);
+  }
+  return false;
+}
+function getBehaviorConfig(value) {
+  if (typeof value === "object" && value !== null) return value;
+  if (value === true) return { enabled: true };
+  return null;
+}
+function generateSlug(title) {
+  return title.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+export {
+  PRODUCT_TYPE_OPTIONS,
+  ProductType,
+  generateSlug,
+  getBehaviorConfig,
+  isBehaviorEnabled
+};
+//# sourceMappingURL=product-types.js.map

package/dist/product-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/product-types.ts"],"sourcesContent":["/**\n * Product Types — Platform-level type definitions for product CRUD.\n *\n * These types represent the fields that the API always accepts,\n * independent of any template. Template-specific fields are stored\n * in the generic `data` record.\n */\n\n// ============================================\n// ENUMS\n// ============================================\n\nexport enum ProductType {\n  PHYSICAL = 'physical',\n  DIGITAL = 'digital',\n  SERVICE = 'service',\n  TICKET = 'ticket',\n  PACKAGE = 'package',\n}\n\nexport const PRODUCT_TYPE_OPTIONS = [\n  { value: ProductType.PHYSICAL, label: 'Physical product' },\n  { value: ProductType.DIGITAL, label: 'Digital product' },\n  { value: ProductType.SERVICE, label: 'Service' },\n  { value: ProductType.TICKET, label: 'Ticket' },\n  { value: ProductType.PACKAGE, label: 'Package' },\n] as const;\n\n// ============================================\n// INTERFACES\n// ============================================\n\nexport interface ProductMedia {\n  url: string;\n  type?: 'image' | 'video';\n  alt?: string;\n  width?: number;\n  height?: number;\n  thumbnail?: string;\n  duration?: number;\n}\n\n/** @deprecated Use ProductMedia */\nexport type ProductImage = ProductMedia;\n\nexport interface ProductVariant {\n  id: string;\n  name: string;\n  sku?: string;\n  price?: number;\n  costPrice?: number | null;\n  quantity?: number;\n  image?: ProductMedia;\n  data?: Record<string, unknown>;\n}\n\n// ============================================\n// BEHAVIOR CONFIG TYPES\n// ============================================\n\n/** Base config — every behavior at minimum has an enabled flag */\nexport interface BehaviorConfig {\n  enabled: boolean;\n}\n\n/** Nothing beyond `enabled` yet (return policy, restocking fee are future). */\nexport type SellableConfig = BehaviorConfig;\n\n/**\n * Where a booking actually happens.\n *\n * A service could say how long it takes, who does it and what it costs, and\n * had nowhere to say where the customer should turn up. The only meeting link\n * the engine knew about hung off the *ticketed* behaviour, so a consultation\n * could only have a place by accident — connect a calendar and Google mints a\n * Meet room. In person, a phone call, or \"here is my own Zoom\" were unsayable,\n * and the confirmation went out with no answer to the one question the\n * customer has.\n *\n * `google-meet` is the only kind that has no `value`: the room is minted per\n * booking when the calendar is connected, which is also why it is the only one\n * that can go wrong later — see the note on the field in the panel.\n */\nexport type BookingLocationKind =\n  'google-meet' | 'link' | 'in-person' | 'phone' | 'custom';\n\nexport interface BookingLocation {\n  kind: BookingLocationKind;\n  /**\n   * The link, address or number the kind asks for. Empty on `google-meet`\n   * and on `custom`, which carry nothing and `instructions` respectively.\n   */\n  value?: string;\n  /** Anything else the customer needs — the buzzer, the parking, the door. */\n  instructions?: string;\n}\n\nexport interface BookableConfig extends BehaviorConfig {\n  bookingMode?: 'duration' | 'date-range' | 'group';\n  durationMinutes?: number;\n  bufferBefore?: number;\n  bufferAfter?: number;\n  advanceBookingDays?: number;\n  maxCapacity?: number;\n  requiresDeposit?: boolean;\n  depositPercent?: number;\n  cancellationHours?: number;\n  assignmentStrategy?:\n    | 'auto-first'\n    | 'auto-best'\n    | 'customer-chooses'\n    | 'round-robin'\n    | 'pool'\n    | 'sole-provider';\n  durationType?: 'fixed' | 'hourly' | 'nightly' | 'weekly' | 'monthly';\n  checkInTime?: string;\n  checkOutTime?: string;\n  minDuration?: number;\n  maxDuration?: number;\n  pricingUnit?: 'flat' | 'hourly';\n  location?: BookingLocation;\n}\n\nexport interface ShippableConfig extends BehaviorConfig {\n  weight?: number;\n  dimensions?: { l: number; w: number; h: number };\n  requiresAddress?: boolean;\n}\n\nexport interface SubscribableConfig extends BehaviorConfig {\n  interval?: 'weekly' | 'biweekly' | 'monthly' | 'yearly';\n  trialDays?: number;\n  linkedPlanId?: string;\n  accessTags?: string[];\n}\n\nexport interface DownloadableConfig extends BehaviorConfig {\n  fileUrl?: string;\n  fileSize?: number;\n  maxDownloads?: number;\n}\n\n/**\n * Something let out to someone else for a while: a short-let, a vacation\n * rental, a hall, a studio, a pitch. `pricingModel` decides the unit it is\n * let by, and every length rule below is counted in that same unit.\n */\nexport interface RentableConfig extends BehaviorConfig {\n  pricingModel?: 'per-night' | 'per-hour' | 'flat-rate';\n  surchargeWeekend?: number;\n  securityDeposit?: number;\n  cleaningFee?: number;\n  maxGuests?: number;\n  /** Shortest booking accepted, in nights or hours per `pricingModel`. */\n  minUnits?: number;\n  /** Longest booking accepted, in the same unit. */\n  maxUnits?: number;\n  /** How many interchangeable copies of this listing exist — eight identical\n   *  studios sold as one product rather than eight. One by default. */\n  availableUnits?: number;\n  /** The listing this one is part of, by id. A house let both whole and by\n   *  the room shares one calendar, so letting either takes the other. */\n  partOf?: string;\n  /** Dates the owner has closed, as `YYYY-MM-DD`. Not sold, not booked: shut,\n   *  and refused on the storefront in words of its own. */\n  blockedDates?: string[];\n}\n\n/**\n * A product that mints a gift card when it is paid for.\n *\n * Denominations are ordinary variants: the line's selling price becomes the\n * card's face value, so a merchant offering ₦5,000 / ₦10,000 / ₦25,000 sets\n * those up the way they set up any other variant. A parallel list of amounts\n * here would be a second way to say the same thing, and the two would drift.\n */\nexport interface GiftCardConfig extends BehaviorConfig {\n  /** Days the issued card stays valid. Omit for a card that never expires. */\n  expiresAfterDays?: number;\n}\n\n/**\n * One thing a customer can add to this item on the way to paying for it: the\n * extra laces with the shoe, the airport pickup with the stay, the candles on\n * the cake.\n *\n * Not a variant. A variant is a fork — you buy the S *or* the M, and the price\n * replaces the item's. An add-on is a sum — you buy the shoe *and* the laces,\n * and its price is added on top. That is why they cannot be the same control:\n * three sizes are three prices to choose between, three add-ons are eight\n * possible baskets.\n */\nexport interface AddOnItem {\n  id: string;\n  name: string;\n  description?: string;\n  /** Added to the line total, on top of the item (or the chosen variant). */\n  price: number;\n  /** Always included and not removable — a service charge, a deposit. */\n  required?: boolean;\n}\n\nexport interface AddableConfig extends BehaviorConfig {\n  addOns: AddOnItem[];\n}\n\nexport interface TicketedConfig extends BehaviorConfig {\n  eventDate?: string;\n  eventStartTime?: string;\n  eventEndTime?: string;\n  venueCapacity?: number;\n  seating?: 'assigned' | 'general-admission';\n  maxPerCustomer?: number;\n  salesDeadline?: string;\n  venueName?: string;\n  venueAddress?: string;\n  venueCity?: string;\n  venueState?: string;\n  venueCountry?: string;\n  venueCoordinates?: { lat: number; lng: number };\n  onlineEventUrl?: string;\n  tiers?: Array<{\n    id?: string;\n    name: string;\n    price: number;\n    quantity: number;\n    soldCount?: number;\n  }>;\n  recurrence?: EventRecurrenceRule;\n}\n\n/** Recurrence rule for generating event series occurrences */\nexport interface EventRecurrenceRule {\n  frequency: 'daily' | 'weekly' | 'biweekly' | 'monthly';\n  interval?: number;\n  daysOfWeek?: number[];\n  endDate?: string;\n  occurrences?: number;\n}\n\n/**\n * Backward-compatible: each behavior can be a simple boolean OR a config object.\n * Old `{ sellable: true }` still works. New `{ bookable: { enabled: true, durationMinutes: 60 } }` also works.\n */\nexport interface ProductBehaviors {\n  sellable?: boolean | SellableConfig;\n  bookable?: boolean | BookableConfig;\n  subscribable?: boolean | SubscribableConfig;\n  /** Legacy tag-based content gate. Customer must have active sub granting ALL listed tags. */\n  gatedBy?: string[];\n  /** Plan-id content gate. Customer must have active sub to ANY of these plan IDs (OR'd with gatedBy). */\n  gatedByPlanIds?: string[];\n  reservable?: boolean; // deprecated, use bookable\n  downloadable?: boolean | DownloadableConfig;\n  shippable?: boolean | ShippableConfig;\n  rentable?: boolean | RentableConfig;\n  ticketed?: boolean | TicketedConfig;\n  giftcard?: boolean | GiftCardConfig;\n  /**\n   * Extras sold alongside this item. The engine has honoured these since the\n   * cart was written — `resolve-item-price` verifies every selected add-on\n   * against this list and prices it from here, never from the storefront — but\n   * nothing in the dashboard could put one here, so the list was always empty.\n   */\n  addable?: boolean | AddableConfig;\n}\n\n// ============================================\n// BEHAVIOR HELPERS\n// ============================================\n\n/**\n * Check if a behavior is enabled regardless of boolean or config format.\n *\n * Takes `unknown` on purpose. Behaviours are read out of JSONB and reach these\n * helpers as `unknown` far more often than as a typed union, so a narrow\n * parameter did not make callers safer — it made forty of them write\n * `isBehaviorEnabled(x as any)`, which asserts a shape nobody checked. The\n * runtime narrowing below is the real guarantee, so let it be the only one.\n */\nexport function isBehaviorEnabled(value: unknown): boolean {\n  if (typeof value === 'boolean') return value;\n  if (typeof value === 'object' && value !== null && 'enabled' in value) {\n    return Boolean((value as BehaviorConfig).enabled);\n  }\n  return false;\n}\n\n/**\n * Extract the config object from a behavior value. See isBehaviorEnabled for\n * why this accepts `unknown`.\n */\nexport function getBehaviorConfig<T extends BehaviorConfig>(\n  value: unknown,\n): T | null {\n  if (typeof value === 'object' && value !== null) return value as T;\n  if (value === true) return { enabled: true } as T;\n  return null;\n}\n\n/**\n * Platform fields — always accepted by POST /products.\n * Template-specific fields go in `data`.\n */\nexport interface CreateProductPayload {\n  type: ProductType;\n  title: string;\n  slug: string;\n  description?: string;\n  shortDescription?: string;\n  category?: string;\n  tags?: string[];\n  featured?: boolean;\n  isActive?: boolean;\n  sortOrder?: number;\n  image?: ProductMedia;\n  gallery?: ProductMedia[];\n  price?: number;\n  compareAtPrice?: number;\n  costPrice?: number | null;\n  currency?: string;\n  trackInventory?: boolean;\n  quantity?: number;\n  lowStockThreshold?: number;\n  behaviors?: ProductBehaviors;\n  hasVariants?: boolean;\n  variants?: ProductVariant[];\n  /** Template-specific fields live here */\n  data?: Record<string, unknown>;\n  /** Semantic intent key — which business activity this item serves */\n  intent?: string;\n  /** Team member IDs (tenant_members.id) assigned as owners of this product. */\n  assigneeIds?: string[];\n}\n\nexport type UpdateProductPayload = Partial<Omit<CreateProductPayload, 'type'>>;\n\n/**\n * Full product as returned by GET /products/:id.\n * Extends the create payload with server-generated fields.\n */\nexport interface Product extends CreateProductPayload {\n  id: string;\n  tenantId: string;\n  seriesId?: string | null;\n  reserved?: number;\n  available?: number;\n  status?: string;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\n// ============================================\n// HELPERS\n// ============================================\n\n/**\n * Generate a URL-safe slug from a title string.\n */\nexport function generateSlug(title: string): string {\n  return title\n    .toLowerCase()\n    .trim()\n    .replace(/[^\\w\\s-]/g, '') // strip special chars\n    .replace(/[\\s_]+/g, '-') // spaces/underscores to hyphens\n    .replace(/-+/g, '-') // collapse multiple hyphens\n    .replace(/^-|-$/g, ''); // trim leading/trailing hyphens\n}\n"],"mappings":"AAYO,IAAK,cAAL,kBAAKA,iBAAL;AACL,EAAAA,aAAA,cAAW;AACX,EAAAA,aAAA,aAAU;AACV,EAAAA,aAAA,aAAU;AACV,EAAAA,aAAA,YAAS;AACT,EAAAA,aAAA,aAAU;AALA,SAAAA;AAAA,GAAA;AAQL,MAAM,uBAAuB;AAAA,EAClC,EAAE,OAAO,2BAAsB,OAAO,mBAAmB;AAAA,EACzD,EAAE,OAAO,yBAAqB,OAAO,kBAAkB;AAAA,EACvD,EAAE,OAAO,yBAAqB,OAAO,UAAU;AAAA,EAC/C,EAAE,OAAO,uBAAoB,OAAO,SAAS;AAAA,EAC7C,EAAE,OAAO,yBAAqB,OAAO,UAAU;AACjD;AA8PO,SAAS,kBAAkB,OAAyB;AACzD,MAAI,OAAO,UAAU,UAAW,QAAO;AACvC,MAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,aAAa,OAAO;AACrE,WAAO,QAAS,MAAyB,OAAO;AAAA,EAClD;AACA,SAAO;AACT;AAMO,SAAS,kBACd,OACU;AACV,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,MAAI,UAAU,KAAM,QAAO,EAAE,SAAS,KAAK;AAC3C,SAAO;AACT;AA6DO,SAAS,aAAa,OAAuB;AAClD,SAAO,MACJ,YAAY,EACZ,KAAK,EACL,QAAQ,aAAa,EAAE,EACvB,QAAQ,WAAW,GAAG,EACtB,QAAQ,OAAO,GAAG,EAClB,QAAQ,UAAU,EAAE;AACzB;","names":["ProductType"]}

package/dist/promised-day.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The day a merchant promised an order would arrive.
+ *
+ * Kept as `YYYY-MM-DD` all the way through — the column, the DTO, `DateField`
+ * and here — because that is the form that can be compared to today. It used
+ * to be free text ("December 20, 2024") which meant nothing could sort by it
+ * and no order could ever be late.
+ *
+ * Days are compared as strings, never as Dates. Turning both sides into Date
+ * objects makes "is this late?" depend on the hour and on the reader's
+ * timezone: an order promised for today is not late at 23:00.
+ */
+/**
+ * Today where the merchant is standing.
+ *
+ * Built from local parts rather than `toISOString().slice(0, 10)`, which is
+ * UTC: at 00:30 in Lagos that returns yesterday, and the queue would call an
+ * order late a day early.
+ */
+export declare function todayIso(now?: Date): string;
+/** Has the promised day passed? Never true for an order nobody promised. */
+export declare function isOverdue(day: string | null | undefined, today?: string): boolean;
+/** Is the promised day today? The orders that need to move now. */
+export declare function isDueToday(day: string | null | undefined, today?: string): boolean;
+/**
+ * How a promised day reads in the interface: "today", "tomorrow", "3 days
+ * late", or the date itself once it is far enough away to need naming.
+ *
+ * Relative near the present because that is the only range where a merchant
+ * is doing arithmetic against today, and absolute beyond it because "in 23
+ * days" is not something anyone can act on.
+ */
+export declare function describePromisedDay(day: string | null | undefined, today?: string): string | null;

package/dist/promised-day.js

@@ -0,0 +1,38 @@
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+function todayIso(now = /* @__PURE__ */ new Date()) {
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${now.getFullYear()}-${month}-${day}`;
+}
+function isOverdue(day, today = todayIso()) {
+  if (!day || !ISO_DAY.test(day)) return false;
+  return day < today;
+}
+function isDueToday(day, today = todayIso()) {
+  return !!day && day === today;
+}
+function describePromisedDay(day, today = todayIso()) {
+  if (!day || !ISO_DAY.test(day)) return null;
+  const diff = daysBetween(today, day);
+  if (diff === 0) return "today";
+  if (diff === 1) return "tomorrow";
+  if (diff === -1) return "a day late";
+  if (diff < -1) return `${Math.abs(diff)} days late`;
+  if (diff <= 6) return `in ${diff} days`;
+  return (/* @__PURE__ */ new Date(`${day}T00:00:00`)).toLocaleDateString(void 0, {
+    day: "numeric",
+    month: "short"
+  });
+}
+function daysBetween(from, to) {
+  const start = Date.parse(`${from}T00:00:00Z`);
+  const end = Date.parse(`${to}T00:00:00Z`);
+  return Math.round((end - start) / 864e5);
+}
+export {
+  describePromisedDay,
+  isDueToday,
+  isOverdue,
+  todayIso
+};
+//# sourceMappingURL=promised-day.js.map

package/dist/promised-day.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/promised-day.ts"],"sourcesContent":["/**\n * The day a merchant promised an order would arrive.\n *\n * Kept as `YYYY-MM-DD` all the way through — the column, the DTO, `DateField`\n * and here — because that is the form that can be compared to today. It used\n * to be free text (\"December 20, 2024\") which meant nothing could sort by it\n * and no order could ever be late.\n *\n * Days are compared as strings, never as Dates. Turning both sides into Date\n * objects makes \"is this late?\" depend on the hour and on the reader's\n * timezone: an order promised for today is not late at 23:00.\n */\n\nconst ISO_DAY = /^\\d{4}-\\d{2}-\\d{2}$/;\n\n/**\n * Today where the merchant is standing.\n *\n * Built from local parts rather than `toISOString().slice(0, 10)`, which is\n * UTC: at 00:30 in Lagos that returns yesterday, and the queue would call an\n * order late a day early.\n */\nexport function todayIso(now: Date = new Date()): string {\n  const month = String(now.getMonth() + 1).padStart(2, '0');\n  const day = String(now.getDate()).padStart(2, '0');\n  return `${now.getFullYear()}-${month}-${day}`;\n}\n\n/** Has the promised day passed? Never true for an order nobody promised. */\nexport function isOverdue(\n  day: string | null | undefined,\n  today: string = todayIso(),\n): boolean {\n  if (!day || !ISO_DAY.test(day)) return false;\n  return day < today;\n}\n\n/** Is the promised day today? The orders that need to move now. */\nexport function isDueToday(\n  day: string | null | undefined,\n  today: string = todayIso(),\n): boolean {\n  return !!day && day === today;\n}\n\n/**\n * How a promised day reads in the interface: \"today\", \"tomorrow\", \"3 days\n * late\", or the date itself once it is far enough away to need naming.\n *\n * Relative near the present because that is the only range where a merchant\n * is doing arithmetic against today, and absolute beyond it because \"in 23\n * days\" is not something anyone can act on.\n */\nexport function describePromisedDay(\n  day: string | null | undefined,\n  today: string = todayIso(),\n): string | null {\n  if (!day || !ISO_DAY.test(day)) return null;\n\n  const diff = daysBetween(today, day);\n  if (diff === 0) return 'today';\n  if (diff === 1) return 'tomorrow';\n  if (diff === -1) return 'a day late';\n  if (diff < -1) return `${Math.abs(diff)} days late`;\n  if (diff <= 6) return `in ${diff} days`;\n\n  return new Date(`${day}T00:00:00`).toLocaleDateString(undefined, {\n    day: 'numeric',\n    month: 'short',\n  });\n}\n\n/**\n * Whole days from `from` to `to`, both `YYYY-MM-DD`.\n *\n * Parsed as UTC so the subtraction cannot land on a 23- or 25-hour day when a\n * daylight-saving boundary falls between the two dates.\n */\nfunction daysBetween(from: string, to: string): number {\n  const start = Date.parse(`${from}T00:00:00Z`);\n  const end = Date.parse(`${to}T00:00:00Z`);\n  return Math.round((end - start) / 86_400_000);\n}\n"],"mappings":"AAaA,MAAM,UAAU;AAST,SAAS,SAAS,MAAY,oBAAI,KAAK,GAAW;AACvD,QAAM,QAAQ,OAAO,IAAI,SAAS,IAAI,CAAC,EAAE,SAAS,GAAG,GAAG;AACxD,QAAM,MAAM,OAAO,IAAI,QAAQ,CAAC,EAAE,SAAS,GAAG,GAAG;AACjD,SAAO,GAAG,IAAI,YAAY,CAAC,IAAI,KAAK,IAAI,GAAG;AAC7C;AAGO,SAAS,UACd,KACA,QAAgB,SAAS,GAChB;AACT,MAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,GAAG,EAAG,QAAO;AACvC,SAAO,MAAM;AACf;AAGO,SAAS,WACd,KACA,QAAgB,SAAS,GAChB;AACT,SAAO,CAAC,CAAC,OAAO,QAAQ;AAC1B;AAUO,SAAS,oBACd,KACA,QAAgB,SAAS,GACV;AACf,MAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,GAAG,EAAG,QAAO;AAEvC,QAAM,OAAO,YAAY,OAAO,GAAG;AACnC,MAAI,SAAS,EAAG,QAAO;AACvB,MAAI,SAAS,EAAG,QAAO;AACvB,MAAI,SAAS,GAAI,QAAO;AACxB,MAAI,OAAO,GAAI,QAAO,GAAG,KAAK,IAAI,IAAI,CAAC;AACvC,MAAI,QAAQ,EAAG,QAAO,MAAM,IAAI;AAEhC,UAAO,oBAAI,KAAK,GAAG,GAAG,WAAW,GAAE,mBAAmB,QAAW;AAAA,IAC/D,KAAK;AAAA,IACL,OAAO;AAAA,EACT,CAAC;AACH;AAQA,SAAS,YAAY,MAAc,IAAoB;AACrD,QAAM,QAAQ,KAAK,MAAM,GAAG,IAAI,YAAY;AAC5C,QAAM,MAAM,KAAK,MAAM,GAAG,EAAE,YAAY;AACxC,SAAO,KAAK,OAAO,MAAM,SAAS,KAAU;AAC9C;","names":[]}

package/dist/proposals-api.d.ts

@@ -0,0 +1,96 @@
+export type ProposalKind = 'page-diff' | 'feature-bundle' | 'operation';
+export type ProposalRisk = 'low' | 'medium' | 'high';
+export type ProposalStatus = 'draft' | 'proposed' | 'approved' | 'applied' | 'reverted' | 'rejected' | 'expired';
+export type ProposalEvidenceType = 'user-prompt' | 'metric' | 'event' | 'catalog-fact' | 'template-fact';
+export interface ProposalEvidence {
+    type: ProposalEvidenceType;
+    content: string;
+    ref?: string;
+}
+/** A single reversible edit to a page's sections or design. */
+export type PageDiffOp = {
+    op: 'set-field';
+    sectionId: string;
+    field: string;
+    value: unknown;
+} | {
+    op: 'set-extension';
+    sectionId: string;
+    field: string;
+    value: unknown;
+} | {
+    op: 'set-variant';
+    sectionId: string;
+    variant: string;
+} | {
+    op: 'add-block';
+    block: {
+        type: string;
+        data: Record<string, unknown>;
+        afterSectionId?: string;
+    };
+} | {
+    op: 'remove-block';
+    sectionId: string;
+} | {
+    op: 'reorder';
+    order: string[];
+};
+export interface PageDiffPayload {
+    pageId: string;
+    ops: PageDiffOp[];
+    designDiff?: Record<string, unknown>;
+}
+export interface ProposalActor {
+    type: 'merchant' | 'runtime' | 'system';
+    id?: string;
+}
+export interface Proposal {
+    id: string;
+    tenantId: string;
+    kind: ProposalKind;
+    /** Open string — includes `mcp:<client>`. */
+    origin: string;
+    risk: ProposalRisk;
+    status: ProposalStatus;
+    evidence: ProposalEvidence[];
+    payload: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ProposalAuditEvent {
+    id: string;
+    proposalId: string;
+    tenantId: string;
+    /** e.g. `draft->proposed`, `approved`, `applied`, `reverted`, `rejected`. */
+    transition: string;
+    actor: ProposalActor;
+    detail: Record<string, unknown>;
+    createdAt: string;
+}
+export type ProposalDetail = Proposal & {
+    auditEvents?: ProposalAuditEvent[];
+};
+/** Result returned by the host after the merchant approves or rejects. */
+export interface ProposalDecisionResult {
+    proposal: Proposal;
+    audit: ProposalAuditEvent;
+}
+/** Kinds the host can actually apply today. Others are typed but rejected. */
+export declare const APPLICABLE_KINDS: readonly ProposalKind[];
+/** Statuses awaiting a human decision. */
+export declare const PENDING_STATUSES: readonly ProposalStatus[];
+export declare function isPageDiffPayload(kind: ProposalKind, payload: Record<string, unknown>): payload is PageDiffPayload & Record<string, unknown>;
+export declare function isDecidable(status: ProposalStatus): boolean;
+export declare const proposalsApi: {
+    /** List every proposal for the current tenant (newest first, host-ordered). */
+    list: (tenantSlug: string) => Promise<Proposal[]>;
+    /** Get a proposal with its full audit trail. */
+    get: (tenantSlug: string, id: string) => Promise<ProposalDetail>;
+    /** Approve → stage the proposal into draft and return its audit event. */
+    approve: (tenantSlug: string, id: string) => Promise<ProposalDecisionResult>;
+    /** Reject the proposal with an optional reason and return its audit event. */
+    reject: (tenantSlug: string, id: string, reason?: string) => Promise<ProposalDecisionResult>;
+    /** Revert only this approved proposal's still-unpublished draft changes. */
+    revert: (tenantSlug: string, id: string) => Promise<ProposalDecisionResult>;
+};

package/dist/proposals-api.js

@@ -0,0 +1,41 @@
+import { apiFetch } from "./api";
+const APPLICABLE_KINDS = ["page-diff"];
+const PENDING_STATUSES = [
+  "proposed"
+];
+function isPageDiffPayload(kind, payload) {
+  return kind === "page-diff" && typeof payload.pageId === "string" && Array.isArray(payload.ops);
+}
+function isDecidable(status) {
+  return status === "proposed";
+}
+const proposalsApi = {
+  /** List every proposal for the current tenant (newest first, host-ordered). */
+  list: (tenantSlug) => apiFetch("/proposals", { tenantSlug }),
+  /** Get a proposal with its full audit trail. */
+  get: (tenantSlug, id) => apiFetch(`/proposals/${id}`, { tenantSlug }),
+  /** Approve → stage the proposal into draft and return its audit event. */
+  approve: (tenantSlug, id) => apiFetch(`/proposals/${id}/approve`, {
+    method: "POST",
+    tenantSlug
+  }),
+  /** Reject the proposal with an optional reason and return its audit event. */
+  reject: (tenantSlug, id, reason) => apiFetch(`/proposals/${id}/reject`, {
+    method: "POST",
+    body: JSON.stringify({ reason }),
+    tenantSlug
+  }),
+  /** Revert only this approved proposal's still-unpublished draft changes. */
+  revert: (tenantSlug, id) => apiFetch(`/proposals/${id}/revert`, {
+    method: "POST",
+    tenantSlug
+  })
+};
+export {
+  APPLICABLE_KINDS,
+  PENDING_STATUSES,
+  isDecidable,
+  isPageDiffPayload,
+  proposalsApi
+};
+//# sourceMappingURL=proposals-api.js.map

package/dist/proposals-api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/proposals-api.ts"],"sourcesContent":["// Governed-proposal review surface — client for the `api` proposals module\n// (POST/GET /proposals, /:id, /:id/approve, /:id/reject, /:id/revert).\n//\n// Mirrors the host contract in\n// api/src/modules/proposals/contracts/* and the Proposal entity. The spine is\n// already live; this is the merchant-facing window onto it (Commerce-AI I1).\n\nimport { apiFetch } from './api';\n\n// ── Contract types (mirror of api host vocabulary) ───────────────────────────\n\nexport type ProposalKind = 'page-diff' | 'feature-bundle' | 'operation';\n\nexport type ProposalRisk = 'low' | 'medium' | 'high';\n\nexport type ProposalStatus =\n  | 'draft'\n  | 'proposed'\n  | 'approved'\n  | 'applied'\n  | 'reverted'\n  | 'rejected'\n  | 'expired';\n\nexport type ProposalEvidenceType =\n  | 'user-prompt'\n  | 'metric'\n  | 'event'\n  | 'catalog-fact'\n  | 'template-fact';\n\nexport interface ProposalEvidence {\n  type: ProposalEvidenceType;\n  content: string;\n  ref?: string;\n}\n\n/** A single reversible edit to a page's sections or design. */\nexport type PageDiffOp =\n  | { op: 'set-field'; sectionId: string; field: string; value: unknown }\n  | { op: 'set-extension'; sectionId: string; field: string; value: unknown }\n  | { op: 'set-variant'; sectionId: string; variant: string }\n  | {\n      op: 'add-block';\n      block: {\n        type: string;\n        data: Record<string, unknown>;\n        afterSectionId?: string;\n      };\n    }\n  | { op: 'remove-block'; sectionId: string }\n  | { op: 'reorder'; order: string[] };\n\nexport interface PageDiffPayload {\n  pageId: string;\n  ops: PageDiffOp[];\n  designDiff?: Record<string, unknown>;\n}\n\nexport interface ProposalActor {\n  type: 'merchant' | 'runtime' | 'system';\n  id?: string;\n}\n\nexport interface Proposal {\n  id: string;\n  tenantId: string;\n  kind: ProposalKind;\n  /** Open string — includes `mcp:<client>`. */\n  origin: string;\n  risk: ProposalRisk;\n  status: ProposalStatus;\n  evidence: ProposalEvidence[];\n  payload: Record<string, unknown>;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport interface ProposalAuditEvent {\n  id: string;\n  proposalId: string;\n  tenantId: string;\n  /** e.g. `draft->proposed`, `approved`, `applied`, `reverted`, `rejected`. */\n  transition: string;\n  actor: ProposalActor;\n  detail: Record<string, unknown>;\n  createdAt: string;\n}\n\nexport type ProposalDetail = Proposal & {\n  auditEvents?: ProposalAuditEvent[];\n};\n\n/** Result returned by the host after the merchant approves or rejects. */\nexport interface ProposalDecisionResult {\n  proposal: Proposal;\n  audit: ProposalAuditEvent;\n}\n\n// ── Type guards / helpers ────────────────────────────────────────────────────\n\n/** Kinds the host can actually apply today. Others are typed but rejected. */\nexport const APPLICABLE_KINDS: readonly ProposalKind[] = ['page-diff'] as const;\n\n/** Statuses awaiting a human decision. */\nexport const PENDING_STATUSES: readonly ProposalStatus[] = [\n  'proposed',\n] as const;\n\nexport function isPageDiffPayload(\n  kind: ProposalKind,\n  payload: Record<string, unknown>,\n): payload is PageDiffPayload & Record<string, unknown> {\n  return (\n    kind === 'page-diff' &&\n    typeof payload.pageId === 'string' &&\n    Array.isArray(payload.ops)\n  );\n}\n\nexport function isDecidable(status: ProposalStatus): boolean {\n  return status === 'proposed';\n}\n\n// ── API module ───────────────────────────────────────────────────────────────\n\nexport const proposalsApi = {\n  /** List every proposal for the current tenant (newest first, host-ordered). */\n  list: (tenantSlug: string) =>\n    apiFetch<Proposal[]>('/proposals', { tenantSlug }),\n\n  /** Get a proposal with its full audit trail. */\n  get: (tenantSlug: string, id: string) =>\n    apiFetch<ProposalDetail>(`/proposals/${id}`, { tenantSlug }),\n\n  /** Approve → stage the proposal into draft and return its audit event. */\n  approve: (tenantSlug: string, id: string) =>\n    apiFetch<ProposalDecisionResult>(`/proposals/${id}/approve`, {\n      method: 'POST',\n      tenantSlug,\n    }),\n\n  /** Reject the proposal with an optional reason and return its audit event. */\n  reject: (tenantSlug: string, id: string, reason?: string) =>\n    apiFetch<ProposalDecisionResult>(`/proposals/${id}/reject`, {\n      method: 'POST',\n      body: JSON.stringify({ reason }),\n      tenantSlug,\n    }),\n\n  /** Revert only this approved proposal's still-unpublished draft changes. */\n  revert: (tenantSlug: string, id: string) =>\n    apiFetch<ProposalDecisionResult>(`/proposals/${id}/revert`, {\n      method: 'POST',\n      tenantSlug,\n    }),\n};\n"],"mappings":"AAOA,SAAS,gBAAgB;AA+FlB,MAAM,mBAA4C,CAAC,WAAW;AAG9D,MAAM,mBAA8C;AAAA,EACzD;AACF;AAEO,SAAS,kBACd,MACA,SACsD;AACtD,SACE,SAAS,eACT,OAAO,QAAQ,WAAW,YAC1B,MAAM,QAAQ,QAAQ,GAAG;AAE7B;AAEO,SAAS,YAAY,QAAiC;AAC3D,SAAO,WAAW;AACpB;AAIO,MAAM,eAAe;AAAA;AAAA,EAE1B,MAAM,CAAC,eACL,SAAqB,cAAc,EAAE,WAAW,CAAC;AAAA;AAAA,EAGnD,KAAK,CAAC,YAAoB,OACxB,SAAyB,cAAc,EAAE,IAAI,EAAE,WAAW,CAAC;AAAA;AAAA,EAG7D,SAAS,CAAC,YAAoB,OAC5B,SAAiC,cAAc,EAAE,YAAY;AAAA,IAC3D,QAAQ;AAAA,IACR;AAAA,EACF,CAAC;AAAA;AAAA,EAGH,QAAQ,CAAC,YAAoB,IAAY,WACvC,SAAiC,cAAc,EAAE,WAAW;AAAA,IAC1D,QAAQ;AAAA,IACR,MAAM,KAAK,UAAU,EAAE,OAAO,CAAC;AAAA,IAC/B;AAAA,EACF,CAAC;AAAA;AAAA,EAGH,QAAQ,CAAC,YAAoB,OAC3B,SAAiC,cAAc,EAAE,WAAW;AAAA,IAC1D,QAAQ;AAAA,IACR;AAAA,EACF,CAAC;AACL;","names":[]}

package/dist/proxy-allowlist.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Which API path prefixes the dashboard proxy will forward.
+ *
+ * Hand-maintained, and the reason it lives in its own file: a first path
+ * segment that is not here answers 404 "Invalid API path" before the request
+ * ever reaches potter-api — and nothing else fails. Types pass, lint passes,
+ * the endpoint is perfect when curled directly. It breaks only in a browser,
+ * and on a list with an empty state it breaks INVISIBLY: the 404 falls through
+ * to "nothing here", which is pixel-identical to the truth and is a lie.
+ *
+ * `src/lib/proxy-allowlist.test.ts` compares this list against every literal
+ * `apiFetch<...>('/segment')` in `lib/api/*.ts`. Run it whenever you add an api
+ * client module; five paths shipped broken before it existed.
+ */
+export declare const ALLOWED_PATH_PREFIXES: string[];