@codingfactory/notify-kit-client 0.1.0

package/dist/index.js

@@ -0,0 +1,737 @@
+import { useNotifyKitStore } from './chunk-7LQBNDRD.js';
+export { InvalidSnoozeDurationError, NOTIFY_KIT_MODALS_KEY, NOTIFY_KIT_STORE_KEY, provideNotifyKitModals, provideNotifyKitStore, resetNotifyKitStore, useNotifyKitModals, useNotifyKitStore } from './chunk-7LQBNDRD.js';
+import { provide, inject, ref, computed, onMounted, onUnmounted, watch } from 'vue';
+
+// src/types/notification.ts
+var NOTIFICATION_CATEGORIES = [
+  "workspace",
+  "security",
+  "orders",
+  "social",
+  "system",
+  "marketing"
+];
+var NOTIFICATION_LEVELS = [
+  "info",
+  "success",
+  "warning",
+  "danger"
+];
+function isValidCategory(value) {
+  return typeof value === "string" && NOTIFICATION_CATEGORIES.includes(value);
+}
+function isValidLevel(value) {
+  return typeof value === "string" && NOTIFICATION_LEVELS.includes(value);
+}
+function isNotifyKitNotification(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  if (typeof obj["id"] !== "string") return false;
+  if (typeof obj["key"] !== "string") return false;
+  if (typeof obj["title"] !== "string") return false;
+  if (typeof obj["body"] !== "string") return false;
+  if (typeof obj["created_at"] !== "string") return false;
+  if (!isValidCategory(obj["category"])) return false;
+  if (!isValidLevel(obj["level"])) return false;
+  if (obj["action_url"] !== null && typeof obj["action_url"] !== "string") return false;
+  if (obj["workspace_id"] !== null && typeof obj["workspace_id"] !== "string") return false;
+  if (obj["group_key"] !== null && typeof obj["group_key"] !== "string") return false;
+  if (obj["idempotency_key"] !== null && typeof obj["idempotency_key"] !== "string")
+    return false;
+  if (obj["read_at"] !== null && typeof obj["read_at"] !== "string") return false;
+  if (typeof obj["data"] !== "object" || obj["data"] === null) {
+    if (obj["data"] !== void 0 && (typeof obj["data"] !== "object" || obj["data"] === null)) {
+      return false;
+    }
+  }
+  if (obj["modal"] !== null && typeof obj["modal"] !== "object") return false;
+  return true;
+}
+function isModalEnabled(notification) {
+  return notification.modal?.enabled ?? false;
+}
+
+// src/types/modal.ts
+function isModalSpec(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  if (typeof obj["enabled"] !== "boolean") return false;
+  if (typeof obj["requires_ack"] !== "boolean") return false;
+  if (!Array.isArray(obj["snooze_options_minutes"])) return false;
+  const snoozeOptions = obj["snooze_options_minutes"];
+  for (const option of snoozeOptions) {
+    if (typeof option !== "number" || !Number.isInteger(option) || option < 1) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/types/preferences.ts
+function isChannelPreferences(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  return typeof obj["database"] === "boolean" && typeof obj["broadcast"] === "boolean" && typeof obj["mail"] === "boolean";
+}
+
+// src/types/api.ts
+function isPaginationMeta(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  return typeof obj["current_page"] === "number" && typeof obj["last_page"] === "number" && typeof obj["per_page"] === "number" && typeof obj["total"] === "number";
+}
+function isMeResponse(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  return typeof obj["broadcast_channel"] === "string";
+}
+function isUnreadCountResponse(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  return typeof obj["count"] === "number";
+}
+
+// src/client/NotifyKitClient.ts
+var NotifyKitApiError = class extends Error {
+  constructor(message, status, errors) {
+    super(message);
+    this.status = status;
+    this.errors = errors;
+  }
+  name = "NotifyKitApiError";
+};
+var NotifyKitClient = class {
+  baseUrl;
+  getAuthHeaders;
+  fetchFn;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.getAuthHeaders = config.getAuthHeaders ?? void 0;
+    this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  // ============================================
+  // Me
+  // ============================================
+  /**
+   * Get the current user's broadcast channel information.
+   */
+  async getMe() {
+    return this.request("GET", "/me");
+  }
+  // ============================================
+  // Notifications
+  // ============================================
+  /**
+   * List notifications for the current user.
+   */
+  async listNotifications(params) {
+    const queryParams = this.buildNotificationParams(params);
+    const queryString = queryParams.toString();
+    const url = queryString.length > 0 ? `/notifications?${queryString}` : "/notifications";
+    return this.request("GET", url);
+  }
+  /**
+   * Get the count of unread notifications.
+   */
+  async getUnreadCount() {
+    return this.request(
+      "GET",
+      "/notifications/unread-count"
+    );
+  }
+  /**
+   * Mark a notification as read.
+   */
+  async markRead(id) {
+    await this.request("PATCH", `/notifications/${id}/read`);
+  }
+  /**
+   * Mark all notifications as read.
+   */
+  async markAllRead() {
+    await this.request("POST", "/notifications/read-all");
+  }
+  /**
+   * Delete a notification.
+   */
+  async deleteNotification(id) {
+    await this.request("DELETE", `/notifications/${id}`);
+  }
+  // ============================================
+  // Groups (Phase 2)
+  // ============================================
+  /**
+   * Mark all notifications in a group as read.
+   */
+  async markGroupRead(groupKey) {
+    await this.request("PATCH", `/notifications/groups/${groupKey}/read`);
+  }
+  /**
+   * Get all notifications in a group.
+   */
+  async getGroupNotifications(groupKey, params) {
+    const queryParams = new URLSearchParams();
+    if (params?.page !== void 0) {
+      queryParams.set("page", String(params.page));
+    }
+    if (params?.per_page !== void 0) {
+      queryParams.set("per_page", String(params.per_page));
+    }
+    const queryString = queryParams.toString();
+    const url = queryString.length > 0 ? `/notifications/groups/${groupKey}?${queryString}` : `/notifications/groups/${groupKey}`;
+    return this.request("GET", url);
+  }
+  // ============================================
+  // Modals
+  // ============================================
+  /**
+   * List outstanding modal notifications.
+   */
+  async listModals() {
+    const response = await this.request(
+      "GET",
+      "/modals"
+    );
+    return response.data;
+  }
+  /**
+   * Acknowledge a modal notification.
+   */
+  async ackModal(id) {
+    await this.request("POST", `/modals/${id}/ack`);
+  }
+  /**
+   * Snooze a modal notification.
+   */
+  async snoozeModal(id, minutes) {
+    await this.request("POST", `/modals/${id}/snooze`, { minutes });
+  }
+  // ============================================
+  // Preferences
+  // ============================================
+  /**
+   * Get the current user's notification preferences.
+   */
+  async getPreferences() {
+    return this.request("GET", "/preferences");
+  }
+  /**
+   * Update the current user's notification preferences.
+   */
+  async updatePreferences(preferences) {
+    await this.request("PUT", "/preferences", preferences);
+  }
+  // ============================================
+  // Private helpers
+  // ============================================
+  buildNotificationParams(params) {
+    const queryParams = new URLSearchParams();
+    if (params === void 0) {
+      return queryParams;
+    }
+    if (params.unread === true) {
+      queryParams.set("unread", "true");
+    }
+    if (params.category !== void 0) {
+      queryParams.set("category", params.category);
+    }
+    if (params.workspace_id !== void 0) {
+      queryParams.set("workspace_id", params.workspace_id);
+    }
+    if (params.grouped === true) {
+      queryParams.set("grouped", "1");
+    }
+    if (params.page !== void 0) {
+      queryParams.set("page", String(params.page));
+    }
+    if (params.per_page !== void 0) {
+      queryParams.set("per_page", String(params.per_page));
+    }
+    return queryParams;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (this.getAuthHeaders !== void 0) {
+      const authHeaders = await this.getAuthHeaders();
+      Object.assign(headers, authHeaders);
+    }
+    const requestInit = {
+      method,
+      headers
+    };
+    if (body !== void 0) {
+      requestInit.body = JSON.stringify(body);
+    }
+    const response = await this.fetchFn(url, requestInit);
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new NotifyKitApiError(
+        errorData.message ?? `Request failed with status ${String(response.status)}`,
+        response.status,
+        errorData.errors
+      );
+    }
+    const text = await response.text();
+    if (text.length === 0) {
+      return void 0;
+    }
+    return JSON.parse(text);
+  }
+};
+function createNotifyKitClient(config) {
+  return new NotifyKitClient(config);
+}
+
+// src/client/endpoints.ts
+var ENDPOINTS = {
+  /** GET - Returns broadcast channel for authenticated user */
+  ME: "/me",
+  /** GET - List notifications (supports filters and pagination) */
+  NOTIFICATIONS: "/notifications",
+  /** GET - Get count of unread notifications */
+  UNREAD_COUNT: "/notifications/unread-count",
+  /** PATCH - Mark a specific notification as read */
+  MARK_READ: (id) => `/notifications/${id}/read`,
+  /** POST - Mark all notifications as read */
+  MARK_ALL_READ: "/notifications/read-all",
+  /** DELETE - Delete a specific notification */
+  DELETE_NOTIFICATION: (id) => `/notifications/${id}`,
+  /** PATCH - Mark all notifications in a group as read (Phase 2) */
+  MARK_GROUP_READ: (groupKey) => `/notifications/groups/${groupKey}/read`,
+  /** GET - Get all notifications in a group (Phase 2) */
+  GROUP_NOTIFICATIONS: (groupKey) => `/notifications/groups/${groupKey}`,
+  /** GET - List outstanding modal notifications */
+  MODALS: "/modals",
+  /** POST - Acknowledge a modal notification */
+  ACK_MODAL: (id) => `/modals/${id}/ack`,
+  /** POST - Snooze a modal notification */
+  SNOOZE_MODAL: (id) => `/modals/${id}/snooze`,
+  /** GET - Get user's notification preferences */
+  PREFERENCES: "/preferences"
+};
+var NOTIFY_KIT_CLIENT_KEY = /* @__PURE__ */ Symbol(
+  "notify-kit-client"
+);
+function provideNotifyKitClient(config) {
+  const client = createNotifyKitClient(config);
+  provide(NOTIFY_KIT_CLIENT_KEY, client);
+  return client;
+}
+function useNotifyKitClient(config) {
+  let client;
+  if (config !== void 0) {
+    client = createNotifyKitClient(config);
+  } else {
+    const injectedClient = inject(NOTIFY_KIT_CLIENT_KEY);
+    if (injectedClient === void 0) {
+      throw new Error(
+        "No NotifyKit client available. Either provide config to useNotifyKitClient() or call provideNotifyKitClient() in a parent component."
+      );
+    }
+    client = injectedClient;
+  }
+  return {
+    client,
+    // Me
+    getMe: () => client.getMe(),
+    // Notifications
+    listNotifications: (params) => client.listNotifications(params),
+    getUnreadCount: () => client.getUnreadCount(),
+    markRead: (id) => client.markRead(id),
+    markAllRead: () => client.markAllRead(),
+    deleteNotification: (id) => client.deleteNotification(id),
+    // Groups
+    markGroupRead: (groupKey) => client.markGroupRead(groupKey),
+    getGroupNotifications: (groupKey, params) => client.getGroupNotifications(groupKey, params),
+    // Modals
+    listModals: () => client.listModals(),
+    ackModal: (id) => client.ackModal(id),
+    snoozeModal: (id, minutes) => client.snoozeModal(id, minutes),
+    // Preferences
+    getPreferences: () => client.getPreferences(),
+    updatePreferences: (preferences) => client.updatePreferences(preferences)
+  };
+}
+function useNotifyKitRealtime(options) {
+  const {
+    echo: echoOption,
+    client,
+    autoConnect = true,
+    onNotification,
+    onConnectionChange
+  } = options;
+  const store = useNotifyKitStore();
+  const connectionState = ref("disconnected");
+  const currentChannel = ref(null);
+  const isSubscribed = ref(false);
+  const isConnected = computed(() => connectionState.value === "connected");
+  function getEcho() {
+    return typeof echoOption === "function" ? echoOption() : echoOption;
+  }
+  function setConnectionState(state) {
+    connectionState.value = state;
+    store.setConnectionState(state);
+    onConnectionChange?.(state);
+  }
+  function handleNotification(payload) {
+    if (!isNotifyKitNotification(payload)) {
+      return;
+    }
+    store.addNotification(payload);
+    store.incrementUnreadCount();
+    if (isModalEnabled(payload)) {
+      store.enqueueModal(payload);
+    }
+    onNotification?.(payload);
+  }
+  async function connect() {
+    if (connectionState.value === "connected" || connectionState.value === "connecting") {
+      return;
+    }
+    setConnectionState("connecting");
+    try {
+      const meResponse = await client.getMe();
+      const channel = meResponse.broadcast_channel;
+      currentChannel.value = channel;
+      store.setBroadcastChannel(channel);
+      const echo = getEcho();
+      echo.private(channel).notification(handleNotification);
+      isSubscribed.value = true;
+      setConnectionState("connected");
+    } catch (error) {
+      setConnectionState("error");
+      throw error;
+    }
+  }
+  function disconnect() {
+    if (currentChannel.value !== null && isSubscribed.value) {
+      const echo = getEcho();
+      echo.leave(currentChannel.value);
+      isSubscribed.value = false;
+    }
+    setConnectionState("disconnected");
+  }
+  async function reconnect() {
+    disconnect();
+    await connect();
+  }
+  onMounted(() => {
+    if (autoConnect) {
+      void connect();
+    }
+  });
+  onUnmounted(() => {
+    if (isConnected.value) {
+      disconnect();
+    }
+  });
+  return {
+    isConnected,
+    connectionState,
+    connect,
+    disconnect,
+    reconnect
+  };
+}
+var DEFAULT_CONFIG = {
+  disconnectThresholdMs: 5e3,
+  unreadCountIntervalMs: 3e4,
+  modalsIntervalMs: 12e4,
+  reconnectGracePeriodMs: 2e3
+};
+function useNotifyKitFallback(options) {
+  const { client, connectionState, config: userConfig, onModalsReceived, onUnreadCountReceived } = options;
+  const config = {
+    ...DEFAULT_CONFIG,
+    ...userConfig
+  };
+  const store = useNotifyKitStore();
+  const isPolling = ref(false);
+  const lastPollAt = ref(null);
+  let disconnectTimer = null;
+  let unreadCountInterval = null;
+  let modalsInterval = null;
+  let reconnectGraceTimer = null;
+  async function pollUnreadCount() {
+    try {
+      const response = await client.getUnreadCount();
+      store.setUnreadCount(response.count);
+      lastPollAt.value = Date.now();
+      onUnreadCountReceived?.(response.count);
+    } catch {
+    }
+  }
+  async function pollModals() {
+    try {
+      const modals = await client.listModals();
+      for (const modal of modals) {
+        store.enqueueModal(modal);
+      }
+      store.setLastModalsSync(Date.now());
+      lastPollAt.value = Date.now();
+      onModalsReceived?.(modals);
+    } catch {
+    }
+  }
+  function startPolling() {
+    if (isPolling.value) {
+      return;
+    }
+    isPolling.value = true;
+    void pollUnreadCount();
+    void pollModals();
+    unreadCountInterval = setInterval(() => {
+      void pollUnreadCount();
+    }, config.unreadCountIntervalMs);
+    modalsInterval = setInterval(() => {
+      void pollModals();
+    }, config.modalsIntervalMs);
+  }
+  function stopPolling() {
+    if (!isPolling.value) {
+      return;
+    }
+    isPolling.value = false;
+    if (unreadCountInterval !== null) {
+      clearInterval(unreadCountInterval);
+      unreadCountInterval = null;
+    }
+    if (modalsInterval !== null) {
+      clearInterval(modalsInterval);
+      modalsInterval = null;
+    }
+  }
+  function clearAllTimers() {
+    if (disconnectTimer !== null) {
+      clearTimeout(disconnectTimer);
+      disconnectTimer = null;
+    }
+    if (reconnectGraceTimer !== null) {
+      clearTimeout(reconnectGraceTimer);
+      reconnectGraceTimer = null;
+    }
+  }
+  function handleConnectionStateChange(state) {
+    if (state === "disconnected" || state === "error") {
+      if (reconnectGraceTimer !== null) {
+        clearTimeout(reconnectGraceTimer);
+        reconnectGraceTimer = null;
+      }
+      disconnectTimer ??= setTimeout(() => {
+        startPolling();
+        disconnectTimer = null;
+      }, config.disconnectThresholdMs);
+    } else if (state === "connected") {
+      if (disconnectTimer !== null) {
+        clearTimeout(disconnectTimer);
+        disconnectTimer = null;
+      }
+      if (isPolling.value) {
+        reconnectGraceTimer = setTimeout(() => {
+          stopPolling();
+          void pollUnreadCount();
+          void pollModals();
+          reconnectGraceTimer = null;
+        }, config.reconnectGracePeriodMs);
+      }
+    }
+  }
+  watch(connectionState, handleConnectionStateChange, { immediate: true });
+  onUnmounted(() => {
+    clearAllTimers();
+    stopPolling();
+  });
+  return {
+    isPolling,
+    lastPollAt,
+    startPolling,
+    stopPolling,
+    pollUnreadCount,
+    pollModals
+  };
+}
+
+// src/helpers/toastPolicy.ts
+var DEFAULT_TOAST_CATEGORIES = {
+  workspace: true,
+  security: true,
+  orders: true,
+  social: false,
+  system: true,
+  marketing: true
+};
+var DEFAULT_SOUND_LEVELS = ["danger"];
+var DEFAULT_SOUND_CATEGORIES = ["security"];
+function isCriticalModal(notification) {
+  return notification.modal !== null && notification.modal.enabled && notification.modal.requires_ack;
+}
+function defaultShouldToast(notification, categorySettings) {
+  if (isCriticalModal(notification)) {
+    return false;
+  }
+  return categorySettings[notification.category];
+}
+function defaultShouldPlaySound(notification, soundLevels, soundCategories) {
+  if (soundLevels.includes(notification.level)) {
+    return true;
+  }
+  if (soundCategories.includes(notification.category)) {
+    return true;
+  }
+  return false;
+}
+var defaultToastPolicy = {
+  shouldToast(notification) {
+    return defaultShouldToast(notification, DEFAULT_TOAST_CATEGORIES);
+  },
+  shouldPlaySound(notification) {
+    return defaultShouldPlaySound(
+      notification,
+      DEFAULT_SOUND_LEVELS,
+      DEFAULT_SOUND_CATEGORIES
+    );
+  }
+};
+function createToastPolicy(config) {
+  const categorySettings = {
+    ...DEFAULT_TOAST_CATEGORIES,
+    ...config.toastCategories
+  };
+  const soundLevels = config.soundLevels ?? DEFAULT_SOUND_LEVELS;
+  const soundCategories = config.soundCategories ?? DEFAULT_SOUND_CATEGORIES;
+  return {
+    shouldToast(notification) {
+      if (config.shouldToast !== void 0) {
+        return config.shouldToast(notification);
+      }
+      return defaultShouldToast(notification, categorySettings);
+    },
+    shouldPlaySound(notification) {
+      if (config.shouldPlaySound !== void 0) {
+        return config.shouldPlaySound(notification);
+      }
+      return defaultShouldPlaySound(notification, soundLevels, soundCategories);
+    }
+  };
+}
+
+// src/helpers/modalHelpers.ts
+function getModalAriaAttributes(notification, ids) {
+  const ariaRole = notification.modal?.accessibility?.aria_role ?? "alertdialog";
+  return {
+    role: ariaRole,
+    "aria-modal": "true",
+    "aria-labelledby": ids.titleId,
+    "aria-describedby": ids.bodyId
+  };
+}
+function getEscapeKeyHandler(notification, callbacks) {
+  const behavior = notification.modal?.accessibility?.escape_key_behavior ?? "close";
+  if (behavior === "disabled") {
+    return null;
+  }
+  return (event) => {
+    if (event.key !== "Escape") return;
+    switch (behavior) {
+      case "close":
+        event.preventDefault();
+        callbacks.onClose();
+        break;
+      case "snooze": {
+        event.preventDefault();
+        const minSnooze = notification.modal?.snooze_options_minutes[0] ?? 15;
+        callbacks.onSnooze(minSnooze);
+        break;
+      }
+    }
+  };
+}
+function createFocusTrap(modalElement) {
+  const focusableSelector = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+  let previousFocus = null;
+  let trapHandler = null;
+  function trapFocus(event) {
+    if (event.key !== "Tab") return;
+    const focusable = modalElement.querySelectorAll(focusableSelector);
+    if (focusable.length === 0) return;
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    if (first === void 0 || last === void 0) return;
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+  return {
+    activate() {
+      previousFocus = document.activeElement;
+      const focusable = modalElement.querySelectorAll(focusableSelector);
+      if (focusable.length > 0 && focusable[0] !== void 0) {
+        focusable[0].focus();
+      }
+      trapHandler = trapFocus;
+      modalElement.addEventListener("keydown", trapHandler);
+    },
+    deactivate() {
+      if (trapHandler !== null) {
+        modalElement.removeEventListener("keydown", trapHandler);
+        trapHandler = null;
+      }
+      if (previousFocus !== null) {
+        previousFocus.focus();
+        previousFocus = null;
+      }
+    }
+  };
+}
+function getActionButtonAttributes(action, index) {
+  const attrs = {
+    type: "button",
+    "data-action-type": action.type,
+    "data-action-index": String(index),
+    "aria-label": action.label
+  };
+  if (action.primary === true) {
+    attrs["data-primary"] = true;
+  }
+  return attrs;
+}
+function isCriticalModal2(notification) {
+  return notification.modal?.enabled === true && notification.modal.requires_ack === true;
+}
+function shouldCloseOnBackdropClick(notification) {
+  return !isCriticalModal2(notification);
+}
+function getMinSnoozeDuration(notification) {
+  const options = notification.modal?.snooze_options_minutes;
+  if (options === void 0 || options.length === 0) {
+    return null;
+  }
+  return options[0] ?? null;
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+
+export { ENDPOINTS, NOTIFICATION_CATEGORIES, NOTIFICATION_LEVELS, NOTIFY_KIT_CLIENT_KEY, NotifyKitApiError, NotifyKitClient, VERSION, createFocusTrap, createNotifyKitClient, createToastPolicy, defaultToastPolicy, getActionButtonAttributes, getEscapeKeyHandler, getMinSnoozeDuration, getModalAriaAttributes, isChannelPreferences, isCriticalModal2 as isCriticalModal, isMeResponse, isModalEnabled, isModalSpec, isNotifyKitNotification, isPaginationMeta, isUnreadCountResponse, isValidCategory, isValidLevel, provideNotifyKitClient, shouldCloseOnBackdropClick, useNotifyKitClient, useNotifyKitFallback, useNotifyKitRealtime };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map