@antelopejs/dms-saas 0.0.1

package/frontend-vue/app/composables/useBillingStatus.ts

@@ -0,0 +1,39 @@
+const BILLING_STATUS_ENDPOINT = "/api/saas/billing/status";
+const BILLING_STATUS_STATE_KEY = "saas-billing-status";
+
+export interface PaymentMethodSummary {
+  brand: string;
+  last4: string;
+  expMonth: number;
+  expYear: number;
+}
+
+export interface UnpaidInvoiceRef {
+  number: string | null;
+  amount: number;
+  currency: string;
+  hostedInvoiceUrl: string | null;
+}
+
+export interface UnpaidInvoiceSummary extends UnpaidInvoiceRef {
+  failedAt: string | null;
+  nextRetryAt: string | null;
+  suspendAt: string | null;
+}
+
+export interface BillingStatusResponse {
+  hasStripeCustomer: boolean;
+  status: string | null;
+  isTenantOwner: boolean;
+  paymentMethod: PaymentMethodSummary | null;
+  unpaidInvoice: UnpaidInvoiceSummary | null;
+}
+
+/** Read by the past-due alert, the payment method card and the portal button;
+ * each call reaches Stripe, so the three of them share one request. */
+export function useBillingStatus(): SharedRequest<BillingStatusResponse> {
+  const { $authFetch } = useAuthFetch();
+  return useSharedRequest(BILLING_STATUS_STATE_KEY, () =>
+    $authFetch<BillingStatusResponse>(BILLING_STATUS_ENDPOINT),
+  );
+}

package/frontend-vue/app/composables/useCurrentWorkspace.ts

@@ -0,0 +1,43 @@
+export interface CurrentWorkspace {
+  _id: string;
+  name: string;
+  retentionDays: number;
+}
+
+const CURRENT_ENDPOINT = "/api/saas/workspaces/current";
+const STATE_KEY = "saas-current-workspace";
+
+interface CurrentWorkspaceHandle {
+  workspace: Ref<CurrentWorkspace | null>;
+  load: () => Promise<void>;
+  rename: (name: string) => Promise<void>;
+}
+
+/**
+ * Shared so the general-settings blocks read the workspace once and a rename
+ * done in one of them is immediately visible to the other and to the switcher.
+ */
+export function useCurrentWorkspace(): CurrentWorkspaceHandle {
+  const { $authFetch } = useAuthFetch();
+  const workspace = useDmsState<CurrentWorkspace | null>(STATE_KEY, () => null);
+  const { refresh: refreshMyWorkspaces } = useMyWorkspaces();
+
+  async function load(): Promise<void> {
+    workspace.value = await $authFetch<CurrentWorkspace>(CURRENT_ENDPOINT);
+  }
+
+  async function rename(name: string): Promise<void> {
+    const updated = await $authFetch<CurrentWorkspace>(CURRENT_ENDPOINT, {
+      method: "PUT",
+      body: { name },
+    });
+    workspace.value = workspace.value
+      ? { ...workspace.value, name: updated.name }
+      : null;
+    // The rename is committed at this point: a failing sidebar refresh must
+    // not make the caller report it as failed.
+    await refreshMyWorkspaces().catch(() => undefined);
+  }
+
+  return { workspace, load, rename };
+}

package/frontend-vue/app/composables/useDetailRefresh.ts

@@ -0,0 +1,17 @@
+export interface DetailRefresh {
+  trigger: () => void;
+  triggerRef: Ref<number>;
+}
+
+export function useDetailRefresh(scopeKey: string): DetailRefresh {
+  // useDmsState scopes the counter to the current app instance (SSR-safe) instead
+  // of a module-level Map, which on the server would leak across requests and
+  // could replay a trigger from one request in another for the same scopeKey.
+  const counter = useDmsState<number>(`detail-refresh:${scopeKey}`, () => 0);
+  return {
+    trigger: () => {
+      counter.value++;
+    },
+    triggerRef: counter,
+  };
+}

package/frontend-vue/app/composables/useExportHistory.ts

@@ -0,0 +1,143 @@
+import { ref } from "vue";
+
+const HISTORY_ENDPOINT = "/api/saas/data-export/history";
+const HISTORY_PAGE_SIZE = 10;
+const FIRST_PAGE = 1;
+const DOWNLOAD_ENDPOINT = "/api/saas/data-export/download";
+const FILENAME_HEADER_PATTERN = /filename="([^"]+)"/i;
+const FALLBACK_EXTENSION = "zip";
+
+export interface ExportJobFailure {
+  source: string;
+  error: string;
+}
+
+export interface ExportJobResult {
+  partial: boolean;
+  failures: ExportJobFailure[];
+}
+
+export interface ExportHistoryEntry {
+  jobId: string;
+  scope: string;
+  status: string;
+  progress: number;
+  error?: string;
+  filename?: string;
+  extension?: string;
+  result?: ExportJobResult;
+  /** Moment the stale export sweep drops the archive and its download link. */
+  expiresAt?: string;
+  createdAt: string;
+}
+
+function parseFilename(header: string | null): string | null {
+  return header?.match(FILENAME_HEADER_PATTERN)?.[1] ?? null;
+}
+
+export interface ExportHistoryPage {
+  items: ExportHistoryEntry[];
+  hasMore: boolean;
+  page: number;
+  pageSize: number;
+}
+
+export interface ExportDownloadNaming {
+  filename?: string;
+  extension?: string;
+}
+
+function fallbackFilename(jobId: string, naming?: ExportDownloadNaming): string {
+  const extension = naming?.extension ?? FALLBACK_EXTENSION;
+  return `${naming?.filename ?? `export-${jobId}`}.${extension}`;
+}
+
+/**
+ * The caller's past exports for the current workspace, and the download of a
+ * single one of them — the action both the history rows and the e-mailed link
+ * land on.
+ */
+export function useExportHistory() {
+  const { $authFetch } = useAuthFetch();
+
+  const entries = ref<ExportHistoryEntry[]>([]);
+  const isLoading = ref(false);
+  const hasFailed = ref(false);
+  const page = ref(FIRST_PAGE);
+  const hasMore = ref(false);
+
+  /**
+   * Defaults back to the first page: every caller that reloads does so because
+   * the list changed at its most recent end, which is where page one is.
+   *
+   * A page past the first that comes back empty falls back to the first rather
+   * than showing the "no export yet" state, which would be a lie — exports
+   * expiring under the reader is enough to empty the page they were on.
+   */
+  async function load(targetPage: number = FIRST_PAGE): Promise<void> {
+    isLoading.value = true;
+    try {
+      const result = await $authFetch<ExportHistoryPage>(HISTORY_ENDPOINT, {
+        query: { page: targetPage, pageSize: HISTORY_PAGE_SIZE },
+      });
+      if (!result.items.length && result.page > FIRST_PAGE) {
+        isLoading.value = false;
+        return load(FIRST_PAGE);
+      }
+      entries.value = result.items;
+      page.value = result.page;
+      hasMore.value = result.hasMore;
+      hasFailed.value = false;
+    } catch {
+      hasFailed.value = true;
+    } finally {
+      isLoading.value = false;
+    }
+  }
+
+  function goToPage(targetPage: number): Promise<void> {
+    if (targetPage < FIRST_PAGE || isLoading.value) return Promise.resolve();
+    return load(targetPage);
+  }
+
+  /**
+   * Takes a job id rather than a history row: a link delivered by e-mail may
+   * point at an export older than the window the history lists, and refusing
+   * to download it because it is not on screen would be a lie the server never
+   * told.
+   */
+  async function download(
+    jobId: string,
+    naming?: ExportDownloadNaming,
+  ): Promise<void> {
+    // Encoded because a delivered link hands its job id straight over: an id
+    // holding a separator would otherwise address a different route.
+    const response = await $authFetch.raw(
+      `${DOWNLOAD_ENDPOINT}/${encodeURIComponent(jobId)}`,
+      { responseType: "blob" },
+    );
+    const blob = response._data as Blob | null;
+    if (!blob) throw new Error("Empty export download");
+
+    const objectUrl = URL.createObjectURL(blob);
+    try {
+      const filename =
+        parseFilename(response.headers.get("content-disposition")) ??
+        fallbackFilename(jobId, naming);
+      downloadFile(objectUrl, filename);
+    } finally {
+      URL.revokeObjectURL(objectUrl);
+    }
+  }
+
+  return {
+    entries,
+    isLoading,
+    hasFailed,
+    page,
+    hasMore,
+    load,
+    goToPage,
+    download,
+  };
+}

package/frontend-vue/app/composables/useInvoiceLines.ts

@@ -0,0 +1,22 @@
+export interface InvoiceLine {
+  description: string;
+  quantity: number | null;
+  amount: number;
+  currency?: string | null;
+  periodStart: string | Date | null;
+  periodEnd: string | Date | null;
+}
+
+/** The mirror stores lines as an array, but the table view hands the raw column
+ * value over, which may still be its JSON form. */
+export function parseInvoiceLines(raw: unknown): InvoiceLine[] {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw as InvoiceLine[];
+  if (typeof raw !== "string") return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}

package/frontend-vue/app/composables/useMoneyFormat.ts

@@ -0,0 +1,49 @@
+export const MINOR_UNITS_PER_UNIT = 100;
+
+const FALLBACK_CURRENCY = "EUR";
+
+export interface MajorUnitsFormatOptions {
+  /** Render a whole amount without decimals, e.g. `€20` instead of `€20.00`. */
+  hideWholeAmountDecimals?: boolean;
+}
+
+export function formatMajorUnits(
+  amount: number | null | undefined,
+  currency: string | null | undefined,
+  locale: string,
+  options: MajorUnitsFormatOptions = {},
+): string {
+  if (typeof amount !== "number") return "—";
+  const hasDecimalsToHide =
+    options.hideWholeAmountDecimals === true && Number.isInteger(amount);
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: (currency || FALLBACK_CURRENCY).toUpperCase(),
+    minimumFractionDigits: hasDecimalsToHide ? 0 : undefined,
+  }).format(amount);
+}
+
+/** Amounts mirrored from a payment provider are stored in minor units. */
+export function formatMinorUnits(
+  amount: number | null | undefined,
+  currency: string | null | undefined,
+  locale: string,
+): string {
+  if (typeof amount !== "number") return "—";
+  return formatMajorUnits(amount / MINOR_UNITS_PER_UNIT, currency, locale);
+}
+
+/** Locale-bound view of the formatters above, for use inside components. */
+export function useMoneyFormat() {
+  const { locale } = useI18n();
+  return {
+    formatMinorUnits: (
+      amount: number | null | undefined,
+      currency: string | null | undefined,
+    ) => formatMinorUnits(amount, currency, locale.value),
+    formatMajorUnits: (
+      amount: number | null | undefined,
+      currency: string | null | undefined,
+    ) => formatMajorUnits(amount, currency, locale.value),
+  };
+}

package/frontend-vue/app/composables/useMyWorkspaces.ts

@@ -0,0 +1,47 @@
+export interface MyWorkspace {
+  _id: string;
+  name: string;
+  planName: string | null;
+  isCurrent: boolean;
+}
+
+const WORKSPACES_ENDPOINT = "/api/saas/workspaces/mine";
+const STATE_KEY = "saas-my-workspaces";
+
+interface MyWorkspacesHandle {
+  workspaces: Ref<MyWorkspace[]>;
+  isLoaded: Ref<boolean>;
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Shared between the sidebar switcher and the screens that change what it
+ * displays (rename today), so a change never waits for a page reload.
+ */
+export function useMyWorkspaces(): MyWorkspacesHandle {
+  const { $authFetch } = useAuthFetch();
+  const { loggedIn } = useUserSession();
+  const workspaces = useDmsState<MyWorkspace[]>(STATE_KEY, () => []);
+  const isLoaded = useDmsState<boolean>(`${STATE_KEY}-loaded`, () => false);
+
+  async function refresh(): Promise<void> {
+    if (!loggedIn.value) {
+      workspaces.value = [];
+      isLoaded.value = true;
+      return;
+    }
+
+    try {
+      workspaces.value = await $authFetch<MyWorkspace[]>(WORKSPACES_ENDPOINT);
+      isLoaded.value = true;
+    } catch (error) {
+      // The sidebar is no place for an error card: render nothing instead. Only
+      // the initial load may empty the list — a failed refresh keeps the entries
+      // already on screen rather than making the switcher disappear.
+      if (!isLoaded.value) workspaces.value = [];
+      throw error;
+    }
+  }
+
+  return { workspaces, isLoaded, refresh };
+}

package/frontend-vue/app/composables/usePlanFeatureFormat.ts

@@ -0,0 +1,60 @@
+const UNLIMITED_NUMERIC_VALUE = -1;
+const EMPTY_LABEL = "—";
+const INCLUDED_LABEL = "✓";
+const EXCLUDED_LABEL = "–";
+
+type FeatureValueFormatter = (
+  value: unknown,
+  unit: string | null,
+  unlimitedLabel: string,
+) => string;
+
+function formatBoolean(value: unknown): string {
+  return value ? INCLUDED_LABEL : EXCLUDED_LABEL;
+}
+
+function formatNumeric(
+  value: unknown,
+  unit: string | null,
+  unlimitedLabel: string,
+): string {
+  const numeric = Number(value);
+  if (Number.isNaN(numeric)) return EMPTY_LABEL;
+  if (numeric === UNLIMITED_NUMERIC_VALUE) return unlimitedLabel;
+  return unit ? `${numeric} ${unit}` : String(numeric);
+}
+
+function formatText(value: unknown, unit: string | null): string {
+  const text = String(value).trim();
+  if (!text) return EMPTY_LABEL;
+  return unit ? `${text} ${unit}` : text;
+}
+
+const FORMATTERS: Record<string, FeatureValueFormatter> = {
+  boolean: (value) => formatBoolean(value),
+  number: (value, unit, unlimitedLabel) =>
+    formatNumeric(value, unit, unlimitedLabel),
+  string: (value, unit) => formatText(value, unit),
+};
+
+/**
+ * Renders a plan's feature value the way the comparison table shows it, with
+ * `-1` reading as unlimited — the same convention `maxMembers` already uses.
+ */
+export function usePlanFeatureFormat() {
+  const { t } = useI18n();
+
+  function formatFeatureValue(
+    feature: TenantPlanFeature,
+    value: unknown,
+  ): string {
+    if (value === undefined || value === null || value === "") {
+      return EMPTY_LABEL;
+    }
+    const formatter = FORMATTERS[feature.valueType];
+    if (!formatter) return String(value);
+    return formatter(value, feature.unit, t("saas.workspace.plan.unlimited"));
+  }
+
+  return { formatFeatureValue };
+}

package/frontend-vue/app/composables/usePlanIntervalLabel.ts

@@ -0,0 +1,30 @@
+export type PlanInterval = "month" | "year";
+export type PlanIntervalTranslator = (key: string) => string;
+export type PlanIntervalLabeler = (interval: PlanInterval) => string;
+
+/**
+ * Translates a billing interval.
+ *
+ * @param interval Stored billing interval
+ * @param keyPrefix Translation namespace containing month and year
+ * @param translate Translation function
+ * @returns Translated interval
+ */
+export function formatPlanIntervalLabel(
+  interval: PlanInterval,
+  keyPrefix: string,
+  translate: PlanIntervalTranslator,
+): string {
+  return translate(`${keyPrefix}.${interval}`);
+}
+
+/**
+ * Provides an interval formatter bound to the current locale.
+ *
+ * @param keyPrefix Translation namespace containing month and year
+ * @returns Formatter for a stored billing interval
+ */
+export function usePlanIntervalLabel(keyPrefix: string): PlanIntervalLabeler {
+  const { t } = useI18n();
+  return (interval) => formatPlanIntervalLabel(interval, keyPrefix, t);
+}