@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()
};

Concept Catalog

primitives-ts is the contract layer of the Guinetik stack. Every type below is consumed by at least two of: the NestJS API, the Vue admin panel, the Firestore migration tooling, and guinetik.com itself.

flowchart LR
  P[primitives-ts]
  P --> ID[Identity]
  P --> CO[Content]
  P --> OP[Operations]
  P --> AS[Assistant]
  P --> ST[Storage]

  ID --> ID1[auth]
  ID --> ID2[access]
  ID --> ID3[totp]
  ID --> ID4[security]

  CO --> CO1[website]
  CO --> CO2[launchpad]
  CO --> CO3[files]

  OP --> OP1[system]
  OP --> OP2[agents]
  OP --> OP3[deployments]
  OP --> OP4[github]

  AS --> AS1[chat]
  AS --> AS2[guards]

  ST --> ST1[firestore]

How the domains relate

flowchart LR
  A[auth<br/>who you are] --> B[access<br/>what you may do]
  T[totp<br/>second factor] --> A
  B --> F[FeatureKey]
  F --> C[Content]
  F --> O[Operations]
  F --> X[Assistant]
  C --> S[(firestore)]
  X --> S

Authentication proves identity, access control turns that identity into a set of FeatureKey grants, and every other domain is gated by one of those keys. The Firestore document types are the persisted shape of whatever the other domains produce.

Identity & Access

| Module | Key exports | Purpose | | --- | --- | --- | | auth.types | User, AuthResponse, LoginPayload, AuthProvider, UserProvider | Firebase-backed sign-in, email or Google | | access.types | AdminRole, FeatureKey, FEATURE_CATALOG, AdminUser, userHasFeature | Role plus per-feature grants for the admin panel | | totp.types | TotpSetupResponse, TotpVerifyRequest, TotpStatusResponse | Time-based one-time password enrolment and checks | | security.interface | Security, SecurityLevel, SecurityChallengeResult | Provider-agnostic challenge contract |

An AdminUser is an admin or a guest; a guest sees only the features explicitly granted to it. The nine grantable features are dashboard, site, runtime, files, launchpad, users, system, chat and agents.

Content

| Module | Key exports | Purpose | | --- | --- | --- | | website.types | SiteContent, SiteMetadata, SiteSections, Menu, Theme, Card | Everything guinetik.com renders | | website-firestore.types | ProjectDocument, DemoDocument, FIRESTORE_COLLECTIONS | The stored counterparts of the above | | launchpad.types | LaunchpadBoard, LaunchpadGroup, LaunchpadItem | Bookmark board grouping and layout | | file.types | FileMetadata, FileUploadResponse, FileUploadProgress | Uploads and their lifecycle |

Operations

| Module | Key exports | Purpose | | --- | --- | --- | | system.types | SystemMetrics, Container, LogEntry, NetworkStats, CommandResult | Host and Docker telemetry | | agent.types | AgentInfo, AgentStatus, AgentTask, AgentTasksResponse | Autonomous agent fleet monitoring | | deployment-history.types | DeploymentRecord, DeploymentHistoryResponse | What shipped, when, and whether it held | | github.types | GitHubRepository, GitHubOwner, GitHubLicense | The subset of the GitHub REST shape we consume |

Assistant

| Module | Key exports | Purpose | | --- | --- | --- | | chat.types | ChatSession, ChatMessage, Model, SendMessageRequest | Session-based chat with model selection | | ai-providers.types | AiProviderType, AiModel, AiProviderConfig, AiSettings | AI model provider registry, config, and per-agent model overrides | | type-guards | isChatMessage, isChatSession, isModel | Runtime validation at the API boundary |

Storage

| Module | Key exports | Purpose | | --- | --- | --- | | firestore.types | FirestoreDocument, FirestoreCollection | Base document shape every stored type extends |

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
• 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
• 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

Releases are published to the public npm registry by GitHub Actions using npm trusted publishing (OIDC) — there is no npm token to fetch or set, and npm publish is never run by hand.

1. Make and test your changes in src/, then check the consumers compile:

   npm test && npm run build
   # temporary overlay for a quick type-check; the real install replaces it later
   cp -r dist/* ../api/node_modules/@guinetik/primitives-ts/dist/ && (cd ../api && npx tsc --noEmit)

2. Cut the release from the monorepo root (bumps package.json, commits, tags primitives-v<version>, pushes branch + tag):

   .\scripts\release-primitives.ps1             # patch: 0.8.1 -> 0.8.2
   .\scripts\release-primitives.ps1 -Bump minor # 0.8.1 -> 0.9.0

3. Wait for the workflow (.github/workflows/publish-primitives.yml, about a minute) and confirm the registry has it:

   npm view @guinetik/primitives-ts version

4. Pin the new version in dependent projects (exact, no ^/~):

   cd ../api   && npm install --save-exact @guinetik/primitives-ts@<version>
   cd ../admin && npm install --save-exact @guinetik/primitives-ts@<version>
   cd ../db    && npm install --save-exact @guinetik/primitives-ts@<version>

Full details, one-time trusted-publisher setup and troubleshooting: docs/development/primitives-publishing.md.

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 - Docker build contexts are the app folders, so ../primitives does not exist there
• Simple workflow - A tag push publishes; consumers just npm install

Authentication

None. Installing the package needs no credentials (it is public), and publishing is authenticated by the GitHub Actions workflow's OIDC identity, registered on npmjs.com as the package's trusted publisher.

License

MIT © Guinetik