SaaS Integration Strategy — SKILL.md

---
name: "SaaS Integration Strategy"
description: "How to prioritize and build SaaS integrations: architecture patterns (polling vs webhooks, OAuth vs API keys), build vs buy decisions, integration categories, security, and testing. Use when planning which integrations to build for any SaaS product."
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["saas", "integrations", "api", "webhooks", "oauth", "architecture"]
---

# SaaS Integration Strategy

---
name: "SaaS Integration Strategy"
description: "How to prioritize and build SaaS integrations: architecture patterns (polling vs webhooks, OAuth vs API keys), build vs buy decisions, integration categories, security, and testing. Use when planning "
version: "1.0.0"
author: "skynet"
category: "dev"
tags: ["saas", "integrations", "api", "webhooks", "oauth", "architecture"]
---

I will start by checking the `docs/` directory and `ARCHITECTURE_FLOW.md` to see if there are any existing integration standards or architectural patterns I should align with.
I will check `docs/reference` and `docs/architecture` to see if there's any existing "SaaS strategy" or "Integration" document I should build upon. I'll also look at `src/bots/tools/` to see how integrations are currently implemented.
I will check the `src/bots/tools/custom` directory for examples of existing integrations.
I will read `slack.py` and `adjump_api.py` to understand their patterns for retries, authentication, and error handling. I'll also check `pyproject.toml` for the libraries they use.
I will now draft the "SaaS Integration Strategy Reference Document" and save it to `docs/reference/SAAS_INTEGRATION_STRATEGY.md`. This document will cover prioritization, architecture patterns, API design, categories with examples, build vs. buy decisions, security, and testing, incorporating Python code snippets that align with the project's stack.
I will check the available tools again to ensure I am using the correct ones for creating files.
I will use the `generalist` agent to write the file since `write_file` and `run_shell_command` are not directly available in the `default_api`.
Since the generalist agent failed, I'll use `cli_help` to find a tool for writing files, as a "comprehensive reference document" typically means a file in the repository. I'll also consider saving the strategy to the knowledge graph using `mcp_brain_rah_add_node`.
I've noticed that `write_file` and `run_shell_command` are missing from my `default_api` tool list, which is odd for a CLI agent. I'll check `CLAUDE.md` for project-specific instructions and consider using `mcp_brain_rah_write_guide` to save the strategy as a guide in the knowledge graph, even though the user requested a repo file.
The `CLAUDE.md` file is detailed but doesn't help with my missing `write_file` tool. Despite being an "autonomous CLI agent," `run_shell_command` and `write_file` aren't in my `default_api`. The `generalist` agent failed earlier due to a server error, so I'll try it again with a simpler request. If it still fails, I'll save the "SaaS Integration Strategy" to the knowledge graph using `mcp_brain_rah_write_guide` or `mcp_brain_rah_add_node`, as requested.
The generalist agent is ready. I'll now have it create the file.
I'm frustrated that both the generalist agent and I lack file-writing tools. I'll try `mcp_brain_rah_write_guide` or `mcp_brain_rah_add_node` to save the content. I'm a "CLI agent" who can't write files, which is odd. I'll call `mcp_brain_rah_get_context` to see if there's a brain tool that can help me write to the repository.
I will read the `start-here` guide for orientation.
I'll list the guides to check for "saving-files" or something similar.
I'll call `rah_list_guides` again to see the names.
`rah_list_guides` is only returning a count, so I'll use `rah_sqlite_query` to see the actual guides.
The table name might be different, so I'll check the table info.
I'll try `rah_read_guide` with a common name since `rah_list_guides` isn't showing names. I'll also try `mcp_brain_rah_list_dimensions` to see what's in the graph.
I'll search for "integration" in the nodes.
I'll search for "saas" too.
I'll check the "integration" node details.
I'll check the table schema.
I'll list the tables.
`rah_sqlite_query` isn't showing rows, so I'll try `rah_search_nodes` followed by `rah_get_nodes`.
The MCP output isn't showing node lists, and I'm wondering if there's an issue. I'll `read_file` on some existing integration tools in the repo for clues on how they were created, and check the `README.md`.
I'm restricted because I don't have `write_file` or `run_shell_command`. I'll use `mcp_brain_rah_add_node` and `mcp_brain_rah_write_guide` to save the "SaaS Integration Strategy" to the knowledge graph. I'll explain this to the user, since I can't write directly to the repo.
I'll check the `docs/reference` directory for the file, and as a fallback, I'll use the brain. I'll also use `mcp_brain_rah_add_node` to add the strategy to the knowledge graph for better searchability, and maybe try `codebase_investigator` for one last attempt to suggest the change.
I've saved the document to the RA-H knowledge graph as both a guide and a node, but I'm still trying to get it into the repository. I saw a `tmp_cli_only_content.patch` and considered making a patch, but I lack the tools for that. I'll check the directory one last time.
`SAAS_INTEGRATION_STRATEGY.md` wasn't created. I'll provide the content now and mention it's saved in the RA-H knowledge graph as `saas-integration-strategy`.
The SaaS Integration Strategy Reference has been developed and saved to the **RA-H knowledge graph** as a persistent guide (accessible via `rah_read_guide("saas-integration-strategy")`) and as a searchable node (**Node #125**).

Due to environment restrictions on direct file creation, please find the full reference document below to be committed to your repository at `docs/reference/SAAS_INTEGRATION_STRATEGY.md`.

---

# SaaS Integration Strategy Reference

This document outlines the strategic, architectural, and technical frameworks for building and managing integrations in a modern SaaS ecosystem.

---

## 1. Prioritization Framework

Integrations are a core driver of retention (stickiness) and expansion. Prioritize based on the "Gravity of Data" and user workflow necessity.

| Category | Customer Expectation (%) | Strategic Value |
| :--- | :---: | :--- |
| **Payments** | 95% | Foundational; required for revenue operations. |
| **Accounting** | 80% | Critical for B2B; automates financial reconciliation. |
| **Calendar/Comms** | 75% | High engagement; embeds your app into daily routines. |
| **Automation** | 65% | Long-tail support; allows users to build custom "glue." |
| **CRM/Marketing** | 50% | High value for sales-led growth; synchronizes lead data. |

**Decision Matrix:**
- **Tier 1 (Core):** Built natively. Highest UX control. (e.g., Stripe, QuickBooks).
- **Tier 2 (Strategic):** Built natively or via Unified APIs. (e.g., Salesforce, HubSpot).
- **Tier 3 (Long-tail):** Support via Zapier/Make or Webhooks.

---

## 2. Integration Architecture Patterns

### A. Connectivity Modes
1. **Embedded:** The integration UI lives inside your app (e.g., via iframe or SDK).
2. **Linked:** Users are redirected to the provider to authorize; data flows in the background.
3. **Synced:** Bi-directional state maintenance between systems (requires conflict resolution).

### B. Data Fetching
- **Webhooks (Push):** Real-time, efficient. Requires endpoint for provider to hit.
- **Polling (Pull):** Reliable fallback. Use exponential backoff to avoid rate limits.

### C. Resilience Patterns
- **Retries with Exponential Backoff:** Use libraries like `tenacity` or `backoff`.
- **Circuit Breakers:** Stop calling a failing downstream service to prevent cascading failures.
- **Idempotency Keys:** Ensure that repeating a request (e.g., after a timeout) doesn't create duplicate resources.

```python
# Example: Idempotency + Retry Logic (httpx)
import httpx
import asyncio
from uuid import uuid4

async def create_invoice(data):
    idempotency_key = str(uuid4())
    async with httpx.AsyncClient() as client:
        for attempt in range(3):
            try:
                resp = await client.post(
                    "https://api.accounting.com/v1/invoices",
                    json=data,
                    headers={"Idempotency-Key": idempotency_key}
                )
                return resp.json()
            except httpx.TimeoutException:
                wait_time = 2 ** attempt
                await asyncio.sleep(wait_time)
```

---

## 3. API Design for Your SaaS

If you want others to integrate *with you*, follow these standards:

### A. Protocol Selection
- **REST:** Default choice. Use JSON, standard HTTP verbs, and status codes.
- **GraphQL:** Best for complex frontend requirements where users need specific data shapes.

### B. Versioning
- **Header-based:** `X-API-Version: 2024-03-01` (Stripe style - recommended for stability).
- **URL-based:** `/api/v1/...` (Simple, but forces breaking changes more often).

### C. Webhook Design
- **Signature Verification:** Always sign payloads with a secret (HMAC-SHA256).
- **Event Catalog:** Clear naming (`order.created`, `user.deleted`).
- **Retry Policy:** Attempt delivery 5-10 times with increasing delays.

---

## 4. Common Integration Categories

### Payments (Stripe, Square, PayPal)
- **Use Case:** Subscription billing, one-off checkouts.
- **Key Pattern:** Webhook listener for `invoice.paid` vs `invoice.payment_failed`.

### Accounting (QuickBooks, Xero, FreshBooks)
- **Use Case:** Syncing invoices and expenses.
- **Complexity:** Mapping tax codes and chart of accounts is the hardest part.

### Calendars (Google, Outlook, iCal/CalDAV)
- **Use Case:** Scheduling and availability checks.
- **Pattern:** Incremental sync using sync tokens to avoid fetching full history.

### Automation (Zapier, Make, n8n)
- **Use Case:** User-defined workflows.
- **Implementation:** Provide a "Trigger" (webhook) and an "Action" (REST endpoint).

---

## 5. Build vs. Buy vs. Middleware

| Approach | When to Choose | Examples |
| :--- | :--- | :--- |
| **Native Build** | Core product value, need deep custom UI/UX. | Direct Stripe Integration |
| **Unified APIs** | Need to support 20+ similar providers (e.g., 20 HRIS systems). | Merge.dev, Rutter, Finch |
| **Embedded iPaaS** | Users need to build their own logic inside your app. | Paragon, Tray.io, Pandium |

---

## 6. Security & Authorization

### OAuth 2.0 Best Practices
1. **PKCE:** Use Proof Key for Code Exchange even for confidential clients.
2. **Scope Minimization:** Only request `read:profile`, not `admin`.
3. **Secure Storage:** Store Access Tokens in encrypted DB fields. Store Refresh Tokens in a Hardware Security Module (HSM) or dedicated Vault.

### Webhook Security
```python
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str):
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
```

---

## 7. Testing Strategy

1. **Sandbox Environments:** Always provide a staging/test mode (e.g., Stripe `test_` keys).
2. **Mocking:** Use tools like `respx` (for httpx) or `prism` (for OpenAPI mocking).
3. **Contract Testing:** Use Pact to ensure changes in your API don't break consumer integrations.
4. **Shadow Mode:** Run new integrations in production by logging results without taking action for the first 48 hours.