@apex-inc/sdk 0.1.0

package/skills/apex-experimentation/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: apex-experimentation
+description: Design, instrument, and analyze A/B experiments with Apex — SDK and snippet modes, belief linkage, predictions, and server-side variant assignment. Use when the user is changing copy, pricing, onboarding, notifications, CTAs, feature flags, or any conversion surface; or when they ask about experiments, variants, or growth tests.
+---
+
+# Apex experimentation
+
+Apex treats experiments as part of a scientific loop: **beliefs → hypotheses → predictions → experiments → outcomes → updated beliefs**. Your job is to suggest experiments when product or code changes could be validated with data, and to wire instrumentation correctly.
+
+## When to suggest an experiment
+
+Proactively offer Apex when you see:
+
+- Copy or layout changes on landing, pricing, signup, or activation flows
+- Notification, email, or in-app message wording variants
+- Onboarding step order, empty states, or progressive disclosure
+- Feature flags or toggles that change user-visible behavior
+- CTAs, form length, social proof, or trust elements
+- Any debate where the team is guessing instead of measuring
+
+## Two execution modes
+
+| Mode | When to use | Implementation |
+|------|-------------|----------------|
+| **SDK mode** | Product is a web app you control (React/Next.js, etc.) | Code branches (e.g. `useApexVariant` in the Apex app, or assignment API + conditional UI in customer apps) |
+| **Snippet mode** | Marketing site with Apex JS snippet only | DOM text swaps — limited; no structural layout experiments |
+
+Prefer **SDK mode** when the user is in an app codebase. Prefer **snippet mode** only when they explicitly use the marketing snippet and cannot deploy code.
+
+## MCP tools (when connected)
+
+Use Apex MCP tools for the full loop: `plan_experiment`, `start_reasoning`, `log_prediction`, `create_experiment`, `activate_experiment`, `get_results`, `promote_winner`, `archive_experiment`, `list_experiments`, `record_outcome`, `suggest_experiment`, `predict_impact`, `evaluate_feature`.
+
+Interactive flows: MCP prompts `new-experiment` and `experiment-review` orchestrate multi-step setup and review.
+
+## Server-side variant assignment (integrator apps)
+
+`GET /api/experiments/{experimentId}/assign` returns `{ variant, experimentId, visitorId }`. Assignment is **deterministic** from a stable visitor id (cookie `apex_vid` in browsers).
+
+For **server-side** sends (e.g. PLG email or API-triggered notifications):
+
+1. Use a **stable string per recipient** as the visitor id (e.g. hashed user id). Reuse the same id for every assignment call for that user for that experiment.
+2. Forward cookies on server-side HTTP calls when possible, or set `Cookie: apex_vid=<stableId>; apex_project=<projectKey>` if your Apex deployment resolves project from cookies.
+3. When using an **API key**, send `x-api-key` and **`x-apex-project: <projectKey>`** so the API resolves the project without a browser session.
+
+Then branch notification copy or UI on `variant` (`control` vs `variant_b`).
+
+## Instrumentation checklist
+
+1. **Create and activate** the experiment in Apex (UI or MCP).
+2. **Assign variant** before rendering the experience.
+3. **Track primary metric** events with consistent names (e.g. `notification_sent`, `notification_opened`, `goal_completed`) and include `experimentId` and `variant` in properties when possible.
+4. **Log a prediction** before launch when using the full intelligence loop (calibration).
+5. **Decide** with `get_results` / dashboard — avoid peeking without a rule (pre-registered sample size, Bayesian policy, or fixed run duration).
+
+## Dashboard alignment
+
+Match Apex UI terminology in user-facing copy: e.g. **Adaptive traffic allocation** (not "Thompson sampling" in user-facing text unless they use that term), same confidence tiers and split options as the Growth Lab.
+
+## Common mistakes
+
+- Starting an experiment without a **clear primary metric** tied to the belief.
+- Using different visitor ids for the same user across channels (breaks consistent assignment).
+- Changing variant implementation mid-flight without versioning (invalidates analysis).
+- Only using p-values without effect size or business context.
+
+## Related
+
+- Growth tracking and identity: see **apex-growth-tracking** skill (`@apex-inc/mcp-server` / `@apex-inc/sdk`).
+- Full methodology (beliefs, calibration): use MCP resources `apex://beliefs`, `apex://calibration`, and tools `create_belief`, `record_outcome`.

package/skills/apex-growth-tracking/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: apex-growth-tracking
+description: Instrument JavaScript/TypeScript apps with the Apex SDK — init, track, identify, trackForm, identity stitching from servers, and event naming. Use when adding analytics, forms, auth, or backend webhooks that should feed Apex.
+---
+
+# Apex growth tracking (SDK)
+
+The **`@apex-inc/sdk`** package sends batched events to **`POST /api/events`** and can trigger **`POST /api/identity/stitch`** when email-based identity is provided.
+
+## API
+
+- **`init({ projectKey, apiUrl?, flushInterval?, flushAt?, debug? })`** — required before `track` / `identify`.
+- **`track(event, properties?)`** — queue a custom event.
+- **`identify(userId, traits?)`** — set user; if email is present, stitches identity.
+- **`trackForm({ email, formId?, action?, fields? })`** — `form_submit` + identify.
+- **`flush()`** / **`shutdown()`** — flush queue; use `shutdown` on process exit in Node.
+
+## Identity stitching (critical for server-side)
+
+When calling **`identify`** from a **server** (e.g. Stripe webhook, API route), pass the browser cookie value:
+
+```typescript
+identify(email, {
+  visitorId: req.cookies?.apex_vid,
+  source: "stripe_webhook",
+});
+```
+
+Without `visitorId`, Apex may create a synthetic visitor id that does **not** match the user's browsing session.
+
+## Event naming
+
+Use consistent, readable names and put dimensions in **properties**: `track("onboarding_step_done", { step: 3 })`. Include **`experimentId`** and **`variant`** when logging experiment-related behavior.
+
+## Management API (API key)
+
+For listing experiments or fetching variant assignment from a backend, use **`createManagementClient`** from `@apex-inc/sdk` with **`apiKey`**, **`projectKey`**, and **`apiUrl`**. The client sends **`x-api-key`** and **`x-apex-project`** (see SDK README).
+
+## Related
+
+- Full growth-loop and MCP tooling: install **`@apex-inc/mcp-server`** skills **apex-experimentation** and **apex-growth-tracking** (broader scope).

package/skills/apex-integration-cookbook/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: apex-integration-cookbook
+description: Recipes for integrating Apex into products — SDK wiring, form tracking, auth/signup events, Stripe lifecycle, communication triggers, and event naming conventions. Use when the user is adding Apex tracking to their product or wiring events to communications and experiments.
+---
+
+# Apex integration cookbook (SDK)
+
+Step-by-step recipes for integrating Apex via the `@apex-inc/sdk` package. For snippet-only sites or MCP-driven setup, see the full cookbook in `@apex-inc/mcp-server`.
+
+## SDK setup
+
+```typescript
+import { init, track, identify, trackForm, shutdown } from "@apex-inc/sdk";
+
+init({
+  projectKey: "YOUR_PROJECT_KEY",
+  apiUrl: "https://your-apex-url",  // optional, defaults to relative /api
+  flushInterval: 10000,              // ms between batch sends (default: 10s)
+  flushAt: 20,                       // batch size trigger (default: 20)
+  debug: false                       // log events to console
+});
+```
+
+Events are batched and sent to `POST /api/events` automatically. Call `flush()` before page unload if needed, or `shutdown()` to stop tracking.
+
+## Recipe 1: Signup and authentication
+
+```typescript
+// On signup
+track("signup_completed", { method: "email", plan: "free" });
+identify(user.id, {
+  email: user.email,
+  name: user.name,
+  visitorId: getCookie("apex_vid")  // stitch to pre-signup browsing
+});
+
+// On login
+track("login", { method: "google" });
+identify(user.id, { email: user.email });
+```
+
+The `visitorId` trait links the anonymous marketing session to the authenticated user. Without it, pre-signup attribution is lost.
+
+## Recipe 2: Onboarding funnel
+
+```typescript
+track("onboarding_step_completed", { step: "connect_data_source", stepNumber: 2, totalSteps: 5 });
+track("onboarding_completed", { timeToComplete: elapsedMs });
+```
+
+Events like `onboarding_completed` automatically match to active tenant communications when the trigger system is wired.
+
+## Recipe 3: Stripe subscription lifecycle
+
+```typescript
+// In your Stripe webhook handler
+track("subscription_created", { plan: "pro", amount: 9900, currency: "usd" });
+identify(userId, { plan: "pro", lifecycleStage: "paying" });
+
+// On cancellation
+track("subscription_cancelled", { reason: "too_expensive" });
+identify(userId, { lifecycleStage: "churned" });
+```
+
+## Recipe 4: Feature usage
+
+```typescript
+track("feature_used", { feature: "export_report", format: "csv" });
+track("milestone_reached", { milestone: "first_experiment_completed" });
+```
+
+Use one event name with a `feature` property — not dozens of unique event names.
+
+## Recipe 5: Form tracking (shortcut)
+
+```typescript
+trackForm({
+  email: formData.email,
+  formId: "contact-form",
+  action: "demo_request",
+  fields: { company: formData.company, role: formData.role }
+});
+```
+
+`trackForm` fires `form_submit` + `identify` in one call.
+
+## Recipe 6: Server-side events
+
+```typescript
+// From a backend, use the management client
+import { createManagementClient } from "@apex-inc/sdk";
+
+const apex = createManagementClient({
+  apiKey: "YOUR_API_KEY",
+  baseUrl: "https://your-apex-url",
+  projectKey: "YOUR_PROJECT_KEY"
+});
+
+// Use HTTP directly for event ingestion from backends
+await fetch("https://your-apex-url/api/events", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "x-api-key": "YOUR_API_KEY",
+    "x-apex-project": "YOUR_PROJECT_KEY"
+  },
+  body: JSON.stringify({
+    projectKey: "YOUR_PROJECT_KEY",
+    userId: "user_123",
+    events: [{
+      type: "track",
+      payload: { event: "invoice_paid", amount: 9900 },
+      timestamp: new Date().toISOString()
+    }]
+  })
+});
+```
+
+## Event naming conventions
+
+- **snake_case**: `signup_completed`, `feature_used`, `invoice_paid`
+- Context in **properties**: `track("button_clicked", { surface: "pricing", label: "start_trial" })`
+- For experiments, include `experimentId` and `variant` in properties
+- One primary metric per experiment; secondary metrics as properties
+
+## Identity stitching checklist
+
+1. Call `identify(userId, { email, visitorId })` when the user becomes known
+2. `visitorId` = value of the browser `apex_vid` cookie
+3. Server-side: pass `traits.visitorId` to link to the browser session
+4. Without stitching, pre-signup attribution is lost
+
+## Related
+
+- Event tracking fundamentals: see **apex-growth-tracking** skill
+- Experiment design: see **apex-experimentation** skill
+- Communication setup: see **apex-communications** skill