@belonguniverseai/react-sdk 0.6.6 → 0.6.8

package/dist/components/connectors/connector-form.d.ts

@@ -0,0 +1,299 @@
+import { ConnectorAuthInput, ConnectorCredentialInput, ConnectorTransport } from '../../api/connectors.ts';
+/** The two transports, in menu order — the default first. */
+export declare const CONNECTOR_TRANSPORTS: readonly ConnectorTransport[];
+/** What a connector is reached with unless the user says otherwise. Nearly
+ *  every server published today speaks it; SSE is the older one. */
+export declare const DEFAULT_CONNECTOR_TRANSPORT: ConnectorTransport;
+export declare const isConnectorTransport: (value: string) => value is ConnectorTransport;
+export declare const MAX_CONNECTOR_NAME_CHARS = 100;
+export declare const MAX_CONNECTOR_DESCRIPTION_CHARS = 500;
+export declare const MAX_CONNECTOR_EMOJI_CHARS = 16;
+export declare const MAX_CONNECTOR_SERVER_URL_CHARS = 2048;
+export declare const MAX_CONNECTOR_HEADER_ROWS = 16;
+export declare const MAX_CONNECTOR_OAUTH_CLIENT_ID_CHARS = 256;
+export declare const MAX_CONNECTOR_OAUTH_CLIENT_SECRET_CHARS = 2048;
+export declare const MAX_CONNECTOR_OAUTH_SCOPE_CHARS = 1024;
+export declare const MAX_CONNECTOR_OAUTH_PARAM_ROWS = 10;
+export declare const MAX_CONNECTOR_OAUTH_PARAM_VALUE_CHARS = 512;
+export declare const MAX_CONNECTOR_TOKEN_ENDPOINT_CHARS = 2048;
+/**
+ * One row of the custom-headers editor. Rows are ORDERED and may be blank —
+ * the editor always keeps a row to type into.
+ *
+ * `id` is the row's REACT identity, not data: rows are added, removed from the
+ * middle and retyped, and keying them by array index makes React reuse the
+ * wrong input's DOM node (the value you typed follows the row above the one
+ * you deleted). It never reaches the wire — `validateConnectorAuth` builds the
+ * header map from `name`/`value` alone.
+ */
+export type ConnectorHeaderRow = {
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+};
+/**
+ * One row of the extra-sign-in-settings editor. Same three fields as a header
+ * row and same reason for each of them (see above) — a separate type because
+ * the two editors bound their names and values differently, and a shared alias
+ * would invite validating one with the other's rules.
+ */
+export type ConnectorParamRow = {
+    readonly id: string;
+    readonly name: string;
+    readonly value: string;
+};
+/**
+ * The credential half of the form, as the dialog holds it in state.
+ *
+ * `oauth` is the odd one out and stays that way on purpose: every field is
+ * OPTIONAL and all-empty is the ordinary case, because there is no credential
+ * to type — signing in happens at the provider. They exist for the minority of
+ * apps that hand you an id and a secret to paste, or that insist on being asked
+ * for particular permissions, and they live behind a disclosure so the common
+ * path stays one choice in a menu.
+ *
+ * `oauth_client_credentials` is the opposite: its id and secret are REQUIRED,
+ * because they are the whole credential. It behaves like `bearer` — typed once,
+ * used immediately, replaced through Edit.
+ */
+export type ConnectorAuthDraft = {
+    readonly mode: "none";
+} | {
+    readonly mode: "bearer";
+    readonly token: string;
+} | {
+    readonly mode: "headers";
+    readonly rows: readonly ConnectorHeaderRow[];
+} | {
+    readonly mode: "oauth";
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly scope: string;
+    readonly params: readonly ConnectorParamRow[];
+} | {
+    readonly mode: "oauth_client_credentials";
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly tokenEndpoint: string;
+    readonly scope: string;
+};
+export type ConnectorAuthDraftMode = ConnectorAuthDraft["mode"];
+export type ConnectorFormDraft = {
+    readonly name: string;
+    readonly description: string;
+    readonly emoji: string;
+    readonly serverUrl: string;
+    /** Never validated, only carried: both members are legal, and the edit form
+     *  passes the STORED one straight back through (it cannot be changed). */
+    readonly transport: ConnectorTransport;
+    readonly auth: ConnectorAuthDraft;
+    /** The probe found no dynamic registration endpoint. Only matters when the
+     *  user overrides the token-first suggestion and chooses sign-in. */
+    readonly signInNeedsClientId: boolean;
+};
+/**
+ * What is wrong with the draft. A discriminated union rather than a message
+ * string so the copy lives in the i18n catalog and this module stays
+ * translatable — and so a new rule mechanically fails every `match` on it.
+ */
+export type ConnectorFormProblem = {
+    readonly kind: "name_empty";
+} | {
+    readonly kind: "name_too_long";
+} | {
+    readonly kind: "description_too_long";
+} | {
+    readonly kind: "emoji_too_long";
+} | {
+    readonly kind: "url_empty";
+} | {
+    readonly kind: "url_too_long";
+}
+/** Not a URL at all, or a scheme we could never dispatch (`file:`, `javascript:`). */
+ | {
+    readonly kind: "url_invalid";
+} | {
+    readonly kind: "token_empty";
+}
+/** A row with a value typed but no header name. */
+ | {
+    readonly kind: "header_name_empty";
+} | {
+    readonly kind: "header_name_invalid";
+    readonly name: string;
+} | {
+    readonly kind: "header_name_duplicate";
+    readonly name: string;
+} | {
+    readonly kind: "header_value_newline";
+    readonly name: string;
+} | {
+    readonly kind: "header_rows_exceeded";
+    readonly maxCount: number;
+}
+/** A secret typed with no id. Both blank is fine; a secret alone is a paste
+ *  that went wrong, and the server refuses it too. */
+ | {
+    readonly kind: "oauth_client_id_missing";
+}
+/** Sign-in cannot start because this provider will not dynamically register
+ *  Belong and the draft carries no already-registered app id. */
+ | {
+    readonly kind: "oauth_client_id_required";
+} | {
+    readonly kind: "oauth_client_id_too_long";
+} | {
+    readonly kind: "oauth_client_secret_too_long";
+}
+/** Not a permissions line the app could be asked for — a stray quote, a tab,
+ *  or two spaces where one word was meant. */
+ | {
+    readonly kind: "oauth_scope_invalid";
+} | {
+    readonly kind: "oauth_scope_too_long";
+}
+/** A setting with a value typed but no name. */
+ | {
+    readonly kind: "oauth_param_name_empty";
+} | {
+    readonly kind: "oauth_param_name_invalid";
+    readonly name: string;
+}
+/** A name the sign-in address already uses for something of its own. */
+ | {
+    readonly kind: "oauth_param_name_reserved";
+    readonly name: string;
+} | {
+    readonly kind: "oauth_param_name_duplicate";
+    readonly name: string;
+} | {
+    readonly kind: "oauth_param_value_newline";
+    readonly name: string;
+} | {
+    readonly kind: "oauth_param_value_too_long";
+    readonly name: string;
+} | {
+    readonly kind: "oauth_params_exceeded";
+    readonly maxCount: number;
+}
+/** The service credential's two required halves. Unlike the sign-in mode's,
+ *  these ARE the credential, so neither may be left blank. */
+ | {
+    readonly kind: "cc_client_id_missing";
+} | {
+    readonly kind: "cc_client_id_too_long";
+} | {
+    readonly kind: "cc_client_secret_missing";
+} | {
+    readonly kind: "cc_client_secret_too_long";
+} | {
+    readonly kind: "cc_token_endpoint_invalid";
+} | {
+    readonly kind: "cc_token_endpoint_too_long";
+}
+/** Re-signing in is the Connect action, not a field on the edit form. */
+ | {
+    readonly kind: "oauth_not_replaceable";
+};
+/** The normalized payload a valid draft submits — trimmed, with blank header
+ *  rows dropped and the emoji omitted (not empty-stringed) when unset. */
+export type ConnectorFormValues = {
+    readonly name: string;
+    readonly description: string;
+    readonly emoji?: string;
+    readonly serverUrl: string;
+    readonly transport: ConnectorTransport;
+    readonly auth: ConnectorAuthInput;
+};
+export type ConnectorFormValidation = {
+    readonly kind: "ok";
+    readonly values: ConnectorFormValues;
+} | {
+    readonly kind: "invalid";
+    readonly problem: ConnectorFormProblem;
+};
+/** The auth half's own verdict, for the CREATE form (OAuth included). */
+export type ConnectorAuthValidation = {
+    readonly kind: "ok";
+    readonly value: ConnectorAuthInput;
+} | {
+    readonly kind: "invalid";
+    readonly problem: ConnectorFormProblem;
+};
+/** The narrower verdict the EDIT dialog needs — a credential it can replace. */
+export type ConnectorCredentialValidation = {
+    readonly kind: "ok";
+    readonly value: ConnectorCredentialInput;
+} | {
+    readonly kind: "invalid";
+    readonly problem: ConnectorFormProblem;
+};
+/**
+ * The server's ORIGIN, for showing a user which host they pointed at without
+ * echoing a path or query back (either can carry a token). Falls back to the
+ * raw string when it does not parse — a value we cannot read is still a value
+ * the user typed and may need to recognise.
+ */
+export declare const connectorServerOrigin: (serverUrl: string) => string;
+/**
+ * Is this address worth ASKING about yet? True only for something that would
+ * survive the form's own url check, so a half-typed `https://a` never becomes
+ * a request — the probe fires on a paste, and a request per keystroke would be
+ * a request per keystroke to somebody else's server.
+ */
+export declare const isProbableConnectorUrl: (serverUrl: string) => boolean;
+/**
+ * The credential form a probed address should OPEN on.
+ *
+ * Deliberately returns a BLANK draft of the suggested mode rather than one
+ * pre-filled from discovery. The two values discovery could hand over — a
+ * client id and a scope line — are exactly the two the server re-derives on
+ * its own at sign-in time (`connector-oauth.ts` prefers the row's pinned scope
+ * and falls back to the server's), so writing them into the form would pin
+ * today's answer to a row that outlives it, in a field the user did not type.
+ *
+ * A suggestion is a STARTING POINT: the caller applies it only while the user
+ * has not chosen a mode themselves, and the Advanced select stays the override.
+ */
+export declare const authDraftForSuggestion: (suggestion: {
+    readonly mode: "none";
+} | {
+    readonly mode: "oauth";
+    readonly registration: "dynamic" | "client_id_required";
+    readonly authorizationServerOrigin: string;
+} | {
+    readonly mode: "bearer";
+}) => ConnectorAuthDraft;
+/**
+ * Does the suggested credential need the user to TYPE something before Add can
+ * work? That is the question Advanced's fold answers wrongly by default: a
+ * pasted token and a provider-console client id both live behind it, and a
+ * folded field the form is waiting on reads as a form that refuses to submit
+ * for no reason.
+ */
+export declare const suggestionNeedsInput: (suggestion: {
+    readonly mode: "none";
+} | {
+    readonly mode: "oauth";
+    readonly registration: "dynamic" | "client_id_required";
+} | {
+    readonly mode: "bearer";
+}) => boolean;
+/** Validate the auth half alone. Accepts every mode the CREATE form offers. */
+export declare const validateConnectorAuth: (auth: ConnectorAuthDraft) => ConnectorAuthValidation;
+/**
+ * Validate a credential the EDIT dialog can actually replace.
+ *
+ * `oauth` is refused rather than accepted-and-ignored: re-signing in is the
+ * Connect action, and a save button that silently did nothing would be worse
+ * than a sentence saying where the control is. The edit dialog does not offer
+ * the mode, so this is the belt to that braces — and it keeps the patch's type
+ * honest instead of widening it to a shape the server refuses.
+ *
+ * A SERVICE credential passes, and has to: an app that stopped honouring an id
+ * and secret has no window to send anyone to, so typing the new pair here is
+ * the whole recovery.
+ */
+export declare const validateConnectorCredential: (auth: ConnectorAuthDraft) => ConnectorCredentialValidation;
+/** Validate the whole add-a-connector form. */
+export declare const validateConnectorForm: (draft: ConnectorFormDraft) => ConnectorFormValidation;

package/dist/components/connectors/portal-theme.d.ts

@@ -0,0 +1,8 @@
+import { CSSProperties } from 'react';
+export type PortalTheme = {
+    /** Spread onto the portaled content element. */
+    readonly style: CSSProperties;
+    /** `"dark"` when the dock is dark, so Tailwind's `.dark` variants apply. */
+    readonly className: string | undefined;
+};
+export declare const usePortalTheme: () => PortalTheme;

package/dist/components/connectors/product-name.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The product name the connector copy says out loud — "Simetrik" on the tenant
+ * preset, "Belong" by default, or whatever a host pushed with
+ * `belong.setTheme({ brand })`.
+ *
+ * The same value `app.openAssistant` and `embed.agentWorking` interpolate, read
+ * from the same live store; the connector surfaces need it because they are
+ * PROPLESS (see `ConnectorsListSurface`'s module doc) and cannot be handed the
+ * theme the way `EmbedLogin` is. Lives in a plain `.ts` module for the reason
+ * `portal-theme.ts` does — the component files stay clean React Fast Refresh
+ * boundaries.
+ *
+ * Why the name is in the copy at all: "connect an app so the agent can act on
+ * your data" is a sentence a user cannot weigh, because "the agent" is not
+ * anything they signed up for. The brand is (§42 — name the product).
+ */
+export declare const useProductName: () => string;

package/dist/components/connectors/use-connector-oauth.d.ts

@@ -0,0 +1,28 @@
+import { ConnectorNotice } from './connector-copy.ts';
+export type ConnectorOAuthPhase = {
+    readonly kind: "idle";
+}
+/** The server is discovering the provider; nothing is on screen yet. */
+ | {
+    readonly kind: "starting";
+} | {
+    readonly kind: "waiting";
+    readonly connectorId: string;
+    /** Rendered as a link when the popup did not open. */
+    readonly authorizationUrl: string;
+    readonly popupBlocked: boolean;
+} | {
+    readonly kind: "done";
+    readonly connectorId: string;
+} | {
+    readonly kind: "failed";
+    readonly notice: ConnectorNotice;
+};
+export type ConnectorOAuthConnect = {
+    readonly phase: ConnectorOAuthPhase;
+    /** Start (or restart) the flow for one connector. */
+    readonly connect: (connectorId: string) => Promise<void>;
+    /** Back to `idle` — what a dialog calls when it reopens. */
+    readonly reset: () => void;
+};
+export declare const useConnectorOAuthConnect: () => ConnectorOAuthConnect;

package/dist/components/embed/EmbedRail.d.ts

@@ -7,7 +7,7 @@ import { BelongTheme, BelongThemePalette, PresetName } from '../../types/public.
  *  two must carry the SAME members: this one is what the chrome renders, that
  *  one is what the router and localStorage persist, and a view present in only
  *  one of them is a view you can reach but not come back to after a reload. */
-export type EmbedView = "chat" | "files" | "scheduled" | "prompts";
+export type EmbedView = "chat" | "files" | "scheduled" | "prompts" | "connectors";
 /**
  * 52px rail. Top: user avatar (account + theme controls). Middle: Chat /
  * Files nav (active = Ocean primary fill, brand-driven). Bottom
@@ -15,7 +15,7 @@ export type EmbedView = "chat" | "files" | "scheduled" | "prompts";
  * expand-to-modal — then the collapse toggle. Active fill + brand colours come
  * from `palette` so a host brand push re-themes everything.
  */
-export declare function EmbedRail({ view, collapsed, user, theme, palette, sessions, activeId, planProgress, speakEnabled, ttsSupported, voiceSupported, voiceStatus, pendingVoiceDraft, voiceActionFlash, accent, cssVars, presets, activePreset, onSelectView, onToggleCollapse, onToggleMode, onToggleSide, onAccentChange, onAccentReset, onCssVarsChange, onApplyPreset, onLogout, onNewSession, onSelectSession, onSelectAgentLine, onCloseAgentLine, onDeleteSession, onRenameSession, onSessionsOpen, onViewStats, onToggleSpeak, onExpand, }: {
+export declare function EmbedRail({ view, collapsed, user, theme, palette, sessions, activeId, planProgress, speakEnabled, ttsSupported, voiceSupported, voiceStatus, pendingVoiceDraft, voiceActionFlash, accent, cssVars, presets, activePreset, onSelectView, onToggleCollapse, onToggleMode, onToggleSide, onAccentChange, onAccentReset, onCssVarsChange, onApplyPreset, onLogout, onNewSession, onSelectSession, onSelectAgentLine, onCloseAgentLine, onDeleteSession, onRenameSession, onSessionsOpen, onViewStats, onToggleSpeak, onExpand, connectorsUnavailable, }: {
     view: EmbedView;
     collapsed: boolean;
     user: string | null;
@@ -86,4 +86,16 @@ export declare function EmbedRail({ view, collapsed, user, theme, palette, sessi
     onViewStats?: (sessionId: string) => void;
     onToggleSpeak: () => void;
     onExpand: () => void;
+    /**
+     * This deployment answered "the connectors feature is off here" — the rail
+     * then hides the Connectors entry entirely, because a surface that can only
+     * ever say "unavailable" is worse than no entry at all.
+     *
+     * Optional and defaulting to FALSE so the entry shows OPTIMISTICALLY: the
+     * dock's list query is still in flight on first paint, and a rail item that
+     * pops in a second late reads as a glitch. Only a resolved `featureAbsent`
+     * (404, or a 503 whose body is `connectors_disabled`) flips this — an
+     * ordinary outage keeps the entry, and the surface shows its retry state.
+     */
+    connectorsUnavailable?: boolean;
 }): import("react").JSX.Element;

package/dist/components/embed/rail-flags.d.ts

@@ -40,3 +40,17 @@ export declare const MULTI_AGENT_RAIL_ENABLED = true;
  * back with no other change.
  */
 export declare const VOICE_CALL_BUTTON_ENABLED = false;
+/**
+ * The Connectors tab in the MOBILE bottom nav bar (the desktop rail entry is
+ * always on — it is only gated by whether the deployment has the feature).
+ *
+ * `false` on purpose: the bar is AT CAPACITY. `MobileNavBar`'s own comment
+ * measures it — BEL-259's fourth tab already took the row to 7 cells (8 with
+ * the dial button), which at 375px in Spanish overflows into a horizontal
+ * scroller, and a fifth view tab pushes the sessions switcher and the close
+ * chevron further behind a swipe the user has no reason to attempt. Connectors
+ * is a set-up-once surface; a phone is where you USE what you connected, not
+ * where you register an app. Flip to `true` once the bar is re-thought (an
+ * overflow "More" cell), and the tab appears with no other change.
+ */
+export declare const CONNECTORS_MOBILE_TAB_ENABLED = false;

package/dist/components/embed/save-prompt-name.d.ts

@@ -3,14 +3,19 @@
  * `schedule-dialog-model.ts` uses: every rule lives here, the component holds
  * none of the branching.
  *
- * Two jobs. `slugifyPromptName` turns whatever the user types into the
+ * Three jobs. `slugifyPromptName` turns whatever the user types into the
  * lowercase slug the server accepts (rejecting instead would punish anyone who
- * types a normal title). `validatePromptName` answers the ticket's open
- * save-time UX question: a name already owned by a builtin, a tenant skill, a
- * workspace command, or another saved prompt is BLOCKED and the reason NAMES
- * which one — because the client merge resolves precedence by dropping the
- * shadowed prompt, so saving one would produce a prompt that never appears in
- * `/`. That reads as data loss, and the user has no way to discover it.
+ * types a normal title). `slugifyPromptNameWhileTyping` is its per-keystroke
+ * sibling: identical except it KEEPS a trailing dash, because a controlled
+ * input that re-runs the canonical slugify on every keystroke deletes the `-`
+ * the user just typed ("recon-" → "recon") — which made a hyphenated name like
+ * `recon-overview` impossible to TYPE even though pasting it worked.
+ * `validatePromptName` answers the ticket's open save-time UX question: a name
+ * already owned by a builtin, a tenant skill, a workspace command, or another
+ * saved prompt is BLOCKED and the reason NAMES which one — because the client
+ * merge resolves precedence by dropping the shadowed prompt, so saving one
+ * would produce a prompt that never appears in `/`. That reads as data loss,
+ * and the user has no way to discover it.
  */
 /** Server bound — `pre-prompt.schemas.ts`'s `MAX_PRE_PROMPT_NAME_CHARS`. */
 export declare const MAX_PROMPT_NAME_CHARS = 64;
@@ -19,6 +24,14 @@ export declare const MAX_PROMPT_NAME_CHARS = 64;
  * the server's ceiling (then re-trim, since the cut can land on a dash).
  */
 export declare const slugifyPromptName: (raw: string) => string;
+/**
+ * The per-keystroke transform for the controlled name inputs: same pipeline as
+ * `slugifyPromptName` but the trailing dash SURVIVES, so the `-` the user just
+ * typed is still there when the next letter lands. Dialogs validate and submit
+ * the canonical `slugifyPromptName` of the field, so the kept dash never
+ * reaches the server.
+ */
+export declare const slugifyPromptNameWhileTyping: (raw: string) => string;
 /** Which kind of existing entry already owns a name the user typed. */
 export type PromptNameOwner = "builtin" | "skill" | "command" | "prompt";
 type PromptNameValidation = {

package/dist/embed/dock-state.d.ts

@@ -5,7 +5,7 @@
  * in the stream-state store; this module owns only view + size. Best-effort:
  * disabled/quota'd storage just means no cross-reload restore.
  */
-export type DockView = "chat" | "files" | "scheduled" | "prompts";
+export type DockView = "chat" | "files" | "scheduled" | "prompts" | "connectors";
 export type DockSize = "collapsed" | "expanded" | "modal";
 export type DockState = {
     readonly view: DockView;