@layers/amba-web

@layers/amba-web

Amba is the agent-native backend-as-a-service for mobile and web apps. This package is the browser SDK.

Full parity with the cross-language Amba surface: auth · collections · storage · events · push · entitlements · AI · config · flags · achievements · challenges · currencies · friends · groups · inventory · leaderboards · messaging · moderation · onboarding · referrals · reviews · roles · sessions · streaks · stores · sync · xp.

Install

npm install @layers/amba-web@1.0.1

(pnpm add and yarn add also work.)

Configure + first call

import { Amba } from "@layers/amba-web";

await Amba.configure({
  apiKey: import.meta.env.VITE_AMBA_API_KEY,
});

await Amba.auth.signInAnonymously();
await Amba.events.track("app_opened", { source: "deep_link" });

Read or write a typed collection — rows are automatically scoped to the signed-in user:

const { data: todos } = await Amba.collections.find("todos", {
  filter: Amba.collections.where.eq("done", false),
  order: [{ column: "created_at", direction: "desc" }],
  limit: 50,
});

await Amba.collections.insert("todos", {
  title: "Ship the SDK",
  done: false,
});

Schedule it daily, fetch with getToday

Schedule a content library agentically (via MCP), then read today's selection from the SDK:

// Agent-side (one-time setup via MCP)
//   amba_content_libraries_create({ project_id, name: "Daily Tips" })
//   amba_content_items_add({ project_id, library_id, items: [...] })
//   amba_content_schedules_create({
//     project_id, library_id, name: "Daily rotation",
//     schedule_type: "daily_rotation",
//   })

// In-app (every session)
const todayTip = await Amba.content.getToday("Daily Tips");
console.log(todayTip.body);

getToday(libraryName) returns the item the schedule rotated in for the current period — segment-aware where the schedule is targeted.

Streaks — define once, qualify per user action

Define a streak once via MCP (amba_streaks_create — usually from your dev shell or admin tool), then call qualify from your app on every qualifying user action:

const streak = await Amba.streaks.qualify("daily_play");

// streak.current_count     — current consecutive count
// streak.longest_count     — personal best
// streak.status            — 'active' | 'broken' | 'frozen'
// streak.freezes_remaining — unused shields (auto-granted, configurable)

If the streak hasn't been defined yet, the call throws with error.code === 'STREAK_NOT_DEFINED' — that's a config-time error, never a runtime one. Full guide: https://docs.amba.dev/streaks.

Messaging — 1:1 conversations

The full messaging surface — createConversation, getConversations, listConversations, sendMessage, listMessages, markRead — ships as SDK helpers in 1.0.3+. No REST fallback needed.

// Create a conversation. For `type: "direct"` between two users,
// the call is idempotent — calling it again returns the existing row.
const conv = await Amba.messaging.createConversation({
  participant_ids: [otherUserId],
  type: "direct",
});

// Send a message — conversation_id is a path arg, not a body field
const msg = await Amba.messaging.sendMessage(conv.id, {
  body: "hey, want to start a daily streak together?",
});

// List the user's conversations
const inbox = await Amba.messaging.getConversations();

// Page through messages in a conversation
const messages = await Amba.messaging.listMessages(conv.id, { limit: 50 });

// Mark the conversation as read once the user has scrolled it
await Amba.messaging.markRead(conv.id);

Typed errors on every endpoint: branch on error.code for USER_NOT_FOUND, INVALID_PAYLOAD, CONVERSATION_NOT_FOUND, NOT_A_PARTICIPANT. Full guide: https://docs.amba.dev/social/messaging.

Bundle size

≤30 KB gzipped for the entry point. The shared runtime loads lazily on first call.

Docs

Full reference (auth, collections, storage, push, AI, flags, …): https://docs.amba.dev/sdk/web.

License

MIT