Initial commit

src/types/collection.ts

@@ -0,0 +1,158 @@
+/**
+ * Collection-related type definitions for Chrono Manager
+ */
+
+import type { ListFilter, ListSort, SourceSelector } from "./common";
+
+/**
+ * Permission settings for a collection
+ */
+export interface CollectionPermissionInterface {
+  view: boolean;
+  create: boolean;
+  modify: boolean;
+  destroy: boolean;
+  share: boolean;
+}
+
+/**
+ * Permissions settings for multiple users in a collection
+ */
+export interface CollectionPermissionsInterface {
+  [userId: string]: CollectionPermissionInterface;
+}
+
+/**
+ * Content type settings for a collection
+ */
+export interface CollectionContentsInterface {
+  event?: boolean;
+  task?: boolean;
+  journal?: boolean;
+  [contentType: string]: boolean | undefined;
+}
+
+/**
+ * Represents a collection (calendar) within a service
+ */
+export interface CollectionInterface {
+  '@type': string;
+  provider: string | null;
+  service: string | null;
+  in: number | string | null;
+  id: number | string | null;
+  label: string | null;
+  description: string | null;
+  priority: number | null;
+  visibility: string | null;
+  color: string | null;
+  enabled: boolean;
+  signature: string | null;
+  permissions: CollectionPermissionsInterface;
+  contents: CollectionContentsInterface;
+}
+
+/**
+ * Request to collection list endpoint
+ */
+export interface CollectionListRequest {
+  sources?: SourceSelector;
+  filter?: ListFilter;
+  sort?: ListSort;
+  uid?: string;
+}
+
+/**
+ * Response from collection list endpoint
+ */
+export interface CollectionListResponse {
+  [providerId: string]: {
+    [serviceId: string]: {
+      [collectionId: string]: CollectionInterface;
+    };
+  };
+}
+
+/**
+ * Request to collection extant endpoint
+ */
+export interface CollectionExtantRequest {
+  sources: SourceSelector;
+  uid?: string;
+}
+
+/**
+ * Response from collection extant endpoint
+ */
+export interface CollectionExtantResponse {
+  [providerId: string]: {
+    [serviceId: string]: {
+      [collectionId: string]: boolean;
+    };
+  };
+}
+
+/**
+ * Request to collection fetch endpoint
+ */
+export interface CollectionFetchRequest {
+  provider: string;
+  service: string;
+  identifier: string | number;
+  uid?: string;
+}
+
+/**
+ * Response from collection fetch endpoint
+ */
+export interface CollectionFetchResponse extends CollectionInterface {}
+
+/**
+ * Request to collection create endpoint
+ */
+export interface CollectionCreateRequest {
+  provider: string;
+  service: string;
+  data: CollectionInterface;
+  options?: (string)[]
+  uid?: string;
+}
+
+/**
+ * Response from collection create endpoint
+ */
+export interface CollectionCreateResponse  extends CollectionInterface {}
+
+/**
+ * Request to collection modify endpoint
+ */
+export interface CollectionModifyRequest {
+  provider: string;
+  service: string;
+  identifier: string | number;
+  data: CollectionInterface;
+  uid?: string;
+}
+
+/**
+ * Response from collection modify endpoint
+ */
+export interface CollectionModifyResponse  extends CollectionInterface {}
+
+/**
+ * Request to collection destroy endpoint
+ */
+export interface CollectionDestroyRequest {
+  provider: string;
+  service: string;
+  identifier: string | number;
+  uid?: string;
+}
+
+
+/**
+ * Response from collection destroy endpoint
+ */
+export interface CollectionDestroyResponse {
+  success: boolean;
+}

src/types/common.ts

@@ -0,0 +1,65 @@
+/**
+ * Common types shared across Chrono Manager services
+ */
+
+import type { FilterComparisonOperator, FilterConjunctionOperator } from './service';
+
+/**
+ * Source selector structure for hierarchical resource selection
+ * Structure: Provider -> Service -> Collection -> Entity
+ * 
+ * Examples:
+ * - Simple boolean: { "local": true }
+ * - Nested services: { "system": { "personal": true, "recents": true } }
+ * - Collection IDs: { "system": { "personal": { "299": true, "176": true } } }
+ * - Entity IDs: { "system": { "personal": { "299": [1350, 1353, 5000] } } }
+ */
+export type SourceSelector = {
+  [provider: string]: boolean | ServiceSelector;
+};
+
+export type ServiceSelector = {
+  [service: string]: boolean | CollectionSelector;
+};
+
+export type CollectionSelector = {
+  [collection: string | number]: boolean | EntitySelector;
+};
+
+export type EntitySelector = (string | number)[];
+
+/**
+ * Filter condition for building complex queries
+ */
+export interface FilterCondition {
+  attribute: string;
+  value: string | number | boolean | any[];
+  comparator?: FilterComparisonOperator;
+  conjunction?: FilterConjunctionOperator;
+}
+
+/**
+ * Filter criteria for list operations
+ * Can be simple key-value pairs or complex filter conditions
+ */
+export interface ListFilter {
+  label?: string;
+  [key: string]: any;
+}
+
+/**
+ * Sort options for list operations
+ */
+export interface ListSort {
+  [key: string]: boolean;
+}
+
+/**
+ * Range specification for pagination/limiting results
+ */
+export interface ListRange {
+  type: 'tally';
+  anchor: 'absolute' | 'relative';
+  position: number;
+  tally: number;
+}

src/types/entity.ts

@@ -0,0 +1,166 @@
+import type { ListFilter, ListRange, ListSort, SourceSelector } from './common';
+import type { EventInterface } from './event';
+import type { TaskInterface } from './task';
+import type { JournalInterface } from './journal';
+
+/**
+ * Entity-related type definitions for Chrono Manager
+ */
+
+/**
+ * Represents a chrono entity (event, task, or journal)
+ */
+export interface EntityInterface {
+  '@type': string;
+  version: number;
+  in: string | number | null;
+  id: string | number | null;
+  createdOn: Date | null;
+  createdBy: string | null;
+  modifiedOn: Date | null;
+  modifiedBy: string | null;
+  signature: string | null;
+  data: EventInterface | TaskInterface | JournalInterface | null;
+}
+
+/**
+ * Request to entity list endpoint
+ */
+export interface EntityListRequest {
+  sources?: SourceSelector;
+  filter?: ListFilter;
+  sort?: ListSort;
+  range?: ListRange;
+  uid?: string;
+}
+
+/**
+ * Response from entity list endpoint
+ */
+export interface EntityListResponse {
+  [providerId: string]: {
+    [serviceId: string]: {
+      [collectionId: string]: {
+        [entityId: string]: EntityInterface;
+      };
+    };
+  };
+}
+
+/**
+ * Request to entity delta endpoint
+ */
+export interface EntityDeltaRequest {
+  sources: SourceSelector;
+  uid?: string;
+}
+
+/**
+ * Response from entity delta endpoint
+ */
+export interface EntityDeltaResponse {
+  [providerId: string]: {
+    [serviceId: string]: {
+      [collectionId: string]: {
+        signature: string;
+        created?: {
+          [entityId: string]: EntityInterface;
+        };
+        modified?: {
+          [entityId: string]: EntityInterface;
+        };
+        deleted?: string[]; // Array of deleted entity IDs
+      };
+    };
+  };
+}
+
+/**
+ * Request to entity extant endpoint
+ */
+export interface EntityExtantRequest {
+  sources: SourceSelector;
+  uid?: string;
+}
+
+/**
+ * Response from entity extant endpoint
+ */
+export interface EntityExtantResponse {
+  [providerId: string]: {
+    [serviceId: string]: {
+      [collectionId: string]: {
+        [entityId: string]: boolean;
+      };
+    };
+  };
+}
+
+/**
+ * Request to entity fetch endpoint
+ */
+export interface EntityFetchRequest {
+  provider: string;
+  service: string;
+  collection: string | number;
+  identifiers: (string | number)[];
+  uid?: string;
+}
+
+/**
+ * Response from entity fetch endpoint
+ */
+export interface EntityFetchResponse extends Record<string, EntityInterface> {}
+
+/**
+ * Request to entity create endpoint
+ */
+export interface EntityCreateRequest {
+  provider: string;
+  service: string;
+  collection: string | number;
+  data: EntityInterface;
+  options?: (string)[]
+  uid?: string;
+}
+
+/**
+ * Response from entity create endpoint
+ */
+export interface EntityCreateResponse extends EntityInterface {}
+
+/**
+ * Request to entity modify endpoint
+ */
+export interface EntityModifyRequest {
+  provider: string;
+  service: string;
+  collection: string | number;
+  identifier: string | number;
+  data: EntityInterface;
+  options?: (string)[]
+  uid?: string;
+}
+
+/**
+ * Response from entity modify endpoint
+ */
+export interface EntityModifyResponse extends EntityInterface {}
+
+/**
+ * Request to entity destroy endpoint
+ */
+export interface EntityDestroyRequest {
+  provider: string;
+  service: string;
+  collection: string | number;
+  identifier: string | number;
+  uid?: string;
+}
+
+/**
+ * Response from entity destroy endpoint
+ */
+export interface EntityDestroyResponse {
+  success: boolean;
+}

src/types/event.ts

@@ -0,0 +1,146 @@
+/**
+ * Event-related type definitions for Chrono Manager
+ */
+
+/**
+ * Physical location information
+ */
+export interface EventLocationPhysicalInterface {
+  identifier: string | null;
+  label?: string | null;
+  description?: string | null;
+  relation?: 'start' | 'end' | null;
+  timeZone?: string | null;
+}
+
+/**
+ * Virtual location information
+ */
+export interface EventLocationVirtualInterface {
+  identifier: string | null;
+  location: string;
+  label?: string | null;
+  description?: string | null;
+  relation?: string | null;
+}
+
+/**
+ * Event organizer information
+ */
+export interface EventOrganizerInterface {
+  realm: 'I' | 'E'; // I = Internal, E = External
+  address: string;
+  name?: string | null;
+}
+
+/**
+ * Event participant/attendee information
+ */
+export interface EventParticipantInterface {
+  identifier: string | null;
+  realm: 'I' | 'E'; // I = Internal, E = External
+  address: string;
+  type: 'unknown' | 'individual' | 'group' | 'resource' | 'location';
+  status: 'none' | 'accepted' | 'declined' | 'tentative' | 'delegated';
+  roles: ('owner' | 'chair' | 'attendee' | 'optional' | 'informational' | 'contact')[];
+  name?: string | null;
+  description?: string | null;
+  comment?: string | null;
+  language?: string | null;
+}
+
+/**
+ * Event notification/alarm
+ */
+export interface EventNotificationInterface {
+  identifier: string | null;
+  type: 'visual' | 'audible' | 'email';
+  pattern: 'absolute' | 'relative' | 'unknown';
+  when?: string | null; // ISO 8601 date-time string
+  anchor?: 'start' | 'end' | null;
+  offset?: string | null; // ISO 8601 duration string
+}
+
+/**
+ * Event occurrence/recurrence pattern
+ */
+export interface EventOccurrence {
+  pattern: 'absolute' | 'relative';
+  precision: 'yearly' | 'monthly' | 'weekly' | 'daily' | 'hourly' | 'minutely' | 'secondly' ;
+  interval: number;
+  iterations?: number | null;
+  concludes?: string | null; // ISO 8601 date-time string
+  scale?: string | null;
+  onDayOfWeek?: number[] | null;
+  onDayOfMonth?: number[] | null;
+  onDayOfYear?: number[] | null;
+  onWeekOfMonth?: number[] | null;
+  onWeekOfYear?: number[] | null;
+  onMonthOfYear?: number[] | null;
+  onHour?: number[] | null;
+  onMinute?: number[] | null;
+  onSecond?: number[] | null;
+  onPosition?: number[] | null;
+}
+
+/**
+ * Event mutation (exception/modification to recurring event)
+ */
+export interface EventMutation {
+  mutationId: string | null; // ISO 8601 date-time string
+  mutationTz: string | null;
+  mutationExclusion: boolean | null;
+  sequence: number | null;
+  timeZone: string | null;
+  startsOn: string | null; // ISO 8601 date-time string
+  startsTZ: string | null;
+  endsOn: string | null; // ISO 8601 date-time string
+  endsTZ: string | null;
+  duration: string | null; // ISO 8601 duration string
+  timeless: boolean | null;
+  label: string | null;
+  description: string | null;
+  locationsPhysical: Record<string, EventLocationPhysicalInterface>;
+  locationsVirtual: Record<string, EventLocationVirtualInterface>;
+  availability: 'free' | 'busy' | null;
+  priority: number | null;
+  sensitivity: 'public' | 'private' | 'secret' | null;
+  color: string | null;
+  tags: string[];
+  organizer: EventOrganizerInterface | null;
+  participants: Record<string, EventParticipantInterface>;
+  notifications: Record<string, EventNotificationInterface>;
+}
+
+/**
+ * Main event interface
+ */
+export interface EventInterface {
+  type: string;
+  version: number;
+  urid: string | null;
+  created: string | null; // ISO 8601 date-time string
+  modified: string | null; // ISO 8601 date-time string
+  sequence: number | null;
+  timeZone: string | null;
+  startsOn: string | null; // ISO 8601 date-time string
+  startsTZ: string | null;
+  endsOn: string | null; // ISO 8601 date-time string
+  endsTZ: string | null;
+  duration: string | null; // ISO 8601 duration string
+  timeless: boolean | null;
+  label: string | null;
+  description: string | null;
+  locationsPhysical: Record<string, EventLocationPhysicalInterface>;
+  locationsVirtual: Record<string, EventLocationVirtualInterface>;
+  availability: 'free' | 'busy' | null;
+  sensitivity: 'public' | 'private' | 'secret' | null;
+  priority: number | null;
+  color: string | null;
+  tags: string[];
+  organizer: EventOrganizerInterface | null;
+  participants: Record<string, EventParticipantInterface>;
+  notifications: Record<string, EventNotificationInterface>;
+  pattern: EventOccurrence | null;
+  mutations: Record<string, EventMutation>;
+}

src/types/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Central export point for all Chrono Manager types
+ */
+
+export type * from './collection';
+export type * from './common';
+export type * from './entity';
+export type * from './event';
+export type * from './task';
+export type * from './journal';
+export type * from './provider';
+export type * from './service';

src/types/journal.ts

@@ -0,0 +1,33 @@
+/**
+ * Journal-related type definitions for Chrono Manager
+ */
+
+/**
+ * Journal attachment
+ */
+export interface JournalAttachment {
+  uri: string | null;
+  type: string | null;
+  label: string | null;
+  priority: number | null;
+}
+
+/**
+ * Data for a journal entity
+ */
+export interface JournalInterface {
+  type: string;
+  version: number;
+  urid: string | null;
+  created: Date | null;
+  modified: Date | null;
+  label: string | null;
+  description: string | null;
+  content: string | null;
+  startsOn: Date | null;
+  endsOn: Date | null;
+  status: string | null; // 'draft', 'final', 'cancelled'
+  visibility: string | null; // 'public', 'private', 'confidential'
+  attachments: Record<string, JournalAttachment>;
+  tags: string[];
+}

src/types/provider.ts

@@ -0,0 +1,53 @@
+/**
+ * Provider-specific types
+ */
+import type { SourceSelector } from "./common";
+
+/**
+ * Provider capabilities
+ */
+export interface ProviderCapabilitiesInterface {
+  ServiceList?: boolean;
+  ServiceFetch?: boolean;
+  ServiceExtant?: boolean;
+  ServiceCreate?: boolean;
+  ServiceModify?: boolean;
+  ServiceDelete?: boolean;
+  [key: string]: boolean | undefined;
+}
+
+/**
+ * Provider information
+ */
+export interface ProviderInterface {
+  '@type': string;
+  id: string;
+  label: string;
+  capabilities: ProviderCapabilitiesInterface;
+}
+
+/**
+ * Request to provider list endpoint
+ */
+export interface ProviderListRequest {}
+
+/**
+ * Response from provider list endpoint
+ */
+export interface ProviderListResponse {
+  [providerId: string]: ProviderInterface;
+}
+
+/**
+ * Request to provider extant endpoint
+ */
+export interface ProviderExtantRequest {
+  sources: SourceSelector;
+}
+
+/**
+ * Response from provider extant endpoint
+ */
+export interface ProviderExtantResponse {
+  [providerId: string]: boolean;
+}

src/types/service.ts

@@ -0,0 +1,214 @@
+/**
+ * Service-related type definitions for Chrono Manager
+ */
+
+import type { ListFilter, ListSort, SourceSelector } from "./common";
+
+/**
+ * Filter comparison operators (bitmask values)
+ */
+export const FilterComparisonOperator = {
+  EQ: 1,      // Equal
+  NEQ: 2,     // Not Equal
+  GT: 4,      // Greater Than
+  LT: 8,      // Less Than
+  GTE: 16,    // Greater Than or Equal
+  LTE: 32,    // Less Than or Equal
+  IN: 64,     // In Array
+  NIN: 128,   // Not In Array
+  LIKE: 256,  // Like (pattern matching)
+  NLIKE: 512, // Not Like
+} as const;
+
+export type FilterComparisonOperator = typeof FilterComparisonOperator[keyof typeof FilterComparisonOperator];
+
+/**
+ * Filter conjunction operators
+ */
+export const FilterConjunctionOperator = {
+  NONE: '',
+  AND: 'AND',
+  OR: 'OR',
+} as const;
+
+export type FilterConjunctionOperator = typeof FilterConjunctionOperator[keyof typeof FilterConjunctionOperator];
+
+/**
+ * Filter specification format
+ * Format: "type:length:defaultComparator:supportedComparators"
+ * 
+ * Examples:
+ * - "s:200:256:771" = String field, max 200 chars, default LIKE, supports EQ|NEQ|LIKE|NLIKE
+ * - "a:10:64:192" = Array field, max 10 items, default IN, supports IN|NIN
+ * - "i:0:1:31" = Integer field, default EQ, supports EQ|NEQ|GT|LT|GTE|LTE
+ * 
+ * Type codes:
+ * - s = string
+ * - i = integer
+ * - b = boolean
+ * - a = array
+ * 
+ * Comparator values are bitmasks that can be combined
+ */
+export type FilterSpec = string;
+
+/**
+ * Parsed filter specification
+ */
+export interface ParsedFilterSpec {
+  type: 'string' | 'integer' | 'boolean' | 'array';
+  length: number;
+  defaultComparator: FilterComparisonOperator;
+  supportedComparators: FilterComparisonOperator[];
+}
+
+/**
+ * Parse a filter specification string into its components
+ * 
+ * @param spec - Filter specification string (e.g., "s:200:256:771")
+ * @returns Parsed filter specification object
+ * 
+ * @example
+ * parseFilterSpec("s:200:256:771")
+ * // Returns: {
+ * //   type: 'string',
+ * //   length: 200,
+ * //   defaultComparator: 256 (LIKE),
+ * //   supportedComparators: [1, 2, 256, 512] (EQ, NEQ, LIKE, NLIKE)
+ * // }
+ */
+export function parseFilterSpec(spec: FilterSpec): ParsedFilterSpec {
+  const [typeCode, lengthStr, defaultComparatorStr, supportedComparatorsStr] = spec.split(':');
+  
+  const typeMap: Record<string, ParsedFilterSpec['type']> = {
+    's': 'string',
+    'i': 'integer',
+    'b': 'boolean',
+    'a': 'array',
+  };
+  
+  const type = typeMap[typeCode];
+  if (!type) {
+    throw new Error(`Invalid filter type code: ${typeCode}`);
+  }
+  
+  const length = parseInt(lengthStr, 10);
+  const defaultComparator = parseInt(defaultComparatorStr, 10) as FilterComparisonOperator;
+  
+  // Parse supported comparators from bitmask
+  const supportedComparators: FilterComparisonOperator[] = [];
+  const supportedBitmask = parseInt(supportedComparatorsStr, 10);
+  
+  if (supportedBitmask !== 0) {
+    const allComparators = Object.values(FilterComparisonOperator).filter(v => typeof v === 'number') as number[];
+    for (const comparator of allComparators) {
+      if ((supportedBitmask & comparator) === comparator) {
+        supportedComparators.push(comparator as FilterComparisonOperator);
+      }
+    }
+  }
+  
+  return {
+    type,
+    length,
+    defaultComparator,
+    supportedComparators,
+  };
+}
+
+/**
+ * Capabilities available for a service
+ */
+export interface ServiceCapabilitiesInterface {
+  // Collection capabilities
+  CollectionList?: boolean;
+  CollectionListFilter?: {
+    [key: string]: FilterSpec;
+  };
+  CollectionListSort?: string[];
+  CollectionExtant?: boolean;
+  CollectionFetch?: boolean;
+  CollectionCreate?: boolean;
+  CollectionModify?: boolean;
+  CollectionDestroy?: boolean;
+  
+  // Entity capabilities
+  EntityList?: boolean;
+  EntityListFilter?: {
+    [key: string]: FilterSpec;
+  };
+  EntityListSort?: string[];
+  EntityListRange?: {
+    [rangeType: string]: string[]; // e.g., { "tally": ["absolute", "relative"] }
+  };
+  EntityDelta?: boolean;
+  EntityExtant?: boolean;
+  EntityFetch?: boolean;
+  EntityCreate?: boolean;
+  EntityModify?: boolean;
+  EntityDestroy?: boolean;
+  EntityCopy?: boolean;
+  EntityMove?: boolean;
+}
+
+/**
+ * Represents a service within a provider
+ */
+export interface ServiceInterface {
+  '@type': string;
+  provider: string;
+  id: string;
+  label: string;
+  capabilities?: ServiceCapabilitiesInterface;
+  enabled: boolean;
+}
+
+/**
+ * Request to service list endpoint
+ */
+export interface ServiceListRequest {
+  sources?: SourceSelector;
+  filter?: ListFilter;
+  sort?: ListSort;
+  uid?: string;
+}
+
+/**
+ * Response from service list endpoint
+ */
+export interface ServiceListResponse {
+  [providerId: string]: {
+    [serviceId: string]: ServiceInterface;
+  };
+}
+
+/**
+ * Request to service extant endpoint
+ */
+export interface ServiceExtantRequest {
+  sources: SourceSelector;
+  uid?: string;
+}
+
+/**
+ * Response from service extant endpoint
+ */
+export interface ServiceExtantResponse {
+  [providerId: string]: {
+    [serviceId: string]: boolean;
+  };
+}
+
+/**
+ * Request to service fetch endpoint
+ */
+export interface ServiceFetchRequest {
+  provider: string;
+  service: string;
+  uid?: string;
+}
+
+/**
+ * Response from service fetch endpoint
+ */
+export interface ServiceFetchResponse extends ServiceInterface {}

src/types/task.ts

@@ -0,0 +1,60 @@
+/**
+ * Task-related type definitions for Chrono Manager
+ */
+
+/**
+ * Task subtask information
+ */
+export interface TaskSubtask {
+  label: string | null;
+  completed: boolean;
+  priority: number | null;
+}
+
+/**
+ * Task attachment
+ */
+export interface TaskAttachment {
+  uri: string | null;
+  type: string | null;
+  label: string | null;
+  priority: number | null;
+}
+
+/**
+ * Task recurrence rule
+ */
+export interface TaskRecurrence {
+  frequency: string | null; // 'daily', 'weekly', 'monthly', 'yearly'
+  interval: number | null;
+  count: number | null;
+  until: Date | null;
+  byDay: string[] | null;
+  byMonthDay: number[] | null;
+  byMonth: number[] | null;
+}
+
+/**
+ * Data for a task entity
+ */
+export interface TaskInterface {
+  type: string;
+  version: number;
+  urid: string | null;
+  created: Date | null;
+  modified: Date | null;
+  label: string | null;
+  description: string | null;
+  startsOn: Date | null;
+  dueOn: Date | null;
+  completedOn: Date | null;
+  status: string | null; // 'needs-action', 'in-process', 'completed', 'cancelled'
+  priority: number | null;
+  progress: number | null; // 0-100 percentage
+  color: string | null;
+  recurrence: TaskRecurrence | null;
+  subtasks: Record<string, TaskSubtask>;
+  attachments: Record<string, TaskAttachment>;
+  tags: string[];
+  notes: string | null;
+}