@cosmoops/connect-sdk 0.30.1 → 0.33.0

package/dist/cjs/server/resources/ai.js

@@ -107,5 +107,90 @@ class AiResource {
         });
         return result.data;
     }
+    /**
+     * Draft every section of a platform-defined assessment from one sentence.
+     *
+     * The intended flow is draft first, then let the person correct it section
+     * by section: a blank questionnaire is the reason most people abandon one,
+     * and editing a strawman is a far smaller ask than authoring from nothing.
+     *
+     * Unattributed - assessments run against platform-wide definitions and the
+     * first consumers run before anyone has signed in, so there is no `asUser`
+     * and no workspace here.
+     */
+    async draftAssessment(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/ai/assessment/draft",
+            json: input,
+        });
+        return result.data;
+    }
+    /**
+     * Critique a completed assessment - the tensions between sections, the
+     * riskiest assumption, and a coarse score.
+     *
+     * Unknown section keys in `answers` are ignored rather than rejected, so a
+     * definition changing under a half-finished assessment costs the reader
+     * nothing.
+     */
+    async reviewAssessment(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/ai/assessment/review",
+            json: input,
+        });
+        return result.data;
+    }
+    /**
+     * 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, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/ai/readiness",
+            json: {
+                domain: input.domain,
+                ...(input.refresh ? { refresh: true } : {}),
+            },
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+            signal: options.signal,
+        });
+    }
 }
 exports.AiResource = AiResource;

package/dist/cjs/server/resources/enrichment.js

@@ -52,5 +52,112 @@ class EnrichmentResource {
             signal: options.signal,
         });
     }
+    /**
+     * What the company at a domain **looks like** - logo, palette, typefaces,
+     * and the radius, spacing and breakpoint scales its own stylesheets declare.
+     *
+     * The sibling of `company()` above: that one answers what a company does,
+     * this one answers what it looks like. Useful for white-labelling a portal
+     * to a customer's brand, pre-filling a design brief, or showing a real
+     * account card instead of a grey placeholder.
+     *
+     * Needs an API key scoped to **`enrichment:brand`** - separate from
+     * `enrichment:read` because it is far more expensive: it crawls
+     * stylesheets, may render the page in a headless browser, and caches image
+     * bytes.
+     *
+     * ```ts
+     * const result = await connect.enrichment.brand({ domain: "acme.com" });
+     * if (result.status === "extracted") {
+     *   const primary = result.profile.brandKit.palette.find((c) => c.role === "primary");
+     * }
+     * ```
+     *
+     * Three things to know before wiring it in:
+     *
+     * - **Set your client timeout to at least 90 seconds.** A cold read runs
+     *   the whole extraction 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 cached is the normal
+     *   case - profiles are held for 90 days, so you pay the cold path roughly
+     *   once per domain.
+     * - **Never store `brandKit.logos[].url`.** It is a short-lived signed URL
+     *   minted per read. Render it directly or re-read the profile; persist
+     *   `sourceUrl` if you need something stable.
+     * - **The values were measured, not generated.** Check `palette[].source` -
+     *   a `css-var` entry is the company naming its own colour, a `frequency`
+     *   entry is a ranked count and much weaker.
+     */
+    brand(input, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/enrichment/brand",
+            json: {
+                domain: input.domain,
+                ...(input.refresh ? { refresh: true } : {}),
+            },
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+            signal: options.signal,
+        });
+    }
+    /**
+     * 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, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/enrichment/presence",
+            json: {
+                domain: input.domain,
+                ...(input.refresh ? { refresh: true } : {}),
+            },
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+            signal: options.signal,
+        });
+    }
 }
 exports.EnrichmentResource = EnrichmentResource;

package/dist/cjs/server/resources/push.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PushResource = void 0;
+const http_js_1 = require("../http.js");
+const acting_as_js_1 = require("./acting-as.js");
+/**
+ * Web Push, with Connect holding everything that makes it work.
+ *
+ * Your application supplies a title, a body, a URL and the members to reach.
+ * Connect owns the VAPID keys it signs with, the devices each member has
+ * registered across every application on the platform, that member's own
+ * notification preferences, and the bookkeeping when a browser goes away.
+ *
+ * So you never hold a push credential, never store an endpoint, and cannot
+ * reach anybody who is not an active member of the workspace you name -
+ * membership is re-checked on every send rather than trusted from the ids you
+ * pass.
+ *
+ * ## Two halves, and only `send` belongs on your server
+ *
+ * Registering a device happens in the **browser**, because a subscription is
+ * produced by `pushManager.subscribe()` against the member's own browser and
+ * no server can make one for them. `registerDevice` and `revokeDevice` below
+ * therefore take a session token and are what the SDK bridge calls on the
+ * browser's behalf - see `createConnectHandler`. You will normally reach them
+ * through `useConnectPush()` in `@cosmoops/connect-sdk/client` rather than
+ * directly.
+ */
+class PushResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Notify members of a workspace.
+     *
+     * **`delivered: 0` is a success, not a failure.** The member may have
+     * registered no device, silenced notifications from their apps, or denied
+     * the browser prompt - all ordinary. A caller that retries on zero will
+     * retry forever against somebody who has opted out.
+     *
+     * Treat every send as a nudge toward something already true in your own
+     * data, and never let a failure here fail the thing that triggered it: the
+     * reminder is worth less than the record it is about.
+     *
+     * `url` must be absolute and on an origin this application registered as an
+     * SSO redirect URI. Connect refuses anything else, because a URL it did not
+     * check is an open redirect delivered to a lock screen.
+     */
+    send(input) {
+        return (0, http_js_1.request)(this.transport, { method: "POST", path: "/push", json: input });
+    }
+    /**
+     * The VAPID public key a browser needs before it can subscribe, and whether
+     * the platform can send at all.
+     *
+     * Safe to hand to any signed-in caller: it is the verification half of the
+     * pair, so holding it lets a browser *receive* what Connect signs and never
+     * send anything.
+     */
+    key(options) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/push/subscriptions",
+            headers: (0, acting_as_js_1.actingAs)(options.asUser),
+        });
+    }
+    /** Register one browser, from a subscription that browser just produced. */
+    registerDevice(input, options) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/push/subscriptions",
+            json: input,
+            headers: (0, acting_as_js_1.actingAs)(options.asUser),
+        });
+    }
+    /**
+     * Stop notifications on one browser.
+     *
+     * The id is the one `registerDevice` returned. Connect re-checks that it
+     * belongs to the calling member, so a guessed id is a refusal rather than
+     * somebody else's device going quiet.
+     */
+    revokeDevice(id, options) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "DELETE",
+            path: `/push/subscriptions?id=${encodeURIComponent(id)}`,
+            headers: (0, acting_as_js_1.actingAs)(options.asUser),
+        });
+    }
+}
+exports.PushResource = PushResource;

package/dist/cjs/server/resources/visitor.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VisitorKnowledgeResource = exports.VisitorResource = void 0;
+const http_js_1 = require("../http.js");
+/**
+ * The header a bridge forwards the visitor's own address on.
+ *
+ * It exists because `x-forwarded-for` cannot do this job here: by the time your
+ * backend calls Connect, that header describes the hop from *your server*, and
+ * the address Connect's per-visitor limiter needs is the one on the hop before
+ * it - which only your bridge has seen.
+ *
+ * **What it is and is not trusted for.** It partitions your own application's
+ * budget fairly between visitors; it does not grant anything. A caller sending a
+ * fresh value per request defeats only the per-visitor limiter and is still
+ * bounded by the per-key burst limit and the per-application daily ceiling -
+ * which are the two that actually cap spending, and neither is client-supplied.
+ * Omit it and every visitor shares one bucket, which is a stricter limit rather
+ * than an exemption.
+ */
+const VISITOR_IP_HEADER = "x-connect-visitor-ip";
+function visitorHeaders(options) {
+    return options?.visitorIp ? { [VISITOR_IP_HEADER]: options.visitorIp } : {};
+}
+/**
+ * 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.
+ */
+class VisitorResource {
+    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.
+     */
+    knowledge;
+    constructor(transport) {
+        this.transport = transport;
+        this.knowledge = new VisitorKnowledgeResource(transport);
+    }
+    /**
+     * 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, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/session",
+            json: {
+                workspaceId: input.workspaceId,
+                page: input.page ?? null,
+                resume: input.resume ?? null,
+            },
+            headers: visitorHeaders(options),
+            signal: options.signal,
+        });
+    }
+    /**
+     * 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, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/chat",
+            json: input,
+            headers: visitorHeaders(options),
+            raw: true,
+            signal: options.signal,
+        });
+    }
+    /**
+     * 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, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/book",
+            headers: visitorHeaders(options),
+            signal: options.signal,
+            json: {
+                ...input,
+                startAt: input.startAt instanceof Date ? input.startAt.toISOString() : input.startAt,
+                email: input.email ?? null,
+                notes: input.notes ?? null,
+            },
+        });
+    }
+}
+exports.VisitorResource = VisitorResource;
+/**
+ * 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.
+ */
+class VisitorKnowledgeResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Everything, drafts included - the list a customer audits. */
+    list(workspaceId) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/visitor/knowledge",
+            query: { workspaceId },
+        });
+    }
+    /**
+     * 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.
+     */
+    async save(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge",
+            json: {
+                ...input,
+                itemId: input.itemId ?? null,
+                sourceRef: input.sourceRef ?? null,
+            },
+        });
+        return result.item;
+    }
+    /**
+     * 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.
+     */
+    async publish(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/publish",
+            json: input,
+        });
+        return result.item;
+    }
+    /**
+     * 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.
+     */
+    async unpublish(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/unpublish",
+            json: input,
+        });
+        return result.item;
+    }
+    /** Remove it entirely. A published item is unpublished first. */
+    async delete(input) {
+        await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/visitor/knowledge/delete",
+            json: input,
+        });
+    }
+}
+exports.VisitorKnowledgeResource = VisitorKnowledgeResource;