Client and Auth

There is one deployment-pinned client per app page:

import { opencloud } from "/_opencloud/sdk.js";

The singleton owns same-origin runtime discovery, session refresh, request headers, and capability availability. It never exposes access or refresh tokens.

app.info()

app.info(): Promise<{
  id: string;
  version: string | null;
  environment: "dev" | "production";
  visibility: "public" | "private";
  capabilities: {
    auth: boolean;
    data: boolean;
    files: boolean;
    functions: boolean;
    notifications: boolean;
    realtime: boolean;
    telemetry: boolean;
  };
}>

Use capability flags to disable a feature honestly in a development preview. Do not read /_opencloud/config directly.

auth.currentUser()

Returns the current safe profile or null for a signed-out public visitor:

const user = await opencloud.auth.currentUser();
if (user) {
  renderIdentity(user.displayName ?? user.email ?? user.id);
} else {
  renderSignedOut();
}

The shape is { id, email, displayName, avatarUrl }. Private apps normally receive an admitted user because Sprout handles access at the edge.

For App Admin controls, read the platform-managed access view using the same SDK version already installed in the app:

const [access] = await opencloud.data.table("opencloud_app_access").list();
renderEditingControls(access.is_app_admin);

The view reports current app Edit permission, which also grants normal Agent conversation access. It has one read-only row and needs no migration. Re-read it when refreshing the UI. Enforce protected records with auth.is_app_admin() in RLS; hiding controls alone does not enforce permissions. System Functions, readers, and platform administrators with only review access are not App Admins. Development user A is Admin; B and C are ordinary users.

auth.requireUser()

Returns the same profile or throws OpenCloudError with code AUTH_REQUIRED and surface auth:

const user = await opencloud.auth.requireUser();

Use it before a workflow that cannot proceed anonymously. Data writes, managed file writes, private Functions, and Realtime also enforce their own auth requirements.

auth.signInUrl()

Returns a same-origin URL for a sign-in link and safely preserves the current path, query, and fragment:

signInLink.href = opencloud.auth.signInUrl();

It is synchronous and accepts no options. Sprout resolves the central Auth origin at the edge; app code never constructs or guesses an Auth URL.

dispose()

Closes Realtime subscriptions and clears cached runtime/session state. Call it when the app itself tears down; individual views should call the unsubscribe function returned by realtime.subscribe().