@layers/amba-web 1.0.0

package/README.md

@@ -0,0 +1,129 @@
+# @layers/amba-web
+
+[![npm](https://img.shields.io/npm/v/@layers/amba-web?color=blue)](https://www.npmjs.com/package/@layers/amba-web)
+
+Browser SDK for [amba](https://amba.dev) — the agent-native backend-as-a-service for mobile and web apps.
+
+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**.
+
+Built on top of `@layers/amba-core-wasm` — a Rust core compiled to WebAssembly, ensuring identical behavior across web, Node, React Native, Swift, Kotlin, Flutter, and Unity SDKs.
+
+## Install
+
+```bash
+pnpm add @layers/amba-web
+# or
+npm i @layers/amba-web
+# or
+yarn add @layers/amba-web
+```
+
+## Quickstart
+
+```ts
+import { Amba } from "@layers/amba-web";
+
+// 1) configure once at app start
+await Amba.configure({
+  apiKey: import.meta.env.VITE_AMBA_API_KEY,
+});
+
+// 2) sign in (anonymous, email, or social)
+const session = await Amba.auth.signInAnonymously();
+
+// 3) track engagement
+await Amba.events.track("app_opened", { source: "deep_link" });
+
+// 4) read & write your typed collections (auto-RLS — only your user's rows)
+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,
+});
+```
+
+## API surface
+
+### Auth
+
+```ts
+await Amba.auth.signInAnonymously();
+await Amba.auth.signInWithEmail(email, password);
+await Amba.auth.signUpWithEmail(email, password);
+await Amba.auth.signInWithSocial("apple" | "google", idToken);
+await Amba.auth.signOut(/* rotateAnonymousId? */);
+await Amba.auth.refresh();
+await Amba.auth.me();
+```
+
+### Events
+
+```ts
+await Amba.events.track("signup_completed", { plan: "pro" });
+```
+
+### Collections — Mongo-style filter DSL, server-enforced RLS
+
+```ts
+const { where } = Amba.collections;
+
+await Amba.collections.find("posts", {
+  filter: where.and(where.eq("status", "published"), where.gte("score", 100)),
+  order: [{ column: "created_at", direction: "desc" }],
+  limit: 20,
+});
+```
+
+### Storage — presign → PUT → commit
+
+```ts
+const asset = await Amba.storage.upload({
+  bucket: "avatars",
+  file: fileInput.files[0],
+});
+```
+
+### Push
+
+```ts
+await Amba.push.register(pushToken, "web");
+await Amba.push.subscribe("breaking_news");
+```
+
+### Entitlements
+
+```ts
+if (await Amba.entitlements.has("pro")) {
+  showProFeature();
+}
+```
+
+### AI proxy
+
+```ts
+const reply = await Amba.ai.anthropic.messages.create({
+  prompt_slug: "support_assistant",
+  variables: { user_query: input },
+  max_tokens: 1024,
+});
+```
+
+### Config & flags
+
+```ts
+const config = await Amba.config.fetch();
+const flags = await Amba.flags.fetch();
+```
+
+## Bundle size
+
+≤30 KB gzipped for the entry point. The WASM binary (~150 KB gzipped) loads lazily on `Amba.configure()`.
+
+## License
+
+MIT.