@cosmoops/connect-sdk 0.30.0 → 0.32.0

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 { PushResource } from "./resources/push.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
     /**
@@ -112,6 +113,11 @@ export declare class ConnectClient {
     readonly workspaces: WorkspacesResource;
     /** The platform's own legal identity and DPDP grievance channel - see `PlatformResource`. */
     readonly platform: PlatformResource;
+    /**
+     * Web Push. Connect holds the VAPID keys, the devices and the member's own
+     * preferences; you supply a title, a body and a URL. See `PushResource`.
+     */
+    readonly push: PushResource;
     /**
      * Relays one `/data/*` or `/kv/*` request verbatim - `createConnectHandler`'s
      * store route and nothing else. See `storePassthrough`.
@@ -126,4 +132,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.30.0";
+export declare const SDK_VERSION = "0.32.0";

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

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { AiConversationDetail, AiConversationList, ChatMessage, ConnectScreen } from "../../types.js";
+import type { AiConversationDetail, AiConversationList, AssessmentAnswers, AssessmentDraft, AssessmentReview, ChatMessage, ConnectScreen } from "../../types.js";
 /**
  * RAG chat and structured extraction against a workspace's data.
  *
@@ -87,4 +87,31 @@ export declare class AiResource {
         schemaId: string;
         fileUrl: string;
     }): Promise<T>;
+    /**
+     * 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.
+     */
+    draftAssessment(input: {
+        assessmentKey: string;
+        seed: string;
+    }): Promise<AssessmentDraft>;
+    /**
+     * 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.
+     */
+    reviewAssessment(input: {
+        assessmentKey: string;
+        answers: AssessmentAnswers;
+    }): Promise<AssessmentReview>;
 }

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

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { CompanyEnrichmentResult } from "../../types.js";
+import type { BrandExtractionResult, CompanyEnrichmentResult } from "../../types.js";
 /**
  * What Connect knows about the company at a domain.
  *
@@ -41,4 +41,49 @@ export declare class EnrichmentResource {
     }, options?: {
         signal?: AbortSignal;
     }): Promise<CompanyEnrichmentResult>;
+    /**
+     * 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: {
+        /** A domain or a URL in any form - `acme.com`, `www.acme.com`, `https://acme.com/pricing`. */
+        domain: string;
+        asUser?: string;
+        /** Re-extract even if Connect has a fresh profile cached. For an operator pressing "refresh" - not for automatic calls. */
+        refresh?: boolean;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<BrandExtractionResult>;
 }

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

@@ -0,0 +1,73 @@
+import { type TransportOptions } from "../http.js";
+import type { PushKeyResponse, RegisterPushDeviceInput, RegisterPushDeviceResponse, SendPushInput, SendPushResponse } from "../../types.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.
+ */
+export declare class PushResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * 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: SendPushInput): Promise<SendPushResponse>;
+    /**
+     * 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: {
+        asUser: string;
+    }): Promise<PushKeyResponse>;
+    /** Register one browser, from a subscription that browser just produced. */
+    registerDevice(input: RegisterPushDeviceInput, options: {
+        asUser: string;
+    }): Promise<RegisterPushDeviceResponse>;
+    /**
+     * 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: string, options: {
+        asUser: string;
+    }): Promise<{
+        revoked: boolean;
+    }>;
+}

package/dist/types/types.d.ts

@@ -586,6 +586,54 @@ export interface AiConversationDetail {
     conversation: AiConversation;
     turns: AiConversationTurn[];
 }
+/**
+ * One question in an assessment, as the platform defines it. Echoed back on a
+ * draft so the questions can be rendered without a second round trip.
+ */
+export interface AssessmentSection {
+    /** Stable identifier - the key answers are filed under. */
+    key: string;
+    /** The question as a person reads it. */
+    question: string;
+    /** What belongs here. Written to steer generation, but useful as helper text. */
+    hint?: string;
+    /** Fewest answers a draft offers. */
+    min?: number;
+    /** Most answers a draft offers, and the cap worth enforcing on edits. */
+    max?: number;
+}
+/** Answers, keyed by section key. */
+export type AssessmentAnswers = Record<string, string[]>;
+export interface AssessmentDraft {
+    assessmentKey: string;
+    title: string;
+    /** The definition's sections, in the order they should be asked. */
+    sections: AssessmentSection[];
+    /** Suggested answers - a strawman to edit, never a finished answer. */
+    answers: AssessmentAnswers;
+}
+export type AssessmentFindingSeverity = "critical" | "warning" | "note";
+export interface AssessmentFinding {
+    severity: AssessmentFindingSeverity;
+    /** Section keys this finding concerns - usually two, since the useful findings are tensions between sections. */
+    sections: string[];
+    title: string;
+    detail: string;
+    /** The specific change to make. */
+    fix: string;
+}
+export interface AssessmentReview {
+    assessmentKey: string;
+    findings: AssessmentFinding[];
+    /** The one assumption everything rests on, and a cheap way to test it. Lead with this. */
+    riskiestAssumption: {
+        section: string;
+        assumption: string;
+        experiment: string;
+    };
+    /** 0-100, advisory and coarse - it shows movement between revisions. */
+    score: number;
+}
 export interface WorkspaceApp {
     applicationId: string;
     /** Stable, human-readable key - branch on this, not `applicationId`, which is per-environment. */
@@ -1698,6 +1746,169 @@ export type CompanyEnrichmentResult = {
     status: "skipped";
     reason: EnrichmentSkipReason;
 };
+/**
+ * Where a brand claim was read. Its own union rather than `EnrichmentSource`,
+ * which has no notion of a stylesheet or a rendered page.
+ */
+export type BrandCitationSource = "website" | "stylesheet" | "render";
+export interface BrandCitation {
+    source: BrandCitationSource;
+    url: string;
+    /** ISO-8601. */
+    retrievedAt: string;
+}
+/** Whether the company sells a thing, an engagement, or both. */
+export type BusinessModel = "product" | "service" | "hybrid";
+/**
+ * Where an official name came from.
+ *
+ * `website-legal` is a legal disclosure the company published itself - a
+ * footer copyright line, or the entity named on its Terms page - matched by
+ * code against a corporate suffix and cited. `registry` is a statutory
+ * register and outranks it. Neither is a model's recall.
+ */
+export type OfficialNameSource = "registry" | "website-legal";
+export interface Offering {
+    name: string;
+    /** The company's own grouping when it has one. */
+    category: string | null;
+    description: string | null;
+    url: string | null;
+}
+export type LogoKind = "primary" | "mark" | "wordmark" | "favicon" | "social";
+export interface BrandLogo {
+    /**
+     * A **short-lived signed URL**, minted fresh on every read.
+     *
+     * Do not store it and do not bake it into a cached page - it will expire
+     * and become a broken image with a plausible-looking address. Render it
+     * directly, or re-read the profile, which on a cache hit is one document
+     * read. `null` when Connect holds no cached copy, in which case `sourceUrl`
+     * is all there is.
+     */
+    url: string | null;
+    /** Where it lives on the company's own site. Stable, and the citation. */
+    sourceUrl: string;
+    kind: LogoKind;
+    /** Lowercase extension without the dot: `svg`, `png`, `webp`. */
+    format: string;
+    width: number | null;
+    height: number | null;
+}
+/**
+ * How a colour was obtained, which is how much it is worth.
+ *
+ * `css-var` is the company naming its own colour in its own tokens - the
+ * strongest signal short of a brand manual. `computed` comes from a rendered
+ * page. `frequency` is a ranked count of declarations and is the weakest.
+ */
+export type PaletteSource = "css-var" | "computed" | "frequency";
+export type PaletteRole = "primary" | "secondary" | "accent" | "background" | "surface" | "text" | "muted";
+export interface PaletteEntry {
+    /** Lowercase `#rrggbb`. */
+    hex: string;
+    /** Assigned by a model over measured values - never invented by one. */
+    role: PaletteRole | null;
+    source: PaletteSource;
+    /** The CSS custom property it came from, when `source` is `css-var`. */
+    variableName: string | null;
+    occurrences: number;
+}
+export type TypefaceRole = "display" | "heading" | "body" | "mono";
+export interface TypefaceEntry {
+    /** The first named family in the stack - the one the company chose, not the fallbacks. */
+    family: string;
+    role: TypefaceRole | null;
+    weights: number[];
+    webfontUrl: string | null;
+    occurrences: number;
+}
+/** One step of a measured scale. */
+export interface ScaleStep {
+    value: number;
+    /** `px`, `rem`, `em`, `%`. */
+    unit: string;
+    occurrences: number;
+}
+/**
+ * A CSS framework detected by signature.
+ *
+ * Worth checking first, because it tells you how to read everything else: a
+ * Tailwind site's spacing scale is Tailwind's defaults rather than a
+ * considered choice, and a palette full of `--bs-*` is Bootstrap's.
+ */
+export type CssFramework = "tailwind" | "bootstrap" | "material" | "chakra" | "bulma";
+export interface BrandKit {
+    logos: BrandLogo[];
+    palette: PaletteEntry[];
+    typography: TypefaceEntry[];
+    voice: {
+        tagline: string | null;
+        /** A few adjectives for the register the copy is written in. */
+        tone: string[];
+    };
+}
+export interface DesignSystem {
+    radiusScale: ScaleStep[];
+    spacingScale: ScaleStep[];
+    /** Raw `box-shadow` values, most used first. */
+    shadows: string[];
+    /** `@media` breakpoint widths as written, ascending. */
+    breakpoints: string[];
+    /** Every `--*` declaration on `:root` - the company's own token vocabulary, verbatim. */
+    customProperties: {
+        name: string;
+        value: string;
+    }[];
+    framework: CssFramework | null;
+}
+/**
+ * What a company looks like, measured off its own website.
+ *
+ * The important property: **the numbers and the colours here were parsed, not
+ * generated.** Every hex came out of a stylesheet and every scale step is a
+ * count of real declarations. A model wrote only the prose (`about`,
+ * `industry`, `businessModel`, `offerings`, `voice`) and assigned `role` to
+ * values it was shown. Ask any model directly for a brand colour and it
+ * answers `#3B82F6`; that is the failure this shape exists to avoid.
+ */
+export interface BrandProfile {
+    /** Normalised - lowercase, no scheme, no `www.`. */
+    domain: string;
+    /** The trading name, as the company writes it. */
+    knownAs: string | null;
+    officialName: string | null;
+    officialNameSource: OfficialNameSource | null;
+    about: string | null;
+    industry: string | null;
+    businessModel: BusinessModel | null;
+    offerings: Offering[];
+    brandKit: BrandKit;
+    designSystem: DesignSystem;
+    /** Derived from how many aspects the sources actually filled - not a model's self-report. */
+    confidence: "high" | "medium" | "low";
+    citations: BrandCitation[];
+    /** ISO-8601. Age the profile against this. */
+    retrievedAt: string;
+}
+/**
+ * Why there is nothing to report. A normal 200, not an error.
+ *
+ * `consumer_domain` and `blocked_domain` will never succeed on retry.
+ * `unreachable` may. `no_stylesheet` means the site answered but shipped no
+ * CSS Connect could measure - a real outcome for a page built entirely in
+ * inline styles.
+ */
+export type BrandSkipReason = "no_domain" | "consumer_domain" | "blocked_domain" | "unreachable" | "no_signal" | "no_stylesheet";
+export type BrandExtractionResult = {
+    status: "extracted";
+    profile: BrandProfile;
+    /** Whether Connect served this from its platform-wide cache. The profile is the same either way. */
+    cached: boolean;
+} | {
+    status: "skipped";
+    reason: BrandSkipReason;
+};
 /**
  * What kind of conversation a channel carries. `voice` is the only kind
  * Connect stocks inventory for today - `whatsapp` and `meeting` are modelled
@@ -1952,3 +2163,62 @@ export interface ConversationsPage {
     nextCursor: string | null;
     hasMore: boolean;
 }
+/**
+ * One notification, to members of one workspace.
+ *
+ * Hand-written here rather than imported from `@connect/data`, like every wire
+ * type in this file: the published package carries none of Connect's
+ * internals, and `conformance.test.ts` type-checks these against the server's
+ * own DTOs so drift fails the build in Connect rather than in a partner's
+ * integration.
+ */
+export interface SendPushInput {
+    workspaceId: string;
+    /**
+     * Connect user ids. Ids naming somebody who is not an active member are
+     * dropped rather than refused - a partner legitimately holds a stale id for
+     * somebody who has left, and failing the whole call for one of them would
+     * mean a reminder nobody gets.
+     */
+    userIds: string[];
+    title: string;
+    body: string;
+    /** Absolute, and on an origin this application registered as an SSO redirect URI. */
+    url: string;
+}
+/**
+ * What a fan-out actually did.
+ *
+ * Reported honestly rather than collapsed to a boolean, because the
+ * interesting number is usually `silenced`: a partner seeing zero delivered
+ * needs to know whether nobody has a device or everybody muted them, and those
+ * call for opposite responses.
+ */
+export interface SendPushResponse {
+    /** Members reached after preference filtering. */
+    recipients: number;
+    /** Members dropped because they silenced notifications from their apps. */
+    silenced: number;
+    /** Devices the notification actually reached, across every recipient. */
+    delivered: number;
+    failed: number;
+}
+export interface PushKeyResponse {
+    /** `false` when the platform has no VAPID keys - say so rather than prompting. */
+    configured: boolean;
+    /** The `applicationServerKey` for `pushManager.subscribe()`. Empty when unconfigured. */
+    publicKey: string;
+}
+/** Exactly what `PushSubscription.toJSON()` produces, plus the agent string for the device list. */
+export interface RegisterPushDeviceInput {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+    userAgent: string;
+}
+export interface RegisterPushDeviceResponse {
+    /** Hand this to `revokeDevice` to turn the same browser off again. */
+    id: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.30.0",
+  "version": "0.32.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",