@blendification/results 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.1
+
+- `TrackedConversation`, the type of what `conversations()` yields, now has the fields the server sends: `conversationId`, `respondentName` and `respondentEmail`. 0.1.0 declared `id`, `name` and `email`, which were always undefined. The type also gains `abandoned`, `templateId` and the conversation's dates. It drops the catch-all index signature, so a misspelt field no longer compiles.
+- `conversationPage()` returns a typed `ConversationPage`, and `status` accepts one status or a list.
+- The README named the same wrong fields; it now names the real ones.
+
+## 0.1.0
+
+First release.
+
+- `createResultsClient` calls Blendification's MCP tools and wraps the result reads: `progress`, `conversations`, `transcript`, `summary`, `exportGroup`, `waitForJob` and `watchProgress`.
+- `pkceSignIn` signs a page's viewer in with their Blendification account (OAuth 2.1 with PKCE). `clientCredentials` is for servers, and `staticToken` is for scripts.
+- `registerPageClient` registers a page with the sign-in service once.
+- `@blendification/results/webhooks` exports `verifyWebhookSignature`, which checks webhook deliveries.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blendification
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @blendification/results
 
-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.
+Read Blendification results from your own page or server: how a survey wave is
+going, who has finished, transcripts, results-group summaries and full exports.
+The package also verifies the webhooks Blendification sends when someone starts
+or finishes a conversation.
+
+It talks to the same MCP endpoint an AI agent uses, so a page sees what its
+owner's agent sees, through the same tenant checks.
+
+## Credentials
+
+There is no API key to paste into a page.
+
+- **A page in a browser** signs its viewer in with their Blendification account,
+  using OAuth 2.1 with PKCE. The page holds only that person's short-lived,
+  read-only token, and it renews itself.
+- **A server** (a page's backend, a CRM sync, an agent such as go-ai) uses OAuth
+  client credentials that Blendification issues for one company. Keep the
+  secret on the server.
+
+## A results page
+
+**1. Register the page once.** Do this from a terminal or a script, not on every
+page load. It needs the exact address the sign-in should come back to.
+
+```js
+import { registerPageClient } from '@blendification/results';
+
+const { clientId } = await registerPageClient({
+  mcpUrl: 'https://<mcp host>/mcp',              // the address your MCP connection uses
+  redirectUris: ['https://your-site.example/results'],
+  clientName: 'Acme results page',
+});
+```
+
+The client id is not a secret. Put it in the page's config.
+
+**2. Sign the viewer in, then read.**
+
+```js
+import { createResultsClient, pkceSignIn } from '@blendification/results';
+
+const auth = pkceSignIn({ clientId: '<client id>', redirectUri: 'https://your-site.example/results' });
+const results = createResultsClient({ mcpUrl: 'https://<mcp host>/mcp', auth });
+
+await auth.handleRedirect();               // call on every load; it ignores a URL that has no sign-in answer
+if (!auth.isSignedIn()) {
+  showSignInButton(() => auth.signIn());   // sends the viewer to Blendification's sign-in page
+} else {
+  const p = await results.progress({ templateId: '<template id>' });
+  render(`${p.complete} of ${p.total} finished (${p.completionRatePercent}%)`);
+}
+```
+
+`auth.viewer()` gives the signed-in person's email and name, for display.
+`auth.signOut()` forgets the page's tokens.
+
+## A server
+
+```js
+import { createResultsClient, clientCredentials } from '@blendification/results';
+
+const results = createResultsClient({
+  mcpUrl: process.env.BLENDIFICATION_MCP_URL,
+  auth: clientCredentials({
+    clientId: process.env.BLENDIFICATION_CLIENT_ID,
+    clientSecret: process.env.BLENDIFICATION_CLIENT_SECRET,
+    scope: 'mcp/read',                     // or 'mcp/read mcp/write' if the client was issued both
+  }),
+});
+```
+
+`clientCredentials` refuses to run in a browser.
+
+## Reading
+
+| Call | What it returns |
+| --- | --- |
+| `progress({ templateId?, inviteGroupName?, since? })` | Status counts, completion rate, and splits by invite group or template, read to the end and added up |
+| `conversations({ templateId?, inviteGroupName?, status?, since? })` | An async iterator over every conversation: `conversationId`, `status`, `abandoned`, `respondentName`, `respondentEmail`, `inviteGroup`, `link`, and its dates (`startedAt`, `completedAt`) |
+| `transcript(conversationId, { resultsGroupId })` | Every message, oldest first |
+| `summary(resultsGroupId)` | A results group's name, counts, topics and reports |
+| `exportGroup(resultsGroupId, { format: 'csv' })` | Starts an export, waits for it, and returns download links plus the first page |
+| `watchProgress(args, { onUpdate, intervalMs })` | Polls `progress` and calls `onUpdate` when the counts change. Returns `stop()` |
+| `call(tool, args)` | Any MCP tool the token may use |
+
+## Webhooks
+
+Register a webhook over MCP (`webhook_create`) to have Blendification POST to
+your server when a conversation starts or completes. Verify every delivery
+before trusting it. Pass the raw body, before JSON parsing.
+
+```js
+import { verifyWebhookSignature } from '@blendification/results/webhooks';
+
+app.post('/hooks/blendification', express.raw({ type: 'application/json' }), (req, res) => {
+  const ok = verifyWebhookSignature({
+    secret: process.env.BLENDIFICATION_WEBHOOK_SECRET,
+    header: req.headers['blendification-signature'],
+    body: req.body,
+  });
+  if (!ok) return res.status(400).end();
+  const event = JSON.parse(req.body);        // { id, type, createdAt, data: { conversationId, templateId, ... } }
+  res.status(200).end();                     // answer fast; do slow work afterwards
+});
+```
+
+The event `id` is stable. Ignore an id you have already handled. A delivery
+that fails is retried for about 45 minutes. If 25 events in a row fail, the
+webhook is switched off, and `webhook_list` shows why.

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@blendification/results",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Read Blendification results (survey progress, conversations, transcripts, exports) from your own page or server, signed in with Blendification's OAuth, and verify the webhooks it sends.",
+  "license": "MIT",
+  "author": "Blendification",
+  "homepage": "https://github.com/blendification/blendification-platform/tree/main/packages/results-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blendification/blendification-platform.git",
+    "directory": "packages/results-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/blendification/blendification-platform/issues"
+  },
+  "keywords": [
+    "blendification",
+    "results",
+    "survey",
+    "mcp",
+    "oauth",
+    "webhooks"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./webhooks": {
+      "types": "./types/webhooks.d.ts",
+      "default": "./src/webhooks.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lint": "echo \"results: no lint configured yet\" && exit 0",
+    "test": "node --test test/*.test.js",
+    "check": "node --check src/index.js && node --check src/client.js && node --check src/auth.js && node --check src/webhooks.js"
+  },
+  "types": "types/index.d.ts"
+}

package/src/auth.js

@@ -0,0 +1,342 @@
+/**
+ * How a results page or service proves who it is to Blendification.
+ *
+ * There is no API key. A page in a browser signs its viewer in with their
+ * Blendification account (OAuth 2.1 authorization code with PKCE, the same
+ * sign-in MCP clients use) and holds only that person's short-lived token. A
+ * server (a page's backend, a CRM sync, an agent) uses OAuth client credentials
+ * issued by Blendification for that purpose. Either way the token carries the
+ * scope it was granted, and a read-only token reaches only the read tools.
+ *
+ * Works in browsers and in Node 18+ (fetch, Web Crypto and URL are global in both).
+ */
+
+export const DEFAULT_PAGE_SCOPE = 'openid mcp/read';
+export const DEFAULT_SERVICE_SCOPE = 'mcp/read';
+const EXPIRY_MARGIN_MS = 60_000;
+/** OAuth errors that mean the refresh token will never work again. */
+const DEAD_REFRESH_ERRORS = new Set(['invalid_grant', 'invalid_client', 'unauthorized_client']);
+
+export class ResultsAuthError extends Error {
+  constructor(message, { code = 'not_signed_in', cause } = {}) {
+    super(message);
+    this.name = 'ResultsAuthError';
+    this.code = code;
+    if (cause) this.cause = cause;
+  }
+}
+
+function base64url(bytes) {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function randomString(byteLength = 48) {
+  const bytes = new Uint8Array(byteLength);
+  globalThis.crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+export async function pkceChallenge(verifier) {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}
+
+/** A Storage-shaped map, for Node and for tests. */
+export function memoryStorage() {
+  const m = new Map();
+  return {
+    getItem: (k) => (m.has(k) ? m.get(k) : null),
+    setItem: (k, v) => { m.set(k, String(v)); },
+    removeItem: (k) => { m.delete(k); },
+  };
+}
+
+/** The OAuth server metadata a Blendification MCP endpoint advertises. */
+export async function discoverAuthServer(mcpUrl, fetchFn) {
+  const origin = new URL(mcpUrl).origin;
+  const res = await fetchFn(`${origin}/.well-known/oauth-authorization-server`, { headers: { accept: 'application/json' } });
+  if (!res.ok) throw new ResultsAuthError(`Could not read the sign-in settings from ${origin} (HTTP ${res.status}).`, { code: 'discovery_failed' });
+  const meta = await res.json();
+  if (!meta?.token_endpoint) throw new ResultsAuthError(`${origin} did not advertise a token endpoint.`, { code: 'discovery_failed' });
+  return meta;
+}
+
+async function postForm(fetchFn, url, form, headers = {}) {
+  const res = await fetchFn(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json', ...headers },
+    body: new URLSearchParams(form).toString(),
+  });
+  let json = null;
+  try { json = await res.json(); } catch { /* not JSON */ }
+  if (!res.ok || !json?.access_token) {
+    const reason = json?.error_description || json?.error || `HTTP ${res.status}`;
+    throw new ResultsAuthError(`The token request was refused: ${reason}.`, { code: json?.error || 'token_refused' });
+  }
+  return json;
+}
+
+function toStored(tokens, previous = null, now = Date.now()) {
+  return {
+    access_token: tokens.access_token,
+    refresh_token: tokens.refresh_token || previous?.refresh_token || null,
+    id_token: tokens.id_token || previous?.id_token || null,
+    scope: tokens.scope || previous?.scope || null,
+    expires_at: now + (Number(tokens.expires_in) || 3600) * 1000,
+  };
+}
+
+/** The claims of a JWT, unverified. For display (who is signed in), never for trust. */
+export function readJwtClaims(token) {
+  try {
+    const part = String(token).split('.')[1];
+    const binary = atob(part.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(part.length / 4) * 4, '='));
+    return JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0))));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sign the page's viewer in with their Blendification account.
+ *
+ * Register the page once (registerPageClient, or POST /register on the MCP
+ * host) with its redirect URI, and pass the client id it returns. The client id
+ * is not a secret; it only names the page to the sign-in service.
+ *
+ * @param {object} opts
+ * @param {string} opts.clientId
+ * @param {string} opts.redirectUri - exactly as registered
+ * @param {string} [opts.scope] - default "openid mcp/read" (read-only)
+ * @param {Storage} [opts.storage] - where tokens live (default localStorage, else memory)
+ * @param {Storage} [opts.sessionStorage] - where the in-flight sign-in lives (default sessionStorage)
+ * @param {string} [opts.keyPrefix]
+ * @param {(url: string) => void} [opts.navigate] - default location.assign
+ */
+export function pkceSignIn(opts = {}) {
+  const { clientId, redirectUri } = opts;
+  if (!clientId) throw new ResultsAuthError('pkceSignIn needs clientId.', { code: 'config' });
+  if (!redirectUri) throw new ResultsAuthError('pkceSignIn needs redirectUri.', { code: 'config' });
+  const scope = opts.scope || DEFAULT_PAGE_SCOPE;
+  const prefix = opts.keyPrefix || `blendification.results.${clientId}`;
+  const store = opts.storage || globalThis.localStorage || memoryStorage();
+  const pending = opts.sessionStorage || globalThis.sessionStorage || store;
+  const navigate = opts.navigate || ((url) => globalThis.location.assign(url));
+  const TOKENS = `${prefix}.tokens`;
+  const FLIGHT = `${prefix}.signin`;
+  // Set by createResultsClient; given here too so handleRedirect can run before the client exists.
+  let fetchFn = opts.fetch || globalThis.fetch?.bind(globalThis) || null;
+  let mcpUrl = opts.mcpUrl || null;
+  let meta = null;
+  let refreshing = null;
+  const listeners = new Set();
+
+  const metadata = async () => {
+    if (!meta) {
+      if (!opts.authServer && !mcpUrl) {
+        throw new ResultsAuthError('pkceSignIn does not know the MCP address yet: pass mcpUrl, or create the results client first.', { code: 'config' });
+      }
+      meta = opts.authServer || await discoverAuthServer(mcpUrl, fetchFn);
+    }
+    return meta;
+  };
+  const read = () => {
+    try { return JSON.parse(store.getItem(TOKENS) || 'null'); } catch { return null; }
+  };
+  const write = (value) => {
+    if (value) store.setItem(TOKENS, JSON.stringify(value)); else store.removeItem(TOKENS);
+    for (const fn of listeners) { try { fn(Boolean(value)); } catch { /* a listener's problem */ } }
+  };
+
+  return {
+    kind: 'pkce',
+    scope,
+    attach(ctx) { fetchFn = ctx.fetch || fetchFn; mcpUrl = ctx.mcpUrl || mcpUrl; },
+
+    /** Send the viewer to the Blendification sign-in page. Resolves only if navigation is stubbed. */
+    async signIn({ returnTo } = {}) {
+      const m = await metadata();
+      if (!m.authorization_endpoint) throw new ResultsAuthError('The sign-in service advertised no authorization endpoint.', { code: 'discovery_failed' });
+      const verifier = randomString(48);
+      const state = randomString(16);
+      pending.setItem(FLIGHT, JSON.stringify({ verifier, state, returnTo: returnTo ?? globalThis.location?.href ?? null, at: Date.now() }));
+      const u = new URL(m.authorization_endpoint);
+      u.search = new URLSearchParams({
+        response_type: 'code',
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        scope,
+        state,
+        code_challenge: await pkceChallenge(verifier),
+        code_challenge_method: 'S256',
+      }).toString();
+      navigate(u.toString());
+      return u.toString();
+    },
+
+    /**
+     * Finish a sign-in when the page loads at its redirect URI. Call it on every
+     * load; it does nothing when the URL carries no sign-in answer.
+     * @returns {Promise<{ handled: boolean, signedIn: boolean, returnTo?: string|null }>}
+     */
+    async handleRedirect({ url = globalThis.location?.href, cleanUrl = true } = {}) {
+      const untouched = { handled: false, signedIn: Boolean(read()) };
+      if (!url) return untouched;
+      const u = new URL(url);
+      const target = new URL(redirectUri);
+      const error = u.searchParams.get('error');
+      const code = u.searchParams.get('code');
+      const state = u.searchParams.get('state');
+      // Only the redirect page, and only while a sign-in this page started is
+      // pending: any other ?code= or ?error= belongs to someone else and is left alone.
+      if (u.origin !== target.origin || u.pathname !== target.pathname || (!code && !error)) return untouched;
+      let flight = null;
+      try { flight = JSON.parse(pending.getItem(FLIGHT) || 'null'); } catch { /* none */ }
+      if (!flight) return untouched;
+      pending.removeItem(FLIGHT);
+      if (cleanUrl && globalThis.history?.replaceState) {
+        ['code', 'state', 'error', 'error_description'].forEach((k) => u.searchParams.delete(k));
+        globalThis.history.replaceState(globalThis.history.state, '', u.toString());
+      }
+      if (error) throw new ResultsAuthError(`Sign-in was not completed: ${u.searchParams.get('error_description') || error}.`, { code: error });
+      if (!flight || flight.state !== state) {
+        throw new ResultsAuthError('This sign-in answer does not match a sign-in this page started; start again.', { code: 'state_mismatch' });
+      }
+      const m = await metadata();
+      const tokens = await postForm(fetchFn, m.token_endpoint, {
+        grant_type: 'authorization_code',
+        client_id: clientId,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: flight.verifier,
+      });
+      write(toStored(tokens));
+      return { handled: true, signedIn: true, returnTo: flight.returnTo ?? null };
+    },
+
+    isSignedIn() {
+      const t = read();
+      return Boolean(t && (t.refresh_token || t.expires_at > Date.now()));
+    },
+
+    /** Who is signed in, from the id token (unverified, for display). */
+    viewer() {
+      const claims = readJwtClaims(read()?.id_token);
+      return claims ? { email: claims.email ?? null, name: claims.name ?? claims['cognito:username'] ?? null, sub: claims.sub ?? null } : null;
+    },
+
+    canRefresh() { return Boolean(read()?.refresh_token); },
+
+    async getAccessToken({ forceRefresh = false } = {}) {
+      const t = read();
+      if (!t) throw new ResultsAuthError('Not signed in. Call signIn() first.');
+      if (!forceRefresh && t.expires_at - EXPIRY_MARGIN_MS > Date.now()) return t.access_token;
+      if (!t.refresh_token) { write(null); throw new ResultsAuthError('The sign-in has expired. Sign in again.', { code: 'expired' }); }
+      if (!refreshing) {
+        refreshing = (async () => {
+          const m = await metadata();
+          try {
+            const tokens = await postForm(fetchFn, m.token_endpoint, { grant_type: 'refresh_token', client_id: clientId, refresh_token: t.refresh_token });
+            write(toStored(tokens, t));
+          } catch (err) {
+            // Only a refusal of the refresh token itself ends the sign-in. A
+            // network blip or the sign-in service's 5xx keeps it, to try again.
+            if (err instanceof ResultsAuthError && DEAD_REFRESH_ERRORS.has(err.code)) {
+              write(null);
+              throw new ResultsAuthError('The sign-in could not be renewed. Sign in again.', { code: 'expired', cause: err });
+            }
+            throw new ResultsAuthError('The sign-in could not be renewed just now (the network or the sign-in service failed); try again.', { code: 'refresh_failed', cause: err });
+          }
+        })().finally(() => { refreshing = null; });
+      }
+      await refreshing;
+      return read().access_token;
+    },
+
+    /** Forget this page's tokens. The Blendification session itself is not ended. */
+    signOut() { write(null); },
+
+    /** Called with true or false whenever the signed-in state changes. Returns an unsubscribe function. */
+    onChange(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+  };
+}
+
+/**
+ * OAuth client credentials, for a server. Never use this in a browser: the
+ * secret would be in every visitor's hands. Blendification issues the client
+ * id and secret for one company and one scope.
+ *
+ * @param {{ clientId: string, clientSecret: string, scope?: string, tokenEndpoint?: string }} opts
+ */
+export function clientCredentials(opts = {}) {
+  const { clientId, clientSecret } = opts;
+  if (!clientId || !clientSecret) throw new ResultsAuthError('clientCredentials needs clientId and clientSecret.', { code: 'config' });
+  if (typeof globalThis.window !== 'undefined' && typeof globalThis.document !== 'undefined' && !opts.allowInBrowser) {
+    throw new ResultsAuthError('clientCredentials is for servers; a browser page must use pkceSignIn.', { code: 'config' });
+  }
+  const scope = opts.scope || DEFAULT_SERVICE_SCOPE;
+  let fetchFn = null;
+  let mcpUrl = null;
+  let cached = null;
+  let inflight = null;
+  return {
+    kind: 'client_credentials',
+    scope,
+    attach(ctx) { fetchFn = ctx.fetch; mcpUrl = ctx.mcpUrl; },
+    canRefresh() { return true; },
+    isSignedIn() { return true; },
+    async getAccessToken({ forceRefresh = false } = {}) {
+      if (!forceRefresh && cached && cached.expires_at - EXPIRY_MARGIN_MS > Date.now()) return cached.access_token;
+      if (!inflight) {
+        inflight = (async () => {
+          const endpoint = opts.tokenEndpoint || (await discoverAuthServer(mcpUrl, fetchFn)).token_endpoint;
+          const tokens = await postForm(fetchFn, endpoint, { grant_type: 'client_credentials', scope }, {
+            authorization: `Basic ${btoa(`${clientId}:${clientSecret}`)}`,
+          });
+          cached = toStored(tokens);
+        })().finally(() => { inflight = null; });
+      }
+      await inflight;
+      return cached.access_token;
+    },
+  };
+}
+
+/** A token you already hold (a test, a script). It is never renewed. */
+export function staticToken(token) {
+  if (!token) throw new ResultsAuthError('staticToken needs a token.', { code: 'config' });
+  return {
+    kind: 'static',
+    attach() {},
+    canRefresh() { return false; },
+    isSignedIn() { return true; },
+    async getAccessToken() { return token; },
+  };
+}
+
+/**
+ * Register a page with the sign-in service once, and get its client id. Run it
+ * from a script or a terminal, not on every page load: registrations are
+ * rate-limited and each one is a permanent record.
+ *
+ * @param {{ mcpUrl: string, redirectUris: string[], clientName?: string, fetch?: Function }} opts
+ * @returns {Promise<{ clientId: string, redirectUris: string[], raw: object }>}
+ */
+export async function registerPageClient({ mcpUrl, redirectUris, clientName = 'Blendification results page', fetch: f = globalThis.fetch } = {}) {
+  if (!mcpUrl) throw new ResultsAuthError('registerPageClient needs mcpUrl.', { code: 'config' });
+  if (!Array.isArray(redirectUris) || !redirectUris.length) throw new ResultsAuthError('registerPageClient needs redirectUris.', { code: 'config' });
+  const meta = await discoverAuthServer(mcpUrl, f);
+  const endpoint = meta.registration_endpoint || `${new URL(mcpUrl).origin}/register`;
+  const res = await f(endpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify({ client_name: clientName, redirect_uris: redirectUris, grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'none' }),
+  });
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json?.client_id) {
+    throw new ResultsAuthError(`Registration was refused: ${json?.error_description || json?.error || `HTTP ${res.status}`}.`, { code: json?.error || 'registration_refused' });
+  }
+  return { clientId: json.client_id, redirectUris: json.redirect_uris || redirectUris, raw: json };
+}

package/src/client.js

@@ -0,0 +1,242 @@
+/**
+ * The results client: calls Blendification's MCP tools over JSON-RPC and wraps
+ * the ones a results page needs.
+ *
+ * It speaks to the same /mcp endpoint an AI agent does, so a page sees exactly
+ * what its owner's agent sees, through the same tenant checks, and a read-only
+ * token reaches only the read tools.
+ */
+import { ResultsAuthError } from './auth.js';
+
+export const PROTOCOL_VERSION = '2025-06-18';
+
+export class ResultsError extends Error {
+  constructor(message, { code = null, tool = null, status = null } = {}) {
+    super(message);
+    this.name = 'ResultsError';
+    this.code = code;
+    this.tool = tool;
+    this.status = status;
+  }
+}
+
+function parseRpcBody(text, contentType = '') {
+  if (/text\/event-stream/i.test(contentType)) {
+    // The last JSON-RPC message in the stream is the answer.
+    const messages = text.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).filter(Boolean);
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+      try {
+        const m = JSON.parse(messages[i]);
+        if (m && (m.result !== undefined || m.error)) return m;
+      } catch { /* keep looking */ }
+    }
+    throw new ResultsError('The server answered with an event stream that held no result.');
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ResultsError(`The server answered with something that is not JSON: ${text.slice(0, 120)}`);
+  }
+}
+
+/** Add one page of template_invite_progress to a running total. */
+export function mergeProgress(total, page) {
+  const keys = ['total', 'notStarted', 'started', 'complete', 'abandoned'];
+  const out = total ? { ...total } : { templateId: page.templateId ?? null, templateName: page.templateName ?? null, inviteGroupName: page.inviteGroupName ?? null, since: page.since ?? null };
+  for (const k of keys) out[k] = (out[k] || 0) + (Number(page[k]) || 0);
+  const minOf = (a, b) => (!a ? b ?? null : !b ? a : a < b ? a : b);
+  const maxOf = (a, b) => (!a ? b ?? null : !b ? a : a > b ? a : b);
+  out.firstConversationDate = minOf(out.firstConversationDate, page.firstConversationDate);
+  out.lastStartedAt = maxOf(out.lastStartedAt, page.lastStartedAt);
+  out.lastCompletedAt = maxOf(out.lastCompletedAt, page.lastCompletedAt);
+  for (const [list, key] of [['byInviteGroup', 'inviteGroup'], ['byTemplate', 'templateId']]) {
+    if (!Array.isArray(page[list])) continue;
+    const merged = new Map((out[list] || []).map((b) => [b[key] ?? '', { ...b }]));
+    for (const b of page[list]) {
+      const id = b[key] ?? '';
+      const cur = merged.get(id) || { [key]: b[key] ?? null, total: 0, notStarted: 0, started: 0, complete: 0, abandoned: 0 };
+      for (const k of keys) cur[k] = (cur[k] || 0) + (Number(b[k]) || 0);
+      merged.set(id, cur);
+    }
+    out[list] = [...merged.values()]
+      .map((b) => ({ ...b, completionRatePercent: b.total ? Math.round((b.complete / b.total) * 1000) / 10 : null }))
+      .sort((a, b) => b.total - a.total);
+  }
+  out.completionRatePercent = out.total ? Math.round((out.complete / out.total) * 1000) / 10 : null;
+  return out;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * @param {object} opts
+ * @param {string} opts.mcpUrl - the MCP endpoint, e.g. https://<host>/mcp
+ * @param {object} opts.auth - pkceSignIn(...), clientCredentials(...), staticToken(...), or { getAccessToken }
+ * @param {Function} [opts.fetch]
+ */
+export function createResultsClient(opts = {}) {
+  const { mcpUrl, auth } = opts;
+  if (!mcpUrl) throw new ResultsError('createResultsClient needs mcpUrl (the /mcp address your connection uses).');
+  try { new URL(mcpUrl); } catch { throw new ResultsError(`mcpUrl is not a URL: ${mcpUrl}`); }
+  if (!auth || typeof auth.getAccessToken !== 'function') throw new ResultsError('createResultsClient needs auth: pkceSignIn(), clientCredentials() or staticToken().');
+  const fetchFn = opts.fetch || globalThis.fetch?.bind(globalThis);
+  if (!fetchFn) throw new ResultsError('No fetch is available; pass opts.fetch.');
+  auth.attach?.({ mcpUrl, fetch: fetchFn });
+  let rpcId = 0;
+
+  async function rpc(method, params, retried = false) {
+    const token = await auth.getAccessToken();
+    const res = await fetchFn(mcpUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+        'mcp-protocol-version': PROTOCOL_VERSION,
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({ jsonrpc: '2.0', id: ++rpcId, method, params }),
+    });
+    if (res.status === 401) {
+      if (!retried && auth.canRefresh?.()) {
+        await auth.getAccessToken({ forceRefresh: true });
+        return rpc(method, params, true);
+      }
+      throw new ResultsAuthError('Blendification did not accept the credentials (401). Sign in again.', { code: 'unauthorized' });
+    }
+    const text = await res.text();
+    if (!res.ok) throw new ResultsError(`The MCP endpoint answered HTTP ${res.status}: ${text.slice(0, 200)}`, { status: res.status });
+    const message = parseRpcBody(text, res.headers?.get?.('content-type') || '');
+    if (message.error) throw new ResultsError(message.error.message || 'JSON-RPC error', { code: message.error.code });
+    return message.result;
+  }
+
+  /** Call any MCP tool the token may use, and return its result. */
+  async function call(name, args = {}) {
+    const result = await rpc('tools/call', { name, arguments: args });
+    const text = Array.isArray(result?.content) ? result.content.find((c) => c?.type === 'text')?.text : null;
+    if (result?.isError) throw new ResultsError(text || `${name} failed.`, { tool: name });
+    if (result?.structuredContent !== undefined && result.structuredContent !== null) return result.structuredContent;
+    if (typeof text === 'string') {
+      try { return JSON.parse(text); } catch { return text; }
+    }
+    return null;
+  }
+
+  async function listTools() {
+    const result = await rpc('tools/list', {});
+    return result?.tools ?? [];
+  }
+
+  /** template_invite_progress, read to the end and added up. */
+  async function progress({ templateId, inviteGroupName, since } = {}) {
+    let total = null;
+    let nextToken;
+    let pages = 0;
+    do {
+      const page = await call('template_invite_progress', { templateId, inviteGroupName, since, ...(nextToken ? { nextToken } : {}) });
+      total = mergeProgress(total, page);
+      nextToken = page?.nextToken || null;
+      pages += 1;
+    } while (nextToken && pages < 200);
+    return { ...total, complete: total.complete, pages, finished: !nextToken };
+  }
+
+  /** One page of list_template_conversations. */
+  function conversationPage(args = {}) {
+    return call('list_template_conversations', args);
+  }
+
+  /** Every conversation of a template and/or invite group, page by page. */
+  async function* conversations({ templateId, inviteGroupName, status, since, limit } = {}) {
+    let nextToken;
+    let pages = 0;
+    do {
+      const page = await conversationPage({ templateId, inviteGroupName, status, since, limit, ...(nextToken ? { nextToken } : {}) });
+      for (const row of page?.conversations || page?.items || []) yield row;
+      nextToken = page?.nextToken || null;
+      pages += 1;
+    } while (nextToken && pages < 1000);
+  }
+
+  /** A conversation's messages, oldest first, every page. resultsGroupId is the group it was read through. */
+  async function transcript(conversationId, { resultsGroupId, limit = 100 } = {}) {
+    if (!resultsGroupId) throw new ResultsError('transcript needs resultsGroupId: messages are read through the results group that holds the conversation.');
+    const messages = [];
+    let nextToken;
+    let last = null;
+    let pages = 0;
+    do {
+      last = await call('get_conversation_messages', { resultsGroupId, conversationId, limit, ...(nextToken ? { nextToken } : {}) });
+      messages.push(...(last?.messages || []));
+      nextToken = last?.nextToken || null;
+      pages += 1;
+    } while (nextToken && pages < 100);
+    return { conversationId, messages, complete: !nextToken };
+  }
+
+  /** Wait for a background job (an export, an analysis) to finish. */
+  async function waitForJob(jobId, { intervalMs = 3000, timeoutMs = 10 * 60_000, onUpdate } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const status = await call('fusion_job_status', { jobId });
+      onUpdate?.(status);
+      const state = String(status?.status || '').toLowerCase();
+      // done, or partial (finished with some parts missing; the status says which).
+      if (state === 'done' || state === 'partial') return status;
+      if (state === 'error' || state === 'failed' || state === 'not_found') {
+        throw new ResultsError(status?.error || `Job ${jobId} ended as ${state}.`, { code: state });
+      }
+      if (Date.now() + intervalMs > deadline) throw new ResultsError(`Job ${jobId} was still running after ${Math.round(timeoutMs / 1000)} s.`, { code: 'timeout' });
+      await sleep(intervalMs);
+    }
+  }
+
+  /** Export a results group and return its download links and first page. */
+  async function exportGroup(resultsGroupId, { format = 'csv', conversationIds, includeMessages, includeFeatures, waitMs } = {}) {
+    const started = await call('export_results_group', { resultsGroupId, format, conversationIds, includeMessages, includeFeatures });
+    const jobId = started?.jobId;
+    if (!jobId) throw new ResultsError('export_results_group returned no jobId.', { tool: 'export_results_group' });
+    await waitForJob(jobId, waitMs ? { timeoutMs: waitMs } : {});
+    return call('get_results_group_export', { jobId });
+  }
+
+  /**
+   * Poll progress and call onUpdate when it changes. A page uses this for a
+   * live counter; a server that must react at once should use webhooks.
+   * @returns {() => void} stop
+   */
+  function watchProgress(args, { intervalMs = 30_000, onUpdate, onError } = {}) {
+    let stopped = false;
+    let lastKey = null;
+    const tick = async () => {
+      if (stopped) return;
+      try {
+        const p = await progress(args);
+        const key = JSON.stringify([p.total, p.notStarted, p.started, p.complete, p.abandoned]);
+        if (key !== lastKey) { lastKey = key; onUpdate?.(p); }
+      } catch (err) {
+        onError?.(err);
+      }
+      if (!stopped) setTimeout(tick, Math.max(5000, intervalMs));
+    };
+    tick();
+    return () => { stopped = true; };
+  }
+
+  return {
+    auth,
+    mcpUrl,
+    call,
+    listTools,
+    progress,
+    conversationPage,
+    conversations,
+    transcript,
+    waitForJob,
+    exportGroup,
+    watchProgress,
+    summary: (resultsGroupId) => call('get_results_group_summary', { resultsGroupId }),
+    resultsGroups: (args = {}) => call('list_results_groups', args),
+    templates: (args = {}) => call('list_survey_templates', args),
+  };
+}

package/src/index.js

@@ -0,0 +1,26 @@
+/**
+ * @blendification/results: read Blendification results from your own page or
+ * server, and verify the webhooks it sends.
+ *
+ *   import { createResultsClient, pkceSignIn } from '@blendification/results';
+ *   const auth = pkceSignIn({ clientId: '<registered client id>', redirectUri: location.origin + '/results' });
+ *   const results = createResultsClient({ mcpUrl: 'https://<host>/mcp', auth });
+ *   await auth.handleRedirect();
+ *   if (!auth.isSignedIn()) await auth.signIn();
+ *   const progress = await results.progress({ templateId: '<template id>' });
+ *
+ * Webhook verification is in '@blendification/results/webhooks' (Node only).
+ */
+export { createResultsClient, mergeProgress, ResultsError, PROTOCOL_VERSION } from './client.js';
+export {
+  pkceSignIn,
+  clientCredentials,
+  staticToken,
+  registerPageClient,
+  discoverAuthServer,
+  memoryStorage,
+  readJwtClaims,
+  ResultsAuthError,
+  DEFAULT_PAGE_SCOPE,
+  DEFAULT_SERVICE_SCOPE,
+} from './auth.js';

package/src/webhooks.js

@@ -0,0 +1,44 @@
+/**
+ * Check that a webhook delivery came from Blendification. Node only (it uses
+ * node:crypto), so it is its own entry point: @blendification/results/webhooks.
+ *
+ * Pass the RAW request body, exactly as received, before any JSON parsing:
+ * re-serialised JSON will not match the signature.
+ *
+ *   import { verifyWebhookSignature } from '@blendification/results/webhooks';
+ *   const ok = verifyWebhookSignature({
+ *     secret: process.env.BLENDIFICATION_WEBHOOK_SECRET,
+ *     header: req.headers['blendification-signature'],
+ *     body: rawBody,
+ *   });
+ *
+ * The same rule as the sender (packages/shared-data/src/webhooks.js); a test
+ * pins the two together.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export const SIGNATURE_HEADER = 'blendification-signature';
+
+export function signWebhookPayload(secret, body, timestamp = Math.floor(Date.now() / 1000)) {
+  const mac = createHmac('sha256', String(secret)).update(`${timestamp}.${body}`).digest('hex');
+  return `t=${timestamp},v1=${mac}`;
+}
+
+/**
+ * @param {{ secret: string, header: string, body: string|Buffer, toleranceSeconds?: number, now?: number }} input
+ * @returns {boolean}
+ */
+export function verifyWebhookSignature({ secret, header, body, toleranceSeconds = 300, now = Date.now() }) {
+  const raw = Buffer.isBuffer(body) ? body.toString('utf8') : body;
+  if (!secret || typeof header !== 'string' || typeof raw !== 'string') return false;
+  const parts = Object.fromEntries(header.split(',').map((kv) => {
+    const i = kv.indexOf('=');
+    return i < 0 ? [kv.trim(), ''] : [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
+  }));
+  const t = Number(parts.t);
+  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 || '')) return false;
+  if (Math.abs(Math.floor(now / 1000) - t) > toleranceSeconds) return false;
+  const expected = Buffer.from(signWebhookPayload(secret, raw, t).split('v1=')[1], 'hex');
+  const given = Buffer.from(parts.v1, 'hex');
+  return expected.length === given.length && timingSafeEqual(expected, given);
+}

package/types/index.d.ts

@@ -0,0 +1,167 @@
+export declare const PROTOCOL_VERSION: string;
+export declare const DEFAULT_PAGE_SCOPE: string;
+export declare const DEFAULT_SERVICE_SCOPE: string;
+
+export declare class ResultsError extends Error {
+  code: string | number | null;
+  tool: string | null;
+  status: number | null;
+}
+export declare class ResultsAuthError extends Error {
+  code: string;
+}
+
+export interface StorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+export interface AuthProvider {
+  kind: 'pkce' | 'client_credentials' | 'static' | string;
+  attach?(ctx: { mcpUrl: string; fetch: typeof fetch }): void;
+  getAccessToken(opts?: { forceRefresh?: boolean }): Promise<string>;
+  canRefresh?(): boolean;
+  isSignedIn?(): boolean;
+}
+
+export interface PkceSignIn extends AuthProvider {
+  kind: 'pkce';
+  scope: string;
+  signIn(opts?: { returnTo?: string }): Promise<string>;
+  handleRedirect(opts?: { url?: string; cleanUrl?: boolean }): Promise<{ handled: boolean; signedIn: boolean; returnTo?: string | null }>;
+  isSignedIn(): boolean;
+  viewer(): { email: string | null; name: string | null; sub: string | null } | null;
+  signOut(): void;
+  onChange(listener: (signedIn: boolean) => void): () => void;
+}
+
+export interface AuthServerMetadata {
+  authorization_endpoint?: string;
+  token_endpoint: string;
+  registration_endpoint?: string;
+  [key: string]: unknown;
+}
+
+export declare function pkceSignIn(opts: {
+  clientId: string;
+  redirectUri: string;
+  scope?: string;
+  storage?: StorageLike;
+  sessionStorage?: StorageLike;
+  keyPrefix?: string;
+  navigate?: (url: string) => void;
+  authServer?: AuthServerMetadata;
+  mcpUrl?: string;
+  fetch?: typeof fetch;
+}): PkceSignIn;
+
+export declare function clientCredentials(opts: {
+  clientId: string;
+  clientSecret: string;
+  scope?: string;
+  tokenEndpoint?: string;
+  allowInBrowser?: boolean;
+}): AuthProvider;
+
+export declare function staticToken(token: string): AuthProvider;
+
+export declare function registerPageClient(opts: {
+  mcpUrl: string;
+  redirectUris: string[];
+  clientName?: string;
+  fetch?: typeof fetch;
+}): Promise<{ clientId: string; redirectUris: string[]; raw: Record<string, unknown> }>;
+
+export declare function discoverAuthServer(mcpUrl: string, fetchFn: typeof fetch): Promise<AuthServerMetadata>;
+export declare function memoryStorage(): StorageLike;
+export declare function readJwtClaims(token: string): Record<string, unknown> | null;
+
+export interface ProgressCounts {
+  total: number;
+  notStarted: number;
+  started: number;
+  complete: number;
+  abandoned: number;
+  completionRatePercent: number | null;
+  firstConversationDate?: string | null;
+  lastStartedAt?: string | null;
+  lastCompletedAt?: string | null;
+}
+
+export interface Progress extends ProgressCounts {
+  templateId: string | null;
+  templateName: string | null;
+  inviteGroupName: string | null;
+  since: string | null;
+  byInviteGroup?: Array<ProgressCounts & { inviteGroup: string | null }>;
+  byTemplate?: Array<ProgressCounts & { templateId: string | null }>;
+  pages: number;
+  finished: boolean;
+}
+
+export interface ScopeArgs {
+  templateId?: string;
+  inviteGroupName?: string;
+  since?: string;
+}
+
+export type ConversationStatus = 'not started' | 'started' | 'complete';
+
+/**
+ * One conversation, as conversations() yields it and conversationPage() lists
+ * it (the list_template_conversations tool). A drift test in
+ * services/analysis-engine pins these names to the rows the server builds.
+ */
+export interface TrackedConversation {
+  conversationId: string;
+  /** 'not started', 'started' or 'complete'. */
+  status: string | null;
+  /** Started, then left without completing. */
+  abandoned: boolean;
+  /** Null for an anonymous conversation. */
+  respondentName: string | null;
+  /** Lower-cased. Null for an anonymous conversation. */
+  respondentEmail: string | null;
+  inviteGroup: string | null;
+  templateId: string | null;
+  interviewDate: string | null;
+  createdAt: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  /** The participant's link: the template's hosted page when it names one, else the app's page. */
+  link: string | null;
+}
+
+/** One page of list_template_conversations. */
+export interface ConversationPage {
+  templateId: string | null;
+  templateName: string | null;
+  inviteGroupName: string | null;
+  status: ConversationStatus[] | null;
+  since: string | null;
+  returned: number;
+  conversations: TrackedConversation[];
+  nextToken: string | null;
+  message: string;
+}
+
+export interface ResultsClient {
+  auth: AuthProvider;
+  mcpUrl: string;
+  call<T = any>(tool: string, args?: Record<string, unknown>): Promise<T>;
+  listTools(): Promise<Array<{ name: string; description: string; inputSchema: object }>>;
+  progress(args: ScopeArgs): Promise<Progress>;
+  conversationPage(args: ScopeArgs & { status?: ConversationStatus | ConversationStatus[]; limit?: number; nextToken?: string }): Promise<ConversationPage>;
+  conversations(args: ScopeArgs & { status?: ConversationStatus | ConversationStatus[]; limit?: number }): AsyncGenerator<TrackedConversation>;
+  transcript(conversationId: string, opts: { resultsGroupId: string; limit?: number }): Promise<{ conversationId: string; messages: any[]; complete: boolean }>;
+  waitForJob(jobId: string, opts?: { intervalMs?: number; timeoutMs?: number; onUpdate?: (status: any) => void }): Promise<any>;
+  exportGroup(resultsGroupId: string, opts?: { format?: 'json' | 'csv'; conversationIds?: string[]; includeMessages?: boolean; includeFeatures?: boolean; waitMs?: number }): Promise<any>;
+  watchProgress(args: ScopeArgs, opts?: { intervalMs?: number; onUpdate?: (p: Progress) => void; onError?: (err: unknown) => void }): () => void;
+  summary(resultsGroupId: string): Promise<any>;
+  resultsGroups(args?: Record<string, unknown>): Promise<any>;
+  templates(args?: Record<string, unknown>): Promise<any>;
+}
+
+export declare function createResultsClient(opts: { mcpUrl: string; auth: AuthProvider; fetch?: typeof fetch }): ResultsClient;
+export declare function mergeProgress(total: Progress | null, page: Record<string, unknown>): Progress;

package/types/webhooks.d.ts

@@ -0,0 +1,26 @@
+export declare const SIGNATURE_HEADER: string;
+export declare function signWebhookPayload(secret: string, body: string, timestamp?: number): string;
+export declare function verifyWebhookSignature(input: {
+  secret: string;
+  header: string | undefined;
+  body: string | Buffer;
+  toleranceSeconds?: number;
+  now?: number;
+}): boolean;
+
+export interface ConversationWebhookEvent {
+  id: string;
+  type: 'conversation.started' | 'conversation.completed' | 'webhook.test';
+  createdAt: string;
+  data: {
+    conversationId?: string;
+    templateId?: string | null;
+    companyId?: string | null;
+    status?: string | null;
+    inviteGroupName?: string | null;
+    respondent?: { name: string | null; email: string | null } | null;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    [key: string]: unknown;
+  };
+}