@cyber-eco/types¶

Pure TypeScript interfaces and constants shared across the entire CyberEco ecosystem. This package has zero runtime dependencies -- it exports only types, interfaces, and lightweight constants.

Installation¶

npm install @cyber-eco/types

Zero Runtime Dependencies

This package contains no runtime code beyond simple constant objects. It is safe to import anywhere -- client, server, or edge -- without adding bundle weight.

Core Interfaces¶

StorageAdapter¶

The foundational abstraction that decouples all data operations from any specific database.

import type { StorageAdapter } from '@cyber-eco/types';

interface StorageAdapter {
  getDocument<T>(collection: string, id: string): Promise<T | null>;
  setDocument<T>(collection: string, id: string, data: T, options?: WriteOptions): Promise<WriteResult>;
  updateDocument(collection: string, id: string, data: Record<string, unknown>): Promise<WriteResult>;
  deleteDocument(collection: string, id: string): Promise<WriteResult>;
  query<T>(collection: string, filters: QueryFilter[], options?: QueryOptions): Promise<PaginatedResult<T>>;
  batchWrite(operations: BatchOperation[]): Promise<BatchResult>;
  subscribe<T>(collection: string, id: string, callback: (data: T | null) => void): Unsubscribe;
  subscribeToQuery<T>(collection: string, filters: QueryFilter[], callback: (data: T[]) => void): Unsubscribe;
  serverTimestamp(): unknown;
  generateId(collection: string): string;
}

Two implementations exist:

FirebaseStorageAdapter in @cyber-eco/firebase (production)
MockStorageAdapter in @cyber-eco/services/testing (tests)

IDataLayerService¶

The high-level data layer interface used by domain services. Adds permission checking, caching, sync, and webhooks on top of StorageAdapter.

import type { IDataLayerService } from '@cyber-eco/types';

interface IDataLayerService {
  get<T>(userId: string, collection: string, id: string): Promise<T | null>;
  create<T extends Record<string, unknown>>(userId: string, collection: string, data: T): Promise<string>;
  update(userId: string, collection: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(userId: string, collection: string, id: string): Promise<void>;
  query<T>(userId: string, collection: string, filters: QueryFilter[], options?: QueryOptions): Promise<PaginatedResult<T>>;
  subscribe<T>(userId: string, collection: string, id: string, callback: (data: T | null) => void): Unsubscribe;
  batchWrite(userId: string, operations: Array<{ type: 'set' | 'update' | 'delete'; collection: string; id: string; data?: Record<string, unknown> }>): Promise<void>;
  setPermissionChecker(checker: PermissionChecker): void;
}

QueryFilter and QueryOptions¶

Types for building database queries with filtering, sorting, and pagination.

import type { QueryFilter, QueryOptions, PaginatedResult } from '@cyber-eco/types';

const filters: QueryFilter[] = [
  { field: 'status', operator: '==', value: 'active' },
  { field: 'createdAt', operator: '>=', value: '2024-01-01' },
];

const options: QueryOptions = {
  sort: [{ field: 'createdAt', direction: 'desc' }],
  limit: 25,
  offset: 0,
};

Supported operators: ==, !=, <, <=, >, >=, in, array-contains, array-contains-any

User Types¶

import type { BaseUser, HubUser, SharedUserProfile, AuthUser, AuthToken } from '@cyber-eco/types';

Type	Purpose
`BaseUser`	Minimal user fields shared across all apps
`HubUser`	Hub-specific user with preferences and settings
`SharedUserProfile`	Cross-app public profile
`AuthUser`	Authentication state (UID, email, verified status)
`AuthToken`	Token payload for JWT operations

Permission Types¶

import type { AppRole, AppPermission, ResourcePermission, PermissionCondition } from '@cyber-eco/types';

Type	Purpose
`AppRole`	Union type: `'owner' \\| 'admin' \\| 'moderator' \\| 'member'`
`AppPermission`	App-level role assignment with audit trail and conditions
`ResourcePermission`	Fine-grained resource-level access control
`PermissionCondition`	Conditional constraints (time, IP, MFA, custom)

Constants¶

ROLE_HIERARCHY¶

The 4-tier role hierarchy used across the ecosystem for permission checks.

import { ROLE_HIERARCHY, hasMinimumRole } from '@cyber-eco/types';

// ROLE_HIERARCHY values:
//   owner:     4
//   admin:     3
//   moderator: 2
//   member:    1

// Check if a user meets a minimum role requirement
hasMinimumRole('admin', 'moderator');  // true  -- admin(3) >= moderator(2)
hasMinimumRole('member', 'admin');     // false -- member(1) < admin(3)

COLLECTIONS¶

Canonical Firestore collection names used across all packages and apps.

import { COLLECTIONS } from '@cyber-eco/types';

// Available collections:
COLLECTIONS.USERS                  // 'users'
COLLECTIONS.TRANSACTIONS           // 'transactions'
COLLECTIONS.GROUPS                 // 'groups'
COLLECTIONS.NOTIFICATIONS          // 'notifications'
COLLECTIONS.PERMISSIONS            // 'permissions'
COLLECTIONS.RESOURCE_PERMISSIONS   // 'resourcePermissions'
COLLECTIONS.PERMISSION_LOGS        // 'permissionLogs'
COLLECTIONS.USER_PREFERENCES      // 'userPreferences'
COLLECTIONS.DATA_SYNC_STATUS      // 'dataSyncStatus'
COLLECTIONS.APPS                   // 'apps'
COLLECTIONS.WEBHOOK_REGISTRATIONS  // 'webhookRegistrations'
COLLECTIONS.FRIENDSHIPS            // 'friendships'

Use Constants, Not Strings

Always use COLLECTIONS.USERS instead of the string 'users'. This gives you autocomplete, refactoring safety, and a single source of truth for collection names.

Additional Types¶

Data Layer Configuration¶

import type { DataLayerConfig, PermissionChecker } from '@cyber-eco/types';

const config: DataLayerConfig = {
  adapter: myStorageAdapter,
  cache: { strategy: 'lru', maxSize: 1000, defaultTtl: 300 },
  sync: { enabled: true },
  webhooks: { enabled: false },
  permissions: { enabled: true },
};

Cache Types¶

import type { CacheBackend, CacheStrategy, CacheConfig } from '@cyber-eco/types';
import { DEFAULT_CACHE_TTLS } from '@cyber-eco/types';

Sync and Webhook Types¶

import type { SyncEvent, SyncConflict, DataSyncStatus } from '@cyber-eco/types';
import type { WebhookEvent, WebhookRegistration } from '@cyber-eco/types';

import type { NavigationLink, NavigationProps } from '@cyber-eco/types';
import { hubNavConfig, websiteNavConfig } from '@cyber-eco/types';

Domain-Specific Types¶

// Financial
import type { BankAccount, Transaction, Budget, FinancialSummary } from '@cyber-eco/types';

// Groups and relationships
import type { GroupMember, SharedGroup, UserRelationship, Friendship } from '@cyber-eco/types';

// Activity and notifications
import type { SharedActivity, ActivitySummary, Notification } from '@cyber-eco/types';

// JustSplit app types (namespaced)
import { JustSplit } from '@cyber-eco/types';

Usage Examples¶

Typing a Custom Adapter¶

import type { StorageAdapter, QueryFilter, PaginatedResult } from '@cyber-eco/types';

class PostgresStorageAdapter implements StorageAdapter {
  async getDocument<T>(collection: string, id: string): Promise<T | null> {
    const row = await this.pool.query(
      `SELECT * FROM ${collection} WHERE id = $1`,
      [id]
    );
    return row.rows[0] ?? null;
  }

  // ... implement remaining methods
}

Typing a Domain Service¶

import type { IDataLayerService, HubUser, QueryFilter } from '@cyber-eco/types';
import { COLLECTIONS } from '@cyber-eco/types';

class UserService {
  constructor(private dataLayer: IDataLayerService) {}

  async getUser(requesterId: string, userId: string): Promise<HubUser | null> {
    return this.dataLayer.get<HubUser>(requesterId, COLLECTIONS.USERS, userId);
  }

  async findActiveUsers(requesterId: string): Promise<HubUser[]> {
    const filters: QueryFilter[] = [
      { field: 'status', operator: '==', value: 'active' },
    ];
    const result = await this.dataLayer.query<HubUser>(
      requesterId,
      COLLECTIONS.USERS,
      filters,
      { sort: [{ field: 'createdAt', direction: 'desc' }], limit: 50 }
    );
    return result.data;
  }
}

Package Exports¶

All exports are type-only or lightweight constants. The full list of exports is available in the generated API Reference (run npm run docs:api to generate).

Category	Exports
User types	`BaseUser`, `HubUser`, `SharedUserProfile`, `AuthUser`, `AuthToken`
App types	`App`, `AppConfig`
Permission types	`AppRole`, `AppPermission`, `ResourcePermission`, `PermissionCondition`
Query types	`QueryOperator`, `QueryFilter`, `QuerySort`, `QueryOptions`, `PaginatedResult`
Storage types	`StorageAdapter`, `WriteOptions`, `WriteResult`, `BatchOperation`, `BatchResult`, `Unsubscribe`
Service types	`IDataLayerService`, `DataLayerConfig`, `PermissionChecker`
Cache types	`CacheBackend`, `CacheStrategy`, `CacheConfig`, `DEFAULT_CACHE_TTLS`
Sync types	`SyncEvent`, `SyncConflict`, `DataSyncStatus`
Webhook types	`WebhookEvent`, `WebhookRegistration`
Constants	`ROLE_HIERARCHY`, `hasMinimumRole`, `COLLECTIONS`, `BREAKPOINTS`, `mediaQuery`
Navigation	`NavigationLink`, `NavigationProps`, `hubNavConfig`, `websiteNavConfig`
Domain types	`GroupMember`, `SharedGroup`, `Friendship`, `Transaction`, `Budget`, `Notification`, etc.