Publish MemberJunction as a native Zapier Platform integration (public directory listing)

# Publish MemberJunction as a native Zapier Platform integration

## Goal

Get MemberJunction listed as a **first-class app** in the [Zapier App Directory](https://zapier.com/apps) so end users can build Zaps using MJ triggers/actions/searches without configuring custom HTTP webhooks. Public listing is also a **prerequisite for Zapier MCP exposure** — private integrations do not appear in MCP (per Zapier docs).

## Why now

MJ already has the building blocks that make a Zapier app tractable:
- OAuth 2.0 server work in progress on `601-mcp-oauth`
- Existing Zapier MCP exploration on `claude/review-mcp-zapier-c0IvN`
- Metadata-driven entity system — well-suited to dynamic dropdowns via MJ's `Entity` metadata
- REST/GraphQL endpoints already exposed via MJAPI

This issue captures the full spec so we can size, prioritize, and hand off the work.

---

## Platform route: native **Zapier Platform CLI** (not MCP)

| Option | Public directory listing? |
|---|---|
| Zapier Platform CLI | ✅ Yes — recommended for MJ (git-versioned, fits monorepo) |
| Zapier Platform UI | ✅ Yes — visual editor, harder to maintain |
| Zapier MCP connector | ❌ No — MCP consumes public integrations, does not replace them |

**Location in monorepo:** `packages/Integration/zapier/` (new package)

Docs: [Platform UI vs CLI](https://docs.zapier.com/platform/quickstart/ui-vs-cli) · [Private vs Public Integrations](https://docs.zapier.com/platform/quickstart/private-vs-public-integrations)

---

## Authentication: OAuth 2.0 with PKCE

Zapier accepts OAuth 2.0 (preferred), API Key, Session, Basic, Digest — but for a public listing, OAuth 2.0 is strongly recommended. API Key is only acceptable if users can self-serve it from MJ's UI without contacting support.

**Requirements:**
- Authorization Code grant (only grant supported by Platform UI)
- Authorization URL + Access Token URL (POST)
- Refresh Token URL (recommended)
- PKCE built-in since Platform v14.0.0 (no workaround needed)
- Scopes (comma/space-separated)
- Auth test endpoint (e.g., `/me`)
- **All endpoints HTTPS**

**Reuse strategy:** Build on the OAuth 2.0 authorization server from `601-mcp-oauth` — MJ already needs a compliant OAuth AS for MCP; Zapier can use the same AS.

Docs: [OAuth v2](https://docs.zapier.com/platform/build/oauth)

---

## Build scope — Day One

MJ is metadata-driven, so we can expose **entity-generic** triggers/actions/searches and let Zapier users pick the entity via dynamic dropdown populated from MJ's `Entity` metadata.

### Triggers
- `New Record` — fires when any record of the selected entity is created (poll or webhook)
- `Updated Record` — fires when any record is updated
- `New Record Change` — fires on MJ Record Changes (leverages built-in version control)

### Actions
- `Create Record`
- `Update Record`
- `Delete Record`

### Searches
- `Find Record` — by entity + filter (RunView-style)
- `Find Record or Create` — idempotent upsert

### Category-specific preset triggers/actions (for discoverability)
Add pre-configured variants for `Contact`, `Account`, and other common CRM entities even though the generic version handles them — Zapier recommends concrete names like `New Contact` over `New Record of Type "Contact"`.

**Dynamic dropdowns required:** every entity/field parameter must come from a dynamic dropdown (never free text). MJ's metadata makes this straightforward.

Docs: [Build guidelines](https://docs.zapier.com/platform/publish/integration-build-guidelines) · [27-check reference](https://docs.zapier.com/platform/publish/integration-checks-reference) · [Recommended triggers/actions](https://docs.zapier.com/platform/quickstart/recommended-triggers-and-actions)

---

## Build quality gates (the 27 checks)

Top rejection reasons to design against upfront:
- **A001** — auth test endpoint must pass
- **D001/D007** — HTTPS only, no creds in input fields (creds only via Auth config)
- **D010/T002** — every sample payload has a primary key, matches live run output
- **D023/T003** — ISO-8601 dates everywhere, no epoch/custom formats
- **T004/T006** — static samples must match live run output (no fake data)
- **C004** — backward-incompatible schema changes rejected
- **M002** — description cannot mention "Zapier"
- **M004** — logo ≥256×256 PNG, square, transparent, no text
- **M005** — admin team member must have email on the API-owner's domain (i.e., `@memberjunction.com`)
- **S001** — need ≥3 users with a live Zap turned on before going Public

No minimum trigger/action/search count in official docs, but community reports the informal bar is 3+/3+/3+. The hard gate is **live user Zaps, not T/A count**.

Docs: [Integration checks reference](https://docs.zapier.com/platform/publish/integration-checks-reference)

---

## Branding assets required

| Asset | Spec |
|---|---|
| Logo | PNG, transparent, **≥512×512** (min 256×256), square, ≥72 DPI, **no text** |
| Primary brand color | Required, cannot be `#FFFFFF` |
| App name | "MemberJunction" — no ™/®, no "App"/"Integration" suffix |
| Short description | ≤160 chars, starts `"MemberJunction is a..."`, no "Zapier" reference, no links |
| Category | Exactly one (unless App Family exception) |

Docs: [Branding guidelines](https://docs.zapier.com/platform/publish/branding-guidelines)

---

## Testing requirements

- **Test account** in MJ with non-expiring login, email `integration-testing@zapier.com`, all paid features unlocked so Zapier's support team can reproduce issues
- **Every trigger/action/search** must have at least one **live, turned-on test Zap with ≥1 successful run** in Zap history — do not delete
- **≥10 Zap templates** authored before Public (templates are pre-built Zap blueprints in the directory)

---

## Submission process

1. Build + test as **Private** integration via Platform CLI
2. Run **PublishBot** (built-in 27-check linter) — fix everything it flags
3. Integration Home → **Publish** → fill form → **Submit for Review**
4. Status → **Pending** (still Private). Zapier developer responds within ~1 week with feedback
5. On approval: status → **Beta** — appears in directory with "Beta" tag
6. **Beta lasts 90 days** (early exit possible if 1+ user signs up from your Zapier embed)
7. After 90 days → **Public** automatically

**Timeline estimate:** ~4–5 months end-to-end (build → Beta → Public), dominated by the 90-day Beta window.

Docs: [Publish public integration](https://docs.zapier.com/platform/publish/public-integration) · [Publishing requirements](https://docs.zapier.com/platform/publish/integration-publishing-requirements)

---

## Versioning post-launch

- Semver: PATCH (bugfix) / MINOR (new T-A-S) / MAJOR (breaking)
- Only one Public version at a time; users default to Public version
- **Migrations must stay same MAJOR** (1.x→1.y OK; 1.x→2.0 requires user re-auth)
- Percent-based rollout (5–100%) and per-email migration supported via `zapier-platform migrate`

Docs: [Versions](https://docs.zapier.com/platform/manage/versions) · [Migrate users](https://docs.zapier.com/platform/manage/migrate) · [Planning changes](https://docs.zapier.com/platform/manage/planning-changes)

---

## Partner Program (free, post-launch)

Integration Partner Program — 4 tiers, evaluated quarterly (Jan/Apr/Jul/Oct):

| Tier | Active users/quarter |
|---|---|
| Bronze | entry |
| Silver | 50+ |
| Gold | 350+ |
| Platinum | 3,000+ (or 350+ with 20% QoQ growth) |

Benefits: co-marketing (blog/webinar/case studies), marketing dashboards, Partner Directory placement. No cost, no revenue share — Zapier does not charge partners or take a cut of user subscriptions.

Docs: [Partner Program](https://docs.zapier.com/platform/publish/partner-program)

---

## Cost

- Building, listing, maintaining: **free**
- No revenue share — Zapier does not bill partners based on Zap volume
- Partner Program: free
- End users pay Zapier directly for their Zapier plan; MJ is not billed

---

## Open questions / decisions for the team

1. **Entity scope on Day One** — generic entity triggers only, or also ship preset `Contact`/`Account`/`Entity Document` variants? (Recommendation: both — generic for power users, presets for discoverability)
2. **Polling vs webhook triggers** — polling is simpler; webhooks require MJ to push to Zapier's per-user webhook URL. MJ already has a notification system that could feed this.
3. **OAuth AS reuse** — confirm the `601-mcp-oauth` AS can be registered as the Zapier OAuth provider or if we need a separate endpoint
4. **Who owns the Zapier developer account** — needs a team admin with `@memberjunction.com` email (check M005)
5. **Branding** — who approves the official 512×512 MJ logo PNG + primary color for Zapier directory?
6. **MCP alignment** — once the public Zapier listing lands, MJ automatically becomes available in Zapier MCP. Do we want to pre-announce this?
7. **Ownership** — which team/engineer owns the Zapier package going forward, incl. responding to Zapier-reported bugs within the Partner Program "healthy" SLA?

---

## Suggested next actions (not committing yet)

- [ ] Identify owner for the Zapier package
- [ ] Create Zapier Platform developer account under `@memberjunction.com` domain
- [ ] Scaffold `packages/Integration/zapier/` via `zapier init` (CLI)
- [ ] Design OAuth scopes (least-privilege) for Zapier's access
- [ ] Source/approve 512×512 transparent-PNG logo + brand color
- [ ] Dogfood Private integration internally until ≥3 live user Zaps (S001 gate)
- [ ] Submit for Beta review

---

## References

- [Build your first public integration](https://docs.zapier.com/platform/publish/public-integration)
- [Integration publishing requirements](https://docs.zapier.com/platform/publish/integration-publishing-requirements)
- [Integration build guidelines](https://docs.zapier.com/platform/publish/integration-build-guidelines)
- [Integration checks reference (27 checks)](https://docs.zapier.com/platform/publish/integration-checks-reference)
- [Branding guidelines](https://docs.zapier.com/platform/publish/branding-guidelines)
- [Authentication overview](https://docs.zapier.com/platform/build/auth)
- [OAuth v2](https://docs.zapier.com/platform/build/oauth)
- [Platform UI vs CLI](https://docs.zapier.com/platform/quickstart/ui-vs-cli)
- [Private vs Public Integrations](https://docs.zapier.com/platform/quickstart/private-vs-public-integrations)
- [Recommended triggers/actions](https://docs.zapier.com/platform/quickstart/recommended-triggers-and-actions)
- [Versions](https://docs.zapier.com/platform/manage/versions)
- [Migrate users](https://docs.zapier.com/platform/manage/migrate)
- [Partner Program](https://docs.zapier.com/platform/publish/partner-program)
- [Integration Partner Program](https://zapier.com/developer-platform/partner-program)
- [Zapier MCP](https://zapier.com/mcp)