@antelopejs/dms 0.0.1

package/frontend-vue/layers/dms-core/app/composables/realtime/useSseStream.ts

@@ -0,0 +1,173 @@
+import { HTTP_UNAUTHORIZED } from "../../utils/http-status";
+
+/** Receives decoded data and the frame's id (null if absent, empty if reset). */
+export type SseEventHandler = (
+  eventName: string,
+  data: unknown,
+  id: string | null,
+) => void;
+
+/** Transport termination, independent of application-level terminal events. */
+export type SseCloseReason = "eof" | "error" | "aborted";
+
+/** Options for a single connection; retry and session policy belong to the caller. */
+export interface SseStreamOptions {
+  url: string;
+  headers?: () => Record<string, string>;
+  onEvent: SseEventHandler;
+  onOpen?: () => void;
+  onError?: (error: unknown) => void;
+  /** Called once after cleanup; errors call onError first. Retry on only one callback. */
+  onClose?: (reason: SseCloseReason) => void;
+}
+
+/** Owns a single request, never an automatic reconnection. */
+export interface SseStreamHandle {
+  /** Stops delivery immediately. Repeated calls are harmless. */
+  close(): void;
+}
+
+interface StreamError extends Error {
+  status?: number;
+}
+
+interface ParsedFrame {
+  eventName: string;
+  data: string;
+  id: string | null;
+}
+
+const DEFAULT_EVENT_NAME = "message";
+const SSE_FRAME_SEPARATOR = /\r?\n\r?\n/;
+const SSE_LINE_SEPARATOR = /\r?\n/;
+const FIELD_SEPARATOR = ":";
+const FIELD_SEPARATOR_LENGTH = FIELD_SEPARATOR.length;
+const OPTIONAL_SPACE_LENGTH = " ".length;
+
+function parseFrame(frame: string): ParsedFrame | null {
+  const fields = new Map<string, string>();
+  const dataLines: string[] = [];
+  for (const line of frame.split(SSE_LINE_SEPARATOR)) {
+    const boundary = line.indexOf(FIELD_SEPARATOR);
+    const name = boundary === -1 ? line : line.slice(0, boundary);
+    const raw =
+      boundary === -1 ? "" : line.slice(boundary + FIELD_SEPARATOR_LENGTH);
+    const value = raw.startsWith(" ") ? raw.slice(OPTIONAL_SPACE_LENGTH) : raw;
+    if (name === "id" && value.includes("\0")) continue;
+    fields.set(name, value);
+    if (name === "data") dataLines.push(value);
+  }
+  if (dataLines.length === 0) return null;
+  return {
+    eventName: fields.get("event") || DEFAULT_EVENT_NAME,
+    data: dataLines.join("\n"),
+    id: fields.get("id") ?? null,
+  };
+}
+
+function decodeData(data: string): unknown {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}
+
+function dispatchFrames(
+  buffer: string,
+  options: SseStreamOptions,
+  signal: AbortSignal,
+): string {
+  const frames = buffer.split(SSE_FRAME_SEPARATOR);
+  const rest = frames.pop() ?? "";
+  for (const frame of frames) {
+    if (signal.aborted) break;
+    const parsed = parseFrame(frame);
+    if (parsed)
+      options.onEvent(parsed.eventName, decodeData(parsed.data), parsed.id);
+  }
+  return rest;
+}
+
+async function readStream(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  options: SseStreamOptions,
+  signal: AbortSignal,
+): Promise<void> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const cancel = () => {
+    void reader.cancel().catch(() => {});
+  };
+  signal.addEventListener("abort", cancel, { once: true });
+  try {
+    while (!signal.aborted) {
+      const chunk = await reader.read();
+      if (chunk.done) return;
+      buffer += decoder.decode(chunk.value, { stream: true });
+      buffer = dispatchFrames(buffer, options, signal);
+    }
+  } finally {
+    signal.removeEventListener("abort", cancel);
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
+async function connect(
+  options: SseStreamOptions,
+  signal: AbortSignal,
+): Promise<void> {
+  const response = await fetch(options.url, {
+    method: "GET",
+    headers: options.headers?.() ?? {},
+    signal,
+    credentials: "include",
+  });
+  if (!response.ok || !response.body) {
+    await response.body?.cancel();
+    const error: StreamError = new Error(
+      `SSE request failed: ${response.status}`,
+    );
+    error.status = response.status;
+    throw error;
+  }
+  if (signal.aborted) {
+    await response.body.cancel();
+    return;
+  }
+  try {
+    options.onOpen?.();
+  } catch (error) {
+    await response.body.cancel();
+    throw error;
+  }
+  await readStream(response.body.getReader(), options, signal);
+}
+
+/** Whether a stream error carries HTTP 401 and may need session recovery. */
+export function isUnauthorizedStreamError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as StreamError).status === HTTP_UNAUTHORIZED
+  );
+}
+
+/** Opens one SSE request. EOF is not business completion; no retry is implicit. */
+export function openSseStream(options: SseStreamOptions): SseStreamHandle {
+  const controller = new AbortController();
+  void (async () => {
+    let reason: SseCloseReason = "eof";
+    try {
+      await connect(options, controller.signal);
+      if (controller.signal.aborted) reason = "aborted";
+    } catch (error) {
+      reason = controller.signal.aborted ? "aborted" : "error";
+      if (reason === "error") options.onError?.(error);
+    } finally {
+      options.onClose?.(reason);
+    }
+  })();
+  return { close: () => controller.abort() };
+}

package/frontend-vue/layers/dms-core/app/composables/realtime/useUserRealtime.ts

@@ -0,0 +1,286 @@
+import { isUnauthorizedStreamError, openSseStream } from "./useSseStream";
+
+const REALTIME_USER_PATH = "/api/realtime/user";
+const REALTIME_SUBSCRIBE_PATH_PREFIX = "/api/realtime/subscribe/";
+const REALTIME_UNSUBSCRIBE_PATH = "/api/realtime/unsubscribe";
+const SESSION_HEADER = "x-realtime-session";
+const SESSION_STATE_KEY = "dms.realtime.sessionId";
+const MENU_TOPICS_STATE_KEY = "dms.realtime.menuTopics";
+const HELLO_EVENT = "hello";
+const SNAPSHOT_EVENT = "snapshot";
+const RECONNECT_INITIAL_DELAY_MS = 500;
+const RECONNECT_MAX_DELAY_MS = 30_000;
+const RECONNECT_MULTIPLIER = 2;
+
+export interface RealtimeEvent {
+  topic: string;
+  type: string;
+  payload?: Record<string, unknown>;
+  actorId?: string;
+  ts: number;
+}
+
+export interface RealtimeSnapshotEvent {
+  topic: string;
+  entries: Array<{
+    topic: string;
+    rowId: string;
+    actor: { id: string; displayName?: string; avatarUrl?: string };
+    sessionId: string;
+    instanceId: string;
+    since: number;
+  }>;
+}
+
+export type RealtimeTopicHandler = (
+  event: RealtimeEvent | RealtimeSnapshotEvent,
+) => void;
+
+export interface UserRealtimeApi {
+  subscribe(topic: string, handler: RealtimeTopicHandler): () => void;
+  setPage(pageId: string | null): Promise<void>;
+  sessionId: Ref<string | undefined>;
+  pageId: Ref<string | undefined>;
+  /**
+   * Menu-invalidation topics the server subscribed this session to. Their names
+   * embed the tenant, which the client cannot derive on its own, so they are
+   * announced in the greeting.
+   */
+  menuTopics: Ref<string[]>;
+}
+
+interface UserRealtimeState {
+  sessionId: Ref<string | undefined>;
+  pageId: Ref<string | undefined>;
+  menuTopics: Ref<string[]>;
+  appliedPageId: Ref<string | null>;
+  handlers: Map<string, Set<RealtimeTopicHandler>>;
+  snapshots: Map<string, RealtimeSnapshotEvent>;
+  cancelConnect?: () => void;
+}
+
+let singletonApi: UserRealtimeApi | undefined;
+
+const dispatchToHandlers = (
+  state: UserRealtimeState,
+  topic: string,
+  event: RealtimeEvent | RealtimeSnapshotEvent,
+): void => {
+  const handlers = state.handlers.get(topic);
+  if (!handlers) return;
+  for (const handler of handlers) handler(event);
+};
+
+const isSnapshotEvent = (
+  eventName: string,
+  data: unknown,
+): data is RealtimeSnapshotEvent =>
+  eventName === SNAPSHOT_EVENT &&
+  !!data &&
+  typeof data === "object" &&
+  "topic" in (data as Record<string, unknown>);
+
+const isRealtimeEvent = (data: unknown): data is RealtimeEvent =>
+  !!data &&
+  typeof data === "object" &&
+  typeof (data as Record<string, unknown>).topic === "string" &&
+  typeof (data as Record<string, unknown>).type === "string";
+
+const readMenuTopics = (data: object): string[] => {
+  const { menuTopics } = data as { menuTopics?: unknown };
+  if (!Array.isArray(menuTopics)) return [];
+  return menuTopics.filter(
+    (topic): topic is string => typeof topic === "string",
+  );
+};
+
+const handleHello = (state: UserRealtimeState, data: unknown): void => {
+  if (!data || typeof data !== "object" || !("sessionId" in data)) return;
+  state.sessionId.value = String((data as { sessionId: unknown }).sessionId);
+  state.menuTopics.value = readMenuTopics(data);
+};
+
+const handleEvent =
+  (state: UserRealtimeState) =>
+  (eventName: string, data: unknown): void => {
+    if (eventName === HELLO_EVENT) {
+      handleHello(state, data);
+      return;
+    }
+    if (isSnapshotEvent(eventName, data)) {
+      state.snapshots.set(data.topic, data);
+      dispatchToHandlers(state, data.topic, data);
+      return;
+    }
+    if (isRealtimeEvent(data)) {
+      dispatchToHandlers(state, data.topic, data);
+    }
+  };
+
+const connectWithBackoff = (
+  url: string,
+  state: UserRealtimeState,
+  onConnected: () => void,
+  refreshSession: () => Promise<boolean>,
+  redirectToAuth: () => Promise<void>,
+): (() => void) => {
+  let cancelled = false;
+  let delay = RECONNECT_INITIAL_DELAY_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let activeHandle: { close(): void } | undefined;
+  const dispatch = handleEvent(state);
+  const open = () => {
+    if (cancelled) return;
+    activeHandle = openSseStream({
+      url,
+      onEvent: (eventName, data) => {
+        if (cancelled) return;
+        delay = RECONNECT_INITIAL_DELAY_MS;
+        dispatch(eventName, data);
+        if (eventName === HELLO_EVENT) onConnected();
+      },
+      onError: (error) => {
+        if (cancelled) return;
+        state.appliedPageId.value = null;
+        const scheduleReconnect = () => {
+          if (cancelled) return;
+          timer = setTimeout(open, delay);
+          delay = Math.min(
+            delay * RECONNECT_MULTIPLIER,
+            RECONNECT_MAX_DELAY_MS,
+          );
+        };
+        if (isUnauthorizedStreamError(error)) {
+          void refreshSession().then((refreshed) => {
+            if (refreshed) {
+              scheduleReconnect();
+            } else {
+              void redirectToAuth();
+            }
+          }, scheduleReconnect);
+          return;
+        }
+        scheduleReconnect();
+      },
+    });
+  };
+  open();
+  return () => {
+    cancelled = true;
+    if (timer) clearTimeout(timer);
+    activeHandle?.close();
+    activeHandle = undefined;
+  };
+};
+
+const callPageEndpoint = async (
+  state: UserRealtimeState,
+  pageId: string | null,
+  baseUrl: string,
+): Promise<void> => {
+  const sessionId = state.sessionId.value;
+  if (!sessionId) return;
+  const headers: Record<string, string> = { [SESSION_HEADER]: sessionId };
+  const url = pageId
+    ? `${baseUrl}${REALTIME_SUBSCRIBE_PATH_PREFIX}${pageId}`
+    : `${baseUrl}${REALTIME_UNSUBSCRIBE_PATH}`;
+  await fetch(url, {
+    method: "POST",
+    headers,
+    credentials: "include",
+  });
+};
+
+const reconcilePage = async (
+  state: UserRealtimeState,
+  baseUrl: string,
+): Promise<void> => {
+  const desired = state.pageId.value ?? null;
+  if (state.appliedPageId.value === desired) return;
+  if (!state.sessionId.value) return;
+  await callPageEndpoint(state, desired, baseUrl);
+  if ((state.pageId.value ?? null) === desired) {
+    state.appliedPageId.value = desired;
+  }
+};
+
+const buildApi = (): UserRealtimeApi => {
+  const sessionId = useDmsState<string | undefined>(
+    SESSION_STATE_KEY,
+    () => undefined,
+  );
+  const menuTopics = useDmsState<string[]>(MENU_TOPICS_STATE_KEY, () => []);
+  const appliedPageId = ref<string | null>(null);
+  const pageId = ref<string | undefined>(undefined);
+  const state: UserRealtimeState = {
+    sessionId,
+    pageId,
+    menuTopics,
+    appliedPageId,
+    handlers: new Map(),
+    snapshots: new Map(),
+  };
+
+  const config = useDmsRuntimeConfig();
+  const { loggedIn } = useUserSession();
+  const { refreshSession, redirectToAuth } = useSessionRecovery();
+  const baseUrl = config.public.dms.baseURL as string;
+
+  if (!import.meta.env.SSR) {
+    watch(
+      () => loggedIn.value,
+      (isLoggedIn) => {
+        state.cancelConnect?.();
+        state.cancelConnect = undefined;
+        state.sessionId.value = undefined;
+        state.menuTopics.value = [];
+        state.appliedPageId.value = null;
+        state.snapshots.clear();
+        if (!isLoggedIn) return;
+        state.cancelConnect = connectWithBackoff(
+          `${baseUrl}${REALTIME_USER_PATH}`,
+          state,
+          () => {
+            void reconcilePage(state, baseUrl);
+          },
+          refreshSession,
+          redirectToAuth,
+        );
+      },
+      { immediate: true },
+    );
+  }
+
+  const subscribe = (topic: string, handler: RealtimeTopicHandler) => {
+    let handlers = state.handlers.get(topic);
+    if (!handlers) {
+      handlers = new Set();
+      state.handlers.set(topic, handlers);
+    }
+    handlers.add(handler);
+    if (state.snapshots.has(topic)) {
+      setTimeout(() => {
+        if (!handlers?.has(handler)) return;
+        const latest = state.snapshots.get(topic);
+        if (latest) handler(latest);
+      }, 0);
+    }
+    return () => {
+      handlers?.delete(handler);
+      if (handlers && handlers.size === 0) state.handlers.delete(topic);
+    };
+  };
+
+  const setPage = async (next: string | null): Promise<void> => {
+    state.pageId.value = next ?? undefined;
+    if (import.meta.env.SSR) return;
+    await reconcilePage(state, baseUrl);
+  };
+
+  return { subscribe, setPage, sessionId, pageId, menuTopics };
+};
+
+export function useUserRealtime(): UserRealtimeApi {
+  if (!singletonApi) singletonApi = buildApi();
+  return singletonApi;
+}

package/frontend-vue/layers/dms-core/app/composables/translation/useTranslation.ts

@@ -0,0 +1,104 @@
+const TRANSLATION_KEY_PREFIX = "$";
+
+export type I18nTranslate = (
+  key: string,
+  params: Record<string, unknown>,
+) => string;
+
+/**
+ * i18n access for DMS app plugins, where `useI18n()` is unavailable: returns the
+ * global composer plus an {@link I18nTranslate} bound to it. Inside
+ * components prefer `useI18n` / {@link useTranslation}.
+ */
+export function getPluginI18n() {
+  const { $i18n: i18n } = useDmsApp();
+  const translate: I18nTranslate = (key, params) => i18n.t(key, params);
+  return { i18n, translate };
+}
+
+/**
+ * Whether a DMS display string is marked as an i18n key, and the key it holds.
+ */
+export function readTranslationKey(value: string) {
+  const isKey = value.startsWith(TRANSLATION_KEY_PREFIX);
+  return { isKey, key: isKey ? value.slice(1) : value };
+}
+
+/**
+ * Resolves a DMS display string: values prefixed with `$` are i18n keys
+ * translated through `translate`, anything else is returned verbatim.
+ * Use this from contexts without a component instance (e.g. plugins, with
+ * `dmsApp.$i18n.t`); inside components prefer {@link useTranslation}.
+ */
+export function resolveI18nKey(
+  translate: I18nTranslate,
+  key: string,
+  params?: Record<string, unknown> | null,
+): string {
+  const marked = readTranslationKey(key);
+  if (marked.isKey) {
+    return translate(marked.key, params ?? {});
+  }
+
+  return key;
+}
+
+/**
+ * Resolves a message sent back by the API. Backend messages are i18n keys,
+ * written either bare (`error.unauthorized`) or with the DMS `$` prefix
+ * (`$page.settings.invites.error.not_found`). `translate` echoes the key back
+ * when no translation exists in the active locale or its fallbacks: a message
+ * marked with `$` then falls back to the bare key, and an unmarked one — which
+ * may well be plain prose — is shown as it came in.
+ */
+export function resolveApiMessage(
+  translate: I18nTranslate,
+  message: unknown,
+): string {
+  const text = typeof message === "string" ? message : String(message);
+  const marked = readTranslationKey(text);
+  const translated = translate(marked.key, {});
+
+  if (translated !== marked.key) return translated;
+  return marked.isKey ? marked.key : text;
+}
+
+/**
+ * {@link resolveI18nKey} for optional display strings: returns `undefined` when
+ * the value is empty or when a `$` key has no translation. vue-i18n falls back
+ * to the bare key path, which callers that index or render the result must not
+ * mistake for real text.
+ */
+export function resolveOptionalI18nKey(
+  translate: I18nTranslate,
+  key: string | undefined,
+  params?: Record<string, unknown> | null,
+): string | undefined {
+  if (!key) {
+    return undefined;
+  }
+
+  const resolved = resolveI18nKey(translate, key, params);
+  const isUntranslatedKey =
+    key.startsWith(TRANSLATION_KEY_PREFIX) &&
+    resolved === key.slice(TRANSLATION_KEY_PREFIX.length);
+
+  return isUntranslatedKey ? undefined : resolved;
+}
+
+export const useTranslation = () => {
+  const { t } = useI18n();
+
+  function processI18n(key: string, params?: Record<string, unknown> | null) {
+    return resolveI18nKey(t, key, params);
+  }
+
+  function processApiMessage(message: unknown) {
+    return resolveApiMessage(t, message);
+  }
+
+  return {
+    processI18n,
+    processApiMessage,
+  };
+};

package/frontend-vue/layers/dms-core/app/composables/translation/useUniqueLocales.ts

@@ -0,0 +1,18 @@
+interface LocaleDefinition {
+  code: string;
+}
+
+export const useUniqueLocales = () => {
+  const { locales } = useI18n();
+
+  const uniqueLocales = computed(() => {
+    const seen = new Set<string>();
+    return locales.value.filter((lang: LocaleDefinition) => {
+      if (seen.has(lang.code)) return false;
+      seen.add(lang.code);
+      return true;
+    });
+  });
+
+  return { uniqueLocales };
+};

package/frontend-vue/layers/dms-core/app/composables/useApiError.ts

@@ -0,0 +1,57 @@
+interface Options {
+  context?: string;
+  title?: string;
+  description?: string;
+}
+
+interface ApiError {
+  statusCode?: number;
+  message?: string;
+  data?: unknown;
+}
+
+const DEFAULT_TITLE_KEY = "error.500.title";
+const FALLBACK_ERROR_KEY = "error.500.description";
+
+function isApiError(error: unknown): error is ApiError {
+  return typeof error === "object" && error !== null;
+}
+
+function resolveDescription(error: ApiError): string {
+  const errorData = error.data as Record<string, unknown> | string | undefined;
+  if (
+    errorData &&
+    typeof errorData === "object" &&
+    typeof errorData.message === "string"
+  ) {
+    return errorData.message;
+  }
+  if (typeof errorData === "string") {
+    return errorData;
+  }
+  return FALLBACK_ERROR_KEY;
+}
+
+/**
+ * Extract the backend's error body from a fetch error — an i18n message key
+ * per the API error contract — falling back to the generic 500 key.
+ */
+export function resolveApiErrorMessage(error: unknown): string {
+  return isApiError(error) ? resolveDescription(error) : FALLBACK_ERROR_KEY;
+}
+
+export function useApiError(error: unknown, options?: Options) {
+  const toast = useToast();
+  const dmsApp = useDmsApp();
+  const { t } = dmsApp.$i18n;
+  const translate = (message: string) => resolveApiMessage(t, message);
+
+  const title = options?.title || DEFAULT_TITLE_KEY;
+  const description = options?.description || resolveApiErrorMessage(error);
+
+  toast.add({
+    title: translate(title),
+    description: translate(description),
+    color: "error",
+  });
+}

package/frontend-vue/layers/dms-core/app/composables/useEventedAction.ts

@@ -0,0 +1,53 @@
+interface EventedActionOptions {
+  componentId?: string;
+  events?: {
+    start?: string;
+    success?: string;
+    error?: string;
+  };
+}
+
+interface ExecuteOptions<TResult> {
+  startPayload?: unknown;
+  successPayload?: (result: TResult) => unknown;
+  errorPayload?: (error: unknown) => unknown;
+}
+
+export function useEventedAction<TResult = unknown>(
+  options: EventedActionOptions = {},
+) {
+  const { sendComponentEvent } = useComponentEvent();
+  const isLoading = ref(false);
+
+  function dispatchEvent(eventName: string | undefined, payload: unknown) {
+    if (!eventName || !options.componentId) return;
+    sendComponentEvent(eventName, options.componentId, payload);
+  }
+
+  async function execute(
+    action: () => Promise<TResult>,
+    executeOptions: ExecuteOptions<TResult> = {},
+  ): Promise<TResult> {
+    isLoading.value = true;
+    dispatchEvent(options.events?.start, executeOptions.startPayload);
+
+    try {
+      const result = await action();
+      dispatchEvent(
+        options.events?.success,
+        executeOptions.successPayload?.(result),
+      );
+      return result;
+    } catch (error) {
+      dispatchEvent(
+        options.events?.error,
+        executeOptions.errorPayload?.(error),
+      );
+      throw error;
+    } finally {
+      isLoading.value = false;
+    }
+  }
+
+  return { execute, isLoading };
+}

package/frontend-vue/layers/dms-core/app/composables/useHomepage.ts

@@ -0,0 +1,6 @@
+const DEFAULT_HOMEPAGE = "/";
+
+export const useHomepage = (): string => {
+  const config = useDmsRuntimeConfig();
+  return config.public.dms.homepage || DEFAULT_HOMEPAGE;
+};