CashierFu-Kit

A TypeScript ORM library for CashierFu, providing a comprehensive set of data models and utilities for building point-of-sale and e-commerce applications.

Installation

npm install @cashierfu/kit

Also install a UUID generator:

# Node.js
npm install uuid

# React Native/Expo
npx expo install expo-crypto

# Browser: no installation needed (uses native crypto.randomUUID)

Features

• 🏪 Complete POS data models (Products, Orders, Tills, Gift Cards)
• 📦 Inventory management (Containers, Units, Catalogs)
• 👤 User and customer management
• 🏷️ Tagging and categorization
• 📊 Order processing and payment tracking
• 🎨 Image management with blurhash support
• 🔧 Configurable UUID generation (bring your own generator)
• 📝 TypeScript-first with full type safety
• 🌳 Tree-shakeable ESM and CommonJS builds
• 📦 Tiny bundle size (< 2KB gzipped for ESM)
• 🚫 Zero dependencies

Quick Start

import { configure, Product, Order } from '@cashierfu/kit'

// Create a new product
const product = new Product({
  title: 'Premium Coffee Beans',
  sku: 'COFFEE-001',
  image: 'https://example.com/coffee.jpg',
  tags: [{ id: '1', title: 'Coffee', value: 'coffee' }]
})

// Create an order
const order = new Order({
  items: [{
    productId: product.id,
    title: product.title,
    amount: 1299, // in cents
    taxable: true
  }],
  status: 'Pending'
})

console.log(order.id) // Auto-generated UUID

Core Models

Product

Represents a product in your inventory with support for multiple barcodes, images, and metadata.

const product = new Product({
  title: 'Organic Green Tea',
  sku: 'TEA-001',
  catalogId: 'beverages-catalog-id',
  barcodes: [
    new Barcode({ type: 'UPC', value: '012345678905' })
  ],
  tags: [
    new Tag({ title: 'Organic', value: 'organic' }),
    new Tag({ title: 'Tea', value: 'tea' })
  ],
  metadata: {
    origin: 'Japan',
    weight: '100g'
  }
})

Order

Comprehensive order management with items, payments, shipments, and calculations.

const order = new Order({
  items: [
    new OrderItem({
      productId: 'prod-123',
      title: 'Green Tea',
      amount: 999,
      taxable: true
    })
  ],
  payments: [
    new OrderPayment({
      type: 'Credit Card',
      amount: 1079
    })
  ],
  calculations: new OrderCalculations({
    subtotal: 999,
    tax: 80,
    total: 1079,
    payment: 1079,
    due: 0
  }),
  status: 'Completed',
  customer: new OrderAddress({
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    phone: '555-0123'
  })
})

Catalog

Organize products into catalogs with images and tags.

const catalog = new Catalog({
  title: 'Summer Collection 2025',
  image: 'https://example.com/summer.jpg',
  tags: [
    new Tag({ title: 'Seasonal', value: 'seasonal' })
  ]
})

Till

Track cash register operations with corrections and audits.

const till = new Till({
  title: 'Register 1',
  userId: 'cashier-123',
  corrections: [
    new TillCorrection({
      action: 'Credit',
      amount: 5000, // $50.00
      orderId: 'order-456'
    })
  ]
})

Container

Manage inventory containers (boxes, bins, pallets).

const container = new Container({
  title: 'Storage Bin A1',
  sku: 'BIN-A1',
  userId: 'warehouse-user',
  metadata: {
    location: 'Warehouse Section A',
    capacity: '50 items'
  }
})

Gift Card

Handle gift card creation and balance tracking.

const giftCard = new GiftCard({
  barcode: new Barcode({
    type: 'Code128',
    value: 'GC-123456789'
  }),
  corrections: [
    new GiftCardCorrection({
      action: 'Credit',
      amount: 5000, // Initial load: $50.00
      orderId: 'order-789'
    })
  ]
})

User

Customer and staff management with addresses and store associations.

const user = new User({
  email: '[email protected]',
  firstName: 'Jane',
  lastName: 'Smith',
  role: 'Admin',
  addresses: [
    new UserAddress({
      title: 'Home',
      address1: '123 Main St',
      city: 'Portland',
      state: 'OR',
      zip: '97201'
    })
  ],
  store: new UserStore({
    title: 'Downtown Store',
    taxPercent: 8.5,
    stripeAccountId: 'acct_123'
  })
})

Listing

Create marketplace listings for products.

const listing = new Listing({
  productId: 'prod-123',
  title: 'Vintage Coffee Grinder',
  amount: 4999,
  url: 'https://marketplace.example.com/items/coffee-grinder',
  userId: 'seller-456'
})

Supporting Models

Barcode

const barcode = new Barcode({
  type: 'UPC',
  value: '012345678905'
})

Image

const image = new Image({
  value: 'https://example.com/product.jpg',
  blurhash: 'LEHV6nWB2yk8pyo0adR*.7kCMdnj',
  position: 0
})

Tag

const tag = new Tag({
  title: 'Electronics',
  value: 'electronics'
})

Unit

Define custom units of measure.

const unit = new Unit({
  abbreviation: 'lb',
  title: 'Pound'
})

Grid

Track grid-based inventory locations.

const grid = new Grid({
  column: 3,
  row: 5,
  title: 'A3-5'
})

Utilities

generateUUID

Generate UUIDs using your configured generator. Optionally configure a UUID generator before using this utility.

import { v4 as uuidv4 } from 'uuid'
import { configure, generateUUID } from '@cashierfu/kit'

// Configure first (required)
configure({ generateUUID: uuidv4 })

const id = generateUUID()

generateDateString

import { generateDateString } from '@cashierfu/kit'

const now = generateDateString() // ISO 8601 format

generateAlphanumeric

import { generateAlphanumeric } from '@cashierfu/kit'

const code = generateAlphanumeric(8) // e.g., "A3X9K2P7"

generateHexColor

import { generateHexColor } from '@cashierfu/kit'

const color = generateHexColor() // e.g., "#3A5F9E"

Configuration

UUID Generation (Optional)

Optionally configure a UUID generator before creating any models.

Node.js:

npm install uuid

import { configure } from '@cashierfu/kit'
import { v4 as uuidv4 } from 'uuid'

configure({ generateUUID: uuidv4 })

React Native/Expo:

npx expo install expo-crypto

import { configure } from '@cashierfu/kit'
import * as Crypto from 'expo-crypto'

configure({ generateUUID: () => Crypto.randomUUID() })

Browser:

import { configure } from '@cashierfu/kit'

configure({ generateUUID: () => crypto.randomUUID() })

Custom (for testing):

import { configure } from '@cashierfu/kit'

let counter = 1
configure({ generateUUID: () => `test-${counter++}` })

Model Relationships

User
├── addresses: UserAddress[]
└── store: UserStore

Catalog
├── images: Image[]
└── tags: Tag[]

Product
├── catalogId → Catalog
├── barcodes: Barcode[]
├── images: Image[]
└── tags: Tag[]

Container
├── images: Image[]
└── userId → User

Order
├── items: OrderItem[]
│   ├── productId → Product
│   ├── containerId → Container
│   └── images: Image[]
├── payments: OrderPayment[]
├── shipment: OrderShipment
├── calculations: OrderCalculations
├── customer: OrderAddress
├── store: OrderStore
└── userId → User

Till
├── corrections: TillCorrection[]
└── userId → User

GiftCard
├── barcode: Barcode
├── corrections: GiftCardCorrection[]
└── userId → User

Listing
├── productId → Product
├── userId → User
└── images: Image[]

Static Properties

Several models include a static collection property for database integration:

• Product.collection = 'products'
• Catalog.collection = 'catalogs'
• Container.collection = 'containers'
• GiftCard.collection = 'giftCards'
• Listing.collection = 'listings'
• Order.collection = 'orders'
• Till.collection = 'tills'
• Unit.collection = 'units'
• User.collection = 'users'

TypeScript Support

All models are written in TypeScript and include full type definitions. Every class constructor accepts a Partial<T> type, allowing you to create instances with only the properties you need:

// Minimal product
const product1 = new Product({ title: 'Simple Product' })

// Full product with all properties
const product2 = new Product({
  title: 'Complete Product',
  sku: 'PROD-001',
  catalogId: 'cat-123',
  barcodes: [],
  images: [],
  tags: [],
  metadata: {},
  favorites: []
})

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run watch

# Run tests with coverage
npm run coverage

# Build the library (dual ESM + CJS)
npm run build

# Generate API documentation
npm run docs

# Check bundle size
npm run size

# Lint code
npm run lint

# Fix linting issues
npm run fix

Documentation

• API Documentation - Generated TypeDoc documentation
• Migration Guide - Version migration guides
• Quick Reference - Quick reference for all models
• Contributing - Contributing guidelines

License

ISC

Author

Jay Deaton