Installation & Setup

1dart pub add neuctra_authix_dart_package

import 'package:neuctra_authix_dart_package/neuctra_authix_dart_package.dart';

1// lib/services/authix.dart
2import 'package:neuctra_authix_dart_package/neuctra_authix_dart_package.dart';
3
4/// One shared instance for the whole app.
5final authix = NeuctraAuthix(
6  const NeuctraAuthixConfig(
7    appId: String.fromEnvironment('AUTHIX_APP_ID'),
8    publishableKey: String.fromEnvironment('AUTHIX_PUBLISHABLE_KEY'),
9    appName: 'MyApp',
10    // baseUrl defaults to the production API — override it to point at a
11    // local server during development.
12  ),
13);

1flutter run \
2  --dart-define=AUTHIX_PUBLISHABLE_KEY=pk_live_xxxxxxxx_xxxxxxxxxxxxxxxx \
3  --dart-define=AUTHIX_APP_ID=your_app_id_here
4
5# Or keep them in a file and pass it once:
6flutter run --dart-define-from-file=authix.json

1final authix = NeuctraAuthix(
2  config,
3  client: myHttpClient,          // optional — bring your own http.Client
4  session: SessionStore(),       // optional — share a jar between clients
5  timeout: const Duration(seconds: 15), // optional — defaults to 30s
6);
7
8// Release the underlying client when you are done with it.
9authix.close();

1import 'package:flutter_secure_storage/flutter_secure_storage.dart';
2
3const _storage = FlutterSecureStorage();
4const _key = 'authix_session';
5
6/// Call once during app start-up, before the first API call.
7Future<void> restoreSession() async {
8  final saved = await _storage.read(key: _key);
9  if (saved != null) authix.session.setSessionCookie(saved);
10}
11
12/// Call after a successful login.
13Future<void> persistSession() async {
14  final cookie = authix.session.sessionCookie;
15  if (cookie != null) await _storage.write(key: _key, value: cookie);
16}
17
18/// Call after logout.
19Future<void> forgetSession() => _storage.delete(key: _key);

1Future<void> main() async {
2  WidgetsFlutterBinding.ensureInitialized();
3
4  await restoreSession();
5
6  // checkUserSession never throws — a dead cookie simply returns false
7  // and is cleared from the store for you.
8  final session = await authix.checkUserSession();
9
10  runApp(MyApp(isLoggedIn: session.authenticated));
11}

1import 'package:http/browser_client.dart';
2
3// On Flutter Web the browser owns the cookie jar, so let it send
4// credentials itself. SessionStore stays empty — that is expected.
5final authix = NeuctraAuthix(
6  config,
7  client: BrowserClient()..withCredentials = true,
8);

1try {
2  await authix.loginUser(
3    const LoginParams(email: '[email protected]', password: 'wrong'),
4  );
5} on ConfigurationError catch (err) {
6  // A required argument was empty — no request was sent.
7  print(err.message);
8} on NetworkError catch (err) {
9  // Timeout, offline, DNS or TLS failure.
10  print(err.message);
11} on AuthenticationError catch (err) {
12  // 401 — wrong password, or an expired or revoked credential.
13  print(err.message);
14} on AuthixApiError catch (err) {
15  // Anything else the API rejected.
16  print('${err.status} ${err.code}: ${err.message}');
17  print(err.payload); // the decoded response body
18}

1// Optimistic concurrency: pass the version you last read.
2try {
3  await authix.updateUserData(
4    UpdateUserDataParams(
5      userId: userId,
6      dataId: record.id,
7      data: {'status': 'shipped'},
8      version: record.version,
9    ),
10  );
11} on VersionConflictError catch (err) {
12  // Another device wrote first. Nothing was overwritten.
13  print('now at version ${err.currentVersion}');
14}
15
16// Wrong key for the endpoint — nearly always a pk_ key on a server-only route.
17try {
18  await authix.getAllUsersFromApp(const GetAllAppUsersParams());
19} on InsufficientScopeError catch (err) {
20  print(err.hint); // explains which credential the endpoint needs
21}

1// 1. Create the account — the session cookie is captured automatically
2final signup = await authix.signupUser(
3  const SignupParams(
4    name: 'John Doe',
5    email: '[email protected]',
6    password: 'secret123',
7    username: 'johndoe',
8  ),
9);
10
11final userId = signup['user']?['id']?.toString() ?? '';
12
13// 2. Verify the email address
14await authix.requestEmailVerificationOTP(
15  userId: userId,
16  email: '[email protected]',
17);
18await authix.verifyEmail(email: '[email protected]', otp: '123456');
19
20// 3. Persist the session so it survives an app restart
21await persistSession();
22
23// 4. Store something for this user
24await authix.addUserData(
25  AddUserDataParams(
26    userId: userId,
27    dataCategory: 'notes',
28    data: {'title': 'My first note'},
29  ),
30);
31
32// 5. Log out
33await authix.logoutUser(onLoggedOut: forgetSession);