@unisim/sdk 0.157.0 → 0.159.0

package/dist/presence.d.ts

@@ -9,6 +9,17 @@ export interface UserCounts {
     total: number;
     /** Of those, how many beat in the last two minutes. */
     live: number;
+    /**
+     * Of `total`, how many were last seen in a browser / in an installed app.
+     *
+     * ⚠️ `web + native <= total`, and on a figure that has not turned over since
+     * 0.158.0 shipped it is a good deal less: a person whose last beat predates
+     * the platform column is in neither bucket. `null` where the split is not
+     * available at all — a database without migration 0187, or a product whose
+     * total comes from its own account counter (0185).
+     */
+    web?: number | null;
+    native?: number | null;
 }
 /** Which figure the line is showing. Not a product code — 'suite' is all of them. */
 export type CountScope = 'app' | 'suite';
@@ -17,6 +28,15 @@ export interface ProductCounts extends UserCounts {
     /** The product_code the beat was written under — 'pdf', 'fire_assess', … */
     product: string;
 }
+/**
+ * What the beat reports itself as, matching migration 0187's CHECK.
+ *
+ * ⚠️ `null` is a real answer, not a failure: it means "this install cannot say"
+ * — a Capacitor bridge that has not come up yet, or an Electron build on an OS
+ * this does not recognise. The server keeps whatever platform an earlier beat
+ * established rather than erasing it, so a single unknown beat costs nothing.
+ */
+export type DevicePlatform = 'web' | 'ios' | 'android' | 'windows' | 'macos' | 'linux';
 /** ⚠️ **Legacy, and only ever deleted now.** It used to remember whichever
  *  figure a viewer last switched the line to, which meant one tap made every
  *  app on that browser open on its own figure for ever. The line now always
@@ -25,23 +45,80 @@ export interface ProductCounts extends UserCounts {
  *  do not carry a dead key around. */
 export declare const COUNT_SCOPE_KEY = "unisim:user-count-scope";
 export declare function getInstallId(): string | null;
-/** Report this install as here now. Never throws; resolves whether it landed. */
+/**
+ * True in anything the person INSTALLED — a Capacitor container or an Electron
+ * desktop build — as opposed to a page they navigated to.
+ *
+ * This is what decides that the beat goes immediately rather than waiting for
+ * an interaction, so it deliberately errs towards "no": a browser wrongly
+ * treated as an app would put page loads back in the total, which is the whole
+ * thing this release takes out.
+ *
+ * ⚠️ Electron is read off `navigator.userAgent` and the preload bridge rather
+ * than imported from `desktop.ts`, which pulls React in — and this file has
+ * none on purpose (Universal AI is Svelte).
+ */
+export declare function isInstalledApp(): boolean;
+/**
+ * What this install reports itself as to `app_presence_beat`.
+ *
+ * ⚠️ An installed app that cannot name its OS answers `null`, NOT `'web'`.
+ * Migration 0187 keeps the platform an earlier beat established when a beat
+ * says nothing, so an unknown is a missed chance to record rather than a wrong
+ * record — and a desktop app quietly filed under "web" is the exact figure
+ * this feature exists to get right.
+ */
+export declare function devicePlatform(): DevicePlatform | null;
+/**
+ * What counts as the person doing something. A scroll and a wheel are in the
+ * list on purpose: reading a page IS using it, and a reader who never clicks
+ * is not the drive-by this gate is meant to drop.
+ */
+export declare const INTERACTION_EVENTS: readonly ["pointerdown", "keydown", "touchstart", "wheel", "scroll"];
+/** Whether this page has seen a real interaction yet. Exported for tests and
+ *  for an app that wants to hold something else back on the same rule. */
+export declare function hasInteracted(): boolean;
+/**
+ * Run `fn` on the first interaction — or straight away if one has already
+ * happened on this page. Returns a function that cancels the wait.
+ *
+ * ⚠️ The flag is module-level, so an app that restarts presence (signing in
+ * does) does not put the gate back in front of somebody who has been clicking
+ * for ten minutes.
+ */
+export declare function onFirstInteraction(fn: () => void): () => void;
+/**
+ * Report this install as here now. Never throws; resolves whether it landed.
+ */
 export declare function beatPresence(supabase: SupabaseClient, product: ProductCode): Promise<boolean>;
+export interface PresenceOptions {
+    /**
+     * Web only: hold the first beat until the person interacts with the page
+     * (see {@link INTERACTION_EVENTS}). Default **true** since 0.158.0.
+     *
+     * ⚠️ Turn it off for a surface nobody touches but everybody sees — a wall
+     * display, a kiosk, a screensaver — where "loaded it" really is the whole of
+     * the usage. It does NOT need turning off for an installed app: those never
+     * wait in the first place.
+     */
+    requireInteraction?: boolean;
+}
 /**
- * Beat now, then every {@link PRESENCE_BEAT_MS} while the page is visible, and
- * straight away when it becomes visible again. Returns a stop function.
+ * Beat now — or, on the web, at the first interaction — then every
+ * {@link PRESENCE_BEAT_MS} while the page is visible, and straight away when it
+ * becomes visible again. Returns a stop function.
  *
  * A hidden page does not beat: a backgrounded tab is not someone using the app,
  * and it drops out of "live" within two minutes on its own.
  */
-export declare function startPresence(supabase: SupabaseClient, product: ProductCode): () => void;
+export declare function startPresence(supabase: SupabaseClient, product: ProductCode, options?: PresenceOptions): () => void;
 /** The last counts this origin read for `product` (or, with 'suite', for the
  *  whole suite), or null. */
 export declare function cachedUserCounts(product: ProductCode | 'suite'): UserCounts | null;
 /**
- * Read `{ total, live }` for `product`. Waits (up to 3 s) for this page's
- * pending beat so the reader is in the figure. Resolves null on any failure —
- * the caller hides its line rather than showing a wrong number.
+ * Read `{ total, live, web, native }` for `product`. Waits (up to 3 s) for this
+ * page's pending beat so the reader is in the figure. Resolves null on any
+ * failure — the caller hides its line rather than showing a wrong number.
  */
 export declare function fetchUserCounts(supabase: SupabaseClient, product: ProductCode, scope?: CountScope): Promise<UserCounts | null>;
 /** The last breakdown this origin read, or null. Same job as
@@ -49,8 +126,9 @@ export declare function fetchUserCounts(supabase: SupabaseClient, product: Produ
  *  swaps it for the fresh one when it lands, rather than opening empty. */
 export declare function cachedUserCountsByProduct(): ProductCounts[] | null;
 /**
- * `{ product, total, live }` for every product anybody has ever opened, biggest
- * first — the breakdown behind the suite figure (migration 0184).
+ * `{ product, total, live, web, native }` for every product anybody has ever
+ * opened, biggest first — the breakdown behind the suite figure (migration
+ * 0184).
  *
  * Resolves null on any failure, exactly like {@link fetchUserCounts}, so a
  * caller shows nothing rather than a wrong number. ⚠️ **That includes an app
@@ -62,12 +140,45 @@ export declare function cachedUserCountsByProduct(): ProductCounts[] | null;
  * ⚠️ The rows do NOT sum to `fetchUserCounts(_, _, 'suite').total`: an account
  * using four apps is four rows here and one person there. Never add them up to
  * produce a total — the suite figure is the total.
+ *
+ * ⚠️ `web`/`native` are null on a row whose total comes from that app's own
+ * account counter (migration 0185, the Bipolar apps): the counter has no
+ * platform in it, so a split beside it would describe a different, smaller
+ * population than the total next to it.
  */
 export declare function fetchUserCountsByProduct(supabase: SupabaseClient): Promise<ProductCounts[] | null>;
+/** How many Universal IDs exist, and how many are in use right now (migration
+ *  0188). Anonymous guest sessions are not IDs and are not in either figure. */
+export interface UniversalIdCounts {
+    created: number;
+    live: number;
+}
+/** The last Universal ID counts this origin read, or null. */
+export declare function cachedUniversalIdCounts(): UniversalIdCounts | null;
+/**
+ * `{ created, live }` for Universal IDs — the row at the top of the breakdown
+ * (James, 2026-09-27). Resolves null on any failure, including a database
+ * without migration 0188, so the popup leaves the row out rather than showing
+ * a wrong number.
+ */
+export declare function fetchUniversalIdCounts(supabase: SupabaseClient): Promise<UniversalIdCounts | null>;
+/** "52 created", "2 live" — the Universal IDs row's figures, as separate
+ *  phrases for the same reason as {@link userCountParts}. */
+export declare function universalIdParts(language: string | null | undefined, counts: UniversalIdCounts): string[];
 /**
  * "There are 1,234 total users (5 live)" — or, for the 'suite' scope, "There
  * are a total of 1,234 users across all UNI·SIM apps (5 live)" — in `language`,
  * with the numbers grouped the way that language groups them.
  */
 export declare function formatUserCounts(language: string | null | undefined, counts: UserCounts, scope?: CountScope): string;
+/**
+ * The figures behind one row of the breakdown, as separate phrases — "1,234
+ * users", "900 web", "334 native", "5 live" — so the caller can lay them out
+ * and let them WRAP rather than measuring a single string (James, 2026-09-21:
+ * "show web | native | live if there's enough space").
+ *
+ * The split is left out entirely when it is not available, rather than shown as
+ * "0 web · 0 native": see {@link UserCounts.web}.
+ */
+export declare function userCountParts(language: string | null | undefined, counts: UserCounts): string[];
 //# sourceMappingURL=presence.d.ts.map

package/dist/presence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAG7C,yDAAyD;AACzD,eAAO,MAAM,cAAc,sBAAsB,CAAA;AAEjD,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAA;CACb;AAED,qFAAqF;AACrF,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,CAAA;AAExC,+EAA+E;AAC/E,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;sCAKsC;AACtC,eAAO,MAAM,eAAe,4BAA4B,CAAA;AA4BxD,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAY5C;AAeD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAe7F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,IAAI,CAYxF;AAED;6BAC6B;AAC7B,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,GAAG,UAAU,GAAG,IAAI,CASlF;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,WAAW,EACpB,KAAK,GAAE,UAAkB,GACxB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAuB5B;AAED;;2EAE2E;AAC3E,wBAAgB,yBAAyB,IAAI,aAAa,EAAE,GAAG,IAAI,CAQlE;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAwBjC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,MAAM,EAAE,UAAU,EAClB,KAAK,GAAE,UAAkB,GACxB,MAAM,CAUR"}
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"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"}