Skip to Content
LYNKORIADocs
SDK reference

Client SDK reference

Exports of @lynkoria/client 0.1.0, generated from its type declarations.

Package @lynkoria/client, version 0.1.0. Browsers (and React Native through @lynkoria/react-native). Uses only short-lived user tokens.

Generated from the package's bundled type declarations; every signature below is what your editor sees. For how to use it, read the guide.

Functions

createLynkoria

function createLynkoria(opts: LynkoriaClientOptions): {
  connect: () => void;
  disconnect: () => void;
  readonly connectionState: ConnectionState;
  onConnectionState: (l: (s: ConnectionState) => void) => () => void;
  onError: (l: (e: LynkoriaError) => void) => () => void;
  /** Every applied conversation event, in sequence order per conversation, deduplicated. */
  onMessage: (l: (e: ConversationEvent) => void) => () => void;
  onPresenceChange: (l: (p: Presence) => void) => () => void;
  onCallStateChange: (l: (e: CallSignalEvent) => void) => () => void;
  onTyping: (l: (e: TypingEvent & {
    typing: boolean;
  }) => void) => () => void;
  onRead: (l: (e: ConversationReadEvent) => void) => () => void;
  onConversationUpdated: (l: (e: ConversationUpdatedEvent) => void) => () => void;
  ids: {
    create(): string;
  };
  conversations: {
    list: (params?: {
      limit?: number;
      cursor?: string;
    }) => Promise<{
      items: {
        id: string;
        tenantId: string;
        type: "channel" | "dm" | "group" | "session";
        productConversationId: string | null;
        title: string | null;
        lastSeq: number;
        lastMessageAt: string | null;
        createdAt: string;
        readSeq?: number | undefined;
      }[];
      nextCursor: string | null;
    }>;
    /** Start realtime ordering for a conversation from a known seq (e.g. after loading history). */
    track: (conversationId: string, lastSeq: number) => void;
    untrack: (conversationId: string) => void;
    resync: (conversationId: string) => Promise<void>;
  };
  messages: {
    /** Latest history page (or older, with `beforeSeq`). Also starts tracking the conversation. */
    history(conversationId: string, params?: {
      beforeSeq?: number;
      limit?: number;
    }): Promise<ConversationEventPage>;
    send(input: IdempotentSend): Promise<Message>;
    edit: (messageId: string, text: string) => Promise<{
      id: string;
      conversationId: string;
      seq: number;
      senderId: string;
      clientMessageId: string;
      kind: "system" | "text";
      body: string | null;
      attachments: {
        id: string;
        fileName: string;
        mediaType: string;
        size: number;
        status: "pending" | "ready" | "rejected";
        scanStatus?: "clean" | "failed" | "infected" | "not_scanned" | "pending" | "rejected" | undefined;
      }[];
      reactions: {
        userId: string;
        emoji: string;
      }[];
      parentMessageId: string | null;
      createdAt: string;
      editedAt: string | null;
      deletedAt: string | null;
    }>;
    delete: (messageId: string) => Promise<void>;
    react: (messageId: string, emoji: string) => Promise<void>;
    unreact: (messageId: string, emoji: string) => Promise<void>;
    markRead: (conversationId: string, seq: number) => Promise<{
      readSeq: number;
    }>;
  };
  presence: {
    /** Subscribe to one user's presence; returns an unsubscribe function. */
    subscribe(userId: string, listener: (p: Presence) => void): () => void;
    get: (userId: string) => Promise<{
      userId: string;
      status: "away" | "busy" | "dnd" | "offline" | "online";
      lastSeenAt: string | null;
    }>;
    setStatus: (status: ManualStatus) => Promise<null>;
  };
  typing: {
    /** Throttled to one event per 3 s per conversation. */
    start(conversationId: string): void;
    stop(conversationId: string): void;
  };
  attachments: {
    /** Presigned direct upload; large files never pass through the socket server. */
    upload(conversationId: string, file: Blob, fileName: string): Promise<Attachment>;
    downloadUrl: (attachmentId: string) => Promise<{
      url: string;
      expiresAt: string;
    }>;
  };
  calls: {
    join: (options: JoinCallOptions) => Promise<CallSession>;
  };
  /** Device push registration for native apps (React Native uses this client for messaging). */
  push: {
    /** Call on every FCM/APNs/PushKit token refresh; idempotent. */
    register: (input: {
      provider: PushProvider;
      token: string;
      appId: string;
      apnsEnvironment?: 'sandbox' | 'production';
    }) => Promise<{
      id: string;
      deviceId: string;
      platform: "android" | "ios";
      provider: "apns" | "apns_voip" | "fcm";
      appId: string;
      updatedAt: string;
    }>;
    /** Call on sign-out so this device stops receiving the user's pushes. */
    unregister: (provider?: PushProvider) => Promise<void>;
    preferences: () => Promise<{
      calls: boolean;
      messages: boolean;
    }>;
    setPreferences: (prefs: NotificationPreferences) => Promise<void>;
  };
};

jwtExpiry

Reads exp from a JWT without verifying it (verification happens on the server).

function jwtExpiry(token: string): number | null;

Classes

SequenceTracker

Tracks the last applied conversation sequence number (plan §9.2 step 7). An event with seq > last + 1 means realtime delivery dropped something: resync with after_seq = last.

class SequenceTracker {
  private readonly last;
  get(conversationId: string): number | undefined;
  /** Set the baseline, e.g. after loading history. Never moves backwards. */
  set(conversationId: string, seq: number): void;
  conversations(): string[];
  forget(conversationId: string): void;
  decide(conversationId: string, seq: number): SequenceDecision;
}

Types

CallConnectionState

type CallConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected';

CallDeviceKind

type CallDeviceKind = 'audioinput' | 'audiooutput' | 'videoinput';

CallParticipant

A snapshot of one participant, local or remote.

type CallParticipant = {
  /** Lynkoria media identity: `project:user:device`. */
  identity: string;
  name: string;
  isLocal: boolean;
  isMicrophoneEnabled: boolean;
  isCameraEnabled: boolean;
  isScreenShareEnabled: boolean;
  isSpeaking: boolean;
  connectionQuality: ConnectionQuality;
};

CallSession

type CallSession = {
  /** The underlying LiveKit room, for rendering with @livekit/components-react or custom UI. */
  readonly room: Room;
  readonly state: CallConnectionState;
  setMicrophoneEnabled(enabled: boolean): Promise<void>;
  setCameraEnabled(enabled: boolean): Promise<void>;
  startScreenShare(): Promise<void>;
  stopScreenShare(): Promise<void>;
  onStateChange(listener: (state: CallConnectionState) => void): () => void;
  /** Local participant first, then remote participants in join order. */
  readonly participants: CallParticipant[];
  /** Fires on joins, leaves, mute/camera/screen changes, active speakers and connection quality. */
  onParticipantsChange(listener: (participants: CallParticipant[]) => void): () => void;
  /** Available devices of a kind (asks for permission first if labels are hidden). */
  listDevices(kind: CallDeviceKind): Promise<MediaDeviceInfo[]>;
  /** Switches the active microphone, camera or speaker for this call. */
  switchDevice(kind: CallDeviceKind, deviceId: string): Promise<void>;
  leave(): Promise<void>;
};

ConnectionQuality

type ConnectionQuality = 'excellent' | 'good' | 'poor' | 'lost' | 'unknown';

ConnectionState

type ConnectionState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected';

JoinCallOptions

type JoinCallOptions = {
  /** Calls your product backend, which authorizes the user and asks Lynkoria for a join token. */
  getJoinToken: () => Promise<{
    url: string;
    token: string;
  }>;
  roomOptions?: RoomOptions;
  connectOptions?: RoomConnectOptions;
};

LynkoriaClient

type LynkoriaClient = ReturnType<typeof createLynkoria>;

LynkoriaClientOptions

type LynkoriaClientOptions = {
  /** e.g. https://api.lynkoria.com */
  baseUrl: string;
  /** Calls your product backend, which mints a Lynkoria messaging token with its service key. */
  getMessagingToken: () => Promise<TokenResult>;
  /** Injectable platform adapters (React Native: no `window`, maybe no `crypto.randomUUID`). */
  ids?: {
    create(): string;
  };
  fetch?: typeof fetch;
  socketPath?: string;
  heartbeatMs?: number;
};

SequenceDecision

type SequenceDecision = 'apply' | 'duplicate' | 'gap';

Re-exported

Also exported from this package: ErrorCode (from @lynkoria/contracts), LynkoriaError (from @lynkoria/contracts).

  • export type * from "@lynkoria/contracts"

On this page