@sansavision/yousaid 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@sansavision/yousaid` 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 with TypeScript declarations and declaration maps.
+- Stable: `YouSaidClient` (`sendSignal`, `verifyInstallation`, `listInbox`, `markInboxRead`, `streamInbox`, `confirmRelease`, `mergeAnonymousHistory`), `collectDiagnostics`, `anonymousVisitorId`, `SIGNAL_ATTACHMENT_LIMITS`, `YOUSAID_SDK_VERSION` and the signal, inbox and diagnostics types.
+- New: `SignalInput.context.apphelm` (`AppHelmSignalContext`) carries AppHelm workspace, product, user and session ids so YouSaid can link a conversation back to AppHelm.
+- Experimental (tagged `@experimental`): Rooms, agents, approvals, moderation, proof rendering, beacons and uploads, realtime, `createSseParser` and 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,153 @@
-# Temporary Holding Version
+# @sansavision/yousaid
 
-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.
+The framework-free YouSaid client. Send customer signals from your product, show
+the end user their private inbox of replies, and ask whether a release fixed
+their problem. Works in any modern browser and in Node 20 or later.
+
+```sh
+npm install @sansavision/yousaid @sansavision/yousaid-server
+```
+
+`@sansavision/yousaid-server` runs on your server only. It signs the end user's
+identity so the browser never holds your product signing secret.
+
+## 1. Mint an identity token on your server
+
+```ts
+import { createYouSaidIdentityToken } from "@sansavision/yousaid-server";
+
+// GET /api/yousaid-token, behind your own session check.
+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, name: user.name },
+    process.env.YOUSAID_SIGNING_SECRET!,
+    { keyId: process.env.YOUSAID_KEY_ID! },
+  );
+  return new Response(token, { headers: { "cache-control": "no-store" } });
+}
+```
+
+## 2. Create the client
+
+```ts
+import { YouSaidClient } from "@sansavision/yousaid";
+
+const client = new YouSaidClient({
+  // Prefer a function: every state-changing request consumes the token's nonce.
+  token: () => fetch("/api/yousaid-token").then((response) => response.text()),
+});
+```
+
+| Option | Meaning |
+| --- | --- |
+| `token` | A signed identity token, or a sync or async function that returns a fresh one. Required. |
+| `endpoint` | The signals URL. Defaults to `https://yousaid.dev/api/signals`. Every other call uses the origin of this URL. |
+| `fetch` | A custom `fetch`, for tests or runtimes without a global one. |
+
+## 3. Send a signal
+
+```ts
+const receipt = await client.sendSignal({
+  kind: "bug", // support, bug, feature, ux or review
+  title: "PDF export freezes",
+  body: "The export hangs at 90 percent on long pages.",
+  context: { route: "/export", appVersion: "4.2.0" },
+});
+// receipt: { signalId, threadId, state: "acknowledged", receipt, inboxUrl, replayed }
+```
+
+Retries are safe: pass your own `idempotencyKey` (one is generated otherwise) and a
+replay answers `replayed: true` with the original ids.
+
+Attachments and diagnostics are optional:
+
+```ts
+import { collectDiagnostics, SIGNAL_ATTACHMENT_LIMITS } from "@sansavision/yousaid";
+
+await client.sendSignal({
+  title: "Checkout button does nothing",
+  body: "Clicking Pay shows no error.",
+  attachments: files.slice(0, SIGNAL_ATTACHMENT_LIMITS.maxFiles),
+  // Only after the end user saw and agreed to what is shared. Query strings are never included.
+  diagnostics: collectDiagnostics({ consent: true, appVersion: "4.2.0" }),
+});
+```
+
+### AppHelm context
+
+If your product also reports to AppHelm, attach the AppHelm ids so your team
+gets an "Open in AppHelm" link on the conversation:
+
+```ts
+await client.sendSignal({
+  title: "Sync stopped",
+  body: "Nothing synced since this morning.",
+  context: {
+    apphelm: {
+      workspaceId: "ws_123",            // required, ^[A-Za-z0-9_-]{1,100}$
+      productId: "prod_9",              // optional, ^[A-Za-z0-9_-]{1,100}$
+      externalUserId: "user-42",        // optional, ^[A-Za-z0-9._:@+-]{1,200}$
+      distinctHash: "9f86d081884c7d65", // optional lowercase hex, 16 to 128 characters
+      sessionHash: "2c26b46b68ffc68f",  // optional lowercase hex, 16 to 128 characters
+    },
+  },
+});
+```
+
+Send ids and hashes only, never emails or names. Unknown keys or an invalid value
+drop the whole `apphelm` object; the signal itself is always accepted. YouSaid adds
+the person link (it needs `externalUserId` or `distinctHash`) and the session link
+(it needs `sessionHash`) only when `workspaceId` matches the AppHelm workspace an
+owner or admin connected in YouSaid.
+
+## 4. Inbox
+
+```ts
+const page = await client.listInbox({ limit: 20 });   // { unread, items, nextCursor }
+await client.markInboxRead(page.items.map((item) => item.id)); // or markInboxRead() for all
+
+const stop = new AbortController();
+void client.streamInbox((event) => {
+  if (event.type === "item") console.log("New reply", event.item.subject, event.unread);
+}, stop.signal);
+```
+
+## 5. Release receipts
+
+When you ship a fix, YouSaid asks the people who reported the problem whether it
+works now. Record their answer:
+
+```ts
+await client.confirmRelease("rel_...", "resolved");
+await client.confirmRelease("rel_...", "still_broken", "Still freezes on Safari.");
+```
+
+`still_broken` opens a follow-up signal for your team.
+
+## More
+
+- `client.verifyInstallation()` checks the signed identity and records SDK health for onboarding.
+- `anonymousVisitorId()` and `client.mergeAnonymousHistory()` join anonymous hosted-form history to the signed user after sign-in.
+- `YOUSAID_SDK_VERSION` is the version of this package.
+
+## Stability
+
+Version 0.2.0 marks this surface as **stable**. It follows semantic versioning:
+
+- `YouSaidClient` with its constructor options (`token` string or async callback, `endpoint`, `fetch`) and the methods `sendSignal`, `verifyInstallation`, `listInbox`, `markInboxRead`, `streamInbox`, `confirmRelease` and `mergeAnonymousHistory`
+- `collectDiagnostics`, `anonymousVisitorId`, `SIGNAL_ATTACHMENT_LIMITS`, `YOUSAID_SDK_VERSION`
+- the types `SignalInput` (including `context.apphelm`), `SignalReceipt`, `SignalKind`, `InboxItem`, `InboxPage`, `InboxEvent`, `DiagnosticsCapsule`, `YouSaidClientOptions` and `AppHelmSignalContext`
+
+Everything else is **experimental** and tagged `@experimental` in the type
+declarations: Rooms methods and types, agents, approvals, moderation, `proof()`
+and the proof render, beacon and upload helpers, `RoomRealtimeClient`,
+`createSseParser` 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