npm package: @guinetik/primitives-ts
Description: Shared TypeScript primitives for Guinetik projects
Author: Guinetik
Latest version: 0.7.0

# @guinetik/primitives-ts

Shared TypeScript primitives for Guinetik projects.

## Overview

This package contains pure TypeScript type definitions and interfaces used across the Guinetik ecosystem. It provides a single source of truth for data contracts between frontend and backend applications.

## Features

- ✅ **Pure TypeScript** - No runtime dependencies
- ✅ **Type-safe** - Full TypeScript support with declaration files
- ✅ **Lightweight** - Minimal bundle size
- ✅ **Universal** - Works in Node.js, browsers, and other JavaScript runtimes

## Installation

```bash
npm install @guinetik/primitives-ts
```

## Usage

```typescript
import { User, SystemMetrics, Container } from '@guinetik/primitives-ts';

// Use the types in your application
const user: User = {
  uid: '123',
  email: 'user@example.com',
  displayName: 'John Doe'
};

const metrics: SystemMetrics = {
  cpu: { usage: 45.2, cores: 4, model: 'Intel Xeon' },
  memory: { used: 8, total: 16, percentage: 50 },
  disk: { used: 100, total: 500, percentage: 20 },
  uptime: 86400,
  timestamp: new Date()
};
```

## Type Categories

### Authentication (`auth.types.ts`)
- `User` - User information
- `AuthResponse` - Authentication response
- `AuthProvider` - Authentication provider types
- `UserUpdateData` - User profile update data
- `LoginPayload` - Login request payload

### System Monitoring (`system.types.ts`)
- `SystemMetrics` - System metrics (CPU, memory, disk)
- `Container` - Docker container information
- `LogEntry` - Container log entry
- `NetworkStats` - Network statistics
- `DeploymentInfo` - Deployment information
- `CommandResult` - Shell command execution result

### Website Content (`website.types.ts`)
- `SiteContent` - Full site content structure
- `SiteMetadata` - Site metadata
- `Menu`, `MenuItem` - Navigation menu
- `Theme`, `ThemeConfig` - Theme configuration
- `Card`, `Tag` - Project/demo cards with tags
- `Experiment` - CodePen experiments
- `AboutSection`, `ProjectsSection`, `DemosSection`, `ReposSection` - Content sections

## Development

```bash
# Build the package
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:cov

# The build output will be in the dist/ folder
```

## Testing

This package includes unit tests using Jest with TypeScript support.

### Test Coverage

Tests cover:
- **Type Guards** - Runtime validation for chat types, models, and request objects
- **Enum Validation** - ClaudeModel enum consistency and format checks
- **Constants** - Model tier values and chat role validation
- **Edge Cases** - Null/undefined handling, invalid types, and boundary conditions

### Running Tests

```bash
# Run all tests once
npm test

# Watch mode for test-driven development
npm run test:watch

# Generate HTML coverage report (outputs to coverage/ folder)
npm run test:cov
```

### Type Guards

The package exports runtime type guards for validating data structures:

```typescript
import {
  isChatMessage,
  isChatSession,
  isModel,
  isSendMessageRequest
} from '@guinetik/primitives-ts';

// Validate incoming data
if (isChatMessage(data)) {
  // TypeScript knows data is ChatMessage here
  console.log(data.content);
}

// Validate API requests
if (isSendMessageRequest(req.body)) {
  // Safe to use req.body as SendMessageRequest
  const { message, model } = req.body;
}
```

Available type guards:
- `isChatRole(value)` - Validates 'user' | 'assistant'
- `isChatMessage(obj)` - Validates ChatMessage interface
- `isChatSession(obj)` - Validates ChatSession interface
- `isModel(obj)` - Validates Model interface
- `isClaudeModel(value)` - Validates ClaudeModel enum values
- `isSendMessageRequest(obj)` - Validates SendMessageRequest interface
- `isCreateSessionRequest(obj)` - Validates CreateSessionRequest interface

## Publishing Workflow

### ⚠️ IMPORTANT: Never Link Locally

**DO NOT use `npm link` for local development!** Always publish to npm and install specific versions.

### Publishing Process

When you make changes to primitives:

1. **Bump the version** (automatically updates package.json and creates git tag):
   ```bash
   cd primitives
   npm version patch  # for bug fixes (0.2.5 -> 0.2.6)
   npm version minor  # for new features (0.2.5 -> 0.3.0)
   npm version major  # for breaking changes (0.2.5 -> 1.0.0)
   ```

2. **Build the package**:
   ```bash
   npm run build
   ```

3. **Publish to npm** (requires `NPM_KEY` environment variable):
   ```bash
   # The NPM_KEY is stored in Bitwarden and should be set as environment variable
   # Set it with: $env:NPM_KEY = "your-npm-access-token"
   npm publish --access public
   ```

4. **Update dependent projects** (api, admin):
   ```bash
   # In api/package.json or admin/package.json, update the version:
   # "@guinetik/primitives-ts": "0.2.6"  (use exact version, no ^ or ~)
   
   # Then install in each project
   cd ../api
   npm install
   
   cd ../admin
   npm install
   ```

### Why No Local Linking?

- **Prevents version drift** - Ensures all projects use exact versions
- **Avoids build issues** - npm link can cause TypeScript declaration file problems
- **Deployment consistency** - Production uses npm packages, dev should match
- **Simple workflow** - Publish is fast and ensures types are properly compiled

### NPM Authentication

The `NPM_KEY` environment variable contains the npm access token for publishing:
- Stored in: Bitwarden Secrets Manager
- Secret name: `NPM_KEY`
- Used by: Local development, CI/CD, and autonomous agents

```bash
# Fetch from Bitwarden (if you have access)
$env:NPM_KEY = (bws secret get NPM_KEY --output json | ConvertFrom-Json).value

# Or set manually if you have the token
$env:NPM_KEY = "npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## License

MIT © Guinetik