@blendification/results 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.2.0
+
+For licensees, who run research for client companies under one billing account.
+
+- `forCompany(companyId)` returns a client that works in that company. It
+  sends the `x-blendification-company` header on every call, so one server can
+  serve several companies at once. The server refuses a call for a company you
+  cannot act in rather than running it in your own. `createResultsClient`
+  takes the same thing as a `companyId` option.
+- `createClientCompany(name)` opens a client company under your billing account
+  and returns its `companyId`.
+- `billing.overview()`, `billing.usage()` and `billing.rates()` return the
+  account (plan, cycle, balance and companies), the credits spent per company
+  and activity with AI usage split by service, and the price list. `usage`
+  takes a company, a cycle (`'all'` for all time) or a `from`/`to` window, and
+  a `Date` works as a bound.
+- Types for all of the above, pinned to what the server sends by a drift test.
+- `COMPANY_HEADER` is exported.
+
+Needs the server deployed with it. An older server answers these tools as
+unknown.
+
+## 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.

package/README.md

@@ -2,8 +2,9 @@
 
 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.
+A licensee can also open client companies, work in each, and see what the
+research cost. 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.
@@ -78,13 +79,65 @@ const results = createResultsClient({
 | 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: id, status, name, email, invite group, link |
+| `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()` |
+| `billing.overview()`, `billing.usage({ companyId?, cycleId?, from?, to? })`, `billing.rates()` | The account, credits spent per company and activity, and the price list (below) |
+| `createClientCompany(name)`, `forCompany(companyId)` | Open a client company, and a client that works in it (below) |
 | `call(tool, args)` | Any MCP tool the token may use |
 
+## Client companies and what they cost
+
+A licensee runs research for its own customers, each in a client company of its
+own. The client companies sit under the licensee's billing account, and their
+usage rolls up to it. A licensee's server can open those companies, work in any
+of them, and read what the work cost.
+
+```js
+const results = createResultsClient({ mcpUrl, auth: clientCredentials({ clientId, clientSecret, scope: 'mcp/read mcp/write' }) });
+
+const acme = await results.createClientCompany('Acme Health');   // { companyId, name, billingAccountId }
+const forAcme = results.forCompany(acme.companyId);              // every call from forAcme works in Acme
+const p = await forAcme.progress({ templateId: '<template id>' });
+
+const cycle = await results.billing.usage();                                      // this cycle, every company
+const acmeCost = await results.billing.usage({ companyId: acme.companyId });      // one company
+const november = await results.billing.usage({ from: '2026-11-01', to: '2026-11-30' });
+const account = await results.billing.overview();   // plan, cycle dates, balance, the companies on the account
+const prices = await results.billing.rates();       // credits per interview, analysis, deck, and the AI rates
+```
+
+`forCompany(id)` sends the `x-blendification-company` header on each call. That
+lets one server work for several companies at once. The server checks every
+call, and refuses one for a company you cannot act in instead of running it in
+your own. `createResultsClient({ ..., companyId })` does the same for a client
+that only ever works in one company.
+
+Spend is in credits.
+
+- `byCompany` gives each company's credits per activity: interviews started
+  and completed, analysis reports, presentations, mixed-data runs and test
+  drives.
+- `aiByService` splits AI model usage by what made the calls: the AI
+  interviewer, Ask Fusion, analysis or the knowledge graph.
+- Credits granted, expired or adjusted are listed apart in `movements` and are
+  not spend.
+- To turn credits into dollars, use the plan in `billing.overview()`. The
+  included credits come with `monthlyPriceUsd`, and the rest bill at
+  `overageRateUsdPerCredit`.
+
+Who can do what:
+
+- **Opening companies** needs a manager role on the account (Admin or Client
+  Manager) and write access.
+- **Billing** is for the account's Owner and Admins, the people who see Billing
+  in the app.
+- **A server's credentials** carry a role when Blendification issues them, so
+  ask for Admin if it should do both.
+- **An Admin of a client company** sees only their own company's spend.
+
 ## Webhooks
 
 Register a webhook over MCP (`webhook_create`) to have Blendification POST to

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blendification/results",
-  "version": "0.1.0",
-  "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.",
+  "version": "0.2.0",
+  "description": "Read Blendification results (survey progress, conversations, transcripts, exports) from your own page or server, signed in with Blendification's OAuth, open client companies and see what research costs, and verify the webhooks it sends.",
   "license": "MIT",
   "author": "Blendification",
   "homepage": "https://github.com/blendification/blendification-platform/tree/main/packages/results-sdk#readme",
@@ -19,7 +19,8 @@
     "survey",
     "mcp",
     "oauth",
-    "webhooks"
+    "webhooks",
+    "billing"
   ],
   "type": "module",
   "main": "src/index.js",

package/src/client.js

@@ -68,14 +68,31 @@ export function mergeProgress(total, page) {
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+/** The request header that names the company one call works in. */
+export const COMPANY_HEADER = 'x-blendification-company';
+
+/** A from/to bound as the server takes it: a Date becomes an ISO time, a string passes through. */
+function timeArg(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) throw new ResultsError('An invalid Date was passed as a usage window bound.');
+    return value.toISOString();
+  }
+  return String(value);
+}
+
 /**
  * @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]
+ * @param {string} [opts.companyId] - work in this company on every call (a client company under your
+ *   billing account); sent as the x-blendification-company header. forCompany() makes one per company.
  */
 export function createResultsClient(opts = {}) {
   const { mcpUrl, auth } = opts;
+  const companyId = opts.companyId === undefined || opts.companyId === null ? null : String(opts.companyId).trim();
+  if (companyId === '') throw new ResultsError('companyId is empty. Pass a company id, or leave it out to work in your own company.');
   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().');
@@ -93,6 +110,7 @@ export function createResultsClient(opts = {}) {
         accept: 'application/json, text/event-stream',
         'mcp-protocol-version': PROTOCOL_VERSION,
         authorization: `Bearer ${token}`,
+        ...(companyId ? { [COMPANY_HEADER]: companyId } : {}),
       },
       body: JSON.stringify({ jsonrpc: '2.0', id: ++rpcId, method, params }),
     });
@@ -223,9 +241,41 @@ export function createResultsClient(opts = {}) {
     return () => { stopped = true; };
   }
 
+  /**
+   * The same connection, working in another company: every call it makes names
+   * that company, and the server refuses the call if you cannot act there. The
+   * way for one backend to serve several client companies at once.
+   */
+  function forCompany(id) {
+    if (id === undefined || id === null || !String(id).trim()) throw new ResultsError('forCompany needs a company id.');
+    return createResultsClient({ ...opts, companyId: String(id).trim() });
+  }
+
+  /** Open a client company under your billing account; returns its companyId. Needs a manager role and write access. */
+  function createClientCompany(nameOrOpts) {
+    const name = typeof nameOrOpts === 'string' ? nameOrOpts : nameOrOpts?.name;
+    if (typeof name !== 'string' || !name.trim()) throw new ResultsError('createClientCompany needs a name.');
+    return call('create_client_company', { name: name.trim() });
+  }
+
+  const billing = {
+    /** The plan, the cycle, the balance and the companies on your billing account. */
+    overview: ({ limit } = {}) => call('billing_overview', { limit }),
+    /** Credits spent per company and activity, for the current cycle unless you name another window. */
+    usage: ({ companyId: forId, cycleId, from, to, limit } = {}) => call('billing_usage', {
+      companyId: forId, cycleId, from: timeArg(from), to: timeArg(to), limit,
+    }),
+    /** What each activity costs in credits, and the AI rates. */
+    rates: ({ includeModels } = {}) => call('billing_rates', { includeModels }),
+  };
+
   return {
     auth,
     mcpUrl,
+    companyId,
+    forCompany,
+    createClientCompany,
+    billing,
     call,
     listTools,
     progress,

package/src/index.js

@@ -11,7 +11,7 @@
  *
  * Webhook verification is in '@blendification/results/webhooks' (Node only).
  */
-export { createResultsClient, mergeProgress, ResultsError, PROTOCOL_VERSION } from './client.js';
+export { createResultsClient, mergeProgress, ResultsError, PROTOCOL_VERSION, COMPANY_HEADER } from './client.js';
 export {
   pkceSignIn,
   clientCredentials,

package/types/index.d.ts

@@ -106,24 +106,210 @@ export interface ScopeArgs {
   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 {
-  id: string;
-  status: string;
-  name?: string | null;
-  email?: string | null;
-  inviteGroup?: string | null;
-  link?: string | null;
-  [key: string]: unknown;
+  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;
+}
+
+/** A plan as billing_overview reports it. Credits are the unit everything is billed in. */
+export interface BillingPlan {
+  planId: string | null;
+  name: string | null;
+  monthlyPriceUsd: number | null;
+  includedCreditsPerCycle: number;
+  /** What a credit beyond the included ones costs, in USD. */
+  overageRateUsdPerCredit: number;
+  isSponsored: boolean;
+}
+
+/** A company on the billing account. */
+export interface BillingCompany {
+  companyId: string;
+  name: string | null;
+  /** The licensed company that owns the account; the others are its client companies. */
+  isLicensee: boolean;
+}
+
+/**
+ * billing_overview. A drift test in services/analysis-engine pins these names
+ * to the object the server builds.
+ */
+export interface BillingOverview {
+  billingAccountId: string | null;
+  name: string | null;
+  /** 'account': you see every company on the account; 'company': an Admin of a client company sees only their own. */
+  view: 'account' | 'company';
+  status: string | null;
+  plan: BillingPlan;
+  cycle: { id: string | null; start: string | null; end: string | null };
+  trialEnd: string | null;
+  /** Credits left. */
+  balance: number;
+  lifetimeGranted: number;
+  lifetimeDebited: number;
+  overageUnits: number;
+  enforcement: string | null;
+  licenseeCompanyId: string | null;
+  homeCompanyId: string | null;
+  /** The company this call worked in: your own, or the one forCompany() / the header named. */
+  actingCompanyId: string | null;
+  companies: BillingCompany[];
+  /** Every company on the account, even when `companies` is cut to the limit. */
+  companyCount: number;
+  companiesTruncated: boolean;
+  unit: 'credits';
+}
+
+/** Spend on one kind of activity. `type` is the ledger's key; `label` says it in words. */
+export interface UsageByType {
+  type: string;
+  label: string;
+  count: number;
+  spentCredits: number;
+}
+
+/** AI spend by the service that made the model calls (the AI interviewer, Ask Fusion, analysis, ...). */
+export interface UsageByService {
+  service: string;
+  label: string;
+  count: number;
+  spentCredits: number;
+}
+
+/** One company's spend. companyId null is spend tied to no company (account level). */
+export interface CompanyUsage {
+  companyId: string | null;
+  name: string | null;
+  spentCredits: number;
+  count: number;
+  types: UsageByType[];
+  aiByService: UsageByService[];
+}
+
+/** Credits added or removed that are not anyone's use: grants, top-ups, expiries, adjustments. Signed. */
+export interface CreditMovement {
+  type: string;
+  label: string;
+  kind: string | null;
+  count: number;
+  credits: number;
+}
+
+/** billing_usage. Only use is spend; movements are reported apart. */
+export interface BillingUsage {
+  billingAccountId: string | null;
+  view: 'account' | 'company';
+  /** The one company reported, or null for every company you can see. */
+  companyId: string | null;
+  /** Why that company: you asked, you asked for "all", the call worked in it, or the default. */
+  companyChosenBy: 'asked' | 'all' | 'acting' | 'default';
+  window: { scope: 'cycle' | 'all' | 'range' | null; cycleId: string | null; from: string | null; to: string | null };
+  unit: 'credits';
+  totals: { spentCredits: number; debitCount: number; addedCredits: number; removedCredits: number };
+  byType: UsageByType[];
+  aiByService: UsageByService[];
+  /** Largest spend first, cut to the limit; the rest are summed in otherCompanies. */
+  byCompany: CompanyUsage[];
+  otherCompanies: { count: number; spentCredits: number } | null;
+  movements: CreditMovement[];
+  entryCount: number;
+  /** True when the window held more ledger entries than one read covers: narrow it. */
+  truncated: boolean;
+}
+
+/** Credits per 1,000 input and output tokens, and per unit (a character, an audio second, an image). */
+export interface AiRate {
+  inputPer1k: number;
+  outputPer1k: number;
+  perUnit: number;
+}
+
+export interface ModelRate extends AiRate {
+  /** provider:model */
+  model: string;
+  kinds?: Record<string, Partial<AiRate>>;
+}
+
+/** billing_rates. The same for every account. */
+export interface BillingRates {
+  version: string | null;
+  unit: 'credits';
+  events: Array<{ type: string; label: string; credits: number }>;
+  aiDefault: AiRate | null;
+  modelCount: number;
+  /** Null unless includeModels was asked for. */
+  models: ModelRate[] | null;
+  roundingMode: string | null;
+}
+
+/** create_client_company's answer. */
+export interface ClientCompany {
+  companyId: string;
+  name: string;
+  billingAccountId: string | null;
+  message: string;
+}
+
+/** A from/to bound: a Date, or YYYY-MM-DD (a whole day when it ends a window), or an ISO time. */
+export type UsageBound = Date | string;
+
+export interface BillingReads {
+  overview(opts?: { limit?: number }): Promise<BillingOverview>;
+  usage(opts?: { companyId?: string | 'all'; cycleId?: string | 'all'; from?: UsageBound; to?: UsageBound; limit?: number }): Promise<BillingUsage>;
+  rates(opts?: { includeModels?: boolean }): Promise<BillingRates>;
 }
 
 export interface ResultsClient {
   auth: AuthProvider;
   mcpUrl: string;
+  /** The company every call names (x-blendification-company), or null for your own. */
+  companyId: string | null;
+  /** The same connection working in another company. The server refuses a call in a company you cannot act in. */
+  forCompany(companyId: string): ResultsClient;
+  /** Open a client company under your billing account. Needs a manager role and write access. */
+  createClientCompany(nameOrOpts: string | { name: string }): Promise<ClientCompany>;
+  /** What research costs: the account, spend per company and activity, and the price list. */
+  billing: BillingReads;
   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?: string[]; limit?: number; nextToken?: string }): Promise<any>;
-  conversations(args: ScopeArgs & { status?: string[]; limit?: number }): AsyncGenerator<TrackedConversation>;
+  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>;
@@ -133,5 +319,6 @@ export interface ResultsClient {
   templates(args?: Record<string, unknown>): Promise<any>;
 }
 
-export declare function createResultsClient(opts: { mcpUrl: string; auth: AuthProvider; fetch?: typeof fetch }): ResultsClient;
+export declare const COMPANY_HEADER: 'x-blendification-company';
+export declare function createResultsClient(opts: { mcpUrl: string; auth: AuthProvider; fetch?: typeof fetch; companyId?: string }): ResultsClient;
 export declare function mergeProgress(total: Progress | null, page: Record<string, unknown>): Progress;