@aria-framework/mobile

The phone half of an Aria app, for Expo SDK 57 / React Native. It's extracted from Support101 Field, where it ran in production.

The server half is already shared. Every Aria server speaks the same /api/v1 contract through @aria-framework/api-auth and aria-starter's routes/api/:

• auth/login | refresh | logout | entra/config | entra/exchange | me;
• push/register | unregister;
• notifications.

This package is the client for that contract.

| Import | What | |---|---| | @aria-framework/mobile/client | createClient({ storagePrefix }): server URL and tokens in SecureStore, single-flight refresh on 401, Entra PKCE, authed downloads plus a cache keyed per server, multipart upload, notifications, push registration. Also ApiError, AuthError, mimeFor. | | …/auth | <AuthProvider client appName push onSignedIn onSignedOut> and useAuth(): local and Microsoft sign-in (the deep-link race handled), restore on launch. | | …/push | createPush({ client }): Expo token registration, the Settings switch, the Android channel. | | …/unread | useUnread(client, onPoll?): the bell count (on focus, and every 30 s in the foreground). | | …/keyboard | useKeyboardLift(scrollRef): low fields above the keyboard on edge-to-edge Android. | | …/haptics, …/time | hapticSuccess/Tap; utcMs, ago, fmtBytes (server timestamps are UTC). | | …/screens | LoginScreen, NotificationsScreen, and Settings cards (AccountCard, AppearanceCard, ServerCard, PushCard, CacheCard, ToggleCard, SignOutButton, VersionFooter), built on @aria-framework/theme. | | …/notifications | notificationSections(items) and tint(hex, alpha): the list's grouping and unread colour, as plain functions. |

0.4.0 — extra headers, for an offline outbox:

• request(method, path, body, { headers }) and upload(path, uri, mime, params, name, { headers }) add headers to the call — an outbox sends each queued write with an Idempotency-Key, so a replay the server already handled is answered from its record instead of done twice. Both arguments are optional: every existing call is unchanged.
• upload failures are classified like request's: no response, a 5xx or a 429 → NetworkError (try again later); any other non-2xx stays an ApiError.

0.3.0 — a dead zone is not a sign-out:

• NetworkError (a subclass of ApiError, so existing checks keep working): no response at all (status 0), a 5xx, or a 429. The request did not happen and the session is intact — tell it apart from AuthError (sign in again).
• A refresh that could not be ASKED keeps the session. Before 0.3.0 any failed refresh cleared it: an access token expiring with no signal, or during a server restart, signed the user out. Now only an answered rejection (400/401/403) does; everything else throws NetworkError and the next request tries again.
• A refresh whose answer is lost (rotated on the server, never received) keeps the OLD token, so the retry presents it again — pair with @aria-framework/api-auth 0.6.0's reuseGraceSeconds so that retry is not read as theft.

0.2.0:

• LoginScreen has "Forgot password?": email, then the 6-digit code alone, then the new password, then it signs in. It needs the server's POST /api/v1/auth/forgot, /verify-code and /reset (Support101 v0.371.0). The client calls are forgotPassword, verifyResetCode and resetPassword; a server without them answers 404, which shows as an error on the email step.
• NotificationsScreen matches the web bell (@aria-framework/notify 0.4.0): unread cards have a brand tint, a left edge, a dot and a semibold title; read cards fade; "NEW (n)" and "EARLIER" headers appear only when both groups exist.

Wiring (one module in the app)

// src/api.ts
import { createClient } from "@aria-framework/mobile/client";
export const client = createClient({ storagePrefix: "ops" });   // UNIQUE per app on one phone
export const request = client.request;                           // your endpoints build on this

// src/push.ts
import { createPush } from "@aria-framework/mobile/push";
export const push = createPush({ client });

// App.tsx
<ThemeProvider storageKey="ops.theme">
  <AuthProvider client={client} appName="Ops101" push={push}> … </AuthProvider>
</ThemeProvider>

Create the client and push once, at module level, never inside a component.

Rules

• storagePrefix must be unique per app. Keys are ${prefix}_access, _refresh, _user, _base_url, _entra_pkce, _cache_swept, _push_enabled, _push_token. Support101 uses s101, which is exactly its pre-package layout, so its users stayed signed in.

• The app's expo.scheme (app.json) is the Microsoft sign-in return (<scheme>://auth-callback). It must be unique per app, and the server's mobile return URL must match it.

• Native modules are peer dependencies. Install them in the app with npx expo install so their versions match the SDK:

  • always needed: expo-secure-store, expo-crypto, expo-file-system, @react-native-async-storage/async-storage;
  • per subpath: expo-constants, expo-web-browser, expo-notifications, expo-haptics, @react-navigation/native, @aria-framework/theme.

  Every peer is declared optional in peerDependenciesMeta, as @aria-framework/theme does. npm 7+ otherwise installs required peers itself, which put the whole React Native / Expo tree (about 6,800 lockfile lines) into this monorepo. An Expo app always has the always-needed four anyway.

• Expo Go cannot run it (remote push left Expo Go at SDK 53). Use a development build.

• An Expo SDK upgrade is a release of this package. Bump the peer ranges and the SDK in the description, then each app follows.

Tests

npm test compiles, then runs the logic from dist/ in plain Node with the Expo modules stubbed (test/_stubs.js):

• client: storage keys, single-flight refresh, failed refresh → AuthError, PKCE, server switch, downloads, uploads;
• the pure helpers;
• push;
• the export surface.

The screens are verified on a device or emulator, in the app.