# AI Assistant Context for CashierFu-Kit

This file provides context to help AI assistants understand how to use CashierFu-Kit in projects.

## What is CashierFu-Kit?

CashierFu-Kit is a TypeScript ORM library for building point-of-sale (POS) and e-commerce applications. It provides data models and utilities for managing:

- Catalogs and Products
- Containers and Unititized Inventory
- User accounts

## Core Concepts

### 1. Models Are Classes with Partial Constructors

All models accept a `Partial<T>` parameter in their constructor, meaning you can create instances with only the properties you need:

```typescript
// Minimal
const product = new Product({ title: 'Coffee' })

// With more details
const product = new Product({
  title: 'Coffee',
  sku: 'COFFEE-001',
  amount: 1299
})
```

### 2. Auto-Generated Properties

Models automatically generate certain properties if not provided:
- `id` - Auto-generated UUID
- `createdAt` / `updatedAt` - Auto-generated ISO date strings
- `color` (for Tags) - Auto-generated hex color

### 3. Database Collections

Many models have a static `collection` property for database integration:

```typescript
Product.collection // 'products'
Unit.collection   // 'units'
User.collection    // 'users'
```

### 4. Money is Stored in Cents

All monetary amounts are integers representing cents:

```typescript
const product = new Product({ title: 'Coffee Beans' })
const unit = new Unit({ amount: 87 })         // $0.87
```

### 5. Relationships via IDs

Models reference each other through ID fields:

```typescript
const unit = new Unit({
  userId: 'user-123',           // Links to User
  title: 'New Unit',
  containerId: 'container-123'  // Links to container
})
```

## Common Use Cases

### Creating a Product with Full Details

```typescript
const product = new Product({
  title: 'Organic Coffee',
  sku: 'COFFEE-001',
  catalogId: 'beverages',
  barcodes: [new Barcode({ type: 'UPC_A', value: '012345678905' })],
  images: [new Image({ value: 'https://...' })],
  tags: [new Tag({ title: 'Organic' })],
  metadata: { origin: 'Colombia' }
})
```

### Managing Unit Statuses

```typescript
const unit = new Unit({
  productId: 'prod-123',
  containerId: 'warehouse-bin-a1',
  amount: 1299,
  sku: 'ITEM-001',
  statuses: [
    new Status({ value: 'active' }),
    new Status({ value: 'draft' })
  ],
  images: [
    new Image({
      value: 'https://example.com/unit.jpg',
      blurhash: 'LEHV6nWB2yk8pyo0adR*.7kCMdnj'
    })
  ],
  barcodes: [new Barcode({ type: 'CODE128', value: 'UNIT-001' })]
})
```

### Managing Inventory with Units

```typescript
const unit = new Unit({
  productId: 'prod-123',
  containerId: 'warehouse-bin-a1',
  amount: 1299,
  sku: 'ITEM-001',
  barcodes: [new Barcode({ type: 'CODE128', value: 'UNIT-001' })]
})
```

## Important Types

### Enumerations

```typescript
// Barcode Types
type BarcodeType = 'UPC_A' | 'UPC_E' | 'EAN13' | 'CODE128' | 'QR' | ...

// Unit status values
type StatusValues = 'active' | 'draft' | 'missing' | 'sold'
```

## Configuration

### Custom UUID Generation

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

configure({ generateUuid: () => `CUSTOM-${Date.now()}` })
```

## Model Reference

### Main Models
- **Product** - Products in inventory
- **User** - User accounts (customers, staff, admin)
- **Catalog** - Product collections/categories
- **Container** - Physical storage locations
- **Unit** - Individual product instances with location
- **Status** - Unit status entries (`active`, `draft`, `missing`, `sold`)

### Supporting Classes
- **Barcode** - Barcode data
- **Image** - Reusable image data (`value`, `blurhash`)
- **Tag** - Categorization tags
- **Grid** / **GridSlot** - Grid-based layouts

### User Subclasses
- **UserAddress** - Saved addresses
- **UserStore** - Store configuration

## Utilities

- `generateUuid()` - Generate UUIDs (configurable)
- `generateDateString()` - ISO 8601 date strings
- `generateAlphanumeric(length)` - Random alphanumeric codes
- `generateHexColor()` - Random hex colors

## Tips for AI Assistants

1. **Always use Partial types** when suggesting model instantiation
2. **Remember amounts are in cents** - convert dollars to cents
3. **Use proper ID references** - don't embed full objects, use IDs
4. **Check static collections** - they're useful for database operations
5. **Import from '@cashierfu/kit'** - not from individual files
6. **Types are exported** - use `import type { Product }` when needed
7. **All models auto-generate** - id, createdAt, updatedAt if not provided
8. **Nested models exist** - Barcode, Image, etc. should be instantiated

## Example Project Integration

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

// Create catalog
const catalog = new Catalog({
  title: 'Summer Collection'
})

// Create products
const product = new Product({
  title: 'Beach Towel',
  catalogId: catalog.id,
  amount: 2499
})
```