@mrrocket/sdk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this package. It follows semantic versioning; before 1.0 a minor version may change an API.
+
+## 0.1.0
+
+First public release on npm as `@mrrocket/sdk`, MIT licensed. Next.js lives under `@mrrocket/sdk/next`
+(`/next/server`, `/next/proxy`); the package root is kept for a framework-free core.
+
+- Affiliate referrals: `?mrr_ref`/`mrr_click` (tracked links) and `?ref` (direct links) are kept in a first-party `mrr_ref` cookie following consent (`attribution` prop), a click beacon goes to `/api/sdk/affiliate/click`, `$referral` rides on `identify()` and own events. New exports `getReferral`, `referralForCheckout`, `referralLink`, `readReferralCookie`. Tests: `npm test`.
+
+## 0.0.1 (never published)
+
+First installable build, compiled to JavaScript (ESM) with type declarations: no `transpilePackages` needed.
+
+- Page views, `data-ck-goal` clicks, `track`, `identify`, UTM and referrer capture, batched events.
+- Consent modes `cookieless` (default), `cookies`, `off`, `respectDnt`.
+- Experiments: `useVariant`, `<Experiment>`, `<Text>`, server helpers `getCockpitConfig`, `getVariant`, `getTexts`,
+  `previewFrom` (`/next/server`), `withCockpitId` (`/next/proxy`), preview links for MRRocket.
+- `<FeedbackBoard>`, `<FeedbackWidget>`, `useFeedback`, `<Survey>` (automatic via the provider).
+- `host` and `apiKey` default to `NEXT_PUBLIC_MRROCKET_HOST` and `NEXT_PUBLIC_MRROCKET_KEY`.
+- Server helpers run on Node, Edge and Cloudflare Workers; `getCockpitConfig` times out after 2.5 s and returns `null`
+  (control variants) when MRRocket cannot be reached.
+- Console warnings (once) when the host or key is wrong.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brombach Technologies GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,251 @@
-# Temporary Holding Version
+# @mrrocket/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MRRocket SDK. This release covers Next.js (App Router), imported from `@mrrocket/sdk/next`; other frameworks get their own entry in the same package (`@mrrocket/sdk/react` is next). One provider in your layout gives MRRocket page views, your events and A/B tests that the agents can run. MRRocket shows every variant of your real pages, because the SDK can render any variant on request.
+
+Status: 0.1.0, MIT licensed, compiled to ESM JavaScript with type declarations (no `transpilePackages`). Works with Next.js 15 and 16, React 19, on Node and on Cloudflare Workers (OpenNext). The source lives in the MRRocket repo (`prototype/web/packages/cockpit-next`).
+
+## Install
+
+```bash
+pnpm add @mrrocket/sdk   # or npm install / yarn add
+```
+
+Your public key is in MRRocket › Settings › Products, one per product (`mrr_pub_…`, or `ck_pub_…` for a product without a stored key). It is safe in the browser, like PostHog's project key. Never put a secret key in client code.
+
+Two environment variables, both public (Next.js inlines `NEXT_PUBLIC_*` at build time, so they must exist when you run `next build`):
+
+| Variable | What | Default |
+| --- | --- | --- |
+| `NEXT_PUBLIC_MRROCKET_HOST` | Where MRRocket runs, for example `https://app.example.com` (no path) | the page's own origin |
+| `NEXT_PUBLIC_MRROCKET_KEY` | The product's public key | none: the SDK warns in the console and sends nothing |
+
+`host` and `apiKey` props override them. The server answers every `/api/sdk` request with open CORS headers, so any website origin may call it.
+
+## 1. Provider in the root layout
+
+```tsx
+// app/layout.tsx
+import { CockpitProvider } from "@mrrocket/sdk/next";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+    return (
+        <html lang="en">
+            <body>
+                <CockpitProvider>
+                    {children}
+                </CockpitProvider>
+            </body>
+        </html>
+    );
+}
+```
+
+From then on every route change is a `$pageview`, and clicks on elements with `data-ck-goal` count as that goal. By default the SDK is cookieless: it stores nothing in the browser (see [Privacy and consent](#privacy-and-consent)).
+
+```tsx
+<button data-ck-goal="signup_started">Start free trial</button>
+```
+
+## 2. Your own events
+
+```tsx
+"use client";
+import { useCockpit } from "@mrrocket/sdk/next";
+
+const { track, identify } = useCockpit();
+track("checkout_started", { plan: "team" });
+identify(user.id, { plan: user.plan });
+```
+
+## 3. A/B tests
+
+MRRocket's agents create experiments; the key is shown on each test in MRRocket.
+
+Swap a whole block:
+
+```tsx
+import { Experiment } from "@mrrocket/sdk/next";
+
+<Experiment name="rr-home-logos" variants={{ control: <Hero />, a: <HeroWithLogos /> }} />;
+```
+
+Or ask for the variant:
+
+```tsx
+const variant = useVariant("rr-pricing-annual-first"); // "control" | "a"
+```
+
+Let tests change copy without a deploy: wrap the text once, and MRRocket can send new words for it.
+
+```tsx
+<h1><Text id="home.headline">Sales training that sticks</Text></h1>
+```
+
+Give each text an id that is unique across your site (`home.headline`, `pricing.cta`), because a running test changes that id wherever it appears. Control never changes text: your defaults stay.
+
+With `consent="cookies"` every visitor stays in one variant across visits (the `ck_id` cookie). Cookieless, the variant holds for client-side navigation but can change on a reload, unless you pass your own `distinctId` or call `identify()`. Exposures are recorded as `$exposure` with the experiment and the variant.
+
+## 4. No flicker: render the variant on the server
+
+```tsx
+// app/pricing/page.tsx
+import { cookies } from "next/headers";
+import { CockpitProvider } from "@mrrocket/sdk/next";
+import { getCockpitConfig, getVariant, previewFrom } from "@mrrocket/sdk/next/server";
+
+export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | string[] | undefined>> }) {
+    const sp = await searchParams;
+    const config = await getCockpitConfig(); // key and host from the environment; pass { apiKey, host } to override
+    const variant = getVariant("rr-pricing-annual-first", { config, searchParams: sp, cookies: await cookies() });
+    return (
+        <CockpitProvider config={config ?? undefined} {...previewFrom(sp)}>
+            {variant === "a" ? <YearlyFirst /> : <MonthlyFirst />}
+        </CockpitProvider>
+    );
+}
+```
+
+`getCockpitConfig` waits at most 2.5 seconds (`timeoutMs`) and returns `null` when MRRocket is unreachable, slow or answers an error: the page then renders with control variants and never throws.
+
+The server needs an id it can read. Cookieless (the default) there is none, so pass your own, for example the signed-in user's id, to both sides: `getVariant(key, { config, searchParams: sp, distinctId: user.id })` and `<CockpitProvider distinctId={user.id}>`.
+
+With `consent="cookies"`, give first-time visitors their `ck_id` before the page renders. This writes a cookie, so only do it once the visitor agreed:
+
+```ts
+// proxy.ts (Next.js 16; middleware.ts before)
+import { NextResponse, type NextRequest } from "next/server";
+import { withCockpitId } from "@mrrocket/sdk/next/proxy";
+
+export function proxy(request: NextRequest) {
+    const response = NextResponse.next();
+    withCockpitId(request.cookies, response.cookies);
+    return response;
+}
+```
+
+## 5. Cloudflare Workers (OpenNext)
+
+The server helpers (`getCockpitConfig`, `getVariant`, `getTexts`, `previewFrom`) and the proxy helper use only `fetch`, `AbortController` and plain objects, so they run on Node, the Edge runtime and Workers via `@opennextjs/cloudflare`. Put the two variables where `next build` reads them (`.env`, `.env.production`, or your CI environment), because Next.js inlines `NEXT_PUBLIC_*` during the build, not at request time.
+
+## 6. Previews in MRRocket
+
+MRRocket shows each variant of your page by loading it with `?ck_preview=<experiment>:<variant>&ck_embed=1`. The SDK renders that variant and tracks nothing while embedded, so previews never count as visits. If your site sends `X-Frame-Options: DENY` or a strict `frame-ancestors`, allow your MRRocket domain.
+
+## 7. Feedback board
+
+A Canny-style board for your own `/feedback` page: requests with votes and comments, a roadmap and a changelog. Visitors vote once; a duplicate hint shows similar requests while they type.
+
+```tsx
+// app/feedback/page.tsx
+import { FeedbackBoard } from "@mrrocket/sdk/next";
+
+export default function Page() {
+    return <FeedbackBoard title="Feedback" theme="auto" accent="#3f76ff" />;
+}
+```
+
+It must sit inside `CockpitProvider`. Call `identify(user.id, { name, email })` and comments and requests carry the user. MRRocket also hosts the same board at `/b/<productId>`.
+
+## 8. Feedback widget
+
+A floating button with the top five requests and a short suggest form.
+
+```tsx
+import { FeedbackWidget, useFeedback } from "@mrrocket/sdk/next";
+
+<FeedbackWidget position="bottom-right" label="Feedback" boardUrl="/feedback" />;
+
+// Open it from your own button:
+const { open, close } = useFeedback();
+<button onClick={open}>Send feedback</button>;
+
+// Or with no code at all:
+<a data-ck-feedback>Feedback</a>;
+```
+
+## 9. Surveys
+
+Surveys you build in MRRocket (NPS, rating, choice, text) appear automatically: three seconds after the page opens, a small card shows bottom-left (a bottom sheet on phones). Nothing shows inside MRRocket previews or with `consent="off"`. A dismissed survey stays away for that visitor: across visits with `consent="cookies"` (localStorage), otherwise for the page load.
+
+```tsx
+<CockpitProvider apiKey={key} surveys={false}>{children}</CockpitProvider> // switch surveys off
+```
+
+Widgets style themselves with one scoped stylesheet (class prefix `ckw-`), light and dark by `prefers-color-scheme`. Use `theme="light" | "dark" | "auto"` and `accent` to adjust.
+
+## 10. Affiliate referrals
+
+When the product runs an affiliate program in MRRocket, the provider picks up partner referrals by itself: `?mrr_ref=<code>&mrr_click=<id>` from a partner's tracked link (`<mrrocket>/r/<code>`) or `?ref=<code>` from a direct link. It keeps the referral in a first-party cookie `mrr_ref` on your domain plus localStorage (for the program's days, default 60), sends a click beacon for direct links, and adds `$referral: { code, clickId }` to `identify()` and your own events.
+
+```tsx
+import { getReferral, referralForCheckout, referralLink } from "@mrrocket/sdk/next";
+
+getReferral(); // { code, clickId, at } | null
+referralForCheckout(); // { client_reference_id: "mrr_ref:<code>:<clickId>", metadata: { mrr_ref, mrr_click } } | null
+referralLink("https://buy.stripe.com/abc"); // a Payment Link with client_reference_id=mrr_ref__<code>__<clickId>
+```
+
+On the server (the route that creates a Stripe Checkout Session):
+
+```ts
+import { readReferralCookie, referralForCheckout } from "@mrrocket/sdk/next/server";
+const ref = referralForCheckout(readReferralCookie((await cookies()).get("mrr_ref")?.value));
+await stripe.checkout.sessions.create({ ...params, ...(ref ?? {}), subscription_data: { metadata: ref?.metadata ?? {} } });
+```
+
+Apps with RevenueCat: set the subscriber attribute `$mrr_ref` (and `$mrr_click`), or give the partner an App Store offer code equal to their code.
+
+| Prop | Default | What |
+| --- | --- | --- |
+| `attribution` | `"consent"` | `"consent"`: stored only while `consent="cookies"`, otherwise in memory for the page load; `"always"`: stored whatever the consent (only with a legal basis); `"off"`: referrals ignored |
+| `referralParam` | `"ref"` | the query parameter of direct links |
+
+The referral cookie is a marketing cookie: where the law asks for consent (EU, UK), it needs it. Withdrawing consent (leaving `"cookies"`) deletes it.
+
+## Privacy and consent
+
+```tsx
+<CockpitProvider apiKey={key} consent="cookieless" respectDnt>
+```
+
+| `consent` | Stored in the browser | Sent |
+| --- | --- | --- |
+| `"cookieless"` (default) | Nothing: no cookie, no localStorage, no sessionStorage | Events without a visitor id |
+| `"cookies"` | `ck_id` (1 year), `ck_sid` (30 minutes), dismissed surveys, `mrr_ref` (affiliate referral, program days) | Events with `ck_id` as `distinctId` |
+| `"off"` | Nothing | Nothing, and no surveys |
+
+- **Cookieless:** the server counts visitors with a hash of key, date, IP and user agent that changes every day, like Plausible; the IP is never stored. A visitor coming back on another day counts again, so retention needs `identify()` or cookies. After `identify(id)` events carry that id. Experiments, surveys and feedback use your `distinctId` prop, else a random id in memory for the page load: variants hold across client-side navigation, not across reloads, and a dismissed survey can come back after a reload.
+- **Changing it:** `const { consent, setConsent } = useCockpit()`. From `"off"` to another mode, tracking starts and the current page view is sent right away. Leaving `"cookies"` deletes `ck_id`, `ck_sid` and the stored survey dismissals; `"off"` also drops unsent events. If the `consent` prop changes, the SDK follows it.
+- **The SDK does not remember the choice.** Your consent banner stores it and calls `setConsent()` on every page load.
+- **`respectDnt`** (default false): when the browser sends Do Not Track or Global Privacy Control, nothing is sent or stored, whatever the consent.
+- **Sessions** end after 30 minutes without an event: in the `ck_sid` cookie with `"cookies"`, in memory otherwise (a reload starts a new session id).
+- Previews inside MRRocket (`ck_embed=1`) track nothing.
+
+## What it sends
+
+`POST {host}/api/sdk/events`, batched every two seconds and on page hide, at most 100 events and 64 KB per request:
+
+```ts
+{
+    key: string;
+    events: {
+        event: string;
+        distinctId?: string; // ck_id or the identify() id; missing cookieless until identify()
+        sessionId?: string;
+        props?: Record<string, unknown>; // page views carry { path }
+        ts?: number; // ms
+        url?: string; // location.href
+        referrer?: string; // document.referrer on the first page, then the previous in-app URL
+        utm_source?: string; // utm_* from the landing URL, kept for the page load
+        utm_medium?: string;
+        utm_campaign?: string;
+        utm_term?: string;
+        utm_content?: string;
+        screen?: { w: number; h: number };
+    }[];
+}
+```
+
+Answers `202 { ok: true, received, dropped }`; `400` bad body, `404` unknown key, `413` too large, `429` over 600 requests a minute per key. The server adds the country (from `x-vercel-ip-country` or `cf-ipcountry`) and browser, OS and device (from the user agent); the IP only feeds the daily hash. Bot user agents are not stored. `signup`, `checkout` and `purchase` feed Web analytics, `$identify` creates a person in People. Raw events are kept 90 days.
+
+`GET {host}/api/sdk/config?key=…` returns the experiments for the key.

package/dist/api.d.ts

@@ -0,0 +1,113 @@
+export type PostStatus = "review" | "planned" | "progress" | "shipped";
+export declare const STATUS_LABEL: Record<PostStatus, string>;
+export interface FeedbackBoardInfo {
+    id: string;
+    label: string;
+}
+export interface FeedbackPost {
+    id: string;
+    title: string;
+    body: string;
+    board: string;
+    status: PostStatus;
+    votes: number;
+    comments: number;
+    voted: boolean;
+    createdAt: string;
+}
+export interface FeedbackList {
+    boards: FeedbackBoardInfo[];
+    posts: FeedbackPost[];
+}
+export interface FeedbackRoadmap {
+    columns: {
+        planned: FeedbackPost[];
+        progress: FeedbackPost[];
+        shipped: FeedbackPost[];
+    };
+}
+export interface ChangelogEntry {
+    id: string;
+    title: string;
+    body: string;
+    publishedAt: string;
+}
+export interface FeedbackComment {
+    id: string;
+    body: string;
+    author: string;
+    isTeam: boolean;
+    postedAt: string;
+}
+export type SurveyQuestionKind = "nps" | "rating" | "single" | "multi" | "text";
+export interface SurveyQuestion {
+    key: string;
+    kind: SurveyQuestionKind;
+    title: string;
+    description?: string;
+    required: boolean;
+    options?: string[];
+    scale?: number;
+    low?: string;
+    high?: string;
+    placeholder?: string;
+}
+export interface SurveyDefinition {
+    id: string;
+    name: string;
+    type: string;
+    thanks: string;
+    questions: SurveyQuestion[];
+}
+export type SurveyAnswer = number | string | string[];
+export declare class ApiError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+interface Conn {
+    host: string;
+    apiKey: string;
+    distinctId: string;
+    user?: {
+        id: string;
+        [key: string]: unknown;
+    };
+}
+/** The small fetch client behind the widgets. Every read takes an AbortSignal so unmounting cancels it. */
+export declare const createApi: (c: Conn) => {
+    list: (o: {
+        board?: string;
+        sort?: "top" | "new";
+        q?: string;
+    }, signal?: AbortSignal) => Promise<FeedbackList>;
+    roadmap: (signal?: AbortSignal) => Promise<FeedbackRoadmap>;
+    changelog: (signal?: AbortSignal) => Promise<{
+        entries: ChangelogEntry[];
+    }>;
+    submit: (p: {
+        title: string;
+        body?: string;
+        board: string;
+    }) => Promise<FeedbackPost>;
+    vote: (id: string) => Promise<{
+        voted: boolean;
+        votes: number;
+    }>;
+    comments: (id: string, signal?: AbortSignal) => Promise<{
+        comments: FeedbackComment[];
+    }>;
+    comment: (id: string, body: string) => Promise<FeedbackComment>;
+    survey: (url: string, signal?: AbortSignal) => Promise<{
+        survey: SurveyDefinition | null;
+    }>;
+    seen: (id: string) => Promise<unknown>;
+    respond: (id: string, r: {
+        answers: Record<string, SurveyAnswer>;
+        completed: boolean;
+        seconds: number;
+    }) => Promise<unknown>;
+};
+export type Api = ReturnType<typeof createApi>;
+/** The client for the provider's key, host and visitor. */
+export declare const useApi: () => Api;
+export {};

package/dist/api.js

@@ -0,0 +1,71 @@
+// src/api.ts
+import { useMemo } from "react";
+import { useCtx } from "./context.js";
+var STATUS_LABEL = {
+  review: "Under review",
+  planned: "Planned",
+  progress: "In progress",
+  shipped: "Shipped"
+};
+var ApiError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+};
+var qs = (params) => {
+  const p = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) if (v) p.set(k, v);
+  return p.toString();
+};
+var call = async (url, init, signal) => {
+  let res;
+  try {
+    res = await fetch(url, {
+      ...init,
+      signal,
+      headers: init?.body ? { "content-type": "application/json" } : void 0
+    });
+  } catch (e) {
+    if (e.name === "AbortError") throw e;
+    throw new ApiError("Could not reach the server. Check your connection and try again.", 0);
+  }
+  if (!res.ok) {
+    let detail = "";
+    try {
+      detail = (await res.json()).error ?? "";
+    } catch {
+    }
+    throw new ApiError(detail || (res.status === 429 ? "Too many requests. Try again in a minute." : "Something went wrong. Please try again."), res.status);
+  }
+  return await res.json();
+};
+var createApi = (c) => {
+  const base = `${c.host}/api/sdk`;
+  const who = { key: c.apiKey, distinctId: c.distinctId, user: c.user };
+  const post = (path, body, signal) => call(`${base}${path}`, { method: "POST", body: JSON.stringify({ ...who, ...body }) }, signal);
+  return {
+    list: (o, signal) => call(`${base}/feedback?${qs({ key: c.apiKey, distinctId: c.distinctId, board: o.board, sort: o.sort, q: o.q })}`, void 0, signal),
+    roadmap: (signal) => call(`${base}/feedback/roadmap?${qs({ key: c.apiKey })}`, void 0, signal),
+    changelog: (signal) => call(`${base}/feedback/changelog?${qs({ key: c.apiKey })}`, void 0, signal),
+    submit: (p) => post("/feedback", p),
+    vote: (id) => post(`/feedback/${encodeURIComponent(id)}/vote`, {}),
+    comments: (id, signal) => call(`${base}/feedback/${encodeURIComponent(id)}/comments?${qs({ key: c.apiKey })}`, void 0, signal),
+    comment: (id, body) => post(`/feedback/${encodeURIComponent(id)}/comments`, { body }),
+    survey: (url, signal) => call(`${base}/surveys?${qs({ key: c.apiKey, distinctId: c.distinctId, url })}`, void 0, signal),
+    seen: (id) => post(`/surveys/${encodeURIComponent(id)}/seen`, { user: void 0 }),
+    respond: (id, r) => post(`/surveys/${encodeURIComponent(id)}/respond`, r)
+  };
+};
+var useApi = () => {
+  const { apiKey, host, distinctId, user } = useCtx();
+  return useMemo(() => createApi({ apiKey, host, distinctId, user }), [apiKey, host, distinctId, user]);
+};
+export {
+  ApiError,
+  STATUS_LABEL,
+  createApi,
+  useApi
+};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api.ts"],"sourcesContent":["import { useMemo } from \"react\";\nimport { useCtx } from \"./context\";\n\nexport type PostStatus = \"review\" | \"planned\" | \"progress\" | \"shipped\";\n\nexport const STATUS_LABEL: Record<PostStatus, string> = {\n    review: \"Under review\",\n    planned: \"Planned\",\n    progress: \"In progress\",\n    shipped: \"Shipped\",\n};\n\nexport interface FeedbackBoardInfo {\n    id: string;\n    label: string;\n}\n\nexport interface FeedbackPost {\n    id: string;\n    title: string;\n    body: string;\n    board: string;\n    status: PostStatus;\n    votes: number;\n    comments: number;\n    voted: boolean;\n    createdAt: string;\n}\n\nexport interface FeedbackList {\n    boards: FeedbackBoardInfo[];\n    posts: FeedbackPost[];\n}\n\nexport interface FeedbackRoadmap {\n    columns: { planned: FeedbackPost[]; progress: FeedbackPost[]; shipped: FeedbackPost[] };\n}\n\nexport interface ChangelogEntry {\n    id: string;\n    title: string;\n    body: string;\n    publishedAt: string;\n}\n\nexport interface FeedbackComment {\n    id: string;\n    body: string;\n    author: string;\n    isTeam: boolean;\n    postedAt: string;\n}\n\nexport type SurveyQuestionKind = \"nps\" | \"rating\" | \"single\" | \"multi\" | \"text\";\n\nexport interface SurveyQuestion {\n    key: string;\n    kind: SurveyQuestionKind;\n    title: string;\n    description?: string;\n    required: boolean;\n    options?: string[];\n    scale?: number;\n    low?: string;\n    high?: string;\n    placeholder?: string;\n}\n\nexport interface SurveyDefinition {\n    id: string;\n    name: string;\n    type: string;\n    thanks: string;\n    questions: SurveyQuestion[];\n}\n\nexport type SurveyAnswer = number | string | string[];\n\nexport class ApiError extends Error {\n    status: number;\n    constructor(message: string, status: number) {\n        super(message);\n        this.status = status;\n    }\n}\n\ninterface Conn {\n    host: string;\n    apiKey: string;\n    distinctId: string;\n    user?: { id: string; [key: string]: unknown };\n}\n\nconst qs = (params: Record<string, string | undefined>) => {\n    const p = new URLSearchParams();\n    for (const [k, v] of Object.entries(params)) if (v) p.set(k, v);\n    return p.toString();\n};\n\nconst call = async <T>(url: string, init: RequestInit | undefined, signal?: AbortSignal): Promise<T> => {\n    let res: Response;\n    try {\n        res = await fetch(url, {\n            ...init,\n            signal,\n            headers: init?.body ? { \"content-type\": \"application/json\" } : undefined,\n        });\n    } catch (e) {\n        if ((e as Error).name === \"AbortError\") throw e;\n        throw new ApiError(\"Could not reach the server. Check your connection and try again.\", 0);\n    }\n    if (!res.ok) {\n        let detail = \"\";\n        try {\n            detail = ((await res.json()) as { error?: string }).error ?? \"\";\n        } catch {\n            // Not JSON; the status is enough.\n        }\n        throw new ApiError(detail || (res.status === 429 ? \"Too many requests. Try again in a minute.\" : \"Something went wrong. Please try again.\"), res.status);\n    }\n    return (await res.json()) as T;\n};\n\n/** The small fetch client behind the widgets. Every read takes an AbortSignal so unmounting cancels it. */\nexport const createApi = (c: Conn) => {\n    const base = `${c.host}/api/sdk`;\n    const who = { key: c.apiKey, distinctId: c.distinctId, user: c.user };\n    const post = <T>(path: string, body: Record<string, unknown>, signal?: AbortSignal) =>\n        call<T>(`${base}${path}`, { method: \"POST\", body: JSON.stringify({ ...who, ...body }) }, signal);\n    return {\n        list: (o: { board?: string; sort?: \"top\" | \"new\"; q?: string }, signal?: AbortSignal) =>\n            call<FeedbackList>(`${base}/feedback?${qs({ key: c.apiKey, distinctId: c.distinctId, board: o.board, sort: o.sort, q: o.q })}`, undefined, signal),\n        roadmap: (signal?: AbortSignal) => call<FeedbackRoadmap>(`${base}/feedback/roadmap?${qs({ key: c.apiKey })}`, undefined, signal),\n        changelog: (signal?: AbortSignal) => call<{ entries: ChangelogEntry[] }>(`${base}/feedback/changelog?${qs({ key: c.apiKey })}`, undefined, signal),\n        submit: (p: { title: string; body?: string; board: string }) => post<FeedbackPost>(\"/feedback\", p),\n        vote: (id: string) => post<{ voted: boolean; votes: number }>(`/feedback/${encodeURIComponent(id)}/vote`, {}),\n        comments: (id: string, signal?: AbortSignal) =>\n            call<{ comments: FeedbackComment[] }>(`${base}/feedback/${encodeURIComponent(id)}/comments?${qs({ key: c.apiKey })}`, undefined, signal),\n        comment: (id: string, body: string) => post<FeedbackComment>(`/feedback/${encodeURIComponent(id)}/comments`, { body }),\n        survey: (url: string, signal?: AbortSignal) =>\n            call<{ survey: SurveyDefinition | null }>(`${base}/surveys?${qs({ key: c.apiKey, distinctId: c.distinctId, url })}`, undefined, signal),\n        seen: (id: string) => post<unknown>(`/surveys/${encodeURIComponent(id)}/seen`, { user: undefined }),\n        respond: (id: string, r: { answers: Record<string, SurveyAnswer>; completed: boolean; seconds: number }) =>\n            post<unknown>(`/surveys/${encodeURIComponent(id)}/respond`, r),\n    };\n};\n\nexport type Api = ReturnType<typeof createApi>;\n\n/** The client for the provider's key, host and visitor. */\nexport const useApi = (): Api => {\n    const { apiKey, host, distinctId, user } = useCtx();\n    return useMemo(() => createApi({ apiKey, host, distinctId, user }), [apiKey, host, distinctId, user]);\n};\n"],"mappings":"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","names":[]}

package/dist/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Everything of the SDK that needs the browser or React state. It is its own file with the "use client" directive so
+ * that the build keeps one client chunk: server components import these as client references, while the plain
+ * helpers (`core`, `server`, `proxy`) stay free of the directive.
+ */
+export { CockpitProvider, Experiment, Text, useCockpit, useVariant, type CockpitProviderProps } from "./client.js";
+export { FeedbackBoard, FeedbackWidget, useFeedback, type FeedbackBoardProps, type FeedbackWidgetProps } from "./feedback.js";
+export { Survey } from "./survey.js";
+export type { CockpitUser } from "./context.js";
+export { type ChangelogEntry, type FeedbackBoardInfo, type FeedbackComment, type FeedbackList, type FeedbackPost, type FeedbackRoadmap, type PostStatus, type SurveyAnswer, type SurveyDefinition, type SurveyQuestion, type SurveyQuestionKind, createApi, } from "./api.js";
+export { CSS as WIDGET_CSS, useStyles } from "./styles.js";

package/dist/browser.js

@@ -0,0 +1,25 @@
+"use client";
+
+// src/browser.ts
+import { CockpitProvider, Experiment, Text, useCockpit, useVariant } from "./client.js";
+import { FeedbackBoard, FeedbackWidget, useFeedback } from "./feedback.js";
+import { Survey } from "./survey.js";
+import {
+  createApi
+} from "./api.js";
+import { CSS, useStyles } from "./styles.js";
+export {
+  CockpitProvider,
+  Experiment,
+  FeedbackBoard,
+  FeedbackWidget,
+  Survey,
+  Text,
+  CSS as WIDGET_CSS,
+  createApi,
+  useCockpit,
+  useFeedback,
+  useStyles,
+  useVariant
+};
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["\"use client\";\n\n/**\n * Everything of the SDK that needs the browser or React state. It is its own file with the \"use client\" directive so\n * that the build keeps one client chunk: server components import these as client references, while the plain\n * helpers (`core`, `server`, `proxy`) stay free of the directive.\n */\nexport { CockpitProvider, Experiment, Text, useCockpit, useVariant, type CockpitProviderProps } from \"./client\";\nexport { FeedbackBoard, FeedbackWidget, useFeedback, type FeedbackBoardProps, type FeedbackWidgetProps } from \"./feedback\";\nexport { Survey } from \"./survey\";\nexport type { CockpitUser } from \"./context\";\nexport {\n    type ChangelogEntry,\n    type FeedbackBoardInfo,\n    type FeedbackComment,\n    type FeedbackList,\n    type FeedbackPost,\n    type FeedbackRoadmap,\n    type PostStatus,\n    type SurveyAnswer,\n    type SurveyDefinition,\n    type SurveyQuestion,\n    type SurveyQuestionKind,\n    createApi,\n} from \"./api\";\nexport { CSS as WIDGET_CSS, useStyles } from \"./styles\";\n"],"mappings":";;;AAOA,SAAS,iBAAiB,YAAY,MAAM,YAAY,kBAA6C;AACrG,SAAS,eAAe,gBAAgB,mBAAsE;AAC9G,SAAS,cAAc;AAEvB;AAAA,EAYI;AAAA,OACG;AACP,SAAgB,KAAY,iBAAiB;","names":[]}

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+import { type ReactNode } from "react";
+import { type AttributionMode } from "./referral.js";
+import { type CockpitConfig, type ConsentMode, type VariantId } from "./core.js";
+export interface CockpitProviderProps {
+    /** The product's public key from Cockpit › Settings › SDK. Safe in the browser. Default: `NEXT_PUBLIC_MRROCKET_KEY`. */
+    apiKey?: string;
+    /** Where MRRocket runs, like `https://app.example.com`. Default: `NEXT_PUBLIC_MRROCKET_HOST`, else the page's own origin. */
+    host?: string;
+    preview?: Record<string, VariantId>;
+    embedded?: boolean;
+    /** Config fetched on the server, to render the right variant on the first paint. */
+    config?: CockpitConfig;
+    /** Your own id for this visitor, for example a signed-in user id. Keeps variants stable without cookies. */
+    distinctId?: string;
+    /**
+     * "cookieless" (default) stores nothing in the browser, "cookies" keeps a visitor cookie for a year, "off" sends
+     * nothing. The SDK does not remember the choice: set it on every page load, from the prop or setConsent().
+     */
+    consent?: ConsentMode;
+    /** Send nothing when the browser asks not to be tracked (Do Not Track or Global Privacy Control). */
+    respectDnt?: boolean;
+    /** Ask visitors the surveys you run in Cockpit. Set false to switch them off. */
+    surveys?: boolean;
+    /**
+     * Affiliate referrals (`?ref=` links and MRRocket's tracked links). "consent" (default): stored in the first-party
+     * `mrr_ref` cookie only while consent is "cookies", in memory otherwise. "always": stored whatever the consent (only
+     * where your legal basis allows it). "off": referrals are ignored.
+     */
+    attribution?: AttributionMode;
+    /** The query parameter of direct partner links, default `ref` (`https://your.site/?ref=maya`). */
+    referralParam?: string;
+    children: ReactNode;
+}
+/**
+ * Put it once around your app, in `app/layout.tsx`. It loads your experiments, keeps each visitor in one variant,
+ * records page views and sends your events to Cockpit in small batches.
+ *
+ * `preview` forces variants for this render, for example from the `ck_preview` search param on the server,
+ * so a Cockpit preview never flickers. Without it the provider reads the param itself after the first render.
+ */
+export declare const CockpitProvider: ({ apiKey: apiKeyProp, host: hostProp, preview: forced, embedded: embeddedProp, config: bootstrapConfig, distinctId: bootstrapId, consent: consentProp, respectDnt, surveys, attribution, referralParam, children, }: CockpitProviderProps) => import("react").JSX.Element;
+/** `track`, `identify`, the consent mode and its setter, the visitor id and whether the experiments have loaded. */
+export declare const useCockpit: () => {
+    track: (event: string, props?: Record<string, unknown>) => void;
+    identify: (id: string, props?: Record<string, unknown>) => void;
+    distinctId: string;
+    ready: boolean;
+    embedded: boolean;
+    consent: ConsentMode;
+    setConsent: (mode: ConsentMode) => void;
+};
+/** The variant this visitor sees, for example `"control"` or `"a"`. Records the exposure. */
+export declare const useVariant: (key: string) => VariantId;
+/** Renders the element for the visitor's variant; control when the variant has no element. */
+export declare const Experiment: ({ name, variants }: {
+    name: string;
+    variants: Record<VariantId, ReactNode> & {
+        control: ReactNode;
+    };
+}) => import("react").JSX.Element;
+/**
+ * A text that experiments may change without a deploy: Cockpit sends the new copy for `id` and this renders it.
+ * Write your default as the children.
+ */
+export declare const Text: ({ id, children }: {
+    id: string;
+    children: string;
+}) => import("react").JSX.Element;