@sansavision/yousaid-react 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@sansavision/yousaid-react` are recorded here. The project
+follows semantic versioning for the stable surface listed in README.md.
+
+## 0.2.0
+
+First npm release.
+
+- Ships compiled ES2022 JavaScript (`jsx: react-jsx`) with TypeScript declarations and declaration maps.
+- Depends on `@sansavision/yousaid` `^0.2.0`; peer dependency `react >= 19`.
+- Stable: `YouSaidProvider`, `useYouSaid`, `YouSaidLauncher`, `Inbox`, `useInbox` and `LifecycleReceipt`.
+- Experimental (tagged `@experimental`): Rooms components and hooks, agents, approvals, moderation, Proof widgets, `ProofPrompt` and proof hooks, map helpers.

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 Sansa Group AB
+
+All rights reserved, Sansa Group AB. Licence terms pending owner and legal review.
+
+No licence is granted to use, copy, modify or distribute this software until
+Sansa Group AB publishes licence terms for it.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# @sansavision/yousaid-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components and hooks for YouSaid: a feedback launcher, the end user's live
+inbox of replies, and lifecycle receipts. Requires React 19 or later.
+
+```sh
+npm install @sansavision/yousaid-react @sansavision/yousaid-server
+```
+
+`@sansavision/yousaid` (the framework-free client) is installed with it.
+`@sansavision/yousaid-server` runs on your server only and signs the end user's
+identity.
+
+## 1. Mint an identity token on your server
+
+```ts
+import { createYouSaidIdentityToken } from "@sansavision/yousaid-server";
+
+export async function GET(request: Request) {
+  const user = await currentUser(request);
+  const token = await createYouSaidIdentityToken(
+    { sub: user.id, org_id: "org_...", product_id: "prd_...", email: user.email },
+    process.env.YOUSAID_SIGNING_SECRET!,
+    { keyId: process.env.YOUSAID_KEY_ID! },
+  );
+  return new Response(token, { headers: { "cache-control": "no-store" } });
+}
+```
+
+## 2. Wrap your app in the provider
+
+```tsx
+"use client";
+import { YouSaidProvider, YouSaidLauncher, Inbox } from "@sansavision/yousaid-react";
+
+// A function, not a string: every write consumes the token's nonce.
+const getToken = () => fetch("/api/yousaid-token").then((response) => response.text());
+
+export function Feedback() {
+  return (
+    <YouSaidProvider token={getToken}>
+      <YouSaidLauncher label="Talk to us" appVersion="4.2.0" />
+      <Inbox title="Replies" />
+    </YouSaidProvider>
+  );
+}
+```
+
+`YouSaidProvider` takes the same options as `YouSaidClient` (`token`, `endpoint`,
+`fetch`). Keep the `token` function stable (define it outside the component or
+wrap it in `useCallback`) so the client is not recreated on every render.
+
+## Components and hooks
+
+| Export | What it does |
+| --- | --- |
+| `YouSaidProvider` | Creates one `YouSaidClient` for the tree. |
+| `useYouSaid()` | Returns that client, for example to call `sendSignal` or `confirmRelease` from your own UI. Throws outside the provider. |
+| `YouSaidLauncher` | A floating "Talk to us" button and form: message kind, attachments and an opt-in diagnostics checkbox. Props: `label`, `defaultView`, `appVersion`, `featureFlags`, `breadcrumbs`, `verifyInstall` (default true). |
+| `Inbox` | The signed-in end user's replies, live over Server-Sent Events, with unread counts and mark-read. Props: `title`, `emptyMessage`, `onOpen(item)`. |
+| `useInbox({ live, limit })` | The same data headless: `{ items, unread, loading, connected, error, refresh, markRead }`. |
+| `LifecycleReceipt` | A `role="status"` receipt that tells the user where their report is. Props: `title`, `state`. |
+
+```tsx
+import { LifecycleReceipt, useInbox, useYouSaid } from "@sansavision/yousaid-react";
+
+function ReleaseQuestion({ releaseId }: { releaseId: string }) {
+  const client = useYouSaid();
+  return <button onClick={() => void client.confirmRelease(releaseId, "resolved")}>It works now</button>;
+}
+
+function UnreadBadge() {
+  const { unread } = useInbox({ live: true });
+  return unread ? <span aria-label={`${unread} unread replies`}>{unread}</span> : null;
+}
+
+<LifecycleReceipt title="Report received" state="The team is looking at it." />;
+```
+
+Send AppHelm context with a signal through `useYouSaid().sendSignal({ ..., context: { apphelm: { workspaceId, externalUserId } } })`.
+See the `@sansavision/yousaid` README for the field rules.
+
+## Server rendering
+
+Every component renders on the server without touching `window`; the network work
+starts in effects after hydration. The modules carry `"use client"`.
+
+## Stability
+
+Version 0.2.0 marks these exports as **stable** under semantic versioning:
+`YouSaidProvider`, `useYouSaid`, `YouSaidLauncher`, `Inbox`, `useInbox` and
+`LifecycleReceipt`.
+
+Everything else is **experimental** and tagged `@experimental` in the type
+declarations: `YouSaidRooms` and every Rooms component and hook, agent and
+approval cards, moderation, the Proof widgets (`ProofWall`, `ProofCarousel`,
+`ProofCard`, `ProofBadge`, `ProofMap`, `ProofMarquee`, `ProofVideoBubble`,
+`ProofLogoStrip`), `ProofPrompt` and the proof hooks, and the map helpers.
+Experimental APIs can change in any minor release.
+
+## Licence
+
+`UNLICENSED`. All rights reserved, Sansa Group AB. Licence terms are pending
+owner and legal review; see LICENSE.
+
+Documentation: https://yousaid.dev/docs/sdk

package/dist/context.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+import { YouSaidClient, type YouSaidClientOptions } from "@sansavision/yousaid";
+export declare function YouSaidProvider({ children, ...options }: YouSaidClientOptions & {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useYouSaid(): YouSaidClient;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAIhF,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,GAAG,OAAO,EACX,EAAE,oBAAoB,GAAG;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAQhD;AAED,wBAAgB,UAAU,IAAI,aAAa,CAK1C"}

package/dist/context.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { YouSaidClient } from "@sansavision/yousaid";
+const YouSaidContext = createContext(null);
+export function YouSaidProvider({ children, ...options }) {
+    const client = useMemo(() => new YouSaidClient(options), [options.endpoint, options.fetch, options.token]);
+    return (_jsx(YouSaidContext.Provider, { value: client, children: children }));
+}
+export function useYouSaid() {
+    const client = useContext(YouSaidContext);
+    if (!client)
+        throw new Error("useYouSaid must be used inside YouSaidProvider.");
+    return client;
+}

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { type ReactNode } from "react";
+import { type DiagnosticsCapsule, type InboxItem, type RoomDetail, type RoomSummary } from "@sansavision/yousaid";
+export { YouSaidProvider, useYouSaid } from "./context.js";
+export { AgentMentionMenu, canvasEntries, DEFAULT_CANVAS_LABELS, DEFAULT_MENTION_AGENTS, filterAgents, mentionMenuKey, RequestHumanButton, RoomCanvas, roomAgentStyles, useAgentRun, usePendingApprovals, useRequestHuman, useRoomCanvas, useRoomEvents, useRoomMembers, type CanvasEntry, type MentionAgent, } from "./rooms.js";
+export declare function YouSaidLauncher({ label, defaultView, appVersion, featureFlags, breadcrumbs, verifyInstall, }: {
+    label?: string;
+    defaultView?: "feedback" | "rooms";
+    /** Included in the diagnostic capsule only when the user opts in. */
+    appVersion?: string;
+    featureFlags?: string[];
+    breadcrumbs?: DiagnosticsCapsule["breadcrumbs"];
+    /** Report SDK installation health once per page load (used by onboarding). */
+    verifyInstall?: boolean;
+}): import("react").JSX.Element;
+/**
+ * Live in-app inbox for the signed-in end user: loads the latest items, keeps
+ * a Server-Sent Events stream open (with backoff reconnects), and marks items read.
+ */
+export declare function useInbox(options?: {
+    live?: boolean;
+    limit?: number;
+}): {
+    items: InboxItem[];
+    unread: number;
+    loading: boolean;
+    connected: boolean;
+    error: string;
+    refresh: () => Promise<void>;
+    markRead: (ids?: string[]) => Promise<void>;
+};
+export declare function Inbox({ title, emptyMessage, onOpen }: {
+    title?: string;
+    emptyMessage?: string;
+    onOpen?: (item: InboxItem) => void;
+}): import("react").JSX.Element;
+/** @experimental */
+export declare function useRooms(): {
+    rooms: RoomSummary[];
+    loading: boolean;
+    error: string;
+    refresh: () => Promise<void>;
+};
+/** @experimental */
+export declare function useRoom(roomId: string | null): {
+    room: RoomDetail | null;
+    loading: boolean;
+    error: string;
+    refresh: () => Promise<void>;
+};
+/** @experimental */
+export declare function useRoomComposer(roomId: string | null, onSent?: () => void | Promise<void>): {
+    send: (body: string) => Promise<boolean>;
+    pending: boolean;
+    error: string;
+};
+/** @experimental */
+export declare function YouSaidRooms({ embedded, initialRoomId, onSolveSession, }: {
+    embedded?: boolean;
+    initialRoomId?: string | null;
+    onSolveSession?: (session: {
+        authToken: string;
+        mode: "audio" | "video" | "screen_share";
+    }) => void;
+}): import("react").JSX.Element;
+/** @experimental */
+export declare function RoomsList({ rooms, selectedId, onSelect, }: {
+    rooms: RoomSummary[];
+    selectedId?: string | null;
+    onSelect: (roomId: string) => void;
+}): import("react").JSX.Element;
+/** @experimental */
+export declare function RoomView({ detail, onRefresh, onSolveSession, }: {
+    detail: RoomDetail;
+    onRefresh: () => void | Promise<void>;
+    onSolveSession?: (session: {
+        authToken: string;
+        mode: "audio" | "video" | "screen_share";
+    }) => void;
+}): import("react").JSX.Element;
+/** @experimental */
+export declare function RoomComposer({ roomId, onSent, }: {
+    roomId: string;
+    onSent?: () => void | Promise<void>;
+}): import("react").JSX.Element;
+/** @experimental */
+export declare function AgentActionCard({ state, children, }: {
+    state: "drafted" | "approval_needed" | "completed";
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** @experimental */
+export declare function ApprovalCard({ summary, onApprove, onReject, }: {
+    summary: string;
+    onApprove: () => void;
+    onReject: () => void;
+}): import("react").JSX.Element;
+export declare function LifecycleReceipt({ title, state, }: {
+    title: string;
+    state: string;
+}): import("react").JSX.Element;
+export * from "./proof.js";
+export { ProofPromptView, useProofPrompt, type ProofPromptOptions, type ProofPromptProps, type ProofPromptState } from "./proof-prompt.js";
+/**
+ * Native in-app Proof prompt using the provider's signed identity. See ProofPromptView for props.
+ * @experimental
+ */
+export declare function ProofPrompt(props: Omit<import("./proof-prompt.js").ProofPromptProps, "client">): import("react").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}