Skip to content

Integrations

Jump to bottom
Viames Marino edited this page Apr 25, 2026 · 5 revisions

Pair framework: Integrations

Pair supports a broad set of external services without making integrations feel like a separate subsystem bolted onto the framework.

Pair v4 extension packages should use Runtime Extensions: explicit registrations through RuntimeExtensionInterface and AdapterRegistry. The core does not auto-discover provider packages.

This is separate from Installable Packages, the ZIP/manifest package mechanism used for module, template, provider, and custom package installation through InstallablePackage and InstallablePackageRecord.

This area is a plus of the framework, but it should be read as a family of equal capabilities:

  • storage and file delivery
  • maps, geocoding, and places
  • mail delivery
  • payments
  • AI
  • anti-bot
  • search
  • Supabase bridge workflows
  • messaging and notifications

Use this page as the hub for choosing the right integration page and understanding how these services fit into Pair projects.

How to read this area

Integration pages in the wiki usually fall into one of these shapes:

  • service reference page Focused on constructor, main methods, configuration, and common usage.
  • low-level client/helper page Useful when a higher-level service is built on top of a reusable transport layer.
  • integration cookbook page Focused on architecture patterns, jobs, webhooks, background sync, and production behavior.

Not every external service needs all three layers. Some integrations are naturally small and need one reference page; others are split into multiple pages because the implementation has both transport and project-level integration concerns.

Service map

Storage and file delivery

  • AmazonS3 Server-side wrapper for S3-compatible object storage operations.

Maps, geocoding, and places

  • GoogleMaps Browser-side helper for loading Pair's Google Maps assets and frontend integration.
  • GoogleMapsClient Low-level HTTP client shared by the server-side Google Maps services.
  • GoogleGeocoder Server-side geocoding wrapper.
  • GooglePlacesService Server-side Places API wrapper.
  • GoogleAddress Form/input-oriented integration for address autocomplete and maps-assisted UX.

Mail delivery

  • Mailer Base abstraction for mail senders.
  • SendMail Concrete mail service using a sendmail-style transport.
  • SmtpMailer Concrete SMTP-based mailer.
  • AmazonSes AWS SES mail sender implementation.
  • ResendMailer Optional HTTP-only Resend mailer for transactional emails, tags, idempotency, and webhook events.

Payments

  • StripeGateway Optional payments gateway for Checkout Sessions, embedded checkout, Customer Portal, PaymentIntents, and webhook verification.

AI

  • OpenAIClient Optional AI client for Responses API calls, embeddings, and Realtime client secrets.
  • GeminiClient Optional AI client for Gemini native generateContent calls, chat-style transcripts, and embeddings.
  • ClaudeClient Optional AI client for Claude Messages API calls and chat-style transcripts.

Anti-bot

  • CloudflareTurnstile Optional Turnstile helper for browser widgets and server-side token validation on public forms and API writes.

Search

  • MeilisearchClient Optional search client for indexing read models, filtered and faceted search, pagination, and vector/hybrid search payloads.

Supabase bridge workflows

  • SupabaseClient Optional server-side bridge for Supabase Storage, Auth lookup, PostgREST/RPC, and Realtime URL construction without replacing Pair ORM or auth.

Messaging and notifications

  • TelegramBotClient Main Telegram Bot API client for generic calls, webhook helpers, messaging, and file downloads.
  • WhatsAppCloudClient WhatsApp Cloud API client for outbound messaging, media handling, webhook verification, and normalized events.

Choosing the right page

Use Integrations when:

  • you want the overview of supported external services
  • you need to decide which page to read first
  • you want a neutral map of the integration surface of Pair

Use a service reference page when:

  • you already know the provider
  • you need constructor details, config, and method-level examples

Use an integration cookbook page when:

  • the provider needs background sync, webhooks, retries, or production architecture guidance

Some integrations keep webhook and operational guidance directly in the class page, as happens with WhatsAppCloudClient. This is a documentation-shape choice, not a signal that one provider is more central to Pair than the others.

Common integration pattern in Pair

Across services, the recurring structure is usually:

  • a framework service/helper that wraps the external provider
  • optional project service classes that map provider behavior to domain behavior
  • controllers, jobs, or workers that call the project service

This keeps Pair controllers thin and isolates provider-specific behavior where it belongs.

For new optional packages, prefer this shape:

  • provider SDK dependency stays in the extension package
  • application bootstrap registers the Runtime Extension explicitly
  • the Runtime Extension publishes one or more adapters through Application::setAdapter(...)
  • API examples return explicit ResponseInterface objects
  • secrets are read from .env and never logged

Related pages

Clone this wiki locally