@hanzo/rooms 0.1.0

package/dist/lib/tier.js

@@ -0,0 +1,207 @@
+'use client';
+/**
+ * WHAT THIS ACCOUNT IS ON, AND WHAT IT MAY SPEND.
+ *
+ * Two reads, one question each. `GET /v1/billing/tier` names the plan and its
+ * term. `GET /v1/billing/balance` is the money: it reads the ledger the model
+ * gate admits against and every metered call is debited from, so its
+ * `available` is the one figure a person's spend is compared to. The tier's own
+ * `effectiveAvailable` is computed from commerce's store, which a top-up reaches
+ * and a usage debit does not, so it stays at the top-up after the ledger has
+ * spent it — and for the ecosystem orgs it is a $1,000 floor the gate never
+ * reads. The balance replaces it here; nothing adds the two.
+ *
+ * WHAT IT DOES NOT DO IS GUESS. The server answers 502 rather than 0 for a
+ * balance it could not read — "unknown is not broke" — and this keeps that
+ * distinction all the way to the screen: a failed read resolves to an error, an
+ * error renders as a sentence, and no path in this file produces a number that
+ * did not come from a response.
+ *
+ * The failure carries `status` because that is what `workspace/failure.ts`
+ * reads first, so a refusal here already speaks the vocabulary every room uses.
+ * A second Refusal class would be a second vocabulary for the same event.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { api } from './api.js';
+import { bearer, org, orgs, scope } from './session.js';
+import { list } from './list.js';
+import { money } from './plans.js';
+import { date } from './limits.js';
+/** An error that names the status, for `say()` to turn into a sentence. */
+const refusal = (status, message) => Object.assign(new Error(message), { status });
+/** GETs `path` as whoever holds the bearer, in this browser's organization. */
+async function read(path, signal) {
+    const res = await fetch(`${api()}${path}`, {
+        headers: scope(),
+        signal,
+    });
+    if (!res.ok) {
+        // The body is RFC 7807 here — `detail` is the server's own sentence, which
+        // is better than any rewording of it. Where there is none, the status is
+        // still a fact and `say()` knows what to do with it.
+        let detail = '';
+        try {
+            detail = (await res.json()).detail ?? '';
+        }
+        catch {
+            // an HTML error page proves nothing worth showing
+        }
+        throw refusal(res.status, detail || `Billing answered ${res.status}`);
+    }
+    return (await res.json());
+}
+/** 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 async function readTier(signal) {
+    const token = bearer();
+    if (!token)
+        throw refusal(401, 'Sign in to see your plan');
+    const [data, ledger] = await Promise.all([
+        read('/v1/billing/tier', signal),
+        read('/v1/billing/balance', signal),
+    ]);
+    data.balance = { ...data.balance, effectiveAvailable: ledger.available, account: ledger.account };
+    return data;
+}
+/**
+ * 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 function paid(t) {
+    return Boolean((t?.plan && t.plan !== 'free') || t?.tier?.name === 'pro' || t?.tier?.name === 'enterprise');
+}
+/** The states in which a subscription is the plan the org is on. */
+const LIVE = new Set(['active', 'trialing']);
+/**
+ * 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 async function readSubscription(signal) {
+    const got = await read('/v1/billing/subscriptions', signal);
+    return list(got?.subscriptions).find((s) => LIVE.has(s?.status) && typeof s?.plan?.price === 'number') ?? 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 function renewal(s) {
+    const each = money((s.plan.price * Math.max(1, s.quantity || 1)) / 100);
+    const when = date(s.currentPeriodEnd);
+    return `${each}/${s.plan.interval || 'month'} subscription${when ? `, ${s.cancelAtPeriodEnd ? 'ends' : 'renews'} ${when}` : ''}`;
+}
+/** The live subscription, held: null while unknown, refused, or on no plan. */
+export function useSubscription(enabled = true, org = null) {
+    const [sub, setSub] = useState(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const stop = new AbortController();
+        readSubscription(stop.signal)
+            .then((got) => {
+            if (!stop.signal.aborted)
+                setSub(got);
+        })
+            .catch(() => {
+            if (!stop.signal.aborted)
+                setSub(null);
+        });
+        return () => stop.abort();
+    }, [enabled, org]);
+    return sub;
+}
+/** How long a sign-in waits on billing before it offers the plans. */
+const PATIENCE = 5000;
+/** `signal`, cut off at PATIENCE, on a browser that can combine the two; else PATIENCE alone. */
+function within(signal) {
+    const limit = typeof AbortSignal.timeout === 'function' ? AbortSignal.timeout(PATIENCE) : undefined;
+    if (!signal || !limit)
+        return limit ?? signal;
+    return typeof AbortSignal.any === 'function' ? AbortSignal.any([signal, limit]) : limit;
+}
+/**
+ * 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 async function paying(signal) {
+    const token = bearer();
+    if (!token)
+        return false;
+    const acting = org();
+    const where = acting ? [acting] : orgs().slice(0, 10);
+    const reads = await Promise.allSettled((where.length ? where : [null]).map(async (o) => {
+        const res = await fetch(`${api()}/v1/billing/tier`, {
+            headers: { Authorization: `Bearer ${token}`, ...(o ? { 'X-Org-Id': o } : {}) },
+            signal: within(signal),
+        });
+        return res.ok ? (await res.json()) : null;
+    }));
+    return reads.some((r) => r.status === 'fulfilled' && paid(r.value));
+}
+/**
+ * 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 function useTier(enabled = true, org = null) {
+    const [tier, setTier] = useState(null);
+    const [wrong, setWrong] = useState(null);
+    const [nonce, setNonce] = useState(0);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const stop = new AbortController();
+        setWrong(null);
+        readTier(stop.signal)
+            .then((got) => {
+            if (!stop.signal.aborted)
+                setTier(got);
+        })
+            .catch((e) => {
+            if (!stop.signal.aborted) {
+                setTier(null);
+                setWrong(e);
+            }
+        });
+        return () => stop.abort();
+    }, [enabled, nonce, org]);
+    return { tier, wrong, reload: useCallback(() => setNonce((n) => n + 1), []) };
+}
+/**
+ * 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 function usePersonal(org, enabled = true) {
+    const [read, setRead] = useState(null);
+    useEffect(() => {
+        if (!enabled || !org)
+            return;
+        const stop = new AbortController();
+        fetch(`${api()}/v1/iam/organizations?${new URLSearchParams({ q: org })}`, {
+            headers: scope(),
+            signal: stop.signal,
+        })
+            .then((res) => (res.ok ? res.json() : null))
+            .then((body) => {
+            const row = list(body?.organizations).find((o) => o?.name === org);
+            if (!stop.signal.aborted)
+                setRead({ org, personal: Boolean(row?.isPersonal) });
+        })
+            .catch(() => {
+            if (!stop.signal.aborted)
+                setRead({ org, personal: false });
+        });
+        return () => stop.abort();
+    }, [enabled, org]);
+    return read && read.org === org ? read.personal : null;
+}

package/dist/lib/tiers.d.ts

@@ -0,0 +1,9 @@
+export type Tier = 'alpha' | 'beta';
+export declare function useTiers(): Set<Tier>;
+/** The tiers this reader has chosen to hide, and the toggle that sets them.
+ *
+ * Entitlement is one question (`useTiers`), what you want to see is another. A
+ * reader who may see a beta room can still put it away — the choice is theirs and
+ * lives with them, in this browser, never on the server. It starts empty: you see
+ * what you are entitled to until you say otherwise. */
+export declare function useHidden(): [Set<Tier>, (tier: Tier) => void];

package/dist/lib/tiers.js

@@ -0,0 +1,141 @@
+'use client';
+// Which preview tiers this identity may see.
+//
+// The rail offers Chat and Dev to everyone. The rooms after them — Inbox,
+// Agents, Tasks, Drive — are behind a tier, and a tier opens for exactly three
+// reasons, asked here and nowhere else:
+//
+//   1. A SUPERADMIN sees every tier. That is IAM's answer, read off the signed
+//      membership set: its first entry is the org the account lives in, and a
+//      SuperAdmin lives in the reserved `admin` org (hanzoai/authz Claims.Sudo).
+//      A membership of `admin` held from another org confers nothing, and a
+//      per-org `isAdmin` is a different, org-scoped question.
+//
+//   2. An ALPHA or BETA org sees its own tier. Whether an org is in a cohort is
+//      a targeting decision that lives on the cloud, so it is asked of the cloud:
+//      POST /v1/flags answers the feature flags in force for this identity, and
+//      `tier.alpha` / `tier.beta` open their rooms.
+//
+//   3. A LOCALHOST BUILD sees every tier, because a room nobody can open is a
+//      room nobody can work on. The check is the ORIGIN the page was served
+//      from, not an env var and not a build flag: a deployed host can never
+//      satisfy it however it is configured, so this cannot leak an unfinished
+//      room into production by being set wrong somewhere.
+//
+//   4. Nothing else. Signed out, still loading, or on any error the answer is the
+//      empty set: the rail shows Chat and Dev and nothing more. Failing closed is
+//      the point — a stranger meets the product the landing page describes, and a
+//      flags outage cannot leak an unfinished room into it.
+//
+// The per-account SETTING that hides a tier the reader is entitled to lives with
+// the reader, not here — see `useHidden`. This answers what you MAY see; that
+// answers what you have chosen to.
+import { useEffect, useState } from 'react';
+import { useIam, useOrganizations } from '@hanzo/iam/react';
+import { api } from './api.js';
+import { superAdmin as isSuperAdmin } from './session.js';
+/** Every tier, for the callers that are entitled to all of them. */
+const ALL = ['alpha', 'beta'];
+/**
+ * Whether this page is being served from a developer's own machine.
+ *
+ * The ORIGIN, because it is the one fact a deployment cannot accidentally
+ * acquire: no environment variable, no build flag and no misconfigured host
+ * turns api.hanzo.ai into localhost. Loopback by both names, and the private
+ * ranges a second machine on the same desk is reached by.
+ *
+ * READ AFTER MOUNT, never during the render that hydrates. The server has no
+ * origin to look at and answers false, so a client that answered true on its
+ * first pass rendered a different rail than the HTML it was hydrating and React
+ * threw the tree away. It is a fact about the browser, and a fact only the
+ * browser holds arrives in an effect.
+ */
+const local = () => {
+    if (typeof window === 'undefined')
+        return false;
+    const host = window.location.hostname;
+    return (host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host === '[::1]' ||
+        host.endsWith('.local') ||
+        /^10\./.test(host) ||
+        /^192\.168\./.test(host));
+};
+export function useTiers() {
+    const { user, accessToken } = useIam();
+    const { organizations } = useOrganizations();
+    const [flags, setFlags] = useState({});
+    const [here, setHere] = useState(false);
+    const [superAdmin, setSuperAdmin] = useState(false);
+    useEffect(() => setHere(local()), []);
+    // IAM's answer off the token's own `orgs` claim (lib/auth/session), read after
+    // mount like `local` so the first render matches the HTML it hydrates.
+    useEffect(() => setSuperAdmin(isSuperAdmin()), [accessToken]);
+    const id = user?.id ?? user?.name ?? '';
+    useEffect(() => {
+        // A SuperAdmin needs no answer from the server, and a stranger has none to
+        // ask for. Only a signed-in, non-admin identity consults /v1/flags.
+        if (!id || superAdmin) {
+            setFlags({});
+            return;
+        }
+        const ac = new AbortController();
+        // The PostHog-shaped evaluate: a distinct_id and the person's org, answered
+        // with `{ featureFlags: { … } }`. The session cookie carries the principal;
+        // with none the cloud answers 403 and this falls to the empty set, which is
+        // the signed-out room — the safe direction.
+        fetch(`${api()}/v1/flags`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ distinct_id: id, person_properties: { org: organizations[0]?.name } }),
+            signal: ac.signal,
+        })
+            .then((r) => (r.ok ? r.json() : null))
+            .then((body) => setFlags(body?.featureFlags ?? {}))
+            .catch(() => setFlags({}));
+        return () => ac.abort();
+    }, [id, superAdmin, organizations]);
+    // A platform admin, or a page served off a developer's own machine. Both see
+    // every tier for the same reason: a room nobody can open is a room nobody can
+    // work on.
+    if (superAdmin || here)
+        return new Set(ALL);
+    const tiers = new Set();
+    if (flags['tier.alpha'] === true)
+        tiers.add('alpha');
+    if (flags['tier.beta'] === true)
+        tiers.add('beta');
+    return tiers;
+}
+const HIDDEN_KEY = 'hanzo.hidden-tiers';
+/** The tiers this reader has chosen to hide, and the toggle that sets them.
+ *
+ * Entitlement is one question (`useTiers`), what you want to see is another. A
+ * reader who may see a beta room can still put it away — the choice is theirs and
+ * lives with them, in this browser, never on the server. It starts empty: you see
+ * what you are entitled to until you say otherwise. */
+export function useHidden() {
+    const [hidden, setHidden] = useState(new Set());
+    useEffect(() => {
+        try {
+            const saved = JSON.parse(localStorage.getItem(HIDDEN_KEY) || '[]');
+            setHidden(new Set(saved));
+        }
+        catch {
+            setHidden(new Set());
+        }
+    }, []);
+    const toggle = (tier) => setHidden((was) => {
+        const next = new Set(was);
+        next.has(tier) ? next.delete(tier) : next.add(tier);
+        try {
+            localStorage.setItem(HIDDEN_KEY, JSON.stringify([...next]));
+        }
+        catch {
+            /* a browser that refuses storage keeps the choice for this session */
+        }
+        return next;
+    });
+    return [hidden, toggle];
+}

package/dist/lib/todo.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The board's store: `/v1/todo` with resilient local cache fallback.
+ *
+ * A card IS a forge issue — the platform's own words: "the column is a LABEL on
+ * the forge, so the board and the forge web UI are the same object seen twice:
+ * relabelling in either moves the card in both." So nothing here invents a
+ * parallel place to keep work; it reads and writes the one the org already has.
+ *
+ * WHAT THE STORE HOLDS, and therefore what this board can honestly draw: a
+ * title, a description, a column, a priority, an assignee, labels, and a start
+ * and due date. Checklists ride in the description as markdown task items,
+ * which is not a workaround — it is how a forge issue has always spelled a
+ * checklist, so one written here renders in the forge web UI and one written
+ * there arrives back on the card.
+ */
+import type { AiClient } from '@hanzo/ai';
+/** One card, as the board reads it. */
+export interface Card {
+    id: string;
+    /** "<key>#<number>" — the board and the number on it, joined. */
+    identifier: string;
+    projectKey: string;
+    number: number;
+    kind: string;
+    source: string;
+    repo?: string;
+    title: string;
+    description?: string;
+    /** The column. One of {@link COLUMNS}. */
+    status: string;
+    priority: string;
+    assignee?: string;
+    labels: string[];
+    /** Unix seconds; 0/absent means unscheduled. */
+    startAt?: number;
+    dueAt?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * THE COLUMNS, and they are the platform's own closed set rather than a list a
+ * reader types. `newIssue` names them: "backlog, todo, in_progress, done or
+ * canceled". A column that is not one of these cannot be moved to, because the
+ * move is a relabel and the forge would not know the label.
+ */
+export declare const COLUMNS: readonly [{
+    readonly id: 'backlog';
+    readonly label: 'Backlog';
+}, {
+    readonly id: 'todo';
+    readonly label: 'To do';
+}, {
+    readonly id: 'in_progress';
+    readonly label: 'Doing';
+}, {
+    readonly id: 'done';
+    readonly label: 'Done';
+}, {
+    readonly id: 'canceled';
+    readonly label: 'Canceled';
+}];
+/** The priorities the store accepts, loudest first. */
+export declare const PRIORITIES: readonly ['urgent', 'high', 'medium', 'low', 'none'];
+export declare const DEFAULT_CARDS: Card[];
+/** Every card on the org's board, or one project's when `key` is given. */
+export declare function board(client?: AiClient | null, params?: {
+    key?: string;
+    status?: string;
+    label?: string;
+    scheduled?: boolean;
+}, signal?: AbortSignal): Promise<Card[]>;
+/** The boards themselves — a project is a repository on the forge. */
+export declare function projects(client?: AiClient | null, signal?: AbortSignal): Promise<{
+    key: string;
+    name?: string;
+}[]>;
+/** Opens a card in a column. */
+export declare function open(client: AiClient | null | undefined, key: string, card: {
+    title: string;
+    description?: string;
+    status?: string;
+    priority?: string;
+    labels?: string[];
+}, signal?: AbortSignal): Promise<Card>;
+/**
+ * Edits a card. Absent fields are left alone.
+ */
+export declare function edit(client: AiClient | null | undefined, key: string, num: number, patch: {
+    title?: string;
+    description?: string;
+    status?: string;
+    priority?: string;
+    assignee?: string;
+    labels?: string[];
+    startAt?: number;
+    dueAt?: number;
+}, signal?: AbortSignal): Promise<Card>;
+/** Takes the card — the store's own verb for who is doing the work. */
+export declare function claim(client: AiClient | null | undefined, key: string, num: number, signal?: AbortSignal): Promise<Card>;
+/** One line of a description that is a task. */
+export interface Step {
+    done: boolean;
+    text: string;
+    /** Which line it is, so ticking one rewrites that line and no other. */
+    line: number;
+}
+/**
+ * The task items in a description.
+ */
+export declare function steps(description?: string): Step[];
+/** The description with one step's box flipped, and every other line untouched. */
+export declare function tick(description: string, line: number, done: boolean): string;
+/** The description with one more step at the end of its list. */
+export declare function addStep(description: string, text: string): string;
+export interface Sift {
+    holder?: string;
+    by?: 'person' | 'agent';
+    state?: 'done' | 'open';
+    due?: 'none' | 'late' | 'day' | 'week' | 'month';
+    labels?: string[];
+    active?: number;
+    text?: string;
+}
+export declare const SETTLED: Set<string>;
+export declare function sift(cards: Card[], want: Sift, me?: string, agents?: Set<string>): Card[];