@libreapps/commerce 7.5.1

package/service/impls/standalone/order/index.ts

@@ -0,0 +1,129 @@
+import { 
+  getFirestore, 
+  collection, 
+  setDoc, 
+  doc, 
+  serverTimestamp,
+  type Firestore,
+  type FieldValue, 
+} from 'firebase/firestore'  
+
+import type { ActualLineItemSnapshot } from '../actual-line-item'
+
+import firebaseApp from './firebase' 
+
+let dbInstance: Firestore | undefined = undefined
+
+const getDBInstance = (name: string): Firestore => {
+  if (!dbInstance) {
+    dbInstance = getFirestore(firebaseApp, name) 
+  }
+  return dbInstance  
+} 
+ 
+interface SavedOrder {
+  email: string
+  name: string
+  // TODO: add shippingInfo type
+  shippingInfo?: any
+  paymentInfo?: any
+  status: string
+  timestamp: FieldValue
+  items: ActualLineItemSnapshot[]
+}
+
+const createOrder = async (
+  email: string,
+  items: ActualLineItemSnapshot[],
+  options: {
+    dbName: string
+    ordersTable: string
+  },
+  name?: string
+): Promise<{
+  success: boolean,
+  error: any,
+  id?: string,
+}> => {  
+
+  let error: any | null = null
+  const ordersRef = collection(getDBInstance(options.dbName), options.ordersTable)
+  const orderId = `${email}-${new Date().toISOString()}`
+
+  try {
+    await setDoc(doc(ordersRef, orderId), {
+      email,
+      name: name ?? '',
+      status: 'open',
+      timestamp: serverTimestamp(),
+      items,
+    } satisfies SavedOrder)
+    return { success: !error, error, id: orderId }
+  }
+  catch (e) {  
+    console.error('Error writing item document: ', e)
+    error = e  
+  }  
+  
+  return { success: !error, error }  
+}
+
+const updateOrderShippingInfo = async (
+  orderId: string,
+  shippingInfo: any,
+  options: {
+    dbName: string
+    ordersTable: string
+  }
+): Promise<{
+  success: boolean,
+  error: any
+}> => {  
+
+  let error: any | null = null
+  const ordersRef = collection(getDBInstance(options.dbName), options.ordersTable)
+
+  try {
+    await setDoc(doc(ordersRef, orderId), {
+      shippingInfo,
+      timestamp: serverTimestamp(),
+    }, { merge: true })
+  } 
+  catch (e) {  
+    console.error('Error writing item document: ', e)
+    error = e  
+  }  
+  
+  return { success: !error, error }  
+}
+
+const updateOrderPaymentInfo = async (
+  orderId: string,
+  paymentInfo: any,
+  options: {
+    dbName: string
+    ordersTable: string
+  }
+): Promise<{
+  success: boolean,
+  error: any
+}> => {  
+
+  let error: any | null = null
+  const ordersRef = collection(getDBInstance(options.dbName), options.ordersTable)
+
+  try {
+    await setDoc(doc(ordersRef, orderId), {
+      paymentInfo,
+      timestamp: serverTimestamp(),
+    }, { merge: true })
+  } 
+  catch (e) {  
+    console.error('Error writing item document: ', e)
+    error = e  
+  }  
+  
+  return { success: !error, error }  
+}
+
+export { createOrder, updateOrderShippingInfo, updateOrderPaymentInfo }

package/service/impls/standalone/persistence.ts

@@ -0,0 +1,33 @@
+import { reaction } from 'mobx'
+import { StandaloneService, type StandaloneServiceSnapshot } from './index'
+
+const LS_KEY = 'lux-cart'
+
+const readSnapshot = (key: string): StandaloneServiceSnapshot | undefined  => {
+  const snapshotAsStr = localStorage.getItem(key)
+  return snapshotAsStr ? JSON.parse(snapshotAsStr) as StandaloneServiceSnapshot : undefined
+}
+
+const writeSnapshotsOnChange = (cmmc: StandaloneService, key: string): void => {
+
+  if (typeof window !== 'undefined') {
+    reaction(
+      () => (cmmc.cartTotal),
+      (total) => {
+        if (total > 0) {
+          const snapshot = cmmc.takeSnapshot()
+          localStorage.setItem(key, JSON.stringify(snapshot) )
+        }
+        else {
+          localStorage.removeItem(key)  
+        }
+      }
+    )
+  }
+}
+
+export {
+  readSnapshot,
+  writeSnapshotsOnChange  
+}
+

package/service/path-utils.ts

@@ -0,0 +1,26 @@
+import type { SelectedPaths } from '../types'
+import sep from './sep'
+
+export const getSelectedPaths = (
+  skuPath: string
+): { paths: SelectedPaths; level: number } => {
+  
+  const toks = skuPath.split(sep.tok)
+  const level = toks.length - 1
+  const paths: SelectedPaths = {}
+  for (let l = 1; l <= level; l++ ) {
+    paths[l] = [toks[l]]   
+  } 
+  return {
+    paths,
+    level
+  }
+}
+
+export const getParentPath = (skuPath: string): string => (
+  skuPath.split(sep.tok).slice(0, -1).join(sep.tok)
+)
+
+export const lastToken = (skuPath: string): string => (
+  skuPath.split(sep.tok).pop()!
+)

package/service/sep.ts

@@ -0,0 +1,7 @@
+import type { TokenSeparators } from '../types'
+
+export default {
+  tok: '-',
+  subTok: '_',
+  decimal: '.'
+} satisfies TokenSeparators 

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../tsconfig.libreapps.base.json",
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ],
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "skipLibCheck": true,
+    "strict": false
+  }
+}

package/types/README.md

@@ -0,0 +1,2 @@
+These are the types that the card ui expects and understands.
+There should always be adaptors both ways from LibreApps commerceJs types.

package/types/category-node.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react'
+
+interface CategoryNode {
+  skuToken: string             // a token in the sku
+  label: string;
+    /** 
+     * Explicitly marks this node as a "last user-visible" / "outermost" Category. 
+     * Normally, a node is "outermost" when it has no subnodes 
+     * (and thus is a family with products -- "single-family")
+     * But if it *has* subnodes, and its subNodes are actually sibling families
+     * of a Category, it must be marked as "outermost" ("multi-family")
+     * */
+  outermost?: boolean;
+  img? : string | ReactNode  // icon is required 
+  imgAR? : number           // helps with svgs
+
+  /** 
+   * One word prompt that describes the 'meaning' of 
+   * the subnodes. 
+   * For example, if a node is 'Lux Credit', 
+   * it's subNodesLabel might be 'Level', so some UI's
+   * might be configured to render 'Level: Black'
+   * 
+   * or something like...
+   * 
+   * <Tabs title={parentNode.label + ': ' + parentNode.subNodesLabel} values={families.map((f) => (f.shortName))} />
+   * 
+   * ...which renders
+   *        
+   * Lux Credit Levels:
+   * Black   Elite   Founder   Sovereign 
+  */
+  subNodesLabel?: string   
+  subNodes?: CategoryNode[]
+}
+
+type CategoryNodeRole = 
+  'single-family' | 
+  'family-in-multi-family' | 
+  'multi-family' | 
+  'non-outermost' 
+
+  // Which facets tokens are 'on' at each level
+type SelectedPaths = Record<number, string[]>
+
+export type {
+  CategoryNodeRole,
+  CategoryNode,
+  SelectedPaths
+}

package/types/checkout.ts

@@ -0,0 +1,47 @@
+import type { ComponentType } from 'react'
+import type { UseFormReturn } from 'react-hook-form'
+
+type TransactionStatus = 'unpaid' | 'paid' | 'confirmed' | 'error'
+
+interface CheckoutStepComponentProps {
+  onDone: () => void
+  orderId: string | undefined
+  setOrderId: (orderId: string | undefined) => void
+}
+
+interface CheckoutStep {
+  name: string  
+  label?: string 
+  Comp: ComponentType<CheckoutStepComponentProps>
+}
+
+type ContactFormType = UseFormReturn<{
+  name: string
+  email: string
+}, any, {
+  name: string
+  email: string
+}>
+
+interface PaymentMethodComponentProps {
+  onDone: () => void
+  transactionStatus: TransactionStatus
+  setTransactionStatus: (status: TransactionStatus) => void
+  storePaymentInfo: (paymentInfo: any) => Promise<void>
+  contactForm: ContactFormType
+}
+
+interface PaymentMethodDesc {
+  value: string  
+  label: string 
+  Comp: ComponentType<PaymentMethodComponentProps>
+}
+
+export {
+  type TransactionStatus,
+  type CheckoutStepComponentProps,
+  type CheckoutStep,
+  type PaymentMethodComponentProps,
+  type PaymentMethodDesc,
+  type ContactFormType,
+}

package/types/commerce-config.ts

@@ -0,0 +1,13 @@
+import type { ServiceOptions } from '..'
+import type { CategoryNode } from './category-node'
+import type { Family } from './family'
+import type { SelectionUISpecifier }  from './selection-ui-specifier'
+
+interface CommerceConfig {
+  families: Family[]
+  rootNode: CategoryNode
+  options?: ServiceOptions
+  uiSpecifiers?: Record<string, SelectionUISpecifier>
+}
+
+export { type CommerceConfig as default }

package/types/commerce-service.ts

@@ -0,0 +1,128 @@
+import type { LineItem, ObsLineItemRef } from './line-item'
+import type { CategoryNode, SelectedPaths, CategoryNodeRole } from './category-node'
+import type { Family, ObsFamilyRef} from './family'
+import type Promo from './promo'
+
+
+interface CommerceService extends ObsLineItemRef, ObsFamilyRef {
+
+    /** Items in cart */
+  get cartItems(): LineItem[]
+    /** Total of all quantities of all items in cart */
+  get cartQuantity(): number
+    /** Total of all prices x quantities of items in cart */
+  get cartTotal(): number
+
+    /** cartItem whose quantity was modified most recently 
+     * item: LineItem
+     * modified: number (timestamp)
+     * (undefined if cartEmpty)
+     */
+  get recentItem(): { item: LineItem, modified: number }  | undefined 
+  get promoAppliedCartTotal(): number
+
+  get cartEmpty(): boolean
+
+  get appliedPromo(): Promo | null
+  setAppliedPromo(promo: Promo | null): void
+    /** returns the price with promo applied, of undefined if no promo or promo does not apply */
+  itemPromoPrice(item: LineItem): number | undefined
+   
+  getFamilySubtotal(familyId: string): number
+
+  createOrder(email: string, name?: string): Promise<string | undefined>
+  updateOrderShippingInfo(orderId: string, shippingInfo: any): Promise<void>
+  updateOrderPaymentInfo(orderId: string, paymentInfo: any): Promise<void>
+
+    /** 
+     * Sets the tokens at each level supplied.
+     * If a level is selected as [], nothing will be selected.
+     * If a level is missing (undefined), everything at that level is selected
+     * 
+     * This selects one or more Family's, and all the LineItem's in them.
+     * 
+     * An empty value object selects all Family's and all LineItem's,
+     * */ 
+  selectPaths(value: SelectedPaths): Family[]
+  selectPath(skuPath: string): Family[] 
+
+    /**
+     * With role as ...
+     *  
+     * 'single-family': 
+     *    item: item with skuPath as SKU, otherwise undefined
+     *    node: node at path (or item's parent node),
+     *    family: node at path as family (or item's parent node as family), 
+     *    families: undefined 
+     * 
+     * 'family-in-multi-family': 
+     *    item: item with skuPath as SKU, otherwise undefined
+     *    node: parent node of this family (or parent node of item's family)
+     *    family: this family (or item's family)
+     *    families: this family (or item's family) and siblings
+     * 
+     * 'multi-family': 
+     *    item: undefined
+     *    node: node at path 
+     *    family: undefined
+     *    families: subnodes / families of this node
+     *    
+     * 'non-outermost': 
+     *    item: undefined
+     *    node: node at path
+     *    family: undefined
+     *    families: undefined
+     * 
+    */
+  peek(skuPath: string): {
+    role: CategoryNodeRole
+    family: Family | undefined
+    families: Family[] | undefined
+    node: CategoryNode | undefined
+    item: LineItem | undefined
+  } | string // or error string
+
+    /** @deprecated
+     *  Whether this path defines a Family, or if it has further levels 
+     * */
+  getNodeAtPath(skuPath: string): CategoryNode | undefined 
+
+  get selectedPaths(): SelectedPaths // returns a copy
+  
+  get selectedItems(): LineItem[]
+  get selectedFamilies(): Family[] 
+  get hasSelection(): boolean
+
+
+    /** 
+     * Who are the subnodes selected at 'level'? 
+     * If more than one value is selected at 'level', 
+     * the returned CategoryNode[] may represent multiple sets. 
+     * */ 
+  getSelectedNodesAtLevel(level: number): CategoryNode[] | undefined 
+
+      /**
+     * For convenience, so widgets can share state.
+     * "current" is unrelated to what branches and items are 
+     * "selected" (with CategoryNode's and paths)
+     * 
+     *  SEE ALSO: from ObsLineItemRef and ObsFamilyRef, there are also
+     *  get item(): LineItem | undefined
+     *  get family(): Family | undefined
+     * 
+     *  These simply delegate to these functions
+     *  */ 
+  setCurrentItem(sku: string | undefined): boolean // valid sku and was set.
+  get currentItem(): LineItem | undefined
+  setCurrentFamily(id: string | undefined): boolean // valid id and was set.
+  get currentFamily(): Family | undefined
+
+    // utility
+  getFamilyById(id: string): Family | undefined
+  getItemBySku(sku: string): LineItem | undefined
+}
+
+
+export {
+  type CommerceService as default
+}

package/types/family.ts

@@ -0,0 +1,26 @@
+import type { ImageDef } from '@libreapps/ui/types'
+import type Product from './product'
+
+interface Family {
+  id: string            // LXB-AU-B
+  title: string         // Minted Bar, Lux Elite Card
+  titleShort?: string   // Elite
+  parentTitle?: string  // Lux Gold, Lux Credit
+  byline?: string       // literal text, or name of function on 'this' object that returns a string
+  desc?: string
+  img?: ImageDef, 
+    // inbound to the service, they're Products 
+    // when it's initialized, interally they become LineItems
+    // always ok to cast up to LineItem thereafter
+  products: Product[] 
+}
+
+
+interface ObsFamilyRef {
+  get family(): Family | undefined
+}
+
+export {
+  type Family, 
+  type ObsFamilyRef
+}

package/types/index.ts

@@ -0,0 +1,15 @@
+
+export type { default as CommerceService } from './commerce-service'
+export type { default as CommerceConfig } from './commerce-config'
+export type { default as MultiFamilySelectorProps } from './multi-family-selector-props'
+export type { default as Product } from './product'
+export type { default as Promo } from './promo'
+export type { default as TokenSeparators } from './token-separators'
+
+export * from './category-node'
+export * from './checkout'
+export * from './family'
+export * from './item-selector'
+export * from './line-item'
+export * from './selection-ui-specifier'
+export * from './string-mutator'

package/types/item-selector.ts

@@ -0,0 +1,97 @@
+import type { LineItem, ObsLineItemRef } from './line-item'
+
+interface ItemSelector {
+  items: LineItem[]
+  selectedItemRef: ObsLineItemRef
+  selectSku: (sku: string) => void 
+}
+
+  /** default: 'text' */
+type ItemButton = 'text' | 'image-and-text' | 'image' 
+
+  // NOTE: if a field is added here, it should also
+  // be added to util/item-selector-options-accessor.ts
+type ItemSelectorOptions = {
+
+    /** 
+     * default: short
+     * 'short': product.shortTitle if defined
+     * 'long': always us product.title, even if .shortTitle is defined
+     * 'none': do not show title AND BYLINE
+     * 
+     * (NOTE: *not* the same as buttonType = 'none')
+     */
+  familyTitle?: 'none' | 'long' | 'short'
+
+    /** only if title shown 
+     * default: false */
+  showFamilyByline?: boolean
+
+    /** 
+     * Whether the item label includes the Family name.
+     * eg, 'Minted Bar, 1oz' vs '1oz'
+     * default: false.
+     */
+  showFamilyInOption?: boolean
+    /** default: true if it exists */
+  showByline?: boolean
+
+    /** default: true */
+  showPrice?: boolean
+
+    /**
+     * Show the current item quantity along with title and price.
+     * default: false
+     */
+  showQuantity?: boolean   
+
+  buttonType?: ItemButton  
+
+    /** (button selector only) default: false */
+  horizButtons?: boolean  
+
+    /** (carousel selector only) 
+     * affects sort.  See below.
+     * default: false */
+  showSlider?: boolean
+
+    /** default true */
+  showButtonIfOnlyOne?: boolean
+
+    /** 
+     * Sort by cost. 
+     * If it's a carousel selector and 'showSlider' is true, 
+     * defaults to 'asc', unless another value is explicitly specified.
+     * Otherwise, defaults to 'none' 
+     * */
+  sort?: 'none' | 'asc' | 'desc' 
+}
+
+interface _ItemSelectorCompProps {
+  clx?: string
+  itemClx?: string
+  soleItemClx?: string
+    /** type-specific props for ItemSelector's.
+     * eg, Carousel options.
+     */
+  ext?: any
+    /** List selectors will scroll.  
+     * Used internally
+     * default: false */
+  scrollable? : boolean
+  options?: ItemSelectorOptions
+
+  mobile?: boolean 
+}
+
+type ItemSelectorCompProps = Omit<_ItemSelectorCompProps, 'scrollable'>
+
+interface ItemSelectorProps extends 
+  ItemSelector, _ItemSelectorCompProps {}
+
+export {
+  type ItemSelector,
+  type ItemSelectorCompProps,
+  type ItemSelectorOptions,
+  type ItemSelectorProps
+}

package/types/line-item.ts

@@ -0,0 +1,29 @@
+import type Product from './product'
+
+  // Client code always 
+  // has a LineItem, whether the Product
+  // is in the cart or not. Something is in the cart
+  // when its quantity > 0.  That's the only difference.
+  // The ui, and as well as some Cart state, reacts to 
+  // changes in this quantity.
+
+  // It could have more accurately been named
+  // 'QuantifiedProduct' but that sucked.
+interface LineItem extends Product {
+
+  /** all observable */
+  get quantity(): number
+  get canDecrement(): boolean
+  get isInCart(): boolean
+
+  increment(): void
+  decrement(): void
+
+  get title(): string
+}
+
+interface ObsLineItemRef {
+  get item(): LineItem | undefined
+}
+
+export type { LineItem, ObsLineItemRef}

package/types/multi-family-selector-props.ts

@@ -0,0 +1,20 @@
+import type { Dimensions } from '@libreapps/ui/types'
+
+import type { Family } from './family'
+import type { ItemSelectorOptions } from './item-selector'
+import type { MultiFamilySelectorOptions } from './selection-ui-specifier'
+import type { CategoryNode } from './category-node'
+import type { LineItem } from './line-item'
+
+interface MultiFamilySelectorProps {
+  families: Family[]
+  parent: CategoryNode
+  clx?: string
+  itemClx?: string
+  itemOptions?: ItemSelectorOptions
+  selectorOptions?: MultiFamilySelectorOptions 
+  mediaConstraint?: Dimensions
+  mobile?: boolean
+}
+
+export { type MultiFamilySelectorProps as default }

package/types/product.ts

@@ -0,0 +1,21 @@
+import type { ImageDef, MediaStackDef } from '@libreapps/ui/types'
+
+interface Product extends MediaStackDef {
+  id: string    // DB index // not a logical aspect of our domain.  may not be necessary at all
+  sku: string   // human visible on orders etc.
+  fullTitle?: string
+  optionLabel: string
+  optionLabelShort?: string
+  familyId: string  // skuPath, eg LXB-AU-B
+  familyTitle: string
+  byline?: string
+  desc?: string
+  price: number
+    // image to by uses as an image button in a list of choices
+    // defaults to (MediaStackDef's) img
+  optionImg?: ImageDef
+}
+
+export {
+  type Product as default
+}

package/types/promo.ts

@@ -0,0 +1,10 @@
+interface Promo {
+  type: 'percent' | 'amount'
+  code: string
+  value: number,
+  skus?: string[]
+}
+
+export {
+  type Promo as default
+}