@cosmoops/connect-sdk 0.32.0 → 0.33.0

package/dist/types/client/index.d.ts

@@ -10,7 +10,7 @@
  * whatever theme the host application platform already configured, and one theme
  * change lands identically in all of them.
  */
-export { ConnectProvider, useConnect, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+export { ConnectProvider, useConnect, useConnectOptional, useConnectUser, useConnectWorkspaceType, useConnectAudience, useConnectPlatformAccess, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectCompanyProfile, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
 export type { ConnectProviderProps, ConnectContextValue, ConnectSession, ConnectOneTapHint, ConnectOneTapFailure, UseConnectResourceOptions, } from "./provider.js";
 export { blockingBlockers, normalizePlanFeatures } from "../helpers.js";
 export type { WirePlanFeature } from "../helpers.js";
@@ -52,6 +52,11 @@ export { normalizeNav, flattenNav, normalizePath, resolveActivePath, isNavItemAc
 export type { ConnectNav, ConnectNavItem, ConnectNavSection, ConnectNavLinkProps, ConnectLinkRenderer, } from "./components/nav.js";
 export type { ConnectScreen } from "../types.js";
 export { matchConnectScreen, isLinkableConnectScreen, } from "./components/ai-screens.js";
+export { ConnectVisitorChat } from "./components/visitor-chat.js";
+export type { ConnectVisitorChatProps } from "./components/visitor-chat.js";
+export { readVisitorStream, visitorSlotOfferFrom } from "./components/visitor-stream.js";
+export type { VisitorStreamHandlers } from "./components/visitor-stream.js";
+export type { VisitorAppointment, VisitorBooking, VisitorField, VisitorMessage, VisitorSession, VisitorSlot, VisitorSlotOffer, VisitorToolCall, VisitorTurnDone, } from "../types.js";
 export { ConnectAppsGrid } from "./components/apps-grid.js";
 export type { ConnectAppsGridProps } from "./components/apps-grid.js";
 export { ConnectAskAi } from "./components/ask-ai.js";

package/dist/types/client/provider.d.ts

@@ -245,6 +245,27 @@ export interface ConnectProviderProps {
  */
 export declare function ConnectProvider({ clientId, basePath, redirectUri, appUrl, fetch: fetchImpl, silentSignIn, children, }: ConnectProviderProps): import("react").JSX.Element;
 export declare function useConnect(): ConnectContextValue;
+/**
+ * The context when there is one, `null` when there is not.
+ *
+ * **For a component that must work on a page with no provider**, which is a
+ * real case rather than defensive coding: `<ConnectVisitorChat>` goes on a
+ * public marketing page, and those pages frequently have no `ConnectProvider`
+ * anywhere near them - there is no session to hold and nothing on the page that
+ * needs one. `useConnect()` throwing is right for every component that reads a
+ * session; it is wrong for one whose whole purpose is the visitor who has none.
+ *
+ * What inheriting the context buys such a component, when it is inside one, is
+ * `basePath` and the injected `fetch` - so the same component renders against
+ * Storybook's mock bridge and the docs site's canned fetch without either of
+ * them having to pass anything.
+ *
+ * Do not reach for this to make an ordinary component tolerant of a missing
+ * provider. A session-reading component that silently renders a signed-out
+ * state because somebody forgot to wrap their app is a bug that looks like a
+ * product decision.
+ */
+export declare function useConnectOptional(): ConnectContextValue | null;
 /** The signed-in user, or `null`. Sugar over `useConnect().session`. */
 export declare function useConnectUser(): ConnectUser | null;
 /**

package/dist/types/server/client.d.ts

@@ -21,6 +21,7 @@ import { AnalyticsResource } from "./resources/analytics.js";
 import { OtpResource } from "./resources/otp.js";
 import { SessionsResource } from "./resources/sessions.js";
 import { PlatformResource } from "./resources/platform.js";
+import { VisitorResource } from "./resources/visitor.js";
 import { PushResource } from "./resources/push.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
@@ -111,6 +112,11 @@ export declare class ConnectClient {
     readonly integrations: IntegrationsResource;
     /** Which workspaces the signed-in user belongs to, switching between them, and the team - see `WorkspacesResource`. */
     readonly workspaces: WorkspacesResource;
+    /**
+     * The public chat bubble on your own site - see `VisitorResource`. The one
+     * resource here whose caller is not one of your users.
+     */
+    readonly visitor: VisitorResource;
     /** The platform's own legal identity and DPDP grievance channel - see `PlatformResource`. */
     readonly platform: PlatformResource;
     /**

package/dist/types/server/handler.d.ts

@@ -40,28 +40,4 @@ export interface ConnectHandlerOptions {
      */
     stateCookieName?: string;
 }
-/**
- * The browser half of this SDK cannot hold an API key - so it does not.
- *
- * `@cosmoops/connect-sdk/client` talks only to your own origin, and this
- * handler is what answers. It lives in your backend, holds the key, and
- * exposes a fixed, named set of reads plus sign-out and session revocation.
- * Nothing here proxies arbitrary paths: a generic passthrough would hand the
- * browser your whole API surface under your credentials, which is the same
- * leak with extra steps.
- *
- * Framework-agnostic - `Request` in, `Response` out, so it mounts anywhere
- * that shape exists.
- *
- * ```ts
- * // app/api/connect/[...route]/route.ts
- * const handler = createConnectHandler({ client, session });
- * export { handler as GET, handler as POST };
- * ```
- *
- * Every route resolves the workspace from the caller's *own* session, never
- * from a query parameter. A browser must not be able to ask about an
- * workspace it is not signed into, and a client-supplied `workspaceId`
- * is exactly that hole.
- */
 export declare function createConnectHandler(options: ConnectHandlerOptions): (request: Request) => Promise<Response>;

package/dist/types/server/resources/ai.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { AiConversationDetail, AiConversationList, AssessmentAnswers, AssessmentDraft, AssessmentReview, ChatMessage, ConnectScreen } from "../../types.js";
+import type { AiConversationDetail, AiConversationList, AssessmentAnswers, AssessmentDraft, AssessmentReview, ChatMessage, ConnectScreen, ReadinessAssessmentResult } from "../../types.js";
 /**
  * RAG chat and structured extraction against a workspace's data.
  *
@@ -114,4 +114,51 @@ export declare class AiResource {
         assessmentKey: string;
         answers: AssessmentAnswers;
     }): Promise<AssessmentReview>;
+    /**
+     * How ready the site at a domain is for AI agents.
+     *
+     * Probes for an MCP server, an OpenAPI description, `llms.txt`, structured
+     * data and a markdown twin; evaluates the site's `robots.txt` against the
+     * assistants that actually fetch pages; checks whether its content survives
+     * without JavaScript and whether a bot wall refuses agents outright. Then
+     * grades what it found and says what to fix first.
+     *
+     * Needs an API key scoped to **`ai:readiness`**, which is separate from every
+     * other AI scope because it is the widest outbound surface on the API - it
+     * POSTs to candidate MCP endpoints and fetches the home page under two user
+     * agents.
+     *
+     * ```ts
+     * const result = await connect.ai.readiness({ domain: "acme.com" });
+     * if (result.status === "assessed") {
+     *   console.log(result.report.grade, result.report.topFix?.fix);
+     * }
+     * ```
+     *
+     * Four things to know before wiring it in:
+     *
+     * - **Set your client timeout to at least 90 seconds.** A cold assessment
+     *   runs the whole probe before answering and can take up to a minute; many
+     *   HTTP clients default to 30s and abandon a request that was about to
+     *   succeed. Cached reads return in milliseconds and are the normal case -
+     *   reports are held for a week.
+     * - **A week, not ninety days**, because a report is a to-do list somebody is
+     *   working through. Pass `refresh` after shipping a fix to see it land.
+     * - **Handle `status: "error"` checks as unknown, not as failures.** They mean
+     *   Connect could not measure that check, and they are excluded from the
+     *   score rather than counted against it.
+     * - **`skipped` says whose problem it is.** `unreachable` means the site did
+     *   not answer; `provider_unavailable` means Connect's own assessment service
+     *   did. Only the second is worth retrying silently, and neither should be
+     *   shown as a failing grade.
+     */
+    readiness(input: {
+        /** A domain or a URL in any form - `acme.com`, `www.acme.com`, `https://acme.com/pricing`. */
+        domain: string;
+        asUser?: string;
+        /** Re-assess even if Connect has a fresh report cached. For an operator who has just shipped a fix. */
+        refresh?: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadinessAssessmentResult>;
 }

package/dist/types/server/resources/enrichment.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { BrandExtractionResult, CompanyEnrichmentResult } from "../../types.js";
+import type { BrandExtractionResult, CompanyEnrichmentResult, PresenceScanResult } from "../../types.js";
 /**
  * What Connect knows about the company at a domain.
  *
@@ -86,4 +86,60 @@ export declare class EnrichmentResource {
     }, options?: {
         signal?: AbortSignal;
     }): Promise<BrandExtractionResult>;
+    /**
+     * How **visible** the business at a domain is online, scored out of 100.
+     *
+     * The third sibling of `company()` and `brand()`: that one answers what a
+     * business does, the other what it looks like, and this one answers how
+     * findable it is - by a search engine, by a customer, and by the assistants
+     * that increasingly answer questions about a business before anybody visits
+     * its site.
+     *
+     * Needs an API key scoped to **`enrichment:presence`** - separate from
+     * `enrichment:read` and `enrichment:brand` because it is the widest outbound
+     * read of the three: roughly twenty fetches across the site's well-known
+     * paths, and sometimes a headless browser.
+     *
+     * ```ts
+     * const result = await connect.enrichment.presence({ domain: "acme.com" });
+     * if (result.status === "scanned") {
+     *   for (const next of result.scan.recommendations) {
+     *     console.log(`${next.priority}. ${next.title} - ${next.fix}`);
+     *   }
+     * }
+     * ```
+     *
+     * Four things to know before wiring it in:
+     *
+     * - **The score is computed, not generated.** Every point comes from a check
+     *   run against something actually observed, and every check ships with its
+     *   weight, what was seen and the URL that settles it - so the total is
+     *   reconstructable. A model only orders `recommendations` and writes the
+     *   prose; it cannot move the number. That is the whole reason this is worth
+     *   showing a customer: ask a model how good a company's web presence is and
+     *   it answers 72 with total confidence for a site it never read.
+     * - **`social` is claimed, never verified.** Those are URLs the site itself
+     *   printed. Nothing proves the account belongs to that business - render it
+     *   as "linked from their site". Check `machineReadable` too: `false` means
+     *   a real profile that search engines have to infer from a footer link,
+     *   which is a specific, common and easily fixed finding.
+     * - **A low score is a success, not a skip.** Every check failing is the most
+     *   useful report this produces. Only `unreachable` means the site did not
+     *   answer - and `provider_unavailable` means *Connect* did not, which is
+     *   never something to tell your user about their own site.
+     * - **Set your client timeout to at least 90 seconds.** A cold scan runs the
+     *   whole probe before answering; many HTTP clients default to 30s and
+     *   abandon a request that was about to succeed. Cached scans return in
+     *   milliseconds, and cached is the normal case - results are held for a
+     *   fortnight, so you pay the cold path roughly once per domain.
+     */
+    presence(input: {
+        /** A domain or a URL in any form - `acme.com`, `www.acme.com`, `https://acme.com/pricing`. */
+        domain: string;
+        asUser?: string;
+        /** Re-scan even if Connect has a fresh result cached. For an operator who has just shipped a fix - not for automatic calls. */
+        refresh?: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<PresenceScanResult>;
 }

package/dist/types/server/resources/visitor.d.ts

@@ -0,0 +1,200 @@
+import { type TransportOptions } from "../http.js";
+import type { VisitorAppointment, VisitorKnowledgeItem, VisitorKnowledgeList, VisitorKnowledgeSource, VisitorSession } from "../../types.js";
+/**
+ * What `book` takes.
+ *
+ * A named interface rather than an inline shape, so `conformance.test.ts` can
+ * pin it against the server's own request schema - the check that stops a
+ * required field being optional here, which is a 400 a partner only meets at
+ * runtime.
+ */
+export interface VisitorBookInput {
+    sessionId: string;
+    workspaceId: string;
+    /** The same published slug the turn's slot lookup used. */
+    eventTypeSlug: string;
+    /** ISO-8601, or a `Date`. Must be one of the offered slots. */
+    startAt: string | Date;
+    name: string;
+    /** Required - it is how the host reaches them, and the second limiter key. */
+    phone: string;
+    email?: string | null;
+    notes?: string | null;
+}
+/** The per-call option every visitor method takes, so the limiter can see a visitor. */
+export interface VisitorCallOptions {
+    /** The visitor's address, as your bridge saw it. See `VISITOR_IP_HEADER`. */
+    visitorIp?: string | null;
+    signal?: AbortSignal;
+}
+/**
+ * The public chat bubble on your own marketing site.
+ *
+ * The one resource here whose caller is **not** one of your users. There is no
+ * `asUser`, no `workspaceId` and no session anywhere in it: the counterpart is a
+ * stranger who has no account, and everything the assistant may say or do is
+ * configuration a platform admin set on your application record.
+ *
+ * That is why none of these methods takes an id naming anything. The workspace a
+ * call books into, the event type it books, the knowledge it answers from and the
+ * daily budget it spends are all read from your application - so nothing a
+ * visitor types, and nothing an injection attempt in your own chat window
+ * achieves, reaches a different tenant.
+ *
+ * **Never call these from a browser.** They take your API key, like every other
+ * resource on this client. `createConnectHandler` already exposes them on your
+ * own origin for `<ConnectVisitorChat>` to use, which is how the credential stays
+ * server-side.
+ */
+export declare class VisitorResource {
+    private readonly transport;
+    /**
+     * The knowledge base behind the assistant - see `VisitorKnowledgeResource`.
+     *
+     * Nested rather than a top-level resource, because it is meaningless on its
+     * own: it exists to decide what *this* assistant may say.
+     */
+    readonly knowledge: VisitorKnowledgeResource;
+    constructor(transport: TransportOptions);
+    /**
+     * Open a conversation, or reopen one.
+     *
+     * Generates nothing - the greeting and the suggested questions come off the
+     * application record - so this is the one call in the flow that is always fast,
+     * which is what lets a bubble paint real copy instead of a spinner.
+     *
+     * Pass `resume` with a `sessionId` you kept and the transcript comes back with
+     * it. A `resume` that is expired, unknown or another application's silently
+     * starts a fresh conversation rather than failing: the token is the only thing
+     * being offered and it is being rejected, so there is nothing for the visitor
+     * to do about an error.
+     */
+    startSession(input: {
+        /** The customer whose website this is. Checked against your subscriptions. */
+        workspaceId: string;
+        /**
+         * Where the bubble was opened - a path or a page title.
+         *
+         * Worth passing: "how much is this?" asked from a pricing page and from a
+         * docs page are different questions, and this is the only signal of which.
+         * Treated as an untrusted hint and nothing else.
+         */
+        page?: string | null;
+        resume?: string | null;
+    }, options?: VisitorCallOptions): Promise<VisitorSession>;
+    /**
+     * One turn, streamed.
+     *
+     * Returns the raw `Response` rather than a parsed body, the same way
+     * `ai.chat` does: this answers server-sent events, and buffering them here
+     * would throw away the only reason to stream. The events are `delta`
+     * (`{text}`), `done` (`VisitorTurnDone`) and `error` (`{message}`).
+     *
+     * **The transcript is not a parameter**, which is the security property this
+     * endpoint is built around: the caller is ultimately a browser on a public
+     * page, and a client that can supply its own transcript can supply one in
+     * which anything has already been established. Only the conversation id and
+     * the new message travel.
+     */
+    chat(input: {
+        sessionId: string;
+        workspaceId: string;
+        message: string;
+        /** What the assistant calls itself, from your own widget settings. */
+        assistantName?: string;
+        /** A published event type slug in that workspace, for the booking exit. */
+        bookingEventTypeSlug?: string | null;
+    }, options?: VisitorCallOptions): Promise<Response>;
+    /**
+     * Book the call a visitor chose.
+     *
+     * `startAt` must be a time the turn's own slot lookup returned - an arbitrary
+     * instant is refused. That, plus a name and phone collected in real fields,
+     * is what makes it impossible to book an appointment at a time nobody offered
+     * or with a phone number a model parsed out of prose.
+     *
+     * A conversation books at most one appointment; a second call answers `409`.
+     */
+    book(input: VisitorBookInput, options?: VisitorCallOptions): Promise<VisitorAppointment>;
+}
+/**
+ * What `knowledge.save` takes.
+ *
+ * A named interface so `conformance.test.ts` can pin it against the server's own
+ * request schema - the check that stops a required field being optional here,
+ * which is a 400 a partner only meets at runtime.
+ */
+export interface SaveVisitorKnowledgeInput {
+    workspaceId: string;
+    /** Omit to create. An id that does not exist is refused, never created under. */
+    itemId?: string | null;
+    title: string;
+    body: string;
+    source: VisitorKnowledgeSource;
+    /** The crawled URL or the uploaded file's name. */
+    sourceRef?: string | null;
+}
+/**
+ * A subscribing workspace's **public** knowledge base - what their website chat
+ * may tell strangers.
+ *
+ * ## It is deliberately not their Context Index
+ *
+ * `ai.chat` answers from a workspace's Drive-fed corpus, for a signed-in member
+ * of that workspace. This is a separate store that holds only what somebody
+ * explicitly published, and the separation is the reason a publishable widget
+ * credential is safe to publish: everything the widget can reach was already
+ * meant for the public.
+ *
+ * Do not try to fill it by uploading to Drive. Nothing reaches this store as a
+ * side effect of anything else - that is the invariant, not an inconvenience.
+ *
+ * ## Publishing is its own call
+ *
+ * `save` always writes a draft. `publish` is what makes text readable by
+ * strangers, so no edit can do it by accident, and `unpublish` can fail - which
+ * means the item is **still live**, not that the call was pointless.
+ */
+export declare class VisitorKnowledgeResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /** Everything, drafts included - the list a customer audits. */
+    list(workspaceId: string): Promise<VisitorKnowledgeList>;
+    /**
+     * Create or edit a draft.
+     *
+     * A body over the cap is **refused rather than truncated** - split a long page
+     * into sections, which is also what makes retrieval work.
+     */
+    save(input: SaveVisitorKnowledgeInput): Promise<VisitorKnowledgeItem>;
+    /**
+     * Make one item readable by strangers.
+     *
+     * May be slow: the publish that outgrows the prompt provisions a retrieval
+     * corpus and indexes everything published so far. An indexing failure still
+     * publishes and comes back with `indexState: "failed"` and `indexError` set,
+     * so a provider hiccup never makes your button look broken.
+     */
+    publish(input: {
+        workspaceId: string;
+        itemId: string;
+    }): Promise<VisitorKnowledgeItem>;
+    /**
+     * Take one item out of what strangers can read.
+     *
+     * **A failure means it is still live.** The retrievable copy is removed before
+     * the record is flipped, so a provider that refuses the delete aborts rather
+     * than leaving an item your screen shows as withdrawn that the widget goes on
+     * quoting. Surface the error and let them retry; do not grey the row out
+     * optimistically.
+     */
+    unpublish(input: {
+        workspaceId: string;
+        itemId: string;
+    }): Promise<VisitorKnowledgeItem>;
+    /** Remove it entirely. A published item is unpublished first. */
+    delete(input: {
+        workspaceId: string;
+        itemId: string;
+    }): Promise<void>;
+}