@cosmoops/connect-sdk 0.1.0

package/dist/esm/client/use-checkout.js

@@ -0,0 +1,168 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useConnect } from "./provider.js";
+/** How often `/entitlements` is re-read while a checkout is open. */
+const POLL_INTERVAL_MS = 3_000;
+/** Give up polling after this long. Long enough for a card 3-D Secure detour, short enough not to poll a forgotten tab all day. */
+const POLL_DEADLINE_MS = 15 * 60 * 1000;
+/**
+ * Grace period after the Connect window closes before calling it abandoned.
+ *
+ * The window can close a beat before Connect's own write lands - and on the
+ * paid path the subscription is created `"created"` and confirmed by a
+ * webhook, so "closed" and "settled" are genuinely different moments. A few
+ * extra polls here is the difference between a correct success and telling a
+ * customer who just paid that nothing happened.
+ */
+const CLOSE_GRACE_MS = 12_000;
+/**
+ * Drives a checkout that completes on Connect, not here.
+ *
+ * The partner's page cannot complete a subscription itself - see
+ * `ConnectPlans`' doc comment for why that is deliberate - so the flow is:
+ * open Connect, watch `/entitlements` until the entitlement changes, then
+ * refresh the session so every Connect component on the page repaints.
+ *
+ * **The result is read from Connect's own state, never from the window.**
+ * A closed window proves nothing: the customer may have paid and closed it,
+ * or opened it, thought better of it, and closed it. Polling is what tells
+ * the two apart, which is why the window closing only starts a short grace
+ * period rather than ending the run.
+ */
+export function useConnectCheckout() {
+    const { fetchResource, invalidateResource, refresh } = useConnect();
+    const [state, setState] = useState({ status: "idle", url: null });
+    // Everything the poll loop needs lives in a ref: it runs from a timer, and
+    // re-creating the loop whenever a piece of it changed identity would
+    // restart the very interval that is meant to survive re-renders.
+    const run = useRef(null);
+    const generation = useRef(0);
+    const stop = useCallback(() => {
+        generation.current += 1;
+        run.current = null;
+    }, []);
+    const reset = useCallback(() => {
+        stop();
+        setState({ status: "idle", url: null });
+    }, [stop]);
+    const start = useCallback(({ url, isSettled }) => {
+        stop();
+        // Opened synchronously inside the press handler - a `window.open` after
+        // an await is what pop-up blockers exist to stop, and it would be
+        // blocked in every browser regardless of the user's settings.
+        //
+        // No `noopener`: with it set, `window.open` returns `null` by
+        // specification, and this hook would then read every successfully
+        // opened checkout as blocked. The handle is the whole point - it is
+        // how the grace period below knows the customer closed the window.
+        // The window it hands an `opener` to is Connect's own origin, and
+        // cross-origin access is limited to navigating this page, which
+        // Connect does not do.
+        const opened = window.open(url, "connect_checkout", "popup,width=520,height=780");
+        if (!opened) {
+            // Not a failure to report as an error: the customer can still get
+            // there, they just have to click the link themselves.
+            setState({ status: "blocked", url });
+            return;
+        }
+        run.current = {
+            url,
+            isSettled,
+            window: opened,
+            closedAt: null,
+            startedAt: Date.now(),
+            generation: generation.current,
+        };
+        setState({ status: "waiting", url });
+    }, [stop]);
+    useEffect(() => {
+        // One interval for the hook's whole life rather than one per run: it does
+        // nothing while `run.current` is null, and a run that starts from a press
+        // handler picks it up on the next tick without re-creating the timer.
+        let inFlight = false;
+        const poll = async () => {
+            const current = run.current;
+            if (!current || inFlight)
+                return;
+            const now = Date.now();
+            const expired = now - current.startedAt > POLL_DEADLINE_MS;
+            // `closed` is readable cross-origin; nothing else about the window is.
+            if (current.window?.closed && current.closedAt === null)
+                current.closedAt = now;
+            const graceElapsed = current.closedAt !== null && now - current.closedAt > CLOSE_GRACE_MS;
+            inFlight = true;
+            let settled = false;
+            try {
+                invalidateResource("/entitlements");
+                settled = current.isSettled(await fetchResource("/entitlements"));
+            }
+            catch {
+                // A bridge blip mid-checkout is not an answer either way - keep
+                // polling and let the deadline decide.
+            }
+            finally {
+                inFlight = false;
+            }
+            // The run may have been superseded or reset while that read was in
+            // flight; writing state from it now would resurrect a dead run.
+            if (run.current?.generation !== current.generation)
+                return;
+            if (settled) {
+                stop();
+                setState({ status: "completed", url: current.url });
+                // Session-wide, not just this path: `/session` carries its own
+                // `subscription` block, and every other Connect component on the
+                // page reads through the same cache.
+                void refresh();
+                return;
+            }
+            if (graceElapsed || expired) {
+                stop();
+                setState({ status: "abandoned", url: current.url });
+            }
+        };
+        const interval = setInterval(() => void poll(), POLL_INTERVAL_MS);
+        // Coming back to this tab is the strongest hint available that something
+        // happened in the other one - poll immediately rather than waiting out
+        // the interval the customer is now staring at.
+        const onVisible = () => {
+            if (document.visibilityState === "visible")
+                void poll();
+        };
+        document.addEventListener("visibilitychange", onVisible);
+        return () => {
+            clearInterval(interval);
+            document.removeEventListener("visibilitychange", onVisible);
+        };
+    }, [fetchResource, invalidateResource, refresh, stop]);
+    return { ...state, start, reset };
+}
+/**
+ * The Connect URL that cancels a subscription.
+ *
+ * Its own builder rather than a mode on `buildCheckoutUrl`, because it takes
+ * no plan: cancelling is about the subscription, not about what to move it to.
+ * Lands on the same kind of intercepted modal the other two do
+ * (`app/@modal/(.)billing/.../cancel`).
+ */
+export function buildCancelUrl({ appUrl, subscriptionId }) {
+    return new URL(`/billing/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`, appUrl).toString();
+}
+/**
+ * The Connect URL that completes a subscribe or a plan change.
+ *
+ * Both land on a modal Connect renders over the relevant page (an intercepted
+ * parallel route - `app/@modal/(.)services/...` and
+ * `app/@modal/(.)billing/...`), so the customer arrives already looking at the
+ * confirmation for the plan they picked here, not at a catalogue they have to
+ * find it in again.
+ */
+export function buildCheckoutUrl({ appUrl, serviceId, planId, subscriptionId, coupon, }) {
+    const path = subscriptionId
+        ? `/billing/subscriptions/${encodeURIComponent(subscriptionId)}/change-plan/${encodeURIComponent(planId)}`
+        : `/services/${encodeURIComponent(serviceId)}/subscribe/${encodeURIComponent(planId)}`;
+    const url = new URL(path, appUrl);
+    if (coupon?.trim())
+        url.searchParams.set("coupon", coupon.trim());
+    return url.toString();
+}

package/dist/esm/errors.js

@@ -0,0 +1,69 @@
+/**
+ * Every failure the Connect service API can report, as one class.
+ *
+ * The API speaks two error dialects and this collapses them: the
+ * `/api/v1/service/*` endpoints use `{ error: { code, message } }`, while the
+ * three `/sso/*` ones use OAuth2's `{ error, error_description }` (RFC 6749
+ * §5.2). Both land here with `code` populated, so integrating code branches on
+ * one field either way.
+ */
+export class ConnectError extends Error {
+    name = "ConnectError";
+    /** HTTP status. `0` when the request never got a response (network failure, timeout). */
+    status;
+    /** `rate_limited`, `forbidden`, `invalid_token`, ... - branch on this, never on `message`. */
+    code;
+    /** From `Retry-After` on a 429, in milliseconds. `null` otherwise. */
+    retryAfterMs;
+    /** The endpoint that failed, e.g. `POST /sso/token` - present on every error. */
+    endpoint;
+    /** Parsed response body, when there was one. */
+    body;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.status = init.status;
+        this.code = init.code;
+        this.endpoint = init.endpoint;
+        this.retryAfterMs = init.retryAfterMs ?? null;
+        this.body = init.body;
+    }
+    /**
+     * Whether trying the exact same request again could plausibly succeed -
+     * throttling, a transient server fault, or no response at all. The SDK
+     * already retries these internally (see `ConnectClientOptions.maxRetries`);
+     * this is for callers deciding whether to queue their own retry after the
+     * SDK has given up.
+     */
+    get isRetryable() {
+        return this.status === 0 || this.status === 429 || this.status >= 500;
+    }
+    /**
+     * Whether the user's Connect sign-in is over and they need to go back
+     * through `identity.authorizeUrl()`. Collapses every session-side failure,
+     * matching how the API reports them - unknown, expired, revoked, or issued
+     * to a different service all arrive as one `invalid_token`.
+     */
+    get isSessionExpired() {
+        return this.code === "invalid_token";
+    }
+    /**
+     * Whether *your own API key* is dead - revoked or past its expiry - rather
+     * than the request being wrong.
+     *
+     * Connect answers `403` for every credential failure and keeps the code
+     * uniform (`forbidden`) whenever telling them apart would help someone
+     * 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.
+     *
+     * Worth alerting on. It is the one failure that will not resolve itself and
+     * takes down every call your integration makes.
+     */
+    get isKeyRejected() {
+        return this.code === "key_revoked" || this.code === "key_expired";
+    }
+}
+export function isConnectError(error) {
+    return error instanceof ConnectError;
+}

package/dist/esm/format-relative-time.js

@@ -0,0 +1,15 @@
+/** "3m ago" / "2h ago" / "5d ago", falling back to a plain date past 30 days. */
+export function formatRelativeTime(date) {
+    const diffMinutes = Math.round((Date.now() - date.getTime()) / 60_000);
+    if (diffMinutes < 1)
+        return "just now";
+    if (diffMinutes < 60)
+        return `${diffMinutes}m ago`;
+    const diffHours = Math.round(diffMinutes / 60);
+    if (diffHours < 24)
+        return `${diffHours}h ago`;
+    const diffDays = Math.round(diffHours / 24);
+    if (diffDays < 30)
+        return `${diffDays}d ago`;
+    return date.toLocaleDateString();
+}

package/dist/esm/helpers.js

@@ -0,0 +1,26 @@
+/**
+ * The blockers that actually deny access, in the order to show them.
+ *
+ * Advisory ones (no saved payment method mid-subscription, say) are worth
+ * surfacing but are not a reason to lock anyone out today - filtering them here
+ * keeps that judgement in one place rather than in every call site.
+ */
+export function blockingBlockers(readiness) {
+    return readiness.readiness.blockers.filter((blocker) => blocker.severity === "blocking");
+}
+/**
+ * Coerces either wire shape into `PlanFeature[]`.
+ *
+ * A bare key becomes `{ key, name: key, description: "" }` - the same
+ * fallback the server applies for a plan older than its service's feature
+ * catalog, so an un-upgraded Connect renders exactly what it always did
+ * rather than a column of blanks.
+ *
+ * Applied inside `BillingResource.listPlans`, so anything reading a plan
+ * through the SDK or its bridge already has the normalised shape and no
+ * component needs to know this ambiguity exists. Exported for a partner who
+ * hand-rolled a bridge instead of using `createConnectHandler`.
+ */
+export function normalizePlanFeatures(features) {
+    return (features ?? []).map((feature) => typeof feature === "string" ? { key: feature, name: feature, description: "" } : feature);
+}

package/dist/esm/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@cosmoops/connect-sdk` - the official client for the CosmoOps Connect
+ * **service-partner API** (`/api/v1/service/*`).
+ *
+ * This root entry is the isomorphic surface: wire types, the error class, and
+ * pure helpers. It pulls in neither Node-only code nor React, so it is safe to
+ * import from anywhere.
+ *
+ * - `@cosmoops/connect-sdk/server` - `ConnectClient` and `createConnectHandler`.
+ *   Holds the API key. Never import this from browser code.
+ * - `@cosmoops/connect-sdk/client` - React components and hooks. Talks to your
+ *   own origin only.
+ */
+export { ConnectError, isConnectError } from "./errors.js";
+export { blockingBlockers, normalizePlanFeatures } from "./helpers.js";

package/dist/esm/next/index.js

@@ -0,0 +1,279 @@
+import { ConnectClient } from "../server/client.js";
+import { createConnectHandler } from "../server/handler.js";
+/**
+ * Plug-and-play wiring for Next.js.
+ *
+ * Everything below is server-side. Nothing here is *statically* imported from
+ * `next`, so this module loads in App Router route handlers, the Node runtime
+ * and the edge runtime alike - and needs no peer dependency. The one place
+ * that does reach for `next/headers` does it behind a dynamic import, inside
+ * the function that needs it, and says so when it isn't there.
+ *
+ * The whole integration is two files:
+ *
+ * ```ts
+ * // app/api/connect/[...connect]/route.ts
+ * export { GET, POST } from "@cosmoops/connect-sdk/next";
+ * ```
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { ConnectProvider } from "@cosmoops/connect-sdk/client";
+ * <ConnectProvider>{children}</ConnectProvider>
+ * ```
+ *
+ * Plus one line in `next.config.ts`, which is optional but catches the single
+ * misconfiguration that fails silently:
+ *
+ * ```ts
+ * import { withConnect } from "@cosmoops/connect-sdk/next";
+ * export default withConnect({});
+ * ```
+ *
+ * Configuration comes from the environment, so none of those files take
+ * arguments:
+ *
+ * | Variable | Required | Purpose |
+ * | --- | --- | --- |
+ * | `CONNECT_API_KEY` | yes | server-side credential |
+ * | `CONNECT_CLIENT_ID` | yes | OAuth client id |
+ * | `NEXT_PUBLIC_CONNECT_CLIENT_ID` | yes | same value, for `<ConnectProvider>` |
+ * | `CONNECT_APP_URL` | no | non-production Connect instance |
+ * | `CONNECT_SESSION_COOKIE` | no | session cookie name |
+ *
+ * Register `{your origin}/api/connect/callback` as a redirect URI in the
+ * service's Setup tab. That is the only step this cannot do for you.
+ */
+const DEFAULT_COOKIE = "connect_session";
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`@cosmoops/connect-sdk/next: ${name} is not set. Add it to your environment - see the module docs for the full list.`);
+    }
+    return value;
+}
+let cached = null;
+/**
+ * The shared server client, built from the environment on first use.
+ *
+ * Lazy on purpose: reading `CONNECT_API_KEY` at module load would throw during
+ * `next build`, where route modules are imported but never invoked and secrets
+ * are frequently absent.
+ */
+export function connectClient(overrides = {}) {
+    if (cached && Object.keys(overrides).length === 0)
+        return cached;
+    const client = new ConnectClient({
+        apiKey: requireEnv("CONNECT_API_KEY"),
+        clientId: requireEnv("CONNECT_CLIENT_ID"),
+        ...(process.env.CONNECT_APP_URL ? { baseUrl: process.env.CONNECT_APP_URL } : {}),
+        ...overrides,
+    });
+    if (Object.keys(overrides).length === 0)
+        cached = client;
+    return client;
+}
+/**
+ * An httpOnly cookie holding the opaque `sessionToken`.
+ *
+ * Not signed or encrypted, deliberately. The token is opaque and useless
+ * without the `client_secret` that never leaves the server, so a tampered
+ * value buys an attacker a 401 rather than a forged identity - and a signing
+ * secret would be one more thing to rotate for protection already provided by
+ * the token's own design. `SameSite=Lax` because `Strict` would withhold the
+ * cookie on the redirect back from Connect.
+ */
+export function cookieSessionStore(cookieName = process.env.CONNECT_SESSION_COOKIE ?? DEFAULT_COOKIE) {
+    const serialise = (value, maxAge, secure) => [
+        `${cookieName}=${encodeURIComponent(value)}`,
+        "Path=/",
+        "HttpOnly",
+        "SameSite=Lax",
+        secure ? "Secure" : "",
+        `Max-Age=${maxAge}`,
+    ]
+        .filter(Boolean)
+        .join("; ");
+    const isSecure = (request) => new URL(request.url).protocol === "https:";
+    return {
+        read(request) {
+            const header = request.headers.get("cookie");
+            if (!header)
+                return null;
+            for (const part of header.split(";")) {
+                const [key, ...rest] = part.trim().split("=");
+                if (key === cookieName)
+                    return decodeURIComponent(rest.join("=")) || null;
+            }
+            return null;
+        },
+        write(request, response, sessionToken) {
+            // ~15 days, matching the token's own lifetime - a cookie that outlives
+            // the token it carries only produces confident 401s.
+            response.headers.append("set-cookie", serialise(sessionToken, 15 * 24 * 60 * 60, isSecure(request)));
+        },
+        clear(request, response) {
+            response.headers.append("set-cookie", serialise("", 0, isSecure(request)));
+        },
+    };
+}
+/**
+ * The catch-all route handlers, ready to re-export.
+ *
+ * Only needed when you are changing something - a different mount point, a
+ * session store that isn't a cookie, a post-login destination that isn't `/`.
+ * The zero-configuration case is the `GET` / `POST` re-export below, which is
+ * this function with no arguments.
+ *
+ * ```ts
+ * // app/api/connect/[...connect]/route.ts
+ * import { createConnectHandlers } from "@cosmoops/connect-sdk/next";
+ * export const { GET, POST } = createConnectHandlers({ basePath: "/api/auth" });
+ * ```
+ *
+ * `GET` and `POST` are the same function - the bridge routes on method and
+ * path itself, so Next only needs to know both verbs reach it.
+ */
+export function createConnectHandlers(options = {}) {
+    const handler = createConnectHandler({
+        client: options.client ?? connectClient(),
+        session: options.session ?? cookieSessionStore(),
+        ...(options.basePath ? { basePath: options.basePath } : {}),
+        ...(options.defaultRedirect ? { defaultRedirect: options.defaultRedirect } : {}),
+    });
+    return { GET: handler, POST: handler };
+}
+let defaultHandler = null;
+/**
+ * The bridge itself, for the default mount at `/api/connect`.
+ *
+ * Built on the first request rather than at module load, for the same reason
+ * `connectClient` is lazy: `next build` imports every route module, and an
+ * environment-reading constructor at the top level turns a missing secret in
+ * CI into a failed build of routes that were never going to run there.
+ */
+async function handle(request) {
+    defaultHandler ??= createConnectHandler({
+        client: connectClient(),
+        session: cookieSessionStore(),
+    });
+    return defaultHandler(request);
+}
+/**
+ * The one-line backend.
+ *
+ * ```ts
+ * // app/api/connect/[...connect]/route.ts
+ * export { GET, POST } from "@cosmoops/connect-sdk/next";
+ * ```
+ *
+ * That gives you `/signin`, `/callback`, the session cookie, and the
+ * `/session` `/entitlements` `/plans` `/apps` `/addons` `/sessions` `/logout`
+ * reads the browser half calls. Reach for `createConnectHandlers` instead only
+ * when you need to configure one of them.
+ */
+export { handle as GET, handle as POST };
+/**
+ * Rebuilds a `Request` from the headers of the Server Component, Route Handler
+ * or Server Action currently rendering.
+ *
+ * `next/headers` is imported dynamically and only from here, so this module
+ * still has no static dependency on `next` - which is what lets it load on the
+ * edge runtime and in a non-Next backend that only wants `createConnectHandler`.
+ */
+async function requestFromHeaders() {
+    let read;
+    try {
+        ({ headers: read } = await import("next/headers"));
+    }
+    catch (cause) {
+        throw new Error("@cosmoops/connect-sdk/next: getConnectSession() with no arguments needs `next/headers`, which only exists inside a Server Component, Route Handler or Server Action. Pass the `Request` explicitly anywhere else.", { cause });
+    }
+    // Deliberately outside the try. `headers()` *throws* to tell Next this route
+    // is dynamic - `DYNAMIC_SERVER_USAGE` is control flow, not a fault - and a
+    // catch around it converts a route that should have opted out of prerendering
+    // into a failed build. Only the import is guarded, because only the import
+    // can be legitimately absent.
+    const incoming = (await read());
+    // Only the cookie header is actually read, but the URL has to be well-formed
+    // and its protocol is what a custom session store would use to decide
+    // `Secure` - so reconstruct the real one rather than hardcoding localhost.
+    const host = incoming.get("x-forwarded-host") ?? incoming.get("host") ?? "localhost";
+    const proto = incoming.get("x-forwarded-proto") ?? (host.startsWith("localhost") ? "http" : "https");
+    return new Request(`${proto}://${host}/`, { headers: incoming });
+}
+/**
+ * The signed-in user for a Server Component, Route Handler or Server Action,
+ * or `null`.
+ *
+ * ```tsx
+ * // app/dashboard/page.tsx
+ * const session = await getConnectSession();
+ * if (!session) redirect("/api/connect/signin?next=/dashboard");
+ * ```
+ *
+ * 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.
+ *
+ * Reads `cookies()` transitively, so under `cacheComponents` this belongs
+ * inside a `<Suspense>` boundary (or a `'use cache: private'` function) like
+ * any other request-scoped read - a page that awaits it above every boundary
+ * gives up its static shell.
+ *
+ * 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.
+ */
+export async function getConnectSession(request, options = {}) {
+    const store = options.session ?? cookieSessionStore();
+    const token = await store.read(request ?? (await requestFromHeaders()));
+    if (!token)
+        return null;
+    try {
+        return await (options.client ?? connectClient()).identity.getUser(token);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `next.config` wrapper.
+ *
+ * Asserts, at config load, that the public client id is present - the one
+ * variable whose absence fails silently in the browser instead of loudly on
+ * the server, because `NEXT_PUBLIC_*` is inlined at build time and an unset
+ * one simply becomes `undefined`. That is its whole job.
+ *
+ * In particular it does **not** replace the bridge route, and cannot: Next has
+ * no plugin API that contributes a route from a `node_modules` package - the
+ * App Router discovers routes by walking your own `app/` directory and nothing
+ * else, and a `next.config` rewrite still needs a real route to point at. So
+ * `app/api/connect/[...connect]/route.ts` has to exist whether or not you use
+ * this wrapper. It is one line, and `npx @cosmoops/connect-sdk init` writes it:
+ *
+ * ```ts
+ * export { GET, POST } from "@cosmoops/connect-sdk/next";
+ * ```
+ *
+ * The two are independent - the route works with a plain config, and this
+ * wrapper is useful with no route at all. Using both is just the default setup.
+ *
+ * It does **not** add this package to `transpilePackages`, and you should not
+ * either. `dist/` is already ES2022 with `"use client"` hoisted to the top of
+ * every browser file, so Turbopack and webpack both consume it as-is;
+ * transpiling it again only costs build time. An earlier version of this
+ * wrapper added the entry, which is why it may still be in your config.
+ *
+ * ```ts
+ * import { withConnect } from "@cosmoops/connect-sdk/next";
+ * export default withConnect({ });
+ * ```
+ */
+export function withConnect(config = {}) {
+    if (!process.env.NEXT_PUBLIC_CONNECT_CLIENT_ID && process.env.NODE_ENV !== "test") {
+        console.warn("[@cosmoops/connect-sdk] NEXT_PUBLIC_CONNECT_CLIENT_ID is not set - <ConnectProvider> will not be able to start a sign-in.");
+    }
+    return config;
+}
+export { createConnectHandler } from "../server/handler.js";
+export { ConnectClient } from "../server/client.js";

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}