@classytic/commerce-sdk 0.1.2 → 0.2.1

package/dist/permissions/checker.js

@@ -0,0 +1,150 @@
+import { groups } from "./roles.js";
+
+//#region src/permissions/checker.ts
+/**
+* Permission Checker — client-side RBAC resolution.
+*
+* Mirrors be-prod/src/config/permissions/ exactly.
+* Takes allRoles (system + branch member role) and returns flat can* booleans.
+*
+* Usage:
+*   const { allRoles } = useBranch();
+*   const can = createPermissionChecker(allRoles);
+*   if (can.products.delete) { ... }
+*/
+function hasAny(userRoles, allowed) {
+	return allowed.some((r) => userRoles.includes(r));
+}
+function isAdmin(userRoles) {
+	return hasAny(userRoles, groups.adminOnly);
+}
+function isHeadOffice(branch) {
+	return branch?.branchRole === "head_office";
+}
+function getStockAdjustmentCapability(userRoles, branch, currentStock) {
+	if (!branch) return {
+		mode: "none",
+		reason: "No branch selected"
+	};
+	const admin = isAdmin(userRoles);
+	const hasMgmt = hasAny(userRoles, ["branch_manager", "inventory_staff"]);
+	if (isHeadOffice(branch)) {
+		if (!admin) return {
+			mode: "none",
+			reason: "Head office stock adjustments require admin/superadmin role. Use Purchases to add stock."
+		};
+		return { mode: "set_any" };
+	}
+	if (admin) return { mode: "set_any" };
+	if (hasMgmt) return {
+		mode: "set_decrease_only",
+		max: Math.max(0, currentStock),
+		reason: "Sub-branches can only decrease stock via adjustments. Use Stock Requests to get more stock from Head Office."
+	};
+	return {
+		mode: "none",
+		reason: "Stock adjustments require admin/superadmin or branch_manager/inventory_staff role"
+	};
+}
+function createPermissionChecker(allRoles) {
+	const r = allRoles;
+	return {
+		isAdmin: isAdmin(r),
+		isSuperAdmin: hasAny(r, groups.superadminOnly),
+		products: {
+			list: true,
+			create: hasAny(r, groups.storeAdmin),
+			update: hasAny(r, groups.storeAdmin),
+			delete: hasAny(r, groups.storeAdmin),
+			syncStock: hasAny(r, groups.inventoryStaff)
+		},
+		categories: {
+			list: true,
+			create: hasAny(r, groups.storeAdmin),
+			delete: hasAny(r, groups.storeAdmin)
+		},
+		orders: {
+			list: hasAny(r, groups.storeAdmin),
+			create: hasAny(r, ["user"]),
+			updateStatus: hasAny(r, groups.storeAdmin),
+			cancel: true,
+			delete: hasAny(r, groups.storeAdmin)
+		},
+		customers: {
+			list: hasAny(r, groups.storeAdmin),
+			create: hasAny(r, groups.storeAdmin),
+			delete: hasAny(r, groups.storeAdmin)
+		},
+		promos: {
+			list: hasAny(r, groups.storeAdmin),
+			create: hasAny(r, groups.storeAdmin),
+			delete: hasAny(r, groups.storeAdmin)
+		},
+		users: {
+			list: hasAny(r, groups.platformStaff),
+			create: hasAny(r, groups.superadminOnly),
+			update: hasAny(r, groups.superadminOnly),
+			delete: hasAny(r, groups.superadminOnly)
+		},
+		branches: {
+			list: hasAny(r, groups.storeStaff),
+			create: hasAny(r, groups.storeAdmin),
+			update: hasAny(r, groups.storeAdmin),
+			delete: hasAny(r, groups.storeAdmin)
+		},
+		pos: { access: hasAny(r, groups.storeStaff) },
+		inventory: {
+			view: hasAny(r, groups.storeStaff),
+			viewAll: hasAny(r, groups.adminOnly),
+			adjust: hasAny(r, groups.storeStaff),
+			purchase: hasAny(r, groups.warehouseStaff),
+			purchaseView: hasAny(r, [...groups.inventoryStaff, ...groups.financeStaff]),
+			transferCreate: hasAny(r, groups.warehouseStaff),
+			transferReceive: hasAny(r, [
+				"admin",
+				"superadmin",
+				"store-manager"
+			]),
+			transferView: hasAny(r, groups.inventoryStaff),
+			stockRequestCreate: hasAny(r, groups.inventoryStaff),
+			stockRequestApprove: hasAny(r, groups.warehouseStaff),
+			supplierManage: hasAny(r, groups.warehouseStaff),
+			supplierView: hasAny(r, groups.inventoryStaff),
+			movements: hasAny(r, groups.storeStaff),
+			lotManage: hasAny(r, groups.warehouseStaff),
+			lotView: hasAny(r, groups.inventoryStaff),
+			packageManage: hasAny(r, groups.warehouseStaff),
+			packageView: hasAny(r, groups.inventoryStaff),
+			procurementCreate: hasAny(r, groups.warehouseStaff),
+			procurementView: hasAny(r, [...groups.inventoryStaff, ...groups.financeStaff]),
+			replenishmentManage: hasAny(r, groups.warehouseStaff),
+			replenishmentView: hasAny(r, groups.inventoryStaff),
+			costView: hasAny(r, [...groups.warehouseStaff, ...groups.financeStaff]),
+			traceView: hasAny(r, groups.warehouseStaff),
+			reportView: hasAny(r, [...groups.warehouseStaff, ...groups.financeStaff])
+		},
+		finance: {
+			view: hasAny(r, groups.financeStaff),
+			manage: hasAny(r, groups.financeStaff)
+		},
+		accounting: {
+			view: hasAny(r, groups.financeStaff),
+			manage: hasAny(r, groups.financeStaff)
+		},
+		loyalty: {
+			view: hasAny(r, groups.storeAdmin),
+			manage: hasAny(r, groups.storeAdmin)
+		},
+		media: {
+			view: hasAny(r, groups.storeAdmin),
+			manage: hasAny(r, groups.storeAdmin)
+		},
+		cms: {
+			view: hasAny(r, groups.storeAdmin),
+			manage: hasAny(r, groups.storeAdmin)
+		}
+	};
+}
+
+//#endregion
+export { createPermissionChecker, getStockAdjustmentCapability };

package/dist/permissions/index.d.ts

@@ -0,0 +1,3 @@
+import { BranchRoleValue, RoleValue, branchRoles, groups, roles } from "./roles.js";
+import { BranchContext, Permissions, StockAdjustmentCapability, createPermissionChecker, getStockAdjustmentCapability } from "./checker.js";
+export { type BranchContext, type BranchRoleValue, type Permissions, type RoleValue, type StockAdjustmentCapability, branchRoles, createPermissionChecker, getStockAdjustmentCapability, groups, roles };

package/dist/permissions/index.js

@@ -0,0 +1,4 @@
+import { branchRoles, groups, roles } from "./roles.js";
+import { createPermissionChecker, getStockAdjustmentCapability } from "./checker.js";
+
+export { branchRoles, createPermissionChecker, getStockAdjustmentCapability, groups, roles };

package/dist/permissions/roles.d.ts

@@ -0,0 +1,39 @@
+//#region src/permissions/roles.d.ts
+/**
+ * Role definitions — mirrors be-prod/src/config/permissions/roles.ts exactly.
+ * Single source of truth for both backend and frontend.
+ */
+declare const roles: {
+  readonly USER: "user";
+  readonly ADMIN: "admin";
+  readonly SUPERADMIN: "superadmin";
+  readonly FINANCE_MANAGER: "finance-manager";
+  readonly FINANCE_ADMIN: "finance-admin";
+  readonly STORE_MANAGER: "store-manager";
+  readonly STORE_STAFF: "store-staff";
+  readonly WAREHOUSE_STAFF: "warehouse-staff";
+  readonly WAREHOUSE_ADMIN: "warehouse-admin";
+};
+type RoleValue = (typeof roles)[keyof typeof roles];
+declare const groups: {
+  readonly platformStaff: readonly ["admin", "superadmin"];
+  readonly adminOnly: readonly ["admin", "superadmin"];
+  readonly superadminOnly: readonly ["superadmin"];
+  readonly storeAdmin: readonly ["superadmin", "admin", "store-manager", "warehouse-admin", "finance-admin"];
+  readonly storeStaff: readonly ["superadmin", "admin", "store-manager", "store-staff"];
+  readonly financeStaff: readonly ["superadmin", "admin", "finance-admin", "finance-manager"];
+  readonly warehouseStaff: readonly ["superadmin", "admin", "warehouse-admin", "warehouse-staff"];
+  readonly inventoryStaff: readonly ["superadmin", "admin", "warehouse-admin", "warehouse-staff", "store-manager", "store-staff"];
+};
+/** Branch-level roles (Better Auth org membership) */
+declare const branchRoles: {
+  readonly BRANCH_MANAGER: "branch_manager";
+  readonly INVENTORY_STAFF: "inventory_staff";
+  readonly CASHIER: "cashier";
+  readonly STOCK_RECEIVER: "stock_receiver";
+  readonly STOCK_REQUESTER: "stock_requester";
+  readonly VIEWER: "viewer";
+};
+type BranchRoleValue = (typeof branchRoles)[keyof typeof branchRoles];
+//#endregion
+export { BranchRoleValue, RoleValue, branchRoles, groups, roles };

package/dist/permissions/roles.js

@@ -0,0 +1,66 @@
+//#region src/permissions/roles.ts
+/**
+* Role definitions — mirrors be-prod/src/config/permissions/roles.ts exactly.
+* Single source of truth for both backend and frontend.
+*/
+const roles = {
+	USER: "user",
+	ADMIN: "admin",
+	SUPERADMIN: "superadmin",
+	FINANCE_MANAGER: "finance-manager",
+	FINANCE_ADMIN: "finance-admin",
+	STORE_MANAGER: "store-manager",
+	STORE_STAFF: "store-staff",
+	WAREHOUSE_STAFF: "warehouse-staff",
+	WAREHOUSE_ADMIN: "warehouse-admin"
+};
+const groups = {
+	platformStaff: [roles.ADMIN, roles.SUPERADMIN],
+	adminOnly: [roles.ADMIN, roles.SUPERADMIN],
+	superadminOnly: [roles.SUPERADMIN],
+	storeAdmin: [
+		roles.SUPERADMIN,
+		roles.ADMIN,
+		roles.STORE_MANAGER,
+		roles.WAREHOUSE_ADMIN,
+		roles.FINANCE_ADMIN
+	],
+	storeStaff: [
+		roles.SUPERADMIN,
+		roles.ADMIN,
+		roles.STORE_MANAGER,
+		roles.STORE_STAFF
+	],
+	financeStaff: [
+		roles.SUPERADMIN,
+		roles.ADMIN,
+		roles.FINANCE_ADMIN,
+		roles.FINANCE_MANAGER
+	],
+	warehouseStaff: [
+		roles.SUPERADMIN,
+		roles.ADMIN,
+		roles.WAREHOUSE_ADMIN,
+		roles.WAREHOUSE_STAFF
+	],
+	inventoryStaff: [
+		roles.SUPERADMIN,
+		roles.ADMIN,
+		roles.WAREHOUSE_ADMIN,
+		roles.WAREHOUSE_STAFF,
+		roles.STORE_MANAGER,
+		roles.STORE_STAFF
+	]
+};
+/** Branch-level roles (Better Auth org membership) */
+const branchRoles = {
+	BRANCH_MANAGER: "branch_manager",
+	INVENTORY_STAFF: "inventory_staff",
+	CASHIER: "cashier",
+	STOCK_RECEIVER: "stock_receiver",
+	STOCK_REQUESTER: "stock_requester",
+	VIEWER: "viewer"
+};
+
+//#endregion
+export { branchRoles, groups, roles };

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

@@ -0,0 +1,57 @@
+import { ApiResponse, BaseApi, RequestOptions } from "../../core/api-factory.js";
+import { Branch, CreateBranchPayload, UpdateBranchPayload } from "../types/branch.js";
+
+//#region src/platform/api/branch.d.ts
+type FetchOptions = Omit<RequestOptions, 'token' | 'organizationId'>;
+declare class BranchApi extends BaseApi<Branch, CreateBranchPayload, UpdateBranchPayload> {
+  constructor(config?: {});
+  /**
+   * Get branch by code
+   * GET /branches/code/:code
+   *
+   * @example
+   * branchApi.getByCode({ token, code: 'DHK-1' })
+   */
+  getByCode({
+    token,
+    code,
+    options
+  }: {
+    token: string;
+    code: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Branch>>;
+  /**
+   * Get default branch (auto-creates if none exists)
+   * GET /branches/default
+   *
+   * @example
+   * branchApi.getDefault({ token })
+   */
+  getDefault({
+    token,
+    options
+  }: {
+    token: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Branch>>;
+  /**
+   * Set a branch as the default
+   * POST /branches/:id/set-default
+   *
+   * @example
+   * branchApi.setDefault({ token, id: '507f1f77bcf86cd799439011' })
+   */
+  setDefault({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Branch>>;
+}
+declare const branchApi: BranchApi;
+//#endregion
+export { BranchApi, branchApi };

package/dist/platform/api/branch.js

@@ -0,0 +1,73 @@
+import { handleApiRequest } from "../../core/api-handler.js";
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/platform/api/branch.ts
+/**
+* Branch API - CRUD + Custom Endpoints
+*
+* Standard CRUD (inherited from BaseApi):
+* - getAll({ token, params }) - list with filtering/pagination
+* - getById({ token, id }) - get by ID
+* - create({ token, data }) - create (admin only)
+* - update({ token, id, data }) - update (admin only)
+* - delete({ token, id }) - delete (admin only)
+*
+* Custom endpoints:
+* - getByCode({ token, code }) - GET /branches/code/:code
+* - getDefault({ token }) - GET /branches/default (auto-creates if none)
+* - setDefault({ token, id }) - POST /branches/:id/set-default
+*
+* For active branches: getAll({ token, params: { isActive: true } })
+*/
+var BranchApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("branches", config);
+	}
+	/**
+	* Get branch by code
+	* GET /branches/code/:code
+	*
+	* @example
+	* branchApi.getByCode({ token, code: 'DHK-1' })
+	*/
+	async getByCode({ token, code, options = {} }) {
+		if (!code) throw new Error("Branch code is required");
+		return handleApiRequest("GET", `${this.baseUrl}/code/${code}`, {
+			token,
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Get default branch (auto-creates if none exists)
+	* GET /branches/default
+	*
+	* @example
+	* branchApi.getDefault({ token })
+	*/
+	async getDefault({ token, options = {} }) {
+		return handleApiRequest("GET", `${this.baseUrl}/default`, {
+			token,
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Set a branch as the default
+	* POST /branches/:id/set-default
+	*
+	* @example
+	* branchApi.setDefault({ token, id: '507f1f77bcf86cd799439011' })
+	*/
+	async setDefault({ token, id, options = {} }) {
+		if (!id) throw new Error("Branch ID is required");
+		return handleApiRequest("POST", `${this.baseUrl}/${id}/set-default`, {
+			token,
+			...options
+		});
+	}
+};
+const branchApi = new BranchApi();
+
+//#endregion
+export { BranchApi, branchApi };

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

@@ -0,0 +1,67 @@
+import { ApiResponse, BaseApi } from "../../core/api-factory.js";
+import { PlatformConfig, UpdatePlatformConfigPayload } from "../types/config.js";
+
+//#region src/platform/api/config.d.ts
+declare class PlatformConfigApi extends BaseApi {
+  constructor();
+  /**
+   * Get platform configuration.
+   * Public without token (cached 1hr), authenticated with token (no-store).
+   */
+  getConfig({
+    token,
+    select
+  }?: {
+    token?: string | null;
+    select?: string | null;
+  }): Promise<ApiResponse<PlatformConfig>>;
+  /** PATCH /platform/config — Update (admin only) */
+  updateConfig({
+    data
+  }: {
+    data: UpdatePlatformConfigPayload;
+  }): Promise<ApiResponse<PlatformConfig>>;
+  /** Convenience: get payment methods only */
+  getPaymentMethods({
+    token
+  }?: {
+    token?: string | null;
+  }): Promise<ApiResponse<Pick<PlatformConfig, 'paymentMethods'>>>;
+  /** Convenience: get checkout settings */
+  getCheckoutSettings({
+    token
+  }?: {
+    token?: string | null;
+  }): Promise<ApiResponse<Pick<PlatformConfig, 'checkout'>>>;
+  /** Convenience: get delivery zones */
+  getDeliveryZones({
+    token
+  }?: {
+    token?: string | null;
+  }): Promise<ApiResponse<Pick<PlatformConfig, 'checkout'>>>;
+  /** Convenience: get VAT config */
+  getVatConfig({
+    token
+  }?: {
+    token?: string | null;
+  }): Promise<ApiResponse<Pick<PlatformConfig, 'vat'>>>;
+  /** Convenience: get membership config */
+  getMembershipConfig({
+    token
+  }?: {
+    token?: string | null;
+  }): Promise<ApiResponse<Pick<PlatformConfig, 'membership'>>>;
+  /** GET /platform/permissions/matrix — Get RBAC permission matrix (authenticated) */
+  getPermissionMatrix(): Promise<ApiResponse<PermissionMatrix>>;
+}
+interface PermissionEntry {
+  type: 'public' | 'authenticated' | 'roles';
+  roles: string[];
+}
+interface PermissionMatrix {
+  roles: string[];
+  modules: Record<string, Record<string, PermissionEntry>>;
+}
+declare const platformConfigApi: PlatformConfigApi;
+//#endregion
+export { PermissionEntry, PermissionMatrix, PlatformConfigApi, platformConfigApi };

package/dist/platform/api/config.js

@@ -0,0 +1,83 @@
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/platform/api/config.ts
+/**
+* Platform Configuration API
+*
+* Singleton resource — all platform-wide settings.
+*
+* Endpoints:
+* - GET  /api/v1/platform/config — Get config (supports ?select=field1,field2)
+* - PATCH /api/v1/platform/config — Update config (admin only)
+*/
+var PlatformConfigApi = class extends BaseApi {
+	constructor() {
+		super("platform");
+	}
+	/**
+	* Get platform configuration.
+	* Public without token (cached 1hr), authenticated with token (no-store).
+	*/
+	async getConfig({ token, select } = {}) {
+		const params = select ? { select } : void 0;
+		return this.request("GET", `${this.baseUrl}/config`, {
+			token: token ?? void 0,
+			params,
+			options: {
+				cache: token ? "no-store" : "force-cache",
+				revalidate: token ? void 0 : 3600,
+				tags: ["platform-config"]
+			}
+		});
+	}
+	/** PATCH /platform/config — Update (admin only) */
+	async updateConfig({ data }) {
+		return this.request("PATCH", `${this.baseUrl}/config`, {
+			data,
+			options: { tags: ["platform-config"] }
+		});
+	}
+	/** Convenience: get payment methods only */
+	async getPaymentMethods({ token } = {}) {
+		return this.getConfig({
+			token,
+			select: "paymentMethods"
+		});
+	}
+	/** Convenience: get checkout settings */
+	async getCheckoutSettings({ token } = {}) {
+		return this.getConfig({
+			token,
+			select: "checkout"
+		});
+	}
+	/** Convenience: get delivery zones */
+	async getDeliveryZones({ token } = {}) {
+		return this.getConfig({
+			token,
+			select: "checkout"
+		});
+	}
+	/** Convenience: get VAT config */
+	async getVatConfig({ token } = {}) {
+		return this.getConfig({
+			token,
+			select: "vat"
+		});
+	}
+	/** Convenience: get membership config */
+	async getMembershipConfig({ token } = {}) {
+		return this.getConfig({
+			token,
+			select: "membership"
+		});
+	}
+	/** GET /platform/permissions/matrix — Get RBAC permission matrix (authenticated) */
+	async getPermissionMatrix() {
+		return this.request("GET", `${this.baseUrl}/permissions/matrix`, { options: { cache: "no-store" } });
+	}
+};
+const platformConfigApi = new PlatformConfigApi();
+
+//#endregion
+export { PlatformConfigApi, platformConfigApi };

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

@@ -0,0 +1,15 @@
+import { BaseApi } from "../../core/api-factory.js";
+import { FeatureManifest } from "../types/features.js";
+
+//#region src/platform/api/features.d.ts
+declare class FeaturesApi extends BaseApi<FeatureManifest> {
+  constructor();
+  /** Get feature license manifest (public, cached per deployment) */
+  getManifest(): Promise<{
+    success: boolean;
+    data: FeatureManifest;
+  }>;
+}
+declare const featuresApi: FeaturesApi;
+//#endregion
+export { FeaturesApi, featuresApi };

package/dist/platform/api/features.js

@@ -0,0 +1,20 @@
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/platform/api/features.ts
+/**
+* Features API — fetches the feature license manifest.
+* Public endpoint — no auth required.
+*/
+var FeaturesApi = class extends BaseApi {
+	constructor() {
+		super("features");
+	}
+	/** Get feature license manifest (public, cached per deployment) */
+	async getManifest() {
+		return this.request("GET", this.baseUrl);
+	}
+};
+const featuresApi = new FeaturesApi();
+
+//#endregion
+export { FeaturesApi, featuresApi };

package/dist/platform/api/index.d.ts

@@ -0,0 +1,6 @@
+import { PlatformConfigApi, platformConfigApi } from "./config.js";
+import { BranchApi, branchApi } from "./branch.js";
+import { UserApi, userApi } from "./user.js";
+import { EvaluationApi, ProgramApi, VoucherApi, evaluationApi, programApi, voucherApi } from "./promo.js";
+import { WebhookApi, webhookApi } from "./webhook.js";
+import { FeaturesApi, featuresApi } from "./features.js";