@eka-care/ekam-types

Shared type contracts for the Ekam platform

@eka-care/ekam-types is a TypeScript-only package that defines the contracts between every part of the Ekam platform — Host, Shell, Modules, Genie, Terminology, FHIR client, and events. It contains only interfaces, types, enums, and constants. Zero runtime code. Zero JavaScript output. Zero dependencies.

Every other Ekam package imports from @eka-care/ekam-types. When a contract changes here, TypeScript breaks every consumer that doesn't conform — this is the automated enforcement mechanism.

Installation

npm install -D @eka-care/ekam-types

Usage

Import types using TypeScript's import type syntax:

import type { EkaSDK, EkamContext, EkamManifest } from '@eka-care/ekam-types';

export class MyModule implements EkamModuleInstance {
  private sdk: EkaSDK;

  constructor(sdk: EkaSDK) {
    this.sdk = sdk;
  }

  mount(container: HTMLElement): void {
    const { patient, practitioner } = this.sdk.context;
    // ...
  }

  update(context: Partial<EkamContext>): void {
    // Handle context changes
  }

  canDestroy(): boolean | string {
    return true;
  }

  destroy(): void {
    // Cleanup
  }
}

Who Uses This Package

Every Ekam package imports from @eka-care/ekam-types:

• Host (EMR): Uses EkamConfig to initialize the Shell
• Shell: Uses EkamModuleInstance, EkamManifest, SlotConfig for Module lifecycle
• Modules: Use EkaSDK, EkamContext, EkamModuleInstance for their implementation
• SDK: Uses EkaFHIRClient, EkaGenie, EkaTerminology for service contracts
• Genie: Implements EkaGenie, EkaGenieKV, EkaGenieCollection
• FHIR Client: Implements EkaFHIRClient
• Terminology: Implements EkaTerminology, TerminologyProvider

Package Structure

The package is organized into domain-specific modules:

Core Identity & Context

• workspace.ts: Workspace identity (multi-tenancy)
• context.ts: Patient, Practitioner, Organization, Auth, EkamContext
• config.ts: EkamConfig — what Host passes to Shell

Module Lifecycle

• module.ts: Module lifecycle contract (mount, update, canDestroy, destroy)

SDK Services

• sdk.ts: EkaSDK interface — what Modules receive
• fhir.ts: FHIR client types (read, search, create, update, delete)
• genie.ts: Genie storage types (KV store, collections)
• terminology.ts: Terminology provider + search types
• events.ts: FHIR lifecycle event types
• ui.ts: UI service types (toast, confirm, print, navigate)

Configuration & Manifest

• manifest.ts: Module manifest shape (eka.manifest.yaml)
• shell.ts: Zone names, slot configuration

Devtools & Runtime Extension

• devtools.ts: Contracts for runtime extension and the devtools chunk — EkamLifecycleEvents (app:mounted, app:unmounted, context:changed, sdk:created), BeforeMountTransform and BeforeMountContext (Express-style mount middleware), EkamSDKCreatedEvent, MountedAppInfo, EkamWindowGlobal (window.__ekam__), EkamDevtoolsChunk (default-export contract), EkamPersistedState (localStorage['__ekam__'] shape), and EkamDebugConfig ({ hotkey?, devtoolsUrl? }, also accepted as true shorthand on EkamConfig.debug).

The Dependency Rule

This package has:

• ✅ Zero runtime code — only type declarations
• ✅ Zero dependencies — not even React types
• ✅ Zero JavaScript output — only .d.ts files

If you need to add runtime code or dependencies, you're in the wrong package. Those belong in @ekam/sdk, @ekam/runtime, or a new package.

Versioning Policy

We follow strict semantic versioning:

• Patch (0.1.1): Documentation updates, JSDoc improvements, internal restructuring
• Minor (0.2.0): New optional fields, new interfaces, backward-compatible additions
• Major (1.0.0): Breaking changes — required fields added, fields removed, types changed

When making changes:

1. Always add new fields as optional first (minor release)
2. Deprecate old fields before removing them (minor release with deprecation notice)
3. Remove deprecated fields or change types in a major release

This ensures consumers can upgrade safely without breaking their code.

TypeScript Configuration

This package is built with:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "declaration": true,
    "emitDeclarationOnly": true,
    "strict": true
  }
}

Key setting: emitDeclarationOnly: true produces .d.ts files only, no JavaScript.

Building

npm run build      # Compile types to dist/
npm run typecheck  # Type-check without emitting files

The build output is .d.ts declaration files in dist/, typically under 50KB total.

What's NOT in v1

These will be added as the platform grows:

• Strict FHIR resource types (Patient, Observation, etc. as distinct interfaces)
• Permission enforcement types (RBAC roles, token scopes)
• Offline sync protocol types (internal to Genie)
• Module Federation types (if loading mechanism changes)
• Analytics/telemetry types
• Marketplace API types

For v1, we define the minimal types needed to get the first Module running end-to-end.

Contributing

When adding new types:

1. JSDoc everything — explain what it is, who uses it, and where it fits
2. Keep it minimal — only add types that multiple packages need
3. Start optional — new fields should be optional in v1, required in v2
4. Test consumers — verify your changes don't break existing Modules
5. Update this README — document the new types

License

Proprietary — internal Ekam platform use only.