@cosmoops/connect-sdk 0.32.0 → 0.33.0

package/dist/types/types.d.ts

@@ -534,6 +534,160 @@ export interface WriteLogResponse {
     attributed: boolean;
 }
 /** One turn of a RAG chat. Matches the AI SDK's `UIMessage` loosely enough to pass one straight through. */
+/** Where a knowledge item's text came from. */
+export type VisitorKnowledgeSource = "website" | "authored" | "upload";
+/**
+ * How a published item reaches the model.
+ *
+ * `inline` is the **normal and better** state for a small knowledge base, not a
+ * degraded one: the model is shown every published item rather than a top-k
+ * slice, with no chunk boundaries and no retrieval round trip. The other three
+ * only occur once a knowledge base has outgrown the prompt.
+ */
+export type VisitorKnowledgeIndexState = "inline" | "indexing" | "indexed" | "failed";
+/**
+ * One thing a workspace's website chat is allowed to tell strangers.
+ *
+ * **Not the workspace's Context Index.** That corpus is fed by every Drive
+ * upload; this store holds only what somebody explicitly published, which is
+ * what makes it safe to answer an anonymous visitor from. Nothing arrives here
+ * as a side effect of anything else.
+ */
+export interface VisitorKnowledgeItem {
+    id: string;
+    title: string;
+    body: string;
+    source: VisitorKnowledgeSource;
+    /** The crawled URL, or the uploaded file's name. `null` for authored text. */
+    sourceRef: string | null;
+    status: "draft" | "published";
+    indexState: VisitorKnowledgeIndexState;
+    /** Why the last index attempt failed, for your own screen to show. */
+    indexError: string | null;
+    /** ISO-8601, or `null` for a draft. */
+    publishedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * The knowledge base, and how its published half reaches the model.
+ *
+ * `mode` is a property of the *set*, which is why it is here and not on each
+ * item - and why a screen should read it from here rather than inferring it.
+ */
+export interface VisitorKnowledgeList {
+    /** Drafts included: this is the list a customer audits. */
+    items: VisitorKnowledgeItem[];
+    mode: "none" | "inline" | "retrieval";
+}
+/**
+ * What the widget should ask for next, decided by Connect.
+ *
+ * `"message"` is the ordinary composer. The others mean render that field's own
+ * input instead - and the reason this is a server decision rather than something
+ * the widget infers from the assistant's sentence is the phone: an email asked
+ * for in prose gets typed into a general text box with autocorrect on, where
+ * `type="email" inputmode="email" autocomplete="email"` brings up a keyboard
+ * with an `@` on it. A six-digit code wants `autocomplete="one-time-code"`,
+ * which is what lets iOS offer the code straight from the notification.
+ */
+export type VisitorField = "message" | "email" | "code" | "name";
+/** One stored message in a visitor conversation. `at` is ISO-8601. */
+export interface VisitorMessage {
+    role: "visitor" | "assistant";
+    text: string;
+    at: string;
+}
+/**
+ * An appointment this conversation booked, as a visitor is allowed to see it.
+ *
+ * Deliberately not the booking: no host ids, no workspace ids, no internal
+ * reference - the same narrowing Connect's own public booking page makes.
+ */
+export interface VisitorBooking {
+    startAt: string;
+    endAt: string;
+    /** The workspace's zone, not the visitor's - the zone the confirmation uses. */
+    timezone: string;
+}
+/**
+ * A conversation, as `visitor.startSession` opens or reopens it.
+ *
+ * **It carries no greeting and no suggestions.** Those are your own widget
+ * settings, rendered from your own store - so your bubble paints its first frame
+ * with no call to Connect at all, and this exists only to mint or recover the
+ * conversation Connect holds.
+ */
+export interface VisitorSession {
+    /**
+     * Hold this and send it with every turn.
+     *
+     * Treat it as a credential: it is the only thing identifying the conversation,
+     * and anyone holding it can continue it. Keep it in `sessionStorage` - it
+     * should survive a reload, which is what lets somebody follow a link out of
+     * the chat and come back, and it should not travel to another tab or outlive
+     * the visit.
+     */
+    sessionId: string;
+    /** The transcript, oldest first. Empty on a new conversation. */
+    messages: VisitorMessage[];
+    field: VisitorField;
+    turnsRemaining: number;
+    booking: VisitorAppointment | null;
+}
+/**
+ * The appointment `visitor.book` placed, and the one a reopened conversation
+ * reports.
+ *
+ * `VisitorBooking` plus `label`, and the extra field is the point: the words are
+ * produced by the same formatter the confirmation email uses, so the chat and
+ * the email cannot read differently about the same appointment. Render it rather
+ * than formatting `startAt` yourself - the visitor's browser is in their zone and
+ * the appointment is in the host's, and `Intl`'s month names differ between
+ * engines besides.
+ */
+export interface VisitorAppointment extends VisitorBooking {
+    label: string;
+}
+/** One time the assistant may offer, as its slot lookup returned it. */
+export interface VisitorSlot {
+    /** ISO-8601. Pass this back verbatim to book it. */
+    startAt: string;
+    /** Already written out in the workspace's own timezone - render this, don't reformat. */
+    label: string;
+}
+/**
+ * The times a turn looked up, lifted out of the tool result.
+ *
+ * **Draw the buttons from this, never from the assistant's sentence.** A time the
+ * visitor taps is then one the server offered, which is what makes
+ * `visitor.book` unable to take a time nobody was given.
+ */
+export interface VisitorSlotOffer {
+    eventType: string;
+    durationMinutes: number;
+    timezone: string;
+    slots: VisitorSlot[];
+}
+/** What a tool did this turn. `result` is the tool's own payload - switch on `name`. */
+export interface VisitorToolCall {
+    name: string;
+    result: unknown;
+}
+/** The `done` event at the end of a streamed turn. */
+export interface VisitorTurnDone {
+    toolCalls: VisitorToolCall[];
+    field: VisitorField;
+    turnsRemaining: number;
+    /**
+     * Whether the reply was grounded in published knowledge.
+     *
+     * `false` means nothing published covered the question, so the assistant said
+     * so and offered a call. Worth recording: a run of them is a knowledge base
+     * with a gap in it, which is the most useful signal this endpoint produces.
+     */
+    grounded: boolean;
+}
 export interface ChatMessage {
     role: "user" | "assistant" | "system";
     [field: string]: unknown;
@@ -1909,6 +2063,265 @@ export type BrandExtractionResult = {
     status: "skipped";
     reason: BrandSkipReason;
 };
+/** The five questions a readiness report answers. */
+export type ReadinessDimension = 
+/** Can an agent *act* here? MCP, OpenAPI, agent cards. */
+"agent_interfaces"
+/** Can an agent get the content at all? JavaScript dependency, bot walls, semantic structure. */
+ | "retrievability"
+/** Can an agent *read* it? llms.txt, markdown twins, structured data. */
+ | "machine_readable"
+/** Is an agent *allowed*, and does the site say so deliberately? */
+ | "crawl_consent"
+/** Is the site safe and identifiable to transact with? */
+ | "trust";
+/**
+ * How a check came out.
+ *
+ * `error` is the one to handle deliberately: it means Connect **could not
+ * measure** this - a timeout, a refused connection - and it is excluded from
+ * the score rather than counted as a failure. Render it as unknown, never as a
+ * problem. `absent` ("you do not have this") and `fail` ("you have it and it is
+ * broken") are likewise distinct and want different words.
+ */
+export type ReadinessCheckStatus = "pass" | "partial" | "fail" | "absent" | "error";
+/**
+ * Whether a check can cost points or only earn them.
+ *
+ * A `bonus` check raises the score when it passes and leaves it alone when it
+ * does not - so a site is never marked down for missing a convention almost
+ * nobody has adopted yet. Worth surfacing differently in a UI: a failed `core`
+ * check is a gap, an absent `bonus` one is an opportunity.
+ */
+export type ReadinessCheckKind = "core" | "bonus";
+/** One measured fact, with the evidence that settles it. */
+export interface ReadinessCheck {
+    /** Stable dotted id, e.g. `mcp.server`. Safe to key on; findings cite it. */
+    id: string;
+    dimension: ReadinessDimension;
+    kind: ReadinessCheckKind;
+    title: string;
+    status: ReadinessCheckStatus;
+    /** Relative importance inside its dimension. Only ratios are meaningful. */
+    weight: number;
+    /** What was actually observed, in one line - specific enough to show the user verbatim. */
+    observed: string;
+    /** The URL that proves it, where there is one. */
+    evidence: string | null;
+}
+export interface ReadinessDimensionScore {
+    dimension: ReadinessDimension;
+    /** 0-100. */
+    score: number;
+    /** This dimension's share of the overall score. */
+    weight: number;
+    /** Core checks that could not be measured. Show this rather than implying full coverage. */
+    unmeasured: number;
+}
+export type ReadinessGrade = "A" | "B" | "C" | "D" | "F";
+/** One thing to do about it, anchored in the checks that motivated it. */
+export interface ReadinessFinding {
+    severity: "critical" | "warning" | "note";
+    /** The checks this is about. Every id here appears in `checks`. */
+    checkIds: string[];
+    title: string;
+    detail: string;
+    fix: string;
+    effort: "low" | "medium" | "high";
+}
+/**
+ * Whether an assistant could answer a buyer's question from the site's own pages.
+ *
+ * The one judged rather than measured part of the report - a model read the
+ * pages and decided. Everything else in `checks` was parsed from real responses.
+ */
+export interface ReadinessAnswerability {
+    offering: boolean;
+    pricing: boolean;
+    howToBuy: boolean;
+    contact: boolean;
+    summary: string;
+    gaps: string[];
+}
+/**
+ * How ready a site is for AI agents.
+ *
+ * The important property, and the one that makes this worth showing a customer:
+ * **the score was computed from the checks, and the checks were measured.**
+ * Whether an MCP server exists is a completed JSON-RPC handshake, not a file
+ * that happened to answer 200; whether assistants are blocked is that site's
+ * `robots.txt` evaluated by its real rules. A model contributed only
+ * `answerability` and the prose in `findings`, and it cannot alter a status or
+ * the score.
+ */
+export interface ReadinessReport {
+    /** Normalised - lowercase, no scheme, no `www.`. */
+    domain: string;
+    /** 0-100, weighted across dimensions. */
+    score: number;
+    grade: ReadinessGrade;
+    dimensions: ReadinessDimensionScore[];
+    checks: ReadinessCheck[];
+    /** Ordered by consequence, most serious first. */
+    findings: ReadinessFinding[];
+    answerability: ReadinessAnswerability | null;
+    /** The one thing to do first. Drawn from `findings`, so it never disagrees with them. */
+    topFix: {
+        checkId: string;
+        title: string;
+        fix: string;
+    } | null;
+    /** ISO-8601. Age the report against this. */
+    assessedAt: string;
+}
+/**
+ * Why there is nothing to report. A normal 200, not an error.
+ *
+ * The distinction that matters for what you show and whether you retry:
+ * `unreachable` is about the **site** - it did not answer - and may succeed
+ * later. `provider_unavailable` is about **Connect** - our assessment service
+ * is down or unconfigured - and is worth retrying without telling the user
+ * anything about their own site. `no_domain` and `blocked_domain` never succeed
+ * on retry.
+ */
+export type ReadinessSkipReason = "no_domain" | "blocked_domain" | "consumer_domain" | "unreachable" | "provider_unavailable";
+export type ReadinessAssessmentResult = {
+    status: "assessed";
+    report: ReadinessReport;
+    /** Whether Connect served this from its platform-wide cache. The report is the same either way. */
+    cached: boolean;
+} | {
+    status: "skipped";
+    reason: ReadinessSkipReason;
+};
+/** The five things a presence is scored on. */
+export type PresenceCategory = "findability" | "identity" | "social" | "contactability" | "trust";
+/**
+ * How a check came out.
+ *
+ * `partial` is a real third state rather than a rounded failure: a site with
+ * `og:title` but no `og:image` has done most of the work, and rendering that as
+ * a failure is both wrong and discouraging.
+ */
+export type PresenceCriterionStatus = "pass" | "partial" | "fail";
+/** Where a score sits, coarsely. Advisory - use it to pick wording, not to make a decision. */
+export type PresenceBand = "absent" | "emerging" | "established" | "strong";
+/** The networks a scan recognises. `other` is a profile that matched no known pattern, kept rather than dropped. */
+export type PresenceNetwork = "linkedin" | "instagram" | "facebook" | "youtube" | "google_business" | "crunchbase" | "x" | "tiktok" | "github" | "other";
+/**
+ * One check, its verdict and the evidence behind it.
+ *
+ * `weight` and `earned` are both published so the total can be reconstructed:
+ * a `partial` that cost two points and one that cost six look identical
+ * without them, and a score nobody can reconstruct is a score nobody trusts.
+ */
+export interface PresenceCriterion {
+    /** Stable across scans, so two reports of one domain can be diffed. */
+    key: string;
+    category: PresenceCategory;
+    label: string;
+    status: PresenceCriterionStatus;
+    /** The check's full weight in the rubric. */
+    weight: number;
+    /** The share of `weight` actually earned. */
+    earned: number;
+    /** What was seen, in one line. */
+    observed: string;
+    /** The URL that settles it, when there is one. */
+    citation: string | null;
+    /** What to change. `null` when the check passed. */
+    fix: string | null;
+}
+export interface PresenceCategoryScore {
+    category: PresenceCategory;
+    /** 0-100 within the category, so a weak one is legible beside a strong one. */
+    score: number;
+    weight: number;
+    earned: number;
+}
+/**
+ * A profile the subject's own site linked.
+ *
+ * **Claimed, never verified.** Nothing in a scan proves the account belongs to
+ * that business - that needs a credential for each network. Render it as
+ * "linked from their site", never as a confirmed account.
+ */
+export interface PresenceSocialProfile {
+    network: PresenceNetwork;
+    url: string;
+    handle: string | null;
+    /**
+     * Whether the site declared it in `schema.org` `sameAs` markup rather than
+     * only as a link.
+     *
+     * The one to read closely. `false` means a real presence with none of the
+     * discoverability - a search engine has to infer the connection from a
+     * footer icon - and it is among the most common findings a scan produces.
+     */
+    machineReadable: boolean;
+}
+/** One prioritised thing to do. `fix` is Connect's own reviewed text; `why` is written for this business. */
+export interface PresenceRecommendation {
+    /** Names the check this came from, so advice is always traceable to evidence. */
+    criterionKey: string;
+    category: PresenceCategory;
+    /** 1 is what to do first. Always 1..n with no gaps. */
+    priority: number;
+    title: string;
+    /** What it costs this business specifically. Empty when the narrative could not be generated. */
+    why: string;
+    fix: string;
+}
+/**
+ * How visible a business is online.
+ *
+ * The important property, and the one that makes this worth showing a
+ * customer: **the score was computed from the checks, and the checks were
+ * measured.** Every point comes from something a fetcher observed on the site.
+ * A model contributed only the ordering of `recommendations` and the prose in
+ * `why` and `summary`; it cannot alter a status, a weight or the score.
+ */
+export interface PresenceScan {
+    /** Normalised - lowercase, no scheme, no `www.`. */
+    domain: string;
+    /** 0-100. */
+    score: number;
+    band: PresenceBand;
+    categories: PresenceCategoryScore[];
+    /** Every check, passed and failed. The audit trail behind the number. */
+    criteria: PresenceCriterion[];
+    /** Every profile found, including networks the rubric does not weight individually. */
+    social: PresenceSocialProfile[];
+    /** Two or three sentences on the overall state. Empty when it could not be generated - the scan is complete without it. */
+    summary: string;
+    /** What to do, in order. Render this before `criteria`. */
+    recommendations: PresenceRecommendation[];
+    /** ISO-8601. Age the scan against this. */
+    scannedAt: string;
+}
+/**
+ * Why there is nothing to report. A normal 200, not an error.
+ *
+ * The distinction that matters for what you show and whether you retry:
+ * `unreachable` is about the **site** - the home page did not answer - and may
+ * succeed later. `provider_unavailable` is about **Connect** - our scanner is
+ * down or unconfigured - and is worth retrying without telling the user
+ * anything about their own site. `no_domain`, `consumer_domain` and
+ * `blocked_domain` never succeed on retry.
+ *
+ * Note what is **not** here: a low score. Every check failing is a successful
+ * scan and the most useful report this produces.
+ */
+export type PresenceSkipReason = "no_domain" | "consumer_domain" | "blocked_domain" | "unreachable" | "provider_unavailable";
+export type PresenceScanResult = {
+    status: "scanned";
+    scan: PresenceScan;
+    /** Whether Connect served this from its platform-wide cache. The scan is the same either way. */
+    cached: boolean;
+} | {
+    status: "skipped";
+    reason: PresenceSkipReason;
+};
 /**
  * What kind of conversation a channel carries. `voice` is the only kind
  * Connect stocks inventory for today - `whatsapp` and `meeting` are modelled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -83,7 +83,8 @@
     "test": "bun test",
     "docs:md": "typedoc --options typedoc.markdown.json",
     "storybook": "storybook dev -p 6106",
-    "build:storybook": "storybook build -o storybook-static"
+    "build:storybook": "storybook build -o storybook-static",
+    "release:stage": "bun run scripts/stage-release.ts"
   },
   "devDependencies": {
     "@connect/ai": "workspace:*",