@hanzo/rooms 0.1.0

package/dist/lib/share.js

@@ -0,0 +1,216 @@
+/**
+ * Sharing a conversation by link.
+ *
+ * The platform makes a read-only link to one conversation and answers its token
+ * once (github.com/hanzoai/agent share.go, under /v1/agent/chat). It keeps only
+ * the token's hash, so the token is held here, in this person's browser, for
+ * the conversation it opens — `own()` in lib/auth/session.ts removes it with
+ * every other `hanzo*` key when a different person signs in.
+ *
+ * A shared chat opens for its owner and for the people who open the link signed
+ * in, and for nobody else. A reader who is not signed in is told the title and
+ * asked to sign in; a signed-in reader is recorded as a viewer the owner can
+ * see, reads the chat, and finds it afterwards under Shared with you, read by
+ * its share id (`/chat/shared?s=<id>`) with no token at all. The token names a
+ * chat and authenticates nobody: every read carries the reader's own bearer.
+ *
+ * The token rides the address as the FRAGMENT (`/chat/shared#<token>`), which a
+ * browser never sends to any server. It leaves the address before anything on
+ * the page can read it: `SEAL`, the first script in the document head, moves it
+ * into this tab's sessionStorage and replaces the address with one that has no
+ * fragment, before the analytics and ad tags configure themselves. It reaches
+ * the platform only in a request body, and survives the sign-in round trip in
+ * sessionStorage — never back in an address.
+ */
+import { api } from './api.js';
+import { live, scope } from './session.js';
+/** The page a shared conversation is read on. */
+export const SHARED = '/chat/shared';
+/** Where this tab holds a link's token between opening it and reading it. */
+export const OPENING = 'hanzo:share:open';
+/**
+ * The document-head script that takes a share token out of the address. On any
+ * spelling of /chat/shared with a fragment — and on any page whose fragment has
+ * a share token's shape, the not-found page included — the fragment goes to
+ * sessionStorage (and to `window.hzShare` for a browser that refuses storage)
+ * and the address is replaced by the same path and query with no fragment. It
+ * runs as the document is parsed and again on every `hashchange` and
+ * `popstate`, with its listeners registered before any tag's, so a link pasted
+ * into an open tab is taken out before a tag's own history listener reads the
+ * address. First in the head, so no tag and no module ever sees an address
+ * carrying a token.
+ */
+export const SEAL = `(function(){function s(){try{var l=location,h=l.hash;if(h.length<2)return;var t=h.slice(1);try{t=decodeURIComponent(t)}catch(_){}var p=l.pathname.toLowerCase().replace(/\\/+/g,'/').replace(/\\/index\\.html$/,'').replace(/\\.html$/,'').replace(/\\/$/,'');if(p!=='${SHARED}'&&!/^[A-Za-z0-9_-]{43}$/.test(t))return;window.hzShare=t;try{sessionStorage.setItem('${OPENING}',t)}catch(_){}history.replaceState(null,'',l.pathname+l.search)}catch(_){}}s();addEventListener('hashchange',s);addEventListener('popstate',s)})()`;
+/** `SEAL` for a fragment the head's listeners did not take: the token goes to
+ *  this tab and the address loses the fragment. */
+export function take() {
+    try {
+        const hash = window.location.hash;
+        if (hash.length < 2)
+            return;
+        let token = hash.slice(1);
+        try {
+            token = decodeURIComponent(token);
+        }
+        catch {
+            /* a malformed escape: the fragment as written */
+        }
+        ;
+        window.hzShare = token;
+        try {
+            window.sessionStorage.setItem(OPENING, token);
+        }
+        catch {
+            /* held on the window for this page */
+        }
+        history.replaceState(null, '', window.location.pathname + window.location.search);
+    }
+    catch {
+        /* a browser that refuses history: the head script already tried */
+    }
+}
+/** The address that opens a share, on this origin unless told otherwise. */
+export function link(token, origin = window.location.origin) {
+    return `${origin}${SHARED}#${token}`;
+}
+/** The address a viewer reads a chat shared with them at, without the token. */
+export function address(share) {
+    return `${SHARED}?s=${encodeURIComponent(share)}`;
+}
+/** A token this tab is holding for a link it opened and has not read yet, or ''. */
+export function opening() {
+    if (typeof window === 'undefined')
+        return '';
+    try {
+        const held = window.sessionStorage.getItem(OPENING);
+        if (held)
+            return held;
+    }
+    catch {
+        /* a browser that refuses storage: the head left it on the window */
+    }
+    return window.hzShare ?? '';
+}
+/** Forget the token this tab was holding, once the link has been read. */
+export function opened() {
+    try {
+        window.sessionStorage.removeItem(OPENING);
+    }
+    catch {
+        /* nothing held */
+    }
+    delete window.hzShare;
+}
+/** A refusal, carrying the platform's own sentence and status. */
+export class Refused extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The sentence a refusal carries, or one in plain words when it carries none. */
+function sentence(body, status) {
+    const b = (body ?? {});
+    const said = [b.detail, typeof b.error === 'object' ? b.error?.message : b.error, b.message].find((v) => typeof v === 'string' && v.trim() !== '');
+    if (said)
+        return said;
+    if (status === 401 || status === 403)
+        return 'Sign in again to manage sharing.';
+    if (status >= 500)
+        return 'Sharing is not answering right now. Try again shortly.';
+    return 'That did not work. Try again.';
+}
+async function call(path, init) {
+    const r = await fetch(`${api()}${path}`, init);
+    const text = await r.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        body = null;
+    }
+    if (!r.ok)
+        throw new Refused(sentence(body, r.status), r.status);
+    return body;
+}
+const base = (thread) => `/v1/agent/chat/conversations/${encodeURIComponent(thread)}/shares`;
+/** The owner's side: make, list and revoke the links to one conversation, and
+ *  remove one viewer from a link. */
+export const shares = {
+    list: async (thread) => (await call(base(thread), { headers: scope() })).shares ?? [],
+    make: (thread) => call(base(thread), { method: 'POST', headers: { 'Content-Type': 'application/json', ...scope() }, body: '{}' }),
+    revoke: (thread, id) => call(`${base(thread)}/${encodeURIComponent(id)}`, { method: 'DELETE', headers: scope() }),
+    unview: (thread, id, viewer) => call(`${base(thread)}/${encodeURIComponent(id)}/viewers/${encodeURIComponent(viewer)}`, { method: 'DELETE', headers: scope() }),
+};
+/** The reader's bearer and the organization they are working in: an owner who
+ *  opens their own link from the organization they shared it in is its owner
+ *  there, and not a viewer of it. Nothing about the reader's organization is
+ *  read or changed. */
+function reader() {
+    if (!live())
+        return {};
+    const h = scope();
+    return h.Authorization ? h : {};
+}
+/** Open a link, or null when it opens nothing (never made, revoked, or closed
+ *  to this reader). `open` is the reader's go-ahead to be recorded as a viewer,
+ *  given after they were told who shared it and that their name is shown. */
+export async function read(token, open = false) {
+    try {
+        return await call('/v1/agent/chat/shares/read', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...reader() },
+            body: JSON.stringify({ token, open }),
+        });
+    }
+    catch (e) {
+        if (e instanceof Refused && e.status === 404)
+            return null;
+        throw e;
+    }
+}
+/** Read a chat shared with the reader by its share id, or null when it is no
+ *  longer open to them. */
+export async function readShared(share) {
+    try {
+        return await call(`/v1/agent/chat/shared/${encodeURIComponent(share)}`, { headers: reader() });
+    }
+    catch (e) {
+        if (e instanceof Refused && e.status === 404)
+            return null;
+        throw e;
+    }
+}
+/** The chats shared with the reader, most recently opened first. */
+export async function sharedWithMe() {
+    return (await call('/v1/agent/chat/shared', { headers: reader() })).shared ?? [];
+}
+/** Where this browser keeps the token of the link it last made for a conversation. */
+const held = (thread) => `hanzo:share:${thread}`;
+/** The link this browser holds for a conversation, if its share is still live. */
+export function heldToken(thread, live) {
+    try {
+        const raw = window.localStorage.getItem(held(thread));
+        const got = raw ? JSON.parse(raw) : null;
+        if (got?.id && got.token && live.some((s) => s.id === got.id))
+            return { id: got.id, token: got.token };
+    }
+    catch {
+        /* nothing held, or a store that refuses */
+    }
+    return null;
+}
+/** Hold a new link's token for its conversation; null forgets it. */
+export function hold(thread, value) {
+    try {
+        if (value)
+            window.localStorage.setItem(held(thread), JSON.stringify(value));
+        else
+            window.localStorage.removeItem(held(thread));
+    }
+    catch {
+        /* the link still works; this browser just cannot copy it again */
+    }
+}

package/dist/lib/signout.d.ts

@@ -0,0 +1,14 @@
+import { IAM } from '@hanzo/iam';
+/** Whether the page in front of us is on such an origin. */
+export declare const here: () => boolean;
+/** The IAM client for this page; the token exchange at the callback shares its PKCE store. */
+export declare function useClient(): IAM;
+/** Where a sign-out lands: this site's sign-in, which does not ask IAM for the session just ended. */
+export declare const OUT = "/login?from=logout";
+/**
+ * Sign-out on this site: @hanzo/ui/auth's `signOut` — the tokens handed back to
+ * IAM's /v1/iam routes, IAM's session here ended, the local session cleared —
+ * counted as logout_completed, and then /login?from=logout, where the person can
+ * sign straight back in. IAM's own logout page is never visited.
+ */
+export declare function useSignOut(): () => Promise<void>;

package/dist/lib/signout.js

@@ -0,0 +1,40 @@
+'use client';
+/**
+ * IAM, called from this page. The embedded sign-in, the silent check for a
+ * session and sign-out all go through `useClient`, whose credential calls are
+ * answered on this origin where it answers them (universe static-sites
+ * `iam-on-hanzo-ai`): that is also where IAM keeps its session cookie, so the
+ * session a person signs in with here is the one a later visit finds, and the
+ * one sign-out ends. Nobody is sent to hanzo.id for any of it.
+ */
+import { useMemo } from 'react';
+import { IAM } from '@hanzo/iam';
+import { useIam } from '@hanzo/iam/react';
+import { useSignOut as useUiSignOut } from '@hanzo/ui/auth';
+import { track } from './tags.js';
+import { APEX } from './host.js';
+/**
+ * The hosts that answer IAM's sign-in and sign-out calls on their own origin:
+ * every host this export is served on and signs in at (universe static-sites
+ * `iam-on-hanzo-ai`), and the dev server's /v1 proxy.
+ */
+const HOSTS = new Set([...APEX, 'cloud.hanzo.ai', 'hanzo.bot', 'bot.hanzo.ai', 'localhost', '127.0.0.1']);
+/** Whether the page in front of us is on such an origin. */
+export const here = () => typeof window !== 'undefined' && HOSTS.has(window.location.hostname);
+/** The IAM client for this page; the token exchange at the callback shares its PKCE store. */
+export function useClient() {
+    const { config } = useIam();
+    const local = here();
+    return useMemo(() => new IAM(local ? { ...config, proxyBaseUrl: window.location.origin } : config), [config, local]);
+}
+/** Where a sign-out lands: this site's sign-in, which does not ask IAM for the session just ended. */
+export const OUT = '/login?from=logout';
+/**
+ * Sign-out on this site: @hanzo/ui/auth's `signOut` — the tokens handed back to
+ * IAM's /v1/iam routes, IAM's session here ended, the local session cleared —
+ * counted as logout_completed, and then /login?from=logout, where the person can
+ * sign straight back in. IAM's own logout page is never visited.
+ */
+export function useSignOut() {
+    return useUiSignOut({ to: OUT, track });
+}

package/dist/lib/tags.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The funnel's one call. `track` is @hanzo/event's: a moment reaches our stream
+ * (POST /v1/event, the one ingest) and every browser tag the visitor's consent
+ * and region allow, under one event_id. The tags come from the site's tag
+ * config (GET /v1/project/tags, which also says which consent rule binds this
+ * visitor); no platform id lives in this repo. Our stream stays the record every
+ * Hanzo dashboard reads, and cloud forwards its copy server-side.
+ *
+ * `startTags` runs once, from app/providers.tsx. `attach` hands `track` the
+ * page's one client, from inside its provider.
+ */
+import { mirror, startTags, tagsReady, visit, type Analytics } from '@hanzo/event';
+export { mirror, startTags, tagsReady, visit };
+/** The sites one visit can cross; GA4 keeps it one session across them. */
+export declare const DOMAINS: string[];
+/** Hands track() the one @hanzo/event client, from inside its provider. */
+export declare function attach(client: Analytics): void;
+/**
+ * `url` with the visitor's identity on it when it leads to another Hanzo host
+ * (hanzo.id, hanzo.app), so the journey across the hop is one visitor
+ * (@hanzo/event link). Any other address comes back as it was.
+ */
+export declare function link(url: string): string;
+/** `link` for the redirect to IAM: the same, and the queue is sent before the page leaves. */
+export declare function authorize(url: string): string;
+/** One funnel moment, to every place it is counted, under one event_id. */
+export declare function track(name: string, params?: Record<string, unknown>): void;

package/dist/lib/tags.js

@@ -0,0 +1,46 @@
+/**
+ * The funnel's one call. `track` is @hanzo/event's: a moment reaches our stream
+ * (POST /v1/event, the one ingest) and every browser tag the visitor's consent
+ * and region allow, under one event_id. The tags come from the site's tag
+ * config (GET /v1/project/tags, which also says which consent rule binds this
+ * visitor); no platform id lives in this repo. Our stream stays the record every
+ * Hanzo dashboard reads, and cloud forwards its copy server-side.
+ *
+ * `startTags` runs once, from app/providers.tsx. `attach` hands `track` the
+ * page's one client, from inside its provider.
+ */
+import { mirror, startTags, tagsReady, track as fire, visit } from '@hanzo/event';
+export { mirror, startTags, tagsReady, visit };
+/** The sites one visit can cross; GA4 keeps it one session across them. */
+export const DOMAINS = [
+    'hanzo.ai',
+    'hanzo.app',
+    'hanzo.chat',
+    'pay.hanzo.ai',
+    'hanzo.id',
+    'hanzo.build',
+    'docs.hanzo.ai',
+    'platform.hanzo.ai',
+    'cal.hanzo.ai',
+];
+let stream;
+/** Hands track() the one @hanzo/event client, from inside its provider. */
+export function attach(client) {
+    stream = client;
+}
+/**
+ * `url` with the visitor's identity on it when it leads to another Hanzo host
+ * (hanzo.id, hanzo.app), so the journey across the hop is one visitor
+ * (@hanzo/event link). Any other address comes back as it was.
+ */
+export function link(url) {
+    return stream ? stream.link(url) : url;
+}
+/** `link` for the redirect to IAM: the same, and the queue is sent before the page leaves. */
+export function authorize(url) {
+    return stream ? stream.authorize(url) : url;
+}
+/** One funnel moment, to every place it is counted, under one event_id. */
+export function track(name, params = {}) {
+    fire(stream, name, params);
+}

package/dist/lib/tap.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A standalone tap target, as gui props: a box with its content in a row, and
+ * 44px on its smaller side under a coarse pointer (WCAG 2.5.5, a thumb). A
+ * mouse keeps the control's own size. A link inside a sentence is not one —
+ * stretching it to 44px would tear the line it sits in.
+ *
+ * Spread it on the gui element that is the control: `<XStack render="a" {...tap}>`.
+ */
+export declare const tap: {
+    readonly display: 'inline-flex';
+    readonly flexDirection: 'row';
+    readonly items: 'center';
+    readonly $touchable: {
+        readonly minH: 44;
+        readonly minW: 44;
+    };
+};

package/dist/lib/tap.js

@@ -0,0 +1,9 @@
+/**
+ * A standalone tap target, as gui props: a box with its content in a row, and
+ * 44px on its smaller side under a coarse pointer (WCAG 2.5.5, a thumb). A
+ * mouse keeps the control's own size. A link inside a sentence is not one —
+ * stretching it to 44px would tear the line it sits in.
+ *
+ * Spread it on the gui element that is the control: `<XStack render="a" {...tap}>`.
+ */
+export const tap = { display: 'inline-flex', flexDirection: 'row', items: 'center', $touchable: { minH: 44, minW: 44 } };

package/dist/lib/tier.d.ts

@@ -0,0 +1,115 @@
+/** The plan, as billing names it. */
+export interface TierLimits {
+    name: string;
+    displayName: string;
+    dailyCreditsCents: number;
+    maxAgents: number;
+    /** MaxAgents 0 means "no ceiling" rather than "no agents" — the reading a
+     *  bare zero cannot carry. The server publishes it because the zero is
+     *  ambiguous, so nothing here re-derives it. */
+    unlimitedAgents: boolean;
+    allowedModels?: string[];
+}
+/** Whole USD cents, every field. */
+export interface TierBalance {
+    currency: string;
+    prepaidAvailable: number;
+    creditsRemaining: number;
+    dailyRemaining: number;
+    /** THE ONE FIGURE TO COMPARE AGAINST ZERO: the ledger's `available`, which
+     *  `readTier` states from GET /v1/billing/balance. */
+    effectiveAvailable: number;
+    /** The account that figure is the balance OF, as billing resolved the payer —
+     *  the org's own pool, or a member's wallet inside it. Never derived here. */
+    account?: string;
+}
+/** A rate term — "10 requests per minute, 3 left, resets at …". */
+export interface TierWindow {
+    span: string;
+    limit: number;
+    used: number;
+    remaining: number;
+    resets: string;
+}
+export interface Tier {
+    user: string;
+    /** The catalog rung the subject is served as — a plan slug like "max-20x",
+     *  or "" where the account holds no subscription. `tier` is the coarser
+     *  class (free/dev/enterprise) that slug is served under; this is the row
+     *  `lib/plans.ts` names, and the one a menu should print. */
+    plan: string;
+    tier: TierLimits;
+    balance: TierBalance;
+    windows?: TierWindow[];
+}
+/** Reads the tier and the balance for whoever holds the bearer. The requests
+ *  name no subject — the credential is the scope — so there is no id to get wrong. */
+export declare function readTier(signal?: AbortSignal): Promise<Tier>;
+/**
+ * Whether a tier answer is a paid plan: billing names a paid plan the account's
+ * subscription is on, or serves it a paid tier — `pro`, which a plan recorded
+ * outside checkout confers, or `enterprise` (the platform org, a partner org).
+ * A trial nobody paid for is `starter` and names no plan.
+ */
+export declare function paid(t: {
+    plan?: string;
+    tier?: {
+        name?: string;
+    };
+} | null | undefined): boolean;
+/** A plan the org subscribes to, as GET /v1/billing/subscriptions lists it. Money in whole cents. */
+export interface Subscription {
+    id: string;
+    status: string;
+    quantity: number;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    plan: {
+        id: string;
+        name: string;
+        price: number;
+        currency: string;
+        interval: string;
+    };
+}
+/**
+ * The org's live subscription, or null where it holds none — being on no plan
+ * is an answer, and a refusal is not: that throws, the way the tier read does.
+ */
+export declare function readSubscription(signal?: AbortSignal): Promise<Subscription | null>;
+/**
+ * The term as a sentence: "$200/month subscription, renews Oct 30, 2026". The
+ * price is per seat, so it is the seats times it; a cancelled term ends rather
+ * than renews.
+ */
+export declare function renewal(s: Subscription): string;
+/** The live subscription, held: null while unknown, refused, or on no plan. */
+export declare function useSubscription(enabled?: boolean, org?: string | null): Subscription | null;
+/**
+ * Whether this account pays for a plan where it works: in the organization it
+ * acts in, or, before it has picked one, in any organization its token names.
+ * A read that fails or takes longer than PATIENCE counts as no plan, so the
+ * plans are offered rather than the app withheld. At most ten organizations
+ * are asked.
+ */
+export declare function paying(signal?: AbortSignal): Promise<boolean>;
+/**
+ * The tier, held. `null` while unknown — which is BOTH "still asking" and
+ * "asked and was refused", so `wrong` is kept beside it rather than swallowed:
+ * a row cannot choose between saying nothing and saying why without it.
+ */
+export declare function useTier(enabled?: boolean, org?: string | null): {
+    tier: Tier | null;
+    wrong: unknown;
+    reload: () => void;
+};
+/**
+ * Whether an organization is its owner's personal one, off IAM's own row.
+ *
+ * The token's `orgs` claim names an organization and the reader's role in it
+ * and says nothing of its kind; IAM keeps that on the row (`isPersonal`), and
+ * `GET /v1/iam/organizations` answers the rows the caller belongs to. `null`
+ * until it is answered for this organization. A refusal reads as `false`, so a
+ * room that needs a plan goes on asking for one.
+ */
+export declare function usePersonal(org: string | null, enabled?: boolean): boolean | null;