@classytic/commerce-sdk 0.1.2 → 0.2.1

package/dist/platform/index.js

@@ -1,8 +1,14 @@
-"use client";
-export { BRANCH_KEYS, BranchApi, COUPON_KEYS, CouponApi, ExportApi, ExportFields, ExportFilters, PLATFORM_KEYS, PlatformConfigApi, USER_KEYS, UserApi, WebhookApi, branchApi, branchHooks, businessApi, couponApi, couponHooks, exportAndDownload, exportApi, isHeadOffice, isSubBranch, parseCSV, platformApi, platformConfigApi, readCSVBlob, useBranchActions, useBranchDetail, useBranchNavigation, useBranches, useCouponActions, useCouponDetail, useCouponNavigation, useCoupons, useDeliveryZones, useMembershipConfig, usePaymentMethods, usePlatformConfig, useUpdatePlatformConfig, useUserActions, useUserDetail, useUserNavigation, useUsers, userApi, userHooks, webhookApi } from '../chunk-YYFKLOKO.js';
-import '../chunk-QCTXAMLA.js';
-import '../chunk-B6MPVOV7.js';
-import '../chunk-U3XT35GZ.js';
-import '../chunk-IHCBBLLW.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+import { PlatformConfigApi, platformConfigApi } from "./api/config.js";
+import { BranchApi, branchApi } from "./api/branch.js";
+import { UserApi, userApi } from "./api/user.js";
+import { EvaluationApi, ProgramApi, VoucherApi, evaluationApi, programApi, voucherApi } from "./api/promo.js";
+import { WebhookApi, webhookApi } from "./api/webhook.js";
+import { FeaturesApi, featuresApi } from "./api/features.js";
+import { isHeadOffice, isSubBranch } from "./types/branch.js";
+import { PERMISSION_MATRIX_KEYS, PLATFORM_KEYS, useDeliveryZones, useMembershipConfig, usePaymentMethods, usePermissionMatrix, usePlatformConfig, useUpdatePlatformConfig } from "./hooks/config.js";
+import { BRANCH_KEYS, branchHooks, useBranchActions, useBranchDetail, useBranchNavigation, useBranches } from "./hooks/branch.js";
+import { USER_KEYS, useUserActions, useUserDetail, useUserNavigation, useUsers, userHooks } from "./hooks/user.js";
+import { EVALUATION_KEYS, PROGRAM_KEYS, VOUCHER_KEYS, programHooks, useFullProgram, useProgramActions, useProgramDetail, useProgramNavigation, useProgramRewards, useProgramRules, useProgramTransition, usePrograms, usePromoCommit, usePromoEvaluate, usePromoPreview, usePromoRollback, useVoucherCancel, useVoucherGenerate, useVoucherGenerateSingle, useVoucherValidate } from "./hooks/promo.js";
+import { FEATURE_KEYS, useFeatures } from "./hooks/features.js";
+
+export { BRANCH_KEYS, BranchApi, EVALUATION_KEYS, EvaluationApi, FEATURE_KEYS, FeaturesApi, PERMISSION_MATRIX_KEYS, PLATFORM_KEYS, PROGRAM_KEYS, PlatformConfigApi, ProgramApi, USER_KEYS, UserApi, VOUCHER_KEYS, VoucherApi, WebhookApi, branchApi, branchHooks, evaluationApi, featuresApi, isHeadOffice, isSubBranch, platformConfigApi, programApi, programHooks, useBranchActions, useBranchDetail, useBranchNavigation, useBranches, useDeliveryZones, useFeatures, useFullProgram, useMembershipConfig, usePaymentMethods, usePermissionMatrix, usePlatformConfig, useProgramActions, useProgramDetail, useProgramNavigation, useProgramRewards, useProgramRules, useProgramTransition, usePrograms, usePromoCommit, usePromoEvaluate, usePromoPreview, usePromoRollback, useUpdatePlatformConfig, useUserActions, useUserDetail, useUserNavigation, useUsers, useVoucherCancel, useVoucherGenerate, useVoucherGenerateSingle, useVoucherValidate, userApi, userHooks, voucherApi, webhookApi };

package/dist/platform/prefetch.d.ts

@@ -0,0 +1,9 @@
+import * as _classytic_arc_next_prefetch0 from "@classytic/arc-next/prefetch";
+
+//#region src/platform/prefetch.d.ts
+/**
+ * Platform SSR Prefetchers
+ */
+declare const branchesPrefetcher: _classytic_arc_next_prefetch0.CrudPrefetcher;
+//#endregion
+export { branchesPrefetcher };

package/dist/platform/prefetch.js

@@ -0,0 +1,11 @@
+import { branchApi } from "./api/branch.js";
+import { createCrudPrefetcher } from "../core/prefetch.js";
+
+//#region src/platform/prefetch.ts
+/**
+* Platform SSR Prefetchers
+*/
+const branchesPrefetcher = createCrudPrefetcher(branchApi, "branches");
+
+//#endregion
+export { branchesPrefetcher };

package/dist/platform/types/branch.d.ts

@@ -0,0 +1,110 @@
+//#region src/platform/types/branch.d.ts
+/**
+ * Branch Types
+ *
+ * Type definitions for store/warehouse locations.
+ * Separated from inventory types for better organization and single responsibility.
+ */
+type BranchType = 'store' | 'warehouse' | 'outlet' | 'franchise';
+/**
+ * Branch Hierarchy Role
+ * Determines the branch's position in the inventory flow hierarchy.
+ *
+ * - head_office: Central warehouse/HQ that receives purchases and distributes to sub-branches
+ * - sub_branch: Store/outlet that receives stock from head office
+ */
+type BranchRole = 'head_office' | 'sub_branch';
+interface BranchAddress {
+  line1?: string;
+  line2?: string;
+  city?: string;
+  state?: string;
+  postalCode?: string;
+  country?: string;
+}
+/**
+ * Branch (Store/Warehouse Location)
+ *
+ * Represents a physical location for inventory tracking and POS operations.
+ * Every deployment must have at least one branch (default branch).
+ *
+ * Branch Hierarchy:
+ * - One branch must be designated as head_office (typically the default branch)
+ * - All other branches are sub_branch by default
+ * - Stock flows: Suppliers -> Head Office -> Sub-branches
+ */
+interface Branch {
+  _id: string;
+  /** URL-friendly slug (auto-generated from name) */
+  slug: string;
+  /** Unique branch code (e.g., "DHK-1", "CTG-MAIN") - uppercase, stable */
+  code: string;
+  /** Display name */
+  name: string;
+  /** Branch type (store, warehouse, outlet, franchise) */
+  type: BranchType;
+  /**
+   * Branch role in inventory hierarchy
+   * - head_office: Receives purchases, distributes to sub-branches
+   * - sub_branch: Receives stock from head office only
+   */
+  role: BranchRole;
+  /** Physical address */
+  address?: BranchAddress;
+  /** Contact phone */
+  phone?: string;
+  /** Contact email */
+  email?: string;
+  /** Operating hours (simple format, e.g., "10:00 AM - 10:00 PM") */
+  operatingHours?: string;
+  /** Whether this is the default branch (only one can be default) */
+  isDefault: boolean;
+  /** Whether this branch is active */
+  isActive: boolean;
+  /** Admin notes (admin-only field) */
+  notes?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+/**
+ * Create Branch Payload
+ */
+interface CreateBranchPayload {
+  code: string;
+  name: string;
+  type?: BranchType;
+  /** Branch hierarchy role (defaults to 'sub_branch') */
+  role?: BranchRole;
+  address?: BranchAddress;
+  phone?: string;
+  email?: string;
+  operatingHours?: string;
+  isDefault?: boolean;
+}
+/**
+ * Update Branch Payload
+ */
+interface UpdateBranchPayload extends Partial<CreateBranchPayload> {
+  isActive?: boolean;
+  notes?: string;
+}
+/**
+ * Branch Summary (for dropdowns, lists)
+ */
+interface BranchSummary {
+  _id: string;
+  code: string;
+  name: string;
+  role: BranchRole;
+  isDefault: boolean;
+}
+/**
+ * Check if branch is head office
+ */
+declare function isHeadOffice(branch: Branch | BranchSummary): boolean;
+/**
+ * Check if branch is sub-branch
+ */
+declare function isSubBranch(branch: Branch | BranchSummary): boolean;
+//#endregion
+export { Branch, BranchAddress, BranchRole, BranchSummary, BranchType, CreateBranchPayload, UpdateBranchPayload, isHeadOffice, isSubBranch };

package/dist/platform/types/branch.js

@@ -0,0 +1,16 @@
+//#region src/platform/types/branch.ts
+/**
+* Check if branch is head office
+*/
+function isHeadOffice(branch) {
+	return branch.role === "head_office";
+}
+/**
+* Check if branch is sub-branch
+*/
+function isSubBranch(branch) {
+	return branch.role === "sub_branch";
+}
+
+//#endregion
+export { isHeadOffice, isSubBranch };

package/dist/platform/types/config.d.ts

@@ -0,0 +1,137 @@
+//#region src/platform/types/config.d.ts
+/**
+ * Platform Config Types
+ *
+ * Mirrors `modules/platform/platform.model.js` (PlatformConfig singleton).
+ * Includes payment methods, checkout, logistics, VAT, and policies.
+ */
+type PaymentMethodType = "cash" | "mfs" | "bank_transfer" | "card";
+interface PaymentMethodConfig {
+  _id?: string;
+  type: PaymentMethodType;
+  name: string;
+  provider?: "bkash" | "nagad" | "rocket" | "upay";
+  walletNumber?: string;
+  walletName?: string;
+  bankName?: string;
+  accountNumber?: string;
+  accountName?: string;
+  branchName?: string;
+  routingNumber?: string;
+  cardTypes?: ("visa" | "mastercard" | "amex" | "unionpay" | "other")[];
+  note?: string;
+  isActive?: boolean;
+}
+interface PlatformVatCategoryRate {
+  category: string;
+  rate: number;
+  description?: string;
+}
+interface PlatformVatInvoiceConfig {
+  showVatBreakdown?: boolean;
+  prefix?: string;
+  startNumber?: number;
+  currentNumber?: number;
+  footerText?: string;
+}
+interface PlatformSupplementaryDutyConfig {
+  enabled?: boolean;
+  defaultRate?: number;
+}
+interface PlatformVatConfig {
+  isRegistered: boolean;
+  bin?: string;
+  registeredName?: string;
+  vatCircle?: string;
+  defaultRate: number;
+  pricesIncludeVat: boolean;
+  categoryRates?: PlatformVatCategoryRate[];
+  invoice?: PlatformVatInvoiceConfig;
+  supplementaryDuty?: PlatformSupplementaryDutyConfig;
+}
+interface DeliveryZone {
+  _id?: string;
+  name: string;
+  region: string;
+  price: number;
+  estimatedDays?: number;
+  isActive?: boolean;
+}
+interface CheckoutPickupBranch {
+  branchId?: string;
+  branchCode?: string;
+  branchName?: string;
+}
+type DeliveryFeeSource = "static" | "provider";
+interface CheckoutSettings {
+  allowStorePickup: boolean;
+  pickupBranches: CheckoutPickupBranch[];
+  deliveryFeeSource: DeliveryFeeSource;
+  freeDeliveryThreshold: number;
+  deliveryZones: DeliveryZone[];
+}
+interface LogisticsSettings {
+  defaultPickupStoreId?: number;
+  defaultPickupStoreName?: string;
+  defaultPickupAreaId?: number;
+  defaultPickupAreaName?: string;
+  webhookSecret?: string;
+  autoCreateShipment: boolean;
+  autoCreateOnStatus: string;
+}
+interface PlatformPolicies {
+  termsAndConditions?: string;
+  privacyPolicy?: string;
+  refundPolicy?: string;
+  shippingPolicy?: string;
+}
+type MembershipRoundingMode = "floor" | "round" | "ceil";
+interface MembershipTierConfig {
+  name: string;
+  minPoints: number;
+  pointsMultiplier: number;
+  discountPercent: number;
+  color?: string;
+}
+interface MembershipRedemptionConfig {
+  enabled: boolean;
+  minRedeemPoints: number;
+  minOrderAmount: number;
+  maxRedeemPercent: number;
+  pointsPerBdt: number;
+}
+interface MembershipConfig {
+  enabled: boolean;
+  pointsPerAmount: number;
+  amountPerPoint: number;
+  roundingMode: MembershipRoundingMode;
+  tiers: MembershipTierConfig[];
+  cardPrefix: string;
+  cardDigits: number;
+  redemption?: MembershipRedemptionConfig;
+}
+interface PlatformConfig {
+  _id: string;
+  platformName: string;
+  /** Flexible payment methods array */
+  paymentMethods: PaymentMethodConfig[];
+  checkout: CheckoutSettings;
+  logistics: LogisticsSettings;
+  vat: PlatformVatConfig;
+  membership?: MembershipConfig;
+  policies?: PlatformPolicies;
+  isSingleton: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+interface UpdatePlatformConfigPayload {
+  platformName?: string;
+  paymentMethods?: PaymentMethodConfig[];
+  checkout?: Partial<CheckoutSettings>;
+  logistics?: Partial<LogisticsSettings>;
+  vat?: Partial<PlatformVatConfig>;
+  membership?: Partial<MembershipConfig>;
+  policies?: Partial<PlatformPolicies>;
+}
+//#endregion
+export { CheckoutPickupBranch, CheckoutSettings, DeliveryFeeSource, DeliveryZone, LogisticsSettings, MembershipConfig, MembershipRedemptionConfig, MembershipRoundingMode, MembershipTierConfig, PaymentMethodConfig, PlatformConfig, PlatformPolicies, PlatformSupplementaryDutyConfig, PlatformVatCategoryRate, PlatformVatConfig, PlatformVatInvoiceConfig, UpdatePlatformConfigPayload };

package/dist/platform/types/features.d.ts

@@ -0,0 +1,46 @@
+//#region src/platform/types/features.d.ts
+/**
+ * Feature License Types
+ *
+ * Represents which modules + tiers are enabled for this deployment.
+ * Served by GET /api/v1/features (public, no auth).
+ *
+ * Designed so backend can evolve resolution logic (license key, SaaS billing, etc.)
+ * without breaking the SDK contract.
+ */
+type PlanStatus = "trial" | "pro" | "enterprise" | "expired";
+interface PlanInfo {
+  /** Current plan level */
+  status: PlanStatus;
+  /** Human-readable plan name (e.g. "BigBoss Pro") */
+  name: string;
+  /** Trial/plan expiry date (ISO string). Null if no expiry. */
+  expiresAt: string | null;
+  /** Days remaining. -1 if no expiry. */
+  daysRemaining: number;
+}
+type FeatureTier = "basic" | "standard" | "enterprise";
+/** Feature-level status (more granular than boolean enabled) */
+type FeatureStatus = "active" | "trial" | "disabled" | "expired" | "upgrade_required";
+interface ResolvedFeature {
+  /** Feature ID (e.g. "loyalty", "inventory", "warehouse") */
+  id: string;
+  /** Whether the feature is usable right now */
+  enabled: boolean;
+  /** Granular status for UI display */
+  status: FeatureStatus;
+  /** Current tier level */
+  tier: FeatureTier;
+  /** Tier-specific capabilities (e.g. ["earn_points", "tiers", "referrals"]) */
+  capabilities: string[];
+}
+interface FeatureManifest {
+  /** Deployment plan info */
+  plan: PlanInfo;
+  /** All features with resolved state */
+  features: ResolvedFeature[];
+  /** List of enabled feature IDs (convenience) */
+  enabled: string[];
+}
+//#endregion
+export { FeatureManifest, FeatureStatus, FeatureTier, PlanInfo, ResolvedFeature };

package/dist/platform/types/promo.d.ts

@@ -0,0 +1,260 @@
+//#region src/platform/types/promo.d.ts
+/**
+ * Promo Types
+ *
+ * Type definitions for the @classytic/promo engine.
+ * Covers programs, rules, rewards, vouchers, and cart evaluation.
+ */
+type ProgramType = 'promotion' | 'coupon' | 'discount_code' | 'buy_x_get_y' | 'gift_card';
+type TriggerMode = 'auto' | 'code';
+type ProgramStatus = 'draft' | 'active' | 'paused' | 'expired' | 'archived';
+type StackingMode = 'exclusive' | 'stackable';
+type RewardType = 'discount' | 'free_product';
+type DiscountMode = 'percentage' | 'fixed';
+type DiscountScope = 'order' | 'cheapest' | 'specific_products';
+type VoucherStatus = 'active' | 'used' | 'expired' | 'cancelled';
+/** Promotional program (promotion, coupon, discount code, buy-x-get-y, gift card) */
+interface Program {
+  _id: string;
+  name: string;
+  description?: string;
+  programType: ProgramType;
+  triggerMode: TriggerMode;
+  status: ProgramStatus;
+  stackingMode: StackingMode;
+  priority: number;
+  startsAt?: string;
+  endsAt?: string;
+  maxUsageTotal?: number;
+  usedCount: number;
+  maxUsagePerCustomer?: number;
+  applicableCustomerIds: string[];
+  applicableCustomerTags: string[];
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+/** Eligibility rule attached to a program */
+interface Rule {
+  _id: string;
+  programId: string;
+  name?: string;
+  minimumAmount: number;
+  minimumQuantity: number;
+  applicableProductIds: string[];
+  applicableCategories: string[];
+  applicableSkus: string[];
+  buyQuantity?: number;
+  code?: string;
+  startsAt?: string;
+  endsAt?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+/** Reward granted when a rule is satisfied */
+interface Reward {
+  _id: string;
+  programId: string;
+  ruleId?: string;
+  rewardType: RewardType;
+  discountMode?: DiscountMode;
+  discountAmount?: number;
+  maxDiscountAmount?: number;
+  discountScope: DiscountScope;
+  applicableProductIds: string[];
+  freeProductId?: string;
+  freeProductSku?: string;
+  freeQuantity: number;
+  giftCardAmount?: number;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+/** Single voucher redemption record */
+interface VoucherRedemption {
+  orderId: string;
+  customerId?: string;
+  discountAmount: number;
+  redeemedAt: string;
+}
+/** Voucher / code instance */
+interface Voucher {
+  _id: string;
+  programId: string;
+  code: string;
+  status: VoucherStatus;
+  customerId?: string;
+  usageLimit: number;
+  usedCount: number;
+  initialBalance?: number;
+  currentBalance?: number;
+  expiresAt?: string;
+  redemptions: VoucherRedemption[];
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+/** Program with its rules and rewards pre-loaded */
+interface FullProgram extends Program {
+  rules: Rule[];
+  rewards: Reward[];
+}
+/** Single cart line item for evaluation */
+interface CartItem {
+  productId: string;
+  sku?: string;
+  categoryId?: string;
+  quantity: number;
+  unitPrice: number;
+  lineTotal?: number;
+}
+/** Input payload for cart evaluation */
+interface EvaluateInput {
+  items: CartItem[];
+  subtotal: number;
+  codes?: string[];
+  customerId?: string;
+  customerTags?: string[];
+}
+/** Applied discount line in evaluation result */
+interface DiscountLine {
+  programId: string;
+  programName: string;
+  rewardId: string;
+  type: 'percentage' | 'fixed';
+  scope: string;
+  amount: number;
+  description: string;
+  voucherCode?: string;
+}
+/** Free product line in evaluation result */
+interface FreeProductLine {
+  programId: string;
+  programName: string;
+  rewardId: string;
+  productId?: string;
+  productSku?: string;
+  quantity: number;
+  description: string;
+}
+/** Code that was submitted but not applied */
+interface RejectedCode {
+  code: string;
+  reason: string;
+}
+/** Full evaluation result from the promo engine */
+interface EvaluationResult {
+  evaluationId: string;
+  appliedDiscounts: DiscountLine[];
+  freeProducts: FreeProductLine[];
+  totalDiscount: number;
+  subtotalAfterDiscount: number;
+  appliedCodes: string[];
+  rejectedCodes: RejectedCode[];
+  warnings: string[];
+  isPreview: boolean;
+  programsApplied: string[];
+}
+/** Result of committing an evaluation to an order */
+interface CommitResult {
+  evaluationId: string;
+  orderId: string;
+  totalDiscount: number;
+  programsCommitted: number;
+  vouchersUsed: number;
+}
+/** Voucher validation result */
+interface VoucherValidation {
+  valid: boolean;
+  voucher?: {
+    code: string;
+    programId: string;
+    programType: string;
+    status: string;
+    remainingUses: number;
+    currentBalance?: number;
+    expiresAt?: string;
+  };
+  error?: string;
+}
+/** Gift card balance lookup result */
+interface GiftCardBalance {
+  code: string;
+  initialBalance: number;
+  currentBalance: number;
+  spent: number;
+  voucherId: string;
+}
+/** Create a new program */
+interface CreateProgramPayload {
+  name: string;
+  description?: string;
+  programType: ProgramType;
+  triggerMode: TriggerMode;
+  stackingMode?: StackingMode;
+  priority?: number;
+  startsAt?: string;
+  endsAt?: string;
+  maxUsageTotal?: number;
+  maxUsagePerCustomer?: number;
+  applicableCustomerIds?: string[];
+  applicableCustomerTags?: string[];
+  metadata?: Record<string, unknown>;
+}
+/** Update an existing program */
+type UpdateProgramPayload = Partial<CreateProgramPayload>;
+/** Create a rule on a program */
+interface CreateRulePayload {
+  name?: string;
+  minimumAmount?: number;
+  minimumQuantity?: number;
+  applicableProductIds?: string[];
+  applicableCategories?: string[];
+  applicableSkus?: string[];
+  buyQuantity?: number;
+  code?: string;
+  startsAt?: string;
+  endsAt?: string;
+  metadata?: Record<string, unknown>;
+}
+/** Update a rule */
+type UpdateRulePayload = Partial<CreateRulePayload>;
+/** Create a reward on a program */
+interface CreateRewardPayload {
+  ruleId?: string;
+  rewardType: RewardType;
+  discountMode?: DiscountMode;
+  discountAmount?: number;
+  maxDiscountAmount?: number;
+  discountScope?: DiscountScope;
+  applicableProductIds?: string[];
+  freeProductId?: string;
+  freeProductSku?: string;
+  freeQuantity?: number;
+  giftCardAmount?: number;
+  metadata?: Record<string, unknown>;
+}
+/** Update a reward */
+type UpdateRewardPayload = Partial<CreateRewardPayload>;
+/** Batch-generate voucher codes */
+interface GenerateCodesPayload {
+  programId: string;
+  count: number;
+  customerId?: string;
+  expiresAt?: string;
+  metadata?: Record<string, unknown>;
+}
+/** Generate a single voucher code (optionally custom) */
+interface GenerateSingleCodePayload {
+  programId: string;
+  code?: string;
+  customerId?: string;
+  expiresAt?: string;
+  initialBalance?: number;
+  metadata?: Record<string, unknown>;
+}
+/** Valid program state transition actions */
+type ProgramTransitionAction = 'activate' | 'pause' | 'archive';
+//#endregion
+export { CartItem, CommitResult, CreateProgramPayload, CreateRewardPayload, CreateRulePayload, DiscountLine, DiscountMode, DiscountScope, EvaluateInput, EvaluationResult, FreeProductLine, FullProgram, GenerateCodesPayload, GenerateSingleCodePayload, GiftCardBalance, Program, ProgramStatus, ProgramTransitionAction, ProgramType, RejectedCode, Reward, RewardType, Rule, StackingMode, TriggerMode, UpdateProgramPayload, UpdateRewardPayload, UpdateRulePayload, Voucher, VoucherRedemption, VoucherStatus, VoucherValidation };

package/dist/platform/types/user.d.ts

@@ -0,0 +1,72 @@
+//#region src/platform/types/user.d.ts
+/**
+ * User Types for Admin Management
+ *
+ * Simple types for CRUD operations on users.
+ * Frontend uses standard BaseApi methods with these types.
+ */
+/** System-level roles (global permissions) */
+type UserRoleType = 'user' | 'admin' | 'superadmin' | 'finance-admin' | 'finance-manager' | 'store-manager' | 'store-staff' | 'warehouse-admin' | 'warehouse-staff';
+/** Branch-specific roles */
+type BranchRoleType = 'branch_manager' | 'inventory_staff' | 'cashier' | 'stock_receiver' | 'stock_requester' | 'viewer';
+/** User's branch assignment */
+interface UserBranchAssignment {
+  branchId: string;
+  branchCode?: string;
+  branchName?: string;
+  branchRole?: 'head_office' | 'sub_branch';
+  roles: BranchRoleType[];
+  isPrimary: boolean;
+}
+/** User document */
+interface User {
+  _id: string;
+  name: string;
+  email: string;
+  roles: UserRoleType[];
+  branches: UserBranchAssignment[];
+  isActive: boolean;
+  lastLoginAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+/** Create user payload */
+interface CreateUserPayload {
+  name: string;
+  email: string;
+  password: string;
+  roles?: UserRoleType[];
+  branches?: Array<{
+    branchId: string;
+    roles?: BranchRoleType[];
+    isPrimary?: boolean;
+  }>;
+}
+/** Update user payload - just patch what you need */
+interface UpdateUserPayload {
+  name?: string;
+  email?: string;
+  roles?: UserRoleType[];
+  branches?: Array<{
+    branchId: string;
+    roles?: BranchRoleType[];
+    isPrimary?: boolean;
+  }>;
+  isActive?: boolean;
+}
+/** Query params for listing users */
+interface UserListParams {
+  page?: number;
+  limit?: number;
+  sort?: string;
+  name?: string;
+  'name[contains]'?: string;
+  email?: string;
+  roles?: UserRoleType;
+  'roles[in]'?: string;
+  'branches.branchId'?: string;
+  'branches.roles'?: BranchRoleType;
+  isActive?: boolean;
+}
+//#endregion
+export { BranchRoleType, CreateUserPayload, UpdateUserPayload, User, UserBranchAssignment, UserListParams, UserRoleType };