Payments: PayKit integration + API keys + entitlements

[BleedingDev]

Goal

Enable monetization for the hosted Smart Address service: customers can pay, get API access, and receive entitlements/limits that map to product capabilities (modes, quotas).

Who Uses This

• Customers purchasing API access.
• Operators managing subscription lifecycle and revenue operations.
• Engineering enforcing entitlements and measuring usage.

What “Done” Means (Business)

• Customers can subscribe via a payment provider and manage their subscription lifecycle (upgrade/downgrade/cancel).
• Customers receive an API key (or equivalent credential) for authenticated usage.
• The hosted service enforces entitlements (access to premium mode, quotas, rate limits).
• Usage is measured so billing can be accurate and auditable.
• Webhook-driven updates keep subscription state consistent.
• Self-hosting remains possible without requiring billing features.

Constraints

• Provider-agnostic integration (avoid lock-in).
• Strong security expectations for keys and webhook handling.

Out of Scope

• Full user account system (login, teams, roles) unless explicitly decided.
• Complex invoicing/tax/VAT and multi-currency from day one.

---

Technical notes: #5 (comment)

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• SDK: Core JS + React/Vue/Svelte + Web Component #1

👤 Suggested Assignees

• BleedingDev

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[BleedingDev]

Technical Notes

Architectural Split (to keep self-hosting clean)

• Keep apps/service-bun self-hostable and free of billing dependencies.
• Add a SaaS-only layer (proposed: apps/saas-gateway) that:
  • validates API keys
  • enforces quotas/rate limits
  • meters usage
  • handles PayKit webhooks
  • proxies requests to the core service

PayKit Integration

• Use @paykit-sdk/core + one provider adapter (start with @paykit-sdk/stripe).
• Webhook handler must process raw request bodies for signature verification.
• Persist webhook event IDs for idempotency.

Core Data Needed (SaaS DB)

• Tenants/customers, API keys (store hashes only), subscriptions, entitlements/limits, webhook events, usage aggregates.

Enforcement Points

• Auth: Authorization: Bearer <apiKey>.
• Preflight checks before expensive work: rate limit → quota → entitlement (strategy access).
• Metering: record provider usage + cache hits to support cost attribution and future billing reconciliation.

Integration with Other Issues

• Strategy modes: entitlement gating for reliable-fast.
• Analytics: tenant-aware metrics and usage reporting.