@abloatai/humans 0.61.0 → 0.63.0

package/src/react/createAbloReact.ts

@@ -29,6 +29,7 @@ import {
 } from './AbloProvider.js';
 import {
   useAbloImpl,
+  useAbloClientImpl,
   type AbloSelector,
   type ModelClientSelector,
   type UseAbloHydratedModelResult,
@@ -38,6 +39,11 @@ import {
 import type { AbloClient as Ablo } from '../client.js';
 import type { ModelOperations } from '../local/client/createModelOperations.js';
 import type { Schema, SchemaRecord } from '@abloatai/transaction/schema/schema';
+import {
+  usePresenceImpl,
+  type PresenceModelSelector,
+} from './usePresence.js';
+import type { PresenceSession } from '@abloatai/transaction/presence';
 
 /** What a binding returns: the provider and the hook, with `S` fixed. */
 export interface AbloReactBinding<S extends SchemaRecord> {
@@ -60,6 +66,11 @@ export interface AbloReactBinding<S extends SchemaRecord> {
       options?: UseAbloModelOptions<T>,
     ): UseAbloModelResult<T>;
   };
+  /** Declare and reactively read record presence with the same model clients. */
+  usePresence: <T, C>(
+    modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<S, T, C>,
+    recordId: string,
+  ) => readonly PresenceSession[];
 }
 
 /**
@@ -112,5 +123,18 @@ export function createAbloReact<S extends SchemaRecord>(
     return useAbloImpl<S, T, C>(bound, modelOrSelect, id, options);
   }
 
-  return { AbloProvider: BoundAbloProvider, useAblo: useBoundAblo };
+  function useBoundPresence<T, C>(
+    modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<S, T, C>,
+    recordId: string,
+  ): readonly PresenceSession[] {
+    const bound = useContext(BoundClientContext);
+    const engine = useAbloClientImpl(bound);
+    return usePresenceImpl(engine, modelOrSelect, recordId);
+  }
+
+  return {
+    AbloProvider: BoundAbloProvider,
+    useAblo: useBoundAblo,
+    usePresence: useBoundPresence,
+  };
 }

package/src/react/useAblo.ts

@@ -223,12 +223,7 @@ export function useAbloImpl<
   id?: string,
   options?: UseAbloModelOptions<T>,
 ): Ablo<R> | null | UseAbloModelResult<T> | T | undefined {
-  const ctx = useContext(AbloInternalContext);
-  // The bound client wins — it is already `Ablo<R>`, no rebinding. The
-  // fallback is the ONE remaining schema rebind in the SDK; it retires with
-  // the last legacy provider mount (docs/plans/typed-react-binding.md).
-  const engine: Ablo<R> | null =
-    boundClient ?? (ctx?.engine ? rebindEngine<R>(ctx.engine) : null);
+  const engine = useAbloClientImpl(boundClient);
   const initial = options?.initial;
   const isSelectorOnly = typeof modelOrSelect === 'function' && id === undefined;
   const modelClient: ModelOperations<T, C> | undefined =
@@ -278,3 +273,16 @@ export function useAbloImpl<
   if (modelOrSelect) return modelResult;
   return engine;
 }
+
+/** @internal Resolve the bound or legacy provider client through one rebind seam. */
+export function useAbloClientImpl<R extends SchemaRecord>(
+  boundClient: Ablo<R> | null,
+): Ablo<R> | null {
+  const ctx = useContext(AbloInternalContext);
+  // The bound client wins — it is already `Ablo<R>`, no rebinding. The
+  // fallback is the ONE remaining schema rebind in the SDK; it retires with
+  // the last legacy provider mount (docs/plans/typed-react-binding.md).
+  const engine: Ablo<R> | null =
+    boundClient ?? (ctx?.engine ? rebindEngine<R>(ctx.engine) : null);
+  return engine;
+}

package/src/react/usePresence.ts

@@ -0,0 +1,88 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { PresenceSession } from '@abloatai/transaction/presence';
+import { AbloValidationError } from '@abloatai/transaction/errors';
+import {
+  getModelClientMeta,
+  type ModelOperations,
+} from '../local/client/createModelOperations.js';
+import type { AbloClient as Ablo } from '../client.js';
+import type { SchemaRecord } from '@abloatai/transaction/schema/schema';
+import type { ResolveSchema } from '@abloatai/transaction/types/global';
+import { useAbloClientImpl } from './useAblo.js';
+
+type DefaultModels = ResolveSchema extends { models: infer M }
+  ? M extends SchemaRecord
+    ? M
+    : SchemaRecord
+  : SchemaRecord;
+
+export type PresenceModelSelector<R extends SchemaRecord, T, C> =
+  (ablo: Ablo<R>) => ModelOperations<T, C>;
+
+/**
+ * Declare that this component is reading one row and return every live session
+ * reading or otherwise acting on that row. Ablo owns the lease, refresh,
+ * reconnect, and cleanup mechanics for the component's lifetime.
+ */
+export function usePresence<T, C>(
+  modelClient: ModelOperations<T, C>,
+  recordId: string,
+): readonly PresenceSession[];
+export function usePresence<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  select: PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[];
+export function usePresence<
+  R extends SchemaRecord = DefaultModels,
+  T = Record<string, unknown>,
+  C = unknown,
+>(
+  modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[] {
+  const engine = useAbloClientImpl<R>(null);
+  return usePresenceImpl(engine, modelOrSelect, recordId);
+}
+
+/** @internal Shared by the global hook and schema-bound React factory. */
+export function usePresenceImpl<R extends SchemaRecord, T, C>(
+  engine: Ablo<R> | null,
+  modelOrSelect: ModelOperations<T, C> | PresenceModelSelector<R, T, C>,
+  recordId: string,
+): readonly PresenceSession[] {
+  if (recordId.length === 0) {
+    throw new AbloValidationError(
+      'usePresence requires a non-empty record id.',
+      { code: 'invalid_request', param: 'recordId' },
+    );
+  }
+  const modelClient = typeof modelOrSelect === 'function'
+    ? engine
+      ? modelOrSelect(engine)
+      : null
+    : modelOrSelect;
+  const presence = modelClient ? getModelClientMeta(modelClient)?.presence : undefined;
+  if (modelClient !== null && presence === undefined) {
+    throw new AbloValidationError(
+      'usePresence requires a model from the reactive Ablo client.',
+      { code: 'invalid_request', param: 'modelClient' },
+    );
+  }
+
+  const [, render] = useState(0);
+
+  useEffect(
+    () => presence?.subscribe(() => { render((version) => version + 1); }),
+    [presence],
+  );
+
+  useEffect(() => presence?.read(recordId), [presence, recordId]);
+
+  return presence?.get(recordId) ?? [];
+}

package/src/react.ts

@@ -3,6 +3,10 @@ export { useReactive } from './useReactive.js';
 export { useCurrentUserId } from './react/useCurrentUserId.js';
 export { useErrorListener } from './react/useErrorListener.js';
 export { useSyncStatus, type SyncStatusSnapshot } from './react/useSyncStatus.js';
+export {
+  usePresence,
+  type PresenceModelSelector,
+} from './react/usePresence.js';
 export {
   useMutationFailureListener,
   type MutationFailurePayload,

package/src/surface.ts

@@ -37,6 +37,8 @@ export const PUBLIC_MODEL_VERBS = [
   'list',
   'listAll',
   'local',
+  'presence',
+  'events',
   'create',
   'update',
   'delete',

package/dist/presenceStream.d.ts

@@ -1,69 +0,0 @@
-/**
- * Creates a {@link PresenceStream} over a live sync connection. Presence is the
- * lightweight, ephemeral "who's here and what are they doing" view: each
- * participant broadcasts a status and an activity, and sees everyone else's.
- * The stream is built directly on the sync WebSocket and adds no second
- * connection. It is the sibling of {@link createClaimStream}, which reuses the
- * same presence frames.
- *
- * There are two ways to construct it:
- *
- *   1. Direct — pass an already-open `transport`, for example an agent worker
- *      or a test.
- *   2. Deferred — construct without a transport and call `attach(transport)`
- *      once the connection is ready. The returned stream object is stable from
- *      construction, so callers can hold the reference and let attachment
- *      happen later.
- *
- * Wire frames:
- *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
- *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
- *       other participants on the same sync groups.
- *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
- *       `leave`.
- */
-import type { WsTransport } from '@abloatai/transaction/transport/websocket';
-import type { PresenceStream } from '@abloatai/transaction/types/streams';
-import type { ParticipantKind } from '@abloatai/transaction/types/participant';
-/**
- * The wire capability the presence stream actually uses: subscribe to typed
- * inbound frames, check liveness, and send outbound frames. The duplex
- * `WsTransport` satisfies it — the same port shape the claim stream depends
- * on — so the stream can attach to whatever connection the host built,
- * without naming the engine's subclass.
- */
-export type PresenceTransport = Pick<WsTransport, 'subscribe' | 'isConnected' | 'send'>;
-export interface PresenceStreamConfig {
-    /** Identity used to filter our own echoed frames out of `others`. */
-    participantId: string;
-    /** Optional human label for the self entry. */
-    label?: string;
-    /** Sync groups the participant is broadcasting on. Used for the
-     *  initial `self` entry and for `othersIn(...)` filtering. */
-    syncGroups: readonly string[];
-    /** Marks `self` as an agent. Server is the source of truth for
-     *  peers' `isAgent`, but `self` is local — caller decides. */
-    isAgent?: boolean;
-}
-/** PresenceStream extended with engine-lifecycle hooks. */
-export interface AttachablePresenceStream extends PresenceStream {
-    /** Wire the stream to a now-ready transport. Calls before this are
-     *  buffered (self mutations only — no wire send). Idempotent. */
-    attach(transport: PresenceTransport): void;
-    /**
-     * Seeds the participant identity once the host resolves it. The stream can
-     * be built before identity is known — a hosted client learns who it is
-     * from its credential's scope during connect — and until then the
-     * construction-time values (possibly empty) would leave the `self` entry
-     * blank and let the participant's own echoed frames into `others`. Updates
-     * the `self` entry in place, so held references see the resolved identity.
-     */
-    setParticipant(participant: {
-        id: string;
-        kind?: ParticipantKind;
-        syncGroups?: readonly string[];
-    }): void;
-    /** Tear down listeners. Stream object stays usable as a no-op. */
-    dispose(): void;
-}
-export declare function createPresenceStream(config: PresenceStreamConfig, transport?: PresenceTransport | null): AttachablePresenceStream;

package/dist/presenceStream.js

@@ -1,200 +0,0 @@
-/**
- * Creates a {@link PresenceStream} over a live sync connection. Presence is the
- * lightweight, ephemeral "who's here and what are they doing" view: each
- * participant broadcasts a status and an activity, and sees everyone else's.
- * The stream is built directly on the sync WebSocket and adds no second
- * connection. It is the sibling of {@link createClaimStream}, which reuses the
- * same presence frames.
- *
- * There are two ways to construct it:
- *
- *   1. Direct — pass an already-open `transport`, for example an agent worker
- *      or a test.
- *   2. Deferred — construct without a transport and call `attach(transport)`
- *      once the connection is ready. The returned stream object is stable from
- *      construction, so callers can hold the reference and let attachment
- *      happen later.
- *
- * Wire frames:
- *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
- *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
- *       other participants on the same sync groups.
- *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
- *       `leave`.
- */
-import { asyncIteratorFrom } from '@abloatai/transaction/utils/asyncIterator';
-import { participantKindFromWire } from '@abloatai/transaction/coordination/schema';
-import { isTargetTuple, subTarget, wireTarget } from '@abloatai/transaction/coordination';
-export function createPresenceStream(config, transport = null) {
-    const { label, syncGroups, isAgent = false } = config;
-    // Mutable: the host seeds the resolved identity via `setParticipant` once
-    // it is known; the own-echo filter always reads the current value.
-    let participantId = config.participantId;
-    // ── Self ─────────────────────────────────────────────────────────
-    const self = {
-        participantKind: isAgent ? 'agent' : 'user',
-        participantId,
-        label,
-        syncGroups: [...syncGroups],
-        activity: { entityType: 'Unknown', entityId: '', action: 'idle' },
-        lastActive: new Date().toISOString(),
-    };
-    // ── Others ───────────────────────────────────────────────────────
-    const othersById = new Map();
-    let othersSnapshot = Object.freeze([]);
-    const listeners = new Set();
-    const notifyListeners = () => {
-        othersSnapshot = Object.freeze(Array.from(othersById.values()));
-        for (const l of listeners) {
-            try {
-                l();
-            }
-            catch {
-                /* one bad listener doesn't break the others */
-            }
-        }
-    };
-    // ── Wire wiring ──────────────────────────────────────────────────
-    let attached = null;
-    const unsubs = [];
-    function attach(t) {
-        if (attached)
-            return; // idempotent
-        attached = t;
-        // Reconnect: clear roster (Hub sends fresh snapshot), re-announce
-        // own activity (peers don't auto-learn about us across reconnects).
-        unsubs.push(t.subscribe('connected', () => {
-            if (othersById.size > 0) {
-                othersById.clear();
-                othersSnapshot = Object.freeze([]);
-                notifyListeners();
-            }
-            if (self.activity.entityId)
-                sendUpdate(self.activity);
-        }));
-        // Inbound presence frames arrive in the wire vocabulary
-        // (userId / isAgent / timestamp); translate them into the shape this
-        // stream exposes (participantId / participantKind / lastActive).
-        unsubs.push(t.subscribe('presence_update', (event) => {
-            if (event.userId === participantId)
-                return; // own echo
-            if (!event.userId)
-                return;
-            switch (event.kind) {
-                case 'leave':
-                    if (othersById.delete(event.userId))
-                        notifyListeners();
-                    return;
-                // No `undefined` arm: every site that builds a presence frame stamps
-                // `kind`, and the schema now says so, so an unlabelled frame is not a
-                // shape the transport can hand us.
-                case 'enter':
-                case 'update': {
-                    const entry = {
-                        participantKind: participantKindFromWire(event.participantKind, event.isAgent),
-                        participantId: event.userId,
-                        syncGroups: event.syncGroups ?? [],
-                        activity: event.activity
-                            ? {
-                                ...wireTarget(event.activity),
-                                ...subTarget(event.activity),
-                                action: event.activity.action,
-                                ...(event.activity.detail !== undefined
-                                    ? { detail: event.activity.detail }
-                                    : {}),
-                            }
-                            : { entityType: 'Unknown', entityId: '', action: event.status },
-                        lastActive: event.timestamp
-                            ? new Date(event.timestamp).toISOString()
-                            : new Date().toISOString(),
-                    };
-                    othersById.set(event.userId, entry);
-                    notifyListeners();
-                    return;
-                }
-            }
-        }));
-        // If self was already mutated before attach, broadcast it now.
-        if (self.activity.entityId)
-            sendUpdate(self.activity);
-    }
-    if (transport)
-        attach(transport);
-    // ── Outbound ────────────────────────────────────────────────────
-    // Do not include `isAgent` in the payload. The server derives it
-    // authoritatively from the connection's identity, and letting a client
-    // self-declare it once caused human sessions to broadcast as agents to peers.
-    function sendUpdate(activity) {
-        if (!attached?.isConnected())
-            return; // no-op until connected
-        attached.send({
-            type: 'presence_update',
-            payload: { status: 'online', activity },
-        });
-    }
-    function doUpdate(activity) {
-        self.activity = activity;
-        self.lastActive = new Date().toISOString();
-        sendUpdate(activity);
-    }
-    function resolveTarget(target) {
-        if (isTargetTuple(target)) {
-            return { entityType: target[0], entityId: target[1], action: 'unknown' };
-        }
-        return {
-            ...wireTarget(target),
-            ...subTarget(target),
-            action: 'unknown',
-        };
-    }
-    const withVerb = (action) => (target, detail) => {
-        doUpdate({ ...resolveTarget(target), action, detail });
-    };
-    return {
-        self,
-        update: doUpdate,
-        editing: withVerb('editing'),
-        reading: withVerb('reading'),
-        viewing: withVerb('viewing'),
-        idle: () => {
-            doUpdate({ entityType: 'Unknown', entityId: '', action: 'idle' });
-        },
-        get others() {
-            return othersSnapshot;
-        },
-        othersIn: (syncGroup) => othersSnapshot.filter((e) => e.syncGroups.includes(syncGroup)),
-        onChange: (listener) => {
-            listeners.add(listener);
-            return () => {
-                listeners.delete(listener);
-            };
-        },
-        [Symbol.asyncIterator]() {
-            return asyncIteratorFrom((onChange) => {
-                listeners.add(onChange);
-                return () => {
-                    listeners.delete(onChange);
-                };
-            }, () => othersSnapshot);
-        },
-        attach,
-        setParticipant(participant) {
-            participantId = participant.id;
-            const writable = self;
-            writable.participantId = participant.id;
-            if (participant.kind)
-                writable.participantKind = participant.kind;
-            if (participant.syncGroups)
-                writable.syncGroups = [...participant.syncGroups];
-        },
-        dispose() {
-            for (const off of unsubs)
-                off();
-            unsubs.length = 0;
-            listeners.clear();
-            othersById.clear();
-            othersSnapshot = Object.freeze([]);
-            attached = null;
-        },
-    };
-}