@oxyhq/services 26.0.1 → 26.0.4

package/lib/typescript/module/ui/session/backgroundSession.d.ts

@@ -0,0 +1,42 @@
+import type { OxyServices } from '@oxyhq/core';
+/** Whether this platform/app can hold a background credential at all. */
+export declare function isBackgroundSessionSupported(): boolean;
+/**
+ * Drop the stored credential. No-op where unsupported, and never throws.
+ *
+ * Called on sign-out and BEFORE an account switch's network work, so the window
+ * in which background code could still serve the previous account is as short as
+ * one local write.
+ */
+export declare function clearBackgroundSession(): Promise<void>;
+export interface BackgroundSessionSyncInput {
+    oxyServices: OxyServices;
+    /** The signed-in account, or `null` when signed out. */
+    userId: string | null;
+    /** Whether a bearer is available yet — provisioning requires one. */
+    canUsePrivateApi: boolean;
+    /**
+     * Whether this run is still the current one. A run that loses its relevance
+     * mid-flight (unmount, or another identity change) must not write the
+     * credential it was about to write.
+     */
+    isCurrent: () => boolean;
+}
+/**
+ * Bring the native credential in line with the session JS currently holds.
+ *
+ * Ordering is the load-bearing part: a credential belonging to a DIFFERENT
+ * account is cleared before any network call, so a crash mid-provision leaves
+ * background code signed out rather than serving the previous account's data
+ * under the new account's name. The server enforces the same rule independently
+ * (a mint is re-authorized against the live device session, and against its ACTIVE
+ * account), so this is the fast local half of a belt-and-braces pair, not the only
+ * guard.
+ *
+ * Throws for exactly one thing — a `@oxyhq/core` too old to provision (see
+ * {@link assertProvisioningAvailable}). Every other failure is caught and logged:
+ * a background credential is an enhancement, and failing to provision one must
+ * not disturb the session that is working.
+ */
+export declare function syncBackgroundSession(input: BackgroundSessionSyncInput): Promise<void>;
+//# sourceMappingURL=backgroundSession.d.ts.map

package/lib/typescript/module/ui/session/backgroundSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backgroundSession.d.ts","sourceRoot":"","sources":["../../../../../src/ui/session/backgroundSession.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAyG/C,yEAAyE;AACzE,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAa5D;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,WAAW,CAAC;IACzB,wDAAwD;IACxD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qEAAqE;IACrE,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC;CAC1B;AA8BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAqF5F"}

package/lib/typescript/module/ui/session/index.d.ts

@@ -13,6 +13,7 @@
 export { createSessionClient } from './createSessionClient.js';
 export { createTokenTransport } from './tokenTransport.js';
 export { createPlatformAuthStateStore } from './authStore.js';
+export { useBackgroundSessionSync } from './useBackgroundSessionSync.js';
 export { createIdentitySessionBinding, IdentityBoundSessionError } from './identityBinding.js';
 export type { IdentitySessionBinding } from './identityBinding.js';
 export { createSessionClientHost, accountIdsOf, activeSessionIdOf, activeUserOf, deviceStateToClientSessions, } from '@oxyhq/core';

package/lib/typescript/module/ui/session/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/ui/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAAuB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAkB,CAAC;AACxD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAa,CAAC;AAC3D,OAAO,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,MAAM,sBAAmB,CAAC;AAC5F,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAmB,CAAC;AAChE,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,2BAA2B,GAC5B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/ui/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAAuB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAkB,CAAC;AACxD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAa,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA4B,CAAC;AACtE,OAAO,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,MAAM,sBAAmB,CAAC;AAC5F,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAmB,CAAC;AAChE,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,2BAA2B,GAC5B,MAAM,aAAa,CAAC"}

package/lib/typescript/module/ui/session/useBackgroundSessionSync.d.ts

@@ -0,0 +1,23 @@
+import type { OxyServices } from '@oxyhq/core';
+export interface UseBackgroundSessionSyncInput {
+    /** `OxyProviderProps.backgroundSession`. */
+    enabled: boolean;
+    oxyServices: OxyServices;
+    /** The signed-in account, or `null` when signed out. */
+    userId: string | null;
+    /** Whether a bearer is available yet — provisioning needs one. */
+    canUsePrivateApi: boolean;
+}
+/**
+ * An effect is the right shape here, unusually for this codebase: the work is a
+ * side effect on native storage, and it has to react both to an identity change
+ * (a value) and to the app being foregrounded (a subscription). There is no
+ * derived-state or React Query formulation of "write a credential to the
+ * keystore when the user changes or the app comes back".
+ *
+ * Re-runs on identity change, which is what makes sign-out and account switching
+ * work: `syncBackgroundSession` clears a credential belonging to anyone other
+ * than `userId` before it does any network work.
+ */
+export declare function useBackgroundSessionSync({ enabled, oxyServices, userId, canUsePrivateApi, }: UseBackgroundSessionSyncInput): void;
+//# sourceMappingURL=useBackgroundSessionSync.d.ts.map

package/lib/typescript/module/ui/session/useBackgroundSessionSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBackgroundSessionSync.d.ts","sourceRoot":"","sources":["../../../../../src/ui/session/useBackgroundSessionSync.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO/C,MAAM,WAAW,6BAA6B;IAC5C,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;IACzB,wDAAwD;IACxD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,kEAAkE;IAClE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,WAAW,EACX,MAAM,EACN,gBAAgB,GACjB,EAAE,6BAA6B,GAAG,IAAI,CAgDtC"}

package/lib/typescript/module/ui/types/navigation.d.ts

@@ -54,11 +54,11 @@ export interface OxyProviderProps {
     authWebUrl?: string;
     authRedirectUri?: string;
     /**
-     * Authorize endpoint override for silent cross-origin session restore
-     * (web cross-app SSO on cold boot). Defaults to the production Oxy IdP
-     * (`https://auth.oxy.so/authorize`) when unset. Set this from an env var
-     * (e.g. Vite `VITE_OXY_AUTHORIZE_URL`, Expo `EXPO_PUBLIC_OXY_AUTHORIZE_URL`)
-     * so a local/staging deployment targets its own IdP instead of production.
+     * Authorize endpoint override for web "Sign in with Oxy". Defaults to the
+     * production Oxy IdP (`https://auth.oxy.so/authorize`) when unset. Set this
+     * from an env var (e.g. Vite `VITE_OXY_AUTHORIZE_URL`, Expo
+     * `EXPO_PUBLIC_OXY_AUTHORIZE_URL`) so a local/staging deployment targets its
+     * own IdP instead of production.
      */
     authorizeBaseUrl?: string;
     /**
@@ -78,9 +78,9 @@ export interface OxyProviderProps {
      * rather than hidden in the UI: `accounts` stays empty and is never fetched,
      * `switchToAccount` / `switchSession` reject with `IdentityBoundSessionError`,
      * `accountDialogController` is `null` and `openAccountDialog()` does nothing,
-     * and the two web OAuth cold-boot lanes (authorization-code return + silent
-     * cross-origin restore) are skipped — all of them commit whichever account
-     * the IdP resolves, which is not necessarily the local key's owner.
+     * and the web OAuth cold-boot lane (the authorization-code return leg) is
+     * skipped — it commits whichever account the IdP resolves, which is not
+     * necessarily the local key's owner.
      *
      * Read once at mount, like `baseURL` / `oxyServices`: changing it on a
      * mounted provider does not re-bind the session.
@@ -90,22 +90,23 @@ export interface OxyProviderProps {
     /**
      * How a WEB third-party "Sign in with Oxy" hands the user to the IdP.
      *
-     * - `'redirect'` (default) — a full-page navigation to `auth.oxy.so`, which
-     *   returns to the registered `redirect_uri` with `?code=`. The tab unmounts
-     *   and remounts, so route and unsaved state are lost.
-     * - `'popup'` — a small `auth.oxy.so` window opened from the user's click.
-     *   The app stays MOUNTED and becomes authenticated without a reload; the
-     *   IdP delivers only the authorization code + `state` back to the opener
-     *   via `postMessage` (never a token, device secret, or PKCE verifier). A
-     *   blocked popup falls back to the redirect automatically.
+     * - `'popup'` (default) — a small `auth.oxy.so` window opened from the
+     *   user's click. The app stays MOUNTED and becomes authenticated without a
+     *   reload; the IdP delivers only the authorization code + `state` back to
+     *   the opener via `postMessage` (never a token, device secret, or PKCE
+     *   verifier). A blocked popup falls back to the redirect automatically.
+     * - `'redirect'` — a full-page navigation to `auth.oxy.so`, which returns to
+     *   the registered `redirect_uri` with `?code=`. The tab unmounts and
+     *   remounts, so route and unsaved state are lost.
+     *
+     * Either way the navigation only ever happens from a real user gesture: the
+     * SDK never bounces the top-level window on its own (#691 phase 7b).
      *
      * Native is unaffected — it always uses an in-app auth session.
-     * @default 'redirect'
+     * @default 'popup'
      */
     webAuthMode?: WebAuthMode;
     queryClient?: QueryClient;
-    /** Sync device credentials to auth.oxy.so after interactive sign-in. @default true */
-    hubSync?: boolean;
     /**
      * Convenience: wrap the whole app subtree in `<RequireOxyAuth prompt=...>`.
      * `off` (default) renders children unconditionally; `soft` adds a dismissible
@@ -115,5 +116,12 @@ export interface OxyProviderProps {
      * @default 'off'
      */
     requireAuth?: 'off' | 'soft' | 'hard';
+    /**
+     * When true, provisions a non-rotating background credential for native code
+     * (Android widgets) that runs without a JS runtime. Android-only today; inert
+     * on web and iOS.
+     * @default false
+     */
+    backgroundSession?: boolean;
 }
 //# sourceMappingURL=navigation.d.ts.map

package/lib/typescript/module/ui/types/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../../src/ui/types/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAgB,CAAC;AAElD,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,MAAM,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAE5B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACxE,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,eAAe,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGrC,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAGlC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAGjE,aAAa,CAAC,EAAE,SAAS,CAAC;IAG1B,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IAMtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;CACzC"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../../src/ui/types/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAsB,CAAC;AAEtD,OAAO,KAAK,EAAiB,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAgB,CAAC;AAElD,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,MAAM,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAE5B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACxE,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,eAAe,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGrC,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAGlC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD,YAAY,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAGjE,aAAa,CAAC,EAAE,SAAS,CAAC;IAG1B,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAGnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IAMtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACtC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC/B"}

package/lib/typescript/module/ui/utils/fileManagement.d.ts

@@ -1,6 +1,6 @@
-import type Ionicons from '@expo/vector-icons/Ionicons';
-import type { AssetUploadInput, RNFileDescriptor } from '@oxyhq/core';
-import type { ComponentProps } from 'react';
+import type Ionicons from "@expo/vector-icons/Ionicons";
+import type { AssetUploadInput, RNFileDescriptor } from "@oxyhq/core";
+import type { ComponentProps } from "react";
 /**
  * Extended File interface that includes a `uri` property for mobile preview support.
  * React Native file pickers return URI-based references that need to be preserved
@@ -33,7 +33,7 @@ export declare function formatFileSize(bytes: number): string;
 /**
  * Get icon name for file based on content type
  */
-export declare function getFileIcon(contentType: string): ComponentProps<typeof Ionicons>['name'];
+export declare function getFileIcon(contentType: string): ComponentProps<typeof Ionicons>["name"];
 /**
  * Convert a document/image picker asset into a value that
  * `OxyServices.assetUpload` can accept.
@@ -50,6 +50,6 @@ export declare function convertDocumentPickerAssetToFile(doc: PickerAsset, index
 /**
  * Upload file raw - helper function for file uploads
  */
-export declare function uploadFileRaw(file: AssetUploadInput, userId: string, oxyServices: any, visibility?: 'private' | 'public' | 'unlisted'): Promise<any>;
+export declare function uploadFileRaw(file: AssetUploadInput, userId: string, oxyServices: any, visibility?: "private" | "public" | "unlisted"): Promise<any>;
 export {};
 //# sourceMappingURL=fileManagement.d.ts.map

package/lib/typescript/module/ui/utils/fileManagement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fileManagement.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/fileManagement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,6BAA6B,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAG5C;;;;GAIG;AACH,UAAU,WAAY,SAAQ,IAAI;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAO5E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CASxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gCAAgC,CAClD,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAAC,CA4DhD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAC/B,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,MAAM,EAEd,WAAW,EAAE,GAAG,EAChB,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,gBAGjD"}
+{"version":3,"file":"fileManagement.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/fileManagement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,6BAA6B,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAG5C;;;;GAIG;AACH,UAAU,WAAY,SAAQ,IAAI;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAO5E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAC1B,WAAW,EAAE,MAAM,GACjB,cAAc,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAYzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gCAAgC,CACrD,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAAC,CAuEhD;AAED;;GAEG;AACH,wBAAsB,aAAa,CAClC,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,MAAM,EAEd,WAAW,EAAE,GAAG,EAChB,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,gBAG9C"}

package/lib/typescript/module/ui/utils/netConnectivity.d.ts

@@ -0,0 +1,17 @@
+export interface NetInfoLikeState {
+    isConnected: boolean | null;
+    isInternetReachable?: boolean | null;
+}
+/**
+ * Mirrors Bloom `ConnectionStatusToasts` reachability semantics: a link that
+ * reports connected but explicitly unreachable (captive portal, no route) counts
+ * as offline.
+ */
+export declare function isNetConnectivityOnline(state: NetInfoLikeState): boolean;
+/**
+ * Conservative offline verdict for boot-path probes. Unknown / probing states
+ * (`null`, timed-out fetch) resolve to "not offline" so a flaky probe never
+ * skips a real sign-in.
+ */
+export declare function isNetConnectivityExplicitlyOffline(state: NetInfoLikeState | null | undefined): boolean;
+//# sourceMappingURL=netConnectivity.d.ts.map

package/lib/typescript/module/ui/utils/netConnectivity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"netConnectivity.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/netConnectivity.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,mBAAmB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAExE;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACzC,OAAO,CAKT"}

package/lib/typescript/module/ui/utils/oauthReturn.d.ts

@@ -4,12 +4,21 @@ import type { OAuthSessionCommitInput } from '../oauth/types.js';
  * When the RP lands with `?code=` after signing in at auth.oxy.so, exchange the
  * code for a device-first session before cold boot runs.
  *
- * This is the REDIRECT transport's return leg. It owns only what is specific to
- * a full-page round trip — reading the code off the URL, recovering the
- * handshake `sessionStorage` carried across the navigation, and cleaning both up
- * afterwards — and delegates state validation, the PKCE exchange, and the
- * session commit to `completeOAuthCode`, the same function the popup transport
- * runs.
+ * This is the REDIRECT transport's return leg. The SDK never starts a full-page
+ * authorize navigation on its own any more (#691 phase 7b), but this lane is
+ * still load-bearing: a browser-BLOCKED sign-in popup falls back to a full-page
+ * redirect (`startWebOAuthSignIn`), and that redirect comes back here.
+ *
+ * It owns only what is specific to a full-page round trip — reading the code off
+ * the URL, recovering the handshake `sessionStorage` carried across the
+ * navigation, and cleaning both up afterwards — and delegates state validation,
+ * the PKCE exchange, and the session commit to `completeOAuthCode`, the same
+ * function the popup transport runs.
+ *
+ * It is also the SINGLE cleanup path for an OAuth `error` landing on the URL:
+ * any `?error=…` (including an `error=login_required` left over from the
+ * now-deleted silent restore) is stripped along with `state` /
+ * `error_description`, and the stale PKCE handshake is cleared.
  */
 export declare function tryCompleteOAuthReturn(opts: {
     oxyServices: OxyServices;
@@ -36,10 +45,4 @@ export declare function tryCompleteOAuthReturn(opts: {
  * not push a spurious event at every listener on the page.
  */
 export declare function replaceUrlAfterOAuthReturn(fallbackUrl: string): void;
-/**
- * When auth.oxy.so hub-sync redeem fails, the IdP redirects back with
- * `?hub_sync=failed`. Strip the param and log so cold boot can continue
- * without leaving a stale query string.
- */
-export declare function consumeHubSyncFailure(): boolean;
 //# sourceMappingURL=oauthReturn.d.ts.map

package/lib/typescript/module/ui/utils/oauthReturn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauthReturn.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/oauthReturn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAS/C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAgB,CAAC;AAG9D;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE,GAAG,OAAO,CAAC,OAAO,CAAC,CAwCnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAuBpE;AAeD;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAgB/C"}
+{"version":3,"file":"oauthReturn.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/oauthReturn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAS/C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAgB,CAAC;AAG9D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE,GAAG,OAAO,CAAC,OAAO,CAAC,CA6CnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAuBpE"}

package/lib/typescript/module/ui/utils/userUtils.d.ts

@@ -1,9 +1,9 @@
 /**
  * User display name and date formatting utilities.
  *
- * The display-name helpers are thin wrappers around the canonical
- * `getAccountDisplayName` in `@oxyhq/core`, which handles all the edge cases
- * (missing username, missing name, fallback to truncated `publicKey`, i18n).
+ * Display-name helpers follow the API contract: prefer `name.displayName` when
+ * present, otherwise fall back to the normalized handle via
+ * `getNormalizedUserHandle`.
  */
 import { type DisplayNameUserShape } from '@oxyhq/core';
 /**
@@ -13,18 +13,11 @@ export declare const formatDate: (dateString: string | undefined | null | Date)
 /**
  * Gets a display name from user data.
  *
- * Prefers full name → composed first+last → username → `Account 0x12345678…`
- * (derived from publicKey) → translated "Unnamed".
- *
- * @param user - User-like object with optional name/username/publicKey
- * @param locale - Optional locale for the final fallback label
+ * Prefers API `name.displayName`, then the normalized handle.
  */
-export declare const getDisplayName: (user: DisplayNameUserShape | null | undefined, locale?: string) => string;
+export declare const getDisplayName: (user: DisplayNameUserShape | null | undefined) => string;
 /**
- * Gets a short display name (first name or username).
- *
- * Used for compact UI (e.g. greetings). Falls back to the full display name
- * helper, which also handles publicKey-only accounts.
+ * Gets a short display name (first token) for compact UI.
  */
-export declare const getShortDisplayName: (user: DisplayNameUserShape | null | undefined, locale?: string) => string;
+export declare const getShortDisplayName: (user: DisplayNameUserShape | null | undefined) => string;
 //# sourceMappingURL=userUtils.d.ts.map

package/lib/typescript/module/ui/utils/userUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"userUtils.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/userUtils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,YAAY,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,KAAG,MAezE,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,oBAAoB,GAAG,IAAI,GAAG,SAAS,EAC7C,SAAS,MAAM,KACd,MAAiD,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,oBAAoB,GAAG,IAAI,GAAG,SAAS,EAC7C,SAAS,MAAM,KACd,MAiBF,CAAC"}
+{"version":3,"file":"userUtils.d.ts","sourceRoot":"","sources":["../../../../../src/ui/utils/userUtils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA2B,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEjF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,YAAY,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,KAAG,MAezE,CAAC;AAQF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,oBAAoB,GAAG,IAAI,GAAG,SAAS,KAC5C,MAIF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,oBAAoB,GAAG,IAAI,GAAG,SAAS,KAC5C,MAcF,CAAC"}

package/lib/typescript/types/expo-image-picker.d.ts

@@ -0,0 +1,35 @@
+declare module 'expo-image-picker' {
+    export interface ImagePickerAsset {
+        uri: string;
+        width: number;
+        height: number;
+    }
+
+    export interface ImagePickerSuccessResult {
+        canceled: false;
+        assets: ImagePickerAsset[];
+    }
+
+    export interface ImagePickerCanceledResult {
+        canceled: true;
+        assets: null;
+    }
+
+    export type ImagePickerResult = ImagePickerSuccessResult | ImagePickerCanceledResult;
+
+    export interface ImagePickerPermission {
+        granted: boolean;
+        canAskAgain: boolean;
+    }
+
+    export interface ImagePickerOptions {
+        mediaTypes?: 'images'[];
+        allowsMultipleSelection?: boolean;
+        quality?: number;
+    }
+
+    export function launchImageLibraryAsync(options?: ImagePickerOptions): Promise<ImagePickerResult>;
+    export function launchCameraAsync(options?: ImagePickerOptions): Promise<ImagePickerResult>;
+    export function requestMediaLibraryPermissionsAsync(): Promise<ImagePickerPermission>;
+    export function requestCameraPermissionsAsync(): Promise<ImagePickerPermission>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/services",
-  "version": "26.0.1",
+  "version": "26.0.4",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -60,6 +60,18 @@
       },
       "default": "./lib/module/ui/server.js"
     },
+    "./notifications": {
+      "react-native": "./src/notifications/deviceNotifications.ts",
+      "import": {
+        "types": "./lib/typescript/module/notifications/deviceNotifications.d.ts",
+        "default": "./lib/module/notifications/deviceNotifications.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/notifications/deviceNotifications.d.ts",
+        "default": "./lib/commonjs/notifications/deviceNotifications.js"
+      },
+      "default": "./lib/module/notifications/deviceNotifications.js"
+    },
     "./plugins/*": "./plugins/*.js",
     "./expo-module.config.json": "./expo-module.config.json",
     "./package.json": "./package.json"
@@ -126,17 +138,16 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "0.17.0",
-    "@oxyhq/core": "^12.10.6",
+    "@oxyhq/contracts": "0.21.0",
     "@simplewebauthn/browser": "^13.3.0",
     "color": "^4.2.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
-    "@commitlint/cli": "^17.6.5",
-    "@commitlint/config-conventional": "^17.6.5",
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
     "@expo/vector-icons": "^15.0.3",
-    "@oxyhq/core": "12.10.6",
+    "@oxyhq/core": "17.0.2",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^11.4.1",
     "@react-native/babel-preset": "^0.86.0",
@@ -157,12 +168,13 @@
     "expo-image": "~57.0.1",
     "expo-linear-gradient": "~57.0.1",
     "expo-notifications": "~57.0.5",
+    "expo-web-browser": "~57.0.1",
     "husky": "^4.3.8",
     "jest": "~29.7.0",
     "lint-staged": "^15.2.4",
     "nativewind": "5.0.0-preview.3",
     "react-native-builder-bob": "^0.43.0",
-    "react-native-css": "^3.0.0",
+    "react-native-css": "^3.0.6",
     "react-native-gesture-handler": "~2.32.0",
     "react-native-keyboard-controller": "1.21.13",
     "react-native-qrcode-svg": "^6.3.0",
@@ -178,9 +190,9 @@
   "peerDependencies": {
     "@expo/vector-icons": "^15.0.3",
     "@oxyhq/bloom": ">=0.59.0",
-    "@oxyhq/core": "^12.10.6",
+    "@oxyhq/core": "^17.0.2",
     "@react-native-async-storage/async-storage": "^2.0.0",
-    "@react-native-community/netinfo": "^11.4.1",
+    "@react-native-community/netinfo": ">=11.4.1",
     "@tanstack/query-async-storage-persister": "^5.101",
     "@tanstack/query-sync-storage-persister": "^5.101",
     "@tanstack/react-query": "^5.101",
@@ -196,16 +208,18 @@
     "expo-image-manipulator": ">=56.0.0",
     "expo-image-picker": ">=56.0.0",
     "expo-linear-gradient": ">=56.0.0",
-    "expo-notifications": ">=56.0.0",
     "expo-modules-core": "*",
+    "expo-notifications": ">=56.0.0",
+    "expo-web-browser": ">=56.0.0",
     "nativewind": ">=5.0.0",
+    "react-native-css": "^3.0.6",
     "react": ">=18.0.0",
     "react-native": ">=0.85.0",
-    "react-native-gesture-handler": "~2.32.0",
+    "react-native-gesture-handler": ">=2.31.1",
     "react-native-keyboard-controller": ">=1.21.0",
     "react-native-qrcode-svg": "^6.3.0",
     "react-native-reanimated": ">=4.3.0",
-    "react-native-safe-area-context": "~5.8.0",
+    "react-native-safe-area-context": ">=5.7.0",
     "react-native-svg": ">=15.15.0",
     "socket.io-client": "^4.8.0",
     "zustand": "^5.0.0"
@@ -214,6 +228,9 @@
     "nativewind": {
       "optional": true
     },
+    "react-native-css": {
+      "optional": true
+    },
     "expo-modules-core": {
       "optional": true
     },
@@ -252,6 +269,9 @@
     },
     "expo-image-picker": {
       "optional": true
+    },
+    "expo-web-browser": {
+      "optional": true
     }
   },
   "react-native-builder-bob": {

package/src/index.ts

@@ -201,23 +201,25 @@ export { useFileFiltering } from './ui/hooks/useFileFiltering';
 export type { ViewMode, SortBy, SortOrder } from './ui/hooks/useFileFiltering';
 
 // ---------------------------------------------------------------------------
-// Device notifications (the ONE `expo-notifications` adapter)
+// Device notifications — DELIBERATELY NOT EXPORTED HERE
 // ---------------------------------------------------------------------------
-// The Expo-side half of push: permission, platform tag, and the EXPO push token
-// `@oxyhq/core`'s `registerPushToken` accepts (never a raw APNs/FCM token).
-// Native-only by construction — every entry point resolves its null/no-op result
-// from `Platform.OS` before `expo-notifications` is ever imported, and both
-// `expo-notifications` and `expo-constants` are OPTIONAL peers.
-export {
-    pushTokenPlatform,
-    hasNotificationPermission,
-    requestNotificationPermission,
-    getExpoPushToken,
-    takeLaunchNotificationData,
-    installForegroundNotificationHandler,
-    subscribeToNotificationResponses,
-} from './notifications/deviceNotifications';
-export type { ForegroundPresentation } from './notifications/deviceNotifications';
+// The `expo-notifications` adapter lives behind its own entry point:
+//
+//     import { getExpoPushToken } from '@oxyhq/services/notifications';
+//
+// It is the one module in this package whose dependencies (`expo-notifications`
+// and `expo-constants`) are optional peers that an app which does not use push
+// genuinely never installs. Re-exporting it from THIS barrel is what made that
+// optionality a lie: a barrel export puts the module in the import graph of
+// every consumer, and `tsc` must resolve the specifier of an `import()` even
+// when the call is lazy and wrapped in try/catch — so every consumer without
+// `expo-notifications` failed with TS2307 (plus TS7006 cascades) whether or not
+// it had ever heard of push. Behind a subpath the module is only ever pulled in
+// by an app that asked for it, which is what "optional peer" is supposed to
+// mean.
+//
+// Do NOT re-add these exports here. `__tests__/notifications/barrelIsolation.test.ts`
+// fails if you do.
 
 // ---------------------------------------------------------------------------
 // UI components
@@ -273,6 +275,7 @@ export { LogoText } from './ui/components/logo/LogoText';
 // `useOxy().openAccountDialog`.
 export { default as ProfileButton } from './ui/components/ProfileButton';
 export type { ProfileButtonProps } from './ui/components/ProfileButton';
+export type { AccountDialogMenuItem } from './ui/navigation/accountDialogManager';
 
 // The account switcher/sign-in/sign-up chooser WITHOUT dialog chrome — the
 // surface stack presents `OxyAccountDialogScreen` (which renders this) into

package/src/notifications/deviceNotifications.ts

@@ -8,6 +8,25 @@
  * already lives in `@oxyhq/core`; core may never import an `expo-*` module, and
  * this adapter is the Expo-side half that closes that gap.
  *
+ * ## Reached through its OWN entry point, never the root barrel
+ *
+ * ```ts
+ * import { getExpoPushToken } from '@oxyhq/services/notifications';
+ * ```
+ *
+ * This is the only module in the package that depends on peers an app which
+ * does not use push genuinely never installs, and a barrel export would put it
+ * in EVERY consumer's import graph. `tsc` resolves the specifier of an
+ * `import()` even when the call is lazy and inside a try/catch, so a barrel
+ * export turned "optional peer" into a hard requirement: consumers with no
+ * interest in push failed to type-check with TS2307. The subpath is what keeps
+ * the optionality honest — see the note in `src/index.ts`.
+ *
+ * Metro is the resolver that behaves differently here, and in the useful
+ * direction: an unresolvable DYNAMIC `import()` bundles fine (the `catch` below
+ * takes over at runtime), where a static import fails the build outright. That
+ * is why the runtime shape below must stay dynamic-and-guarded.
+ *
  * ## Native-only by construction
  *
  * Every entry point resolves its null/no-op result from `Platform.OS` BEFORE the
@@ -297,6 +316,69 @@ export type ForegroundPresentation = 'show' | 'suppress';
  */
 let foregroundHandlerAttempted = false;
 
+/** How prominently Android surfaces a channel's notifications. */
+export type NotificationChannelImportance = 'default' | 'high';
+
+/** An Android notification channel this app delivers on. */
+export interface NotificationChannelSpec {
+  /**
+   * The channel id. It MUST match the id the sender attaches: Android 8+ drops
+   * a notification whose channel the app has not created, silently and with no
+   * error on either side, which is the hardest push symptom there is to
+   * diagnose. Ids that cross the wire belong in `@oxyhq/contracts`, not in a
+   * string typed on both sides.
+   */
+  id: string;
+  /** User-visible channel name — app copy, so the caller localizes it. */
+  name: string;
+  /** User-visible description shown in Android's notification settings. */
+  description?: string;
+  importance?: NotificationChannelImportance;
+}
+
+/**
+ * Create (or update) an Android notification channel.
+ *
+ * A no-op everywhere but Android: iOS has no channels, and web never loads the
+ * native module. Call it BEFORE registering a push token, so the very first
+ * notification the server sends already has a channel to land on.
+ *
+ * Failure is non-fatal and logged: a missing channel costs visibility, and
+ * refusing to register a token over it would cost the feature entirely.
+ *
+ * @returns Whether the channel was actually created (`false` off Android, or
+ *   when the native module is unavailable, or when creation failed).
+ */
+export async function ensureNotificationChannel(
+  spec: NotificationChannelSpec,
+): Promise<boolean> {
+  if (Platform.OS !== 'android') {
+    return false;
+  }
+  const notifications = await loadNotifications();
+  if (!notifications) {
+    return false;
+  }
+  try {
+    await notifications.setNotificationChannelAsync(spec.id, {
+      name: spec.name,
+      importance:
+        spec.importance === 'high'
+          ? notifications.AndroidImportance.HIGH
+          : notifications.AndroidImportance.DEFAULT,
+      ...(spec.description ? { description: spec.description } : {}),
+    });
+    return true;
+  } catch (error) {
+    log.warn(
+      'could not create the notification channel',
+      { method: 'ensureNotificationChannel', channelId: spec.id },
+      error,
+    );
+    return false;
+  }
+}
+
 /**
  * Install the ONE process-wide handler that decides whether an incoming
  * notification is shown while the app is in the FOREGROUND.