@cosmoops/connect-sdk 0.32.0 → 0.34.0

package/dist/cjs/helpers.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_PLAN_LIMIT = void 0;
 exports.blockingBlockers = blockingBlockers;
 exports.normalizePlanFeatures = normalizePlanFeatures;
+exports.planLimitFor = planLimitFor;
+exports.planLimitAllows = planLimitAllows;
 /**
  * The blockers that actually deny access, in the order to show them.
  *
@@ -28,3 +31,46 @@ function blockingBlockers(readiness) {
 function normalizePlanFeatures(features) {
     return (features ?? []).map((feature) => typeof feature === "string" ? { key: feature, name: feature, description: "" } : feature);
 }
+/**
+ * What a key the plan carries no answer for reads as - see
+ * `SubscribedPlan.limits`, which is sparse.
+ *
+ * `"none"` rather than `"unlimited"`: a plan that was never asked about a
+ * limit has not sold it, and defaulting the other way would hand an unbounded
+ * allowance to every tier that predates the question.
+ */
+exports.NO_PLAN_LIMIT = { model: "none", value: null };
+/**
+ * One plan's answer for one limit key, with the sparse-map default applied.
+ *
+ * Indexing `plan.limits` directly is what makes a missing key `undefined`,
+ * which then reads as unlimited through the first `?.` somebody writes. This
+ * returns a `PlanLimit` either way.
+ */
+function planLimitFor(limits, key) {
+    return limits?.[key] ?? exports.NO_PLAN_LIMIT;
+}
+/**
+ * Whether `additional` more of the resource fit under this limit, given how
+ * many the subscriber already has. The comparison, written once.
+ *
+ * Every way of writing it at a call site is wrong in a different direction:
+ * `count < limit.value` is off by one as soon as you add more than one row,
+ * `if (!limit.value)` refuses the unlimited tier, and
+ * `limit.value ?? Infinity` grants unlimited to a plan that allows none. This
+ * is the same implementation Connect's own server uses to validate a plan.
+ *
+ * ```ts
+ * const limit = await connect.entitlements.getLimit(workspaceId, "sites");
+ * if (!planLimitAllows(limit, await countSites(workspaceId))) {
+ *   throw new Error("Your plan's site limit is reached.");
+ * }
+ * ```
+ */
+function planLimitAllows(limit, currentCount, additional = 1) {
+    if (limit.model === "unlimited")
+        return true;
+    if (limit.model === "none")
+        return false;
+    return currentCount + additional <= (limit.value ?? 0);
+}

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.storeIndexCovers = exports.describeQueryRejection = exports.unchangedSince = exports.storeIndexSignature = exports.storeIndexFor = exports.serverTimestamp = exports.increment = exports.documentExists = exports.deleteField = exports.arrayUnion = exports.arrayRemove = exports.normalizePlanFeatures = exports.blockingBlockers = exports.isConnectError = exports.ConnectError = void 0;
+exports.storeIndexCovers = exports.describeQueryRejection = exports.unchangedSince = exports.storeIndexSignature = exports.storeIndexFor = exports.serverTimestamp = exports.increment = exports.documentExists = exports.deleteField = exports.arrayUnion = exports.arrayRemove = exports.planLimitFor = exports.planLimitAllows = exports.NO_PLAN_LIMIT = exports.normalizePlanFeatures = exports.blockingBlockers = exports.isConnectError = exports.ConnectError = void 0;
 /**
  * `@cosmoops/connect-sdk` - the official client for the CosmoOps Connect
  * **application-partner API** (`/api/v1/application/*`).
@@ -22,6 +22,10 @@ Object.defineProperty(exports, "isConnectError", { enumerable: true, get: functi
 var helpers_js_1 = require("./helpers.js");
 Object.defineProperty(exports, "blockingBlockers", { enumerable: true, get: function () { return helpers_js_1.blockingBlockers; } });
 Object.defineProperty(exports, "normalizePlanFeatures", { enumerable: true, get: function () { return helpers_js_1.normalizePlanFeatures; } });
+var helpers_js_2 = require("./helpers.js");
+Object.defineProperty(exports, "NO_PLAN_LIMIT", { enumerable: true, get: function () { return helpers_js_2.NO_PLAN_LIMIT; } });
+Object.defineProperty(exports, "planLimitAllows", { enumerable: true, get: function () { return helpers_js_2.planLimitAllows; } });
+Object.defineProperty(exports, "planLimitFor", { enumerable: true, get: function () { return helpers_js_2.planLimitFor; } });
 var store_js_1 = require("./store.js");
 Object.defineProperty(exports, "arrayRemove", { enumerable: true, get: function () { return store_js_1.arrayRemove; } });
 Object.defineProperty(exports, "arrayUnion", { enumerable: true, get: function () { return store_js_1.arrayUnion; } });

package/dist/cjs/next/index.js

@@ -79,11 +79,18 @@ const errors_js_1 = require("../errors.js");
  * | --- | --- | --- |
  * | `CONNECT_API_KEY` | yes | server-side credential |
  * | `CONNECT_CLIENT_ID` | yes | OAuth client id |
- * | `CONNECT_APP_URL` | no | non-production Connect instance |
- * | `CONNECT_SESSION_COOKIE` | no | session cookie name |
+ * | `CONNECT_APP_URL` | no | non-production Connect instance; unset means production |
+ * | `CONNECT_SESSION_COOKIE` | no | session cookie name; unset means `connect_session` |
+ *
+ * `CONNECT_APP_URL` is server-side only and does not reach the browser:
+ * `ConnectProvider` defaults `appUrl` to the production origin independently,
+ * so an app pointed at another instance must pass that prop as well or its
+ * portal links and its browser-built authorize URL still go to production.
  *
  * Register `{your origin}/api/connect/callback` as a redirect URI in the
- * application's Connect client section. That is the only step this cannot do for you.
+ * application's Connect client section. That is the only step this cannot do
+ * for you, and Connect matches it exactly - every origin you run from needs
+ * its own entry, localhost included.
  *
  * No `next.config.ts` changes needed either, including `transpilePackages`:
  * `dist/` is already ES2022 with `"use client"` hoisted to the top of every

package/dist/cjs/server/client.js

@@ -23,6 +23,7 @@ const analytics_js_1 = require("./resources/analytics.js");
 const otp_js_1 = require("./resources/otp.js");
 const sessions_js_1 = require("./resources/sessions.js");
 const platform_js_1 = require("./resources/platform.js");
+const visitor_js_1 = require("./resources/visitor.js");
 const push_js_1 = require("./resources/push.js");
 exports.DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 const APPLICATION_API_PREFIX = "/api/v1/application";
@@ -115,6 +116,11 @@ class ConnectClient {
     integrations;
     /** Which workspaces the signed-in user belongs to, switching between them, and the team - see `WorkspacesResource`. */
     workspaces;
+    /**
+     * The public chat bubble on your own site - see `VisitorResource`. The one
+     * resource here whose caller is not one of your users.
+     */
+    visitor;
     /** The platform's own legal identity and DPDP grievance channel - see `PlatformResource`. */
     platform;
     /**
@@ -165,6 +171,7 @@ class ConnectClient {
         this.sessions = new sessions_js_1.SessionsResource(transport, options.clientId ?? null);
         this.integrations = new integrations_js_1.IntegrationsResource(transport);
         this.workspaces = new workspaces_js_1.WorkspacesResource(transport);
+        this.visitor = new visitor_js_1.VisitorResource(transport);
         this.platform = new platform_js_1.PlatformResource(transport);
         this.push = new push_js_1.PushResource(transport);
         this.storeRelay = (spec) => (0, data_js_1.storePassthrough)(transport, spec);
@@ -172,4 +179,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.32.0";
+exports.SDK_VERSION = "0.34.0";

package/dist/cjs/server/handler.js

@@ -99,6 +99,24 @@ function redirect(location, cookies = []) {
  * workspace it is not signed into, and a client-supplied `workspaceId`
  * is exactly that hole.
  */
+/**
+ * The visitor's own address, for Connect's per-visitor limiter.
+ *
+ * **Left-most `x-forwarded-for` entry**, which is the same precedence Connect's
+ * own `/api/book` and `/api/auth/session` use, and the same caveat applies: the
+ * left-most entry is the client as the first proxy saw it, and a client can
+ * prepend to that header. That makes it unsuitable for authorization and fine
+ * for this - it partitions your application's own budget between visitors, and
+ * the ceilings that actually cap spending are per key and per application.
+ *
+ * `null` where nothing forwarded one - a local dev server, or a platform that
+ * does not set it. Connect then counts every visitor in one shared bucket,
+ * which is a stricter limit rather than an exemption.
+ */
+function visitorIpOf(request) {
+    const forwarded = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+    return forwarded || request.headers.get("x-real-ip") || null;
+}
 function createConnectHandler(options) {
     const basePath = (options.basePath ?? "/api/connect").replace(/\/+$/, "");
     const { client, session } = options;
@@ -330,6 +348,130 @@ function createConnectHandler(options) {
             return json({ readiness, subscription });
         },
         "GET /plans": async () => json(await client.billing.listPlans()),
+        /* ---------------------------------------------------------------------- */
+        /* The visitor assistant - the only routes here with no session at all     */
+        /* ---------------------------------------------------------------------- */
+        /**
+         * `POST /visitor/session`, `/visitor/chat`, `/visitor/book`.
+         *
+         * Three routes that take **no session**, which makes them the exception to
+         * the rule every other route here follows. That is not a hole: the caller
+         * is a stranger on a public page, and there is no account for a session to
+         * identify. The question "whose data is this" has a different answer here -
+         * it is the *application's*, and the application is the one thing this
+         * bridge does hold a credential for.
+         *
+         * So the scoping that `requireWorkspace` provides elsewhere is provided
+         * here by Connect's own configuration: the workspace a call books into and
+         * the knowledge it answers from come from the application record, and no
+         * field in any of these bodies names a tenant. A browser cannot widen that
+         * by asking, because there is nothing to ask with.
+         *
+         * **`GET /company-profile` is the precedent and the limit of it.** That one
+         * is unauthenticated because the answer is identical for every caller.
+         * These are unauthenticated because the *caller* has no identity - but the
+         * answer is still per application, and spending is still per application.
+         * Which is why they are the only routes here that pass the visitor's own
+         * address along: the limiters on the far side count a visitor, and this
+         * bridge is the only thing that knows which one.
+         */
+        "POST /visitor/session": async (request) => {
+            const body = (await request.json().catch(() => null));
+            /*
+             * **The workspace is the browser's claim here, and that is the one thing
+             * this bridge must not simply relay.** Every other route on this bridge
+             * resolves the tenant from the caller's session; a visitor has none, so
+             * the widget names the customer whose site it is on - and a page can name
+             * any of them.
+             *
+             * Connect checks the workspace against your subscriptions, so the worst
+             * case is bounded to *your own* customers rather than the platform's. That
+             * is still one customer's budget spent from another's page, so an
+             * application serving several customers should resolve the workspace from
+             * its own widget record - by the embed token in the snippet, say - rather
+             * than trusting this field. The SDK cannot do that for you: it does not
+             * know what your widgets are keyed by.
+             */
+            if (typeof body?.workspaceId !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "workspaceId is required",
+                    endpoint: "POST /visitor/session",
+                });
+            }
+            return json(await client.visitor.startSession({
+                workspaceId: body.workspaceId,
+                page: typeof body.page === "string" ? body.page : null,
+                resume: typeof body.resume === "string" ? body.resume : null,
+            }, { visitorIp: visitorIpOf(request) }));
+        },
+        "POST /visitor/chat": async (request) => {
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.sessionId !== "string" ||
+                typeof body?.workspaceId !== "string" ||
+                typeof body?.message !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "sessionId, workspaceId and message are required",
+                    endpoint: "POST /visitor/chat",
+                });
+            }
+            const upstream = await client.visitor.chat({
+                sessionId: body.sessionId,
+                workspaceId: body.workspaceId,
+                message: body.message,
+                ...(typeof body.assistantName === "string"
+                    ? { assistantName: body.assistantName }
+                    : {}),
+                ...(typeof body.bookingEventTypeSlug === "string"
+                    ? { bookingEventTypeSlug: body.bookingEventTypeSlug }
+                    : {}),
+            }, { visitorIp: visitorIpOf(request) });
+            /*
+             * Piped, never buffered - awaiting the body would collect the whole reply
+             * server-side and deliver it in one lump, which is the only thing
+             * streaming was for. The browser hanging up propagates down this pipe and
+             * stops generation upstream, which on this surface also stops the
+             * spending.
+             */
+            return new Response(upstream.body, {
+                status: upstream.status,
+                headers: {
+                    "content-type": upstream.headers.get("content-type") ?? "text/event-stream",
+                    "cache-control": "no-store",
+                    // Without this a proxy in front of your app may buffer the whole
+                    // stream to inspect it, which undoes the streaming end to end.
+                    "x-accel-buffering": "no",
+                    "x-content-type-options": "nosniff",
+                },
+            });
+        },
+        "POST /visitor/book": async (request) => {
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.sessionId !== "string" ||
+                typeof body?.workspaceId !== "string" ||
+                typeof body?.eventTypeSlug !== "string" ||
+                typeof body?.startAt !== "string") {
+                throw new errors_js_1.ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "sessionId, workspaceId, eventTypeSlug and startAt are required",
+                    endpoint: "POST /visitor/book",
+                });
+            }
+            return json(await client.visitor.book({
+                sessionId: body.sessionId,
+                workspaceId: body.workspaceId,
+                eventTypeSlug: body.eventTypeSlug,
+                startAt: body.startAt,
+                name: typeof body.name === "string" ? body.name : "",
+                phone: typeof body.phone === "string" ? body.phone : "",
+                email: typeof body.email === "string" ? body.email : null,
+                notes: typeof body.notes === "string" ? body.notes : null,
+            }, { visitorIp: visitorIpOf(request) }));
+        },
         /**
          * The platform's legal identity and grievance channel.
          *

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

@@ -142,5 +142,55 @@ class AiResource {
         });
         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/billing.js

@@ -17,6 +17,10 @@ class BillingResource {
      * independently of the instance it talks to. Without the coercion a partner
      * pointed at a Connect that has not upgraded yet renders a feature list of
      * blanks - which is exactly what happened. See `normalizePlanFeatures`.
+     *
+     * `limits` is defaulted for the same reason, one version later: an instance
+     * that predates limits sends no such field, and a pricing grid mapping over
+     * `plan.limits` would throw rather than simply show no limit rows.
      */
     async listPlans() {
         const response = await (0, http_js_1.request)(this.transport, { method: "GET", path: "/plans" });
@@ -24,6 +28,7 @@ class BillingResource {
             plans: (response.plans ?? []).map((plan) => ({
                 ...plan,
                 features: (0, helpers_js_1.normalizePlanFeatures)(plan.features),
+                limits: plan.limits ?? [],
             })),
         };
     }

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

@@ -100,5 +100,64 @@ class EnrichmentResource {
             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/entitlements.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntitlementsResource = void 0;
 const http_js_1 = require("../http.js");
+const helpers_js_1 = require("../../helpers.js");
 /**
  * The two checks worth making on every request: may this workspace be here at
  * all, and what is it paying for.
@@ -45,6 +46,52 @@ class EntitlementsResource {
         const result = await this.getSubscription(workspaceId);
         return result.hasActiveSubscription && (result.plan?.features.includes(feature) ?? false);
     }
+    /**
+     * How much of a metered resource this workspace may have - the numeric
+     * counterpart of `hasFeature`, for the resources your application counts
+     * itself (sites, projects, pipelines).
+     *
+     * **This is the effective ceiling, not the plan's own number.** Connect has
+     * already folded in whatever the add-ons on the subscription raise it by, so
+     * "Starter includes 1 site, they bought two 5-site packs" arrives here as
+     * `{ model: "limited", value: 11 }`. You never join the plan against the
+     * add-on list yourself, and a customer who buys another pack needs no change
+     * on your side.
+     *
+     * Returns `{ model: "none" }` rather than throwing when there is no active
+     * subscription, when the plan carries no answer for this key, and when the
+     * Connect instance predates limits entirely - the same reasoning
+     * `hasFeature` gives for answering `false`: "not entitled" is the same answer
+     * either way, and a limit check should not need a try/catch around it.
+     *
+     * Connect does not enforce this. It cannot see what you are counting, so it
+     * hands you the number and your code refuses the next row - `canAdd` is that
+     * comparison if you already have the count.
+     */
+    async getLimit(workspaceId, key) {
+        const result = await this.getSubscription(workspaceId);
+        if (!result.hasActiveSubscription)
+            return helpers_js_1.NO_PLAN_LIMIT;
+        return (0, helpers_js_1.planLimitFor)(result.plan?.limits, key);
+    }
+    /**
+     * Whether this workspace may add `additional` more of a limited resource,
+     * given how many it already has.
+     *
+     * You supply the count, because only your application can produce it. This
+     * is `getLimit` plus `planLimitAllows`, which exists so the comparison is
+     * not rewritten per call site - see that helper for the three ways of
+     * getting it wrong.
+     *
+     * ```ts
+     * if (!(await connect.entitlements.canAdd(workspaceId, "sites", sites.length))) {
+     *   return refuse("Your plan's site limit is reached.");
+     * }
+     * ```
+     */
+    async canAdd(workspaceId, key, currentCount, additional = 1) {
+        return (0, helpers_js_1.planLimitAllows)(await this.getLimit(workspaceId, key), currentCount, additional);
+    }
     /**
      * One page of the workspaces subscribed to your application, newest first.
      *