@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

npm install @guinetik/primitives-ts

Usage

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

// Use the types in your application
const user: User = {
  uid: '123',
  email: '[email protected]',
  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

# 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

# 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:

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):

   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:

   npm run build

3. Publish to npm (requires NPM_KEY environment variable):

   # 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):

   # 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

# 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