diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f502fd00..1c323f8d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -226,6 +226,13 @@ jobs:
cd ui/packages/nextjs
npm publish --provenance --access public ${{ github.event.inputs.dry_run == 'true' && '--dry-run' || '' }}
+ # Trusted publishing only works for a package that already exists on
+ # npm, so the first release of this one is published by hand.
+ - name: Publish @authsome/plugin-subscription
+ run: |
+ cd ui/packages/plugin-subscription
+ npm publish --provenance --access public ${{ github.event.inputs.dry_run == 'true' && '--dry-run' || '' }}
+
# ─── Flutter/pub.dev Release ─────────────────────────────────────────
# Authentication is OIDC, provisioned inside the reusable workflow -- there is
# no pub credential to configure here. Two consequences:
@@ -238,6 +245,11 @@ jobs:
# 2. pub.dev rejects automated publishing from anything but a tag push, so a
# workflow_dispatch run can only ever rehearse. dry-run is forced on for
# those, which is also what the dry_run input maps to on a tag push.
+ #
+ # Automated publishing can only be switched on for a package that already
+ # exists on pub.dev, so authsome_subscription and
+ # authsome_subscription_flutter go up by hand (`dart pub publish`) once,
+ # then get the tag pattern above. Until then their step here fails.
flutter-release:
name: Flutter Release
needs: [prepare]
@@ -252,5 +264,5 @@ jobs:
with:
# Ordered: authsome_flutter depends on authsome_core, and
# authsome_flutter_ui depends on authsome_flutter.
- packages: '["flutter/packages/authsome_core", "flutter/packages/authsome_flutter", "flutter/packages/authsome_flutter_ui"]'
+ packages: '["flutter/packages/authsome_core", "flutter/packages/authsome_flutter", "flutter/packages/authsome_flutter_ui", "flutter/packages/authsome_subscription", "flutter/packages/authsome_subscription_flutter"]'
dry-run: ${{ github.event_name != 'push' || github.event.inputs.dry_run == 'true' }}
diff --git a/api/me_active_org_test.go b/api/me_active_org_test.go
index 61480fa2..cb37330f 100644
--- a/api/me_active_org_test.go
+++ b/api/me_active_org_test.go
@@ -44,4 +44,9 @@ func TestGetMe_ActiveOrgID(t *testing.T) {
withOrg := *sess
withOrg.OrgID = orgID
assert.Equal(t, orgID.String(), get(middleware.WithSession(base, &withOrg))["active_org_id"])
+
+ // A JWT carries the organization in its claims and there's no session
+ // row; the auth middleware puts the org on the context instead.
+ jwtOrg := id.NewOrgID()
+ assert.Equal(t, jwtOrg.String(), get(middleware.WithOrgID(base, jwtOrg))["active_org_id"])
}
diff --git a/docs/content/docs/plugins/subscription.mdx b/docs/content/docs/plugins/subscription.mdx
index 46af8af9..f437fa44 100644
--- a/docs/content/docs/plugins/subscription.mdx
+++ b/docs/content/docs/plugins/subscription.mdx
@@ -147,6 +147,76 @@ route a tenant's billing writes to one of them, or check for an existing subscri
webhook.
+## In React
+
+The client half ships as `@authsome/plugin-subscription`. Add it to your provider the way you added the server plugin to the engine:
+
+```tsx
+import { subscription } from "@authsome/plugin-subscription";
+import { useSubscription, Entitled } from "@authsome/plugin-subscription/react";
+import { PricingTable, CurrentPlanCard } from "@authsome/plugin-subscription/components";
+
+
+
+
+
+function Billing() {
+ const { plan, subscription, changePlan, isPending } = useSubscription();
+ return (
+ <>
+
+
+
+ );
+}
+
+}>
+
+
+```
+
+Everything reading the subscription shares one cache. A write updates it, a sign-out clears it, and switching organization reloads it. `` shows the fallback until it has a positive answer, so loading or an outage never opens a paid feature.
+
+## In Flutter
+
+Two packages: `authsome_subscription` (pure Dart: models and state) and `authsome_subscription_flutter` (widgets).
+
+```dart
+AuthProvider(
+ config: AuthConfig(baseUrl: url, plugins: const [SubscriptionPlugin()]),
+ child: const MyApp(),
+);
+
+const CurrentPlanCard();
+PricingTable(onCheckout: (uri) => launchUrl(uri));
+const EntitlementGate(feature: 'sso', fallback: UpgradePrompt(), child: SsoSettings());
+
+final billing = context.subscription;
+final result = await billing.changePlan('team');
+```
+
+The widgets hand checkout and portal URLs back to you (`onCheckout`, `onOpen`), so the packages don't depend on a URL launcher. On both platforms the components show plain words when a write fails and pass the server's error to `onError`.
+
+`CurrentPlanCard` asks before it cancels and says when the plan ends. If the server doesn't have the subscription plugin, the client packages say so once in the console during development, and every entitlement check fails closed.
+
+The billing methods on the core `ui-core` and `authsome_core` clients still work, and are marked deprecated in favour of these packages.
+
+### Another tenant's billing
+
+Support staff who hold `billing:manage` can look after a customer's billing from the same components. Pass the customer's tenant and every read and write carries it as `tenant_id`:
+
+```tsx
+
+const { subscription } = useSubscription({ tenantId: customer.orgId });
+```
+
+```dart
+CurrentPlanCard(tenantId: customer.orgId);
+final billing = context.subscriptionFor(customer.orgId);
+```
+
+Underneath that's `api.forTenant(id)`, which returns the same API with its own cache. It keeps its tenant when you switch organization and clears when you sign out. The server refuses anyone without `billing:manage`.
+
## Operator routes
Plans, coupons, invoices and the ID-based subscription routes (`/subscriptions/:subId/...`)
diff --git a/flutter/packages/authsome_core/lib/src/generated/api_client.dart b/flutter/packages/authsome_core/lib/src/generated/api_client.dart
index 5a460821..83528f36 100644
--- a/flutter/packages/authsome_core/lib/src/generated/api_client.dart
+++ b/flutter/packages/authsome_core/lib/src/generated/api_client.dart
@@ -1081,6 +1081,7 @@ class AuthClient {
/// List coupons
/// GET /v1/billing/coupons
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future listCoupons({required String appId, required String token}) async {
final path = '/v1/billing/coupons';
// A list of pairs rather than a map, because a query string may carry the
@@ -1101,6 +1102,7 @@ class AuthClient {
/// Create coupon
/// POST /v1/billing/coupons
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future createCoupon({required CreateCouponRequest body, required String token}) async {
final path = '/v1/billing/coupons';
final res = await _request(
@@ -1114,6 +1116,7 @@ class AuthClient {
/// Delete coupon
/// DELETE /v1/billing/coupons/{couponId}
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future deleteCoupon({required String couponId, required String token}) async {
final path = '/v1/billing/coupons/$couponId';
await _request(
@@ -1125,6 +1128,7 @@ class AuthClient {
/// List your entitlements
/// GET /v1/billing/entitlements
+ @Deprecated('Use the authsome_subscription package instead.')
Future listEntitlements({required String token, String? tenantId}) async {
final path = '/v1/billing/entitlements';
// A list of pairs rather than a map, because a query string may carry the
@@ -1145,6 +1149,7 @@ class AuthClient {
/// Check feature entitlement
/// GET /v1/billing/entitlements/{featureKey}
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future checkEntitlement({required String featureKey, required String tenantId, required String token, String? appId}) async {
final path = '/v1/billing/entitlements/$featureKey';
// A list of pairs rather than a map, because a query string may carry the
@@ -1166,6 +1171,7 @@ class AuthClient {
/// List invoices
/// GET /v1/billing/invoices
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future listInvoices({required String appId, required String tenantId, required String token}) async {
final path = '/v1/billing/invoices';
// A list of pairs rather than a map, because a query string may carry the
@@ -1187,6 +1193,7 @@ class AuthClient {
/// Get invoice
/// GET /v1/billing/invoices/{invoiceId}
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future getInvoice({required String invoiceId, required String token}) async {
final path = '/v1/billing/invoices/$invoiceId';
final res = await _request(
@@ -1199,6 +1206,7 @@ class AuthClient {
/// Mark invoice as paid
/// POST /v1/billing/invoices/{invoiceId}/pay
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future markInvoicePaid({required String invoiceId, required MarkInvoicePaidRequest body, required String token}) async {
final path = '/v1/billing/invoices/$invoiceId/pay';
await _request(
@@ -1211,6 +1219,7 @@ class AuthClient {
/// Void an invoice
/// POST /v1/billing/invoices/{invoiceId}/void
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future voidInvoice({required String invoiceId, required VoidInvoiceRequest body, required String token}) async {
final path = '/v1/billing/invoices/$invoiceId/void';
await _request(
@@ -1223,6 +1232,7 @@ class AuthClient {
/// List billing plans
/// GET /v1/billing/plans
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future listBillingPlans({required String appId, required String token, String? status, bool? includeAddons}) async {
final path = '/v1/billing/plans';
// A list of pairs rather than a map, because a query string may carry the
@@ -1245,6 +1255,7 @@ class AuthClient {
/// Create billing plan
/// POST /v1/billing/plans
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future createBillingPlan({required CreatePlanRequest body, required String token}) async {
final path = '/v1/billing/plans';
final res = await _request(
@@ -1258,6 +1269,7 @@ class AuthClient {
/// Get billing plan
/// GET /v1/billing/plans/{planId}
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future getBillingPlan({required String planId, required String token}) async {
final path = '/v1/billing/plans/$planId';
final res = await _request(
@@ -1270,6 +1282,7 @@ class AuthClient {
/// Activate a billing plan
/// POST /v1/billing/plans/{planId}/activate
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future activateBillingPlan({required String planId, required String token}) async {
final path = '/v1/billing/plans/$planId/activate';
await _request(
@@ -1281,6 +1294,7 @@ class AuthClient {
/// Archive a billing plan
/// POST /v1/billing/plans/{planId}/archive
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future archiveBillingPlan({required String planId, required String token}) async {
final path = '/v1/billing/plans/$planId/archive';
await _request(
@@ -1292,6 +1306,7 @@ class AuthClient {
/// Open the billing portal
/// POST /v1/billing/portal
+ @Deprecated('Use the authsome_subscription package instead.')
Future createBillingPortalSession({required PortalRequest body, required String token}) async {
final path = '/v1/billing/portal';
final res = await _request(
@@ -1305,6 +1320,7 @@ class AuthClient {
/// Get your subscription
/// GET /v1/billing/subscription
+ @Deprecated('Use the authsome_subscription package instead.')
Future getCurrentSubscription({required String token, String? tenantId}) async {
final path = '/v1/billing/subscription';
// A list of pairs rather than a map, because a query string may carry the
@@ -1325,6 +1341,7 @@ class AuthClient {
/// Subscribe to a plan
/// POST /v1/billing/subscription
+ @Deprecated('Use the authsome_subscription package instead.')
Future subscribe({required SubscribeRequest body, required String token}) async {
final path = '/v1/billing/subscription';
final res = await _request(
@@ -1338,6 +1355,7 @@ class AuthClient {
/// Change plan or seats
/// PATCH /v1/billing/subscription
+ @Deprecated('Use the authsome_subscription package instead.')
Future updateSubscription({required UpdateSubscriptionRequest body, required String token}) async {
final path = '/v1/billing/subscription';
final res = await _request(
@@ -1351,6 +1369,7 @@ class AuthClient {
/// Cancel your subscription
/// POST /v1/billing/subscription/cancel
+ @Deprecated('Use the authsome_subscription package instead.')
Future cancelCurrentSubscription({required CancelCurrentRequest body, required String token}) async {
final path = '/v1/billing/subscription/cancel';
final res = await _request(
@@ -1364,6 +1383,7 @@ class AuthClient {
/// Keep your subscription
/// POST /v1/billing/subscription/resume
+ @Deprecated('Use the authsome_subscription package instead.')
Future resumeCurrentSubscription({required TenantRequest body, required String token}) async {
final path = '/v1/billing/subscription/resume';
final res = await _request(
@@ -1377,6 +1397,7 @@ class AuthClient {
/// List subscriptions
/// GET /v1/billing/subscriptions
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future listSubscriptions({required String appId, required String tenantId, required String token, String? status}) async {
final path = '/v1/billing/subscriptions';
// A list of pairs rather than a map, because a query string may carry the
@@ -1399,6 +1420,7 @@ class AuthClient {
/// Create subscription
/// POST /v1/billing/subscriptions
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future createSubscription({required CreateSubscriptionRequest body, required String token}) async {
final path = '/v1/billing/subscriptions';
final res = await _request(
@@ -1412,6 +1434,7 @@ class AuthClient {
/// Get active subscription
/// GET /v1/billing/subscriptions/active
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future getActiveSubscription({required String appId, required String tenantId, required String token}) async {
final path = '/v1/billing/subscriptions/active';
// A list of pairs rather than a map, because a query string may carry the
@@ -1433,6 +1456,7 @@ class AuthClient {
/// Cancel subscription
/// POST /v1/billing/subscriptions/{subId}/cancel
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future cancelSubscription({required String subId, required CancelSubscriptionRequest body, required String token}) async {
final path = '/v1/billing/subscriptions/$subId/cancel';
await _request(
@@ -1445,6 +1469,7 @@ class AuthClient {
/// Change subscription plan
/// POST /v1/billing/subscriptions/{subId}/change-plan
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future changeSubscriptionPlan({required String subId, required ChangePlanRequest body, required String token}) async {
final path = '/v1/billing/subscriptions/$subId/change-plan';
await _request(
@@ -1457,6 +1482,7 @@ class AuthClient {
/// Pause subscription
/// POST /v1/billing/subscriptions/{subId}/pause
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future pauseSubscription({required String subId, required String token}) async {
final path = '/v1/billing/subscriptions/$subId/pause';
await _request(
@@ -1468,6 +1494,7 @@ class AuthClient {
/// Resume subscription
/// POST /v1/billing/subscriptions/{subId}/resume
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future resumeSubscription({required String subId, required String token}) async {
final path = '/v1/billing/subscriptions/$subId/resume';
await _request(
@@ -1479,6 +1506,7 @@ class AuthClient {
/// Get usage summary
/// GET /v1/billing/usage
+ @Deprecated('Operator route. Call it from your server with the authsome Dart SDK, or use authsome_subscription for tenant billing.')
Future getUsageSummary({required String appId, required String tenantId, required String token}) async {
final path = '/v1/billing/usage';
// A list of pairs rather than a map, because a query string may carry the
diff --git a/flutter/packages/authsome_subscription/CHANGELOG.md b/flutter/packages/authsome_subscription/CHANGELOG.md
new file mode 100644
index 00000000..62094844
--- /dev/null
+++ b/flutter/packages/authsome_subscription/CHANGELOG.md
@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.6.1
+
+- First release.
diff --git a/flutter/packages/authsome_subscription/LICENSE b/flutter/packages/authsome_subscription/LICENSE
new file mode 100644
index 00000000..ba6a044b
--- /dev/null
+++ b/flutter/packages/authsome_subscription/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/flutter/packages/authsome_subscription/README.md b/flutter/packages/authsome_subscription/README.md
new file mode 100644
index 00000000..124a6dde
--- /dev/null
+++ b/flutter/packages/authsome_subscription/README.md
@@ -0,0 +1,47 @@
+# authsome_subscription
+
+The client half of authsome's `subscription` plugin, for Dart and Flutter. You get the tenant's subscription, its plan, seats and feature checks as typed models, and a stream of changes. For widgets, add [`authsome_subscription_flutter`](https://pub.dev/packages/authsome_subscription_flutter).
+
+```yaml
+dependencies:
+ authsome_core: ^1.6.1
+ authsome_subscription: ^1.6.1
+```
+
+The server needs the plugin too: `authsome.WithPlugin(subscription.New(...))`.
+
+## Usage
+
+```dart
+final auth = AuthManager(AuthConfig(
+ baseUrl: 'https://api.example.com',
+ plugins: const [SubscriptionPlugin()],
+));
+await auth.initialize();
+
+final billing = auth.plugin();
+await billing.load();
+
+final sub = billing.snapshot.subscription.data;
+if (sub != null && sub.willCancel) {
+ print('${sub.plan.name} ends on ${sub.cancelAt}');
+}
+```
+
+Writes update the snapshot, so anything listening to `billing.changes` sees the new state:
+
+```dart
+final result = await billing.changePlan('team');
+switch (result) {
+ case SubscriptionChanged(:final subscription):
+ print('now on ${subscription.plan.name}');
+ case CheckoutRequired(:final url):
+ await launchUrl(url); // payment first; nothing changed yet
+}
+```
+
+`cancel()` cancels at the end of the period unless you pass `when: CancelWhen.now`, and `resume()` takes that back. `billing.entitlement('sso')` reads the cached check for a feature.
+
+The snapshot follows the session: signing out clears it, and signing in or switching organization reloads it. When the server doesn't have the subscription plugin, the resources come back `ResourceStatus.unavailable` without a request, and debug builds print one warning saying so.
+
+`billing.forTenant(orgId)` returns the same API pinned to another tenant, with its own cache, for support staff who hold `billing:manage`. It keeps its tenant across organization switches and clears on sign-out.
diff --git a/flutter/packages/authsome_subscription/analysis_options.yaml b/flutter/packages/authsome_subscription/analysis_options.yaml
new file mode 100644
index 00000000..5cb95a45
--- /dev/null
+++ b/flutter/packages/authsome_subscription/analysis_options.yaml
@@ -0,0 +1,7 @@
+include: package:lints/recommended.yaml
+
+linter:
+ rules:
+ prefer_single_quotes: true
+ sort_constructors_first: false
+ avoid_dynamic_calls: false
diff --git a/flutter/packages/authsome_subscription/lib/authsome_subscription.dart b/flutter/packages/authsome_subscription/lib/authsome_subscription.dart
new file mode 100644
index 00000000..af3d8917
--- /dev/null
+++ b/flutter/packages/authsome_subscription/lib/authsome_subscription.dart
@@ -0,0 +1,16 @@
+/// The client half of authsome's subscription plugin.
+///
+/// ```dart
+/// final auth = AuthManager(AuthConfig(
+/// baseUrl: 'https://api.example.com',
+/// plugins: [SubscriptionPlugin()],
+/// ));
+/// final billing = auth.plugin();
+/// await billing.load();
+/// ```
+///
+/// Flutter widgets are in `authsome_subscription_flutter`.
+library authsome_subscription;
+
+export 'src/models.dart';
+export 'src/subscription_api.dart';
diff --git a/flutter/packages/authsome_subscription/lib/src/models.dart b/flutter/packages/authsome_subscription/lib/src/models.dart
new file mode 100644
index 00000000..200db0c4
--- /dev/null
+++ b/flutter/packages/authsome_subscription/lib/src/models.dart
@@ -0,0 +1,265 @@
+/// Typed models for the subscription plugin, mapped from the server's JSON.
+library;
+
+/// A subscription's state. A value from a newer server reads as [unknown].
+enum SubscriptionStatus {
+ active,
+ trialing,
+ pastDue,
+ canceled,
+ expired,
+ paused,
+ unknown;
+
+ /// Parses the server's snake_case status.
+ static SubscriptionStatus parse(String value) => switch (value) {
+ 'active' => active,
+ 'trialing' => trialing,
+ 'past_due' => pastDue,
+ 'canceled' => canceled,
+ 'expired' => expired,
+ 'paused' => paused,
+ _ => unknown,
+ };
+}
+
+/// Currencies the ledger stores without a minor unit. It stores every other
+/// currency with two places, so this list has to match the ledger's, not ISO 4217.
+const _zeroDecimal = {'jpy', 'krw', 'vnd', 'clp', 'pyg', 'idr'};
+
+const _symbols = {'usd': r'$', 'eur': '€', 'gbp': '£', 'jpy': '¥', 'inr': '₹', 'cad': r'CA$', 'aud': r'A$'};
+
+/// An amount in the currency's minor unit (cents for usd).
+class Money {
+ const Money({required this.amountMinor, required this.currency});
+
+ final int amountMinor;
+ final String currency;
+
+ /// Decimal places the currency uses.
+ int get decimals => _zeroDecimal.contains(currency.toLowerCase()) ? 0 : 2;
+
+ /// The amount in major units, e.g. 29.0 for 2900 usd cents.
+ double get major => decimals == 0 ? amountMinor.toDouble() : amountMinor / 100;
+
+ /// A plain rendering such as `$29.00` or `NGN 10.50`. Use your own
+ /// NumberFormat for locale-aware output; [major] and [currency] are there
+ /// for that.
+ String format() {
+ // Integer arithmetic, so a large amount doesn't pick up float rounding.
+ final abs = amountMinor.abs();
+ final amount = decimals == 0
+ ? '$abs'
+ : '${abs ~/ 100}.${(abs % 100).toString().padLeft(2, '0')}';
+ final sign = amountMinor < 0 ? '-' : '';
+ final symbol = _symbols[currency.toLowerCase()];
+ return symbol != null ? '$sign$symbol$amount' : '$sign${currency.toUpperCase()} $amount';
+ }
+}
+
+/// A plan's base price and how often it's charged.
+class Price extends Money {
+ const Price({required super.amountMinor, required super.currency, required this.interval});
+
+ /// "monthly", "yearly", ... as the server names it.
+ final String interval;
+}
+
+/// One feature a plan includes. A null [limit] means unlimited.
+class PlanFeature {
+ const PlanFeature({
+ required this.key,
+ required this.name,
+ required this.type,
+ required this.limit,
+ required this.softLimit,
+ this.period,
+ });
+
+ final String key;
+ final String name;
+
+ /// "boolean", "metered" or "seat".
+ final String type;
+ final int? limit;
+ final String? period;
+ final bool softLimit;
+
+ factory PlanFeature.fromJson(Map json) => PlanFeature(
+ key: json['key'] as String,
+ name: json['name'] as String,
+ type: json['type'] as String,
+ limit: (json['limit'] as num?)?.toInt(),
+ period: json['period'] as String?,
+ softLimit: json['soft_limit'] as bool? ?? false,
+ );
+}
+
+class Plan {
+ const Plan({
+ required this.id,
+ required this.slug,
+ required this.name,
+ required this.description,
+ required this.status,
+ required this.trialDays,
+ required this.isAddon,
+ required this.price,
+ required this.features,
+ required this.metadata,
+ });
+
+ final String id;
+ final String slug;
+ final String name;
+ final String description;
+ final String status;
+ final int trialDays;
+ final bool isAddon;
+
+ /// Null for a plan without a price.
+ final Price? price;
+ final List features;
+ final Map metadata;
+
+ factory Plan.fromJson(Map json) {
+ final amount = json['amount_minor'] as num?;
+ return Plan(
+ id: json['id'] as String,
+ slug: json['slug'] as String,
+ name: json['name'] as String,
+ description: json['description'] as String? ?? '',
+ status: json['status'] as String,
+ trialDays: (json['trial_days'] as num?)?.toInt() ?? 0,
+ isAddon: json['is_addon'] as bool? ?? false,
+ price: amount == null
+ ? null
+ : Price(
+ amountMinor: amount.toInt(),
+ currency: json['currency'] as String,
+ interval: json['billing_period'] as String? ?? '',
+ ),
+ features: [
+ for (final f in (json['features'] as List? ?? const []))
+ PlanFeature.fromJson(Map.from(f as Map)),
+ ],
+ metadata: Map.from(json['metadata'] as Map? ?? const {}),
+ );
+ }
+}
+
+/// Seat use on a plan with a seat feature. A null [limit] means unlimited.
+class Seats {
+ const Seats({required this.featureKey, required this.used, required this.limit});
+
+ final String featureKey;
+ final int used;
+ final int? limit;
+}
+
+class Subscription {
+ const Subscription({
+ required this.id,
+ required this.tenantId,
+ required this.status,
+ required this.plan,
+ required this.currentPeriodStart,
+ required this.currentPeriodEnd,
+ this.trialStart,
+ this.trialEnd,
+ this.cancelAt,
+ this.canceledAt,
+ this.pausedAt,
+ this.seats,
+ });
+
+ final String id;
+ final String tenantId;
+ final SubscriptionStatus status;
+ final Plan plan;
+ final DateTime currentPeriodStart;
+ final DateTime currentPeriodEnd;
+ final DateTime? trialStart;
+ final DateTime? trialEnd;
+
+ /// When a cancellation scheduled for the period end takes effect.
+ final DateTime? cancelAt;
+ final DateTime? canceledAt;
+ final DateTime? pausedAt;
+ final Seats? seats;
+
+ /// The tenant has the plan's features: active, trialing, or past due.
+ bool get isActive =>
+ status == SubscriptionStatus.active ||
+ status == SubscriptionStatus.trialing ||
+ status == SubscriptionStatus.pastDue;
+ bool get isTrialing => status == SubscriptionStatus.trialing;
+ bool get isPaused => status == SubscriptionStatus.paused;
+
+ /// A cancellation is scheduled; the plan runs until [cancelAt].
+ bool get willCancel => cancelAt != null;
+
+ /// Whole days of trial left, null when not trialing.
+ int? get trialDaysLeft {
+ final end = trialEnd;
+ if (!isTrialing || end == null) return null;
+ final left = end.difference(DateTime.now()).inMilliseconds / Duration.millisecondsPerDay;
+ return left <= 0 ? 0 : left.ceil();
+ }
+
+ factory Subscription.fromJson(Map json) {
+ DateTime? date(String key) {
+ final v = json[key] as String?;
+ return v == null ? null : DateTime.parse(v);
+ }
+
+ final seats = json['seats'] as Map?;
+ return Subscription(
+ id: json['id'] as String,
+ tenantId: json['tenant_id'] as String,
+ status: SubscriptionStatus.parse(json['status'] as String),
+ plan: Plan.fromJson(Map.from(json['plan'] as Map)),
+ currentPeriodStart: DateTime.parse(json['current_period_start'] as String),
+ currentPeriodEnd: DateTime.parse(json['current_period_end'] as String),
+ trialStart: date('trial_start'),
+ trialEnd: date('trial_end'),
+ cancelAt: date('cancel_at'),
+ canceledAt: date('canceled_at'),
+ pausedAt: date('paused_at'),
+ seats: seats == null
+ ? null
+ : Seats(
+ featureKey: seats['feature_key'] as String,
+ used: (seats['used'] as num).toInt(),
+ limit: (seats['limit'] as num?)?.toInt(),
+ ),
+ );
+ }
+}
+
+/// Whether the tenant may use a feature, and how much of it is left.
+class Entitlement {
+ const Entitlement({
+ required this.allowed,
+ required this.used,
+ required this.limit,
+ required this.remaining,
+ this.reason,
+ });
+
+ final bool allowed;
+ final int used;
+
+ /// Negative means unlimited, as ledger reports it.
+ final int limit;
+ final int remaining;
+ final String? reason;
+
+ factory Entitlement.fromJson(Map json) => Entitlement(
+ allowed: json['allowed'] as bool,
+ used: (json['used'] as num).toInt(),
+ limit: (json['limit'] as num).toInt(),
+ remaining: (json['remaining'] as num).toInt(),
+ reason: json['reason'] as String?,
+ );
+}
diff --git a/flutter/packages/authsome_subscription/lib/src/subscription_api.dart b/flutter/packages/authsome_subscription/lib/src/subscription_api.dart
new file mode 100644
index 00000000..7fd6d6fc
--- /dev/null
+++ b/flutter/packages/authsome_subscription/lib/src/subscription_api.dart
@@ -0,0 +1,377 @@
+import 'dart:async';
+
+import 'package:authsome_core/authsome_core.dart';
+
+import 'models.dart';
+
+/// Where a piece of server state is. [unavailable] means the server doesn't
+/// have the subscription plugin installed; treat it like a plan without
+/// the feature.
+enum ResourceStatus { idle, loading, ready, error, unavailable }
+
+/// One piece of server state.
+class Resource {
+ const Resource(this.status, this.data, [this.error]);
+
+ final ResourceStatus status;
+ final T data;
+ final Object? error;
+
+ bool get isLoading => status == ResourceStatus.loading;
+}
+
+/// Everything the plugin knows, as one immutable snapshot.
+class SubscriptionSnapshot {
+ const SubscriptionSnapshot({
+ required this.subscription,
+ required this.canManage,
+ required this.plans,
+ required this.entitlements,
+ });
+
+ SubscriptionSnapshot.initial()
+ : subscription = const Resource(ResourceStatus.idle, null),
+ canManage = false,
+ plans = const Resource(ResourceStatus.idle, []),
+ entitlements = const Resource(ResourceStatus.idle, {});
+
+ /// The tenant's subscription; data is null when it has none.
+ final Resource subscription;
+
+ /// Whether the signed-in user may change the subscription.
+ final bool canManage;
+
+ /// Plans the tenant can buy, cheapest first.
+ final Resource> plans;
+
+ /// Every feature on the current plan, checked.
+ final Resource> entitlements;
+
+ SubscriptionSnapshot copyWith({
+ Resource? subscription,
+ bool? canManage,
+ Resource>? plans,
+ Resource>? entitlements,
+ }) =>
+ SubscriptionSnapshot(
+ subscription: subscription ?? this.subscription,
+ canManage: canManage ?? this.canManage,
+ plans: plans ?? this.plans,
+ entitlements: entitlements ?? this.entitlements,
+ );
+}
+
+/// What a plan or seat change did.
+sealed class ChangeResult {
+ const ChangeResult();
+}
+
+/// The change happened; here's the subscription now.
+class SubscriptionChanged extends ChangeResult {
+ const SubscriptionChanged(this.subscription);
+ final Subscription subscription;
+}
+
+/// Payment comes first: send the customer to [url]. Nothing changed yet.
+class CheckoutRequired extends ChangeResult {
+ const CheckoutRequired(this.url);
+ final Uri url;
+}
+
+/// When a cancellation takes effect.
+enum CancelWhen { periodEnd, now }
+
+// State every scope of one plugin instance shares.
+class _Shared {
+ final scopes = {};
+ bool warned = false;
+}
+
+const _unavailableWarning =
+ "authsome: the server doesn't have the subscription plugin, so billing reads as "
+ 'unavailable and every entitlement check fails closed. Register it on the server with '
+ 'authsome.WithPlugin(subscription.New(...)), or drop SubscriptionPlugin from your client plugins.';
+
+/// The subscription plugin's API, from `auth.plugin()` or,
+/// in Flutter, `context.subscription`.
+class SubscriptionApi {
+ SubscriptionApi(PluginContext ctx) : this._scoped(ctx, null, _Shared());
+
+ SubscriptionApi._scoped(this._ctx, this.tenantId, this._shared) {
+ // Follow the session: a sign-out forgets everything, and a sign-in or
+ // an organization switch reloads whatever had been loaded.
+ _events = _ctx.events.listen(
+ (event) {
+ switch (event) {
+ case AuthEvent.signedOut:
+ _generation++;
+ _set(SubscriptionSnapshot.initial());
+ case AuthEvent.signedIn:
+ _reload();
+ // A pinned tenant doesn't change with the organization.
+ case AuthEvent.orgChanged:
+ if (tenantId == null) _reload();
+ case AuthEvent.sessionRefreshed:
+ break;
+ }
+ },
+ // The manager closes its events when it's disposed; nothing will
+ // change after that, so neither does this stream.
+ onDone: () => unawaited(_changes.close()),
+ );
+ }
+
+ final PluginContext _ctx;
+ final _Shared _shared;
+
+ /// The tenant this API is pinned to, or null for the session's own (its
+ /// active organization, or the user in user mode).
+ final String? tenantId;
+
+ late final StreamSubscription _events;
+ final _changes = StreamController.broadcast();
+ SubscriptionSnapshot _snapshot = SubscriptionSnapshot.initial();
+
+ // Bumped whenever the session or organization changes, so a response for
+ // the one the user just left is dropped instead of shown.
+ int _generation = 0;
+
+ // The load in flight for the current generation, shared by every caller.
+ ({int gen, Future future})? _loading;
+
+ /// The current snapshot.
+ SubscriptionSnapshot get snapshot => _snapshot;
+
+ /// Every new snapshot.
+ Stream get changes => _changes.stream;
+
+ void _set(SubscriptionSnapshot next) {
+ _snapshot = next;
+ if (!_changes.isClosed) _changes.add(next);
+ }
+
+ /// The same API for another tenant, with its own cache. For operators who
+ /// hold billing:manage and look after customers' billing; the server
+ /// refuses anyone else. Calling it twice with one ID returns one instance.
+ SubscriptionApi forTenant(String tenantId) =>
+ _shared.scopes.putIfAbsent(tenantId, () => SubscriptionApi._scoped(_ctx, tenantId, _shared));
+
+ // A pinned scope names its tenant on every request; the session's scope
+ // leaves it to the server.
+ Map? get _query => tenantId == null ? null : {'tenant_id': tenantId!};
+ Map _scoped(Map body) =>
+ tenantId == null ? body : {...body, 'tenant_id': tenantId};
+
+ bool get _unavailable {
+ if (_ctx.isServerEnabled != false) return false;
+ if (!_shared.warned) {
+ _shared.warned = true;
+ // Debug builds only: asserts are stripped from release builds.
+ assert(() {
+ // ignore: avoid_print
+ print(_unavailableWarning);
+ return true;
+ }());
+ }
+ return true;
+ }
+ bool get _signedIn => _ctx.state is AuthAuthenticated;
+
+ // A new session or organization: whatever was shown belongs to the old
+ // one, so clear it before anyone can act on it, then load again.
+ void _reload() {
+ _generation++;
+ if (_snapshot.subscription.status == ResourceStatus.idle) return;
+ _set(_snapshot.copyWith(
+ subscription: const Resource(ResourceStatus.loading, null),
+ entitlements: const Resource(ResourceStatus.loading, {}),
+ canManage: false,
+ ));
+ unawaited(load());
+ }
+
+ /// Loads the subscription and its entitlements. Calls made while a load
+ /// is running share it.
+ Future load() {
+ final current = _loading;
+ if (current != null && current.gen == _generation) return current.future;
+ final gen = _generation;
+ final future = _load(gen).whenComplete(() {
+ if (_loading?.gen == gen) _loading = null;
+ });
+ _loading = (gen: gen, future: future);
+ return future;
+ }
+
+ Future _load(int gen) async {
+ if (_unavailable) {
+ _set(_snapshot.copyWith(
+ subscription: const Resource(ResourceStatus.unavailable, null),
+ entitlements: const Resource(ResourceStatus.unavailable, {}),
+ ));
+ return;
+ }
+ if (!_signedIn) return;
+ _set(_snapshot.copyWith(
+ subscription: Resource(ResourceStatus.loading, _snapshot.subscription.data),
+ ));
+ final entitlements = _loadEntitlements(gen);
+ try {
+ final res = await _ctx.request('GET', '/v1/billing/subscription', query: _query) as Map;
+ if (gen != _generation) return;
+ final sub = res['subscription'] as Map?;
+ _set(_snapshot.copyWith(
+ subscription: Resource(
+ ResourceStatus.ready,
+ sub == null ? null : Subscription.fromJson(Map.from(sub)),
+ ),
+ canManage: res['can_manage'] as bool? ?? false,
+ ));
+ } catch (error) {
+ if (gen != _generation) return;
+ _set(_snapshot.copyWith(
+ subscription: Resource(ResourceStatus.error, _snapshot.subscription.data, error),
+ ));
+ }
+ await entitlements;
+ }
+
+ Future _loadEntitlements(int gen) async {
+ if (gen != _generation) return;
+ _set(_snapshot.copyWith(
+ entitlements: Resource(ResourceStatus.loading, _snapshot.entitlements.data),
+ ));
+ try {
+ final res = await _ctx.request('GET', '/v1/billing/entitlements', query: _query) as Map;
+ if (gen != _generation) return;
+ final raw = Map.from(res['entitlements'] as Map? ?? const {});
+ _set(_snapshot.copyWith(
+ entitlements: Resource(ResourceStatus.ready, {
+ for (final e in raw.entries)
+ e.key: Entitlement.fromJson(Map.from(e.value as Map)),
+ }),
+ ));
+ } catch (error) {
+ if (gen != _generation) return;
+ _set(_snapshot.copyWith(
+ entitlements: Resource(ResourceStatus.error, _snapshot.entitlements.data, error),
+ ));
+ }
+ }
+
+ /// Loads the plans the tenant can buy.
+ Future loadPlans() async {
+ if (_unavailable) {
+ _set(_snapshot.copyWith(plans: const Resource(ResourceStatus.unavailable, [])));
+ return;
+ }
+ // /plans is app-wide and wants the app's ID: the client config carries
+ // it, and so does the signed-in user.
+ final state = _ctx.state;
+ final user = state is AuthAuthenticated ? state.user : null;
+ final appId = _ctx.clientConfig?.appId ?? (user is User ? user.appId : null);
+ final gen = _generation;
+ _set(_snapshot.copyWith(plans: Resource(ResourceStatus.loading, _snapshot.plans.data)));
+ try {
+ final res = await _ctx.request('GET', '/v1/billing/plans', query: {'app_id': appId}) as Map;
+ if (gen != _generation) return;
+ _set(_snapshot.copyWith(
+ plans: Resource(ResourceStatus.ready, [
+ for (final p in (res['plans'] as List? ?? const []))
+ Plan.fromJson(Map.from(p as Map)),
+ ]),
+ ));
+ } catch (error) {
+ if (gen != _generation) return;
+ _set(_snapshot.copyWith(plans: Resource(ResourceStatus.error, _snapshot.plans.data, error)));
+ }
+ }
+
+ /// Starts a subscription on a plan, by slug or ID.
+ Future subscribe(String plan, {int? seats, String? returnUrl, String? cancelUrl}) =>
+ _change('POST', _body({'plan': plan}, seats, returnUrl, cancelUrl));
+
+ /// Moves the subscription to another plan, by slug or ID.
+ Future changePlan(String plan, {int? seats, String? returnUrl, String? cancelUrl}) =>
+ _change('PATCH', _body({'plan': plan}, seats, returnUrl, cancelUrl));
+
+ /// Changes the seat count on the current plan.
+ Future setSeats(int seats, {String? returnUrl, String? cancelUrl}) =>
+ _change('PATCH', _body({}, seats, returnUrl, cancelUrl));
+
+ /// Cancels at the end of the period (the default) or now.
+ Future cancel({CancelWhen when = CancelWhen.periodEnd}) => _mutate(
+ '/v1/billing/subscription/cancel',
+ {'when': when == CancelWhen.now ? 'now' : 'period_end'},
+ );
+
+ /// Takes back a cancellation scheduled for the end of the period.
+ Future resume() => _mutate('/v1/billing/subscription/resume', {});
+
+ /// A link to the payment provider's billing portal.
+ Future openPortal({String? returnUrl}) async {
+ final res = await _ctx.request('POST', '/v1/billing/portal',
+ body: _scoped({if (returnUrl != null) 'return_url': returnUrl})) as Map;
+ return Uri.parse(res['url'] as String);
+ }
+
+ /// The cached check for a feature, null when it isn't on the plan or not loaded.
+ Entitlement? entitlement(String feature) => _snapshot.entitlements.data[feature];
+
+ Map _body(Map base, int? seats, String? returnUrl, String? cancelUrl) => {
+ ...base,
+ if (seats != null) 'seats': seats,
+ if (returnUrl != null) 'return_url': returnUrl,
+ if (cancelUrl != null) 'cancel_url': cancelUrl,
+ };
+
+ Future _change(String method, Map body) async {
+ final gen = _generation;
+ final res = await _ctx.request(method, '/v1/billing/subscription', body: _scoped(body)) as Map;
+ final url = res['checkout_url'] as String?;
+ if (url != null && url.isNotEmpty) return CheckoutRequired(Uri.parse(url));
+ return SubscriptionChanged(_commit(res, gen));
+ }
+
+ Future _mutate(String path, Map body) async {
+ final gen = _generation;
+ final res = await _ctx.request('POST', path, body: _scoped(body)) as Map;
+ return _commit(res, gen);
+ }
+
+ // Writes answer with the new subscription. It goes straight into the
+ // cache, and the entitlements are rechecked since the plan may have moved.
+ // A write that lands after the user switched org or signed out still
+ // returns its result, but the cache now belongs to someone else.
+ Subscription _commit(Map res, int gen) {
+ final json = res['subscription'] as Map?;
+ if (json == null) {
+ throw StateError('authsome: the server answered without a subscription');
+ }
+ final sub = Subscription.fromJson(Map.from(json));
+ if (gen == _generation) {
+ _set(_snapshot.copyWith(subscription: Resource(ResourceStatus.ready, sub)));
+ unawaited(_loadEntitlements(gen));
+ }
+ return sub;
+ }
+
+ /// Stops following the session. The plugin's manager calls nothing on
+ /// dispose today, so this is for tests and long-lived isolates.
+ Future close() async {
+ await _events.cancel();
+ if (!_changes.isClosed) await _changes.close();
+ }
+}
+
+/// The subscription client plugin. Register it in [AuthConfig.plugins] and
+/// read it with `auth.plugin()`.
+class SubscriptionPlugin extends AuthPlugin {
+ const SubscriptionPlugin();
+
+ @override
+ String get name => 'subscription';
+
+ @override
+ SubscriptionApi init(PluginContext ctx) => SubscriptionApi(ctx);
+}
diff --git a/flutter/packages/authsome_subscription/pubspec.yaml b/flutter/packages/authsome_subscription/pubspec.yaml
new file mode 100644
index 00000000..5d084cd2
--- /dev/null
+++ b/flutter/packages/authsome_subscription/pubspec.yaml
@@ -0,0 +1,19 @@
+name: authsome_subscription
+description: Client plugin for authsome's subscription plugin. Plans, subscriptions, seats and entitlements for Dart and Flutter apps.
+version: 1.6.1
+homepage: https://github.com/xraph/authsome
+repository: https://github.com/xraph/authsome/tree/main/flutter/packages/authsome_subscription
+issue_tracker: https://github.com/xraph/authsome/issues
+
+environment:
+ sdk: ^3.6.0
+
+resolution: workspace
+
+dependencies:
+ authsome_core: ^1.6.1
+
+dev_dependencies:
+ http: ^1.2.0
+ lints: ^4.0.0
+ test: ^1.25.0
diff --git a/flutter/packages/authsome_subscription/test/subscription_api_test.dart b/flutter/packages/authsome_subscription/test/subscription_api_test.dart
new file mode 100644
index 00000000..a8c4b866
--- /dev/null
+++ b/flutter/packages/authsome_subscription/test/subscription_api_test.dart
@@ -0,0 +1,455 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:authsome_core/authsome_core.dart';
+import 'package:authsome_subscription/authsome_subscription.dart';
+import 'package:http/http.dart' as http;
+import 'package:http/testing.dart';
+import 'package:test/test.dart';
+
+Map planJson(String slug, [Map overrides = const {}]) => {
+ 'id': 'plan_$slug',
+ 'name': '${slug[0].toUpperCase()}${slug.substring(1)}',
+ 'slug': slug,
+ 'description': '',
+ 'currency': 'usd',
+ 'status': 'active',
+ 'trial_days': 0,
+ 'features_count': 1,
+ 'is_addon': false,
+ 'app_id': 'app_1',
+ 'base_amount': '29.00',
+ 'billing_period': 'monthly',
+ 'amount_minor': 2900,
+ 'features': [
+ {'key': 'sso', 'name': 'SSO', 'type': 'boolean', 'limit': 1, 'soft_limit': false},
+ ],
+ ...overrides,
+ };
+
+Map subJson([Map overrides = const {}]) => {
+ 'id': 'sub_1',
+ 'tenant_id': 'org_1',
+ 'status': 'active',
+ 'plan': planJson('pro'),
+ 'current_period_start': '2026-11-01T00:00:00Z',
+ 'current_period_end': '2026-12-01T00:00:00Z',
+ 'trial_start': null,
+ 'trial_end': null,
+ 'cancel_at': null,
+ 'canceled_at': null,
+ 'paused_at': null,
+ 'app_id': 'app_1',
+ ...overrides,
+ };
+
+final _me = {
+ 'id': 'usr_1',
+ 'app_id': 'app_user',
+ 'env_id': 'env_1',
+ 'email': 'a@test',
+ 'email_verified': true,
+ 'first_name': 'A',
+ 'last_name': 'B',
+ 'banned': false,
+ 'phone_verified': false,
+ 'roles': [],
+ 'active_org_id': 'org_1',
+ 'created_at': '2026-01-01T00:00:00Z',
+ 'updated_at': '2026-01-01T00:00:00Z',
+};
+
+typedef Handler = FutureOr Function(http.Request req);
+
+http.Response _json(Object? body, [int status = 200]) => http.Response(jsonEncode(body), status);
+
+({AuthManager manager, Map routes, List calls, SubscriptionApi Function() api})
+ _setup({List? serverPlugins, String? configAppId}) {
+ final routes = {
+ 'GET /v1/me': (_) => _json(_me),
+ 'POST /v1/signout': (_) => _json({'status': 'ok'}),
+ 'GET /v1/billing/subscription': (_) => _json({'subscription': subJson(), 'can_manage': true}),
+ 'GET /v1/billing/entitlements': (_) => _json({
+ 'entitlements': {
+ 'sso': {'allowed': true, 'feature': 'sso', 'used': 0, 'limit': 1, 'remaining': 1},
+ },
+ }),
+ };
+ final calls = [];
+ final storage = MemoryTokenStorage()
+ ..setItem('authsome:session', jsonEncode({
+ 'session_token': 'tok',
+ 'refresh_token': 'ref',
+ 'expires_at': DateTime.now().add(const Duration(hours: 1)).toUtc().toIso8601String(),
+ }));
+ final manager = AuthManager(AuthConfig(
+ baseUrl: 'https://api.test',
+ storage: storage,
+ plugins: [SubscriptionPlugin()],
+ initialClientConfig: serverPlugins == null && configAppId == null
+ ? null
+ : ClientConfig(supportedPlugins: serverPlugins, appId: configAppId),
+ httpClient: MockClient((req) async {
+ final key = '${req.method} ${req.url.path}';
+ calls.add('$key${req.url.hasQuery ? '?${req.url.query}' : ''}');
+ final handler = routes[key];
+ if (handler == null) return _json({'error': 'no route $key'}, 404);
+ return handler(req);
+ }),
+ ));
+ addTearDown(manager.dispose);
+ return (manager: manager, routes: routes, calls: calls, api: () => manager.plugin());
+}
+
+void main() {
+ group('models', () {
+ test('maps the server view into typed models', () async {
+ final s = _setup();
+ s.routes['GET /v1/billing/subscription'] = (_) => _json({
+ 'can_manage': false,
+ 'subscription': subJson({
+ 'status': 'trialing',
+ 'trial_end': DateTime.now().add(const Duration(days: 3)).toUtc().toIso8601String(),
+ 'cancel_at': '2026-12-01T00:00:00Z',
+ 'seats': {'feature_key': 'seats', 'used': 3, 'limit': null},
+ 'plan': planJson('team', {
+ 'features': [
+ {'key': 'api', 'name': 'API', 'type': 'metered', 'limit': null, 'soft_limit': true, 'period': 'monthly'},
+ ],
+ }),
+ }),
+ });
+ await s.manager.initialize();
+ await s.api().load();
+
+ final snap = s.api().snapshot;
+ final sub = snap.subscription.data!;
+ expect(snap.subscription.status, ResourceStatus.ready);
+ expect(snap.canManage, isFalse);
+ expect(sub.plan.slug, 'team');
+ expect(sub.plan.price!.amountMinor, 2900);
+ expect(sub.plan.price!.interval, 'monthly');
+ expect(sub.plan.features.single.limit, isNull);
+ expect(sub.plan.features.single.softLimit, isTrue);
+ expect(sub.seats!.used, 3);
+ expect(sub.seats!.limit, isNull);
+ expect(sub.status, SubscriptionStatus.trialing);
+ expect(sub.isTrialing, isTrue);
+ expect(sub.isActive, isTrue);
+ expect(sub.willCancel, isTrue);
+ expect(sub.cancelAt, DateTime.utc(2026, 12, 1));
+ expect(sub.trialDaysLeft, 3);
+ });
+
+ test('keeps an unknown status from a newer server', () {
+ expect(SubscriptionStatus.parse('frozen'), SubscriptionStatus.unknown);
+ expect(SubscriptionStatus.parse('past_due'), SubscriptionStatus.pastDue);
+ });
+
+ test('formats money by the currency digits', () {
+ expect(const Money(amountMinor: 2900, currency: 'usd').format(), r'$29.00');
+ expect(const Money(amountMinor: 500, currency: 'jpy').format(), '¥500');
+ expect(const Money(amountMinor: 1050, currency: 'ngn').format(), 'NGN 10.50');
+ });
+
+ test('uses the ledger currency digits', () {
+ // The ledger stores idr without a minor unit and every other
+ // currency outside its zero-decimal list with two places.
+ expect(const Money(amountMinor: 15000, currency: 'IDR').decimals, 0);
+ expect(const Money(amountMinor: 15000, currency: 'idr').format(), 'IDR 15000');
+ expect(const Money(amountMinor: 1050, currency: 'bif').decimals, 2);
+ expect(const Money(amountMinor: 1050, currency: 'bif').format(), 'BIF 10.50');
+ });
+
+ test('formats large and negative amounts exactly', () {
+ expect(const Money(amountMinor: 900719925474099, currency: 'usd').format(), r'$9007199254740.99');
+ expect(const Money(amountMinor: -1005, currency: 'usd').format(), r'-$10.05');
+ });
+ });
+
+ group('loading', () {
+ test('loads the subscription, can_manage and entitlements', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ expect(s.api().snapshot.subscription.data!.id, 'sub_1');
+ expect(s.api().snapshot.canManage, isTrue);
+ expect(s.api().snapshot.entitlements.status, ResourceStatus.ready);
+ expect(s.api().entitlement('sso')!.allowed, isTrue);
+ expect(s.api().entitlement('nope'), isNull);
+ });
+
+ test('is unavailable without asking when the server has no subscription plugin', () async {
+ final s = _setup(serverPlugins: ['organization']);
+ await s.manager.initialize();
+ await s.api().load();
+ expect(s.api().snapshot.subscription.status, ResourceStatus.unavailable);
+ expect(s.calls.where((c) => c.contains('/v1/billing')), isEmpty);
+ });
+
+ test('drops a response for the org the session has since left', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ final gate = Completer();
+ s.routes['GET /v1/billing/subscription'] = (_) async {
+ await gate.future;
+ return _json({'subscription': subJson(), 'can_manage': true});
+ };
+ final loading = s.api().load();
+
+ s.routes['POST /v1/me/switch-org'] = (_) => _json({'session_id': 's', 'org_id': 'org_2'});
+ s.routes['GET /v1/billing/subscription'] = (_) => _json({'subscription': null, 'can_manage': true});
+ await s.manager.switchOrg('org_2');
+ gate.complete();
+ await loading;
+ await Future.delayed(Duration.zero);
+ expect(s.api().snapshot.subscription.status, ResourceStatus.ready);
+ expect(s.api().snapshot.subscription.data, isNull);
+ });
+
+ test('shares one request between overlapping loads', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await Future.wait([s.api().load(), s.api().load()]);
+ expect(s.calls.where((c) => c == 'GET /v1/billing/subscription'), hasLength(1));
+ expect(s.calls.where((c) => c == 'GET /v1/billing/entitlements'), hasLength(1));
+ });
+
+ test('hides the old org while the new one loads', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ final gate = Completer();
+ s.routes['POST /v1/me/switch-org'] = (_) => _json({'session_id': 's', 'org_id': 'org_2'});
+ s.routes['GET /v1/billing/subscription'] = (_) async {
+ await gate.future;
+ return _json({'subscription': null, 'can_manage': false});
+ };
+ await s.manager.switchOrg('org_2');
+ final snap = s.api().snapshot;
+ expect(snap.subscription.status, ResourceStatus.loading);
+ expect(snap.subscription.data, isNull);
+ expect(snap.canManage, isFalse);
+ expect(snap.entitlements.data, isEmpty);
+ gate.complete();
+ });
+
+ test('drops plans that arrive after sign-out', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ final gate = Completer();
+ s.routes['GET /v1/billing/plans'] = (_) async {
+ await gate.future;
+ return _json({'plans': [planJson('pro')]});
+ };
+ final loading = s.api().loadPlans();
+ await s.manager.signOut();
+ gate.complete();
+ await loading;
+ expect(s.api().snapshot.plans.status, ResourceStatus.idle);
+ expect(s.api().snapshot.plans.data, isEmpty);
+ });
+
+ test('ends the changes stream when the manager is disposed', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ final done = Completer();
+ s.api().changes.listen(null, onDone: done.complete);
+ s.manager.dispose();
+ await done.future.timeout(const Duration(seconds: 1));
+ });
+
+ test('resets on sign-out', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ await s.manager.signOut();
+ expect(s.api().snapshot.subscription.status, ResourceStatus.idle);
+ expect(s.api().snapshot.subscription.data, isNull);
+ });
+
+ test('reads plans for the client config app, else the user app', () async {
+ final withConfig = _setup(configAppId: 'app_cfg');
+ withConfig.routes['GET /v1/billing/plans'] = (_) => _json({
+ 'plans': [planJson('free', {'amount_minor': null}), planJson('pro')],
+ });
+ await withConfig.manager.initialize();
+ await withConfig.api().loadPlans();
+ expect(withConfig.calls, contains('GET /v1/billing/plans?app_id=app_cfg'));
+ expect(withConfig.api().snapshot.plans.data.map((p) => p.slug), ['free', 'pro']);
+ expect(withConfig.api().snapshot.plans.data.first.price, isNull);
+
+ final fromUser = _setup();
+ fromUser.routes['GET /v1/billing/plans'] = (_) => _json({'plans': []});
+ await fromUser.manager.initialize();
+ await fromUser.api().loadPlans();
+ expect(fromUser.calls, contains('GET /v1/billing/plans?app_id=app_user'));
+ });
+ });
+
+ group('writes', () {
+ test('writes a changed subscription into the cache', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ s.routes['PATCH /v1/billing/subscription'] = (req) {
+ expect(jsonDecode(req.body), {'plan': 'team', 'seats': 5});
+ return _json({'subscription': subJson({'plan': planJson('team')})});
+ };
+ final result = await s.api().changePlan('team', seats: 5);
+ expect(result, isA());
+ expect(s.api().snapshot.subscription.data!.plan.slug, 'team');
+ });
+
+ test('leaves the cache alone when payment comes first', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ s.routes['POST /v1/billing/subscription'] = (_) => _json({'checkout_url': 'https://pay.example/1'});
+ final result = await s.api().subscribe('business', returnUrl: 'https://app/billing');
+ expect(result, isA());
+ expect((result as CheckoutRequired).url, Uri.parse('https://pay.example/1'));
+ expect(s.api().snapshot.subscription.data!.plan.slug, 'pro');
+ });
+
+ test('surfaces a refused write without touching the cache', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ s.routes['POST /v1/billing/subscription/cancel'] = (_) => _json({'error': 'nope'}, 403);
+ await expectLater(s.api().cancel(), throwsA(isA()));
+ expect(s.api().snapshot.subscription.data!.cancelAt, isNull);
+ });
+
+ test('cancels at the period end by default and resumes', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ s.routes['POST /v1/billing/subscription/cancel'] = (req) {
+ expect(jsonDecode(req.body), {'when': 'period_end'});
+ return _json({'subscription': subJson({'cancel_at': '2026-12-01T00:00:00Z'})});
+ };
+ s.routes['POST /v1/billing/subscription/resume'] = (_) => _json({'subscription': subJson()});
+ expect((await s.api().cancel()).willCancel, isTrue);
+ expect((await s.api().resume()).willCancel, isFalse);
+ });
+
+ test('drops a write that lands after an org switch', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ final gate = Completer();
+ s.routes['PATCH /v1/billing/subscription'] = (_) async {
+ await gate.future;
+ return _json({'subscription': subJson({'plan': planJson('team')})});
+ };
+ final writing = s.api().changePlan('team');
+ s.routes['POST /v1/me/switch-org'] = (_) => _json({'session_id': 's', 'org_id': 'org_2'});
+ s.routes['GET /v1/billing/subscription'] = (_) => _json({'subscription': null, 'can_manage': true});
+ await s.manager.switchOrg('org_2');
+ // Let the new org's load finish first, so only the stale write is left.
+ await Future.delayed(const Duration(milliseconds: 10));
+ expect(s.api().snapshot.subscription.status, ResourceStatus.ready);
+ gate.complete();
+ final result = await writing;
+ await Future.delayed(Duration.zero);
+ // The caller still hears what happened to the org it wrote to.
+ expect((result as SubscriptionChanged).subscription.plan.slug, 'team');
+ expect(s.api().snapshot.subscription.data, isNull);
+ });
+
+ test('drops a write that lands after sign-out', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ await s.api().load();
+ final gate = Completer();
+ s.routes['POST /v1/billing/subscription/resume'] = (_) async {
+ await gate.future;
+ return _json({'subscription': subJson()});
+ };
+ final writing = s.api().resume();
+ await s.manager.signOut();
+ gate.complete();
+ await writing;
+ expect(s.api().snapshot.subscription.status, ResourceStatus.idle);
+ expect(s.calls.where((c) => c == 'GET /v1/billing/entitlements'), hasLength(1));
+ });
+
+ test('emits a snapshot on every change', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ final seen = [];
+ s.api().changes.listen(seen.add);
+ await s.api().load();
+ expect(seen, isNotEmpty);
+ });
+ });
+
+ group('a server without the plugin', () {
+ Future> printed(Future Function() body) async {
+ final lines = [];
+ await runZoned(body, zoneSpecification: ZoneSpecification(
+ print: (self, parent, zone, line) => lines.add(line),
+ ));
+ return lines;
+ }
+
+ test('warns once in debug, naming the fix', () async {
+ final lines = await printed(() async {
+ final s = _setup(serverPlugins: ['organization']);
+ await s.manager.initialize();
+ await s.api().load();
+ await s.api().load();
+ await s.api().loadPlans();
+ await s.api().forTenant('org_9').load();
+ });
+ expect(lines.where((l) => l.contains('subscription.New')), hasLength(1));
+ });
+
+ test('stays quiet when the server has it', () async {
+ final lines = await printed(() async {
+ final s = _setup(serverPlugins: ['subscription']);
+ await s.manager.initialize();
+ await s.api().load();
+ });
+ expect(lines, isEmpty);
+ });
+ });
+
+ group('forTenant', () {
+ test('reads and writes another tenant, with its own cache', () async {
+ final s = _setup();
+ Object? cancelBody;
+ s.routes['POST /v1/billing/subscription/cancel'] = (req) {
+ cancelBody = jsonDecode(req.body);
+ return _json({'subscription': subJson({'tenant_id': 'org_9', 'cancel_at': '2026-12-01T00:00:00Z'})});
+ };
+ await s.manager.initialize();
+ final other = s.api().forTenant('org_9');
+ expect(identical(s.api().forTenant('org_9'), other), isTrue);
+ expect(other.tenantId, 'org_9');
+ expect(s.api().tenantId, isNull);
+
+ await other.load();
+ expect(s.calls, contains('GET /v1/billing/subscription?tenant_id=org_9'));
+ expect(s.calls, contains('GET /v1/billing/entitlements?tenant_id=org_9'));
+ expect(s.api().snapshot.subscription.status, ResourceStatus.idle);
+
+ await other.cancel();
+ expect(cancelBody, {'when': 'period_end', 'tenant_id': 'org_9'});
+ expect(other.snapshot.subscription.data!.willCancel, isTrue);
+ });
+
+ test('keeps a pinned tenant across org switches and forgets it on sign-out', () async {
+ final s = _setup();
+ await s.manager.initialize();
+ final other = s.api().forTenant('org_9');
+ await other.load();
+ s.routes['POST /v1/me/switch-org'] = (_) => _json({'session_id': 's', 'org_id': 'org_2'});
+ await s.manager.switchOrg('org_2');
+ expect(other.snapshot.subscription.status, ResourceStatus.ready);
+ await s.manager.signOut();
+ expect(other.snapshot.subscription.status, ResourceStatus.idle);
+ });
+ });
+}
diff --git a/flutter/packages/authsome_subscription_flutter/CHANGELOG.md b/flutter/packages/authsome_subscription_flutter/CHANGELOG.md
new file mode 100644
index 00000000..62094844
--- /dev/null
+++ b/flutter/packages/authsome_subscription_flutter/CHANGELOG.md
@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.6.1
+
+- First release.
diff --git a/flutter/packages/authsome_subscription_flutter/LICENSE b/flutter/packages/authsome_subscription_flutter/LICENSE
new file mode 100644
index 00000000..ba6a044b
--- /dev/null
+++ b/flutter/packages/authsome_subscription_flutter/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/flutter/packages/authsome_subscription_flutter/README.md b/flutter/packages/authsome_subscription_flutter/README.md
new file mode 100644
index 00000000..f00ded4a
--- /dev/null
+++ b/flutter/packages/authsome_subscription_flutter/README.md
@@ -0,0 +1,62 @@
+# authsome_subscription_flutter
+
+Material 3 widgets for authsome's `subscription` plugin: a pricing table, the current plan, usage, an entitlement gate and a billing portal button.
+
+```yaml
+dependencies:
+ authsome_flutter: ^1.6.1
+ authsome_subscription_flutter: ^1.6.1
+```
+
+## Set it up
+
+```dart
+AuthProvider(
+ config: AuthConfig(
+ baseUrl: 'https://api.example.com',
+ plugins: const [SubscriptionPlugin()],
+ ),
+ child: const MyApp(),
+);
+```
+
+## Widgets
+
+```dart
+const CurrentPlanCard();
+
+PricingTable(
+ highlight: 'team',
+ onCheckout: (uri) => launchUrl(uri),
+);
+
+const EntitlementGate(
+ feature: 'sso',
+ fallback: UpgradePrompt(),
+ child: SsoSettings(),
+);
+
+const UsageMeter(feature: 'api_calls', label: 'API calls this month');
+
+ManageBillingButton(onOpen: (uri) => launchUrl(uri));
+```
+
+`PricingTable` and `CurrentPlanCard` show plain words when a change fails, such as "Couldn't change your plan. Try again.", and pass the server's error to `onError` if you want to log it. Leave out `onCheckout` and a paid plan can't be bought: the table says so and hands `onError` a `StateError`.
+
+`EntitlementGate` only shows its child when the plan includes the feature. While the check loads, on an error, or when the server doesn't have the plugin, you get the fallback.
+
+Opening a payment or portal page is left to you, so the package doesn't pull in a URL launcher. Pass `launchUrl` from url_launcher, or whatever you already use.
+
+`CurrentPlanCard` asks before it cancels. Every widget takes a `tenantId` for support staff who hold `billing:manage` and look after a customer's billing, and `context.subscriptionFor(id)` is the API for that tenant.
+
+For your own UI, `context.subscription` is the plugin's API and `SubscriptionBuilder` rebuilds from its snapshot:
+
+```dart
+SubscriptionBuilder(
+ builder: (context, snap) {
+ final sub = snap.subscription.data;
+ if (snap.subscription.isLoading) return const CircularProgressIndicator();
+ return Text(sub?.plan.name ?? 'Free');
+ },
+);
+```
diff --git a/flutter/packages/authsome_subscription_flutter/analysis_options.yaml b/flutter/packages/authsome_subscription_flutter/analysis_options.yaml
new file mode 100644
index 00000000..f190a220
--- /dev/null
+++ b/flutter/packages/authsome_subscription_flutter/analysis_options.yaml
@@ -0,0 +1,10 @@
+analyzer:
+ exclude:
+ - build/**
+include: package:flutter_lints/flutter.yaml
+
+linter:
+ rules:
+ prefer_single_quotes: true
+ sort_constructors_first: false
+ avoid_dynamic_calls: false
diff --git a/flutter/packages/authsome_subscription_flutter/lib/authsome_subscription_flutter.dart b/flutter/packages/authsome_subscription_flutter/lib/authsome_subscription_flutter.dart
new file mode 100644
index 00000000..f6152d1c
--- /dev/null
+++ b/flutter/packages/authsome_subscription_flutter/lib/authsome_subscription_flutter.dart
@@ -0,0 +1,18 @@
+/// Flutter widgets for authsome's subscription plugin.
+///
+/// ```dart
+/// AuthProvider(
+/// config: AuthConfig(baseUrl: url, plugins: const [SubscriptionPlugin()]),
+/// child: const MyApp(),
+/// );
+///
+/// const CurrentPlanCard();
+/// PricingTable(onCheckout: (uri) => launchUrl(uri));
+/// const EntitlementGate(feature: 'sso', fallback: UpgradePrompt(), child: SsoSettings());
+/// ```
+library authsome_subscription_flutter;
+
+export 'package:authsome_flutter/authsome_flutter.dart';
+export 'package:authsome_subscription/authsome_subscription.dart';
+
+export 'src/subscription_widgets.dart';
diff --git a/flutter/packages/authsome_subscription_flutter/lib/src/subscription_widgets.dart b/flutter/packages/authsome_subscription_flutter/lib/src/subscription_widgets.dart
new file mode 100644
index 00000000..86effa5e
--- /dev/null
+++ b/flutter/packages/authsome_subscription_flutter/lib/src/subscription_widgets.dart
@@ -0,0 +1,482 @@
+import 'dart:async';
+
+import 'package:authsome_flutter/authsome_flutter.dart';
+import 'package:authsome_subscription/authsome_subscription.dart';
+import 'package:flutter/material.dart';
+
+/// Reaches the subscription plugin from the widget tree.
+extension SubscriptionContext on BuildContext {
+ /// The subscription plugin's API. The plugin has to be in the
+ /// [AuthConfig.plugins] of the surrounding [AuthProvider].
+ SubscriptionApi get subscription => AuthProvider.of(this).plugin();
+
+ /// The API for [tenantId], or the session's own when it's null. Passing a
+ /// tenant is for operators who hold billing:manage.
+ SubscriptionApi subscriptionFor(String? tenantId) =>
+ tenantId == null ? subscription : subscription.forTenant(tenantId);
+}
+
+/// Builds from the subscription plugin's snapshot and rebuilds when it
+/// changes. Loads the subscription (and, with [loadPlans], the plans) the
+/// first time it's built while signed in. Pass [tenantId] to read another
+/// tenant than the session's (operators holding billing:manage only).
+class SubscriptionBuilder extends StatefulWidget {
+ const SubscriptionBuilder({required this.builder, this.loadPlans = false, this.tenantId, super.key});
+
+ final Widget Function(BuildContext context, SubscriptionSnapshot snapshot) builder;
+ final bool loadPlans;
+ final String? tenantId;
+
+ @override
+ State createState() => _SubscriptionBuilderState();
+}
+
+class _SubscriptionBuilderState extends State {
+ SubscriptionApi? _api;
+
+ @override
+ void didChangeDependencies() {
+ super.didChangeDependencies();
+ _resolve();
+ }
+
+ @override
+ void didUpdateWidget(SubscriptionBuilder oldWidget) {
+ super.didUpdateWidget(oldWidget);
+ if (oldWidget.tenantId != widget.tenantId) _resolve();
+ }
+
+ void _resolve() {
+ final auth = AuthProvider.of(context);
+ final api = context.subscriptionFor(widget.tenantId);
+ _api = api;
+ // AuthProvider is inherited, so this runs again when the user signs in.
+ if (!auth.isAuthenticated) return;
+ if (api.snapshot.subscription.status == ResourceStatus.idle) unawaited(api.load());
+ if (widget.loadPlans && api.snapshot.plans.status == ResourceStatus.idle) {
+ unawaited(api.loadPlans());
+ }
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ final api = _api!;
+ return StreamBuilder(
+ stream: api.changes,
+ initialData: api.snapshot,
+ builder: (context, _) => widget.builder(context, api.snapshot),
+ );
+ }
+}
+
+// Idle counts as loading only while signed in: SubscriptionBuilder is
+// about to start the load. Signed out, nothing will, so idle means empty.
+bool _isLoading(BuildContext context, Resource r) =>
+ r.status == ResourceStatus.loading ||
+ (r.status == ResourceStatus.idle && AuthProvider.of(context).isAuthenticated);
+
+/// Shows [child] only when the plan includes [feature]. Loading, an error,
+/// or billing not being installed all show [fallback] (or [loading] while
+/// the check loads), so a paywall never opens by accident.
+class EntitlementGate extends StatelessWidget {
+ const EntitlementGate({
+ required this.feature,
+ required this.child,
+ this.fallback = const SizedBox.shrink(),
+ this.loading,
+ this.tenantId,
+ super.key,
+ });
+
+ final String feature;
+ final String? tenantId;
+ final Widget child;
+ final Widget fallback;
+ final Widget? loading;
+
+ @override
+ Widget build(BuildContext context) {
+ return SubscriptionBuilder(tenantId: tenantId, builder: (context, snap) {
+ final entitlements = snap.entitlements;
+ if (entitlements.status == ResourceStatus.ready &&
+ entitlements.data[feature]?.allowed == true) {
+ return child;
+ }
+ if (_isLoading(context, entitlements)) return loading ?? fallback;
+ return fallback;
+ });
+ }
+}
+
+String _date(BuildContext context, DateTime date) =>
+ MaterialLocalizations.of(context).formatShortDate(date.toLocal());
+
+// Server messages are written for developers, so people see plain words
+// and the error itself goes to the widget's onError.
+void _showError(BuildContext context, String message) {
+ ScaffoldMessenger.maybeOf(context)?.showSnackBar(SnackBar(content: Text(message)));
+}
+
+/// The plans the tenant can buy, cheapest first, with a button on each.
+///
+/// Without [onSelected] a tap subscribes or changes plan. When the plan
+/// needs paying for, [onCheckout] gets the payment page's URL; open it with
+/// your launcher of choice, e.g. `launchUrl(uri)` from url_launcher.
+class PricingTable extends StatefulWidget {
+ const PricingTable({
+ this.onSelected,
+ this.onCheckout,
+ this.highlight,
+ this.returnUrl,
+ this.cancelUrl,
+ this.onError,
+ this.tenantId,
+ super.key,
+ });
+
+ final ValueChanged? onSelected;
+
+ /// Another tenant than the session's, for operators holding billing:manage.
+ final String? tenantId;
+
+ /// Gets the payment page URL when a plan needs paying for. Without it the
+ /// table can't take payment: it tells the user and passes a [StateError]
+ /// to [onError].
+ final ValueChanged? onCheckout;
+
+ /// Called with the error when a change fails; the table shows plain words.
+ final ValueChanged