Skip to Content
🚀 Orga AI is in open beta.
DocumentationClient SDKsCoreIntroduction

Introduction

What Is the Core SDK?

@orga-ai/core is a shared internal package that provides common functionality used by all Orga AI client SDKs (@orga-ai/react, @orga-ai/react-native, and future frameworks). It’s designed to eliminate code duplication and provide a consistent foundation across framework-specific implementations.

The Core SDK provides:

  • Configuration Management: Global SDK initialization via OrgaAI.init()
  • API Communication: Sending WebRTC offers to the Orga AI realtime API (after client SDKs create them)
  • Type Definitions: Shared TypeScript types, constants, and enums
  • Utilities: Logging, media constraints, and helper functions
  • Error Handling: Standardized error classes
  • Port Interfaces: Platform abstraction interfaces (for future adapter implementations)

Primary Purpose: Shared Foundation

This package is primarily intended for internal use by client SDKs, not for direct use in applications.

Client SDKs like @orga-ai/react and @orga-ai/react-native handle:

  • WebRTC peer connection creation and management
  • Media stream handling (camera/microphone access)
  • Framework-specific hooks and components
  • Platform-specific WebRTC implementations

The Core SDK then provides the shared utilities these client SDKs use, such as:

  • Sending the WebRTC offer to the realtime API (connectToRealtime)
  • Configuration management (OrgaAI.init(), OrgaAI.getConfig())
  • Shared types and constants
  • Logging utilities

Can I Use It Directly?

While not the primary use case, you could use @orga-ai/core directly if you’re:

  • Building a custom framework adapter
  • Creating headless automation scripts
  • Implementing a non-standard integration

However, for most applications, you should use the framework-specific SDKs (@orga-ai/react or @orga-ai/react-native) which provide a complete, tested solution.

How Client SDKs Use Core

Here’s how client SDKs typically use the Core package:

  1. Initialize: Client SDK calls OrgaAI.init() with configuration
  2. Create WebRTC Connection: Client SDK creates peer connection, gathers ICE candidates
  3. Send Offer: Client SDK calls connectToRealtime() from Core to send the offer to the backend
  4. Handle Response: Client SDK processes the answer and completes WebRTC setup

Important: The Core SDK does not handle WebRTC setup—it only sends the offer after the client SDK has created it.

How It Fits Together

What Core Does NOT Do

  • ❌ WebRTC peer connection creation (handled by client SDKs)
  • ❌ Media stream management (handled by client SDKs)
  • ❌ Framework-specific hooks or components (handled by client SDKs)
  • ❌ Platform-specific WebRTC implementations (handled by client SDKs)

What Core DOES Do

  • âś… Configuration management (OrgaAI.init(), OrgaAI.getConfig())
  • âś… Sending WebRTC offers to realtime API (connectToRealtime)
  • âś… Shared types, constants, and enums
  • âś… Logging utilities
  • âś… Error classes
  • âś… Port interfaces (for future adapter implementations)

Supported Environments

  • Node.js >=18.17 (for server-side usage or testing)
  • Browsers via bundlers that respect conditional exports
  • React Native when used through @orga-ai/react-native

Dependencies

  • Minimal runtime dependencies
  • Requires bundlers that understand package exports map for conditional exports
Last updated on
OverviewArchitecture