akanjs 3.0.0-beta.8 → 3.0.0

package/vendor/@akanjs/native/plugins/local-notifications/src/desktop.ts

@@ -0,0 +1,196 @@
+
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { type DesktopContext, defineDesktopPlugin, type NativeEvent } from "../../../packages/desktop/src/plugin.ts";
+import type {
+  DeliveredNotification,
+  LocalNotificationsApi,
+  LocalNotificationsEvents,
+  NotificationData,
+  NotificationEvent,
+  PendingNotification,
+  PermissionState,
+  Repeat,
+} from "./index.ts";
+import { checkIds, checkScheduled } from "./schedule.ts";
+
+/** A request as notify.rs reports it (pending, delivered, events). */
+export interface NativeRequest {
+  id: string | null;
+  title: string | null;
+  body: string | null;
+  /** userInfo data: JSON text. */
+  data: string | null;
+  /** userInfo target time, epoch ms. */
+  at: number | null;
+  every: string | null;
+  /** Next date of a calendar (repeating) trigger. */
+  next: number | null;
+  /** When it was shown (delivered list). */
+  date: number | null;
+  /** Carries this plugin's marker. */
+  ours: boolean;
+}
+
+/** UNAuthorizationStatus: 0 notDetermined, 1 denied, 2 authorized, 3 provisional, 4 ephemeral. */
+export function permissionState(status: number): PermissionState {
+  if (status === 2 || status === 3 || status === 4) return "granted";
+  if (status === 1) return "denied";
+  return "prompt";
+}
+
+/** Ours and with a 32-bit integer id (other requests of the app, e.g. push, are left alone). */
+function mine(r: NativeRequest): r is NativeRequest & { id: string } {
+  if (!r.ours || r.id === null || !/^-?\d+$/.test(r.id)) return false;
+  const id = Number(r.id);
+  return id >= -2147483648 && id <= 2147483647;
+}
+
+function dataOf(r: NativeRequest): NotificationData | undefined {
+  if (r.data === null) return undefined;
+  try {
+    const value = JSON.parse(r.data);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function eventOf(r: NativeRequest & { id: string }): NotificationEvent {
+  const event: NotificationEvent = { id: Number(r.id), title: r.title ?? "", body: r.body ?? "" };
+  const data = dataOf(r);
+  if (data) event.data = data;
+  return event;
+}
+
+const REPEATS = new Set(["minute", "hour", "day", "week"]);
+
+export function pendingOf(r: NativeRequest & { id: string }): PendingNotification {
+  const n: PendingNotification = { ...eventOf(r), at: r.next ?? r.at ?? 0 };
+  if (r.every && REPEATS.has(r.every)) n.every = r.every as Repeat;
+  return n;
+}
+
+function deliveredOf(r: NativeRequest & { id: string }): DeliveredNotification {
+  const n: DeliveredNotification = eventOf(r);
+  if (r.date !== null) n.at = r.date;
+  return n;
+}
+
+/**
+ * A notify.* op with the app it is for and, on Windows and Linux, the file the shell keeps the
+ * pending notifications in, so they are scheduled again at the next launch (notify_schedule.rs).
+ */
+const shell = (ctx: DesktopContext, op: string, args: Record<string, unknown> = {}) =>
+  ctx.shell(op, {
+    ...args,
+    app: { id: ctx.app.id, name: ctx.app.name },
+    ...(process.platform === "darwin" ? {} : { store: storePath(ctx) }),
+  });
+const storePath = (ctx: DesktopContext) => join(ctx.appDataDir, "notifications.json");
+
+/** Kept for the first `action` listener (plugins.md C2). */
+const BUFFER = 16;
+
+export function createDesktopNotifications() {
+  const received = new Set<(e: NotificationEvent) => void>();
+  const action = new Set<(e: NotificationEvent) => void>();
+  const pendingActions: NotificationEvent[] = [];
+
+  const status = async (ctx: DesktopContext) => ((await shell(ctx, "notify.status")) as { status: number }).status;
+  const list = async (ctx: DesktopContext, op: "notify.pending" | "notify.delivered") =>
+    ((await shell(ctx, op)) as NativeRequest[]).filter(mine);
+
+  const onNative = (e: NativeEvent) => {
+    const r = e.notification as NativeRequest | undefined;
+    if (!r || !mine(r)) return;
+    const event = eventOf(r);
+    if (e.event === "received") for (const listener of received) listener(event);
+    else if (e.event === "action") {
+      if (action.size === 0) {
+        pendingActions.push(event);
+        if (pendingActions.length > BUFFER) pendingActions.shift();
+      } else for (const listener of action) listener(event);
+    }
+  };
+
+  return defineDesktopPlugin<LocalNotificationsApi, LocalNotificationsEvents>({
+    id: "local-notifications",
+    setup(ctx) {
+      
+      ctx.onNativeEvent("notification", onNative);
+
+      if (process.platform !== "darwin" && existsSync(storePath(ctx))) {
+        ctx.onNativeEvent(
+          "init",
+          () =>
+            void shell(ctx, "notify.restore").catch((error) =>
+              console.error("[akan-native] local-notifications: cannot restore the pending notifications", error),
+            ),
+        );
+      }
+    },
+    methods: {
+      async schedule(args, ctx) {
+        const items = checkScheduled(args);
+        
+        if (permissionState(await status(ctx)) !== "granted") {
+          throw new AkanNativeError(
+            "PERMISSION_DENIED",
+            "notification permission is not granted (call requestPermission)",
+          );
+        }
+        await shell(ctx, "notify.add", {
+          items: items.map((n) => ({
+            id: n.id,
+            title: n.title,
+            body: n.body,
+            at: n.at,
+            ...(n.every ? { every: n.every } : {}),
+            ...(n.data ? { data: JSON.stringify(n.data) } : {}),
+          })),
+        });
+        return { ids: items.map((n) => n.id) };
+      },
+      async cancel(args, ctx) {
+        await shell(ctx, "notify.removePending", { ids: checkIds(args, "cancel").map(String) });
+      },
+      getPending: async (_args, ctx) => ({
+        notifications: (await list(ctx, "notify.pending")).map(pendingOf).sort((a, b) => a.at - b.at),
+      }),
+      getDelivered: async (_args, ctx) => ({ notifications: (await list(ctx, "notify.delivered")).map(deliveredOf) }),
+      async removeDelivered(args, ctx) {
+        await shell(ctx, "notify.removeDelivered", { ids: checkIds(args, "removeDelivered").map(String) });
+      },
+      async removeAllDelivered(_args, ctx) {
+        const ids = (await list(ctx, "notify.delivered")).map((r) => r.id);
+        if (ids.length) await shell(ctx, "notify.removeDelivered", { ids });
+      },
+      createChannel: () => {},
+      checkPermission: async (_args, ctx) => ({ display: permissionState(await status(ctx)) }),
+      
+      async requestPermission(args, ctx) {
+        const provisional = (args as { provisional?: unknown } | undefined)?.provisional === true;
+        const now = await status(ctx);
+        if (now !== 0 && !(now === 3 && !provisional)) return { display: permissionState(now) };
+        const after = (await shell(ctx, "notify.request", { provisional })) as { status: number };
+        return { display: permissionState(after.status) };
+      },
+    },
+    events: {
+      received(emit) {
+        received.add(emit);
+        return () => received.delete(emit);
+      },
+      action(emit) {
+        action.add(emit);
+        for (const event of pendingActions.splice(0)) emit(event);
+        return () => action.delete(emit);
+      },
+    },
+  });
+}
+
+export default createDesktopNotifications();

package/vendor/@akanjs/native/plugins/local-notifications/src/index.ts

@@ -0,0 +1,174 @@
+import { definePlugin, type Plugin } from "../../../packages/core/src/index.ts";
+import { usePluginEvent } from "../../../packages/react/src/index.ts";
+import { checkIds, normalizeSchedule } from "./schedule.ts";
+import { web } from "./web.ts";
+
+/** C1 permission states. Android reports "prompt-with-rationale" after one refusal. */
+export type PermissionState = "granted" | "denied" | "prompt" | "prompt-with-rationale";
+
+export type Repeat = "minute" | "hour" | "day" | "week";
+
+/** Android channel importance: "high" pops up (heads-up), "low" is silent, "min" is folded away. */
+export type Importance = "min" | "low" | "default" | "high";
+
+/** Any JSON object. It comes back unchanged in getPending, getDelivered and the events. */
+export type NotificationData = Record<string, unknown>;
+
+export interface NotificationRequest {
+  /** 32-bit integer, unique within the app. Scheduling an id again replaces the earlier one. */
+  id: number;
+  title: string;
+  body?: string;
+  /**
+   * When to show it: an ISO 8601 date-time (local time without an offset) or epoch milliseconds.
+   * Omitted or in the past: right away. With `every` it sets the time of the repeats and must be
+   * less than one interval from now.
+   */
+  at?: string | number;
+  /**
+   * Repeat until cancelled. Without `at` the first one comes one interval from now (2 s earlier:
+   * iOS calendar triggers work in whole seconds). day and week keep the local time of day across DST.
+   * Android without the exact-alarm permission delivers each one up to about 75% of the interval late.
+   */
+  every?: Repeat;
+  /**
+   * Android channel (createChannel); an unknown one is INVALID_ARGS there. Default: the plugin's
+   * "default" channel ("Notifications", default importance). Ignored elsewhere.
+   */
+  channelId?: string;
+  data?: NotificationData;
+}
+
+export interface PendingNotification {
+  id: number;
+  title: string;
+  body: string;
+  /** Next delivery, epoch ms. */
+  at: number;
+  every?: Repeat;
+  channelId?: string;
+  data?: NotificationData;
+}
+
+export interface DeliveredNotification {
+  id: number;
+  title: string;
+  body: string;
+  /** When it was shown, epoch ms, where the host knows it. */
+  at?: number;
+  data?: NotificationData;
+}
+
+export interface NotificationEvent {
+  id: number;
+  title: string;
+  body: string;
+  data?: NotificationData;
+}
+
+export interface ChannelOptions {
+  id: string;
+  /** Shown in the system settings. */
+  name: string;
+  description?: string;
+  /** Default "default". Android keeps the user's choice: importance cannot change after creation. */
+  importance?: Importance;
+}
+
+export interface LocalNotificationsApi {
+  /** Requires the display permission (PERMISSION_DENIED otherwise); it never prompts by itself. */
+  schedule(args: { notifications: NotificationRequest[] }): Promise<{ ids: number[] }>;
+  /** Stops pending (future and repeating) notifications. Shown ones stay: see removeDelivered. */
+  cancel(args: { ids: number[] }): Promise<void>;
+  getPending(): Promise<{ notifications: PendingNotification[] }>;
+  /** Notifications of this plugin still shown in the notification center / shade. */
+  getDelivered(): Promise<{ notifications: DeliveredNotification[] }>;
+  removeDelivered(args: { ids: number[] }): Promise<void>;
+  /** Removes every shown notification of this plugin (push notifications are not touched). */
+  removeAllDelivered(): Promise<void>;
+  /** Android notification channel. Resolves without doing anything on other platforms. */
+  createChannel(args: ChannelOptions): Promise<void>;
+  checkPermission(): Promise<{ display: PermissionState }>;
+  /**
+   * Shows the system prompt when the state is "prompt" (web: call it from a click).
+   * iOS `provisional: true` grants quiet delivery (Notification Center only, no banner or sound)
+   * without a prompt; a later requestPermission() without it still shows the prompt. Ignored elsewhere.
+   */
+  requestPermission(args?: { provisional?: boolean }): Promise<{ display: PermissionState }>;
+}
+
+export interface LocalNotificationsEvents {
+  /** A notification was shown while the app is in the foreground (web: while the page runs). */
+  received: NotificationEvent;
+  /**
+   * The user tapped a notification. A tap that launched or resumed the app before anything listened
+   * is delivered to the first listener (plugins.md C2).
+   */
+  action: NotificationEvent;
+}
+
+export const METHODS = [
+  "schedule",
+  "cancel",
+  "getPending",
+  "getDelivered",
+  "removeDelivered",
+  "removeAllDelivered",
+  "createChannel",
+  "checkPermission",
+  "requestPermission",
+] as const;
+
+const raw = definePlugin<LocalNotificationsApi, LocalNotificationsEvents>("local-notifications", {
+  methods: METHODS,
+  events: ["received", "action"],
+  web,
+});
+
+/** Runs the check synchronously so a rejected argument never reaches the host. */
+function checked<A, R>(check: (args: unknown) => A, call: (args: A) => Promise<R>): (args: unknown) => Promise<R> {
+  return (args) => {
+    let valid: A;
+    try {
+      valid = check(args);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return call(valid);
+  };
+}
+
+/**
+ * Local notifications: scheduled on the device, no server. The page resolves dates before calling
+ * the host (see schedule.ts), so every host gets the same arguments.
+ * Windows and Linux keep no schedule for apps: the app shows its pending notifications itself, so
+ * they are delivered only while it runs (the web: while the page is open), and taps arrive only
+ * then. A Linux session without a notification server is UNSUPPORTED.
+ */
+export const localNotifications: Plugin<LocalNotificationsApi, LocalNotificationsEvents> = Object.freeze({
+  ...raw,
+  schedule: checked(
+    (args) => normalizeSchedule(args, Date.now()),
+    (args) => raw.schedule(args),
+  ),
+  cancel: checked(
+    (args) => ({ ids: checkIds(args, "cancel") }),
+    (args) => raw.cancel(args),
+  ),
+  removeDelivered: checked(
+    (args) => ({ ids: checkIds(args, "removeDelivered") }),
+    (args) => raw.removeDelivered(args),
+  ),
+});
+
+/** Calls `handler` for every tapped notification while mounted, including the one that launched the app. */
+export function useNotificationAction(handler: (event: NotificationEvent) => void): void {
+  usePluginEvent(localNotifications, "action", handler);
+}
+
+/** Calls `handler` for every notification shown while the app is in the foreground. */
+export function useNotificationReceived(handler: (event: NotificationEvent) => void): void {
+  usePluginEvent(localNotifications, "received", handler);
+}
+
+export { addInterval, nextOccurrence, normalizeSchedule, type ScheduledNotification } from "./schedule.ts";

package/vendor/@akanjs/native/plugins/local-notifications/src/schedule.ts

@@ -0,0 +1,164 @@
+
+
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import type { NotificationData, Repeat } from "./index.ts";
+
+export const REPEATS: readonly Repeat[] = ["minute", "hour", "day", "week"];
+
+/** How much earlier than "one interval from now" a repeating series starts at the latest. */
+export const REPEAT_MARGIN = 2000;
+
+/** What schedule() sends to the host: `at` is always the first delivery time in epoch ms. */
+export interface ScheduledNotification {
+  id: number;
+  title: string;
+  body: string;
+  at: number;
+  every?: Repeat;
+  channelId?: string;
+  data?: NotificationData;
+}
+
+const invalid = (message: string) => new AkanNativeError("INVALID_ARGS", message);
+
+export function isInt32(value: unknown): value is number {
+  return Number.isInteger(value) && (value as number) >= -2147483648 && (value as number) <= 2147483647;
+}
+
+/** A list of notification ids (32-bit integers, the Android notification id range). */
+export function checkIds(args: unknown, method: string): number[] {
+  const ids = (args as { ids?: unknown } | null | undefined)?.ids;
+  if (!Array.isArray(ids) || !ids.every(isInt32)) throw invalid(`${method}: ids must be an array of 32-bit integers`);
+  return ids as number[];
+}
+
+/**
+ * The same wall-clock time `count` intervals after `at`. day and week keep the local time of day
+ * across DST changes (09:00 stays 09:00), like iOS calendar triggers; minute and hour are fixed lengths.
+ */
+export function addInterval(at: number, every: Repeat, count = 1): number {
+  if (every === "minute") return at + count * 60_000;
+  if (every === "hour") return at + count * 3_600_000;
+  const d = new Date(at);
+  const days = (every === "day" ? 1 : 7) * count;
+  return new Date(
+    d.getFullYear(),
+    d.getMonth(),
+    d.getDate() + days,
+    d.getHours(),
+    d.getMinutes(),
+    d.getSeconds(),
+    d.getMilliseconds(),
+  ).getTime();
+}
+
+/** The first occurrence of the series (at, at + 1 interval, ...) that is later than `after`. */
+export function nextOccurrence(at: number, every: Repeat, after: number): number {
+  if (at > after) return at;
+  const step = every === "minute" ? 60_000 : every === "hour" ? 3_600_000 : every === "day" ? 86_400_000 : 604_800_000;
+  
+  let k = Math.max(1, Math.floor((after - at) / step));
+  while (addInterval(at, every, k - 1) > after && k > 1) k--;
+  while (addInterval(at, every, k) <= after) k++;
+  return addInterval(at, every, k);
+}
+
+/** For hosts in JS (web, desktop): the arguments normalizeSchedule produced, checked again at the bridge. */
+export function checkScheduled(args: unknown): ScheduledNotification[] {
+  const list = (args as { notifications?: unknown } | null | undefined)?.notifications;
+  const ok =
+    Array.isArray(list) &&
+    list.length > 0 &&
+    list.every(
+      (n) =>
+        isPlainObject(n) &&
+        isInt32(n.id) &&
+        typeof n.title === "string" &&
+        typeof n.body === "string" &&
+        typeof n.at === "number" &&
+        Number.isFinite(n.at) &&
+        (n.every === undefined || REPEATS.includes(n.every as Repeat)) &&
+        (n.data === undefined || isPlainObject(n.data)),
+    );
+  if (!ok) throw invalid("schedule: expected the notifications normalizeSchedule() produces");
+  return list as ScheduledNotification[];
+}
+
+function parseAt(value: unknown, index: number): number {
+  if (typeof value === "number" && Number.isFinite(value)) return Math.round(value);
+  if (typeof value === "string" && value.trim() !== "") {
+    const ms = Date.parse(value);
+    if (Number.isFinite(ms)) return ms;
+  }
+  throw invalid(`notifications[${index}].at must be an ISO 8601 date-time string or epoch milliseconds`);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Checks schedule() arguments and resolves the first delivery time of each notification:
+ * - no at, no every: now (shown right away)
+ * - at only: that time; a time in the past means now
+ * - every only: one interval from now (2 s earlier, see REPEAT_MARGIN)
+ * - at + every: at sets the phase (09:00 for a daily reminder) and must be less than one interval
+ *   away, because an iOS repeating trigger cannot start later than its next matching time.
+ *   A past at continues the series at its next occurrence.
+ */
+export function normalizeSchedule(args: unknown, now: number): { notifications: ScheduledNotification[] } {
+  const list = (args as { notifications?: unknown } | null | undefined)?.notifications;
+  if (!Array.isArray(list) || list.length === 0) throw invalid("schedule: notifications must be a non-empty array");
+  const seen = new Set<number>();
+  const notifications = list.map((raw, i): ScheduledNotification => {
+    if (!isPlainObject(raw)) throw invalid(`notifications[${i}] must be an object`);
+    const { id, title, body, at, every, channelId, data } = raw;
+    if (!isInt32(id)) throw invalid(`notifications[${i}].id must be a 32-bit integer`);
+    if (seen.has(id)) throw invalid(`notifications[${i}].id ${id} is used twice`);
+    seen.add(id);
+    if (typeof title !== "string" || title.trim() === "")
+      throw invalid(`notifications[${i}].title must be a non-empty string`);
+    if (body !== undefined && typeof body !== "string") throw invalid(`notifications[${i}].body must be a string`);
+    if (every !== undefined && !REPEATS.includes(every as Repeat))
+      throw invalid(`notifications[${i}].every must be one of ${REPEATS.join(", ")}`);
+    if (channelId !== undefined && (typeof channelId !== "string" || channelId === ""))
+      throw invalid(`notifications[${i}].channelId must be a non-empty string`);
+    if (data !== undefined) {
+      if (!isPlainObject(data)) throw invalid(`notifications[${i}].data must be a plain JSON object`);
+      try {
+        JSON.stringify(data);
+      } catch {
+        throw invalid(`notifications[${i}].data must be JSON`);
+      }
+    }
+
+    let first: number;
+    if (every) {
+      const repeat = every as Repeat;
+      const limit = addInterval(now, repeat);
+      if (at === undefined) first = limit;
+      else {
+        first = parseAt(at, i);
+        if (first > limit) {
+          throw invalid(
+            `notifications[${i}]: with every "${repeat}", at must be less than one ${repeat} from now (it sets the time of the repeats)`,
+          );
+        }
+        first = nextOccurrence(first, repeat, now);
+      }
+
+      first = Math.min(first, limit - REPEAT_MARGIN);
+    } else {
+      first = at === undefined ? now : Math.max(now, parseAt(at, i));
+    }
+
+    const out: ScheduledNotification = { id, title, body: body ?? "", at: first };
+    if (every) out.every = every as Repeat;
+    if (channelId) out.channelId = channelId as string;
+    if (data) out.data = JSON.parse(JSON.stringify(data)) as NotificationData;
+    return out;
+  });
+  return { notifications };
+}

package/vendor/@akanjs/native/plugins/local-notifications/src/timers.ts

@@ -0,0 +1,72 @@
+
+
+import type { PendingNotification } from "./index.ts";
+import { nextOccurrence, type ScheduledNotification } from "./schedule.ts";
+
+/** setTimeout clamps delays above 2^31-1 ms (about 24.8 days) to 0: wait in steps instead. */
+const MAX_DELAY = 2_147_483_647;
+
+export interface TimerHost {
+  now(): number;
+  setTimer(fn: () => void, ms: number): unknown;
+  clearTimer(handle: unknown): void;
+  /** Shows the notification. Called for every delivery, repeats included. */
+  show(notification: ScheduledNotification): void;
+}
+
+export const systemTimers = {
+  now: () => Date.now(),
+  setTimer: (fn: () => void, ms: number) => setTimeout(fn, ms),
+  clearTimer: (handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+export class NotificationTimers {
+  private readonly pending = new Map<number, { notification: ScheduledNotification; timer: unknown }>();
+
+  constructor(private readonly host: TimerHost) {}
+
+  /** Same id again replaces the earlier one. Due notifications are shown right away. */
+  schedule(notifications: ScheduledNotification[]): number[] {
+    for (const n of notifications) {
+      this.cancel([n.id]);
+      if (!n.every && n.at <= this.host.now()) this.host.show(n);
+      else this.arm({ ...n });
+    }
+    return notifications.map((n) => n.id);
+  }
+
+  cancel(ids: number[]): void {
+    for (const id of ids) {
+      const entry = this.pending.get(id);
+      if (!entry) continue;
+      this.host.clearTimer(entry.timer);
+      this.pending.delete(id);
+    }
+  }
+
+  list(): PendingNotification[] {
+    return [...this.pending.values()].map(({ notification }) => ({ ...notification })).sort((a, b) => a.at - b.at);
+  }
+
+  private arm(n: ScheduledNotification): void {
+    const delay = Math.min(MAX_DELAY, Math.max(0, n.at - this.host.now()));
+    const timer = this.host.setTimer(() => this.fire(n), delay);
+    this.pending.set(n.id, { notification: n, timer });
+  }
+
+  private fire(n: ScheduledNotification): void {
+    if (this.pending.get(n.id)?.notification !== n) return; 
+    const now = this.host.now();
+    if (n.at > now) {
+      this.arm(n); 
+      return;
+    }
+    this.host.show(n);
+    if (!n.every) {
+      this.pending.delete(n.id);
+      return;
+    }
+    
+    this.arm({ ...n, at: nextOccurrence(n.at, n.every, now) });
+  }
+}