Catalog Capability Contracts

The catalog owns provider purposes and default descriptions. These describe a connection’s useful role; they never grant access to an operation or resource. The trusted runtime, selected tools, provider permissions, and organization grants remain authoritative. A catalog metric describes a supported target, not evidence that a collector is running or that a source has complete coverage.

These contracts were reviewed against the connector implementations and provider documentation on September 21, 2026. Reporting adapter rollout is tracked separately in the implementation milestone ledger. A successful connection, reporting permission, research progress, and available metrics are independent states.

The email adapters retain daily UTC component counts. Resend’s metrics cache can lag fifteen minutes; its returned dates establish actual retained coverage. A delivered email was accepted by the receiving server, which does not prove inbox placement. Instantly’s reported reply count is period activity; the reply/sent ratio is not a sent-cohort response rate or a classification of human/positive replies. Its complete campaign inventory explicitly includes AI-managed campaigns. Missing report days remain gaps, and zero sent messages produce an undefined rate. Account IDs are nullable when the provider exposes a globally unique resource ID without an account identity endpoint.

Stripe reporting uses API version 2025-02-24.acacia, with independent payment, refund and subscription sources under the authenticated account and live/test environment. Hourly payment collection follows balance movements so an older authorization captured today is not missed. Daily reconciliation traverses charges and refunds completely with resumable cursors. Only a completed subscription inventory becomes visible; each inventory retains its own snapshot identity. Current subscription state establishes history from collection onward, not earlier MRR.

Tax-exclusive sales require verified invoice or Checkout tax amounts. Missing tax, ambiguous multicapture timing, partial-payment tax allocation and unsupported pricing remain incomplete. Refunds use their own successful occurrence dates; authorization reversals are excluded. MRR includes active and past-due fixed recurring charges after applicable recurring discounts, excluding trials, metered usage, one-off fees and tax. Daily and weekly prices normalize using 365 days and 52 weeks per year; annual prices divide by twelve. Fixed discounts spanning incompatible billing periods remain incomplete. Scheduled cancellation is distinct from effective termination.

Lemon Squeezy reporting validates the key’s live/test mode and every selected store. It retains minimal order, renewal invoice, subscription, current item/price and discount-redemption facts. Initial invoices are excluded because their orders already represent the sale. Its separate native MRR definition sums a complete customer inventory in USD; it never replaces Oblive MRR. Chat reads use the API’s underscore filter names (store_id, subscription_id, and corresponding parent filters), and prove resource scope using relationship IDs or typed foreign-key attributes. Subscription collection uses bounded five-record pages and parallel independent detail reads. Unknown sale outcomes such as chargebacks and signed credit adjustments are retained as unknown payment facts; they produce calculation gaps rather than aborting unrelated inventory or implying zero.

The documented order/invoice API does not expose payment completion timestamps. Creation/update timestamps are not substituted, so occurrence-based collected-sales history remains incomplete. Refund amounts are cumulative; full-refund completion does not establish earlier partial-refund dates. These limits remain visible even when the last page contains no records. Oblive MRR supports verified standard/package recurring prices and applicable forever discounts. Incomplete item lists, tiered pricing, inclusive tax, repeating-discount end dates, product-limited discount allocation and fixed discounts shared by multiple order items remain explicitly incomplete. Lemon’s cancelled grace period remains active until effective expiration. All inventories resume at their retained page and become visible only after completion.

GA4 collection retains source calendar days, Monday-based weeks and calendar months. Weekly and monthly user counts come from matching-period reports with no date dimension; daily distinct counts are never added together. Each grain has a separate series and replacement-window receipt. Original property timezone boundaries include DST. Reports retain sampling sizes, thresholding, metric restrictions, explicit truncation and the expected 48-hour processing interval. Empty or restricted results remain gaps; a zero denominator is an undefined rate.

Event/user retention settings are retained as metadata, without imposing them on standard aggregate history. The provider’s explicit report truncation controls coverage. Native distinct counts can be approximate. A revoked Google refresh grant pauses reporting until reconnection; temporary platform errors remain retryable. GA4 stays fixed read-only.

PostHog discovers the personal key’s US/EU region and authorized projects. Reporting separately requires Query Read and Project Read. Fixed native Trends queries retain aggregate counts only: daily activity, rolling seven-day activity, rolling thirty-day activity, new users, and distinct sessions. Activity is a daily gauge; weekly/monthly displays use the latest gauge. New users and sessions use exact matching-period reports for source calendar days, Monday-based weeks and months. Never sum daily session counts to obtain a weekly unique-session count. Test-account filters are disabled in these definitions; all captured events are eligible. Native distinct estimates remain labeled as approximate. Activation and retention remain unavailable until their events and cohorts are configured.

Asynchronous PostHog query IDs are checkpointed and polled in later work units. Cached report timestamps remain distinct from collection timestamps. Missing permission pauses collection, warnings retain incomplete coverage, and truncated or incompatible reports cannot publish. The collector does not export events or person profiles and does not claim an undocumented retention window or processing delay.

Meta collection uses the pinned Marketing API version and read-only Insights reports. Asynchronous report IDs, pagination and source calendar windows are durable. Account and campaign levels publish together after all pages complete; their level dimension prevents adding account totals to their own campaigns. Reach comes from matching daily, weekly or monthly native reports and remains an estimated distinct count. Default conversions select purchase only, with explicit seven-day click and one-day view attribution on impression date. Aliased purchase action types are not added together. Missing purchase counts or values remain gaps. Rates retain their spend, click, impression or purchase components; CPM applies the factor of one thousand after aggregation.

X Ads remains a separate OAuth 1.0a source. Campaign discovery includes deleted campaigns and resumes through every account and campaign page. Funding instruments supply the actual currency; monetary micros divide exactly by one million. Hourly reports use explicit UTC windows and retain the account timezone separately. This avoids relabeling X’s daily reports, whose documented offset behavior does not reconstruct historical DST boundaries. Reports preserve separate placements and native purchase attribution: post-engagement plus post-view, excluding assisted conversions. The provider’s configured attribution windows are not replaced with an invented universal window.

Current X Ads data uses synchronous reports; reconciliation and backfill checkpoint asynchronous jobs in windows no longer than thirty days. Performance and conversion reports are separate. A missing conversion permission does not suppress valid spend. Downloaded gzip files use the official report host without credentials, with redirects disabled and compressed/decompressed size bounds. Expired jobs restart the same read-only window. Null metrics remain gaps and actual zero remains zero. Billing values retain the provider’s provisional 72-hour interval. Neither advertising collector requests campaign-changing permissions.

Engineering and support collection

GitHub uses stable repository and owner IDs, with separate pull-request, issue and Actions sources. Repository working defaults do not restrict the token’s reporting inventory. Completed open inventories establish gauges from connection onward. Issue closure events exclude pull requests and preserve later reclosures; merged pull requests use their actual merge timestamp. Workflow attempts include reruns separately. Success divides successful attempts by success, failure and timed-out outcomes; other conclusions remain separate. The workflow completion period uses the provider’s update timestamp, explicitly retained as its time basis. Oversized filtered windows split, and daily reconciliation revisits available runs to find later reruns. Actions retention is explicit.

Crisp keeps its existing workspace MCP token and reviewed read tools. The collector checks tool authorization and pagination arguments against the server’s advertised schema; unsupported filters cannot silently produce an incomplete total. Open conversations require a completed inventory. Conversation and message pages resume from minimal cursors without retaining message bodies, contact details or operator identities. First-human-response elapsed time starts at the first visitor message and excludes automated messages and internal notes. Unknown bot classification cannot establish an earlier human response. First resolution requires a retained state:resolved event, not a current resolved flag. Duration samples belong to their response/resolution event period.

Crisp’s active-operator gauge means the size of its native last-active reply list, not operators currently online. Limited visitor sockets produce partial coverage. These native snapshots and Oblive’s elapsed-time definitions remain distinct from Crisp’s separate analytics capability. The current MCP surface exposes conversation page numbers but lacks the reviewed filter and message continuation arguments required by the historical collector. Those conversation metrics report an unsupported reporting capability and pause; company configuration cannot supply a missing tool argument. Operator and visitor snapshots remain independently collectable, including the MCP items envelope for active operators.

Audience and social collection

Reach enumerates the official resource groups and their profiles, preserving both upstream IDs. The reviewed inventory includes reach_listProfileContactsV1 and reach_listProfileSegmentsV1: older unscoped tools only cover the default profile. Unfiltered pagination metadata establishes complete contact and segment totals; page length alone cannot. Profile counts come from the full resource inventory. These are snapshots from connection onward. Contacts across profiles represent profile memberships, not deduplicated people. No contact details are retained and no campaign operations are added to the connector.

X verifies the connected user and collects follower and per-post lifetime snapshots. Public post totals can include promoted activity; they remain separate from X Ads reports. Native engagements and link clicks require private metric access and are subject to the provider’s post-age window. Unavailable private metrics do not suppress available public impressions. Engagement rate uses matching lifetime components, taking the latest snapshot per post before aggregation. Repeated snapshots never become event-period flows. Post inventory is source-limited and does not establish twelve months of historical metrics. OAuth refresh persists rotated credentials with a comparison against the stored credential; the old collection generation must then retry before publication.

Provider references

• Resend: Metrics API.

• Instantly: Daily campaign analytics.

• Hostinger: Official MCP server, official API CLI.

• Exa: MCP tools.

• Firecrawl: Official MCP documentation. Our reviewed surface is narrower than the provider’s full catalog.

• Stripe: MCP, subscription analytics, charges, currency representation, multicapture.

• Lemon Squeezy: Customers, prices, orders.

• GitHub: Issues, workflow runs, Actions retention.

• Apollo: MCP. Oblive’s reviewed OAuth scopes intentionally cover a subset.

• PostHog: Query API, native aggregations.

• GA4: Reporting expectations, response metadata.

• Crisp: MCP token and scope, REST message and analytics contracts.

• Meta: Insights.

• X: Metrics, Ads analytics, Ads currency, Ads timezone behavior.

• Google Workspace: Official CLI.

• Upstash: REST API.

• MongoDB: Indexed document counts.

Contract changes

Update the catalog, trusted runtime when capabilities change, capability fixtures, agent instructions, and this reference together. Catalog purposes use the shared finite TIntegrationPurpose contract; they must be nonempty and unique. Keep owner customizations distinct from catalog presentation. Semantic metric changes require a new definition version. A declared metric is unavailable until its adapter can establish required source facts, permission, scope, and coverage.

Provider order

The first usable connection becomes Primary for each of its purposes; subsequent connections become Secondary, then Fallback. Owners can reorder providers under Integrations → Provider order. Reconnecting or rotating a key preserves the order. Disconnected entries keep their position but are ineligible; deleting an integration removes it. Google Workspace purposes reflect selected services.

GET /organizations/:id/integrations/preferences returns one revisioned document. PUT /organizations/:id/integrations/preferences/:purpose accepts expectedRevision and an exact permutation of connectorKeys. A concurrent connection or reorder produces a retryable conflict, never a lost owner choice. Preference changes refresh future runtime context without changing the authorization epoch. Manual usage role fields have been removed.

Selection checks capabilities, exact account/resource identity, grants, permission and readiness before applying this order. Resend, Instantly and mailbox operations are distinct. An uncertain external write must be reconciled through its original receipt before any further attempt. Analytics continues collecting all configured sources, including secondary providers.

Connection evidence

Resend and Stripe collect optional connection details alongside MCP validation with a five-second deadline and a 512 KiB response limit. Failure to read optional details does not disable a usable connection. No provider response bodies or private Stripe account/person fields are retained.

Resend retains the first 100 domain statuses and tracking settings, with an explicit completeness flag. A fully verified domain with sending enabled is identified as ready; partial or unknown verification stays unconfirmed. No sender address is inferred. The owner chooses a sender when sending requires one. Domain evidence is a connection-time snapshot.

Stripe identifies the authenticated account and distinguishes live/test key modes. Only account ID, default currency and source timezone are retained. Reporting permission probes remain separate from MCP connection success. The safe runtime inventory includes this bounded evidence and its check time.

Verified connection health

Configuration readiness means the required settings and credentials are saved. It is separate from verified provider access. POST /organizations/{organizationId}/integrations/{integrationRef}/check checks Google authentication or the MCP tool inventory with a bounded timeout. The integration projection and agent inventory include sanitized health observations for the exact credential and resource selection checked. Successful data operations record their own verification; discovery does not certify every operation. An unrelated successful operation cannot erase another failure.

Health is backend-owned durability. Stale results from replaced credentials or settings are ignored. Integration blockers include relevant health states in their recovery fingerprint, so a verified recovery can resume work without requiring an unrelated configuration edit. Repeated checks with the same result do not create a new recovery fingerprint. No agent command is added: agents observe health through the existing integration inventory and their authorized provider operations.

Reporting access and recovery

Crisp conversation reporting uses the REST API because its MCP conversation tools do not expose the required date filters and message cursor. Save a website or plugin identifier/key using PUT /organizations/{organizationId}/integrations/{integrationRef}/reporting-credential. The backend verifies that REST and MCP resolve the same website before encrypting the reporting credential with a separate encryption purpose. The API returns only credential presence. Removing these credentials does not disable MCP operations or the operator/visitor gauges. See Crisp authentication and the REST contracts.

MongoDB creation metrics require an allowed BSON date field and an indexed date-range query. A missing index or an incompatible sampled field produces an unavailable creation metric while document counts continue. An index proposal is { key: { [creationField]: 1 } } for the selected collection; Oblive never creates it automatically. Validate it against existing indexes and write costs before an owner applies it. The sample checks capability, not the type of every record.

Configuration, credential and adapter changes restart affected paused collectors. An explicit connection check also requests a bounded reporting recheck; repeat requests are coalesced and paused failures have a one-minute minimum before retry. Hourly collection remains unchanged. Successful discovery clears old failure reasons. A reporting failure does not revoke unrelated agent operations. Connection checks execute an enabled, reviewed read with no required arguments where available; tool discovery alone is never evidence that business data is readable.