layla-sdk

Layla SDK

Use @layla-network/sdk when building a third-party Layla mini-app that runs inside the Layla WebView and needs to call the on-device Layla host.

The packaged skill is self-contained. Use the bundled references first:

• Read references/sdk-api.md for SDK imports, method signatures, examples, exported types, mock usage, abort behavior, and error handling.
• Read references/mini-apps-overview.md for mini-app packaging, metadata, index.html versus index.url, WebView runtime expectations, and troubleshooting.

If the bundled reference appears stale and internet access is available, check the public package source or release docs for the installed package version:

• https://github.com/l3utterfly/layla-sdk
• Prefer tagged release source over the default branch when the user's project has a specific installed version.

Runtime Rules

Run SDK calls inside the Layla WebView. The host injects the React Native WebView bridge. If that bridge is unavailable, SDK requests reject with LaylaBridgeUnavailableError.

The one non-WebView environment is task.js: an optional background task script at the mini-app root that the host runs in a QuickJS runtime with the SDK already injected as a global layla instance. See "Background Tasks (task.js)" below.

Do not use this SDK as an ordinary browser HTTP client. There is no API key, base URL, or fetch endpoint to configure. The SDK sends bridge messages to the Layla host.

Layla SDK is designed to work with local LLMs running on device, so response times can be slow. When building mini-apps, prioritize streaming APIs and show appropriate loading, thinking, and progress states instead of leaving the UI idle while a request runs.

For local browser development outside Layla, use installLaylaMock(...) before the first SDK call when the app needs SDK responses during development.

Core Import

Import from the package root:

import LaylaSDK, {
  Layla,
  LaylaAbortError,
  LaylaBridgeUnavailableError,
  LaylaError,
  type ChatCompletionMessageParam,
  type LaylaChatMessage,
  type LaylaChatHistoryEntry,
  type LaylaScheduledChatMessage,
  type LaylaCharacter,
  type LaylaMemory,
  type LaylaPersona,
  type LaylaTTSVoice,
  type GenerateVoiceToFileResult,
  type ExecuteSqlResult,
  type STTSpeechRecognizedListener,
  type BackgroundAudioStatusListener,
  type BackgroundAudioTrackChangedListener,
  type BackgroundAudioFinishedListener,
  type LaylaExecutionContext,
  type ChatContextFinishedSpeakingListener,
  type ChatContextNewMessageListener,
  type ChatContextSentimentUpdateListener,
  type ChatContextStartedSpeakingListener,
  type ChatContextStartedThinkingListener,
  type SentimentValues,
  type TavernCardV2,
} from '@layla-network/sdk';