filmopen_account

A snapshot

This specification is a copy of docs/software/packages/filmopen_account.md in the application’s repository, taken at commit 0b4fe88 of 11 November 2026. It is imported byte for byte and is not edited here; a change is made there, and arrives with the next snapshot.

Generated by scripts/package_digest.py; regenerate, never edit.

The filmopen.ai account: sign-in through Supabase with PKCE (account_auth.dart), the ai.filmopen.desktop:// callback registration (Windows; a phone’s scheme is in its manifest) and the callback’s arrival through the platform’s link door, the account’s state for the app (accountModelProvider, made as the rail’s profile is first built and kept as long as the app, so that no sign-in’s result is dropped while the popup is closed), the account’s public snapshot for the app (AccountSnapshotAdapter, installed and let go with the state: a passive observer that starts nothing — signed out, loading, or signed in with the account’s id, the balance unavailable until the website reports one), the rail’s profile (AccountProfileButton: from that snapshot, the username in effect with Login and Signup, Loading…, or with the balance as its state says it; it keeps the account’s names alive, so signing in sets the username, §6.6 — an amount only where one is known, zero included), the account’s popup (AccountPopup: who is signed in, the username chosen from the account’s names, and the way in or out), the sign-in dialog and the provider marks.

Flutter. 23 files, 3,986 lines under lib/; 158 tests in 15 files. Barrel: lib/filmopen_account.dart.

Depends on

• filmopen_format — uses AccountAuthProblem, Author, ExactDecimal, ShortName, newUsageId
• filmopen_platform — uses CredentialStore, CredentialStoreUnavailable
• filmopen_store — uses AppLog, LogLevel
• filmopen_state — uses AccountAccess, AccountAuthentication, AccountBalance, AccountIdentity, AccountLedger, AccountNamesStatus, AccountOpener, AccountProjects, AccountProjectsRefused, AccountSnapshot, AccountSnapshots, AudienceSettings, CommunityGroups, CommunityGroupsRefused, CreditFunding, DeviceAccount, DeviceRegistration, DraftsNotSettledException, FundedReceipt, FundingBinding, FundingResult, FundingUnavailable, GroupDetail, GroupInvitation, GroupMember, GroupMembership, GroupName, GroupPage, KnownAccountBalance, LedgerRead and 42 more
• filmopen_ui — uses AppColors, FilmOpenLogo, showMessage
• filmopen_l10n — uses nothing by name the digest could see
• filmopen_dictation — uses nothing by name the digest could see

Third-party: flutter_riverpod, supabase_flutter, logging, url_launcher, flutter_svg, http.

Used by

filmopen_app

Public API

What the barrel exports, file by file. A name is class, enum, mixin, extension, typedef, a top-level function, getter, setter or variable; under a class, its public constructors, fields, getters, setters and methods.

lib/src/account_auth.dart

• variable const filmOpenAuthUrl — Public client configuration.
• variable const filmOpenPublishableKey
• variable const filmOpenAuthScheme — The URL scheme the browser hands the sign-in result back through on desktop; account_registration_io.dart registers it with Windows.
• variable const filmOpenDesktopCallback
• variable const filmOpenAccountUrl — The website’s account page, and its help, which is a page of the documentation site as every guide is (kFilmOpenDocsUrl): the website serves no /docs/….
• variable const filmOpenAccountHelpUrl
• function bool isFilmOpenAuthCallback(Uri uri) — Whether [uri] is the sign-in result coming back from the browser.
• function Uri? authCallbackIn(Iterable<String> arguments) — The sign-in result the process was started with, or null.
• class AccountStorageException — Thrown by the storage adapters below when the credential store fails (its CredentialStoreUnavailable: the platform’s failure, a timeout, or a write refused over a store that reads empty, §6.7).
  • const AccountStorageException(this.cause)
  • final Object cause
• class AccountBrowserException — Thrown by the card when the browser could not be opened: url_launcher on Windows throws a PlatformException rather than returning false.
  • const AccountBrowserException([this.cause])
  • final Object? cause
• function AccountAuthProblem accountAuthProblem(Object error) — The code for [error].
• function Map<String, Object?> accountErrorData(Object error) — What the log says of [error]: its type, its machine codes and its whole text, the server’s words included (AuthException.message, a PostgrestException’s message, details and hint).
• class AccountWithheldException — The account is withheld from this process (an agent build’s, §6.6): nothing connects, restores or exchanges.
  • const AccountWithheldException() — Says the account is not available here.
• class FilmOpenAccountAuth — The one Supabase client, created on first use.
  • static final instance
  • void withhold() — Withholds the account from this process for good: an agent build’s entrypoint calls it before the app starts, so that every door — the card’s connection, a sign-in, a callback’s exchange, the launch’s restoration — an…
  • Future<SupabaseClient> initialize() — Creates the client on the first call and shares the same future with every later one.
  • String get callbackUrl
• class SecureSessionStorage — The account’s session in the device’s credential store, under its own name alone, through the one door, CredentialStore.current, whose guard refuses a write over a store that lost names (§6.7); fails closed, never p…
  • const SecureSessionStorage()
• class SecurePkceStorage — The PKCE verifier under filmopen.pkce.<key> alone, through the same door.
• class AuthAnswersClient — The account’s HTTP client: each answer of the auth server’s token endpoint logged with its grant, status and the server’s error code and words, never a 2xx body, which holds the tokens.
  • AuthAnswersClient(this._inner)

lib/src/account_balance.dart

• class AccountBalanceReader — Reads GET https://<kFilmOpenDomain>/v1/balance with the session’s bearer into the account’s balance.
  • AccountBalanceReader({http.Client? client, DateTime Function()? clock}) — A reader through [client] — a real one where none is given — at the build’s own domain.
  • Future<AccountBalance> read(Future<String?> Function() accessToken, {Future<void>? abort}) — The balance for the session whose token [accessToken] answers; unavailable at once, with no request, without one.
• function String refusalCode(http.Response response) — A refusal’s code ({error, says}), where it has the shape of one; its words are [refusalSays].
• function String? refusalSays(http.Response response) — A refusal’s words (says), as the server wrote them, or null where the body has none.
• function Future<T> portalWait<T>(Future<T> work, Future<void>? abort) — Waits until an operation answers or Stop cancels it, with no application deadline.
• function Future<http.Response> portalSend(http.Client client, String method, Uri url, Map<String, String> headers, {String? body, Future<void>? abort}) — Sends one abortable portal request and cancels its body read when Stop completes.

lib/src/account_card_model.dart

• typedef typedef AccountNotice — Text resolved against the language in effect when it is shown, so a change of language re-renders it.
• class AccountCardModel — The state and the actions behind the filmopen.ai account (§9.4): the rail’s profile, the account’s popup and the sign-in dialog it opens, which all show the one the app keeps (accountModelProvider).
  • AccountCardModel({ required bool signedInBefore, required bool launchedWithCallback, required this.rememberSignedIn, Future<SupabaseClient> Functio…
  • final void Function(bool signedIn) rememberSignedIn — Writes the “a session exists” hint the next launch reads.
  • static const providers — Only the methods configured in this project’s Supabase dashboard.
  • Stream<AccountNotice> get messages — Transient confirmations, for a snackbar (§9.5).
  • bool get hasClient — A client exists: either restored at start or connected by a gesture.
  • bool get restoreFailed — The session the preferences’ hint promised could not be restored at start — the client could not be made: as far as this process can tell nobody is signed in, while the hint is kept for the next start.
  • bool signedInGiven(bool hint) — Whether a person is signed in, as far as anything may say without starting the account.
  • Future<String?> accessToken() — The session’s access token, refreshed first where it is past its hour; null without a session.
  • User? get user
  • bool get busy — A user action is in flight: progress shows, the controls are disabled.
  • bool get oauthPending — The browser was opened for a provider sign-in and its result has not come back.
  • bool get sentCode
  • String get requestedEmail
  • AccountNotice? get notice — The last validation or failure, shown until the next action.
  • bool get canStartSignIn — The sign-in dialog may open: nobody is signed in, nothing in flight.
  • Future<void> restore() — Opens the client for a session that should already exist.
  • Future<void> callbackArrived(Uri uri, {required bool initial}) — The sign-in result came through the platform’s link door, or as the process’s argument.
  • Future<void> signIn(OAuthProvider provider) — Opens the browser on the provider’s sign-in page, unless the first connection restored a stored session.
  • void cancelBrowser() — Forgets the browser sign-in that was started; the verifier left in the store is overwritten by the next start.
  • Future<void> sendCode(String email) — Sends a sign-in code to [email]; the dialog then asks for the code.
  • Future<void> signInWithPassword(String email, String password) — Signs in with [email] and [password], the road beside the e-mailed code; the auth stream then reports the user.
  • Future<void> verifyCode(String code) — Exchanges the emailed code; the auth stream then reports the user.
  • void changeEmail() — Back to the address box, to correct it or ask for another code.
  • void dismissSignIn() — The sign-in dialog was closed without a result: its validation text does not outlive it.
  • Future<void> signOut()
  • Future<void> open(String url) — Opens a page of the website; says so when no browser opens.
• function String accountProviderName(AppLocalizations l10n, OAuthProvider provider) — The label of an enabled provider; only [AccountCardModel.providers] are ever built.

lib/src/account_device.dart

• function Future<String?> freshAccessToken(SupabaseClient client) — [client]’s access token, refreshed first when the session is past its hour.
• function DeviceAccount deviceAccountOf(SupabaseClient client, User user) — The seam’s account for [user], whose token [client] answers.

lib/src/account_funded.dart

• typedef typedef PortalOperationAnswer — What an operation’s read or end came to: its outcome, its receipt where it has settled, and the website’s status and code where it refused.
• class FundedCalls — Speaks an operation’s two routes on the portal: GET /v1/portal/operations/{id} and POST …/{id}/end.
  • FundedCalls({http.Client? client, this.onReceipt}) — Calls through [client], a real one where none is given.
  • final void Function()? onReceipt — Told when a read found the operation settled: the balance has moved.
  • Future<PortalOperationAnswer> receipt(String platform, String operation, String operationId, Map<String, String> headers, Stopwatch watch, {Future<… — The operation’s read: settled with its receipt, pending with none yet, refused with the website’s code, malformed where the answer is not the contract’s, failed where no answer came.
  • Future<PortalOperationAnswer> end(String platform, String operation, String operationId, Map<String, String> headers, Stopwatch watch, {Future<void… — The operation’s end, once: ended, refused with the website’s code, or failed where no answer came.

lib/src/account_groups.dart

• class AccountGroupsClient — Speaks https://<kFilmOpenDomain>/v1/community/… for groups with the session’s bearer, and X-FilmOpen-Identity as the membership’s own identity where a route acts as one.
  • AccountGroupsClient({http.Client? client, required this.accessToken, this.timeout = const Duration(seconds: 20)}) — A client through [client] — a real one where none is given — for the session whose token [accessToken] answers.
  • final Future<String?> Function() accessToken — The session’s access token, null when nobody is signed in.
  • final Duration timeout — How long one request, or the session’s answer, may take before it counts as unreachable.

lib/src/account_ledger.dart

• class AccountLedgerReader — Reads GET https://<kFilmOpenDomain>/v1/ledger with the session’s bearer into the account’s ledger rows.
  • AccountLedgerReader({http.Client? client, required this.accessToken, this.timeout = const Duration(seconds: 20)}) — A reader through [client] — a real one where none is given — for the session whose token [accessToken] answers.
  • static const pages — The most pages one read follows: enough for a year of a busy supplier, bounded so that a read ends.
  • static const pageSize — The records asked for per page, the route’s most.
  • final Future<String?> Function() accessToken — The session’s access token, null when nobody is signed in.
  • final Duration timeout — How long one request may take before it counts as unreachable.

lib/src/account_lending.dart

• class AccountLending — Speaks https://<kFilmOpenDomain>/v1/lending/… with the session’s bearer and the registered device’s two headers.
  • AccountLending({http.Client? client, required this.accessToken, this.community, this.timeout = const Duration(seconds: 20)}) — A client through [client] — a real one where none is given — for the session whose token [accessToken] answers, reading identities through [community], the installed [AccountProjects] where none is given.
  • final AccountProjects? community — The community’s client, which reads the primary identity; null reads [AccountProjects.current].
  • final Future<String?> Function() accessToken — The session’s access token, null when nobody is signed in.
  • final Duration timeout — How long one request may take before it counts as unreachable.

lib/src/account_media.dart

• class AccountMedia — Turns bytes into a download URL through the website’s two media requests, the mint and the PUT.
  • AccountMedia({http.Client? client, required this.accessToken, this.timeout = const Duration(seconds: 60)}) — A client through [client] — a real one where none is given — for the session whose token [accessToken] answers.
  • final Future<String?> Function() accessToken — The session’s access token, null when nobody is signed in.
  • final Duration timeout — How long the token, the mint and the PUT may each take before they count as failed.

lib/src/account_model_provider.dart

• variable final accountConnectProvider — A client in place of the real initialisation (§9.4): null, the real one; a test’s stand-in, which reaches no socket.
• variable final accountBalanceReaderProvider — Where the account’s balance is read (§6.6): none in a test, which reads no balance; the app installs the real one.
• variable final authCallbacksProvider — The ledger of sign-in callbacks already acted on: the process’s own, or a test’s, since the shared one lives as long as the process and would carry one test’s links into the next.
• variable final accountModelProvider — The filmopen.ai account’s state, one for the app (§9.4): the rail’s profile shows it and its popup acts on it.

lib/src/account_popup.dart

• function Future<void> showAccountPopup(BuildContext context, AccountCardModel model, {String? reason}) — Opens the account’s popup over [context] (§9.4), on the one [model] the app keeps; [reason] is said at its top.
• class AccountPopup — The filmopen.ai account’s popup, which the rail’s profile opens (§9.4): what the account is, and the way in or out.
  • const AccountPopup({super.key, required this.model, this.reason})
  • final AccountCardModel model
  • final String? reason — Why the person is asked to sign in, said at the top — where the one opener was given a reason, as the support flow’s Sign in is; null says nothing.

lib/src/account_portal.dart

• class PortalCredential — A portal credential as the website issued it, held in memory alone: never logged, never written.
  • const PortalCredential({required this.token, required this.expiresAt, required this.scopes, required this.spendCeilingCents}) — The credential’s four facts.
  • final String token — Sent as X-FilmOpen-Portal-Token beside the person’s bearer.
  • final DateTime expiresAt
  • final List<String> scopes
  • final int spendCeilingCents — What it may hold and spend together, in cents.
• typedef typedef PortalAnswer — A credential, or why there is none.
• class PortalSessions — Asks POST https://<kFilmOpenDomain>/v1/portal/session for one credential per operation, of the operation’s scope, and holds it by the operation’s id until it expires or is let go ([drop], [forget]).
  • PortalSessions({http.Client? client, DateTime Function()? clock}) — Sessions through [client], a real one where none is given.
  • Future<PortalAnswer> credential(({String id, String build}) device, Future<String?> Function() accessToken, {required String scope, required String… — The credential held for [operationId] while it is valid, else one of [scope] asked for [device] — the registered id and build stamp — and held for that operation.
  • void drop(String operationId, String reason) — Lets [operationId]’s credential go, for [reason] — ended, unsent, settled, expired, refused or signedOut — so that a later query for it asks once more.
  • void forget() — Lets whatever is held, or asked, go: nobody is signed in any more.
• class AccountProviderFunding — The app’s funding resolver: a person’s own key first, then FilmOpen credit.
  • AccountProviderFunding({required this.ownKeyStored, required this.accessToken, PortalSessions? sessions, FundedCalls? calls}) — A resolver over the installed account snapshot and device registration.
  • final Future<bool> Function(String platform) ownKeyStored — Whether the person’s own key for a platform is stored ([keyStoredFor]).
  • final Future<String?> Function() accessToken — The session’s access token, or null without one.
  • void changed() — Advances the generation: the person’s keys, the account or the device’s registration changed.
  • static bool keyStoredFor(String platform, List<PluginKeyOwner> owners, bool Function(String name) stored) — Whether any of [owners]’ slots on [platform] has a key, [stored] answering by the key’s name, <owner>/<slot>: the keys are named by slot, never by platform.

lib/src/account_profile_button.dart

• class AccountProfileButton — The account’s place on the rail, beneath Help (§9.4): a name and the account’s state.
  • const AccountProfileButton({super.key})

lib/src/account_projects_client.dart — without contractUuid

• class AccountProjectsClient — Speaks https://<kFilmOpenDomain>/v1/community/… and /v1/projects with the session’s bearer alone.
  • AccountProjectsClient({http.Client? client, required this.accessToken, this.timeout = const Duration(seconds: 20)}) — A client through [client] — a real one where none is given — for the session whose token [accessToken] answers.
  • final Future<String?> Function() accessToken — The session’s access token, null when nobody is signed in.
  • final Duration timeout — How long one request, or the session’s answer, may take before it counts as unreachable.

lib/src/account_sign_in_dialog.dart

• class AccountSignInDialog — The sign-in dialog: the logo, Sign in to filmopen.ai, one button per provider with its mark, and — below an or rule — the email code, or the email and a password.
  • const AccountSignInDialog({super.key, required this.model})
  • final AccountCardModel model

lib/src/account_snapshot_adapter.dart

• class AccountSnapshotAdapter — The account’s public snapshot for the rest of the app (AccountSnapshots), read from the account’s state as it already is: an observer that never connects, restores or signs in (§6.6), and whose one request is the ba…
  • AccountSnapshotAdapter(this.model, {required this.signedInBefore, this.balances}) — The adapter over [model], told whether the preferences promised a session at start ([signedInBefore]).
  • final AccountCardModel model — The account’s state, observed.
  • final bool signedInBefore — The preferences’ hint when the state was made: a session was kept at the last run.
  • final AccountBalanceReader? balances — Where the balance is read; null, never.
  • void refreshBalance({Future<void>? abort}) — Reads the balance again for whoever is signed in, keeping the last known one until the answer: as the account’s popup opens, and after a funded call’s receipt.
  • void detach() — Stops observing the state: nothing is published after.

lib/src/auth_callbacks.dart

• class AuthCallbacks — The sign-in callbacks a process has already acted on.
  • static final instance — The ledger every model shares, because the links outlive every model.
  • bool isSpent(Uri uri) — Whether [uri] has already been acted on in this process.
  • bool claim(Uri uri) — Claims [uri]: true the first time this process is handed it, false afterwards.
  • void forget() — Forgets everything, for a test that must not inherit another test’s links.

lib/src/provider_mark.dart

• class ProviderMark — The mark of a sign-in provider, for a “Continue with …” button.
  • const ProviderMark(this.provider, {super.key, this.size = 18})
  • final OAuthProvider provider
  • final double size

Internal

Files under lib/ the barrel does not reach; nothing outside the package may import them.

• lib/src/account_balance_text.dart: accountBalanceAmount, accountBalanceShort, accountBalanceSaid
• lib/src/account_registration_io.dart: canRegisterAuthProtocol, ensureAuthProtocolRegistered
• lib/src/account_registration_stub.dart: canRegisterAuthProtocol, ensureAuthProtocolRegistered