@apex-inc/sdk 0.1.0 → 0.5.0

package/dist/plg-events.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * MWO-009 — Apex PLG Event Catalog.
+ *
+ * Curated, typed event schemas for the eight most common PLG
+ * lifecycle moments. Customers import these interfaces directly so
+ * their `apex.track()` calls type-check end-to-end, and the Apex
+ * dashboard uses them to derive activation / expansion / retention
+ * rollups without bespoke queries per customer.
+ *
+ *   import { EVENTS, type ActivatedEvent } from "@apex-inc/sdk/plg-events";
+ *   apex.track(EVENTS.ACTIVATED, { daysToActivation: 2 } satisfies ActivatedEvent);
+ *
+ * Adding a new event:
+ *   1. Add its name to `EVENTS`.
+ *   2. Add its typed interface below.
+ *   3. Update the doc page at /docs/plg-event-catalog (Phase 10).
+ *
+ * Every event is optional. There's no requirement that a customer
+ * emit any of these — the catalog is a convention, not a gate.
+ * Archived event definitions (Phase 8 follow-up) will stop deriving
+ * new rollups but preserve their historical data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_PLG_EVENTS = exports.EVENTS = void 0;
+exports.trackPlgEvent = trackPlgEvent;
+exports.EVENTS = {
+    SIGNUP: "signup",
+    ACTIVATED: "activated",
+    FEATURE_FIRST_USE: "feature_first_use",
+    AHA_MOMENT: "aha_moment",
+    EXPANSION: "expansion",
+    CONTRACTION: "contraction",
+    REACTIVATION: "reactivation",
+    CHURN: "churn",
+};
+/**
+ * Typed `apex.track` wrapper specific to PLG events. Not a hard gate —
+ * `apex.track()` still accepts any event name — but gives customers
+ * compile-time safety on the curated set.
+ */
+function trackPlgEvent(_apex, name, payload) {
+    _apex.track(name, payload);
+}
+/**
+ * Read-only exhaustive list of the catalog. Handy for UI surfaces
+ * that need to render "all PLG events we know about."
+ */
+exports.ALL_PLG_EVENTS = Object.values(exports.EVENTS);
+//# sourceMappingURL=plg-events.js.map

package/dist/plg-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plg-events.js","sourceRoot":"","sources":["../src/plg-events.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAuHH,sCAQC;AA7HY,QAAA,MAAM,GAAG;IACpB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,iBAAiB,EAAE,mBAAmB;IACtC,UAAU,EAAE,YAAY;IACxB,SAAS,EAAE,WAAW;IACtB,WAAW,EAAE,aAAa;IAC1B,YAAY,EAAE,cAAc;IAC5B,KAAK,EAAE,OAAO;CACN,CAAC;AAuGX;;;;GAIG;AACH,SAAgB,aAAa,CAC3B,KAEC,EACD,IAAO,EACP,OAA2B;IAE3B,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,OAA6C,CAAC,CAAC;AACnE,CAAC;AAqBD;;;GAGG;AACU,QAAA,cAAc,GAA4B,MAAM,CAAC,MAAM,CAAC,cAAM,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apex-inc/sdk",
-  "version": "0.1.0",
-  "description": "Apex Growth Intelligence SDK — track events, identify users, and run experiments from any JavaScript runtime.",
+  "version": "0.5.0",
+  "description": "Event tracking and identity SDK for Apex — currently in private beta.",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,11 @@
       "import": "./dist/esm/index.js",
       "require": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./plg-events": {
+      "import": "./dist/esm/plg-events.js",
+      "require": "./dist/plg-events.js",
+      "types": "./dist/plg-events.d.ts"
     }
   },
   "files": ["dist", "skills"],
@@ -17,12 +22,8 @@
     "build": "tsc && tsc -p tsconfig.esm.json",
     "dev": "tsc --watch"
   },
-  "keywords": ["apex", "growth", "analytics", "experiments", "ab-testing", "sdk"],
+  "keywords": ["apex", "sdk"],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/apex-inc/sdk"
-  },
   "publishConfig": {
     "access": "public"
   },

package/skills/apex-communications/SKILL.md

@@ -133,3 +133,219 @@ After setting up communications, verify these events are tracked:
 3. `feature_used` — fires on first or repeated feature interaction
 4. `purchase_complete` — fires on conversion
 5. Check `getEventIntegrationStatus()` to see which events Apex has received
+
+## Auth Emails (Verification Codes, MFA, Sign-In Codes)
+
+Apex supports verification / MFA / OTP / password-reset emails as a first-class
+template pattern. The `code` block lives in the composer's content palette and
+renders a styled monospace code with an editable caption beneath it. Drop the
+block where you want the code to appear, put `{{code}}` (or any variable name)
+inside, and pass the value at send time.
+
+### Author the template (composer)
+
+1. Open the composer for a transactional comm.
+2. Drop a **Code** block into the canvas where you want the code to land
+   (between the intro paragraph and the brand-footer reads well).
+3. Default content: `{{code}}` as the value, "Verification Code" as the caption.
+   Edit the caption for the use case ("Sign-in Code", "Reset Code", etc.).
+4. Save. The comm is now wired for substitution.
+
+### Send the comm (any auth provider, any backend)
+
+```typescript
+// Cognito CustomMessage Lambda example
+import { ApexClient } from "@apex-inc/sdk";
+
+const apex = new ApexClient({
+  apiKey: process.env.APEX_TRANSACTIONAL_API_KEY, // apex_tx_...
+});
+
+export const handler = async (event) => {
+  await apex.transactional.send({
+    to: event.request.userAttributes.email,
+    commId: "verification-code",
+    variables: {
+      code: event.request.codeParameter, // Cognito mints this
+    },
+  });
+  // Suppress the default Cognito email by leaving response.emailMessage empty.
+};
+```
+
+The same pattern covers any provider — Auth0 Actions, WorkOS hooks, NextAuth
+callbacks, hand-rolled flows:
+
+```typescript
+// Auth0 Action: pre-MFA-challenge
+exports.onExecutePreMfaChallenge = async (event, api) => {
+  const code = generateOtp(); // your generator
+  await apex.transactional.send({
+    to: event.user.email,
+    commId: "mfa-code",
+    variables: { code, expires_in: "5 minutes" },
+  });
+  api.idToken.setCustomClaim("apex_mfa_code", code);
+};
+```
+
+### Why a block, not a special field
+
+The Code block participates in the same variable-substitution layer every other
+text-bearing block uses (`{{variable}}` in `content.text`). That means:
+
+- Operators position the code precisely inside the message card from the editor.
+- Customers building OTP / MFA / sign-in emails get parity with the templates
+  Apex ships internally — no special endpoint, no out-of-band injection.
+- Multiple codes per email work out of the box (drop two Code blocks, use
+  `{{code}}` + `{{recovery_code}}`).
+- Preview, A/B experiments, journey send, transactional send — all paths share
+  the same render contract.
+
+### Anti-patterns
+
+- Don't put the code in a generic Text block — it'll render with default body
+  copy styling instead of the monospace + brand-color treatment Code provides.
+- Don't bake the code into the comm at template-author time. The value comes
+  from the auth provider at send time via `variables.code`.
+- Don't pass the code in `slots` instead of `variables` — slots are for legacy
+  slot-format comms; the substitution layer reads `variables` for builder-format
+  comms (which is everything authored in the current composer).
+
+---
+
+## Wiring preferences for your users — the 20-minute integration
+
+End-users want one place to manage how your product talks to them. Apex
+ships `<ApexPreferenceCenter>` so you can drop that surface into your settings
+page without building it yourself. Channels supported in v0.1:
+
+- **Email** — what they get in their inbox
+- **Inbox** — the in-app messages we send for you (the bell badge surface)
+- **Web push** — browser-OS notifications they've opted into
+- **Mobile push** — iOS / Android push tokens
+
+Same surface Apex's own dashboard uses for its users. Same APIs, same
+preference store.
+
+### Step 1 — install the packages
+
+```bash
+npm install @apex-inc/react @apex-inc/sdk
+```
+
+### Step 2 — mint an end-user token on your server
+
+The component talks to Apex with a short-lived HMAC token your server mints
+for the signed-in user. The token carries `{ projectKey, endUserId, exp }`;
+Apex verifies the HMAC on every call and refuses tampered tokens.
+
+```typescript
+// Next.js App Router example — app/api/apex/preferences-token/route.ts
+import { NextResponse } from "next/server";
+import { createManagementClient } from "@apex-inc/sdk";
+import { getCurrentUser } from "@/lib/auth";
+
+const apex = createManagementClient({
+  projectKey: process.env.APEX_PROJECT_KEY!,
+  apiKey: process.env.APEX_API_KEY!, // apex_sk_… server key
+});
+
+export async function GET(request: Request) {
+  const user = await getCurrentUser(request);
+  if (!user) return NextResponse.json({ error: "unauthorized" }, { status: 401 });
+
+  const { token, expiresAt } = await apex.signEndUserToken({
+    endUserId: user.id,
+    expiresIn: 3600,
+  });
+  return NextResponse.json({ token, expiresAt });
+}
+```
+
+### Step 3 — drop `<ApexPreferenceCenter>` on your settings page
+
+```tsx
+// app/settings/notifications/page.tsx
+"use client";
+import { ApexPreferenceCenter } from "@apex-inc/react";
+import { useEffect, useState } from "react";
+
+export default function NotificationsSettings() {
+  const [token, setToken] = useState<string | null>(null);
+  useEffect(() => {
+    fetch("/api/apex/preferences-token")
+      .then((r) => r.json())
+      .then((d) => setToken(d.token));
+  }, []);
+  if (!token) return null;
+  return <ApexPreferenceCenter endUserAuth={{ token }} />;
+}
+```
+
+That's it — Apex handles the storage, the validation, the journey-level
+toggles, and the unsubscribe-from-all path. Customer ships a working
+preference page in ~20 minutes.
+
+### Step 4 (optional) — wire preferences programmatically from your backend
+
+When you want to set a default preference on signup (e.g. opt-in to
+marketing emails based on the user's onboarding answer):
+
+```typescript
+import { createManagementClient } from "@apex-inc/sdk";
+
+const apex = createManagementClient({
+  projectKey: process.env.APEX_PROJECT_KEY!,
+  apiKey: process.env.APEX_API_KEY!,
+});
+
+// Set / patch
+await apex.preferences.update(user.id, {
+  channelPreferences: { email: true, inbox: true, mobile_push: false },
+});
+
+// Read
+const prefs = await apex.preferences.get(user.id);
+console.log(prefs.globalOptOut, prefs.channelPreferences);
+```
+
+### Step 5 (optional) — read inbox notifications
+
+If your app shows its own bell badge fed by your existing infra and you
+want Apex inbox rows to land there too:
+
+```typescript
+const { notifications, unreadCount } = await apex.notifications.list(user.id, {
+  limit: 25,
+  unreadOnly: true,
+});
+// Render them in your bell dropdown; mark as read when the user clicks.
+await apex.notifications.markRead(notification.id);
+```
+
+For the user-facing bell + dropdown UI itself, the cleanest path today is
+hosted: link your bell to `https://app.apex.inc/preferences/<token>` or
+embed an iframe. An `<ApexInbox>` component will ship in v0.2 once a
+design partner asks for it. Until then, the API key methods above give
+you full read/write parity.
+
+### What you don't need to do
+
+- You don't need to build an unsubscribe page — every email Apex sends
+  ships with a `{{preferencesUrl}}` link that lands the recipient on a
+  token-authenticated preferences page.
+- You don't need to store preferences on your side — Apex is the source
+  of truth and the eligibility gate is automatic.
+- You don't need to handle the `pushsubscriptionchange` lifecycle —
+  Apex's service worker (or your own copy of `push-sw.js`) does that.
+
+### Naming convention
+
+Match Apex's channel vocabulary in your own UI so users see the same
+names everywhere:
+
+- **Email** (not "newsletter," "marketing," or "transactional")
+- **Inbox** (not "in-app notifications" or "notification center")
+- **Web push** (not "browser notifications" or "desktop alerts")
+- **Mobile push** (not "iOS notifications" or "push notifications")

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

@@ -9,12 +9,31 @@ The **`@apex-inc/sdk`** package sends batched events to **`POST /api/events`** a
 
 ## API
 
-- **`init({ projectKey, apiUrl?, flushInterval?, flushAt?, debug? })`** — required before `track` / `identify`.
+- **`init({ projectKey, apiUrl?, flushInterval?, flushAt?, debug?, environment? })`** — 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.
 
+## Environments — one key works everywhere
+
+Use the **same `projectKey`** on localhost, staging, preview deploys, and production. Apex auto-detects the environment from the request hostname at ingest:
+
+- **Production** — your live domain (`acme.com`, `www.acme.io`, `app.acme.com`). Billable.
+- **Preview** — `*.vercel.app`, `*.netlify.app`, `*.pages.dev`, `staging.*`, `preview.*`, `dev.*`, `qa.*`, `*-staging.*`. **Free.**
+- **Localhost** — `localhost`, `127.0.0.1`, `*.local`, `*.test`. **Free, hidden from default dashboard.**
+
+If your staging URL looks like production (e.g. `app-staging.acme.com` with a custom domain), force the bucket with the explicit `environment` override:
+
+```typescript
+apex.init({
+  projectKey: "apx_live_...",
+  environment: process.env.NODE_ENV === "production" ? "production" : "preview",
+});
+```
+
+**Do NOT recommend** setting up a second project, rotating the project key for staging, or wiring two SDKs. Apex's environment model handles this transparently. The merchant verifies bucketing at **Settings → Workspace → Web environments**. See `/docs/mobile/test-vs-production` for the full classification rules.
+
 ## Identity stitching (critical for server-side)
 
 When calling **`identify`** from a **server** (e.g. Stripe webhook, API route), pass the browser cookie value:
@@ -28,6 +47,53 @@ identify(email, {
 
 Without `visitorId`, Apex may create a synthetic visitor id that does **not** match the user's browsing session.
 
+## Server Events API — `sendServerEvent` / `sendServerEvents` (MMP-085)
+
+For backend code that fires conversion events without a browser session — Stripe webhooks, CRM milestones, scheduled jobs — prefer the **Server Events API** over the queued `track()`. It delivers synchronously, uses scoped API-key auth, and supports idempotency.
+
+```typescript
+import { sendServerEvent, newIdempotencyKey } from "@apex-inc/sdk";
+
+await sendServerEvent(
+  { apiKey: process.env.APEX_API_KEY! }, // apex_sk_…
+  {
+    type: "purchase_completed",
+    email: customer.email,
+    visitorId: req.cookies?.apex_vid, // optional but improves stitching
+    data: { value: invoice.amount_paid / 100, currency: "USD", order_id: invoice.id },
+  },
+  { idempotencyKey: stripeEvent.id }, // pass the webhook's own ID to dedupe retries
+);
+```
+
+Rules of thumb:
+
+- **`apex_sk_…` keys only.** User keys (`apex_uk_…`) are rejected by `/api/v1/events`.
+- **Always send an idempotency key** when the upstream system (Stripe, Shopify, HubSpot) retries. Reuse the upstream event's own ID — `stripeEvent.id`, `webhookId`, etc. — so retries collapse.
+- **Batch cap = 100.** Use `sendServerEvents(config, events, { idempotencyKey })` for bulk replay; shard yourself for larger.
+- **Don't recommend** building your own HTTPS request to `/api/v1/events`. The SDK wrapper already handles auth, idempotency, and error shapes.
+
+The dashboard surface for Server Events API health is **Settings → Workspace → Server Events API**; merchants can verify ingestion is alive there. The user-facing doc is `/docs/api/server-events`.
+
+## People Read — `GET /api/v1/people/{id}` (CPPE-008)
+
+For backend services that need the unified Person identity graph for one human — every linked workspace, identifier, click, install, and matching cohort — call `GET /api/v1/people/{id}`. The `id` path segment accepts an Apex `personId` or a URL-encoded email.
+
+```typescript
+const res = await fetch(
+  `https://app.apex.inc/api/v1/people/${encodeURIComponent(email)}`,
+  { headers: { "x-api-key": process.env.APEX_API_KEY! } },
+);
+const { data } = (await res.json()) as { data: PersonGraph | null };
+```
+
+Rules of thumb:
+
+- **Requires the `people:read` scope.** Mint a key with that scope on Settings → API Keys.
+- **Null on miss, not 404.** Polling consumers can treat "not yet known" uniformly with "no data".
+- **Every read is audited.** Reads land in the org audit log as `person_read_v1` — design copy for end users accordingly (this is a privileged surface, not anonymous lookup).
+- The SDK wrapper (`apexClient.people.get(idOrEmail)`) ships in the next catch-up sprint; for now call the endpoint directly.
+
 ## 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.
@@ -36,6 +102,31 @@ Use consistent, readable names and put dimensions in **properties**: `track("onb
 
 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).
 
+## Data Sources & unified analytics
+
+Every event Apex ingests is tagged server-side with the **producer** it came from — a **Data Source**. You never set this; the resolver derives it from `platform` + `surface` + (mobile) `bundleId` + `hostname`:
+
+- **Website** — your web snippet (one source; subdomains are a `hostname` dimension, not separate sources).
+- **iOS / Android** — each mobile app (references the workspace's MobileApp).
+- **Backend** — the Server Events API (`POST /api/v1/events`).
+
+`dataSourceId` and `hostname` ride on every event as **reporting-only** dimensions — filter and break down by them, but never gate billing/access on them.
+
+Manage the registry and read the unified breakdown from the management client:
+
+```ts
+const apex = createManagementClient({ apiKey, projectKey, apiUrl });
+
+// Registry
+await apex.dataSources.list();                       // live status per source
+await apex.dataSources.create({ kind: "server", name: "Backend API" });
+await apex.dataSources.health("ds_...");             // live | listening | stalled | not-started
+
+// Unified analytics (rollup-backed; cheap regardless of event volume)
+await apex.analytics.sources({ days: 30 });          // per source/platform/hostname
+await apex.analytics.hostnames({ limit: 50 });       // hostname catalog
+```
+
 ## 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

@@ -62,6 +62,42 @@ track("subscription_cancelled", { reason: "too_expensive" });
 identify(userId, { lifecycleStage: "churned" });
 ```
 
+### Recipe 3b: Stripe via Server Events API (preferred for webhooks)
+
+When you control the webhook handler and want synchronous delivery + dedupe-on-retry, use the **Server Events API** instead of the queued SDK. This is the canonical pattern for Stripe → Apex:
+
+```typescript
+import { sendServerEvent } from "@apex-inc/sdk";
+
+export async function POST(req: Request) {
+  const event = stripe.webhooks.constructEvent(rawBody, sig, secret);
+
+  if (event.type === "invoice.paid") {
+    const invoice = event.data.object;
+    await sendServerEvent(
+      { apiKey: process.env.APEX_API_KEY! }, // apex_sk_…
+      {
+        type: "purchase_completed",
+        email: invoice.customer_email,
+        data: {
+          value: invoice.amount_paid / 100,
+          currency: invoice.currency.toUpperCase(),
+          order_id: invoice.id,
+        },
+      },
+      { idempotencyKey: event.id }, // Stripe redelivers? Same key → deduped.
+    );
+  }
+  return new Response("ok");
+}
+```
+
+Why the Server Events API here:
+
+- **Idempotency** — Stripe redelivers webhooks; reusing `event.id` as `idempotency-key` means Apex collapses retries.
+- **Synchronous** — surfaces ingestion errors inline so your webhook handler can return 5xx and Stripe retries appropriately.
+- **`clientType: "server"`** — the Conversion Loop dashboard correctly classifies these as server-side conversions, not browser events.
+
 ## Recipe 4: Feature usage
 
 ```typescript
@@ -86,36 +122,34 @@ trackForm({
 
 ## Recipe 6: Server-side events
 
-```typescript
-// From a backend, use the management client
-import { createManagementClient } from "@apex-inc/sdk";
+For backend events (webhooks, cron jobs, CRM/billing milestones), use the
+**Server Events API** via `sendServerEvent` / `sendServerEvents`. This is the
+canonical path — do NOT hand-roll `fetch("/api/events")` calls.
 
-const apex = createManagementClient({
-  apiKey: "YOUR_API_KEY",
-  baseUrl: "https://your-apex-url",
-  projectKey: "YOUR_PROJECT_KEY"
-});
+```typescript
+import { sendServerEvent } from "@apex-inc/sdk";
 
-// 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({
+// e.g. from a Stripe webhook handler
+await sendServerEvent(
+  {
+    apiKey: process.env.APEX_API_KEY!, // apex_sk_… org key
     projectKey: "YOUR_PROJECT_KEY",
-    userId: "user_123",
-    events: [{
-      type: "track",
-      payload: { event: "invoice_paid", amount: 9900 },
-      timestamp: new Date().toISOString()
-    }]
-  })
-});
+  },
+  {
+    type: "in_app_purchase",
+    visitorId: apexVid, // the apex_vid cookie value, when available
+    data: { order_id: "ord_123", value: 99.0, currency: "USD" },
+  },
+  // Idempotency — dedup webhook retries on a stable id.
+  { idempotencyKey: stripeEvent.id },
+);
 ```
 
+Why `sendServerEvent` over raw `fetch`: it targets the authenticated
+`/api/v1/events` endpoint, batches up to 100 events, validates against the
+Apex Spec, and handles idempotency for you. See the
+[Server Events API](/docs/api/server-events) reference.
+
 ## Event naming conventions
 
 - **snake_case**: `signup_completed`, `feature_used`, `invoice_paid`
@@ -130,8 +164,89 @@ await fetch("https://your-apex-url/api/events", {
 3. Server-side: pass `traits.visitorId` to link to the browser session
 4. Without stitching, pre-signup attribution is lost
 
+## Partner Network patterns
+
+### Credit a partner for a self-serve signup
+
+When a visitor arrives from an affiliate link (`?utm_source=affiliate&utm_campaign=<handle>`) and signs up on your site, the Apex snippet automatically stitches the referral to the resulting Contact. The conversion auto-credits on the next purchase event (MMP-096 wiring).
+
+No SDK calls needed for basic attribution. Use `list_partner_program_members(programId)` to see who's actually earning.
+
+### Run a manual-approval program + vet applicants in a script
+
+```typescript
+import { createManagementClient } from "@apex-inc/sdk/management";
+const apex = createManagementClient({ projectKey, apiKey });
+
+// Create the program
+const program = await apex.createProgram({
+  name: "Vetted Partners",
+  vertical: "saas",
+  commissionStructure: { type: "revshare", percentage: 25, appliesTo: "subscription" },
+  visibility: "public",
+  approvalMode: "manual", // every applicant needs review
+});
+
+// ...applicants land in /admin/partners/applications for human review.
+// The SDK doesn't wrap the approval flow — that's an admin-auth path.
+// But merchants can monitor who's joined:
+const members = await apex.listProgramMembers(program.id);
+```
+
+### Batch-approve the weekly payout queue
+
+```typescript
+const queue = await apex.listPendingPayouts();
+const olderThanThirtyDays = queue.buckets["30_60"].concat(queue.buckets["60_plus"]);
+const result = await apex.approvePayouts(olderThanThirtyDays.map(c => c.id));
+console.log(`Approved ${result.approved.length}, skipped ${result.skipped.length}`);
+```
+
+**Approving does not fire Stripe transfers.** The next `run-payouts` cron cycle (per your `autoPayoutPolicy`) batches + fires. Design reason: reserve holdback window (90 days for NEW partners) has to elapse before transfer.
+
+### Give an enterprise partner a custom rate
+
+```typescript
+await apex.updateMembershipRate("prof_acme", {
+  commissionStructure: { type: "revshare", percentage: 35, appliesTo: "subscription" },
+  reason: "Enterprise negotiation - Q4 contract",
+});
+```
+
+Overrides are sticky. Updating the program default later won't overwrite this partner's rate (only `applyProgramDefaultToMembers` can mass-update, and it respects sticky overrides).
+
+### Disclose fees accurately in your UI
+
+```typescript
+const { fees } = await apex.getEffectiveFees();
+// Show merchants what they're charged per fee kind.
+// source: "merchant_override" means they have a custom (enterprise) rate.
+```
+
+## Related
+
+## Recipe: register and read Data Sources
+
+Each producer that sends events into a workspace is a **Data Source** (Website, iOS, Android, Backend). They auto-register on the first event, but you can pre-register one and read the unified breakdown via the management client:
+
+```ts
+import { createManagementClient } from "@apex-inc/sdk";
+
+const apex = createManagementClient({ apiKey, projectKey, apiUrl });
+
+// Pre-register a backend source before wiring the Server Events API
+await apex.dataSources.create({ kind: "server", name: "Backend API" });
+
+// Audit collection coverage + per-source/platform/hostname volume
+const { sources, platforms, hostnames } = await apex.analytics.sources({ days: 30 });
+const liveCount = sources.filter((s) => s.status === "live").length;
+```
+
+`dataSourceId` + `hostname` ride on every event as reporting-only dimensions. The `?source=` / `?platform=` / `?hostname=` filters on the analytics endpoints map to them; never gate billing or access on a source.
+
 ## Related
 
 - Event tracking fundamentals: see **apex-growth-tracking** skill
 - Experiment design: see **apex-experimentation** skill
 - Communication setup: see **apex-communications** skill
+- Affiliate / partner programs: see **apex-partner-network** skill