@hexclave/shared 1.0.3 → 1.0.6

package/src/local-emulator.ts

@@ -0,0 +1,5 @@
+// Well-known shared credentials for the dev-only local emulator's admin user.
+// Backend, dashboard auto-login, and CLI all sign in with these exact values —
+// do not "harden" them.
+export const LOCAL_EMULATOR_ADMIN_EMAIL = "local-emulator@hexclave.com";
+export const LOCAL_EMULATOR_ADMIN_PASSWORD = "LocalEmulatorPassword";

package/src/payments/payment-methods.ts

@@ -0,0 +1,167 @@
+/**
+ * Payment Methods Configuration
+ *
+ * Single source of truth for payment method metadata used by both
+ * backend (route validation) and frontend (UI rendering).
+ */
+
+export type PaymentMethodCategory =
+  | 'cards'
+  | 'wallets'
+  | 'bnpl'
+  | 'realtime'
+  | 'bank_debits'
+  | 'bank_transfers'
+  | 'vouchers';
+
+export type PaymentMethodConfig = {
+  name: string,
+  category: PaymentMethodCategory,
+  dependencies?: string[],
+};
+
+/**
+ * All supported payment methods with their display names, categories, and dependencies.
+ * This is the single source of truth - both backend and frontend should import from here.
+ */
+export const PAYMENT_METHODS: Record<string, PaymentMethodConfig> = {
+  // Cards
+  card: { name: 'Credit/Debit Card', category: 'cards' },
+  cartes_bancaires: { name: 'Cartes Bancaires', category: 'cards' },
+
+  // Wallets
+  apple_pay: { name: 'Apple Pay', category: 'wallets', dependencies: ['card'] },
+  google_pay: { name: 'Google Pay', category: 'wallets', dependencies: ['card'] },
+  link: { name: 'Link', category: 'wallets' },
+  amazon_pay: { name: 'Amazon Pay', category: 'wallets' },
+  cashapp: { name: 'Cash App', category: 'wallets' },
+
+  // Buy Now, Pay Later
+  klarna: { name: 'Klarna', category: 'bnpl' },
+  affirm: { name: 'Affirm', category: 'bnpl' },
+  afterpay_clearpay: { name: 'Afterpay / Clearpay', category: 'bnpl' },
+  zip: { name: 'Zip', category: 'bnpl' },
+
+  // Real-Time Payments
+  ideal: { name: 'iDEAL', category: 'realtime' },
+  bancontact: { name: 'Bancontact', category: 'realtime' },
+  eps: { name: 'EPS', category: 'realtime' },
+  p24: { name: 'Przelewy24', category: 'realtime' },
+  blik: { name: 'BLIK', category: 'realtime' },
+  alipay: { name: 'Alipay', category: 'realtime' },
+  wechat_pay: { name: 'WeChat Pay', category: 'realtime' },
+
+  // Bank Debits
+  sepa_debit: { name: 'SEPA Direct Debit', category: 'bank_debits' },
+  bacs_debit: { name: 'Bacs Direct Debit', category: 'bank_debits' },
+  acss_debit: { name: 'ACSS Debit', category: 'bank_debits' },
+
+  // Bank Transfers
+  us_bank_account: { name: 'US Bank Account', category: 'bank_transfers' },
+
+  // Vouchers
+  multibanco: { name: 'Multibanco', category: 'vouchers' },
+  customer_balance: { name: 'Customer Balance', category: 'vouchers' },
+};
+
+/**
+ * Category definitions with display names, ordered by commonality.
+ */
+export const PAYMENT_CATEGORIES: { id: PaymentMethodCategory, name: string }[] = [
+  { id: 'cards', name: 'Cards' },
+  { id: 'wallets', name: 'Wallets' },
+  { id: 'bnpl', name: 'Buy Now, Pay Later' },
+  { id: 'realtime', name: 'Real-Time Payments' },
+  { id: 'bank_debits', name: 'Bank Debits' },
+  { id: 'bank_transfers', name: 'Bank Transfers' },
+  { id: 'vouchers', name: 'Vouchers' },
+];
+
+// ============================================================================
+// Helper functions
+// ============================================================================
+
+/**
+ * Get display name for a payment method ID.
+ * Returns the ID itself if not found (fallback for unknown methods).
+ */
+export function getPaymentMethodName(methodId: string): string {
+  if (!isKnownPaymentMethod(methodId)) {
+    return methodId;
+  }
+  return PAYMENT_METHODS[methodId].name;
+}
+
+/**
+ * Get category for a payment method ID.
+ * Returns undefined if method is not known.
+ */
+export function getPaymentMethodCategory(methodId: string): PaymentMethodCategory | undefined {
+  if (!isKnownPaymentMethod(methodId)) {
+    return undefined;
+  }
+  return PAYMENT_METHODS[methodId].category;
+}
+
+/**
+ * Get dependencies for a payment method ID.
+ * Returns empty array if method is not known or has no dependencies.
+ */
+export function getPaymentMethodDependencies(methodId: string): string[] {
+  if (!isKnownPaymentMethod(methodId)) {
+    return [];
+  }
+  return PAYMENT_METHODS[methodId].dependencies ?? [];
+}
+
+/**
+ * Check if a payment method ID is known/supported.
+ */
+export function isKnownPaymentMethod(methodId: string): boolean {
+  return methodId in PAYMENT_METHODS;
+}
+
+/**
+ * Get all payment method IDs.
+ */
+export function getAllPaymentMethodIds(): string[] {
+  return Object.keys(PAYMENT_METHODS);
+}
+
+/**
+ * Get all display names (useful for schema validation).
+ */
+export function getAllPaymentMethodNames(): string[] {
+  return Object.values(PAYMENT_METHODS).map(m => m.name);
+}
+
+/**
+ * Build dependencies map: { methodId: [requiredMethodIds] }
+ * Only includes methods that have dependencies.
+ */
+export const PAYMENT_METHOD_DEPENDENCIES: Record<string, string[]> = Object.fromEntries(
+  Object.entries(PAYMENT_METHODS)
+    .filter(([, config]) => config.dependencies && config.dependencies.length > 0)
+    .map(([id, config]) => [id, config.dependencies!])
+);
+
+/**
+ * Group payment method IDs by category.
+ */
+export function getPaymentMethodsByCategory(): Record<PaymentMethodCategory, string[]> {
+  const result: Record<PaymentMethodCategory, string[]> = {
+    cards: [],
+    wallets: [],
+    bnpl: [],
+    realtime: [],
+    bank_debits: [],
+    bank_transfers: [],
+    vouchers: [],
+  };
+
+  for (const [id, config] of Object.entries(PAYMENT_METHODS)) {
+    result[config.category].push(id);
+  }
+
+  return result;
+}

package/src/payments/stripe-limits.ts

@@ -0,0 +1,18 @@
+/**
+ * Stripe API limits shared by backend and frontend.
+ * See https://docs.stripe.com/currencies#minimum-and-maximum-charge-amounts.
+ */
+
+/**
+ * Per-currency minimum for one-time PaymentIntents, in the major unit.
+ * Recurring subs have no minimum ($0 subs are allowed).
+ */
+export const STRIPE_ONE_TIME_MIN_AMOUNT_BY_CURRENCY = {
+  USD: 0.50,
+} as const;
+
+export type StripeSupportedCurrency = keyof typeof STRIPE_ONE_TIME_MIN_AMOUNT_BY_CURRENCY;
+
+export function getStripeOneTimeMinAmount(currency: StripeSupportedCurrency): number {
+  return STRIPE_ONE_TIME_MIN_AMOUNT_BY_CURRENCY[currency];
+}

package/src/plans.ts

@@ -0,0 +1,107 @@
+/**
+ * Plan configuration for Hexclave pricing tiers.
+ *
+ * This file defines the limits for each plan and the item IDs used to track them.
+ * Import these constants in seed.ts and backend code for limit enforcement.
+ */
+
+export const UNLIMITED = 1_000_000_000;
+
+/**
+ * Item IDs used across the codebase for tracking plan limits.
+ */
+export const ITEM_IDS = {
+  seats: "dashboard_admins",
+  authUsers: "auth_users",
+  emailsPerMonth: "emails_per_month",
+  analyticsTimeoutSeconds: "analytics_timeout_seconds",
+  analyticsEvents: "analytics_events",
+  sessionReplays: "session_replays",
+  onboardingCall: "onboarding_call",
+} as const;
+
+export type ItemId = typeof ITEM_IDS[keyof typeof ITEM_IDS];
+
+/**
+ * The offerings/limits included in a plan.
+ */
+export type PlanProductOfferings = {
+  seats: number,
+  authUsers: number,
+  emailsPerMonth: number,
+  analyticsTimeoutSeconds: number,
+  analyticsEvents: number,
+  sessionReplays: number,
+};
+
+/**
+ * Plan limits by plan ID.
+ */
+export const PLAN_LIMITS: {
+  free: PlanProductOfferings,
+  team: PlanProductOfferings,
+  growth: PlanProductOfferings,
+} = {
+  free: {
+    seats: 1,
+    authUsers: 10_000,
+    emailsPerMonth: 1_000,
+    analyticsTimeoutSeconds: 10,
+    analyticsEvents: 100_000,
+    sessionReplays: 2_500,
+  },
+  team: {
+    seats: 4,
+    authUsers: 50_000,
+    emailsPerMonth: 25_000,
+    analyticsTimeoutSeconds: 60,
+    analyticsEvents: 500_000,
+    sessionReplays: 2_500,
+  },
+  growth: {
+    seats: 4,
+    authUsers: UNLIMITED,
+    emailsPerMonth: 25_000,
+    analyticsTimeoutSeconds: 300,
+    analyticsEvents: 1_000_000,
+    sessionReplays: 2_500,
+  },
+};
+
+export type PlanId = keyof typeof PLAN_LIMITS;
+
+/**
+ * Base plan IDs ordered from highest to lowest tier. Use this (instead of
+ * string literals) whenever code needs to pick a customer's "current" plan
+ * from their product list, so the choice stays in sync with `PLAN_LIMITS`.
+ */
+export const BASE_PLAN_IDS_BY_TIER = ["growth", "team", "free"] as const satisfies readonly PlanId[];
+
+/**
+ * Minimal shape of a product entry as it comes out of `team.useProducts()` /
+ * `customer.useProducts()` on both the SDK and dashboard sides. Structural so
+ * we don't pull SDK types into `stack-shared`.
+ */
+type PlanResolutionProduct = { id: string | null, type?: string };
+
+/**
+ * Picks the customer's highest-tier active base plan (growth → team → free),
+ * falling back to `"free"` if none of the known plans appear as a
+ * subscription. Single source of truth for plan gating in the dashboard —
+ * do not reintroduce ad-hoc `p.id === "team" || p.id === "growth"` checks.
+ */
+export function resolvePlanId(products: ReadonlyArray<PlanResolutionProduct>): PlanId {
+  const activeSubscriptionPlanIds = new Set(
+    products.filter(p => p.type === "subscription" && p.id != null).map(p => p.id),
+  );
+  return BASE_PLAN_IDS_BY_TIER.find(id => activeSubscriptionPlanIds.has(id)) ?? "free";
+}
+
+/**
+ * Convenience predicate for "is this customer on a paid plan?". Anything
+ * above free counts, so new paid tiers added to `PLAN_LIMITS` are picked up
+ * automatically.
+ */
+export function isPaidPlan(products: ReadonlyArray<PlanResolutionProduct>): boolean {
+  return resolvePlanId(products) !== "free";
+}