@zerotal/admin 1.0.0

package/src/databaseMedia.ts

@@ -0,0 +1,148 @@
+/**
+ * A media catalogue kept in a database table.
+ *
+ * {@link MediaProvider} is deliberately open, because where a file catalogue
+ * belongs is the app's decision. When the answer is the ordinary one — a table
+ * with a row per file — this builds the provider for you:
+ *
+ *   import { databaseMedia } from "@zerotal/admin";
+ *
+ *   Panel.media(databaseMedia());
+ *
+ * The table it expects:
+ *
+ *   id, path, name, mime, size, alt, folder, uploaded_at
+ *
+ * Column names are adjustable, so an existing table usually needs no migration.
+ * `@zerotal/orm` is resolved lazily, keeping it an optional peer.
+ */
+import { frameworkLog } from "@zerotal/core/logger";
+import type { MediaItem, MediaProvider } from "./media.ts";
+
+export interface DatabaseMediaOptions {
+  /** Table holding the catalogue. Defaults to `"media"`. */
+  table?: string;
+  /** Map the panel's fields onto your column names. */
+  columns?: Partial<Record<keyof MediaItem, string>>;
+}
+
+const DEFAULT_COLUMNS: Record<keyof MediaItem, string> = {
+  id: "id",
+  path: "path",
+  name: "name",
+  mime: "mime",
+  size: "size",
+  alt: "alt",
+  folder: "folder",
+  uploadedAt: "uploaded_at",
+};
+
+/** The minimum query surface this needs, kept structural so `orm` stays optional. */
+interface QueryLike {
+  where(column: string, value: unknown): QueryLike;
+  whereLike?(column: string, value: string): QueryLike;
+  orderBy(column: string, direction: string): QueryLike;
+  limit(n: number): QueryLike;
+  get(): Promise<Record<string, unknown>[]>;
+  insert(values: Record<string, unknown>): Promise<unknown>;
+  update(values: Record<string, unknown>): Promise<unknown>;
+  delete(): Promise<unknown>;
+}
+
+async function table(name: string): Promise<QueryLike | null> {
+  try {
+    const mod = (await import(/* @vite-ignore */ "@zerotal/orm" as string)) as {
+      DB?: { table(name: string): QueryLike };
+    };
+    return mod.DB?.table(name) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a {@link MediaProvider} over a table.
+ *
+ * Listing fails soft — an unconfigured database or a missing table yields an
+ * empty library rather than a broken page — but saving and removing report
+ * their failures, because silently losing an upload is not a kindness.
+ */
+export function databaseMedia(options: DatabaseMediaOptions = {}): MediaProvider {
+  const name = options.table ?? "media";
+  const col = { ...DEFAULT_COLUMNS, ...(options.columns ?? {}) };
+
+  /** Turn a row into a catalogue item, tolerating nulls in the optional fields. */
+  const toItem = (row: Record<string, unknown>): MediaItem => {
+    const str = (key: keyof MediaItem): string | undefined => {
+      const value = row[col[key]];
+      return typeof value === "string" && value !== "" ? value : undefined;
+    };
+    return {
+      id: String(row[col.id] ?? ""),
+      path: str("path") ?? "",
+      name: str("name") ?? "",
+      mime: str("mime") ?? "application/octet-stream",
+      size: Number(row[col.size] ?? 0),
+      ...(str("alt") ? { alt: str("alt")! } : {}),
+      ...(str("folder") ? { folder: str("folder")! } : {}),
+      ...(str("uploadedAt") ? { uploadedAt: str("uploadedAt")! } : {}),
+    };
+  };
+
+  return {
+    async list(query): Promise<MediaItem[]> {
+      try {
+        const t = await table(name);
+        if (!t) return [];
+        let q = t;
+        if (query.folder) q = q.where(col.folder, query.folder);
+        // Searching by name is what a library search means; falling back to an
+        // exact match keeps this working on a driver without `whereLike`.
+        if (query.search) {
+          q = q.whereLike
+            ? q.whereLike(col.name, `%${query.search}%`)
+            : q.where(col.name, query.search);
+        }
+        const rows = await q.orderBy(col.uploadedAt, "desc").limit(query.limit).get();
+        return rows.map(toItem);
+      } catch (error) {
+        frameworkLog("admin").warn("Media library unavailable", { table: name }, error);
+        return [];
+      }
+    },
+
+    async save(item): Promise<MediaItem> {
+      const t = await table(name);
+      if (!t) throw new Error("The media library needs a configured database.");
+      const values: Record<string, unknown> = {
+        [col.path]: item.path,
+        [col.name]: item.name,
+        [col.mime]: item.mime,
+        [col.size]: item.size,
+        [col.alt]: item.alt ?? "",
+        [col.folder]: item.folder ?? "",
+        [col.uploadedAt]: item.uploadedAt ?? new Date().toISOString(),
+      };
+      const inserted = (await t.insert(values)) as Record<string, unknown> | undefined;
+      // Drivers differ on what an insert returns; the path is unique enough to
+      // identify the row when an id does not come back.
+      const id = inserted?.[col.id] ?? inserted;
+      return { ...item, id: id == null ? item.path : String(id) } as MediaItem;
+    },
+
+    async remove(id): Promise<void> {
+      const t = await table(name);
+      if (!t) throw new Error("The media library needs a configured database.");
+      await t.where(col.id, id).delete();
+    },
+
+    async update(id, changes): Promise<void> {
+      const t = await table(name);
+      if (!t) throw new Error("The media library needs a configured database.");
+      await t.where(col.id, id).update({
+        [col.alt]: changes.alt ?? "",
+        [col.folder]: changes.folder ?? "",
+      });
+    },
+  };
+}

package/src/databaseNotifications.ts

@@ -0,0 +1,169 @@
+/**
+ * Database-backed notifications for the panel's bell.
+ *
+ * `Panel.notifications()` takes a provider because "the current user's
+ * notifications" depends on your auth and your schema. When those are the
+ * ordinary ones — `@zerotal/auth` for the user, `@zerotal/notifications`'
+ * `DatabaseChannel` for storage — this builds that provider for you:
+ *
+ *   import { databaseNotifications } from "@zerotal/admin";
+ *
+ *   Panel.notifications(databaseNotifications());
+ *
+ * Everything is optional and adjustable: which user the notifications belong to,
+ * how a stored row becomes a title and a link, and which table to read.
+ *
+ * `@zerotal/notifications` and `@zerotal/auth` are resolved lazily, so neither
+ * becomes a hard dependency of the admin package for apps that don't use this.
+ */
+import type { AdminNotification, NotificationProvider } from "./notifications.ts";
+import { frameworkLog } from "@zerotal/core/logger";
+
+/** A stored notification row, as `DatabaseChannel` writes it. */
+export interface StoredNotification {
+  id: string;
+  notifiable_type: string;
+  notifiable_id: string;
+  type: string;
+  data: string;
+  read_at: string | null;
+  created_at: string;
+}
+
+export interface DatabaseNotificationOptions {
+  /** Table holding the notifications. Defaults to `"notifications"`. */
+  table?: string;
+  /**
+   * Who the bell is showing. Defaults to the signed-in user from
+   * `@zerotal/auth`; returning `null` shows nothing, which is the right answer
+   * for a guest.
+   */
+  notifiable?: () => Promise<unknown> | unknown;
+  /** How many to show. Defaults to 20 — a bell is not an archive. */
+  limit?: number;
+  /**
+   * Turn a stored row into what the panel renders. The default reads `title`,
+   * `body`/`message`, `url`/`href` and `icon` out of the payload, which is what
+   * most notifications carry.
+   */
+  present?: (row: StoredNotification, data: Record<string, unknown>) => AdminNotification;
+}
+
+/** Parse a row's JSON payload, tolerating a payload that was never JSON. */
+function payloadOf(row: StoredNotification): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(row.data) as unknown;
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The default presentation: whatever the payload says, with sane fallbacks. */
+function defaultPresent(row: StoredNotification, data: Record<string, unknown>): AdminNotification {
+  const str = (key: string): string | undefined => {
+    const value = data[key];
+    return typeof value === "string" && value ? value : undefined;
+  };
+  return {
+    id: row.id,
+    // A notification with no title is still worth showing; name it by its class.
+    title: str("title") ?? row.type,
+    ...((str("body") ?? str("message")) ? { body: str("body") ?? str("message")! } : {}),
+    ...((str("url") ?? str("href")) ? { href: str("url") ?? str("href")! } : {}),
+    ...(str("icon") ? { icon: str("icon")! } : {}),
+    read: row.read_at != null,
+    time: row.created_at,
+  };
+}
+
+/**
+ * Build a {@link NotificationProvider} reading from the notifications table.
+ *
+ * Every method fails soft: a missing table, an unconfigured database or a
+ * signed-out user yields an empty bell rather than a broken panel, because a
+ * notification centre is never worth taking the page down for.
+ */
+export function databaseNotifications(
+  options: DatabaseNotificationOptions = {},
+): NotificationProvider {
+  const limit = options.limit ?? 20;
+  const present = options.present ?? defaultPresent;
+
+  /** The DatabaseChannel instance, resolved lazily and cached. */
+  let channel: Promise<DatabaseChannelLike | null> | null = null;
+  const getChannel = (): Promise<DatabaseChannelLike | null> => {
+    channel ??= (async () => {
+      try {
+        const mod = (await import(/* @vite-ignore */ "@zerotal/notifications" as string)) as {
+          DatabaseChannel?: new (table?: string) => DatabaseChannelLike;
+        };
+        if (!mod.DatabaseChannel) return null;
+        return new mod.DatabaseChannel(options.table);
+      } catch {
+        return null;
+      }
+    })();
+    return channel;
+  };
+
+  const getNotifiable = async (): Promise<unknown> => {
+    if (options.notifiable) return options.notifiable();
+    try {
+      const mod = (await import(/* @vite-ignore */ "@zerotal/auth" as string)) as {
+        Auth?: { user?: () => unknown };
+      };
+      return mod.Auth?.user?.() ?? null;
+    } catch {
+      return null;
+    }
+  };
+
+  /** Run `fn` against the channel + current user, or yield `fallback`. */
+  const withChannel = async <T>(
+    fn: (channel: DatabaseChannelLike, notifiable: object) => Promise<T>,
+    fallback: T,
+  ): Promise<T> => {
+    try {
+      const [c, notifiable] = await Promise.all([getChannel(), getNotifiable()]);
+      if (!c || !notifiable || typeof notifiable !== "object") return fallback;
+      return await fn(c, notifiable);
+    } catch (error) {
+      frameworkLog("admin").warn("Database notifications unavailable", undefined, error);
+      return fallback;
+    }
+  };
+
+  return {
+    async resolve(): Promise<AdminNotification[]> {
+      return withChannel(async (c, notifiable) => {
+        const rows = await c.all(notifiable);
+        return rows.slice(0, limit).map((row) => present(row, payloadOf(row)));
+      }, []);
+    },
+
+    async unreadCount(): Promise<number> {
+      return withChannel(async (c, notifiable) => (await c.unread(notifiable)).length, 0);
+    },
+
+    async markRead(id: string): Promise<void> {
+      await withChannel(async (c) => {
+        await c.markAsRead(id);
+      }, undefined);
+    },
+
+    async markAllRead(): Promise<void> {
+      await withChannel(async (c, notifiable) => {
+        await c.markAllAsRead(notifiable);
+      }, undefined);
+    },
+  };
+}
+
+/** The slice of `DatabaseChannel` this bridge uses. */
+interface DatabaseChannelLike {
+  all(notifiable: object): Promise<StoredNotification[]>;
+  unread(notifiable: object): Promise<StoredNotification[]>;
+  markAsRead(id: string): Promise<void>;
+  markAllAsRead(notifiable: object): Promise<void>;
+}