Integrations

Regulated provider contracts, storage, email, MCP, OAuth, API keys, and webhooks.

Regulated provider contracts

features/regulated-commerce/providers/contracts.ts defines the adapter interfaces:

  • IdentityProviderAdapter: create a verification session, retrieve the verified result (age, address match, evidence digest), verify webhooks, health.
  • RegulatedTaxAdapter: quote, commit, and reverse sales, excise, and local fee amounts.
  • CarrierEligibilityAdapter: eligibility, create and cancel label, delivery evidence.
  • ProductRegistryAdapter: resolve and snapshot authorization registries.

The default unconfiguredProvider throws "provider is unconfigured; regulated transactions remain disabled". To connect a provider, implement an interface, authenticate its callbacks from the raw body, and call the recording functions in features/keystone/regulated (recordVerifiedIdentityResult, recordRegulatedTaxQuote, commitRegulatedTaxQuote, recordCarrierEligibility, reverseRegulatedTaxCommit) for the exact cart fingerprint. Raw identity data must never be passed to or stored by those functions; only hashed subjects and evidence digests. Keep failures closed.

features/regulated-commerce/import/shopify.ts plans a Shopify product import and quarantines items with missing evidence; it never treats Shopify tags or publication as legal authority.

Payments and shipping

See Payment providers and Shipping providers.

Storage and email

Images use Keystone S3 storage (S3_BUCKET_NAME, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_ENDPOINT). Email uses SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_STORE_LINK.

MCP and AI chat

/api/mcp-transport/[transport] is a JSON-RPC MCP server that forwards the caller's cookie to /api/graphql, so tools run with the caller's permissions. It exposes schema tools (listModels, queryData, searchModels, getFieldsForType, lookupInputType, createData, updateData, deleteData, modelSpecificSearch) and commerce tools (searchProducts, getProduct, cart tools, shipping and payment tools, placeOrder, getOrder). /api/completion is the dashboard assistant via OpenRouter (OPENROUTER_API_KEY, OPENROUTER_MODEL, OPENROUTER_MAX_TOKENS).

OAuth and API keys

/api/oauth/authorize, /api/oauth/callback, and /api/oauth/token serve OAuthApp integrations such as the Order Management System connection. ApiKey provides scoped machine credentials (active, inactive, revoked; optional expiry and IP restriction). Both need the credential scope and the owner's current role permission. Manage them at /dashboard/platform/api-keys, /apps, and /order-management-system.

Webhooks

WebhookEndpoint records subscribe to events with STORE or USER scope (customer tokens may subscribe only to fulfillment.created; registerWebhookEndpoint). Events go to the WebhookEvent outbox with delivery attempts and dead-lettering; retryWebhookDeliveries redelivers them. Manage endpoints on the generic /dashboard/web-hook-endpoints pages.

On this page