# Alqove Packages

Shared TypeScript packages consumed by web and mobile apps. Managed via npm workspaces.

## Packages

### @alqove/types
- Generated from `api/contracts/openapi.yaml` via `openapi-typescript`
- **Never hand-edit generated.ts** — run `npm run generate` to regenerate
- Manual type additions go in `src/index.ts`
- Re-run generation whenever the OpenAPI spec changes

### @alqove/api-client
- Typed API client wrapping fetch
- Both web and mobile import this — neither writes raw fetch calls
- Consumes types from `@alqove/types`
- Auto-generates idempotency keys on mutations (Layer 1)

### @alqove/shared
- Cross-platform hooks (TanStack Query wrappers), utilities, business logic
- No platform-specific code (no React DOM, no React Native)
- Utilities: `formatPrice`, `dollarsToCents`, date formatting
- Hooks: `useItems`, `useCart`, `useCheckout` (added as features are built)

### @alqove/design-tokens
- Platform-agnostic brand values in JSON (`tokens/*.json`)
- Build script generates: `build/tailwind.js`, `build/css-variables.css`, `build/react-native.ts`
- Run `npm run build` after changing any token file
- Both platforms consume generated output, not raw JSON

### @alqove/design-system
- Documentation only — not code
- Component specs, UI patterns, voice-and-tone guidelines
- AI reads these when implementing components on any platform

## Workflow

1. Change OpenAPI spec → run `npm run build:types`
2. Change design tokens → run `npm run build:tokens`
3. Add shared utility → add to `@alqove/shared`, import in web/mobile
4. New component spec → add markdown to `@alqove/design-system`