@eazo/sdk

Capability-first SDK for web apps that run both on a standard browser and inside the Eazo Mobile WebView. Write one codebase; the SDK picks the right implementation for the runtime.

Install

npm install @eazo/sdk

Quick start

// app/layout.tsx
import { EazoProvider } from "@eazo/sdk/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <EazoProvider>{children}</EazoProvider>;
}

// Any component
import { auth } from "@eazo/sdk";
import { useEazo } from "@eazo/sdk/react";

export function Header() {
  const user = useEazo((s) => s.auth.user);
  if (!user) return <button onClick={() => auth.loginWithSocial("google")}>Sign in</button>;
  return <span>Hi, {user.name}</span>;
}

API

auth

import { auth } from "@eazo/sdk";

auth.user                                   // User | null
auth.loading                                // boolean
auth.authenticated                          // boolean
auth.loginUIOpen                            // boolean (web login UI)
await auth.getToken()                       // string | null
auth.onChange((user) => { ... })            // () => void (unsubscribe)

// One-stop login — handles every runtime and idempotent if already signed in.
const user = await auth.login()             // User
await auth.login({ timeoutMs: 120_000 })    // custom timeout (default: 5 min)
auth.showLogin()                            // imperative open (no await)
auth.hideLogin()                            // imperative close (rejects pending login())

// Low-level login primitives (rarely needed; `login()` orchestrates these).
await auth.loginWithSocial("google")
await auth.loginWithEmailPassword(email, password)
await auth.loginWithEmailCode(email, code)
await auth.sendEmailCode(email)
await auth.logout()

auth.fetchSocialConnections()               // SocialConnection[]
auth.configure({ appId: "..." })        // set Eazo app id

By default the SDK reads NEXT_PUBLIC_EAZO_APP_ID from the environment. Call auth.configure({ appId }) if you need to set it explicitly.

auth.login() — unified login flow

auth.login() is the canonical way to sign a user in. It:

1. Returns the current user immediately if already authenticated (idempotent).
2. On Eazo Mobile (host advertises auth.requestLogin), delegates to the native host login UI.
3. Otherwise, shows the SDK-bundled login modal (social providers + email / code / password).

<button onClick={async () => {
  await auth.login();
  doSomethingProtected();
}}>
  Do something
</button>

It rejects with DENIED if the user cancels, or TIMEOUT after 5 minutes of inactivity (configurable via timeoutMs).

device

import { device } from "@eazo/sdk";

device.platform                             // 'web' | 'mobile'
device.locale                               // 'zh-CN' | ...
device.backendUrl                           // '' when running web-only
device.getContext()                         // full DeviceContext

share

Hand share materials (text + images) to the platform's compose surface. Inside the Eazo Mobile WebView the host opens its native compose page, AI-drafts a post from the inputs, and lets the user edit and publish; in a plain browser the SDK shows a "Continue in the Eazo app" CTA pointing to https://eazo.ai/.

import { share } from "@eazo/sdk";

await share.compose({
  text: "Made carbonara tonight — first time the egg didn't scramble.",
  images: ["data:image/jpeg;base64,..."],   // up to 4; data: or https:
  sourceAppId: "recipe-keeper",             // optional attribution
});
// → { accepted: true } in the mobile app
// → { accepted: false } on the web (download CTA shown)

share.compose throws INVALID_ARGS synchronously if neither text nor images is provided, or if more than 4 images are passed.

React integration

import { EazoProvider, useEazo } from "@eazo/sdk/react";

Rule: inside React render, read reactive state via useEazo(selector). Outside render (event handlers, effects, non-React code), read directly from auth.xxx / device.xxx.

const user = useEazo((s) => s.auth.user);
const { platform, locale } = useEazo((s) => s.device);

Server (Next.js route handler)

import { requireAuth } from "@eazo/sdk/server";

export function GET(req: NextRequest) {
  const r = requireAuth(req);
  if (!r.ok) return r.response;
  // r.user: User
}

Requires EAZO_PRIVATE_KEY in the server environment.

Testing

import { __resetSDK, __dispatchHostMessage } from "@eazo/sdk/testing";

afterEach(() => __resetSDK());

Types

interface User {
  id: string;
  email: string | null;
  name: string | null;
  avatarUrl: string | null;
}

interface DeviceContext {
  platform: "web" | "mobile";
  locale: string;
  backendUrl: string;
}

How it works

The SDK talks to the Eazo Mobile host over postMessage using the protocol documented in PROTOCOL.md. When no host responds within 1.5 seconds, the SDK falls back to web-native implementations (GenAuth for login, localStorage for session, navigator.language for locale).

App code never branches on environment — the capability API is the same on both platforms.

Environment

| Variable | Required | Used by | |---|---|---| | NEXT_PUBLIC_EAZO_APP_ID | web login | auth.loginWith* | | NEXT_PUBLIC_EAZO_API_URL | optional | default backendUrl when web-only | | EAZO_PRIVATE_KEY | server | requireAuth |