@marktiderman/genesis-native 0.1.0 → 0.3.0

package/src/push/modules.ts

@@ -0,0 +1,111 @@
+/**
+ * What the push block reads from `expo-notifications` (SDK 58) and the app's
+ * backend, as the shapes it needs. Pass the real module
+ * (`import * as Notifications from "expo-notifications"`); tests pass fakes.
+ * Every call here was checked against expo-notifications 58.1's own type
+ * declarations.
+ */
+
+/** `{ remove() }`, as every expo-notifications listener returns. */
+export interface SubscriptionLike {
+  remove(): void;
+}
+
+/** `NotificationPermissionsStatus`: Expo's `PermissionResponse` plus the iOS detail. */
+export interface PermissionStatusLike {
+  status: "granted" | "denied" | "undetermined" | string;
+  granted: boolean;
+  canAskAgain: boolean;
+  /** `IosAuthorizationStatus`: 0 not determined, 1 denied, 2 authorized, 3 provisional, 4 ephemeral. */
+  ios?: { status: number } | null;
+}
+
+/** `NotificationPermissionsRequest`: iOS options; Android asks for posting notifications. */
+export interface PermissionRequestLike {
+  ios?: { allowAlert?: boolean; allowBadge?: boolean; allowSound?: boolean; allowProvisional?: boolean };
+}
+
+/** The parts of a received notification the block reads. */
+export interface NotificationLike {
+  request: {
+    identifier: string;
+    content: { data?: Record<string, unknown> | null; title?: string | null };
+  };
+}
+
+/** A tap (or an action) on a notification. */
+export interface NotificationResponseLike {
+  notification: NotificationLike;
+  actionIdentifier: string;
+}
+
+/** `NotificationBehavior` without the deprecated `shouldShowAlert`. */
+export interface NotificationBehaviorLike {
+  shouldShowBanner: boolean;
+  shouldShowList: boolean;
+  shouldPlaySound: boolean;
+  shouldSetBadge: boolean;
+}
+
+/** `NotificationChannelInput`, the fields the block sets. Importance and visibility are Expo's enum numbers. */
+export interface ChannelInputLike {
+  name: string;
+  importance: number;
+  description?: string | null;
+  /** `AndroidNotificationVisibility`: 1 public, 2 private (content hidden on a secure lock screen), 3 secret. */
+  lockscreenVisibility?: number;
+  showBadge?: boolean;
+}
+
+/** `expo-notifications` (SDK 58). */
+export interface NotificationsModuleLike {
+  getPermissionsAsync(): Promise<PermissionStatusLike>;
+  requestPermissionsAsync(request?: PermissionRequestLike): Promise<PermissionStatusLike>;
+  /** Pass the EAS project id: without one there is no Expo push token. */
+  getExpoPushTokenAsync(options: { projectId: string }): Promise<{ data: string }>;
+  /** Fires when the OS hands the app a new device token; the Expo token is fetched again then. */
+  addPushTokenListener(listener: (token: unknown) => void): SubscriptionLike;
+  /** Android only (a no-op elsewhere). Must run before the permission prompt and the token on Android 13+. */
+  setNotificationChannelAsync(channelId: string, channel: ChannelInputLike): Promise<unknown>;
+  setNotificationHandler(handler: { handleNotification: (notification: NotificationLike) => Promise<NotificationBehaviorLike> } | null): void;
+  addNotificationResponseReceivedListener(listener: (response: NotificationResponseLike) => void): SubscriptionLike;
+  /** The tap that launched the app (synchronous since SDK 53). */
+  getLastNotificationResponse(): NotificationResponseLike | null;
+  clearLastNotificationResponse(): void;
+  setBadgeCountAsync(count: number): Promise<boolean>;
+  getBadgeCountAsync(): Promise<number>;
+  /** `"expo.modules.notifications.actions.DEFAULT"`: the person tapped the notification itself. */
+  DEFAULT_ACTION_IDENTIFIER: string;
+}
+
+/** AsyncStorage, MMKV's async adapter, or a stand-in. */
+export interface PushStorageLike {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem?(key: string): Promise<void>;
+}
+
+/** React Native's `AppState`. */
+export interface PushAppStateLike {
+  addEventListener(type: "change", listener: (state: string) => void): { remove(): void };
+}
+
+/** Where a reported error came from. */
+export type PushErrorSource = "permission" | "register" | "forget" | "preferences" | "badge" | "channels" | "routing" | "storage" | "setup";
+
+export type PushOnError = (error: Error, source: PushErrorSource) => void;
+
+export function toError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  const message = (value as { message?: unknown } | null)?.message;
+  return new Error(typeof message === "string" ? message : typeof value === "string" ? value : "Unknown error");
+}
+
+/** Calls the reporter, never letting a failing one break the block. */
+export function report(onError: PushOnError | undefined, error: unknown, source: PushErrorSource) {
+  try {
+    onError?.(toError(error), source);
+  } catch {
+    // ignore a failing reporter
+  }
+}

package/src/push/permission.ts

@@ -0,0 +1,191 @@
+/**
+ * Notification permission, and the soft pre-prompt that comes before the
+ * system's.
+ *
+ * The system prompt can be shown once: a person who says no there has to find
+ * the app in Settings to change it. So the block never asks at launch. The
+ * app calls `prompt.offer()` at the moment push is worth it (they sent their
+ * first message, set a reminder) and the block shows its own sheet first,
+ * saying why; only "Turn on" in that sheet (a tap) brings up the system
+ * prompt. "Not now" waits `cooldownMs` before the sheet can show again, and
+ * after `maxDeclines` it never offers again (Settings still can).
+ */
+import { createStore, type Store } from "../updates/store";
+import { report, type NotificationsModuleLike, type PermissionRequestLike, type PermissionStatusLike, type PushOnError, type PushStorageLike } from "./modules";
+
+/**
+ * `unknown` before the first read; `undetermined` the system can still ask;
+ * `granted`; `provisional` (iOS delivers quietly to Notification Center);
+ * `denied` only Settings can change; `unavailable` no notifications module.
+ */
+export type PushPermissionStatus = "unknown" | "undetermined" | "granted" | "provisional" | "denied" | "unavailable";
+
+export interface PermissionState {
+  status: PushPermissionStatus;
+  /** The system prompt is up. */
+  requesting: boolean;
+}
+
+export interface PermissionStore extends Store<PermissionState> {
+  /** Read the status without asking (no prompt). */
+  refresh(): Promise<PushPermissionStatus>;
+  /** Show the system prompt (only after a tap); resolves to the new status. */
+  request(): Promise<PushPermissionStatus>;
+}
+
+const IOS_PROVISIONAL = 3;
+const IOS_EPHEMERAL = 4;
+
+/** Expo's answer as one status. Android "denied but can ask again" is still askable. */
+export function statusOf(response: PermissionStatusLike): PushPermissionStatus {
+  const ios = response.ios?.status;
+  if (ios === IOS_PROVISIONAL) return "provisional";
+  if (response.granted || response.status === "granted" || ios === IOS_EPHEMERAL) return "granted";
+  if (response.status === "undetermined" || response.canAskAgain) return "undetermined";
+  return "denied";
+}
+
+export const canPush = (status: PushPermissionStatus) => status === "granted" || status === "provisional";
+
+export function createPermissionStore(options: {
+  notifications?: NotificationsModuleLike;
+  request?: PermissionRequestLike;
+  /** Runs before the system prompt (Android 13 shows it only once a channel exists). */
+  beforeRequest?: () => Promise<void>;
+  onError?: PushOnError;
+}): PermissionStore {
+  const { notifications, onError } = options;
+  const store = createStore<PermissionState>({ status: notifications ? "unknown" : "unavailable", requesting: false });
+  return {
+    ...store,
+    async refresh() {
+      if (!notifications) return "unavailable";
+      try {
+        const status = statusOf(await notifications.getPermissionsAsync());
+        store.setState({ status });
+        return status;
+      } catch (error) {
+        report(onError, error, "permission");
+        return store.getState().status;
+      }
+    },
+    async request() {
+      if (!notifications) return "unavailable";
+      if (store.getState().requesting) return store.getState().status;
+      store.setState({ requesting: true });
+      try {
+        await options.beforeRequest?.().catch((error) => report(onError, error, "channels"));
+        const status = statusOf(await notifications.requestPermissionsAsync(options.request ?? DEFAULT_REQUEST));
+        store.setState({ status });
+        return status;
+      } catch (error) {
+        report(onError, error, "permission");
+        return store.getState().status;
+      } finally {
+        store.setState({ requesting: false });
+      }
+    },
+  };
+}
+
+const DEFAULT_REQUEST: PermissionRequestLike = { ios: { allowAlert: true, allowBadge: true, allowSound: true } };
+
+export interface PromptOptions {
+  /** After "Not now", how long before the sheet may show again. Default 3 days. */
+  cooldownMs?: number;
+  /** After this many "Not now"s it never offers again. Default 3. */
+  maxDeclines?: number;
+  /** `offer()` is ignored this long after the block starts, so no screen can ask at launch. Default 10 s. */
+  launchGraceMs?: number;
+}
+
+export interface PromptState {
+  visible: boolean;
+  /** What `offer(reason)` said push is for here, for the sheet's copy. */
+  reason: string | null;
+}
+
+export interface PromptStore extends Store<PromptState> {
+  /**
+   * Show the soft prompt if it is a good moment: signed in, the system can
+   * still ask, not at launch, not too soon after "Not now". Resolves to
+   * whether it showed.
+   */
+  offer(reason?: string): Promise<boolean>;
+  /** "Turn on": hides the sheet and shows the system prompt. */
+  accept(): Promise<PushPermissionStatus>;
+  /** "Not now": hides the sheet and remembers it. */
+  decline(): Promise<void>;
+  hide(): void;
+}
+
+interface Declines {
+  count: number;
+  at: number;
+}
+
+export function createPromptStore(options: PromptOptions & {
+  permission: PermissionStore;
+  storage?: PushStorageLike;
+  storageKey: string;
+  signedIn: () => boolean;
+  /** When the block started (ms), or null before. */
+  startedAt: () => number | null;
+  now: () => number;
+  onError?: PushOnError;
+}): PromptStore {
+  const { permission, storage, storageKey, now, onError } = options;
+  const cooldownMs = options.cooldownMs ?? 3 * 24 * 60 * 60_000;
+  const maxDeclines = options.maxDeclines ?? 3;
+  const launchGraceMs = options.launchGraceMs ?? 10_000;
+  const store = createStore<PromptState>({ visible: false, reason: null });
+  let memory: Declines = { count: 0, at: 0 };
+
+  const readDeclines = async (): Promise<Declines> => {
+    if (!storage) return memory;
+    try {
+      const raw = await storage.getItem(storageKey);
+      const parsed = raw ? (JSON.parse(raw) as Partial<Declines>) : null;
+      return { count: Number(parsed?.count) || 0, at: Number(parsed?.at) || 0 };
+    } catch (error) {
+      report(onError, error, "storage");
+      return memory;
+    }
+  };
+
+  return {
+    ...store,
+    async offer(reason) {
+      if (store.getState().visible) return true;
+      const started = options.startedAt();
+      if (started === null || now() - started < launchGraceMs) return false;
+      if (!options.signedIn()) return false;
+      const status = permission.getState().status === "unknown" ? await permission.refresh() : permission.getState().status;
+      if (status !== "undetermined") return false;
+      const declines = await readDeclines();
+      if (declines.count >= maxDeclines || (declines.count > 0 && now() - declines.at < cooldownMs)) return false;
+      if (!options.signedIn()) return false;
+      store.setState({ visible: true, reason: reason ?? null });
+      return true;
+    },
+    async accept() {
+      store.setState({ visible: false });
+      return permission.request();
+    },
+    async decline() {
+      // Only from the sheet: a dismissal that fires as it closes after "Turn on" isn't a "Not now".
+      if (!store.getState().visible) return;
+      store.setState({ visible: false });
+      const declines = await readDeclines();
+      memory = { count: declines.count + 1, at: now() };
+      try {
+        await storage?.setItem(storageKey, JSON.stringify(memory));
+      } catch (error) {
+        report(onError, error, "storage");
+      }
+    },
+    hide() {
+      store.setState({ visible: false, reason: null });
+    },
+  };
+}

package/src/push/preferences.ts

@@ -0,0 +1,136 @@
+/**
+ * The signed-in person's notification preferences: categories, quiet hours
+ * and privacy previews. Loaded when they sign in, saved on every change
+ * (shown at once, put back if the save fails), cleared when they sign out.
+ * The server reads the saved row; nothing here decides what is delivered.
+ */
+import { createStore, type Store } from "../updates/store";
+import { DEFAULT_PREFERENCES, type NotificationPreferences, type PushBackend, type QuietHours } from "./backend";
+import { report, type PushOnError } from "./modules";
+import { parseClock } from "./quiet-hours";
+
+/** Android importance for a category's channel (Expo's `AndroidImportance`). */
+export type ChannelImportance = "min" | "low" | "default" | "high" | "max";
+
+/** One kind of notification the app sends, which a person can turn off. */
+export interface NotificationCategory {
+  /** Lower case letters, digits, ".", "_" or "-" (`messages`). Also its Android channel id, and the sender's `category`. */
+  id: string;
+  title: string;
+  description?: string;
+  /** On for someone who never chose. Default true; pass the same `defaultOn` to the sender. */
+  defaultOn?: boolean;
+  /** Android channel importance. Default `"default"`. */
+  importance?: ChannelImportance;
+}
+
+export type PreferencesStatus = "idle" | "loading" | "ready" | "error";
+
+export interface PreferencesState {
+  status: PreferencesStatus;
+  preferences: NotificationPreferences;
+  saving: boolean;
+  /** The last load or save that failed (the change was put back). */
+  error: Error | null;
+}
+
+export interface PreferencesStore extends Store<PreferencesState> {
+  load(userId: string): Promise<void>;
+  /** Apply a change now and save it; on failure it is put back and `error` set. */
+  update(change: (current: NotificationPreferences) => NotificationPreferences): Promise<boolean>;
+  reset(): void;
+  isOn(categoryId: string): boolean;
+}
+
+export const CATEGORY_ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** Checks a change before it is shown or saved, so the server never has to refuse it. */
+export function validPreferences(p: NotificationPreferences): boolean {
+  const q: QuietHours = p.quietHours;
+  if (parseClock(q.start) === null || parseClock(q.end) === null) return false;
+  if (q.enabled && !q.timeZone) return false;
+  return Object.keys(p.categories).every((id) => CATEGORY_ID.test(id));
+}
+
+export function createPreferencesStore(options: {
+  backend: PushBackend;
+  categories: readonly NotificationCategory[];
+  onError?: PushOnError;
+}): PreferencesStore {
+  const { backend, categories, onError } = options;
+  for (const category of categories) {
+    if (!CATEGORY_ID.test(category.id)) throw new Error(`createPush: category id "${category.id}" must be lower case letters, digits, ".", "_" or "-"`);
+  }
+  const store = createStore<PreferencesState>({ status: "idle", preferences: DEFAULT_PREFERENCES, saving: false, error: null });
+  let userId: string | null = null;
+  // Each load or save belongs to one sign-in; an answer for an earlier one is dropped.
+  let generation = 0;
+  let saves: Promise<unknown> = Promise.resolve();
+  let confirmed: NotificationPreferences = DEFAULT_PREFERENCES;
+  let pending = 0;
+
+  return {
+    ...store,
+    async load(id) {
+      const mine = ++generation;
+      userId = id;
+      pending = 0;
+      store.setState({ status: "loading", saving: false, error: null });
+      try {
+        const loaded = (await backend.loadPreferences(id)) ?? DEFAULT_PREFERENCES;
+        if (mine !== generation) return;
+        confirmed = loaded;
+        store.setState({ status: "ready", preferences: loaded });
+      } catch (error) {
+        if (mine !== generation) return;
+        report(onError, error, "preferences");
+        store.setState({ status: "error", error: error instanceof Error ? error : new Error("Couldn't load notification settings") });
+      }
+    },
+    update(change) {
+      const id = userId;
+      const mine = generation;
+      // Only on top of the server's copy: a change made while it loads (or after a failed load)
+      // would save the defaults over it, turning a hidden preview back on.
+      if (!id || store.getState().status !== "ready") return Promise.resolve(false);
+      const next = change(store.getState().preferences);
+      if (!validPreferences(next)) return Promise.resolve(false);
+      pending++;
+      store.setState({ preferences: next, saving: true, error: null });
+      // Saves go one at a time, in order; each carries every change before it.
+      const save = saves.then(async () => {
+        if (mine !== generation) return false;
+        let ok = false;
+        try {
+          await backend.savePreferences(id, next);
+          ok = true;
+          if (mine === generation) confirmed = next;
+        } catch (error) {
+          if (mine === generation) {
+            report(onError, error, "preferences");
+            store.setState({ error: error instanceof Error ? error : new Error("Couldn't save notification settings") });
+          }
+        }
+        if (mine !== generation) return false;
+        pending--;
+        // The last save settles what shows: the server's copy (a failed change is put back).
+        if (pending === 0) store.setState({ preferences: confirmed, saving: false });
+        return ok;
+      });
+      saves = save.catch(() => false);
+      return save;
+    },
+    reset() {
+      generation++;
+      userId = null;
+      pending = 0;
+      confirmed = DEFAULT_PREFERENCES;
+      store.setState({ status: "idle", preferences: DEFAULT_PREFERENCES, saving: false, error: null });
+    },
+    isOn(categoryId) {
+      const chosen = store.getState().preferences.categories[categoryId];
+      if (typeof chosen === "boolean") return chosen;
+      return categories.find((c) => c.id === categoryId)?.defaultOn ?? true;
+    },
+  };
+}

package/src/push/quiet-hours.ts

@@ -0,0 +1,71 @@
+/**
+ * Quiet hours on the phone: only for showing them ("on now, until 07:00").
+ * Whether a push waits is decided on the server (migration 0005's
+ * genesis_push_status), in the person's saved time zone, so a phone with a
+ * wrong clock or in another zone can't change it.
+ */
+import type { QuietHours } from "./backend";
+
+const CLOCK = /^([01]\d|2[0-3]):([0-5]\d)$/;
+
+/** Minutes since midnight for `"HH:MM"`, or null. */
+export function parseClock(value: string): number | null {
+  const match = CLOCK.exec(value);
+  return match ? Number(match[1]) * 60 + Number(match[2]) : null;
+}
+
+/** `"HH:MM"` for minutes since midnight (wrapping a day). */
+export function formatClock(minutes: number): string {
+  const m = ((Math.round(minutes) % 1440) + 1440) % 1440;
+  return `${String(Math.floor(m / 60)).padStart(2, "0")}:${String(m % 60).padStart(2, "0")}`;
+}
+
+/** `"HH:MM"` for a `Date`'s local time (what a time picker hands back). */
+export function clockOf(date: Date): string {
+  return formatClock(date.getHours() * 60 + date.getMinutes());
+}
+
+/** Today at `"HH:MM"` local, for a time picker's value. */
+export function dateAt(clock: string, today = new Date()): Date {
+  const minutes = parseClock(clock) ?? 0;
+  const d = new Date(today);
+  d.setHours(Math.floor(minutes / 60), minutes % 60, 0, 0);
+  return d;
+}
+
+/** This phone's IANA time zone, or null when the JavaScript engine can't say. */
+export function deviceTimeZone(): string | null {
+  try {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return typeof zone === "string" && zone.length > 0 ? zone : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Minutes since midnight at `at` in `timeZone`, or null for a zone the engine doesn't know. */
+export function minutesIn(timeZone: string, at: Date): number | null {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", { timeZone, hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).formatToParts(at);
+    const hour = Number(parts.find((p) => p.type === "hour")?.value);
+    const minute = Number(parts.find((p) => p.type === "minute")?.value);
+    return Number.isFinite(hour) && Number.isFinite(minute) ? (hour % 24) * 60 + minute : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Are quiet hours on at `at`? The same rule as the server: the start is
+ * inclusive, the end exclusive, a start after the end runs past midnight, a
+ * start equal to the end is no quiet hours, and an unknown zone is never quiet.
+ */
+export function isQuietAt(quiet: QuietHours, at: Date = new Date()): boolean {
+  if (!quiet.enabled || !quiet.timeZone) return false;
+  const start = parseClock(quiet.start);
+  const end = parseClock(quiet.end);
+  if (start === null || end === null || start === end) return false;
+  const now = minutesIn(quiet.timeZone, at);
+  if (now === null) return false;
+  return start < end ? now >= start && now < end : now >= start || now < end;
+}