@cosmoops/connect-sdk 0.3.0 → 0.6.0

package/dist/types/client/components/surfaces.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The one elevation model every panel inside a Connect modal follows.
+ *
+ * This exists because "just use `bg-surface`" is wrong here, and wrong in a
+ * way that is invisible until you look at the tokens. `Modal.Dialog` paints
+ * itself `bg-overlay`, and in the shared theme (`theme.css`) `--overlay` and
+ * `--surface` sit at the *same lightness* in both schemes - 100% against 100%
+ * in light, 21% against 21% in dark. A `bg-surface` panel dropped on a modal
+ * therefore has no fill contrast at all; only its border separates it from
+ * the dialog behind it.
+ *
+ * That is how the account modal ended up looking half-finished: the identity
+ * card used `bg-surface-secondary` and read as a solid block, while the
+ * destination tiles and the session list used `bg-surface` and read as
+ * hairline outlines floating on nothing. Same nesting depth, two different
+ * physical materials, for no reason a user could infer.
+ *
+ * Three levels, and nesting one inside another always steps the fill:
+ *
+ * - **L0 - the dialog itself.** `bg-overlay`, owned by HeroUI. Not ours.
+ * - **L1 - a panel on the dialog.** `PANEL_FILL` + `border-border`. The
+ *   identity card, each destination tile, the session list.
+ * - **L2 - a medallion inside a panel.** `bg-surface`, which is L0's value
+ *   and therefore reads as *inset* against L1 rather than raised. Light:
+ *   white on grey. Dark: near-black on charcoal. Both directions legible.
+ *
+ * The inversion at L2 is deliberate and is why this is written down. Reaching
+ * for a "lighter" fill one step down works in light mode and quietly fails in
+ * dark; stepping *back to the dialog's own value* is the trick that reads in
+ * both, because the contrast comes from the gap between L1 and L0 rather than
+ * from a direction of travel.
+ */
+export declare const PANEL_FILL = "bg-surface-secondary";
+/**
+ * The icon well shared by destination tiles and session rows: a 40px box
+ * holding a 20px glyph.
+ *
+ * Half the well, which is the point. Both surfaces used to run a `size-4`
+ * (16px) icon inside a `size-9` (36px) well - a 44% fill that reads as an
+ * icon someone forgot to finish, and the specific thing that made the
+ * Profile/Billing/Connect tiles look under-drawn. They also disagreed on
+ * shape (a circle in the tiles, a rounded square in the session rows) for
+ * what is the same component role, so the two surfaces never looked related.
+ *
+ * Pair with `ICON` on the glyph inside. Session rows override the well to
+ * `size-9` for density but keep the same `ICON`, so glyph size stays constant
+ * across the whole modal even where the well does not.
+ */
+export declare const MEDALLION = "size-10";
+/** The glyph inside a `MEDALLION`. Constant across every well in the modal - see `MEDALLION`. */
+export declare const ICON = "size-5";

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

@@ -10,7 +10,7 @@
  * whatever theme the host service platform already configured, and one theme
  * change lands identically in all of them.
  */
-export { ConnectProvider, useConnect, useConnectUser, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectAddonUsage, useConnectSessions, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
+export { ConnectProvider, useConnect, useConnectUser, useConnectEntitlements, useConnectPlans, useConnectApps, useConnectAddonUsage, useConnectSessions, useConnectIntegrations, useConnectResource, CONNECT_APP_URL, } from "./provider.js";
 export type { ConnectProviderProps, ConnectContextValue, ConnectSession } from "./provider.js";
 export { blockingBlockers, normalizePlanFeatures } from "../helpers.js";
 export type { WirePlanFeature } from "../helpers.js";
@@ -25,8 +25,17 @@ export { ConnectUserMenu, ConnectManageSubscriptionButton, ConnectInvoicesButton
 export { ConnectAccountSessions } from "./components/account-sessions.js";
 export type { ConnectAccountSessionsProps } from "./components/account-sessions.js";
 export type { ConnectUserMenuProps } from "./components/user-menu.js";
+export { ConnectAppShell } from "./components/app-shell.js";
+export type { ConnectAppShellProps } from "./components/app-shell.js";
+export { ConnectSideNav } from "./components/side-nav.js";
+export type { ConnectSideNavProps } from "./components/side-nav.js";
+export { useActivePath } from "./use-active-path.js";
+export { normalizeNav, flattenNav, normalizePath, resolveActivePath, isNavItemActive, gateExemptPaths, } from "./components/nav.js";
+export type { ConnectNav, ConnectNavItem, ConnectNavSection, ConnectNavLinkProps, ConnectLinkRenderer, } from "./components/nav.js";
 export { ConnectAppsGrid } from "./components/apps-grid.js";
 export type { ConnectAppsGridProps } from "./components/apps-grid.js";
+export { ConnectIntegrationsModal } from "./components/integrations-modal.js";
+export type { ConnectIntegrationsModalProps } from "./components/integrations-modal.js";
 export { ConnectPlans } from "./components/plans.js";
 export type { ConnectPlansProps } from "./components/plans.js";
 export { ConnectSubscribeDialog } from "./components/subscribe-dialog.js";
@@ -35,6 +44,8 @@ export { ConnectSubscriptionGate, ConnectNoSubscriptionCard, ConnectSubscription
 export type { ConnectSubscriptionGateProps, ConnectNoSubscriptionCardProps, ConnectSubscriptionCardProps, ConnectTrialBannerProps, ConnectSubscriptionState, } from "./components/subscription.js";
 export { ConnectReadinessBanner, ConnectReadinessGate } from "./components/readiness.js";
 export type { ConnectReadinessBannerProps, ConnectReadinessGateProps } from "./components/readiness.js";
+export { ConnectAccessGate, useConnectAccessGate } from "./components/access-gate.js";
+export type { ConnectAccessGateProps, ConnectAccessGateState, ConnectAccessGateResult, } from "./components/access-gate.js";
 export { ConnectFeatureGate, useConnectFeature } from "./components/feature-gate.js";
 export type { ConnectFeatureGateProps } from "./components/feature-gate.js";
 export { ConnectUsageMeter } from "./components/usage-meter.js";

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

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { AddonUsageResponse, ConnectUser, OrganizationApp, PlansResponse, ReadinessResponse, ServiceRole, SessionsListResponse, SessionSubscription, SubscriptionResponse } from "../types.js";
+import type { AddonUsageResponse, ConnectUser, IntegrationsListResponse, OrganizationApp, PlansResponse, ReadinessResponse, ServiceRole, SessionsListResponse, SessionSubscription, SubscriptionResponse } from "../types.js";
 export declare const CONNECT_APP_URL = "https://connect.cosmoops.com";
 export interface ConnectSession {
     user: ConnectUser | null;
@@ -61,7 +61,7 @@ export interface ConnectContextValue {
 }
 export interface ConnectProviderProps {
     /**
-     * This service's public `client_id`, from its Setup tab in Connect.
+     * This service's public `client_id`, from its Integration tab in Connect.
      *
      * Not needed for the default sign-in flow: `signIn()` with no `redirectUri`
      * bounces the browser to your own `/signin` route, which already knows
@@ -87,6 +87,27 @@ export interface ConnectProviderProps {
      * child effects.
      */
     fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * Sign in a returning visitor automatically, with no click.
+     *
+     * When the first `/session` read comes back signed out, the browser is sent
+     * on one round trip to Connect with OIDC `prompt=none`. If they still have
+     * a Connect session and have authorised this app before, they come straight
+     * back signed in and never see a screen. If not, they come straight back
+     * signed out, with no error and nothing rendered differently - your normal
+     * signed-out UI just appears a beat later.
+     *
+     * **Off by default, and it is a real trade, not just caution.** It costs a
+     * full-page redirect on the first load of every signed-out visit - a brief
+     * flash on a marketing page, invisible on an app shell - so it belongs on
+     * apps whose visitors are overwhelmingly already Connect users. It is
+     * attempted at most once per tab (a `sessionStorage` marker), so a visitor
+     * who genuinely has no session does not bounce on every navigation.
+     *
+     * Requires `createConnectHandler` mounted at `basePath`; the redirect goes
+     * to your own `/signin`, which mints the `state` server-side.
+     */
+    silentSignIn?: boolean;
     children: ReactNode;
 }
 /**
@@ -103,7 +124,7 @@ export interface ConnectProviderProps {
  * </ConnectProvider>
  * ```
  */
-export declare function ConnectProvider({ clientId, basePath, redirectUri, appUrl, fetch: fetchImpl, children, }: ConnectProviderProps): import("react").JSX.Element;
+export declare function ConnectProvider({ clientId, basePath, redirectUri, appUrl, fetch: fetchImpl, silentSignIn, children, }: ConnectProviderProps): import("react").JSX.Element;
 export declare function useConnect(): ConnectContextValue;
 /** The signed-in user, or `null`. Sugar over `useConnect().session`. */
 export declare function useConnectUser(): ConnectUser | null;
@@ -174,6 +195,20 @@ export declare function useConnectApps(): {
      */
     refetch(): void;
 };
+/** Enabled Composio-hosted toolkits and this organization's connection status for each. */
+export declare function useConnectIntegrations(): {
+    data: IntegrationsListResponse | null;
+    isLoading: boolean;
+    error: string | null;
+    /**
+     * Forces a fresh read - the provider's cache clears the mutated path's
+     * entry on a successful `mutateResource` call, but nothing re-triggers
+     * this hook's own effect on its own (none of its dependencies change from
+     * a cache write nobody here observes). Call this right after a
+     * `mutateResource` you made against the same `path` completes.
+     */
+    refetch(): void;
+};
 /**
  * This Connect account's own login sessions - account-wide, not scoped to
  * this service, see `SessionsListResponse`'s doc comment. The component

package/dist/types/client/use-active-path.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The current path, from `activePath` when given and from the browser
+ * otherwise.
+ *
+ * Exported because a host building its own shell out of `ConnectSideNav`
+ * needs the same fallback the shell uses.
+ */
+export declare function useActivePath(activePath?: string): string;

package/dist/types/errors.d.ts

@@ -52,7 +52,7 @@ export declare class ConnectError extends Error {
      * guessing keys. These two are the exception: reaching them required
      * presenting a key whose hash matched, so you already hold it, and what you
      * need to know is that no retry and no scope change will fix this - the key
-     * has to be reissued from the service's Setup tab.
+     * has to be reissued from the service's Integration tab.
      *
      * Worth alerting on. It is the one failure that will not resolve itself and
      * takes down every call your integration makes.

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

@@ -81,6 +81,9 @@ export { handle as GET, handle as POST };
  * if (!session) redirect("/api/connect/signin?next=/dashboard");
  * ```
  *
+ * `requireConnectSession()` below is that exact check in one call, for the
+ * common case of "redirect if signed out."
+ *
  * Pass a `Request` to use it somewhere `next/headers` does not exist - a
  * framework-agnostic handler, a test, a custom server. Both forms take the
  * same path afterwards; the argument is only how the cookie is found.
@@ -92,11 +95,48 @@ export { handle as GET, handle as POST };
  *
  * Returns `null` for every failure - an expired session and a missing one both
  * mean "not signed in", and a page guard should not need a try/catch.
+ *
+ * **Memoized per request for the plain, zero-argument call** - the shape
+ * every page, layout and Server Action actually uses - via React's `cache()`.
+ * Passing an explicit `request`, `client` or `session` bypasses the cache
+ * and always makes a live call: those are for tests and non-ambient
+ * callers, where a fresh read every time is the point, not an oversight.
  */
 export declare function getConnectSession(request?: Request, options?: {
     client?: ConnectClient;
     session?: ConnectSessionStore;
 }): Promise<UserResponse | null>;
+/**
+ * `getConnectSession()`, minus the boilerplate of checking it and redirecting
+ * yourself:
+ *
+ * ```tsx
+ * // app/dashboard/page.tsx
+ * const session = await requireConnectSession();
+ * ```
+ *
+ * Redirects to `/signin` under the same `basePath` as `getConnectSession`'s
+ * default (`/api/connect`) when signed out - pass `signInPath` if you mounted
+ * the bridge somewhere else, and `next` to send the visitor back to where
+ * they were once they're signed in. Only sensible in a Server Component,
+ * Route Handler or Server Action, the same three places `redirect()` from
+ * `next/navigation` itself works.
+ *
+ * A thin wrapper, not a framework of its own - reach for `getConnectSession`
+ * plus your own check when "not signed in" isn't "redirect to sign-in"
+ * (an API route returning 401, say). Role and entitlement checks stay
+ * outside this function on purpose: `session.serviceRole.granted` and
+ * `connect.entitlements.*` are one line each on top of the session this
+ * already gives you, and where that line redirects (a plans page, a
+ * "forbidden" screen) is a decision only your app can make - see
+ * "Authentication & authorization" for the pattern.
+ */
+export declare function requireConnectSession(request?: Request, options?: {
+    client?: ConnectClient;
+    session?: ConnectSessionStore;
+    signInPath?: string;
+    next?: string;
+}): Promise<UserResponse>;
 export { createConnectHandler } from "../server/handler.js";
 export type { ConnectSessionStore } from "../server/handler.js";
 export { ConnectClient } from "../server/client.js";

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

@@ -6,13 +6,15 @@ import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
 import { EntitlementsResource } from "./resources/entitlements.js";
 import { IdentityResource } from "./resources/identity.js";
+import { IntegrationsResource } from "./resources/integrations.js";
 import { LogsResource } from "./resources/logs.js";
+import { AnalyticsResource } from "./resources/analytics.js";
 import { OtpResource } from "./resources/otp.js";
 import { SessionsResource } from "./resources/sessions.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
     /**
-     * The API key plaintext from this service's Setup tab, shown once at
+     * The API key plaintext from this service's Integration tab, shown once at
      * creation.
      *
      * One credential does three jobs: it is the `Authorization: Bearer` value
@@ -75,9 +77,13 @@ export declare class ConnectClient {
     readonly otp: OtpResource;
     /** Feature events into the Console's audit log, filterable to your service. */
     readonly logs: LogsResource;
+    /** Emit product events and read back this service's aggregated numbers. */
+    readonly analytics: AnalyticsResource;
     /** This Connect account's own login sessions - account-wide, not scoped to this service. Requires the `sessions:manage` scope. */
     readonly sessions: SessionsResource;
+    /** Composio-hosted third-party connections (Google Calendar, Slack, ...) an organization has connected. */
+    readonly integrations: IntegrationsResource;
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.3.0";
+export declare const SDK_VERSION = "0.6.0";

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

@@ -20,4 +20,11 @@ export type { BillingResource } from "./resources/billing.js";
 export type { AiResource } from "./resources/ai.js";
 export type { OtpResource } from "./resources/otp.js";
 export type { LogsResource } from "./resources/logs.js";
+export type { AnalyticsResource } from "./resources/analytics.js";
 export type { SessionsResource } from "./resources/sessions.js";
+export type { ExecuteIntegrationActionInput, IntegrationsResource } from "./resources/integrations.js";
+/**
+ * Webhook verification and a ready-made POST route. Server-only for the
+ * obvious reason: the signing secret must never reach a browser bundle.
+ */
+export { createConnectWebhookHandler, verifyConnectWebhook, type ConnectWebhookHandlers, type ConnectWebhookHandlerOptions, } from "./webhooks.js";

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

@@ -0,0 +1,31 @@
+import { type TransportOptions } from "../http.js";
+import type { AnalyticsQuery, AnalyticsResponse, EmitEventInput, EmitEventsResponse } from "../../types.js";
+/**
+ * Your service's own analytics: emit product events, and read back the daily
+ * numbers Connect aggregates from them.
+ *
+ * There is no way to name a service in either call. The scope is always the one
+ * your API key belongs to - that is the endpoint's security model, not an
+ * omission.
+ */
+export declare class AnalyticsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Daily series for the requested metrics, up to 90 days.
+     *
+     * **Throws on failure**, unlike `emit` below. A read whose result you are
+     * about to render has to be able to say "I could not load"; silently
+     * returning an empty series would draw a chart of zeroes.
+     */
+    series(query: AnalyticsQuery): Promise<AnalyticsResponse>;
+    /**
+     * Never throws - the same judgement `LogsResource.write` makes, for the same
+     * reason: telemetry that takes down the code path it was observing is worse
+     * than a lost event. A failure is reported through `delivered`.
+     *
+     * Up to 50 events per call. Pass `sessionToken` on an event to attribute it
+     * to the signed-in user; without one it still lands, just unattributed.
+     */
+    emit(events: EmitEventInput[]): Promise<EmitEventsResponse>;
+}

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

@@ -4,8 +4,18 @@ export interface AuthorizeUrlInput {
     redirectUri: string;
     /** Fresh and random per request; check it matches on the way back. `createState()` makes one. */
     state: string;
-    /** `"create"` opens registration instead of sign-in, so one entry point serves both buttons. */
-    prompt?: "create";
+    /**
+     * `"create"` opens registration instead of sign-in, so one entry point
+     * serves both buttons.
+     *
+     * `"none"` is OIDC silent authentication: Connect answers from the
+     * visitor's existing session without showing them anything, returning a
+     * code if they are signed in and have already authorised this client, and
+     * `error=login_required`/`consent_required`/`interaction_required` if not.
+     * Use it to sign in a returning visitor with no click - never to *start* a
+     * sign-in, since by definition it will never show them a login screen.
+     */
+    prompt?: "create" | "none";
     /** Required only if this service enforces PKCE. */
     codeChallenge?: string;
 }

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

@@ -0,0 +1,40 @@
+import { type TransportOptions } from "../http.js";
+import type { DisconnectIntegrationResponse, ExecuteIntegrationActionResponse, InitiateIntegrationConnectionResponse, IntegrationsListResponse } from "../../types.js";
+export interface ExecuteIntegrationActionInput {
+    toolkitSlug: string;
+    actionSlug: string;
+    /** Passed through to Composio verbatim - its shape is defined by the toolkit's own action schema, which Connect does not model. */
+    params?: Record<string, unknown>;
+}
+/**
+ * Composio-hosted third-party connections (Google Calendar, Slack,
+ * Twitter/X, ...) an organization has connected. Connect proxies every call
+ * here - your service never sees or holds the underlying OAuth token, which
+ * stays with Composio.
+ */
+export declare class IntegrationsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /** Enabled toolkits and this organization's connection status for each. */
+    list(organizationId: string): Promise<IntegrationsListResponse["toolkits"]>;
+    /**
+     * Starts a Composio-hosted connection for one toolkit. The returned
+     * `redirectUrl` is where the browser completes the provider's OAuth
+     * screen, then Composio bounces it back to `returnUrl`.
+     *
+     * **The connection is not active when this returns.** Treat the toolkit
+     * as `pending` until a later `list()` call reports `active` - only
+     * Connect's own webhook from Composio confirms that, never the redirect
+     * itself. Reconnecting a disconnected/failed toolkit calls this same
+     * method - there is no separate reconnect.
+     *
+     * Meant to be called on behalf of a signed-in org admin (this is what the
+     * bridge's fixed `POST /integrations/connect` route does), not as a bare
+     * background action with no admin present to complete the OAuth screen.
+     */
+    initiateConnect(organizationId: string, toolkitSlug: string, returnUrl: string): Promise<InitiateIntegrationConnectionResponse>;
+    /** Idempotent - disconnecting a toolkit that was never connected, or is already disconnected, is a success. */
+    disconnect(organizationId: string, toolkitSlug: string): Promise<DisconnectIntegrationResponse>;
+    /** Calls a Composio action against this organization's connected account for the named toolkit. */
+    execute(organizationId: string, input: ExecuteIntegrationActionInput): Promise<ExecuteIntegrationActionResponse>;
+}

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

@@ -0,0 +1,67 @@
+import type { ConnectWebhookEnvelope, ConnectWebhookEventMap, ConnectWebhookEventType } from "../types.js";
+/**
+ * Verifies a `Connect-Signature` header against the raw request body.
+ *
+ * Exported on its own for anyone wiring this into a framework
+ * `createConnectWebhookHandler` does not cover. The **raw** body matters:
+ * verify before parsing, and never re-serialise - `JSON.stringify(await
+ * req.json())` produces a different string whenever key order or number
+ * formatting differs, and the signature will not match.
+ *
+ * Returns a boolean and never explains which check failed. Reporting "bad
+ * timestamp" separately from "bad signature" tells whoever is probing which
+ * half of a forgery to keep working on.
+ */
+export declare function verifyConnectWebhook(rawBody: string, signatureHeader: string | null | undefined, secret: string, now?: Date): boolean;
+/** One handler per event type. Every one is optional; unhandled types are acknowledged and ignored. */
+export type ConnectWebhookHandlers = {
+    [K in ConnectWebhookEventType]?: (data: ConnectWebhookEventMap[K], envelope: ConnectWebhookEnvelope<K>) => void | Promise<void>;
+};
+export interface ConnectWebhookHandlerOptions {
+    /** The endpoint's signing secret, from Console. Keep it in an environment variable. */
+    secret: string;
+    on: ConnectWebhookHandlers;
+    /**
+     * Called when a handler throws. Return nothing to have the delivery
+     * retried (Connect responds to a 5xx by retrying for about 33 hours);
+     * the default logs and rethrows, which produces exactly that.
+     */
+    onError?: (error: unknown, envelope: ConnectWebhookEnvelope) => void | Promise<void>;
+}
+/**
+ * A ready-made `POST` route for Connect's webhooks.
+ *
+ * ```ts
+ * export const POST = createConnectWebhookHandler({
+ *   secret: process.env.CONNECT_WEBHOOK_SECRET!,
+ *   on: {
+ *     "organization.deletion_scheduled": ({ organizationId, purgeAfter }) =>
+ *       freeze(organizationId, purgeAfter),
+ *     "organization.deletion_cancelled": ({ organizationId }) => unfreeze(organizationId),
+ *     "organization.deleted": ({ organizationId }) => purge(organizationId),
+ *   },
+ * })
+ * ```
+ *
+ * Three behaviours worth knowing, because each of them is a decision rather
+ * than an accident:
+ *
+ * **An unverified request gets a 401 and nothing else happens.** No parsing,
+ * no logging of the body, no handler. The endpoint is a public URL, so
+ * anything reachable before the signature check is reachable by anyone.
+ *
+ * **An unhandled event type is a 200.** Connect adds event types over time,
+ * and answering 4xx to one you have not written code for would dead-letter
+ * it immediately and, after enough of them, disable your endpoint. Silence
+ * is the correct answer to "we do not care about this one".
+ *
+ * **A throwing handler produces a 500, on purpose.** That is what makes
+ * Connect retry. Swallowing the error would acknowledge an event you failed
+ * to process, and the retry ladder is the only thing standing between a
+ * transient failure and a permanently missed deletion.
+ *
+ * Delivery is at-least-once and unordered. Dedupe on `envelope.id`, and
+ * reconcile against the readiness endpoint rather than trusting arrival
+ * order - the pull channel is authoritative, this one is fast.
+ */
+export declare function createConnectWebhookHandler(options: ConnectWebhookHandlerOptions): (request: Request) => Promise<Response>;

package/dist/types/types.d.ts

@@ -16,6 +16,15 @@ export interface ConnectUser {
     email: string | null;
     emailVerified: boolean;
     displayName: string | null;
+    /**
+     * The member's profile picture, or `null` when they have not set one.
+     *
+     * Deliberately nullable rather than a generated placeholder: only you know
+     * what your fallback should look like. `<ConnectUserMenu>` renders initials
+     * via `<Avatar.Fallback>`, which also covers the URL loading slowly or
+     * failing outright - so pair the two rather than branching on `null`.
+     */
+    photoUrl: string | null;
     organizationId: string;
     organizationName: string;
 }
@@ -95,7 +104,7 @@ export interface RolesResponse {
     permissionCatalog: ServicePermission[];
     roles: ServiceRoleDefinition[];
 }
-export type ReadinessBlockerCode = "subscription_missing" | "subscription_inactive" | "audience_mismatch" | "verification_required" | "verification_pending" | "verification_rejected" | "verification_expired" | "payment_method_missing" | "seat_limit_reached" | "organization_not_found" | "onboarding_approval_pending" | "onboarding_approval_rejected";
+export type ReadinessBlockerCode = "subscription_missing" | "subscription_inactive" | "audience_mismatch" | "verification_required" | "verification_pending" | "verification_rejected" | "verification_expired" | "payment_method_missing" | "seat_limit_reached" | "organization_not_found" | "onboarding_approval_pending" | "onboarding_approval_rejected" | "organization_suspended" | "payment_retry_pending";
 export interface ReadinessBlocker {
     /**
      * Branch on this. Typed as a union for the codes that exist today, widened
@@ -108,6 +117,8 @@ export interface ReadinessBlocker {
     message: string;
     /** Where in Connect the customer resolves this. `null` when nothing they do helps (e.g. a review in progress). */
     resolveUrl: string | null;
+    /** When this blocker resolves itself automatically - currently only set on `payment_retry_pending`, the deadline dunning suspends the subscription. `undefined`/`null` for every other code. */
+    graceEndsAt?: string | null;
 }
 export interface ReadinessResponse {
     organizationId: string;
@@ -432,3 +443,173 @@ export interface RevokeOtherSessionsResponse {
 }
 /** Host-controlled - the SDK has no theme provider of its own. See `ConnectUserMenuProps.theme`. */
 export type ThemeMode = "light" | "dark" | "system";
+/**
+ * `not_connected` never travels over the wire as a persisted state - it's
+ * what `ListOrganizationIntegrationsUseCase` reports for a toolkit this
+ * organization has no `IntegrationConnection` record for at all.
+ */
+export type IntegrationConnectionStatus = "not_connected" | "pending" | "active" | "failed" | "disconnected" | "expired";
+/**
+ * A Composio-hosted third-party toolkit (Google Calendar, Slack, Twitter/X,
+ * ...) this organization can see - only ever one a platform admin enabled in
+ * Connect's own Console, joined with this org's own connection status.
+ * Connections are org-shared: one covers every member, the way a Slack app
+ * install is shared rather than per-user.
+ */
+export interface IntegrationToolkit {
+    slug: string;
+    name: string;
+    description: string;
+    category: string | null;
+    logoUrl: string | null;
+    status: IntegrationConnectionStatus;
+}
+export interface IntegrationsListResponse {
+    toolkits: IntegrationToolkit[];
+}
+/** The connection isn't active yet when this returns - see `IntegrationsResource.initiateConnect`'s doc comment. */
+export interface InitiateIntegrationConnectionResponse {
+    /** Send the browser here to complete the provider's OAuth screen. */
+    redirectUrl: string;
+    connectionId: string;
+}
+export interface DisconnectIntegrationResponse {
+    success: true;
+}
+export interface ExecuteIntegrationActionResponse {
+    data: unknown;
+    successful: boolean;
+}
+/**
+ * The metrics Connect can report for your service.
+ *
+ * Hand-written here rather than imported from Connect's own registry, like
+ * every other wire type in this file, so the published package carries none of
+ * Connect's internals. `conformance.test.ts` type-checks these against the
+ * server DTOs, so drift fails the build in Connect's repo rather than in a
+ * partner's integration.
+ */
+export type ConnectMetric = "usage.events" | "usage.active_users" | "api.requests" | "api.errors" | "billing.mrr_paise" | "billing.active_subscriptions" | "metering.addon_consumed";
+export interface AnalyticsPoint {
+    /** `YYYY-MM-DD`, UTC. */
+    day: string;
+    /**
+     * **`null` is not zero.** It means the metric was not measurable that day -
+     * `usage.active_users` is a distinct count that only exists after Connect's
+     * nightly rollup, so today's is always `null`, as is any future day. Render
+     * it as a gap or a dash, never as a zero.
+     */
+    value: number | null;
+}
+export interface AnalyticsSeries {
+    metric: ConnectMetric;
+    points: AnalyticsPoint[];
+    /** Sum across measurable days only, or `null` if no day in the range was measurable. */
+    total: number | null;
+    /** True when at least one day was not measurable - caveat the total when this is set. */
+    partial: boolean;
+}
+export interface AnalyticsResponse {
+    from: string;
+    to: string;
+    series: AnalyticsSeries[];
+}
+export interface AnalyticsQuery {
+    metrics: ConnectMetric[];
+    /** Inclusive `YYYY-MM-DD`, UTC. The range must be shorter than 90 days. */
+    from: string;
+    to: string;
+}
+/** One event you push into Connect's analytics pipeline. */
+export interface EmitEventInput {
+    /**
+     * Dot-namespaced and lowercase, e.g. `checkout.completed`. Prefixes Connect
+     * emits itself - `api.`, `billing.`, `addon.`, `subscription.`, `connect.` -
+     * are rejected, so your events can never inflate a metered number.
+     */
+    name: string;
+    /** Defaults to now. Clamped server-side to within 48 hours. */
+    occurredAt?: string | Date;
+    /** Attributes the event to the signed-in user and their organization. */
+    sessionToken?: string;
+    /** A whole number in the smallest unit of `unit` - paise, bytes, milliseconds. */
+    value?: number;
+    unit?: string;
+    props?: Record<string, unknown>;
+}
+export interface EmitEventsResponse {
+    /** False when the call failed outright - see `AnalyticsResource.emit`. */
+    delivered: boolean;
+    accepted: number;
+    attributed: number;
+}
+/**
+ * Every event Connect will POST to your webhook endpoint.
+ *
+ * Additive only - Connect adds event types, never renames one - so a
+ * `switch` that does not handle a future type is safe, and
+ * `createConnectWebhookHandler` simply ignores anything you have not
+ * registered a handler for.
+ */
+export type ConnectWebhookEventType = "organization.deletion_scheduled" | "organization.deletion_cancelled" | "organization.deleted" | "subscription.cancelled";
+/**
+ * A workspace's deletion has been confirmed and the grace window is running.
+ *
+ * Access is *already* denied - readiness reports
+ * `organization_pending_deletion` from this moment - so treat this as "stop
+ * writing", not "start planning". `purgeAfter` is what makes this event worth
+ * having: the customer's data still exists until then, so an export or a
+ * wind-down can run on the same clock rather than after everything is gone.
+ */
+export interface OrganizationDeletionScheduledEvent {
+    organizationId: string;
+    /** ISO-8601. When Connect destroys the workspace. */
+    purgeAfter: string;
+    requestedBy: "owner" | "platform_admin";
+    graceDays: number;
+}
+/**
+ * The deletion was withdrawn and the workspace is live again.
+ *
+ * **Handle this one.** It is the event integrations forget, and its absence
+ * is the worst failure of the set: a service that froze a workspace on
+ * `organization.deletion_scheduled` and never unfreezes leaves a paying
+ * customer locked out of something that has no idea anything changed.
+ */
+export interface OrganizationDeletionCancelledEvent {
+    organizationId: string;
+}
+/** The grace window closed and Connect purged the workspace. Purge your own copy. */
+export interface OrganizationDeletedEvent {
+    organizationId: string;
+    /** ISO-8601. */
+    purgedAt: string;
+}
+/** A subscription ended. Fires on its own, not only as part of a deletion. */
+export interface SubscriptionCancelledEvent {
+    organizationId: string;
+    subscriptionId: string;
+    serviceId: string;
+}
+/** Maps each event type to the shape of its `data`. */
+export interface ConnectWebhookEventMap {
+    "organization.deletion_scheduled": OrganizationDeletionScheduledEvent;
+    "organization.deletion_cancelled": OrganizationDeletionCancelledEvent;
+    "organization.deleted": OrganizationDeletedEvent;
+    "subscription.cancelled": SubscriptionCancelledEvent;
+}
+/** The envelope, as it arrives on the wire. */
+export interface ConnectWebhookEnvelope<T extends ConnectWebhookEventType = ConnectWebhookEventType> {
+    /**
+     * Unique per delivery. **Dedupe on this.** Delivery is at-least-once and
+     * unordered: a partner that assumes exactly-once, or assumes order, will
+     * eventually be wrong.
+     */
+    id: string;
+    type: T;
+    /** ISO-8601. */
+    createdAt: string;
+    /** Bumped only for a breaking payload change - never for a new event type. */
+    apiVersion: string;
+    data: ConnectWebhookEventMap[T];
+}