@qumra/fanar 0.0.0 → 0.0.2

package/dist/notifications.d.ts

@@ -0,0 +1,846 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { T as Tone } from './lib-DOXggTK6.js';
+
+/**
+ * Schema version.
+ *
+ * Stamped on every message so the receiver knows how to read it. A message
+ * with no `v` is read as `1` — those were sent before the field existed.
+ */
+declare const NOTIFICATION_SCHEMA_VERSION = 1;
+/**
+ * Notification priority — three levels, each with real behaviour.
+ *
+ *   `low`       arrives silently
+ *   `normal`    the default
+ *   `critical`  chimes 35% louder, is **not** cleared by "mark all read",
+ *               and counts toward `needsAction`
+ *
+ * ## There used to be four
+ *
+ * `high` existed in the union type and nowhere else — not one line read it.
+ * Four levels with one that does nothing is worse than three that all work:
+ * whoever picks agonises over a distinction that isn't there, and whoever
+ * reads the code hunts for behaviour they will never find.
+ *
+ * A message still sending `high` is read as `normal` with a warning, not
+ * rejected.
+ */
+type NotificationPriority = 'low' | 'normal' | 'critical';
+declare const NOTIFICATION_PRIORITIES: NotificationPriority[];
+/**
+ * An action — a destination, not a callback.
+ *
+ * `href` is an internal path (`/orders/1052`) or a full URL. The library
+ * never navigates on its own: it calls `onAction` and you wire that to your
+ * router. That is what lets the same message work in a React Router app, a
+ * Next app, and a static page.
+ */
+interface NotificationAction {
+    label: string;
+    href: string;
+}
+/**
+ * The message on the wire — what the server sends and the database stores.
+ *
+ * Every optional field has a default in `parseNotification`, so the server
+ * sends the minimum and the rest is derived.
+ *
+ * @example
+ * {
+ *   "v": 1,
+ *   "id": "ntf_01HZY8K3",
+ *   "kind": "order.created",
+ *   "at": "2026-08-10T14:32:00.000Z",
+ *   "title": "New order #1052",
+ *   "body": "Paid in full, awaiting fulfilment.",
+ *   "priority": "normal",
+ *   "data": { "orderId": "1052", "total": 1480, "currency": "EGP" },
+ *   "action": { "label": "Open the order", "href": "/orders/1052" }
+ * }
+ */
+interface NotificationJSON {
+    /** Schema version — absent reads as `1` */
+    v?: number;
+    /** Stable unique id. Deduplication keys off it, so it must come from the server */
+    id: string;
+    /** Event name, `domain.event` — `order.created`, `stock.depleted` */
+    kind: string;
+    /** ISO 8601 in UTC — `2026-08-10T14:32:00.000Z` */
+    at: string;
+    title: string;
+    body?: string;
+    /**
+     * When it was read, ISO — `null` or absent means unread.
+     *
+     * ## Why a timestamp and not a boolean
+     *
+     * `read: true` is one-way: there is no way to say "make it unread again",
+     * and if you tried, the next sync would flip it back — because
+     * "read wins" has no reference to compare against.
+     *
+     * A timestamp gives the same guarantee (newest wins) and three more things:
+     * "unread" becomes a newer event, an optimistic rollback can tell its own
+     * mark from another device's mark that landed in the same instant, and
+     * time-to-read falls out for free.
+     */
+    readAt?: string | null;
+    /** @deprecated Use `readAt` — this is still read and converted, and will be removed */
+    read?: boolean;
+    priority?: NotificationPriority;
+    /**
+     * Grouping key — collapses **toasts only**.
+     *
+     * A new message replaces the previous one from the same group in the toast
+     * queue. Three toasts from the same source landing together is exactly the
+     * noise that makes a merchant turn notifications off.
+     *
+     * ## The inbox does not collapse
+     *
+     * All three stay as separate rows. A toast interrupts, so collapsing it is
+     * a kindness; a row is read at leisure, so collapsing it hides information.
+     *
+     * Durable collapsing ("3 new messages" as one row) is the server's job — it
+     * is the only side that sees the whole time window. Client-side collapsing
+     * only sees what reached this tab. Toasts don't have that problem because
+     * they are per-tab by nature, live for seconds, and nobody counts them.
+     */
+    group?: string;
+    /** Event payload — the library never reads it, it hands it back to you */
+    data?: Record<string, unknown>;
+    action?: NotificationAction;
+    /**
+     * Silence one message — `'none'` and nothing else.
+     *
+     * Sound normally comes from the kind registry. This is for the exception:
+     * the same kind arriving silently during a bulk import, say. There is no
+     * other value — the chime itself is not swappable per message.
+     */
+    sound?: 'none';
+}
+/**
+ * The message after validation — this is what components work with.
+ *
+ * The difference from `NotificationJSON`: dates are `Date`, and optionals are
+ * filled with their defaults. So no component ever writes `?? 'normal'` or
+ * `new Date(...)` again — normalisation happens once, at the boundary.
+ */
+interface Notification {
+    v: number;
+    id: string;
+    kind: string;
+    at: Date;
+    title: string;
+    body?: string;
+    /** When it was read — `null` means unread */
+    readAt: Date | null;
+    /** Shorthand for `readAt !== null` — derived, never stored */
+    read: boolean;
+    priority: NotificationPriority;
+    group?: string;
+    data: Record<string, unknown>;
+    action?: NotificationAction;
+    sound?: 'none';
+}
+/**
+ * The translate function — yours, not the library's.
+ *
+ * ## Why the library does not translate
+ *
+ * The first implementation was `locale.startsWith('ar') ? '…' : '…'` inside
+ * the registry. That works for two kinds and falls apart at the twelfth:
+ *
+ *   - Strings end up buried in code, where no translator can reach them
+ *   - Arabic has a dual as well as a plural, and each inflects the noun
+ *     differently (talab · talabaan · thalaath talabaat, for one, two and
+ *     three orders). No `startsWith` check can produce that
+ *   - And if the project already has an i18n system, this builds a second
+ *     one beside it
+ *
+ * So the library owns the **hook point**, not the translation: it calls `t`
+ * with a key and values, and `t` comes from `NotificationProvider`. Strings
+ * stay in your catalogue, pluralisation stays with the system built for it,
+ * and the library stays unaware of language — exactly as it stays unaware of
+ * what `order.created` means.
+ */
+type NotificationTranslate = (key: string, vars?: Record<string, unknown>) => ReactNode;
+/**
+ * A kind's sound — one chime, or silence.
+ *
+ * `notify` is the only notification chime. It is inlined as a data URI in
+ * `chime.ts`, so there is no file to copy and no path to break when the
+ * library moves to another project. `none` silences the whole kind — for
+ * things worth reading but not worth interrupting for.
+ *
+ * The chime itself is **not swappable**: it is part of Qumra's identity, like
+ * the colours and the typeface. What a project decides is which kinds ring
+ * and which arrive quietly.
+ */
+type NotificationSoundName = 'notify' | 'none';
+/**
+ * A notification kind — the mapping from an event name to its look and sound.
+ *
+ * This is what makes the system portable: the library does not know what
+ * `order.created` means, it knows how to read the registry. Each project
+ * registers its own kinds.
+ */
+interface NotificationKind {
+    /** The event name exactly as the server sends it — `order.created` */
+    kind: string;
+    /** Human-readable name — shown in notification settings and filters */
+    label: string;
+    icon: ComponentType<{
+        size?: number;
+        strokeWidth?: number;
+    }>;
+    /**
+     * Status tone — neutral by default, on purpose.
+     *
+     * This says "this one is worrying", not "this one is from the orders
+     * module". If every kind took a colour, the inbox becomes a rainbow and the
+     * urgent item is lost in it.
+     */
+    tone?: Tone;
+    /** The kind's priority, used when the message does not set one */
+    priority?: NotificationPriority;
+    /**
+     * Whether this kind rings — `notify` by default.
+     *
+     * This is the only decision sound exposes, and it is a product decision,
+     * not an identity one: "app updated" is not worth interrupting for,
+     * "payment failed" is. The chime, its loudness, and its rhythm are fixed in
+     * the library.
+     */
+    sound?: NotificationSoundName;
+    /**
+     * Build the title from `data` instead of the server's text — **optional**.
+     *
+     * ## The problem it solves
+     *
+     * `title` is stored in whatever language was active when it was sent. The
+     * merchant switches language and finds last month's notifications still in
+     * the old one. This happens in Qumra for real — the apps ship in Arabic and
+     * English.
+     *
+     * ## Why it is opt-in and not the default
+     *
+     * If every kind rendered on the client, fixing a wording or a typo would
+     * need a **frontend deploy**. As it stands that is a server-side edit that
+     * lands immediately. So a kind with a template translates, a kind without
+     * takes the server's text — and you adopt it kind by kind, where it earns
+     * its keep.
+     *
+     * An unregistered kind keeps working off the server's text, so the backend
+     * can ship a new kind without waiting for the frontend.
+     *
+     * ## The template calls `t`, it does not translate
+     *
+     * Key and values only. The string lives in your catalogue, and plurals and
+     * inflection are your i18n system's job.
+     *
+     * If the project never passes `t` to the provider, the template is
+     * **ignored** and the server's text is shown — safer than a raw key in
+     * front of a merchant.
+     *
+     * @example
+     * {
+     *   kind: 'order.created',
+     *   title: (n, t) => t('notif.order.created', { id: n.data.orderId }),
+     * }
+     */
+    title?: (n: Notification, t: NotificationTranslate) => ReactNode;
+    /** Same idea as `title`, for the line underneath */
+    body?: (n: Notification, t: NotificationTranslate) => ReactNode;
+}
+/**
+ * A kind after resolution — look and sound guaranteed, templates not.
+ *
+ * A missing `title`/`body` is **meaning**, not absence: it says "use the
+ * server's text". So no default is filled in for them — one would overwrite
+ * text that came from the server with an empty string.
+ */
+interface ResolvedKind extends Required<Omit<NotificationKind, 'title' | 'body'>> {
+    title?: NotificationKind['title'];
+    body?: NotificationKind['body'];
+    /** This kind is not registered, and these values come from the fallback */
+    unknown: boolean;
+}
+interface NotificationKindRegistry {
+    /** Returns the kind, or the fallback with `unknown: true` if unregistered */
+    get: (kind: string) => ResolvedKind;
+    /** Every registered kind — for a notification settings screen */
+    list: () => ResolvedKind[];
+    has: (kind: string) => boolean;
+}
+
+type NotificationParseResult = {
+    ok: true;
+    value: Notification;
+    warnings: string[];
+} | {
+    ok: false;
+    issues: string[];
+};
+interface NotificationBatch {
+    items: Notification[];
+    /** اللي اتعزل — الرسالة الخام وسبب الرفض، عشان يتسجّل مش يتبلع */
+    rejected: {
+        raw: unknown;
+        issues: string[];
+    }[];
+    /** تحذيرات على رسايل عدّت — حقل اتجاهل، إصدار أحدث */
+    warnings: string[];
+}
+/**
+ * بيحقّق رسالة واحدة ويطبّعها.
+ *
+ * المطلوب: `id` و`kind` و`at` و`title`. الباقي بياخد افتراضي.
+ * `at` لازم يكون تاريخ ISO مقروء — الرقم أو النص المكسور بيترفض، لأن
+ * `Invalid Date` بيعدّي صامت وبيطلع «NaN من كذا دقيقة» في الواجهة.
+ */
+interface ParseOptions {
+    /**
+     * سجلّ الأنواع — منه بييجي افتراضي الأولوية لما الرسالة ما تحدّدش.
+     *
+     * من غيره الرسالة اللي مافيهاش `priority` بتاخد `normal` مهما كان
+     * نوعها — يعني `payment.failed` المسجّل `critical` بيوصل عادي،
+     * والسجلّ بيبقى زينة. وده بيكسر أساس النظام: المكتبة مابتعرفش
+     * `order.created` يعني إيه، بتعرف تقرا السجلّ.
+     */
+    kinds?: NotificationKindRegistry;
+}
+declare function parseNotification(raw: unknown, options?: ParseOptions): NotificationParseResult;
+/**
+ * بيحقّق دفعة ويعزل الوحش.
+ *
+ * بيقبل مصفوفة، أو نص JSON، أو كائن فيه `items`/`notifications` —
+ * التلات أشكال اللي الـAPIs بتبعت بيهم. وبيرتّب بالأحدث، وبيلغّي
+ * تكرار الـ`id` (آخر نسخة بتكسب: التحديث بيوصل بنفس المعرّف).
+ */
+declare function parseNotifications(raw: unknown, options?: ParseOptions): NotificationBatch;
+/**
+ * بيرجّع الرسالة لصيغتها على السلك — للتخزين أو إعادة الإرسال.
+ *
+ * عكس `parseNotification` بالظبط: `parse(serialize(n))` بيدّي `n`.
+ * لازم يفضل كده، وإلا الرسالة اللي اتخزّنت مابترجعش زي ما دخلت.
+ */
+declare function serializeNotification(n: Notification): NotificationJSON;
+
+/**
+ * بينشئ سجلّ أنواع.
+ *
+ * @param kinds الأنواع المسجّلة
+ * @param fallback تجاوز الشكل الاحتياطي للنوع المش معروف
+ *
+ * @example
+ * const KINDS = createKindRegistry([
+ *   { kind: 'ticket.assigned', label: 'تذكرة', icon: Ticket, priority: 'critical' },
+ * ])
+ * KINDS.get('ticket.assigned').icon      // Ticket
+ * KINDS.get('حاجة.غريبة').unknown        // true
+ */
+declare function createKindRegistry(kinds: NotificationKind[], fallback?: Partial<Omit<ResolvedKind, 'kind' | 'unknown'>>): NotificationKindRegistry;
+/**
+ * أنواع التجارة الإلكترونية — طقم جاهز لمنتجات قمرة.
+ *
+ * ده **مثال مسجّل** مش جزء من العقد. المشروع التاني بيبني سجلّه
+ * بـ`createKindRegistry` ومابياخدش الطقم ده.
+ *
+ * ── واللون هنا استثناء مش قاعدة ─────────────────────────────────────────
+ * أربعة بس من اتناشر ليهم نغمة: فشل الدفع والمخزون الخالص والطلب
+ * المتعثّر والمرتجع. الباقي محايد. لو كل نوع خد لونه، مافيش حاجة
+ * بتتشاف قبل حاجة — واللون بيبطّل يعني حالة.
+ *
+ * ── و`critical` تلاتة بس ────────────────────────────────────────────────
+ * القاعدة: نزيف **مستمرّ لحد ما حد يتصرّف**. فشل التحصيل والمخزون
+ * الخالص والطلب المتعثّر بيكلّفوا كل يوم بيعدّي؛ المرتجع حصل وخلاص.
+ * والفرق مش أكاديمي: `critical` مابتتمسحش بـ«تعليم الكل»، فلو اتوسّعت
+ * الحماية بتبقى ضجيج مالوش مفتاح إطفاء.
+ *
+ * ── والقوالب على اتنين بس ───────────────────────────────────────────────
+ * `order.created` و`payout.sent` عندهم قالب بينادي `t` بمفتاح وقيم،
+ * فبيترجموا من كتالوج المشروع. الباقي بياخد نصّ السيرفر — عشان تصليح
+ * صياغة يفضل تعديل سيرفر بيوصل فورًا مش نشر فرونت.
+ *
+ * ومن غير `t` على المزوّد، القوالب بتتجاهل والكل بياخد نصّ السيرفر.
+ *
+ * ── والصوت واحد أو ولا حاجة ─────────────────────────────────────────────
+ * النغمة نفسها لكل نوع بيستاهل مقاطعة، و`none` للي بيتقرا ومابيستاهلش:
+ * تحديث تطبيق وملخّص المجتمع. نغمات متعدّدة بتفترض إن التاجر هيحفظ
+ * إن النازلة يعني دفع فشل — وده مابيحصلش، بيسمع رنّة فبيبصّ.
+ * والإلحاح بيتقال بالعلوّ: `critical` بتعلى ٣٥٪.
+ */
+declare const QUMRA_KINDS: NotificationKind[];
+/** سجلّ قمرة جاهز — `QUMRA_NOTIFICATIONS.get('order.created')` */
+declare const QUMRA_NOTIFICATIONS: NotificationKindRegistry;
+
+/** الصوت الوحيد في المكتبة — `none` بتسكّت النوع */
+declare const NOTIFICATION_SOUNDS: Exclude<NotificationSoundName, 'none'>[];
+interface UseNotificationSoundOptions {
+    /** سجلّ الأنواع — منه بييجي صوت كل نوع (`notify` أو `none`) */
+    kinds: NotificationKindRegistry;
+}
+interface NotificationSoundApi {
+    /** الصوت اتفكّ وجاهز — قبلها أي `play` بتتبلع */
+    ready: boolean;
+    muted: boolean;
+    setMuted: (muted: boolean) => void;
+    /**
+     * بيفكّ الصوت — **لازم من معالج حدث مستخدم حقيقي**.
+     *
+     * بتتنادى لوحدها على أول ضغطة لو `autoUnlock`. النداء اليدوي لزرار
+     * «شغّل الصوت» في الإعدادات.
+     */
+    unlock: () => Promise<boolean>;
+    /** بيرنّ حسب النوع — بيحترم الكتم والحدّ الأدنى والأولوية */
+    play: (n: Notification) => void;
+    /** بيرنّ حالاً — لزرار «جرّب الصوت» في الإعدادات */
+    preview: () => void;
+}
+declare function useNotificationSound({ kinds }: UseNotificationSoundOptions): NotificationSoundApi;
+
+interface NotificationsApi {
+    /** كل الرسايل، الأحدث الأول */
+    items: Notification[];
+    /** عدد غير المقروء — ده اللي الجرس بيعرضه */
+    unread: number;
+    /**
+     * غير المقروء اللي «تعليم الكل» مش بيمسحه — الحرج.
+     *
+     * مفصول عن `unread` عن قصد: بعد «تعليم الكل» العدّاد بينزل لكن
+     * مش لصفر، وده بيتقرا عطل لو مافيش رقم تاني بيفسّره. والفصل بيسمح
+     * بوزن بصري مختلف — نقطة حمرا مابتروحش أبداً بترجّع نفس الضغط
+     * اللي بيخلّي التاجر يطفّي الإشعارات.
+     */
+    needsAction: number;
+    /** الوارد لسه — اللي الكروت الطايرة بتعرضه */
+    arrivals: Notification[];
+    /** المرفوض من آخر `hydrate`/`receive` — للتسجيل مش للعرض */
+    rejected: NotificationBatch['rejected'];
+    /**
+     * بيحمّل الموجود من قبل — **صامت وإضافي**.
+     *
+     * بيضيف ويحدّث ومابيشيلش. ده نداء أول تحميل، وتحميل صفحة تانية،
+     * وأي دفعة قديمة.
+     */
+    hydrate: (raw: unknown) => NotificationBatch;
+    /**
+     * مزامنة — **صامتة وبتشيل**.
+     *
+     * زي `hydrate` بس بتشيل كمان اللي السيرفر مابعتوش، **جوّه المدى
+     * الزمني اللي الدفعة بتغطّيه وبس**. فمزامنة الصفحة الأولى مابتمسحش
+     * الصفحات اللي تحتها.
+     */
+    sync: (raw: unknown) => NotificationBatch;
+    /**
+     * بيستقبل وارد جديد — بيرنّ وبيطلع طاير.
+     *
+     * بياخد رسالة واحدة أو دفعة. الرسالة المرفوضة بتتعزل ومابتوقّعش
+     * الباقي.
+     */
+    receive: (raw: unknown) => NotificationBatch;
+    /**
+     * إشعار محلّي من غير سيرفر — بيملى `id` و`at` و`v` لوحده.
+     *
+     * للأفعال اللي التطبيق بيعرف نتيجتها فوراً. بيعدّي على نفس
+     * التحقّق، فالمحلّي مابياخدش طريق جانبي.
+     */
+    push: (input: Omit<NotificationJSON, 'id' | 'at' | 'v'> & {
+        id?: string;
+        at?: string;
+    }) => string | null;
+    markRead: (id: string) => void;
+    markAllRead: () => void;
+    /**
+     * رجّعهم غير مقروئين — للتراجع، ولزرار «علّمه كغير مقروء».
+     *
+     * فعل باسمه زي باقي الـAPI (`dismiss` · `markAllRead` · `sync`)
+     * بدل `setRead(ids, false)`: العلَم البوليان بيخلّي مكان النداء
+     * يحتاج قراية التوقيع عشان يتفهم.
+     */
+    markUnread: (ids: string[]) => void;
+    /** بيلغي شاهد الشيل وبيرجّع الرسالة — للتراجع لما السيرفر يرفض */
+    restore: (n: Notification) => void;
+    /**
+     * السيرفر أكّد الشيل — الشاهد مابقاش لازم.
+     *
+     * من غيرها الشاهد بيستنّى انتهاء صلاحيته على الفاضي، والمجموعة
+     * بتكبر مع كل شيل في الجلسة.
+     */
+    confirmDismiss: (id: string) => void;
+    dismiss: (id: string) => void;
+    clearArrival: (id: string) => void;
+    clearAllArrivals: () => void;
+}
+interface UseNotificationsOptions {
+    /**
+     * سجلّ الأنواع — منه بييجي افتراضي الأولوية.
+     *
+     * من غيره أي رسالة مافيهاش `priority` بتاخد `normal`، فالنوع
+     * المسجّل `critical` بيوصل عادي و`needsAction` بتعدّ غلط.
+     */
+    kinds?: NotificationKindRegistry;
+    /** رسايل أولية — بتتحمّل صامتة زي `hydrate` */
+    initial?: unknown;
+    /** بيتنادى لكل وارد جديد اتقبل — ده مكان الصوت */
+    onReceive?: (n: Notification) => void;
+    /** بيتنادى لما رسالة تترفض — سجّلها، متبلعهاش */
+    onReject?: (rejected: NotificationBatch['rejected']) => void;
+}
+/** `critical` مابيتعلّمش مقروء بـ«تعليم الكل» — «شفته» مش «عالجته» */
+declare const isBulkReadable: (n: Notification) => boolean;
+declare function useNotifications({ kinds, initial, onReceive, onReject, }?: UseNotificationsOptions): NotificationsApi;
+
+/**
+ * تحديث تفاؤلي بتراجع.
+ *
+ * الواجهة بتتغيّر فوراً، والمزامنة بتجري. لو فشلت، `undo` بترجّع
+ * الحالة و`onError` بيقول للمستخدم — لأن التراجع الصامت أوحش من
+ * الفشل نفسه: العدّاد بيرجع يطلع والمستخدم مايعرفش ليه.
+ *
+ * `run` ممكن يرجّع `void` أو وعد، وممكن يرمي متزامن. التلات حالات
+ * بتتعامل واحد — المستدعي اللي مابيزامنش مابيدفعش تمن، واللي
+ * بيزامن مابيحتاجش يلفّ نداءه في `try`.
+ */
+declare function optimistic(run: (() => void | Promise<void>) | undefined, undo: () => void, onError?: (error: unknown) => void): void;
+interface UseNotificationCenterOptions extends UseNotificationsOptions {
+    /** سجلّ الأنواع — بيروح للصوت وبيترجّع عشان يتحطّ في المزوّد */
+    kinds: NotificationKindRegistry;
+    /**
+     * اتقرا إشعار — بالفتح أو بـ«تعليم كمقروء».
+     *
+     * ده مكان المزامنة مع السيرفر. العلامة بتتحطّ **قبل** النداء
+     * (تفاؤلياً) عشان الواجهة ما تستناش الشبكة.
+     *
+     * ── ولو السيرفر رفض ─────────────────────────────────────────────────
+     * ارمي أو رجّع وعداً بيترفض، والمكتبة بترجّع العلامة لوحدها. من
+     * غير كده الواجهة بتوعد بحاجة السيرفر مانفّذهاش: التاجر بيشوف
+     * العدّاد وقع، وبيفتح من جهاز تاني فيلاقيه زي ما هو.
+     *
+     * @example
+     * onRead: async (n) => { await api.markRead(n.id) }   // الفشل بيرجّع العلامة
+     */
+    onRead?: (n: Notification) => void | Promise<void>;
+    /** اتقرا الكل — نداء واحد بدل نداء لكل رسالة. الفشل بيرجّع الكل */
+    onReadAll?: (ids: string[]) => void | Promise<void>;
+    /** اتشال من الصندوق. الفشل بيرجّع الرسالة لمكانها */
+    onDismiss?: (n: Notification) => void | Promise<void>;
+    /**
+     * فشلت مزامنة مع السيرفر واتراجعنا — اعرض توست هنا.
+     *
+     * التراجع الصامت أوحش من الفشل نفسه: العدّاد بيرجع يطلع والمستخدم
+     * مايعرفش ليه.
+     *
+     * و`items` جوّه السياق عشان الرسالة تبقى مفيدة: «تعذّر حفظ قراية»
+     * بتسأل «قراية إيه؟»، و«تعذّر حفظ قراية ٣ إشعارات» بترد.
+     */
+    onSyncError?: (error: unknown, context: {
+        action: 'read' | 'readAll' | 'dismiss';
+        items: Notification[];
+    }) => void;
+    /**
+     * اتضغط إجراء الإشعار — الوجهة في `n.action.href`.
+     *
+     * وصّلها براوترك. الإشعار بيتعلّم مقروء لوحده قبل النداء.
+     */
+    onOpen?: (n: Notification) => void;
+}
+interface NotificationCenter extends NotificationsApi {
+    sound: NotificationSoundApi;
+    /** نفس السجلّ اللي دخل — عشان `NotificationProvider` ياخده من مصدر واحد */
+    kinds: NotificationKindRegistry;
+    /**
+     * الخصائص الجاهزة للمزوّد والأسطح — بتوصّل الفتح والقراءة لوحدها.
+     *
+     * `<NotificationProvider {...inbox.bind.provider}>` بدل ما تكتب
+     * `onAction` و`onOpen` في كل سطح.
+     */
+    bind: {
+        provider: {
+            kinds: NotificationKindRegistry;
+            onAction: (n: Notification) => void;
+        };
+        surface: {
+            items: Notification[];
+            unread: number;
+            needsAction: number;
+            sound: NotificationSoundApi;
+            onMarkAllRead: () => void;
+            onDismiss: (id: string) => void;
+            onOpen: (n: Notification) => void;
+        };
+    };
+}
+/**
+ * الحالة والصوت موصولين — نداء واحد.
+ *
+ * @example
+ * const inbox = useNotificationCenter({
+ *   kinds: QUMRA_NOTIFICATIONS,
+ *   initial: await api.notifications(),   // بيتحمّل صامت
+ * })
+ *
+ * <NotificationProvider kinds={inbox.kinds} onAction={(n) => navigate(n.action.href)}>
+ *   <NotificationMenu unread={inbox.unread} items={inbox.items} sound={inbox.sound} … />
+ *   <NotificationToastHost items={inbox.arrivals} onClose={inbox.clearArrival} />
+ * </NotificationProvider>
+ *
+ * // والوارد من السوكت — بيرنّ وبيطلع طاير
+ * socket.on('notification', inbox.receive)
+ */
+declare function useNotificationCenter({ kinds, onReceive, onRead, onReadAll, onDismiss, onOpen, onSyncError, ...rest }: UseNotificationCenterOptions): NotificationCenter;
+
+/**
+ * الوقت النسبي — «من دقيقتين»، «إمبارح»، «من ٣ شهور».
+ *
+ * أقل من نصّ دقيقة بيتقري «الآن» بدل «قبل ٣٠ ثانية»: الفرق مالوش
+ * معنى للقارئ، والرقم اللي بيتغيّر كل ثانية بيسحب العين. والنصّ من
+ * `Intl` — فبيشتغل على أي لغة من غير ما المكتبة تعرفها.
+ *
+ * @param at وقت الإشعار
+ * @param locale اللغة — الافتراضي `ar`
+ * @param now لحقن الوقت في الاختبار
+ */
+declare function formatRelativeTime(at: Date, locale?: string, now?: Date): string;
+/**
+ * كل كام يجب إعادة الرسم عشان النصّ يفضل صح.
+ *
+ * «من دقيقة» بيبقى غلط بعد دقيقة، و«من ٣ شهور» بيفضل صح لأسبوع.
+ * المؤقّت بيتظبط على دقّة الوحدة بدل ما يشتغل كل ثانية على قايمة
+ * فيها أربعين سطر.
+ */
+declare function relativeTickMs(at: Date, now?: Date): number;
+
+interface NotificationContext {
+    kinds: NotificationKindRegistry;
+    locale: string;
+    t?: NotificationTranslate;
+    onAction?: (n: Notification) => void;
+}
+interface NotificationProviderProps {
+    /** The kind registry — Qumra's registry by default */
+    kinds?: NotificationKindRegistry;
+    /** Locale for relative time — `ar` by default */
+    locale?: string;
+    /**
+     * The translate function from your own i18n system — for kind title templates.
+     *
+     * Without it templates are ignored and the server's text is shown. The
+     * library does not translate on its own: it calls `t(key, vars)` and
+     * nothing more, so strings stay in your catalogue and pluralisation stays
+     * your system's job.
+     */
+    t?: NotificationTranslate;
+    /**
+     * Navigation to a notification's destination.
+     *
+     * The library does not navigate on its own, because a message carries an
+     * `href` and not a callback. Take it from `n.action.href` and hand it to
+     * your router.
+     */
+    onAction?: (n: Notification) => void;
+    children: ReactNode;
+}
+/** Distributes registry, locale and navigation to every surface — once, at the root */
+declare function NotificationProvider({ kinds, locale, t, onAction, children, }: NotificationProviderProps): react.JSX.Element;
+declare const useNotificationContext: () => NotificationContext;
+interface NotificationBellProps {
+    unread: number;
+    /**
+     * How many of them need action — this changes the badge's **shape**, not its
+     * number.
+     *
+     * A red dot that never goes away invites exactly the press that makes a
+     * merchant turn notifications off. So the badge stays the unread count, and
+     * critical items are marked with a ring around it — a second signal on the
+     * same number, not a second number.
+     */
+    needsAction?: number;
+    onClick: () => void;
+    /** Reaches `aria-expanded` — a bell that opens a panel has to say so */
+    expanded?: boolean;
+    label?: string;
+    /** "3 unread" — the number belongs in `aria-label`, not only in the shape */
+    unreadLabel?: (n: number) => string;
+    className?: string;
+}
+/**
+ * The bell button with its unread badge.
+ *
+ * The badge is red and ringed in the background colour — without the ring the
+ * number collides with whatever icon is behind it and half of it becomes
+ * unreadable. The number is in `aria-label` too: a screen reader never sees
+ * the badge, and a bell that only says "notifications" makes a listener open
+ * the inbox every time just to find out whether anything is there.
+ */
+declare function NotificationBell({ unread, needsAction, onClick, expanded, label, unreadLabel, className, }: NotificationBellProps): react.JSX.Element;
+interface NotificationRowProps {
+    item: Notification;
+    /** Called after the destination opens — mark it read here */
+    onOpen?: (n: Notification) => void;
+    onDismiss?: (id: string) => void;
+    dismissLabel?: string;
+    unreadLabel?: string;
+}
+/**
+ * A single notification row.
+ *
+ * Unread is marked twice: with a dot and with heavier text. Colour alone is
+ * not enough — one man in twelve cannot separate two close greys, and weight
+ * reads regardless.
+ *
+ * And the row is **not one big button**. An inbox holds rows that open
+ * something and rows that are only read, and if the whole row is pressable
+ * someone who meant to read lands on another page instead. The action is a
+ * button with a name.
+ */
+declare function NotificationRow({ item, onOpen, onDismiss, dismissLabel, unreadLabel, }: NotificationRowProps): react.JSX.Element;
+interface NotificationListProps {
+    items: Notification[];
+    onOpen?: (n: Notification) => void;
+    onDismiss?: (id: string) => void;
+    emptyTitle?: ReactNode;
+    emptyDescription?: ReactNode;
+    className?: string;
+}
+/** The list itself — identical in the dropdown panel and in the side drawer */
+declare function NotificationList({ items, onOpen, onDismiss, emptyTitle, emptyDescription, className, }: NotificationListProps): react.JSX.Element;
+interface NotificationPanelProps extends NotificationListProps {
+    title?: ReactNode;
+    unread?: number;
+    /**
+     * The unread that "mark all read" does not clear.
+     *
+     * This has to be shown: the badge drops from 12 to 2 and stops, and anyone
+     * who does not know why presses again and nothing happens, so it reads as a
+     * bug. One line says why, once.
+     */
+    needsAction?: number;
+    onMarkAllRead?: () => void;
+    markAllLabel?: string;
+    /** A "see all" footer — without it the inbox is the end of the road */
+    onViewAll?: () => void;
+    viewAllLabel?: string;
+    /** The mute button in the header — pass it from `useNotificationSound` */
+    sound?: {
+        muted: boolean;
+        setMuted: (m: boolean) => void;
+        ready: boolean;
+    };
+}
+/**
+ * The dropdown panel — the notification inbox beside the bell.
+ *
+ * The list has a bounded height and **scrolls inside itself**: a panel that
+ * grows with its list reaches the bottom of the screen and cuts the last
+ * notification off with nothing to show it was cut.
+ *
+ * And "mark all read" disappears once nothing is unread — a button that does
+ * nothing, always present, teaches the user that buttons here do not respond.
+ */
+declare function NotificationPanel({ items, title, unread, needsAction, onMarkAllRead, markAllLabel, onViewAll, viewAllLabel, sound, onOpen, onDismiss, emptyTitle, emptyDescription, className, }: NotificationPanelProps): react.JSX.Element;
+interface SoundToggleProps {
+    muted: boolean;
+    setMuted: (m: boolean) => void;
+    /** Audio is unlocked — before that the button says the browser blocked it, not the user */
+    ready: boolean;
+    className?: string;
+}
+/**
+ * Muting notification sound.
+ *
+ * The third state matters: **not muted, but the browser has not unlocked
+ * audio yet**. The button says so instead of pretending sound is on — someone
+ * waiting for a chime that never comes deserves to know why.
+ */
+declare function SoundToggle({ muted, setMuted, ready, className }: SoundToggleProps): react.JSX.Element;
+interface NotificationMenuProps extends Omit<NotificationPanelProps, 'unread'> {
+    unread: number;
+    bellLabel?: string;
+    /**
+     * Which edge the panel aligns to against the bell — `end` by default.
+     *
+     * The bell sits at the `end` of the top bar, so the panel extends toward
+     * `start` and stays on screen. Move the bell and this has to flip.
+     */
+    align?: 'start' | 'end';
+    /**
+     * Above the bell or below it — `bottom` by default.
+     *
+     * A bottom bar on mobile needs `top`: a panel dropping from a bell at the
+     * bottom of the screen lands entirely outside it.
+     */
+    side?: 'top' | 'bottom';
+    className?: string;
+}
+/**
+ * The bell and the panel as one unit — this is what a top bar mounts.
+ *
+ * It closes on an outside click and on Escape. Both are needed: the outside
+ * click is what a mouse expects, and Escape is the only way out for anyone on
+ * a keyboard.
+ */
+declare function NotificationMenu({ unread, bellLabel, align, side, className, onViewAll, onOpen, ...panel }: NotificationMenuProps): react.JSX.Element;
+interface NotificationDrawerProps extends NotificationListProps {
+    open: boolean;
+    onClose: () => void;
+    title?: ReactNode;
+    unread?: number;
+    /** Same as `NotificationPanel` — the explanation has to show on mobile too */
+    needsAction?: number;
+    onMarkAllRead?: () => void;
+    markAllLabel?: string;
+    closeLabel?: string;
+}
+/**
+ * The side drawer — the same inbox, from the edge of the screen.
+ *
+ * Why two and not one: the dropdown panel is anchored to the bell, and on a
+ * 360px screen that means a panel covering the whole screen with one edge
+ * hanging off it. The drawer opens from `inline-end` — the left in Arabic and
+ * the right in English, by itself.
+ *
+ * And the list inside is **identical**, down to the character: someone who
+ * saw a notification on desktop and looks for it on mobile has to see the
+ * same row, or they will think there are two.
+ */
+declare function NotificationDrawer({ open, onClose, items, title, unread, needsAction, onMarkAllRead, markAllLabel, closeLabel, onOpen, onDismiss, emptyTitle, emptyDescription, }: NotificationDrawerProps): react.JSX.Element;
+/**
+ * The screen corner a toast drops into.
+ *
+ * `start`/`end` are logical, not left and right: `end` means the left in
+ * Arabic and the right in English. The bell moves with the language, and the
+ * notification has to move with it — otherwise it arrives from one side and
+ * is filed on the other.
+ */
+type NotificationPlacement = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+interface NotificationToastHostProps {
+    items: Notification[];
+    onClose: (id: string) => void;
+    onOpen?: (n: Notification) => void;
+    /**
+     * The corner — `top-end` by default, so it lands beside the bell.
+     *
+     * Keep it away from `ToastHost`'s corner (`bottom-start` by default): a
+     * toast says "the thing you did happened" and a notification says
+     * "something arrived from outside", and if both come from the same place
+     * they read as one queue.
+     */
+    placement?: NotificationPlacement;
+    /** Column width above `sm` — below it takes the full width */
+    width?: string;
+    closeLabel?: string;
+    regionLabel?: string;
+    className?: string;
+}
+/**
+ * The toast notification — the card that drops in when something arrives.
+ *
+ * `aria-live="polite"`, not `assertive`: the latter cuts a screen reader off
+ * mid-sentence. A notification is already an interruption; it does not earn a
+ * second one — whoever is listening will hear it once the line finishes.
+ */
+declare function NotificationToastHost({ items, onClose, onOpen, placement, width, closeLabel, regionLabel, className, }: NotificationToastHostProps): react.JSX.Element | null;
+
+export { NOTIFICATION_PRIORITIES, NOTIFICATION_SCHEMA_VERSION, NOTIFICATION_SOUNDS, type Notification, type NotificationAction, type NotificationBatch, NotificationBell, type NotificationBellProps, type NotificationCenter, NotificationDrawer, type NotificationDrawerProps, type NotificationJSON, type NotificationKind, type NotificationKindRegistry, NotificationList, type NotificationListProps, NotificationMenu, type NotificationMenuProps, NotificationPanel, type NotificationPanelProps, type NotificationParseResult, type NotificationPlacement, type NotificationPriority, NotificationProvider, type NotificationProviderProps, NotificationRow, type NotificationRowProps, type NotificationSoundApi, type NotificationSoundName, NotificationToastHost, type NotificationToastHostProps, type NotificationTranslate, type NotificationsApi, type ParseOptions, QUMRA_KINDS, QUMRA_NOTIFICATIONS, type ResolvedKind, SoundToggle, type SoundToggleProps, type UseNotificationCenterOptions, type UseNotificationSoundOptions, type UseNotificationsOptions, createKindRegistry, formatRelativeTime, isBulkReadable, optimistic, parseNotification, parseNotifications, relativeTickMs, serializeNotification, useNotificationCenter, useNotificationContext, useNotificationSound, useNotifications };