@growth-loop/sdk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 growth-loop.dev
+
+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

@@ -0,0 +1,202 @@
+# @growth-loop/sdk
+
+Browser / Node / edge SDK for [growth-loop.dev](https://growth-loop.dev) —
+Claude Code-native product analytics for vibe-coded SaaS.
+
+Pairs with [`@growth-loop/mcp-server`](../mcp-server) so Claude Code can ask
+your funnels, retention, and revenue questions directly with citations.
+
+## Install
+
+```sh
+pnpm add @growth-loop/sdk
+# or
+npm i @growth-loop/sdk
+# or
+yarn add @growth-loop/sdk
+```
+
+## Quick start — Browser (Next.js, Vite, anything web)
+
+```ts
+// src/lib/growth.ts
+'use client';
+import { instrument } from '@growth-loop/sdk';
+import { createBrowserClient } from '@growth-loop/sdk/browser';
+
+export const growth = instrument(
+  createBrowserClient({
+    apiKey: process.env.NEXT_PUBLIC_GROWTH_KEY!,
+    host: process.env.NEXT_PUBLIC_GROWTH_HOST ?? 'https://api.growth-loop.dev',
+  }),
+);
+```
+
+```tsx
+// any client component
+import { growth } from '@/lib/growth';
+
+<button onClick={growth.button('cta_clicked', onClick, { location: 'hero' })}>
+  Sign up
+</button>
+```
+
+`createBrowserClient` enables `autoCapture` by default — page views, clicks,
+rage-clicks, JS errors, and navigation timing all flow without ceremony.
+Disable with `autoCapture: false` if you prefer manual control.
+
+## Quick start — Node / server actions / route handlers
+
+```ts
+// src/lib/growth.server.ts
+import { instrument } from '@growth-loop/sdk';
+import { createServerClient } from '@growth-loop/sdk/node';
+
+export const growth = instrument(
+  createServerClient({
+    apiKey: process.env.GROWTH_KEY!,
+    host: process.env.GROWTH_HOST ?? 'https://api.growth-loop.dev',
+    environment: (process.env.NODE_ENV ?? 'development') as
+      | 'production' | 'preview' | 'development',
+    release: process.env.GIT_COMMIT_SHA,
+  }),
+);
+```
+
+```ts
+// in a route handler / server action
+await growth.identify({ distinctId: user.id, properties: { plan: user.plan } });
+growth.step('signup_completed', { source: 'organic' });
+await growth.flush();   // important on serverless — request can finish before queue drains
+```
+
+## Quick start — Edge / Cloudflare Workers / Deno
+
+The default transport uses `fetch`, which works in any modern runtime. For
+queue-backed delivery (e.g. Cloudflare Queues), pass a custom transport:
+
+```ts
+import { createClient } from '@growth-loop/sdk';
+
+const growth = createClient({
+  apiKey: env.GROWTH_KEY,
+  transport: {
+    async send(url, payload, headers) {
+      await env.GROWTH_QUEUE.send({ url, payload, headers });
+    },
+  },
+});
+```
+
+## Core API
+
+### `Growth` / `createClient(options)`
+
+The low-level client. Use `createClient` for a factory or `new Growth(options)`
+directly.
+
+```ts
+interface GrowthOptions {
+  apiKey: string;
+  host?: string;            // default: 'https://api.growth-loop.dev'
+  flushInterval?: number;   // default: 5000ms
+  batchSize?: number;       // default: 50
+  environment?: string;
+  release?: string;         // git commit SHA — annotates events for `/diagnose`
+  transport?: Transport;
+  autoCapture?: boolean;    // browser only; default: true
+}
+```
+
+Methods:
+
+| Method | What it does |
+|---|---|
+| `track(name, properties?, options?)` | Enqueue one event. Non-blocking. |
+| `identify({ distinctId, properties? })` | Set the current distinct ID + emit `$identify`. Subsequent events inherit the ID. |
+| `flush()` | Force-send any queued events. Returns a Promise. **Always await on serverless.** |
+| `shutdown()` | Flush + stop the worker. Called automatically on `beforeunload` / `process.exit`. |
+| `setDistinctId(id)` | Set the ID without emitting `$identify`. |
+
+### Helpers — `instrument(client)`
+
+Wraps a `GrowthClient` and adds three high-leverage helpers used by
+`/init` (the MCP slash-prompt that auto-instruments your repo):
+
+#### `growth.span(name, fn, options?)`
+
+Wraps an async function. Emits `<name>.started`, `<name>.completed` (with
+`duration_ms`), or `<name>.failed` (with `error_message`, `error_name`). Use
+on anything > 500ms or with non-trivial failure rate.
+
+```ts
+const checkout = growth.span('checkout', async (items: Item[]) => {
+  return await stripe.charge(items);
+});
+```
+
+#### `growth.step(name, properties?)`
+
+Single funnel-step event. Use for activation milestones.
+
+```ts
+growth.step('onboarding.connected_repo', { provider: 'github' });
+```
+
+#### `growth.button(name, onClick, properties?)`
+
+Returns a wrapped click handler — emits the event, then runs the original.
+Built for React onClick props.
+
+```tsx
+<button onClick={growth.button('cta_clicked', signUp, { location: 'hero' })}>
+  Sign up
+</button>
+```
+
+## Recommended event taxonomy
+
+The MCP server's `/diagnose` and `/weekly` prompts know these names natively.
+Use them when they fit.
+
+| Stage | Events |
+|---|---|
+| Identity | `signup_completed`, `login_completed`, `$identify` |
+| Activation | `onboarding.started`, `onboarding.completed`, `first_<thing>_created` |
+| Revenue | `checkout_started`, `checkout_completed`, `subscription_created`, `subscription_canceled`, `payment_failed` |
+| Engagement | wrap key clicks with `growth.button(...)` — limit to 5–10 |
+| Performance | `growth.span('checkout', ...)`, `growth.span('ai.generate', ...)` |
+
+## Privacy
+
+- **Never put PII in `properties`** (email, raw IP, full address, payment
+  details). Use `distinctId` for identity. The dashboard explicitly does not
+  decrypt or display anything in `properties` as identity.
+- ClickHouse TTL is 12 months by default — events older than that are
+  dropped automatically.
+- Browser SDK respects DNT (Do Not Track) and skips ingestion when set.
+
+## Environment variables read by the SDK
+
+| Var | Where | Default |
+|---|---|---|
+| `GROWTH_KEY` / `NEXT_PUBLIC_GROWTH_KEY` | Node / Browser | required |
+| `GROWTH_HOST` / `NEXT_PUBLIC_GROWTH_HOST` | both | `https://api.growth-loop.dev` |
+| `GIT_COMMIT_SHA` | Node | unset (passed via `release`) |
+
+## Going deeper
+
+The SDK is the ingest layer. The agent layer (Claude Code + MCP) is what
+makes growth-loop different — install the MCP server too:
+
+```sh
+claude mcp add growth-loop -- npx -y @growth-loop/mcp-server \
+  -e GROWTH_API_KEY=pk_live_<your-key>
+```
+
+Then in Claude Code: `/init` (auto-instrument), `/diagnose <metric>`,
+`/weekly`, `/pmf`, `/icp`, `/strategy`, `/pivot`.
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,13 @@
+import { b as GrowthOptions, G as GrowthClient } from './client-CC-8sBba.js';
+import '@growth/shared';
+
+interface BrowserOptions extends GrowthOptions {
+    autoCapture?: boolean;
+    capturePageViews?: boolean;
+    captureClicks?: boolean;
+    captureRageClicks?: boolean;
+    capturePerformance?: boolean;
+}
+declare function createBrowserClient(options: BrowserOptions): GrowthClient;
+
+export { type BrowserOptions, GrowthClient, createBrowserClient };