> For the complete documentation index, see [llms.txt](https://wiki.fridays.bot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.fridays.bot/documentation/white-paper/3.-integration-layer.md). # 3. Integration Layer #### 3.1 Integration taxonomy The catalog targets \~50 vendors across 15 categories: accounting, email & calendar, CRM, file storage, payments, e-commerce, point of sale, scheduling & booking, team chat, payroll & HR, email marketing, e-signature, helpdesk, forms & intake, and project management. The full per-vendor reference (transport, auth, webhook scheme, rate limits, review gates, effort estimate) is Appendix A; this section describes the layer's mechanics. Categories are not equal. They differ on three axes that drive every subsequent engineering decision: * **Data criticality.** Accounting and payments actions move money; chat and forms actions do not. Risk classification (§6.1) is assigned per tool, but the *distribution* of high-risk tools is category-determined. * **API hostility.** Payroll (ADP, Rippling) and social publishing (Meta, LinkedIn, TikTok, X) combine restrictive partner gates, paid API tiers, and adversarial review — categories where direct integration cost is disproportionate to per-vendor value (§3.2.3). * **Event support.** Vendors with mature webhooks (Intuit, Zoho, Stripe-class payments) permit event-driven triggering; vendors without force polling, consuming quota the Rate-Limit Governor must ration (§2.3, §3.5). #### 3.2 Transport decision rule Per vendor, exactly one of three transports, chosen in this order: **Rule:** *vendor-official MCP server if one exists and passes the gateway-compatibility test (§3.3) → custom REST/GraphQL wrapper otherwise → unified aggregator when the category's per-vendor cost is disproportionate.* The rule is economic, not ideological. MCP \[1] and REST are complementary layers — MCP is the agent-facing tool interface, REST/GraphQL the transport beneath it, webhooks an independent event plane — so "MCP vs. REST" is a question of who maintains the tool schema, not of capability. **3.2.1 Vendor-official MCP servers** Where the vendor ships and maintains its own MCP server (Intuit for QuickBooks; Microsoft 365; Google Workspace services), Fridays consumes it as a client. Rationale, with the QuickBooks case as the example: * **Schema maintenance transfers to the vendor.** Intuit's MCP server exposes invoicing, estimates, customer search, and reporting as typed tools with input schemas Intuit updates in lockstep with its API. A custom wrapper would re-derive those schemas from OpenAPI specs and chase every minor-version change; the failure mode is silent field drift — precisely the breakage class indicted in §1.1. * **Auth is standardized.** The MCP authorization specification (2025-03-26 revision and later) adopts OAuth 2.1 with PKCE \[1]\[2], so vendor MCP servers plug into the same Token Vault and Callback Service as REST wrappers. One credential plane, two transports. * **Semantics come included.** Vendor tools encode business rules a wrapper must otherwise learn empirically — e.g., QuickBooks tool contracts distinguish deletable invoice states from sent/paid ones and enforce customer/product resolution before invoice creation. Encoding that state machine independently is weeks of sandbox archaeology per vendor. Caveat enforced by the gateway-compatibility test: a vendor MCP server is only adopted if every tool call can be mediated (§3.3). A server requiring direct client↔vendor session state that cannot transit the Action Gateway is rejected and the vendor falls to a REST wrapper — the single-egress invariant (§2.1) outranks maintenance convenience. **3.2.2 Custom REST/GraphQL wrappers** For vendors without an official MCP server, Fridays builds thin wrappers exposing the same typed-tool contract internally. Constraints: * **Tools mirror vendor semantics; they do not abstract them.** A generic `crm.contact.update` facade over Zoho and HubSpot invites the lowest-common-denominator trap unified-API vendors document candidly \[5]: fields that exist in one vendor and not the other either vanish or become untyped passthrough. Fridays instead ships `zoho.contact.update` and (later) `hubspot.contact.update` as distinct tools; cross-vendor uniformity lives in the playbook layer, where the planner selects tools per tenant stack (§5.1). * **Idempotency is wrapper responsibility.** Vendors vary: some accept idempotency keys natively, others require compare-and-set via etags or modified-time preconditions. The wrapper normalizes to the gateway's idempotency contract (§5.4) so the Executor's retry logic is vendor-agnostic. * **Pagination, batching, and partial-failure shapes are normalized** at the wrapper, not in the planner — LLM context is too expensive to spend on cursor bookkeeping (§13.1). **3.2.3 Aggregators for high-friction categories** Two categories route through unified-API aggregators rather than direct builds: * **Payroll/HR → Finch or Merge HRIS \[5].** Direct ADP integration requires the ADP Marketplace partner program (revenue share, certification cycle); Rippling gates its API similarly. Payroll data is also the highest-liability PII class in the stack. An aggregator converts N hostile integrations into one vendor relationship, one DPA, one audit target (§9.3) — at the cost of a sub-processor hop and lowest-common-denominator field coverage, acceptable because Fridays' payroll playbooks are read-heavy (headcount, pay-date awareness for cash-flow forecasting), not write-heavy. * **Social publishing → Ayrshare-class aggregator.** Meta, LinkedIn, TikTok, and X each impose app review with published rejection categories, paid access tiers (X API), and policy churn measured in quarters. Four adversarial review pipelines for one low-risk-class capability (posting) fails the cost rule outright. Aggregator tool calls transit the Action Gateway identically to direct connectors; the aggregator is a transport detail, not a policy exception. #### 3.3 MCP gateway All vendor-MCP traffic is routed through Fridays' own MCP gateway rather than letting planner/executor processes hold direct sessions to vendor servers. The gateway terminates the client side of each vendor MCP session and re-exposes the tools internally, which preserves four properties that direct sessions would forfeit: 1. **Approval interception.** A vendor tool like `quickbooks.invoice.send` carries external-communication risk; the suspension into the Approval Feed (§6.3) must occur *between* the executor's intent and the vendor's execution. Only a mediating gateway has that position. 2. **Metering.** Token spend and vendor API cost attribution per action (§7.4, §13.2) require observing every call at one choke point. 3. **Allow-list enforcement outside the model.** Vendor MCP servers advertise their full tool inventory; a playbook is entitled to a declared subset. The gateway filters tool visibility per playbook *before* tools reach planner context — an injected instruction cannot invoke a tool the planner never saw and the gateway would refuse anyway (§8.2). Enforcement in the prompt alone would be advisory. 4. **Version pinning.** Vendor servers change tool schemas; the gateway pins schema versions per playbook release and fails closed on unrecognized changes, converting silent drift into a CI signal (§3.6, §11.3). #### 3.4 Webhook gateway Single public ingress for vendor events (§2.1 invariant 2). Per-vendor verification is normalized here; nothing unverified reaches the Event Bus. Representative schemes, consolidated fully in Appendix A: * **Intuit/QuickBooks:** `intuit-signature` header, HMAC-SHA256 of the raw payload keyed with the app's verifier token \[3]. * **Microsoft Graph change notifications:** endpoint-validation handshake (`validationToken` echo) at subscription time, `clientState` secret comparison per delivery; rich notifications validated via signed JWT \[3]. * **Google (Gmail):** push delivered through Cloud Pub/Sub with OIDC-signed JWTs on the push endpoint \[3]. * **Zoho:** notification channel with HMAC verification. Beyond verification: **dedupe** (vendor delivery is at-least-once; the gateway keys on vendor event IDs with a sliding window), **replay guard** (timestamp tolerance window; stale signatures rejected), and **normalization** into internal event schema. The operationally underestimated problem is **subscription lifetime**. Microsoft Graph subscriptions for Outlook resources expire in ≤3 days; Gmail `watch()` registrations expire after 7 days; Zoho channels also expire \[3]. Event-driven triggering therefore depends on the Renewal Cron Farm (§4.4) re-arming subscriptions continuously — a lapsed subscription is another *fail-open* mode (§1.1): events silently stop, playbooks starve. Subscription health is exported as a first-class SLO (§7.5) precisely because the failure is invisible to the tenant. #### 3.5 Rate-limit governor Vendor limits differ in unit, scope, and enforcement, so a single global limiter is useless. The governor maintains a per-vendor quota model; representative shapes: * **QuickBooks Online:** \~500 requests/min per realm (tenant company) with a concurrency cap — limits scope to the *tenant*, so one busy tenant cannot starve another, but a single tenant's month-end sweep can starve itself \[4]. * **Gmail API:** quota-unit economy (operations cost different units; sends are expensive) with per-user-per-second ceilings — limits scope to *user × operation class* \[4]. * **Microsoft Graph:** dynamic throttling with `Retry-After` guidance; limits vary by workload and are intentionally unpublished in parts \[4]. * **Zoho CRM:** API credits per rolling 24 h scaled by plan tier — a *daily budget*, not a rate \[4]. Implementation: token-bucket instances keyed per (vendor, tenant, operation-class) fed by the quota model; adaptive backoff honoring `Retry-After` on 429/503 per HTTP semantics \[6]; and **priority classes** — interactive actions (an approval the owner just granted) preempt background sweeps (§10.2). Sustained 429 emission toward a vendor is also a partner-program risk: Intuit evaluates throttling behavior in app review (§3.7), so the governor is compliance infrastructure, not just politeness. #### 3.6 Sandbox matrix Every connector is wired to a persistent vendor test environment exercised in CI: Intuit sandbox companies, Microsoft 365 developer tenants, Google Workspace test domains, Zoho sandbox orgs, aggregator sandbox modes. Purpose is regression detection at the *vendor boundary* — the class of failure unit tests cannot see (schema drift, auth flow changes, new consent screens, webhook format changes). The matrix runs the playbook eval harness end-to-end (§11.3) on schedule and on every connector release; a vendor-side change that breaks a tool contract surfaces as a red build, not a tenant incident. Gaps are tracked explicitly: vendors without sandbox programs get dedicated paid test accounts, flagged in Appendix A as elevated-risk connectors. #### 3.7 Partner-program constraints as architectural inputs Review programs gate categories on timelines of weeks to months and impose technical requirements that must be designed in, not retrofitted: * **Google OAuth verification.** Gmail *restricted scopes* require app verification plus an annual third-party security assessment (CASA/Tier-2-class) \[7]. This constrains §4.5's scope policy: playbooks request the narrowest scope tier that functions, and restricted-scope surface is minimized because each addition re-triggers assessment scope. * **Intuit app review.** Security questionnaire, OAuth implementation review, throttling behavior, and production-keys gating for the QuickBooks App Store — which is simultaneously a GTM channel, making review posture a revenue dependency. * **Microsoft publisher verification / Microsoft 365 App Compliance Program.** Publisher verification is required for multitenant consent at scale; the compliance program tiers map directly onto SOC 2 evidence reuse (§8.6). Consequence: applications are filed ahead of code (long-lead tracking, component 8 in §2.2), and the transport decision rule (§3.2) already prices review hostility — it is *why* social and payroll route to aggregators. *** #### References (Section 3) \[1] Anthropic, *Model Context Protocol* specification — 2025-03-26 revision (authorization: OAuth 2.1) and 2025-06-18 revision. \[2] IETF RFC 7636 (*PKCE*); OAuth 2.1 draft (consolidating RFC 6749 + BCPs). \[3] Vendor event documentation: Intuit Webhooks (HMAC-SHA256 verifier token); Microsoft Graph change notifications (validation handshake, `clientState`, subscription lifetimes ≤3 days for Outlook resources); Gmail API push via Cloud Pub/Sub (`watch()` 7-day expiry); Zoho CRM notification channels. Consolidated per vendor in Appendix A. \[4] Vendor rate-limit documentation: Intuit QuickBooks Online API throttling (per-realm request and concurrency limits); Gmail API usage limits (quota units, per-user rate); Microsoft Graph throttling guidance (`Retry-After`); Zoho CRM API limits (credit system). Appendix A carries exact current values — vendor limits change; the appendix is the living reference, this section the design response. \[5] Unified-API vendor documentation on field-coverage tradeoffs: Merge (HRIS/accounting categories), Finch (employment systems). · \[6] IETF RFC 9110, *HTTP Semantics*, §10.2.3 (`Retry-After`). \[7] Google, *OAuth API verification FAQ* — restricted-scope requirements and annual security-assessment obligation for Gmail restricted scopes. *** *Next: Section 4 (Identity, Auth, and Secrets) — OAuth flows per vendor class, callback service, token vault construction, renewal cron farm, least-privilege scope policy.* *** ### As-Built Reconciliation — V1 *Legend/sources as in §1's addendum.* | § | Status | As-built (source) | | ------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 3.1 Taxonomy (\~50 vendors) | **PLANNED** | **Zero** SaaS connectors exist; four launch connectors (QB/Gmail/M365/Zoho) planned as plugins. IS §1, §4. | | 3.2 Transport rule | **mapped** | Backend's three routes = plugins (primary) / runtime MCP / routine webhooks. IS §4.1. | | 3.2.1 Vendor MCP | **EXISTS (route), un-mediated** | Attaches to the **agent runtime**; the tool call is *not* audited. IS §4.1 route 2. | | 3.2.2 REST wrappers | **EXISTS (substrate)** | = plugin workers (out-of-process, JSON-RPC/stdio, capability-gated, secret refs). IS §4.1 route 1. | | 3.2.3 Aggregators | **PLANNED** | No substrate change. | | **3.3 MCP gateway** | **ASPIRATIONAL** | The paper's key control (approval interception + metering + allow-list + version-pin at one mediating gateway) **does not exist**. IS §4.1 route 2 explicitly notes weaker mediation for runtime MCP; plan is to "consolidate write paths behind plugin tools," but the interim leaves an **un-mediated write path** (Tier-1 C). | | 3.4 Webhook gateway | **EXISTS** | Plugin inbound webhooks + routine triggers, HMAC-SHA256, replay window, secret rotation. IS §4.1, AO §5. Subscription re-arming (Graph ≤3 d / Gmail 7 d) — **PLANNED** (§4.4 farm). | | 3.5 Rate-limit governor | **PLANNED** | Substrate = routine concurrency/catch-up. → `rate-limiting-and-quotas-v1.md`. | | 3.6 Sandbox matrix | **PARTIAL** | Provider packages EXIST; per-vendor connector sandboxes + CI PLANNED. TS §4.3. | | 3.7 Partner-program constraints | **anticipated** | Intuit throttling review, Google CASA / Workspace Limited Use correctly identified as gates; not exercised (no connectors). SC §12; → `rate-limiting-and-quotas-v1.md` §4, `data-handling-and-privacy-v1.md` §4.4. | **Flag:** §3.3 is the trust-model linchpin and is aspirational. The transport *decision rule* is sound and matches backend's plugin-first strategy; the *mediation guarantee* around it is what must still be built. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.fridays.bot/documentation/white-paper/3.-integration-layer.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.