@antelopejs/dms-saas 0.2.0 → 0.3.0

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

@@ -0,0 +1,141 @@
+const BILLING_INFO_ENDPOINT = "/api/saas/tenant/billing-info";
+const BUSINESS_CUSTOMER_TYPE = "business";
+const COUNTRY_CODE_PATTERN = /^[A-Z]{2}$/;
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export type CustomerType = "individual" | "business";
+export type VatVerificationStatus = "pending" | "verified" | "unverified";
+
+export type BillingIdentityField =
+  | "customerType"
+  | "companyName"
+  | "country"
+  | "line1"
+  | "postalCode"
+  | "city"
+  | "billingEmail";
+
+/** The editable billing identity, as the form holds it. */
+export interface BillingIdentityDraft {
+  customerType: CustomerType | null;
+  companyName: string;
+  vatNumber: string;
+  billingEmail: string;
+  country: string;
+  line1: string;
+  postalCode: string;
+  city: string;
+}
+
+interface BillingAddress {
+  line1: string | null;
+  line2: string | null;
+  postalCode: string | null;
+  city: string | null;
+  state: string | null;
+  country: string | null;
+}
+
+export interface BillingInfoResponse {
+  customerType: CustomerType | null;
+  companyName: string | null;
+  vatNumber: string | null;
+  vatVerificationStatus: VatVerificationStatus | null;
+  billingEmail: string | null;
+  address: BillingAddress | null;
+  missingFields: BillingIdentityField[];
+}
+
+type FieldCheck = (draft: BillingIdentityDraft) => boolean;
+
+function isFilled(value: string): boolean {
+  return value.trim().length > 0;
+}
+
+// Mirrors the server-side rules (src/workspaces/billing-identity.ts): the
+// form flags a field before the request, the server refuses it regardless.
+const FIELD_CHECKS: Record<BillingIdentityField, FieldCheck> = {
+  customerType: (draft) => draft.customerType !== null,
+  companyName: (draft) =>
+    draft.customerType !== BUSINESS_CUSTOMER_TYPE ||
+    isFilled(draft.companyName),
+  country: (draft) => COUNTRY_CODE_PATTERN.test(draft.country.trim()),
+  line1: (draft) => isFilled(draft.line1),
+  postalCode: (draft) => isFilled(draft.postalCode),
+  city: (draft) => isFilled(draft.city),
+  billingEmail: (draft) => EMAIL_PATTERN.test(draft.billingEmail.trim()),
+};
+
+/**
+ * Required fields still missing or malformed, in form order; empty when the
+ * identity can be saved. The VAT number is optional, even for a business.
+ */
+export function findMissingBillingFields(
+  draft: BillingIdentityDraft,
+): BillingIdentityField[] {
+  return (Object.keys(FIELD_CHECKS) as BillingIdentityField[]).filter(
+    (field) => !FIELD_CHECKS[field](draft),
+  );
+}
+
+export function emptyBillingIdentityDraft(): BillingIdentityDraft {
+  return {
+    customerType: null,
+    companyName: "",
+    vatNumber: "",
+    billingEmail: "",
+    country: "",
+    line1: "",
+    postalCode: "",
+    city: "",
+  };
+}
+
+export function toBillingIdentityDraft(
+  info: BillingInfoResponse,
+): BillingIdentityDraft {
+  return {
+    customerType: info.customerType,
+    companyName: info.companyName ?? "",
+    vatNumber: info.vatNumber ?? "",
+    billingEmail: info.billingEmail ?? "",
+    country: info.address?.country ?? "",
+    line1: info.address?.line1 ?? "",
+    postalCode: info.address?.postalCode ?? "",
+    city: info.address?.city ?? "",
+  };
+}
+
+function toRequestBody(draft: BillingIdentityDraft) {
+  const isBusiness = draft.customerType === BUSINESS_CUSTOMER_TYPE;
+  return {
+    customerType: draft.customerType,
+    companyName: isBusiness ? draft.companyName : null,
+    vatNumber: isBusiness ? draft.vatNumber : null,
+    billingEmail: draft.billingEmail,
+    address: {
+      country: draft.country,
+      line1: draft.line1,
+      postalCode: draft.postalCode,
+      city: draft.city,
+    },
+  };
+}
+
+/** Reads and saves the workspace billing identity. */
+export function useBillingIdentity() {
+  const { $authFetch } = useAuthFetch();
+
+  function load(): Promise<BillingInfoResponse> {
+    return $authFetch<BillingInfoResponse>(BILLING_INFO_ENDPOINT);
+  }
+
+  function save(draft: BillingIdentityDraft): Promise<BillingInfoResponse> {
+    return $authFetch<BillingInfoResponse>(BILLING_INFO_ENDPOINT, {
+      method: "PUT",
+      body: toRequestBody(draft),
+    });
+  }
+
+  return { load, save };
+}

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

@@ -0,0 +1,69 @@
+export interface InvitationLink {
+  link: string;
+  expiresAt: string;
+}
+
+export interface InvitationRef {
+  tenantId: string;
+  inviteId: string;
+}
+
+const INVITATIONS_ENDPOINT = "/api/saas/workspaces";
+
+/**
+ * Retrieves an invitation's signup link (each retrieval is journaled server
+ * side) and puts it on the clipboard, reporting the outcome with a toast.
+ */
+export function useInvitationLink() {
+  const { $authFetch } = useAuthFetch();
+  const nuxtApp = useDmsApp();
+  const toast = useToast();
+  const { resolveApiError } = useApiErrorMessage();
+
+  function fetchInvitationLink(ref: InvitationRef): Promise<InvitationLink> {
+    return $authFetch<InvitationLink>(
+      `${INVITATIONS_ENDPOINT}/${ref.tenantId}/invitations/${ref.inviteId}/link`,
+      { method: "POST" },
+    );
+  }
+
+  /** Returns whether the link reached the clipboard. */
+  async function copyLink(link: string): Promise<boolean> {
+    const t = nuxtApp.$i18n.t;
+    try {
+      await navigator.clipboard.writeText(link);
+      toast.add({
+        title: t("saas.workspaces.invitations.link.copied"),
+        color: "success",
+        icon: "i-ph-check-circle",
+      });
+      return true;
+    } catch {
+      // The clipboard can be refused (permissions, insecure origin): the link
+      // stays readable so it can still be copied by hand.
+      toast.add({
+        title: t("saas.workspaces.invitations.link.copy_failed"),
+        description: link,
+        color: "warning",
+        icon: "i-ph-warning",
+        duration: 0,
+      });
+      return false;
+    }
+  }
+
+  async function fetchAndCopy(ref: InvitationRef): Promise<void> {
+    try {
+      const { link } = await fetchInvitationLink(ref);
+      await copyLink(link);
+    } catch (error) {
+      toast.add({
+        title: resolveApiError(error, "saas.workspaces.invitations.link.error"),
+        color: "error",
+        icon: "i-ph-warning-circle",
+      });
+    }
+  }
+
+  return { fetchInvitationLink, copyLink, fetchAndCopy };
+}

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

@@ -0,0 +1,20 @@
+import type { BillingStatusResponse } from "./useBillingStatus";
+
+/**
+ * What the past-due banner offers: the invoice itself when Stripe hands out
+ * its payment page, else the billing page to the owner, who can settle from
+ * there; a member only gets the notice, since the owner pays.
+ */
+export type PastDueBannerAction = "settle" | "open_billing" | "none";
+
+type PastDueBannerStatus = Pick<
+  BillingStatusResponse,
+  "isTenantOwner" | "unpaidInvoice"
+>;
+
+export function resolvePastDueBannerAction(
+  status: PastDueBannerStatus | null,
+): PastDueBannerAction {
+  if (status?.unpaidInvoice?.hostedInvoiceUrl) return "settle";
+  return status?.isTenantOwner ? "open_billing" : "none";
+}

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

@@ -0,0 +1,15 @@
+const OPEN_STATE_KEY = "saas-plan-comparison-open";
+
+/**
+ * Open state of the plan comparison modal hosted by the plan card, shared so
+ * other billing blocks (the payment method card's "add a card") can open it.
+ */
+export function usePlanComparison() {
+  const isOpen = useDmsState<boolean>(OPEN_STATE_KEY, () => false);
+
+  function open(): void {
+    isOpen.value = true;
+  }
+
+  return { isOpen, open };
+}

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

@@ -1,59 +1,351 @@
+import { formatMajorUnits } from "./useMoneyFormat";
+
 const UNLIMITED_NUMERIC_VALUE = -1;
 const EMPTY_LABEL = "—";
 const INCLUDED_LABEL = "✓";
-const EXCLUDED_LABEL = "–";
+const EXCLUDED_LABEL = "—";
+const PRICE_UNIT_PREFIX = "per ";
+const UNIT_LABEL_KEY_PREFIX = "saas.workspace.plan.units";
+const MAX_QUANTITY_FRACTION_DIGITS = 2;
+const MIN_PRICE_FRACTION_DIGITS = 2;
+const MAX_PRICE_SIGNIFICANT_DIGITS = 3;
+/** Upper bound `Intl.NumberFormat` accepts for fraction digits. */
+const MAX_FRACTION_DIGITS = 20;
+const BYTES_PER_KILOBYTE = 1_000;
+
+/**
+ * One way of showing a unit: how many stored units it holds, and the i18n
+ * key of a message node with a `quantity` message (`{value}`, pluralised on
+ * the scaled value) and a `price` message (`{price}`).
+ */
+export interface PlanFeatureUnitScale {
+  label: string;
+  size: number;
+}
+
+/**
+ * How a stored unit reads on a plan page. Quantities take the largest scale
+ * they fill; a price reads per `priceScale` of the unit.
+ */
+export interface PlanFeatureUnitRule {
+  scales: PlanFeatureUnitScale[];
+  priceScale: PlanFeatureUnitScale;
+}
+
+type UnitKind = "quantity" | "price";
+
+/** Translates unit label keys, pluralised on `count`. */
+export type UnitLabelTranslator = (
+  key: string,
+  params: Record<string, string>,
+  count: number,
+) => string;
+
+/** Everything the formatter needs besides the value, kept Vue-free for tests. */
+export interface PlanFeatureFormatContext {
+  locale: string;
+  /** Currency the plan is billed in; prices and money amounts read in it. */
+  currency: string | null;
+  unlimitedLabel: string;
+  translateUnit: UnitLabelTranslator;
+  /**
+   * Renders a stored text value through the DMS display string convention:
+   * a `$key` is translated, anything else is returned as is.
+   */
+  translateText: (text: string) => string;
+}
+
+/** The part of a feature definition that decides how its value reads. */
+export interface FormattableFeature {
+  valueType: string;
+  unit: string | null;
+}
 
 type FeatureValueFormatter = (
   value: unknown,
   unit: string | null,
-  unlimitedLabel: string,
+  context: PlanFeatureFormatContext,
 ) => string;
 
+/** A built-in scale, labelled under dms-saas's own unit messages. */
+function builtInScale(name: string, size: number): PlanFeatureUnitScale {
+  return { label: `${UNIT_LABEL_KEY_PREFIX}.${name}`, size };
+}
+
+const BYTE_SCALES = ["byte", "kilobyte", "megabyte", "gigabyte", "terabyte"].map(
+  (name, power) => builtInScale(name, BYTES_PER_KILOBYTE ** power),
+);
+const GIGABYTE_SCALE = BYTE_SCALES[3]!;
+const MINUTE_SCALE = builtInScale("minute", 1);
+
+const BYTE_RULE: PlanFeatureUnitRule = {
+  scales: BYTE_SCALES,
+  priceScale: GIGABYTE_SCALE,
+};
+const MINUTE_RULE: PlanFeatureUnitRule = {
+  scales: [MINUTE_SCALE],
+  priceScale: MINUTE_SCALE,
+};
+
+/**
+ * Generic units dms-saas knows, normalised to lower case. A unit missing here
+ * and from the registry still reads, as a grouped number followed by the unit
+ * verbatim.
+ */
+const BUILT_IN_UNIT_RULES = new Map<string, PlanFeatureUnitRule>([
+  ["byte", BYTE_RULE],
+  ["bytes", BYTE_RULE],
+  ["minute", MINUTE_RULE],
+  ["minutes", MINUTE_RULE],
+]);
+
+/**
+ * Units consumer modules registered. Registration happens at plugin setup,
+ * on the server and in the browser alike, and always maps a unit to the same
+ * rule, so one module-level map is safe to share across SSR requests.
+ */
+const registeredUnitRules = new Map<string, PlanFeatureUnitRule>();
+
+function normalizeUnit(unit: string): string {
+  return unit.trim().toLowerCase();
+}
+
+/**
+ * Teaches the plan pages how a feature unit reads, e.g. vCPU-minutes shown
+ * in vCPU-hours. Call it from a frontend plugin of the module declaring the
+ * features; labels are full i18n keys that module ships in its own locales.
+ * A registered unit takes precedence over a built-in one of the same name.
+ *
+ * @param unit Stored unit or its spellings (matched case-insensitively), without `per `
+ * @param rule Display scales, in any order, and the scale prices read per
+ * @throws When the rule has no scale or a scale is not a positive size
+ */
+export function registerPlanFeatureUnit(
+  unit: string | string[],
+  rule: PlanFeatureUnitRule,
+): void {
+  const scales = [...rule.scales].sort((left, right) => left.size - right.size);
+  const isValid =
+    scales.length > 0 &&
+    [...scales, rule.priceScale].every((candidate) => candidate.size > 0);
+  if (!isValid) {
+    throw new Error(
+      "Invalid plan feature unit rule: expected at least one scale, all with a positive size",
+    );
+  }
+  for (const name of [unit].flat()) {
+    registeredUnitRules.set(normalizeUnit(name), {
+      scales,
+      priceScale: rule.priceScale,
+    });
+  }
+}
+
+function findUnitRule(base: string): PlanFeatureUnitRule | undefined {
+  return registeredUnitRules.get(base) ?? BUILT_IN_UNIT_RULES.get(base);
+}
+
+/** Units whose value is an amount of the plan's currency. */
+const MONEY_UNITS = new Set(["currency", "currency unit", "currency units"]);
+
+interface ParsedUnit {
+  kind: UnitKind;
+  base: string;
+}
+
+function parseUnit(unit: string): ParsedUnit {
+  const normalized = normalizeUnit(unit);
+  if (normalized.startsWith(PRICE_UNIT_PREFIX)) {
+    return {
+      kind: "price",
+      base: normalized.slice(PRICE_UNIT_PREFIX.length).trim(),
+    };
+  }
+  return { kind: "quantity", base: normalized };
+}
+
+function formatNumber(value: number, locale: string): string {
+  return new Intl.NumberFormat(locale, {
+    maximumFractionDigits: MAX_QUANTITY_FRACTION_DIGITS,
+  }).format(value);
+}
+
+/**
+ * Fraction digits keeping `MAX_PRICE_SIGNIFICANT_DIGITS` of a price, never
+ * fewer than a currency's usual two.
+ */
+function priceFractionDigits(value: number): number {
+  if (value === 0) return MIN_PRICE_FRACTION_DIGITS;
+  const magnitude = Math.floor(Math.log10(Math.abs(value)));
+  const significant = MAX_PRICE_SIGNIFICANT_DIGITS - 1 - magnitude;
+  return Math.min(
+    MAX_FRACTION_DIGITS,
+    Math.max(MIN_PRICE_FRACTION_DIGITS, significant),
+  );
+}
+
+/**
+ * Unit prices are often fractions of a cent: keep three significant digits
+ * below a cent instead of rounding them to a misleading zero.
+ */
+function formatPrice(value: number, context: PlanFeatureFormatContext): string {
+  if (!context.currency) return formatNumber(value, context.locale);
+  return new Intl.NumberFormat(context.locale, {
+    style: "currency",
+    currency: context.currency.toUpperCase(),
+    minimumFractionDigits: MIN_PRICE_FRACTION_DIGITS,
+    maximumFractionDigits: priceFractionDigits(value),
+  }).format(value);
+}
+
+function pickScale(
+  scales: PlanFeatureUnitScale[],
+  value: number,
+): PlanFeatureUnitScale {
+  const magnitude = Math.abs(value);
+  const fitting = scales.filter((candidate) => candidate.size <= magnitude);
+  return fitting.at(-1) ?? scales[0]!;
+}
+
+function unitLabelKey(label: string, kind: UnitKind): string {
+  return `${label}.${kind}`;
+}
+
+function formatQuantityInRule(
+  value: number,
+  rule: PlanFeatureUnitRule,
+  context: PlanFeatureFormatContext,
+): string {
+  const chosen = pickScale(rule.scales, value);
+  const scaled = value / chosen.size;
+  return context.translateUnit(
+    unitLabelKey(chosen.label, "quantity"),
+    { value: formatNumber(scaled, context.locale) },
+    scaled,
+  );
+}
+
+function formatPriceInRule(
+  value: number,
+  rule: PlanFeatureUnitRule,
+  context: PlanFeatureFormatContext,
+): string {
+  const scaled = value * rule.priceScale.size;
+  return context.translateUnit(
+    unitLabelKey(rule.priceScale.label, "price"),
+    { price: formatPrice(scaled, context) },
+    1,
+  );
+}
+
+function formatWithUnknownUnit(
+  value: number,
+  parsed: ParsedUnit,
+  unit: string,
+  context: PlanFeatureFormatContext,
+): string {
+  const amount =
+    parsed.kind === "price"
+      ? formatPrice(value, context)
+      : formatNumber(value, context.locale);
+  return `${amount} ${unit.trim()}`;
+}
+
+function formatNumberWithUnit(
+  value: number,
+  unit: string,
+  context: PlanFeatureFormatContext,
+): string {
+  const parsed = parseUnit(unit);
+  if (parsed.kind === "quantity" && MONEY_UNITS.has(parsed.base)) {
+    return formatMajorUnits(value, context.currency, context.locale);
+  }
+  const rule = findUnitRule(parsed.base);
+  if (!rule) return formatWithUnknownUnit(value, parsed, unit, context);
+  return parsed.kind === "price"
+    ? formatPriceInRule(value, rule, context)
+    : formatQuantityInRule(value, rule, context);
+}
+
+function isTruthyFlag(value: unknown): boolean {
+  return value === true || value === "true" || value === 1;
+}
+
 function formatBoolean(value: unknown): string {
-  return value ? INCLUDED_LABEL : EXCLUDED_LABEL;
+  return isTruthyFlag(value) ? INCLUDED_LABEL : EXCLUDED_LABEL;
 }
 
 function formatNumeric(
   value: unknown,
   unit: string | null,
-  unlimitedLabel: string,
+  context: PlanFeatureFormatContext,
 ): 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);
+  if (numeric === UNLIMITED_NUMERIC_VALUE) return context.unlimitedLabel;
+  if (!unit?.trim()) return formatNumber(numeric, context.locale);
+  return formatNumberWithUnit(numeric, unit, context);
 }
 
-function formatText(value: unknown, unit: string | null): string {
+function formatText(
+  value: unknown,
+  unit: string | null,
+  context: PlanFeatureFormatContext,
+): string {
   const text = String(value).trim();
   if (!text) return EMPTY_LABEL;
-  return unit ? `${text} ${unit}` : text;
+  const shown = context.translateText(text);
+  return unit ? `${shown} ${unit}` : shown;
 }
 
 const FORMATTERS: Record<string, FeatureValueFormatter> = {
   boolean: (value) => formatBoolean(value),
-  number: (value, unit, unlimitedLabel) =>
-    formatNumeric(value, unit, unlimitedLabel),
-  string: (value, unit) => formatText(value, unit),
+  number: formatNumeric,
+  string: formatText,
 };
 
 /**
- * Renders a plan's feature value the way the comparison table shows it, with
- * `-1` reading as unlimited — the same convention `maxMembers` already uses.
+ * Renders a plan's feature value for people: `-1` reads as unlimited (the
+ * convention `maxMembers` already uses), booleans as ✓/—, numbers grouped in
+ * the viewer's locale and scaled by unit — bytes to KB…TB, plus any unit a
+ * consumer registered — and `per <unit>` prices read per the same readable
+ * unit. Text values follow the DMS display string convention: a `$key` is
+ * translated, plain text is shown as stored.
+ *
+ * @param feature Feature definition carrying the value type and unit
+ * @param value Value a plan sets for the feature
+ * @param context Locale, plan currency and unit label translator
  */
+export function formatPlanFeatureValue(
+  feature: FormattableFeature,
+  value: unknown,
+  context: PlanFeatureFormatContext,
+): 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, context);
+}
+
+/** Locale-bound view of {@link formatPlanFeatureValue}, for components. */
 export function usePlanFeatureFormat() {
-  const { t } = useI18n();
+  const { t, locale } = useI18n();
+  const { processI18n } = useTranslation();
 
   function formatFeatureValue(
     feature: TenantPlanFeature,
     value: unknown,
+    currency: string | null = null,
   ): 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 formatPlanFeatureValue(feature, value, {
+      locale: locale.value,
+      currency,
+      unlimitedLabel: t("saas.workspace.plan.unlimited"),
+      translateUnit: (key, params, count) => t(key, params, count),
+      translateText: (text) => processI18n(text),
+    });
   }
 
   return { formatFeatureValue };

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

@@ -0,0 +1,24 @@
+/** The part of a feature definition its label and tooltip come from. */
+export interface LabelledFeature {
+  displayName: string;
+  tooltip: string | null;
+}
+
+/**
+ * Feature label and tooltip readers for the plan pages. Both follow the DMS
+ * display string convention: a stored value starting with `$` is an i18n key
+ * the declaring module ships in its own locales, anything else is shown as
+ * written. A `$` tooltip missing from the locales is hidden rather than shown
+ * as a bare key path.
+ */
+export function usePlanFeatureLabel() {
+  const { t } = useI18n();
+  const { processI18n } = useTranslation();
+
+  return {
+    featureLabel: (feature: LabelledFeature) =>
+      processI18n(feature.displayName),
+    featureTooltip: (feature: LabelledFeature) =>
+      resolveOptionalI18nKey(t, feature.tooltip ?? undefined) ?? null,
+  };
+}