Plan: Migrate Shared Interfaces to @uptime.link/interfaces

Overview

Move shared type definitions from catalog_admin/ts_web/interfaces/ to the canonical ../interfaces package (@uptime.link/interfaces) to ensure consistency across all uptime.link packages.

Decisions (Resolved)

1. Check Config: Use base type + discriminated union variants (elegant, type-safe)
2. Incident Status: Create unified type in shared package, migrate both packages
3. Form Interfaces: Keep local in catalog_admin (UI-specific)
4. Versioning: Manual releases - will notify when ready to publish

---

Task 1: Add Base Types to Shared Package

File: ../interfaces/ts/data/types.ts (new)

``typescript
// Status types for monitors/services
export type TStatusType =
| 'operational'
| 'degraded'
| 'partial_outage'
| 'major_outage'
| 'maintenance'
| 'initializing'
| 'error'
| 'paused';

// Check types (discriminant values)
export type TCheckType = 'assumption' | 'function' | 'pwa' | 'pagerank';

// Status mode for monitors
export type TStatusMode = 'auto' | 'manual';

// Incident severity
export type TIncidentSeverity = 'critical' | 'major' | 'minor' | 'maintenance';

// Incident status (unified)
export type TIncidentStatus =
| 'investigating'
| 'identified'
| 'monitoring'
| 'resolved'
| 'postmortem';
`

---

Task 2: Refactor Check Interfaces with Base + Variants

File: ../interfaces/ts/data/checks/index.ts (refactor)

`typescript
import { TStatusType, TCheckType } from '../types.js';

// ============================================
// Base Interface
// ============================================

export interface ICheckBase {
id: string;
name: string;
description?: string;
enabled: boolean;
intervalMs?: number;
lastRun?: number;
lastResult?: 'success' | 'failure' | 'pending';
}

// ============================================
// Discriminated Variants
// ============================================

export interface IAssumptionCheck extends ICheckBase {
checkType: 'assumption';
assumedStatus: TStatusType;
}

export interface IFunctionCheck extends ICheckBase {
checkType: 'function';
functionUrl: string;
expectedStatusCode?: number;
timeoutMs?: number;
headers?: Record;
}

export interface IPwaCheck extends ICheckBase {
checkType: 'pwa';
targetUrl: string;
lighthouseThreshold?: number;
categories?: ('performance' | 'accessibility' | 'best-practices' | 'seo')[];
}

export interface IPageRankCheck extends ICheckBase {
checkType: 'pagerank';
targetUrl: string;
minimumRank?: number;
searchEngine?: 'google' | 'bing';
}

// ============================================
// Union Type (for UI and generic handling)
// ============================================

export type TCheck =
| IAssumptionCheck
| IFunctionCheck
| IPwaCheck
| IPageRankCheck;

// ============================================
// Check Collection
// ============================================

export interface ICheckCollection {
id: string;
name: string;
checks: TCheck[];
}
`

---

Task 3: Create Unified Incident Interface

File: ../interfaces/ts/data/incident.ts (refactor)

`typescript
import { TIncidentSeverity, TIncidentStatus } from './types.js';

export interface IIncidentUpdate {
id: string;
incidentId: string;
status: TIncidentStatus;
message: string;
createdAt: number;
createdBy?: string;
}

export interface IIncident {
id: string;
title: string;
description: string;
severity: TIncidentSeverity;
status: TIncidentStatus;

// Affected services
affectedServiceIds: string[];

// Timeline
createdAt: number;
updatedAt: number;
resolvedAt?: number;

// Updates history
updates: IIncidentUpdate[];

// Metadata
createdBy?: string;
isScheduled?: boolean;
scheduledStartTime?: number;
scheduledEndTime?: number;
}
`

---

Task 4: Add Service Status Interface

File: ../interfaces/ts/data/servicestatus.ts (new)

`typescript
import { TStatusType, TStatusMode, TCheckType } from './types.js';

export interface IServiceStatus {
id: string;
name: string;
displayName: string;
description?: string;

// Current state
currentStatus: TStatusType;
lastChecked: number;
responseTime: number;

// Uptime metrics
uptime30d: number;
uptime90d: number;

// Organization
category?: string;
dependencies?: string[];

// Status management
statusMode: TStatusMode;
manualStatus?: TStatusType;
paused: boolean;

// Check configuration (references check collection)
checkType?: TCheckType;
checkCollectionId?: string;
intervalMs?: number;
}

export interface IStatusHistoryPoint {
timestamp: number;
status: TStatusType;
responseTime?: number;
}

export interface IOverallStatus {
status: TStatusType;
message?: string;
lastUpdated: number;
}
`

---

Task 5: Add Status Page Config

File: ../interfaces/ts/data/statuspageconfig.ts (new)

`typescript
import { IOverallStatus } from './servicestatus.js';

export interface IStatusPageConfig {
id: string;
name: string;
slug: string;

// Branding
logoUrl?: string;
faviconUrl?: string;
primaryColor?: string;

// Content
headerTitle: string;
headerDescription?: string;

// Features
showHistoricalUptime: boolean;
showResponseTime: boolean;
showSubscribeButton: boolean;

// Service grouping
serviceGroups: IServiceGroup[];

// Overall status override
overallStatus?: IOverallStatus;
}

export interface IServiceGroup {
id: string;
name: string;
description?: string;
serviceIds: string[];
expanded: boolean;
}
`

---

Task 6: Update Shared Package Exports

File: ../interfaces/ts/data/index.ts (update)

`typescript
export * from './types.js';
export * from './checks/index.js';
export * from './incident.js';
export * from './servicestatus.js';
export * from './statuspageconfig.js';
// ... existing exports
`

---

Task 7: Update catalog_admin Interfaces

File: catalog_admin/ts_web/interfaces/index.ts (refactor)

`typescript
// Re-export shared types from @uptime.link/interfaces
export {
// Types
TStatusType,
TCheckType,
TStatusMode,
TIncidentSeverity,
TIncidentStatus,

// Check interfaces
ICheckBase,
IAssumptionCheck,
IFunctionCheck,
IPwaCheck,
IPageRankCheck,
TCheck,
ICheckCollection,

// Incident interfaces
IIncident,
IIncidentUpdate,

// Service/Status interfaces
IServiceStatus,
IStatusHistoryPoint,
IOverallStatus,
IStatusPageConfig,
IServiceGroup,
} from '@uptime.link/interfaces';

// ============================================
// Form Interfaces (UI-specific, kept local)
// ============================================

import type { TStatusType, TCheckType, TStatusMode, TIncidentSeverity } from '@uptime.link/interfaces';

export interface IMonitorFormData {
name: string;
displayName: string;
description?: string;
category?: string;
checkType: TCheckType;
intervalMs: number;
statusMode: TStatusMode;
paused: boolean;
// Check-specific fields (form flattens the discriminated union)
assumedStatus?: TStatusType;
functionUrl?: string;
expectedStatusCode?: number;
targetUrl?: string;
lighthouseThreshold?: number;
minimumRank?: number;
}

export interface IIncidentFormData {
title: string;
description: string;
severity: TIncidentSeverity;
affectedServiceIds: string[];
isScheduled: boolean;
scheduledStartTime?: number;
scheduledEndTime?: number;
}

export interface IIncidentUpdateFormData {
status: string;
message: string;
}
`

---

Task 8: Update Component Imports

Scan and update all components that import from local interfaces to ensure they work with the new types. Key files:

- ts_web/elements/upladmin-monitor-form/upladmin-monitor-form.ts
- ts_web/elements/upladmin-monitor-list/upladmin-monitor-list.ts
- ts_web/elements/upladmin-incident-form/upladmin-incident-form.ts
- ts_web/elements/upladmin-incident-list/upladmin-incident-list.ts
- ts_web/elements/upladmin-incident-update/upladmin-incident-update.ts

---

Task 9: Build and Test

1. Build ../interfaces: cd ../interfaces && pnpm build
2. Notify for release of @uptime.link/interfaces
3. Update dependency: pnpm update @uptime.link/interfaces
4. Build catalog_admin: pnpm build
5. Verify no type errors
6. Test UI components manually

---

Files Summary

$3


- ts/data/types.ts
- ts/data/servicestatus.ts
- ts/data/statuspageconfig.ts

$3

- ts/data/checks/index.ts (refactor to base + variants)
- ts/data/incident.ts (unified interface)
- ts/data/index.ts (add exports)

$3

- ts_web/interfaces/index.ts` (re-export from shared + local form types)
- Component files (if import paths change)