# 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

```bash
npm install @cashierfu/kit
```

**Also install a UUID generator:**

```bash
# Node.js
npm install uuid

# React Native/Expo
npx expo install expo-crypto

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

## Features

- 🏪 Complete product catalog management data models (Catalogs, Products)
- 📦 Inventory management (Containers, Units)
- 👤 User and customer management
- 🏷️ Tagging and categorization
- 🎨 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

```typescript
import { Product } from '@cashierfu/kit'

// Create a new product
const product = new Product({
  title: 'Premium Coffee Beans',
  subtitle: 'House Espresso Blend',
  description: 'Whole-bean coffee roasted for espresso and drip brewing.',
  sku: 'COFFEE-001',
  images: [{ value: 'https://example.com/coffee.jpg' }],
  tags: [{ title: 'Coffee' }]
})

console.log(product.id) // Auto-generated UUID
```

## Core Models

### Product

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

```typescript
const product = new Product({
  title: 'Organic Green Tea',
  subtitle: 'Ceremonial Grade',
  description: 'Loose-leaf sencha with a clean vegetal finish.',
  sku: 'TEA-001',
  catalogId: 'beverages-catalog-id',
  barcodes: [
    { type: 'UPC_A', value: '012345678905' }
  ],
  tags: [
    { title: 'Organic' },
    { title: 'Tea' }
  ],
  metadata: {
    origin: 'Japan',
    weight: '100g'
  }
})
```

### Catalog

Organize products into catalogs with images and tags.

```typescript
const catalog = new Catalog({
  title: 'Summer Collection 2025',
  subtitle: 'Seasonal Essentials',
  description: 'Seasonal assortment for summer campaigns and featured displays.',
  images: [{ value: 'https://example.com/summer.jpg' }],
  tags: [
    { title: 'Seasonal' }
  ]
})
```

### Container

Manage inventory containers (boxes, bins, pallets).

```typescript
const container = new Container({
  title: 'Storage Bin A1',
  subtitle: 'Warehouse Section A',
  description: 'Primary backroom bin for boxed overstock inventory.',
  sku: 'BIN-A1',
  userId: 'warehouse-user',
  metadata: {
    location: 'Warehouse Section A',
    capacity: '50 items'
  }
})
```

### Unit

Track inventory at the unit level, including status history/state tags through `statuses`.

```typescript
const unit = new Unit({
  productId: 'prod-123',
  title: 'Front Shelf Grinder Unit',
  subtitle: 'Launch Display Batch',
  containerId: 'bin-a1',
  amount: 1299,
  description: 'Front-of-house sale unit ready for shelf placement.',
  sku: 'ITEM-001',
  statuses: [{ value: 'active' }],
  images: [
    {
      value: 'https://example.com/unit.jpg',
      blurhash: 'LEHV6nWB2yk8pyo0adR*.7kCMdnj'
    }
  ]
})
```

### User

Customer and staff management with addresses and store associations.

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

## Supporting Models

### Barcode

```typescript
const barcode = new Barcode({
  type: 'UPC_A',
  value: '012345678905'
})
```

### Image

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

### Tag

```typescript
const tag = new Tag({
  title: 'Electronics'
})
```

### Grid

Track grid-based inventory locations.

```typescript
const grid = new Grid({
  title: 'A3',
  slots: [
    { index: 0, productId: 'prod-123' },
    { index: 1, productId: 'prod-456' }
  ]
})
```

## Utilities

### generateUuid

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

```typescript
import { v4 as uuidv4 } from 'uuid'
import { configure, generateUuid } from '@cashierfu/kit'

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

const id = generateUuid()
```

### generateDateString

```typescript
import { generateDateString } from '@cashierfu/kit'

const now = generateDateString() // ISO 8601 format
```

### generateAlphanumeric

```typescript
import { generateAlphanumeric } from '@cashierfu/kit'

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

### generateHexColor

```typescript
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:**
```bash
npm install uuid
```
```typescript
import { configure } from '@cashierfu/kit'
import { v4 as uuidv4 } from 'uuid'

configure({ generateUuid: uuidv4 })
```

**React Native/Expo:**
```bash
npx expo install expo-crypto
```
```typescript
import { configure } from '@cashierfu/kit'
import * as Crypto from 'expo-crypto'

configure({ generateUuid: () => Crypto.randomUUID() })
```

**Browser:**
```typescript
import { configure } from '@cashierfu/kit'

configure({ generateUuid: () => crypto.randomUUID() })
```

**Custom (for testing):**
```typescript
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

Unit
├── productId → Product
├── containerId → Container
├── images: Image[]
└── statuses: Status[]
```

## Static Properties

Several models include a static `collection` property for database integration:

- `Product.collection = 'products'`
- `Catalog.collection = 'catalogs'`
- `Container.collection = 'containers'`
- `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:

```typescript
// 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

```bash
# 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](./docs) - Generated TypeDoc documentation
- [Migration Guide](./MIGRATION.md) - Version migration guides
- [Quick Reference](./QUICK_REFERENCE.md) - Quick reference for all models
- [Contributing](./.github/CONTRIBUTING.md) - Contributing guidelines

## License

ISC

## Author

Jay Deaton