@guinetik/primitives-ts 0.2.4 → 0.2.6

package/README.md

@@ -1,87 +1,145 @@
-# @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
-
-# The build output will be in the dist/ folder
-```
-
-## Publishing
-
-```bash
-# Publish to npm (requires authentication)
-npm publish --access public
-```
-
-## License
-
-MIT © Guinetik
+# @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
+
+# The build output will be in the dist/ folder
+```
+
+## 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

package/dist/deployment-history.types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Deployment History Types
+ * Shared between API and Admin for deployment history tracking
+ */
+/**
+ * Deployment status types
+ */
+export type DeploymentRecordStatus = 'success' | 'failed' | 'in-progress';
+/**
+ * Individual deployment record
+ */
+export interface DeploymentRecord {
+    /** Deployment timestamp (ISO 8601 string) */
+    timestamp: string;
+    /** Application name (api, admin, nginx, etc.) */
+    app: string;
+    /** Deployment status */
+    status: DeploymentRecordStatus;
+    /** User who deployed (e.g., 'system', 'guinetik', etc.) */
+    deployer: string;
+    /** Application version (if available from package.json) */
+    version?: string;
+    /** Deployment duration in seconds (if available) */
+    duration?: number;
+}
+/**
+ * Deployment history response
+ */
+export interface DeploymentHistoryResponse {
+    /** List of deployment records */
+    deployments: DeploymentRecord[];
+    /** Total number of deployments found */
+    total: number;
+}
+//# sourceMappingURL=deployment-history.types.d.ts.map

package/dist/deployment-history.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-history.types.d.ts","sourceRoot":"","sources":["../src/deployment-history.types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAElB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IAEZ,wBAAwB;IACxB,MAAM,EAAE,sBAAsB,CAAC;IAE/B,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IAEjB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,iCAAiC;IACjC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAEhC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/deployment-history.types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Deployment History Types
+ * Shared between API and Admin for deployment history tracking
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/github.types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * GitHub API Types
+ *
+ * Types for GitHub REST API integration.
+ * Based on GitHub REST API v3 documentation.
+ *
+ * @see https://docs.github.com/en/rest
+ */
+/**
+ * GitHub Repository Owner (User or Organization)
+ */
+export interface GitHubOwner {
+    login: string;
+    id: number;
+    node_id: string;
+    avatar_url: string;
+    gravatar_id: string;
+    url: string;
+    html_url: string;
+    followers_url: string;
+    following_url: string;
+    gists_url: string;
+    starred_url: string;
+    subscriptions_url: string;
+    organizations_url: string;
+    repos_url: string;
+    events_url: string;
+    received_events_url: string;
+    type: 'User' | 'Organization';
+    site_admin: boolean;
+}
+/**
+ * GitHub Repository License
+ */
+export interface GitHubLicense {
+    key: string;
+    name: string;
+    spdx_id: string;
+    url: string | null;
+    node_id: string;
+}
+/**
+ * GitHub Repository
+ *
+ * Represents a GitHub repository from the REST API.
+ * This is a proxy type - we pass through GitHub's response directly.
+ */
+export interface GitHubRepository {
+    id: number;
+    node_id: string;
+    name: string;
+    full_name: string;
+    private: boolean;
+    owner: GitHubOwner;
+    html_url: string;
+    description: string | null;
+    fork: boolean;
+    url: string;
+    forks_url: string;
+    keys_url: string;
+    collaborators_url: string;
+    teams_url: string;
+    hooks_url: string;
+    issue_events_url: string;
+    events_url: string;
+    assignees_url: string;
+    branches_url: string;
+    tags_url: string;
+    blobs_url: string;
+    git_tags_url: string;
+    git_refs_url: string;
+    trees_url: string;
+    statuses_url: string;
+    languages_url: string;
+    stargazers_url: string;
+    contributors_url: string;
+    subscribers_url: string;
+    subscription_url: string;
+    commits_url: string;
+    git_commits_url: string;
+    comments_url: string;
+    issue_comment_url: string;
+    contents_url: string;
+    compare_url: string;
+    merges_url: string;
+    archive_url: string;
+    downloads_url: string;
+    issues_url: string;
+    pulls_url: string;
+    milestones_url: string;
+    notifications_url: string;
+    labels_url: string;
+    releases_url: string;
+    deployments_url: string;
+    created_at: string;
+    updated_at: string;
+    pushed_at: string;
+    git_url: string;
+    ssh_url: string;
+    clone_url: string;
+    svn_url: string;
+    homepage: string | null;
+    size: number;
+    stargazers_count: number;
+    watchers_count: number;
+    language: string | null;
+    has_issues: boolean;
+    has_projects: boolean;
+    has_downloads: boolean;
+    has_wiki: boolean;
+    has_pages: boolean;
+    has_discussions: boolean;
+    forks_count: number;
+    mirror_url: string | null;
+    archived: boolean;
+    disabled: boolean;
+    open_issues_count: number;
+    license: GitHubLicense | null;
+    allow_forking: boolean;
+    is_template: boolean;
+    web_commit_signoff_required: boolean;
+    topics: string[];
+    visibility: 'public' | 'private' | 'internal';
+    forks: number;
+    open_issues: number;
+    watchers: number;
+    default_branch: string;
+}
+/**
+ * GitHub API Error Response
+ */
+export interface GitHubErrorResponse {
+    message: string;
+    documentation_url?: string;
+    status?: string;
+}
+/**
+ * GitHub Repositories Response
+ *
+ * Response type for GET /user/repos
+ * This is an array of repositories.
+ */
+export type GitHubRepositoriesResponse = GitHubRepository[];
+//# sourceMappingURL=github.types.d.ts.map

package/dist/github.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.types.d.ts","sourceRoot":"","sources":["../src/github.types.ts"],"names":[],"mappings":"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"}

package/dist/github.types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * GitHub API Types
+ *
+ * Types for GitHub REST API integration.
+ * Based on GitHub REST API v3 documentation.
+ *
+ * @see https://docs.github.com/en/rest
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './website.types';
 export * from './firestore.types';
 export * from './website-firestore.types';
 export * from './totp.types';
+export * from './deployment-history.types';
 export type { Security, SecurityChallengeOptions, SecurityChallengeResult } from './security.interface';
 export { SecurityLevel } from './security.interface';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,cAAc,CAAC;AAG7B,YAAY,EAAE,QAAQ,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,cAAc,CAAC;AAG7B,cAAc,4BAA4B,CAAC;AAG3C,YAAY,EAAE,QAAQ,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -36,5 +36,7 @@ __exportStar(require("./firestore.types"), exports);
 __exportStar(require("./website-firestore.types"), exports);
 // TOTP/2FA types
 __exportStar(require("./totp.types"), exports);
+// Deployment history types
+__exportStar(require("./deployment-history.types"), exports);
 var security_interface_1 = require("./security.interface");
 Object.defineProperty(exports, "SecurityLevel", { enumerable: true, get: function () { return security_interface_1.SecurityLevel; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guinetik/primitives-ts",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Shared TypeScript primitives for Guinetik projects",
   "author": "Guinetik",
   "license": "MIT",