@apex-inc/mcp-server 0.3.1 → 0.7.0

package/skills/apex-partner-network/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: apex-partner-network
+description: Build, run, and grow an affiliate / referral program on the Apex Partner Network. Use when a merchant wants to pay partners a commission for driving installs / purchases / subscriptions, manage a roster of affiliates, or invite specific people to promote their product. The SDK wraps programs, memberships, invitations, payouts, fee disclosure, and merchant vouching.
+---
+
+# Apex Partner Network (SDK)
+
+The Apex Partner Network is a two-sided affiliate network: merchants own programs, partners join one or many programs across every merchant they work with, Apex facilitates the money rail between them via Stripe Connect.
+
+This skill covers the **merchant-facing management SDK** — programmatic access from a Node.js backend using an `apex_sk_*` service key. Partner-facing flows (self-signup, dashboard, Stripe Connect OAuth consent) happen in the hosted portal at `partners.apex.inc`.
+
+## Core mental model
+
+| Concept | What it is |
+|---|---|
+| **Program** | A merchant-owned commission offer (CPA or RevShare). Merchants can run multiple. |
+| **Membership** | One partner × one program. Carries the partner's current commission (and its audit history). |
+| **Conversion** | A tracked install/purchase/subscription credited to a partner via their Apex link. |
+| **HoldbackEntry** | One per approved conversion. Splits commission into available + held portions per the partner's trust tier. |
+| **MerchantPayoutBatch** | A settled cycle of all released-available commissions for one partner, fired per the merchant's `autoPayoutPolicy`. |
+
+## SDK bootstrap
+
+```typescript
+import { createManagementClient } from "@apex-inc/sdk/management";
+
+const apex = createManagementClient({
+  projectKey: "your-project-key",
+  apiKey: process.env.APEX_API_KEY!,
+  apiUrl: "https://app.apex.inc", // omit for local dev
+});
+```
+
+All calls below go through this client. Under the hood, requests attach `x-api-key` + `x-apex-project` headers to every `/api/mobile/affiliates/*` route.
+
+## Creating your first program
+
+```typescript
+const program = await apex.createProgram({
+  name: "Partner Program",
+  description: "Refer a customer, earn 20% for 12 months.",
+  vertical: "saas",
+  commissionStructure: {
+    type: "revshare",
+    percentage: 20,
+    appliesTo: "subscription",
+  },
+  visibility: "public",   // shows in /marketplace for partner discovery
+  approvalMode: "manual", // review each applicant
+});
+```
+
+Programs can be `paused`/`archived` later via `updateProgram(id, { status: "paused" })`. Pausing freezes new applications + new conversions but keeps existing memberships alive.
+
+## Inviting a partner
+
+```typescript
+await apex.invitePartner({
+  email: "sarah@example.com",
+  programId: program.id,
+  inviterName: "Alice from Acme",
+  inviterMessage: "I'd love to partner with you — here's a special rate.",
+  customRate: {
+    commissionStructure: {
+      type: "revshare",
+      percentage: 30, // negotiated higher rate
+      appliesTo: "subscription",
+    },
+  },
+});
+```
+
+Sarah gets a magic-link email. If she's already a partner on Apex, the invite creates a new `AffiliateMembership` bound to this program. If she's new, she claims a handle + completes onboarding at the portal.
+
+**Handle rule**: one `@sarah` works across every merchant program she joins. She doesn't need a separate account per merchant.
+
+## Adjusting commission rates
+
+Three commission sources are possible:
+- `program_default` — set by the program; member has never been individually adjusted
+- `membership_override` — explicit override set on this membership (sticky; survives program default updates)
+- `invite_override` — set at invite time (sticky same as membership_override)
+
+```typescript
+// Bump this specific partner to 35%
+await apex.updateMembershipRate("prof_sarah", {
+  commissionStructure: {
+    type: "revshare",
+    percentage: 35,
+    appliesTo: "subscription",
+  },
+  reason: "Volume performer — Q3 bump",
+});
+
+// ...later, reset them back to program default
+await apex.resetMembershipRate("prof_sarah", "Q3 promo ended");
+```
+
+Updating a program's default does NOT retroactively change existing memberships — call `applyProgramDefaultToMembers(programId)` to fan it out (skips overrides).
+
+## Approving payouts
+
+Commissions sit as `pending` until approved. The full batch flow:
+
+```typescript
+// 1. What's owed
+const queue = await apex.listPendingPayouts();
+// {
+//   buckets: { "0_30": [...], "30_60": [...], "60_plus": [...] },
+//   totals: { "0_30": 1450.00, ... },
+//   effectivePolicy: { policy: "manual", source: "project", capUsd: undefined },
+//   caps: { daily: undefined }
+// }
+
+// 2. Approve (creates HoldbackEntry + transitions to "approved")
+const result = await apex.approvePayouts(
+  queue.buckets["0_30"].map(c => c.id),
+);
+// { approved: [{ id, heldbackAmountUsd }], skipped: [...], failed: [...] }
+```
+
+**Approving does NOT fire the Stripe transfer**. The transfer happens at the merchant's `autoPayoutPolicy` cycle (daily / weekly / manual). This decoupling:
+
+- lets the merchant review multiple conversions before committing
+- lets the platform batch per (merchant, partner) to minimize Stripe fees
+- gives the holdback release window (90d for NEW partners, 30d for VERIFIED) time to run
+
+## Fee disclosure
+
+Merchants should always know what Apex charges them:
+
+```typescript
+const { fees } = await apex.getEffectiveFees();
+// fees: {
+//   facilitation_payout: { bps: 25, flatUsd: 0.5, source: "platform_default", isCustom: false },
+//   identity_verification: { flatUsd: 2.5, source: "platform_default", isCustom: false },
+//   instant_payout: { bps: 100, flatUsd: 0.5, source: "platform_default", isCustom: false },
+// }
+```
+
+Enterprise deals show `isCustom: true` with `source: "merchant_override"`. Admin edits propagate within 60 seconds (cache TTL).
+
+## Vouching for a partner
+
+A merchant who knows a partner outside Apex can vouch for them — bumping their trust tier one level for 60 days. This unlocks higher payout caps for the partner immediately. It's NOT free: the merchant takes on indemnity.
+
+```typescript
+await apex.vouchForPartner("prof_sarah", {
+  indemnityAcknowledged: true, // MUST be literally true
+  reason: "10-year professional relationship, verified off-platform",
+});
+```
+
+**Important**: if the partner commits fraud during the 60-day vouched window, the merchant's account is liable for clawbacks the reserve can't cover. Use sparingly.
+
+## What happens when things fail
+
+**Partner reaches a cap**: the batch surfaces a tier-aware message. NEW-tier partners see "processing" (masked); TRUSTED/VERIFIED partners see the reason.
+
+**Merchant's Stripe balance is short**: retry fires in 24h. After 48h (2nd fail), the merchant gets an email. After 72h (3rd fail), a dashboard card appears + partner messaging flips. After 7 days (7th fail), Apex opens a support case — **not labeled as fraud** — for human triage.
+
+Automation never freezes a merchant's `autoPayoutPolicy`. That's always a human decision.
+
+## Reading auto-payout policy
+
+Set per-project or per-program:
+
+```typescript
+await apex.updateProgram(programId, {
+  autoPayoutPolicy: "auto_under_cap", // auto-pay up to cap, manual above
+  autoPayoutCapUsd: 1000,
+});
+```
+
+Policies:
+- `"manual"` — every payout needs merchant click-to-approve (default)
+- `"auto"` — approved conversions auto-queue for the next payout cycle
+- `"auto_under_cap"` — auto under `autoPayoutCapUsd`, queue above
+
+## What this SDK does NOT cover
+
+- **Partner-facing flows** (self-signup at `/apply`, portal dashboard, Stripe Connect Express onboarding) — these happen in the hosted portal + require Cognito auth, not API key auth.
+- **Admin / Fraud Ops** (case queue, appeal decisions, ban list, fee policy edits) — admin Cognito flow, different tooling.
+- **Webhooks** (Stripe Connect events, identity verification status) — those are inbound from Stripe, not outbound from the SDK.
+- **Real-time Stripe transfers** — transfers fire on the merchant's schedule via the platform's payout orchestrator, not synchronously from the SDK.
+
+## See also
+
+- `apex-integration-cookbook` — end-to-end patterns combining partner network + communications + experiments
+- MCP tools: `list_partner_programs`, `create_partner_program`, `invite_partner`, `approve_payouts`, `vouch_for_partner`, `get_effective_fees`
+- Docs: `/docs/partner-network/` for concept walkthroughs + integration guides