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/docs/content/docs/plugins/subscription.mdx b/docs/content/docs/plugins/subscription.mdx
index 46af8af9..bcaea046 100644
--- a/docs/content/docs/plugins/subscription.mdx
+++ b/docs/content/docs/plugins/subscription.mdx
@@ -147,6 +147,58 @@ 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`.
+
+The billing methods on the core `ui-core` and `authsome_core` clients still work, and are marked deprecated in favour of these packages.
+
## 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 04d280da..9bf39d65 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..5bf75f99
--- /dev/null
+++ b/flutter/packages/authsome_subscription/README.md
@@ -0,0 +1,45 @@
+# 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.
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..bd43f9ad
--- /dev/null
+++ b/flutter/packages/authsome_subscription/lib/src/subscription_api.dart
@@ -0,0 +1,331 @@
+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 }
+
+/// The subscription plugin's API, from `auth.plugin()` or,
+/// in Flutter, `context.subscription`.
+class SubscriptionApi {
+ SubscriptionApi(this._ctx) {
+ // 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 || AuthEvent.orgChanged:
+ _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;
+ 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);
+ }
+
+ bool get _unavailable => _ctx.isServerEnabled == false;
+ 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') 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') 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: {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: 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: 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..5ea4c07f
--- /dev/null
+++ b/flutter/packages/authsome_subscription/test/subscription_api_test.dart
@@ -0,0 +1,387 @@
+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);
+ });
+ });
+}
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..473f49c3
--- /dev/null
+++ b/flutter/packages/authsome_subscription_flutter/README.md
@@ -0,0 +1,60 @@
+# 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.
+
+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..b9b69ae9
--- /dev/null
+++ b/flutter/packages/authsome_subscription_flutter/lib/src/subscription_widgets.dart
@@ -0,0 +1,432 @@
+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();
+}
+
+/// 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.
+class SubscriptionBuilder extends StatefulWidget {
+ const SubscriptionBuilder({required this.builder, this.loadPlans = false, super.key});
+
+ final Widget Function(BuildContext context, SubscriptionSnapshot snapshot) builder;
+ final bool loadPlans;
+
+ @override
+ State createState() => _SubscriptionBuilderState();
+}
+
+class _SubscriptionBuilderState extends State {
+ SubscriptionApi? _api;
+
+ @override
+ void didChangeDependencies() {
+ super.didChangeDependencies();
+ final auth = AuthProvider.of(context);
+ final api = auth.plugin();
+ _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,
+ super.key,
+ });
+
+ final String feature;
+ final Widget child;
+ final Widget fallback;
+ final Widget? loading;
+
+ @override
+ Widget build(BuildContext context) {
+ return SubscriptionBuilder(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,
+ super.key,
+ });
+
+ final ValueChanged? onSelected;
+
+ /// 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