@colixsystems/widget-sdk 0.219.1 → 0.220.0

package/README.md

@@ -23,6 +23,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, photoUrl, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope. `photoUrl` is the user's own profile photo as an absolute URL, or `null`. |
 | **CORE** | `useUserPhoto()` | `{ url, canEdit, upload, remove, uploading, error }` | `ctx.user` + the optional `ctx.account` — no scope. Changes the signed-in user's OWN profile photo. `canEdit` is false when nobody is signed in or the host cannot change it; `upload` / `remove` then reject. |
+| **CORE** | `useAnonymousAccount()` | `{ supported, canCreate, creating, error, create }` | The optional `ctx.account.anonymous` — no scope. Offers an account with a generated login code and password and no email. `create()` opens the app's own dialog, which confirms, creates the account, shows the pair once and signs the visitor in; the widget never receives the pair and `create()` resolves `{ created: true }`. `supported` is false where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview and for a badge counter; `canCreate` is false while someone is signed in. |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
 | **CORE** | `useFilePreview(file)` | `{ uri }` | No scope. A temporary address an `<Image>` can show for a file the person picked but has not uploaded yet (a photo in a composer). Native picks use their own uri; on the web the SDK creates and releases an object URL, which widgets may not do themselves. `uri` is null for no file. |
 | **CORE** | `usePageBadge(count)` | `{ supported }` | `ctx.navigation.setBadge` — no scope. Puts `count` on the menu entry or tab of the page the widget is on (a chat's unread messages). The host sums the page's widgets and keeps the last count after the widget leaves the screen, until it reports again; `0` clears this widget's share. `supported` is false where the host draws no page badges (the Builder canvas). |
@@ -83,7 +84,50 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.219.1` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.220.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.220.0 (contract 1.176.0)
+
+**An app can let a visitor continue without an email — `useAnonymousAccount()`.** Some apps must let a person act without identifying themselves and still come back later: someone files a report and returns to follow it. The new hook lets a widget offer an account that has no email address. The server generates a login code and a password, and the visitor signs in again later with that pair on the app's sign-in screen ("Sign in with a login code").
+
+```jsx
+import { useAnonymousAccount, useUser, Button, Text, View } from "@colixsystems/widget-sdk";
+
+export default function ContinueWithoutEmail() {
+  const user = useUser();
+  const { supported, canCreate, creating, error, create } = useAnonymousAccount();
+
+  if (!supported) {
+    return <Text>Continuing without an email is not available here.</Text>;
+  }
+  if (user.id) {
+    return <Text>You are signed in.</Text>;
+  }
+  if (!canCreate) return null;
+
+  return (
+    <View>
+      <Button
+        title="Continue without an email"
+        disabled={creating}
+        onPress={() => create().catch(() => {})}
+      />
+      {error && error.code !== "CANCELLED" ? (
+        <Text>Could not create the account. Try again.</Text>
+      ) : null}
+    </View>
+  );
+}
+```
+
+- **The widget only asks; the app does the rest.** `create()` takes no arguments and opens the app's own dialog. It asks the visitor to confirm, shows the captcha notice when a captcha will run, creates the account, shows the login code and password once with the warning that a lost password cannot be recovered, and signs the visitor in when they confirm they saved them (or opens the sign-in screen's two-factor step when the workspace requires one). Do not build a confirmation, a captcha notice or a credentials screen of your own.
+- **The widget never receives the login code or the password.** `create()` resolves `{ created: true }` and nothing else. Widgets on a page share one context, so a credential that cannot be reset is kept out of it altogether. This is a contract boundary, not a sandbox: the SDK never hands the pair to a widget, but every widget on a page still runs inside the app.
+- **Call `create()` from a user action.** A button's `onPress`, never on mount or in an effect. Nothing is created until the visitor confirms in the dialog.
+- **Failures carry a `code`.** `create()` rejects with an Error whose `code` is the server's refusal (`ANONYMOUS_ACCOUNT_LIMIT_REACHED`, `RATE_LIMITED`, `CAPTCHA_FAILED`, …), `CAPTCHA_UNAVAILABLE` when the captcha could not run (there is no fallback), `ALREADY_SIGNED_IN`, `CANCELLED` when the visitor closes the dialog, or `UNSUPPORTED`. The dialog shows a failure itself and lets the visitor retry, so a rejection means they gave up; treat `CANCELLED` as no error. `error` holds the last one.
+- **`supported` and `canCreate`.** `supported` is false where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview and for a badge counter: render a visible "not available" state. `canCreate` is false while someone is signed in. The hook never throws at render and needs no scope.
+- **What the account can do.** It is not treated as a signed-in member: it gets only what the workspace grants to everyone or to the group chosen for these accounts, plus the records it owns. `useUser().email` is `null` for it.
+
+A host backs the hook with the new optional `WidgetContext.account.anonymous` member, `{ canCreate, create() }`. `account`'s photo actions are now optional members, so a host may publish `account` with either or both. Additive.
 
 ### What's new in 0.219.1
 

package/dist/contract.cjs

@@ -938,6 +938,38 @@ const HOOKS = [
     requiredContextSlice: ["user", "account.setPhoto", "account.removePhoto"],
     scopes: null,
   },
+  {
+    name: "useAnonymousAccount",
+    signature: "useAnonymousAccount()",
+    description:
+      "Offer an account that needs NO email address: the server generates a login code and a password, and the person signs in " +
+      "later with that pair on the app's sign-in screen. For apps where a visitor must be able to act without identifying " +
+      "themselves and still come back (a whistleblower report). The widget ONLY ASKS: create() takes NO arguments and opens the APP'S " +
+      "OWN dialog, which asks the visitor to confirm, runs the captcha, creates the account, shows the login code and password " +
+      "ONCE with the warning that a lost password cannot be recovered, and signs the visitor in when they confirm they saved " +
+      "them (or opens the sign-in screen's two-factor step when the workspace requires one). The widget NEVER receives the " +
+      "login code or the password: create() resolves { created: true } and nothing else. Do NOT build your own confirmation, " +
+      "captcha notice or credentials screen, and never call an endpoint yourself. Call create() from a user action (a button's " +
+      "onPress), never on mount or in an effect. It rejects with an Error carrying code: the server's refusal " +
+      "(ANONYMOUS_ACCOUNT_LIMIT_REACHED, RATE_LIMITED, CAPTCHA_FAILED, …), CAPTCHA_UNAVAILABLE when the " +
+      "captcha could not run (there is no fallback), ALREADY_SIGNED_IN, CANCELLED when the visitor closes the dialog, or " +
+      "UNSUPPORTED. The dialog already shows a failure and lets the visitor retry, so a rejection means they gave up: treat " +
+      "CANCELLED as no error. supported is false — and create() rejects with UNSUPPORTED instead of the hook throwing at " +
+      "render — where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview pane, in a draft " +
+      "preview and for a badge counter: render a visible 'not available' state then. canCreate is false while someone is " +
+      "signed in: hide the button then. After create() resolves the visitor is signed in and the page re-renders, so read " +
+      "useUser() for the new state. Needs no scope. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      supported: "boolean  // the host offers anonymous accounts here",
+      canCreate: "boolean  // supported AND nobody is signed in",
+      creating: "boolean  // a create() call is in flight: the app's dialog is open",
+      error: "(Error & { code?: string, status?: number }) | null  // the last create() failure; cleared by the next attempt",
+      create:
+        "() => Promise<{ created: true }>  // takes no arguments; opens the app's dialog; never returns the login code or password",
+    },
+    requiredContextSlice: ["account.anonymous"],
+    scopes: null,
+  },
   {
     name: "useFill",
     signature: "useFill()",
@@ -3565,26 +3597,31 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
     required: true,
     fields: {
       id: "string",
-      email: "string",
+      email: "string | null",
       displayName: "string",
       photoUrl: "string | null",
     },
   },
-  // Optional so a host that cannot change the photo needs no stub:
-  // useUserPhoto() reports canEdit false when it is absent.
+  // Optional, and so is every member: a host publishes only what it can do.
   account: {
     description:
-      "Optional self-service account actions for the signed-in user: " +
-      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> }. " +
-      "Backs useUserPhoto(). The host performs the request AND updates its own session, so user.photoUrl changes for every " +
-      "widget. setPhoto takes a browser File on web and expo-file-system's File on native. Absent on a host that cannot " +
-      "change the photo (the Builder canvas preview), where useUserPhoto() degrades to canEdit: false rather than throwing.",
+      "Optional self-service account actions; every member is optional too. " +
+      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> } back useUserPhoto() and are " +
+      "present only while a user is signed in. The host performs the request AND updates its own session, so user.photoUrl " +
+      "changes for every widget. setPhoto takes a browser File on web and expo-file-system's File on native. " +
+      "anonymous backs useAnonymousAccount() and is present only where the workspace offers accounts without an email: " +
+      "{ canCreate: boolean, create() -> Promise<{ created: true }> }. create() opens the HOST'S OWN dialog: " +
+      "it asks the visitor to confirm, runs the captcha, calls the server, shows the login code and password once, and signs " +
+      "the visitor in when they confirm they saved them. The pair lives only in that dialog and never reaches the slice, a " +
+      "widget, an error or storage. " +
+      "The whole slice is absent on the Builder canvas, in the preview panes and for a badge counter, where both hooks " +
+      "degrade (canEdit: false, supported: false) rather than throwing.",
     required: false,
-    fields: { setPhoto: "function", removePhoto: "function" },
+    fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
   workspace: {
     description:
@@ -5812,7 +5849,14 @@ const CONTRACT = deepFreeze({
   //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
   //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
   //    became of the order instead of always reporting "cancelled".
-  version: "1.175.0",
+  // 1.176.0: additive (sc-10934) — `useAnonymousAccount()` asks the host to
+  //    create an account with a generated login code and password and no
+  //    email, through the new optional `ctx.account.anonymous`
+  //    (`{ canCreate, create }`). The host shows the pair in its own dialog;
+  //    a widget never receives it. `account`'s photo actions are now
+  //    optional members, and `user.email` is documented as nullable: an
+  //    account without an email has none.
+  version: "1.176.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -938,6 +938,38 @@ const HOOKS = [
     requiredContextSlice: ["user", "account.setPhoto", "account.removePhoto"],
     scopes: null,
   },
+  {
+    name: "useAnonymousAccount",
+    signature: "useAnonymousAccount()",
+    description:
+      "Offer an account that needs NO email address: the server generates a login code and a password, and the person signs in " +
+      "later with that pair on the app's sign-in screen. For apps where a visitor must be able to act without identifying " +
+      "themselves and still come back (a whistleblower report). The widget ONLY ASKS: create() takes NO arguments and opens the APP'S " +
+      "OWN dialog, which asks the visitor to confirm, runs the captcha, creates the account, shows the login code and password " +
+      "ONCE with the warning that a lost password cannot be recovered, and signs the visitor in when they confirm they saved " +
+      "them (or opens the sign-in screen's two-factor step when the workspace requires one). The widget NEVER receives the " +
+      "login code or the password: create() resolves { created: true } and nothing else. Do NOT build your own confirmation, " +
+      "captcha notice or credentials screen, and never call an endpoint yourself. Call create() from a user action (a button's " +
+      "onPress), never on mount or in an effect. It rejects with an Error carrying code: the server's refusal " +
+      "(ANONYMOUS_ACCOUNT_LIMIT_REACHED, RATE_LIMITED, CAPTCHA_FAILED, …), CAPTCHA_UNAVAILABLE when the " +
+      "captcha could not run (there is no fallback), ALREADY_SIGNED_IN, CANCELLED when the visitor closes the dialog, or " +
+      "UNSUPPORTED. The dialog already shows a failure and lets the visitor retry, so a rejection means they gave up: treat " +
+      "CANCELLED as no error. supported is false — and create() rejects with UNSUPPORTED instead of the hook throwing at " +
+      "render — where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview pane, in a draft " +
+      "preview and for a badge counter: render a visible 'not available' state then. canCreate is false while someone is " +
+      "signed in: hide the button then. After create() resolves the visitor is signed in and the page re-renders, so read " +
+      "useUser() for the new state. Needs no scope. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      supported: "boolean  // the host offers anonymous accounts here",
+      canCreate: "boolean  // supported AND nobody is signed in",
+      creating: "boolean  // a create() call is in flight: the app's dialog is open",
+      error: "(Error & { code?: string, status?: number }) | null  // the last create() failure; cleared by the next attempt",
+      create:
+        "() => Promise<{ created: true }>  // takes no arguments; opens the app's dialog; never returns the login code or password",
+    },
+    requiredContextSlice: ["account.anonymous"],
+    scopes: null,
+  },
   {
     name: "useFill",
     signature: "useFill()",
@@ -3561,26 +3593,31 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
     required: true,
     fields: {
       id: "string",
-      email: "string",
+      email: "string | null",
       displayName: "string",
       photoUrl: "string | null",
     },
   },
-  // Optional so a host that cannot change the photo needs no stub:
-  // useUserPhoto() reports canEdit false when it is absent.
+  // Optional, and so is every member: a host publishes only what it can do.
   account: {
     description:
-      "Optional self-service account actions for the signed-in user: " +
-      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> }. " +
-      "Backs useUserPhoto(). The host performs the request AND updates its own session, so user.photoUrl changes for every " +
-      "widget. setPhoto takes a browser File on web and expo-file-system's File on native. Absent on a host that cannot " +
-      "change the photo (the Builder canvas preview), where useUserPhoto() degrades to canEdit: false rather than throwing.",
+      "Optional self-service account actions; every member is optional too. " +
+      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> } back useUserPhoto() and are " +
+      "present only while a user is signed in. The host performs the request AND updates its own session, so user.photoUrl " +
+      "changes for every widget. setPhoto takes a browser File on web and expo-file-system's File on native. " +
+      "anonymous backs useAnonymousAccount() and is present only where the workspace offers accounts without an email: " +
+      "{ canCreate: boolean, create() -> Promise<{ created: true }> }. create() opens the HOST'S OWN dialog: " +
+      "it asks the visitor to confirm, runs the captcha, calls the server, shows the login code and password once, and signs " +
+      "the visitor in when they confirm they saved them. The pair lives only in that dialog and never reaches the slice, a " +
+      "widget, an error or storage. " +
+      "The whole slice is absent on the Builder canvas, in the preview panes and for a badge counter, where both hooks " +
+      "degrade (canEdit: false, supported: false) rather than throwing.",
     required: false,
-    fields: { setPhoto: "function", removePhoto: "function" },
+    fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
   workspace: {
     description:
@@ -5808,7 +5845,14 @@ const CONTRACT = deepFreeze({
   //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
   //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
   //    became of the order instead of always reporting "cancelled".
-  version: "1.175.0",
+  // 1.176.0: additive (sc-10934) — `useAnonymousAccount()` asks the host to
+  //    create an account with a generated login code and password and no
+  //    email, through the new optional `ctx.account.anonymous`
+  //    (`{ canCreate, create }`). The host shows the pair in its own dialog;
+  //    a widget never receives it. `account`'s photo actions are now
+  //    optional members, and `user.email` is documented as nullable: an
+  //    account without an email has none.
+  version: "1.176.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -391,6 +391,80 @@ export function useUserPhoto() {
   return { url, canEdit, upload, remove, uploading, error };
 }
 
+const ANONYMOUS_ACCOUNT_UNSUPPORTED =
+  "Creating an account without an email is not available here";
+
+/**
+ * Offer an account that needs no email address. The server generates a login
+ * code and a password; the person signs in later with that pair. Returns
+ * `{ supported, canCreate, creating, error, create }`.
+ *
+ * A widget only asks. `create()` takes no arguments and opens the app's own dialog
+ * (`ctx.account.anonymous`), which asks the visitor to confirm, runs the
+ * captcha, creates the account, shows the login code and password once and
+ * signs the visitor in when they confirm they saved them. The widget never
+ * receives the pair: `create()` resolves `{ created: true }`. It rejects with
+ * an Error carrying `code` — the server's refusal, `CAPTCHA_UNAVAILABLE`,
+ * `ALREADY_SIGNED_IN`, `CANCELLED` when the visitor closes the dialog, or
+ * `UNSUPPORTED`.
+ *
+ * Call `create()` from a user action (a button press), never on mount.
+ * `ctx.account.anonymous` is optional: where it is absent (the workspace has
+ * the feature off, the Builder canvas, a preview, a badge counter)
+ * `supported` is false and `create()` rejects instead of the hook throwing at
+ * render. `canCreate` is false while someone is signed in.
+ */
+export function useAnonymousAccount() {
+  const ctx = useWidgetContextOrThrow("useAnonymousAccount");
+  const member = ctx.account ? ctx.account.anonymous : null;
+  const supported = Boolean(member) && typeof member.create === "function";
+
+  const hostRef = useRef(null);
+  hostRef.current = supported ? member : null;
+  const inFlightRef = useRef(null);
+  const [creating, setCreating] = useState(false);
+  const [error, setError] = useState(null);
+
+  const create = useCallback(() => {
+    if (inFlightRef.current) return inFlightRef.current;
+    const host = hostRef.current;
+    if (!host) {
+      const err = Object.assign(new Error(ANONYMOUS_ACCOUNT_UNSUPPORTED), {
+        code: "UNSUPPORTED",
+      });
+      setError(err);
+      return Promise.reject(err);
+    }
+    setCreating(true);
+    setError(null);
+    const attempt = Promise.resolve()
+      .then(() => host.create())
+      .then(
+        () => {
+          inFlightRef.current = null;
+          setCreating(false);
+          return { created: true };
+        },
+        (err) => {
+          inFlightRef.current = null;
+          setCreating(false);
+          setError(err);
+          throw err;
+        },
+      );
+    inFlightRef.current = attempt;
+    return attempt;
+  }, []);
+
+  return {
+    supported,
+    canCreate: supported && member.canCreate === true,
+    creating,
+    error,
+    create,
+  };
+}
+
 /**
  * Returns `true` when the host has sized this widget to fill a box of
  * definite height — a widget in the section a fit-to-screen page stretches to

package/dist/index.d.ts

@@ -744,14 +744,18 @@ export interface WidgetContext<TProps = unknown> {
     groupIds: string[];
   };
   /**
-   * Optional self-service account actions backing `useUserPhoto()`. The host
-   * performs the request and updates its own session, so `user.photoUrl`
-   * changes for every widget. Absent where the photo cannot be changed (the
-   * Builder canvas preview); `useUserPhoto().canEdit` is then false.
+   * Optional self-service account actions; every member is optional too.
+   * `setPhoto` / `removePhoto` back `useUserPhoto()` and are present only
+   * while a user is signed in: the host performs the request and updates its
+   * own session, so `user.photoUrl` changes for every widget. `anonymous`
+   * backs `useAnonymousAccount()` and is present only where the workspace
+   * offers accounts without an email. The whole slice is absent on the
+   * Builder canvas, in the preview panes and for a badge counter.
    */
   account?: {
-    setPhoto(file: UserPhotoFile): Promise<{ photoUrl: string | null }>;
-    removePhoto(): Promise<{ photoUrl: null }>;
+    setPhoto?(file: UserPhotoFile): Promise<{ photoUrl: string | null }>;
+    removePhoto?(): Promise<{ photoUrl: null }>;
+    anonymous?: AnonymousAccountHost;
   };
   workspace: {
     id: string;
@@ -1947,6 +1951,59 @@ export interface UserPhotoApi {
  */
 export function useUserPhoto(): UserPhotoApi;
 
+/** A `create()` failure. `code` names the refusal. */
+export type AnonymousAccountError = Error & {
+  /**
+   * The server's refusal (`ANONYMOUS_ACCOUNT_LIMIT_REACHED`, `RATE_LIMITED`,
+   * `CAPTCHA_FAILED`, …), or `CAPTCHA_UNAVAILABLE`
+   * (the captcha could not run), `ALREADY_SIGNED_IN`, `CANCELLED` (the
+   * visitor closed the dialog) or `UNSUPPORTED`. Absent when the failure has
+   * no code.
+   */
+  code?: string;
+  /** The HTTP status of a server refusal; 0 when there was no response. */
+  status?: number;
+};
+
+/** `WidgetContext.account.anonymous`: what a host provides for `useAnonymousAccount()`. */
+export interface AnonymousAccountHost {
+  /** True only while nobody is signed in and no two-factor step is pending. */
+  canCreate: boolean;
+  /**
+   * Opens the host's own dialog, which confirms, creates the account, shows
+   * the login code and password once and signs the visitor in. The pair
+   * never leaves that dialog.
+   */
+  create(): Promise<{ created: true }>;
+}
+
+export interface AnonymousAccountApi {
+  /** False where the host does not offer accounts without an email. */
+  supported: boolean;
+  /** True when `supported` and nobody is signed in. */
+  canCreate: boolean;
+  /** True while a `create()` call is in flight: the app's dialog is open. */
+  creating: boolean;
+  /** The last `create()` failure; cleared by the next attempt. */
+  error: AnonymousAccountError | null;
+  /**
+   * Ask the app to create the account. Call it from a user action. The app
+   * shows the login code and password itself; the widget never receives
+   * them. Rejects with an `AnonymousAccountError`.
+   */
+  create(): Promise<{ created: true }>;
+}
+
+/**
+ * Offer an account that needs no email address: the server generates a
+ * login code and a password, and the person signs in later with that pair.
+ * The app confirms, shows the pair once and signs the visitor in, all in its
+ * own dialog. Never throws at render: where the host does not offer it (the
+ * workspace has it off, the Builder canvas, a preview, a badge counter)
+ * `supported` is false and `create()` rejects with `code: "UNSUPPORTED"`.
+ */
+export function useAnonymousAccount(): AnonymousAccountApi;
+
 /**
  * REQ-LAY-08 — returns `true` when the host has sized this widget to fill a
  * box of definite height (a widget in the section a fit-to-screen page

package/dist/index.js

@@ -78,6 +78,7 @@ export {
   LinkPreviewError,
   useUser,
   useUserPhoto,
+  useAnonymousAccount,
   useFill,
   useNavigation,
   useRouteParams,

package/dist/index.native.js

@@ -78,6 +78,7 @@ export {
   LinkPreviewError,
   useUser,
   useUserPhoto,
+  useAnonymousAccount,
   useFill,
   useNavigation,
   useRouteParams,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.219.1",
+  "version": "0.220.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -938,6 +938,38 @@ const HOOKS = [
     requiredContextSlice: ["user", "account.setPhoto", "account.removePhoto"],
     scopes: null,
   },
+  {
+    name: "useAnonymousAccount",
+    signature: "useAnonymousAccount()",
+    description:
+      "Offer an account that needs NO email address: the server generates a login code and a password, and the person signs in " +
+      "later with that pair on the app's sign-in screen. For apps where a visitor must be able to act without identifying " +
+      "themselves and still come back (a whistleblower report). The widget ONLY ASKS: create() takes NO arguments and opens the APP'S " +
+      "OWN dialog, which asks the visitor to confirm, runs the captcha, creates the account, shows the login code and password " +
+      "ONCE with the warning that a lost password cannot be recovered, and signs the visitor in when they confirm they saved " +
+      "them (or opens the sign-in screen's two-factor step when the workspace requires one). The widget NEVER receives the " +
+      "login code or the password: create() resolves { created: true } and nothing else. Do NOT build your own confirmation, " +
+      "captcha notice or credentials screen, and never call an endpoint yourself. Call create() from a user action (a button's " +
+      "onPress), never on mount or in an effect. It rejects with an Error carrying code: the server's refusal " +
+      "(ANONYMOUS_ACCOUNT_LIMIT_REACHED, RATE_LIMITED, CAPTCHA_FAILED, …), CAPTCHA_UNAVAILABLE when the " +
+      "captcha could not run (there is no fallback), ALREADY_SIGNED_IN, CANCELLED when the visitor closes the dialog, or " +
+      "UNSUPPORTED. The dialog already shows a failure and lets the visitor retry, so a rejection means they gave up: treat " +
+      "CANCELLED as no error. supported is false — and create() rejects with UNSUPPORTED instead of the hook throwing at " +
+      "render — where the workspace has not turned anonymous accounts on, on the Builder canvas, in a preview pane, in a draft " +
+      "preview and for a badge counter: render a visible 'not available' state then. canCreate is false while someone is " +
+      "signed in: hide the button then. After create() resolves the visitor is signed in and the page re-renders, so read " +
+      "useUser() for the new state. Needs no scope. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      supported: "boolean  // the host offers anonymous accounts here",
+      canCreate: "boolean  // supported AND nobody is signed in",
+      creating: "boolean  // a create() call is in flight: the app's dialog is open",
+      error: "(Error & { code?: string, status?: number }) | null  // the last create() failure; cleared by the next attempt",
+      create:
+        "() => Promise<{ created: true }>  // takes no arguments; opens the app's dialog; never returns the login code or password",
+    },
+    requiredContextSlice: ["account.anonymous"],
+    scopes: null,
+  },
   {
     name: "useFill",
     signature: "useFill()",
@@ -3561,26 +3593,31 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
     required: true,
     fields: {
       id: "string",
-      email: "string",
+      email: "string | null",
       displayName: "string",
       photoUrl: "string | null",
     },
   },
-  // Optional so a host that cannot change the photo needs no stub:
-  // useUserPhoto() reports canEdit false when it is absent.
+  // Optional, and so is every member: a host publishes only what it can do.
   account: {
     description:
-      "Optional self-service account actions for the signed-in user: " +
-      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> }. " +
-      "Backs useUserPhoto(). The host performs the request AND updates its own session, so user.photoUrl changes for every " +
-      "widget. setPhoto takes a browser File on web and expo-file-system's File on native. Absent on a host that cannot " +
-      "change the photo (the Builder canvas preview), where useUserPhoto() degrades to canEdit: false rather than throwing.",
+      "Optional self-service account actions; every member is optional too. " +
+      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> } back useUserPhoto() and are " +
+      "present only while a user is signed in. The host performs the request AND updates its own session, so user.photoUrl " +
+      "changes for every widget. setPhoto takes a browser File on web and expo-file-system's File on native. " +
+      "anonymous backs useAnonymousAccount() and is present only where the workspace offers accounts without an email: " +
+      "{ canCreate: boolean, create() -> Promise<{ created: true }> }. create() opens the HOST'S OWN dialog: " +
+      "it asks the visitor to confirm, runs the captcha, calls the server, shows the login code and password once, and signs " +
+      "the visitor in when they confirm they saved them. The pair lives only in that dialog and never reaches the slice, a " +
+      "widget, an error or storage. " +
+      "The whole slice is absent on the Builder canvas, in the preview panes and for a badge counter, where both hooks " +
+      "degrade (canEdit: false, supported: false) rather than throwing.",
     required: false,
-    fields: { setPhoto: "function", removePhoto: "function" },
+    fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
   workspace: {
     description:
@@ -5808,7 +5845,14 @@ const CONTRACT = deepFreeze({
   //    new `ctx.filestore.signingRounds`. `useFileSignature` also returns
   //    `hintCode` and `nameRefusal`, and its `cancel()` resolves to what
   //    became of the order instead of always reporting "cancelled".
-  version: "1.175.0",
+  // 1.176.0: additive (sc-10934) — `useAnonymousAccount()` asks the host to
+  //    create an account with a generated login code and password and no
+  //    email, through the new optional `ctx.account.anonymous`
+  //    (`{ canCreate, create }`). The host shows the pair in its own dialog;
+  //    a widget never receives it. `account`'s photo actions are now
+  //    optional members, and `user.email` is documented as nullable: an
+  //    account without an email has none.
+  version: "1.176.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,