@cosmoops/connect-sdk 0.33.0 → 0.34.0

package/dist/types/client/use-checkout.d.ts

@@ -77,6 +77,23 @@ export interface CheckoutUrlOptions {
     subscriptionId?: string | null;
     /** Carried into Connect's checkout, where it is validated against the real cart. */
     coupon?: string | null;
+    /**
+     * Where Connect sends the customer once the subscription is live - an
+     * absolute URL on your own origin.
+     *
+     * **Without it they do not come back.** Connect's default destination is
+     * the new subscription's own billing page, which is the right answer for
+     * someone who started in Connect and the wrong one for someone who started
+     * on your pricing page: they pay, land on a billing screen for a product
+     * they were in the middle of adopting, and nothing on it points home.
+     *
+     * Connect validates the origin against the redirect URIs registered for
+     * your Connect client and silently ignores anything else, so a value it
+     * does not recognise costs the return trip and never redirects your
+     * customer somewhere you did not register. Register the origin you intend
+     * to use; the path and query are yours.
+     */
+    next?: string | null;
 }
 /**
  * The Connect URL that cancels a subscription.
@@ -103,4 +120,4 @@ export declare function buildCancelUrl({ appUrl, subscriptionId }: {
  * prefix that has never served this page. Building the other one is what
  * sent every first-time subscriber from a partner's pricing page to a 404.
  */
-export declare function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, }: CheckoutUrlOptions): string;
+export declare function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, next, }: CheckoutUrlOptions): string;

package/dist/types/helpers.d.ts

@@ -1,4 +1,4 @@
-import type { PlanFeature, ReadinessBlocker, ReadinessResponse } from "./types.js";
+import type { PlanFeature, PlanLimit, ReadinessBlocker, ReadinessResponse } from "./types.js";
 /**
  * The blockers that actually deny access, in the order to show them.
  *
@@ -31,3 +31,38 @@ export type WirePlanFeature = string | PlanFeature;
  * hand-rolled a bridge instead of using `createConnectHandler`.
  */
 export declare function normalizePlanFeatures(features: readonly WirePlanFeature[] | undefined): PlanFeature[];
+/**
+ * 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.
+ */
+export declare const NO_PLAN_LIMIT: PlanLimit;
+/**
+ * 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.
+ */
+export declare function planLimitFor(limits: Readonly<Record<string, PlanLimit>> | undefined, key: string): PlanLimit;
+/**
+ * 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.");
+ * }
+ * ```
+ */
+export declare function planLimitAllows(limit: PlanLimit, currentCount: number, additional?: number): boolean;

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@
  */
 export { ConnectError, isConnectError } from "./errors.js";
 export { blockingBlockers, normalizePlanFeatures } from "./helpers.js";
+export { NO_PLAN_LIMIT, planLimitAllows, planLimitFor } from "./helpers.js";
 export { arrayRemove, arrayUnion, deleteField, documentExists, increment, serverTimestamp, storeIndexFor, storeIndexSignature, unchangedSince, } from "./store.js";
 export type { StoreIndexDirection, StoreIndexField } from "./store.js";
 export { describeQueryRejection, storeIndexCovers } from "./store-schema.js";

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

@@ -138,4 +138,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.32.0";
+export declare const SDK_VERSION = "0.34.0";

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

@@ -12,6 +12,10 @@ export declare 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.
      */
     listPlans(): Promise<PlansResponse>;
     /**

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

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { ApplicationSubscriber, ReadinessResponse, SubscribersResponse, SubscriptionResponse } from "../../types.js";
+import type { ApplicationSubscriber, PlanLimit, ReadinessResponse, SubscribersResponse, SubscriptionResponse } from "../../types.js";
 /**
  * The two checks worth making on every request: may this workspace be here at
  * all, and what is it paying for.
@@ -28,6 +28,45 @@ export declare class EntitlementsResource {
      * should not need a try/catch around it.
      */
     hasFeature(workspaceId: string, feature: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    getLimit(workspaceId: string, key: string): Promise<PlanLimit>;
+    /**
+     * 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.");
+     * }
+     * ```
+     */
+    canAdd(workspaceId: string, key: string, currentCount: number, additional?: number): Promise<boolean>;
     /**
      * One page of the workspaces subscribed to your application, newest first.
      *

package/dist/types/types.d.ts

@@ -292,6 +292,57 @@ export interface PlanFeature {
     /** Empty string when the catalog carries no description. */
     description: string;
 }
+/**
+ * How much of one metered resource a plan allows, as the **catalogue** read
+ * reports it: the application's own declaration (`key`, `name`, `unit`) joined
+ * to this plan's answer.
+ *
+ * The limits counterpart of `PlanFeature`, and it carries the same asymmetry
+ * against `SubscribedPlan.limits` for the same reason - that one is a contract
+ * keyed for lookup, this one is a row to render.
+ *
+ * There is one entry per limit the application declares, including the ones a
+ * tier allows none of (`model: "none"`). "Starter: 1 site" only means anything
+ * beside "Growth: 5 sites", so a comparison table needs the row even where the
+ * answer is nothing; a card showing only what a tier includes filters on
+ * `model !== "none"`.
+ */
+export interface ResolvedPlanLimit {
+    /** What `getLimit` and `SubscribedPlan.limits` are keyed by. */
+    key: string;
+    /** Human label, e.g. "Sites". */
+    name: string;
+    /** The noun the number needs, e.g. "sites" - render as `${value} ${unit}`. */
+    unit: string;
+    /** Empty string when the application's catalog carries no description. */
+    description: string;
+    model: PlanLimit["model"];
+    /** Non-null iff `model` is `"limited"`. */
+    value: number | null;
+}
+/**
+ * What a plan allows of one metered resource - the **gating** shape, which is
+ * what `getLimit` returns and `planLimitAllows` takes.
+ *
+ * **Three states rather than a nullable number, deliberately.** The obvious
+ * encoding - a `number | null` where `null` means unlimited - makes
+ * `if (!limit) refuse()` read as correct while refusing every subscriber on
+ * the most generous tier, which is the one case nobody tests. Use
+ * `planLimitAllows` rather than comparing by hand: `count < value` is off by
+ * one when adding more than one row, and `value ?? Infinity` grants unlimited
+ * to a plan that allows none.
+ */
+export interface PlanLimit {
+    /**
+     * - `"none"`: this plan does not allow the resource at all. Also what a key
+     *   the plan carries no answer for reads as - see `SubscribedPlan.limits`.
+     * - `"limited"`: a ceiling of `value`.
+     * - `"unlimited"`: no ceiling.
+     */
+    model: "none" | "limited" | "unlimited";
+    /** The ceiling. Non-null iff `model` is `"limited"`, and always >= 1 there - zero is spelled `"none"`. */
+    value: number | null;
+}
 export interface Plan {
     id: string;
     name: string;
@@ -319,6 +370,8 @@ export interface Plan {
     trialDays: number | null;
     /** What this plan unlocks, labelled for display - see `PlanFeature`. */
     features: PlanFeature[];
+    /** How much of each metered resource this plan allows, labelled for display - see `ResolvedPlanLimit`. */
+    limits: ResolvedPlanLimit[];
 }
 /**
  * How often a plan bills.
@@ -351,6 +404,27 @@ export interface SubscribedPlan {
      * comparable, a display name is neither.
      */
     features: string[];
+    /**
+     * How much of each metered resource this workspace may have, keyed by the
+     * limit key your application declared - see `PlanLimit`.
+     *
+     * **Effective, not the tier's raw number**: whatever the add-ons on this
+     * subscription raise a limit by is already folded in, so this is the figure
+     * to compare your own count against. The tier's base number and the add-ons
+     * that raised it are deliberately not broken out here - that is the join
+     * Connect does so nobody has to redo it per resource, per partner.
+     *
+     * **Sparse, and that is the thing to get right**: a key absent here is not
+     * "unlimited" and not an error, it is `{ model: "none" }`. Read it through
+     * `getLimit`/`planLimitFor` rather than indexing the map, which is what
+     * turns a missing key into `undefined` and then, one `?.` later, into an
+     * unbounded allowance.
+     *
+     * Same posture as `features`: Connect cannot intercept calls to your
+     * backend, so your backend compares its own count against this number.
+     * Connect stores the answer and hands it over.
+     */
+    limits: Record<string, PlanLimit>;
 }
 export interface AppliedDiscount {
     source: "coupon" | "admin";
@@ -1026,6 +1100,67 @@ export interface EmitEventsResponse {
  * registered a handler for.
  */
 export type ConnectWebhookEventType = "workspace.deletion_scheduled" | "workspace.deletion_cancelled" | "workspace.deleted" | "subscription.cancelled" | "call.completed" | "call.missed" | "booking.confirmed" | "booking.cancelled" | "booking.rescheduled" | "contact.created" | "contact.updated";
+/** What becomes of one class of data when the workspace is purged. */
+export type ConnectDataDisposition = "erase" | "anonymize" | "retain";
+/** Who answers for your copy of the customer's data. See the deletion-policy guide. */
+export type ConnectFiduciaryRole = "connect_owned" | "processor" | "independent";
+/** One kind of data your application holds, and what your policy said happens to it. */
+export interface ConnectDataClassNotice {
+    /** Stable key, as declared in Console. Safe to switch on. */
+    key: string;
+    /** What the customer was shown - e.g. "Call records". */
+    label: string;
+    disposition: ConnectDataDisposition;
+    /**
+     * How many days this class outlives the workspace **in your own archive**,
+     * or `null` when it goes with the purge.
+     *
+     * The one number in either deletion event you have to act on, and the
+     * reason `policy` is on the wire at all: `purgeAfter` is Connect's clock,
+     * this is yours. Read it rather than hardcoding the figure you typed into
+     * Console - that copy drifts the first time somebody edits the policy, and
+     * this one is the version the customer was actually promised.
+     *
+     * It is Connect's clamped value, so it is never longer than the platform
+     * ceiling even if your stored policy says otherwise.
+     */
+    retainDays: number | null;
+    /** The clause or rule you named as requiring it, shown to the customer verbatim. `null` for a class that is erased. */
+    basis: string | null;
+}
+/** An identifier allocated to the workspace that must be held before reissue - a third clock, neither the grace window nor a retention floor. */
+export interface ConnectResourceReleaseNotice {
+    key: string;
+    label: string;
+    /** Days to hold it before handing it to somebody else. */
+    quarantineDays: number;
+}
+/**
+ * Your application's own data policy, as it stood when this deletion was
+ * confirmed - the declaration the customer read before pressing the button.
+ *
+ * Carried on both deletion events so your handler can be driven by the
+ * declaration rather than by a second copy of it in your code. Two things
+ * about it are worth relying on:
+ *
+ * **It is frozen.** An operator editing the policy while a workspace is
+ * already pending deletion does not change what that deletion runs under;
+ * `version` is which one it is, so a deletion certificate can name it.
+ *
+ * **It is yours alone.** A deletion fans out to every application the
+ * workspace subscribed to, and each one receives only its own policy.
+ */
+export interface ConnectDeletionPolicyNotice {
+    /** The policy version in force when the deletion was confirmed. */
+    version: number;
+    fiduciaryRole: ConnectFiduciaryRole;
+    /** Whether your policy promised the customer an export before the window closed. */
+    exportBeforePurge: boolean;
+    policyUrl: string | null;
+    /** Empty when your application has declared no policy - which the customer was shown as "this application hasn't told us", not as "nothing is kept". */
+    dataClasses: ConnectDataClassNotice[];
+    resourceReleases: ConnectResourceReleaseNotice[];
+}
 /**
  * A workspace's deletion has been confirmed and the grace window is running.
  *
@@ -1041,6 +1176,13 @@ export interface WorkspaceDeletionScheduledEvent {
     purgeAfter: string;
     requestedBy: "owner" | "platform_admin";
     graceDays: number;
+    /**
+     * Your declared policy for this deletion - including how long each data
+     * class may outlive the purge. `null` for a deletion confirmed before
+     * policies existed, which is the only case where you fall back to your own
+     * records.
+     */
+    policy: ConnectDeletionPolicyNotice | null;
 }
 /**
  * The deletion was withdrawn and the workspace is live again.
@@ -1058,6 +1200,13 @@ export interface WorkspaceDeletedEvent {
     workspaceId: string;
     /** ISO-8601. */
     purgedAt: string;
+    /**
+     * The same frozen policy `workspace.deletion_scheduled` carried, repeated
+     * here because this is the event you act on: whether a class is destroyed
+     * now or moved to a retained store for another `retainDays` is this
+     * object's answer, not your code's.
+     */
+    policy: ConnectDeletionPolicyNotice | null;
 }
 /** A subscription ended. Fires on its own, not only as part of a deletion. */
 export interface SubscriptionCancelledEvent {

package/package.json

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