Phone SDK reference

This is the complete surface of the Helix Phone SDK as it ships today (v0.1.0). Each method lists its required permission scope; calls without a granted scope return null/[] rather than throwing. Methods marked mock are wired against a mocked backend until the real integration lands — see Proposed & in-progress.

Creating the SDK

import { createHelixPhoneSdk } from "@helix/phone-sdk";

const phone = createHelixPhoneSdk({
  appId: "studio.example",   // required — your manifest appId
  accessToken?: string,       // first-party/server only; omit for sandboxed apps
  manifest?: PhoneAppManifest,
  bridgeNonce?: string,       // usually read from ?helixBridgeNonce automatically
});

createHelixPhoneSdk returns an object with the namespaces below. It auto-selects the bridge or direct transport.

runtime

account

const me = await phone.account.getCurrentUser();
// { userId, username, displayName, avatarUrl, phoneNumber, bio }

permissions

storage

Per-app key–value storage. Keys match ^[a-zA-Z0-9._:-]{1,128}$; values are JSON up to 32 KB. Writes are atomic upserts. Scope: storage.app.

await phone.storage.set("draft", { caption: "gm", assetId });
const draft = await phone.storage.get<{ caption: string; assetId: string }>("draft");

notifications

Create and manage this app's notifications. Push is rate-limited to ~12/hour per app. Scope: notifications.push.

await phone.notifications.push({
  title: "Render ready",
  body: "Your postcard finished exporting.",
  deepLink: "studio.example/exports",
});

media

The player's album (photos/videos). Upload accepts a File. Scope: media.pick.

const photo = await phone.media.pickFromAlbum();
if (photo) attach(photo);

camera

Capture into the album. mock — mockCapture currently produces a placeholder asset (or copies sourceAssetId); real world/device capture is proposed. Scope: camera.capture.

wallet

Read-only balances. Scope: wallet.read.

const w = await phone.wallet.getBalance();
// w.lix.totalBalance, w.coins.balance — read-only

payments

In-app purchases priced in LIX, from the app's manifest iap catalog. Purchases are idempotent. mock — entitlements are granted but LIX isn't debited yet (see In-app purchases). Scope: payments.

const ent = await phone.payments.purchase("demo_theme_pack", {
  idempotencyKey: crypto.randomUUID(),
});

contacts

The player's contacts, backed by the Helix social graph. Scope: social.connections.read.

messages

Threads and sending, consent-gated. Scope: messages.send_with_consent.

calls

Voice calls and call logs. mock — calls are simulated until the voice API lands. Scope: voice.calls.

presence

The player's current world/instance. mock — returns a fixed world until live presence lands. Scope: presence.world.

social

Opt-in discovery profiles and swiping (the dating/meeting primitive). Swipe matching is mock. Scope: social.discovery.

feeds: helixgram & h

Because Helixgram (photo/video) and H (short posts) are first-party, the SDK exposes them directly. Both require social.discovery; Helixgram createPost/createStory also require media.pick.

phone.helixgram

page is { limit?, before? } for cursor pagination.

phone.h

ui

Native phone UI affordances. No scope required (UI-only).

lifecycle

See Runtime & the bridge for the lifecycle model.