@classytic/commerce-sdk 0.1.2 → 0.2.1

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

@@ -0,0 +1,286 @@
+import { ApiResponse, BaseApi, RequestOptions } from "../../core/api-factory.js";
+import { CommitResult, CreateProgramPayload, CreateRewardPayload, CreateRulePayload, EvaluateInput, EvaluationResult, FullProgram, GenerateCodesPayload, GenerateSingleCodePayload, GiftCardBalance, Program, ProgramTransitionAction, Reward, Rule, UpdateProgramPayload, UpdateRewardPayload, UpdateRulePayload, Voucher, VoucherValidation } from "../types/promo.js";
+
+//#region src/platform/api/promo.d.ts
+type FetchOptions = Omit<RequestOptions, "token" | "organizationId">;
+declare class ProgramApi extends BaseApi<Program, CreateProgramPayload, UpdateProgramPayload> {
+  constructor(config?: {});
+  /**
+   * Get program with rules and rewards pre-loaded
+   * GET /promotions/programs/:id/full
+   */
+  getFullProgram({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<FullProgram>>;
+  /**
+   * Transition program status (Stripe action pattern)
+   * POST /promotions/programs/:id/action { action: "activate" | "pause" | "archive" }
+   */
+  transition({
+    token,
+    id,
+    action,
+    options
+  }: {
+    token: string;
+    id: string;
+    action: ProgramTransitionAction;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Program>>;
+  /**
+   * Add a rule to a program
+   * POST /promotions/programs/:id/rules
+   */
+  addRule({
+    token,
+    id,
+    data,
+    options
+  }: {
+    token: string;
+    id: string;
+    data: CreateRulePayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Rule>>;
+  /**
+   * Update a rule on a program
+   * PATCH /promotions/programs/:programId/rules/:ruleId
+   */
+  updateRule({
+    token,
+    programId,
+    ruleId,
+    data,
+    options
+  }: {
+    token: string;
+    programId: string;
+    ruleId: string;
+    data: UpdateRulePayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Rule>>;
+  /**
+   * Remove a rule from a program
+   * DELETE /promotions/programs/:programId/rules/:ruleId
+   */
+  removeRule({
+    token,
+    programId,
+    ruleId,
+    options
+  }: {
+    token: string;
+    programId: string;
+    ruleId: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<void>>;
+  /**
+   * Add a reward to a program
+   * POST /promotions/programs/:id/rewards
+   */
+  addReward({
+    token,
+    id,
+    data,
+    options
+  }: {
+    token: string;
+    id: string;
+    data: CreateRewardPayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Reward>>;
+  /**
+   * Update a reward on a program
+   * PATCH /promotions/programs/:programId/rewards/:rewardId
+   */
+  updateReward({
+    token,
+    programId,
+    rewardId,
+    data,
+    options
+  }: {
+    token: string;
+    programId: string;
+    rewardId: string;
+    data: UpdateRewardPayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Reward>>;
+  /**
+   * Remove a reward from a program
+   * DELETE /promotions/programs/:programId/rewards/:rewardId
+   */
+  removeReward({
+    token,
+    programId,
+    rewardId,
+    options
+  }: {
+    token: string;
+    programId: string;
+    rewardId: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<void>>;
+}
+declare class VoucherApi {
+  private baseUrl;
+  /**
+   * Generate batch voucher codes
+   * POST /promotions/vouchers/generate
+   */
+  generateCodes({
+    token,
+    data,
+    options
+  }: {
+    token: string;
+    data: GenerateCodesPayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Voucher[]>>;
+  /**
+   * Generate a single voucher code (custom or auto-generated)
+   * POST /promotions/vouchers/generate-single
+   */
+  generateSingle({
+    token,
+    data,
+    options
+  }: {
+    token: string;
+    data: GenerateSingleCodePayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Voucher>>;
+  /**
+   * Validate a voucher code
+   * POST /promotions/vouchers/validate/:code
+   */
+  validateCode({
+    token,
+    code,
+    options
+  }: {
+    token: string;
+    code: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<VoucherValidation>>;
+  /**
+   * Get voucher by ID
+   * GET /promotions/vouchers/:id
+   */
+  getById({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Voucher>>;
+  /**
+   * Get voucher by code
+   * GET /promotions/vouchers/code/:code
+   */
+  getByCode({
+    token,
+    code,
+    options
+  }: {
+    token: string;
+    code: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Voucher>>;
+  /**
+   * Cancel a voucher
+   * POST /promotions/vouchers/:id/cancel
+   */
+  cancel({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Voucher>>;
+  /**
+   * Get gift card balance
+   * GET /promotions/vouchers/balance/:code
+   */
+  getBalance({
+    token,
+    code,
+    options
+  }: {
+    token: string;
+    code: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<GiftCardBalance>>;
+}
+declare class EvaluationApi {
+  private baseUrl;
+  /**
+   * Preview evaluation (dry-run, no side effects)
+   * POST /promotions/evaluate/preview
+   */
+  preview({
+    token,
+    data,
+    options
+  }: {
+    token: string;
+    data: EvaluateInput;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<EvaluationResult>>;
+  /**
+   * Evaluate cart (reserves usage counts)
+   * POST /promotions/evaluate
+   */
+  evaluate({
+    token,
+    data,
+    options
+  }: {
+    token: string;
+    data: EvaluateInput;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<EvaluationResult>>;
+  /**
+   * Commit evaluation to an order
+   * POST /promotions/evaluate/:evaluationId/commit
+   */
+  commit({
+    token,
+    evaluationId,
+    orderId,
+    options
+  }: {
+    token: string;
+    evaluationId: string;
+    orderId: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<CommitResult>>;
+  /**
+   * Rollback an uncommitted evaluation
+   * POST /promotions/evaluate/:evaluationId/rollback
+   */
+  rollback({
+    token,
+    evaluationId,
+    options
+  }: {
+    token: string;
+    evaluationId: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<void>>;
+}
+declare const programApi: ProgramApi;
+declare const voucherApi: VoucherApi;
+declare const evaluationApi: EvaluationApi;
+//#endregion
+export { EvaluationApi, ProgramApi, VoucherApi, evaluationApi, programApi, voucherApi };

package/dist/platform/api/promo.js

@@ -0,0 +1,276 @@
+import { handleApiRequest } from "../../core/api-handler.js";
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/platform/api/promo.ts
+/**
+* Promo API — Programs, Vouchers, Evaluation
+*
+* Three API classes covering the full @classytic/promo engine:
+*
+* ProgramApi (extends BaseApi):
+* - Standard CRUD for programs
+* - getFullProgram: program + rules + rewards in one call
+* - transition: activate / pause / archive (Stripe action pattern)
+* - addRule / updateRule / removeRule
+* - addReward / updateReward / removeReward
+*
+* VoucherApi (standalone):
+* - generateCodes: batch code generation
+* - generateSingle: single code (custom or auto)
+* - validateCode: check if code is valid
+* - getById / getByCode / cancel
+*
+* EvaluationApi (standalone):
+* - preview: dry-run evaluation (isPreview=true)
+* - evaluate: real evaluation (reserves usage)
+* - commit: finalize evaluation to an order
+* - rollback: undo an uncommitted evaluation
+*/
+var ProgramApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("promotions/programs", config);
+	}
+	/**
+	* Get program with rules and rewards pre-loaded
+	* GET /promotions/programs/:id/full
+	*/
+	async getFullProgram({ token, id, options = {} }) {
+		if (!id) throw new Error("Program ID is required");
+		return handleApiRequest("GET", `${this.baseUrl}/${id}/full`, {
+			token,
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Transition program status (Stripe action pattern)
+	* POST /promotions/programs/:id/action { action: "activate" | "pause" | "archive" }
+	*/
+	async transition({ token, id, action, options = {} }) {
+		if (!id) throw new Error("Program ID is required");
+		return handleApiRequest("POST", `${this.baseUrl}/${id}/action`, {
+			token,
+			body: { action },
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Add a rule to a program
+	* POST /promotions/programs/:id/rules
+	*/
+	async addRule({ token, id, data, options = {} }) {
+		if (!id) throw new Error("Program ID is required");
+		return handleApiRequest("POST", `${this.baseUrl}/${id}/rules`, {
+			token,
+			body: data,
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Update a rule on a program
+	* PATCH /promotions/programs/:programId/rules/:ruleId
+	*/
+	async updateRule({ token, programId, ruleId, data, options = {} }) {
+		if (!programId) throw new Error("Program ID is required");
+		if (!ruleId) throw new Error("Rule ID is required");
+		return handleApiRequest("PATCH", `${this.baseUrl}/${programId}/rules/${ruleId}`, {
+			token,
+			body: data,
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Remove a rule from a program
+	* DELETE /promotions/programs/:programId/rules/:ruleId
+	*/
+	async removeRule({ token, programId, ruleId, options = {} }) {
+		if (!programId) throw new Error("Program ID is required");
+		if (!ruleId) throw new Error("Rule ID is required");
+		return handleApiRequest("DELETE", `${this.baseUrl}/${programId}/rules/${ruleId}`, {
+			token,
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Add a reward to a program
+	* POST /promotions/programs/:id/rewards
+	*/
+	async addReward({ token, id, data, options = {} }) {
+		if (!id) throw new Error("Program ID is required");
+		return handleApiRequest("POST", `${this.baseUrl}/${id}/rewards`, {
+			token,
+			body: data,
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Update a reward on a program
+	* PATCH /promotions/programs/:programId/rewards/:rewardId
+	*/
+	async updateReward({ token, programId, rewardId, data, options = {} }) {
+		if (!programId) throw new Error("Program ID is required");
+		if (!rewardId) throw new Error("Reward ID is required");
+		return handleApiRequest("PATCH", `${this.baseUrl}/${programId}/rewards/${rewardId}`, {
+			token,
+			body: data,
+			cache: this.config.cache,
+			...options
+		});
+	}
+	/**
+	* Remove a reward from a program
+	* DELETE /promotions/programs/:programId/rewards/:rewardId
+	*/
+	async removeReward({ token, programId, rewardId, options = {} }) {
+		if (!programId) throw new Error("Program ID is required");
+		if (!rewardId) throw new Error("Reward ID is required");
+		return handleApiRequest("DELETE", `${this.baseUrl}/${programId}/rewards/${rewardId}`, {
+			token,
+			cache: this.config.cache,
+			...options
+		});
+	}
+};
+var VoucherApi = class {
+	constructor() {
+		this.baseUrl = "promotions/vouchers";
+	}
+	/**
+	* Generate batch voucher codes
+	* POST /promotions/vouchers/generate
+	*/
+	async generateCodes({ token, data, options = {} }) {
+		return handleApiRequest("POST", `${this.baseUrl}/generate`, {
+			token,
+			body: data,
+			...options
+		});
+	}
+	/**
+	* Generate a single voucher code (custom or auto-generated)
+	* POST /promotions/vouchers/generate-single
+	*/
+	async generateSingle({ token, data, options = {} }) {
+		return handleApiRequest("POST", `${this.baseUrl}/generate-single`, {
+			token,
+			body: data,
+			...options
+		});
+	}
+	/**
+	* Validate a voucher code
+	* POST /promotions/vouchers/validate/:code
+	*/
+	async validateCode({ token, code, options = {} }) {
+		if (!code) throw new Error("Voucher code is required");
+		return handleApiRequest("POST", `${this.baseUrl}/validate/${encodeURIComponent(code)}`, {
+			token,
+			...options
+		});
+	}
+	/**
+	* Get voucher by ID
+	* GET /promotions/vouchers/:id
+	*/
+	async getById({ token, id, options = {} }) {
+		if (!id) throw new Error("Voucher ID is required");
+		return handleApiRequest("GET", `${this.baseUrl}/${id}`, {
+			token,
+			...options
+		});
+	}
+	/**
+	* Get voucher by code
+	* GET /promotions/vouchers/code/:code
+	*/
+	async getByCode({ token, code, options = {} }) {
+		if (!code) throw new Error("Voucher code is required");
+		return handleApiRequest("GET", `${this.baseUrl}/code/${encodeURIComponent(code)}`, {
+			token,
+			...options
+		});
+	}
+	/**
+	* Cancel a voucher
+	* POST /promotions/vouchers/:id/cancel
+	*/
+	async cancel({ token, id, options = {} }) {
+		if (!id) throw new Error("Voucher ID is required");
+		return handleApiRequest("POST", `${this.baseUrl}/${id}/cancel`, {
+			token,
+			...options
+		});
+	}
+	/**
+	* Get gift card balance
+	* GET /promotions/vouchers/balance/:code
+	*/
+	async getBalance({ token, code, options = {} }) {
+		if (!code) throw new Error("Gift card code is required");
+		return handleApiRequest("GET", `${this.baseUrl}/balance/${encodeURIComponent(code)}`, {
+			token,
+			...options
+		});
+	}
+};
+var EvaluationApi = class {
+	constructor() {
+		this.baseUrl = "promotions/evaluate";
+	}
+	/**
+	* Preview evaluation (dry-run, no side effects)
+	* POST /promotions/evaluate/preview
+	*/
+	async preview({ token, data, options = {} }) {
+		return handleApiRequest("POST", `${this.baseUrl}/preview`, {
+			token,
+			body: data,
+			...options
+		});
+	}
+	/**
+	* Evaluate cart (reserves usage counts)
+	* POST /promotions/evaluate
+	*/
+	async evaluate({ token, data, options = {} }) {
+		return handleApiRequest("POST", this.baseUrl, {
+			token,
+			body: data,
+			...options
+		});
+	}
+	/**
+	* Commit evaluation to an order
+	* POST /promotions/evaluate/:evaluationId/commit
+	*/
+	async commit({ token, evaluationId, orderId, options = {} }) {
+		if (!evaluationId) throw new Error("Evaluation ID is required");
+		return handleApiRequest("POST", `${this.baseUrl}/${evaluationId}/commit`, {
+			token,
+			body: { orderId },
+			...options
+		});
+	}
+	/**
+	* Rollback an uncommitted evaluation
+	* POST /promotions/evaluate/:evaluationId/rollback
+	*/
+	async rollback({ token, evaluationId, options = {} }) {
+		if (!evaluationId) throw new Error("Evaluation ID is required");
+		return handleApiRequest("POST", `${this.baseUrl}/${evaluationId}/rollback`, {
+			token,
+			...options
+		});
+	}
+};
+const programApi = new ProgramApi();
+const voucherApi = new VoucherApi();
+const evaluationApi = new EvaluationApi();
+
+//#endregion
+export { EvaluationApi, ProgramApi, VoucherApi, evaluationApi, programApi, voucherApi };

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

@@ -0,0 +1,10 @@
+import { BaseApi } from "../../core/api-factory.js";
+import { CreateUserPayload, UpdateUserPayload, User } from "../types/user.js";
+
+//#region src/platform/api/user.d.ts
+declare class UserApi extends BaseApi<User, CreateUserPayload, UpdateUserPayload> {
+  constructor(config?: {});
+}
+declare const userApi: UserApi;
+//#endregion
+export { UserApi, userApi };

package/dist/platform/api/user.js

@@ -0,0 +1,29 @@
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/platform/api/user.ts
+/**
+* User API - Admin User Management (CRUD)
+*
+* Standard CRUD (inherited from BaseApi):
+* - getAll({ token, params }) - list users with filtering/pagination
+* - getById({ token, id }) - get user by ID
+* - create({ token, data }) - create user (admin only)
+* - update({ token, id, data }) - update user (admin only)
+* - delete({ token, id }) - delete user (admin only)
+*
+* Query examples:
+* - List all users: getAll({ token, params: { page: 1, limit: 10 } })
+* - Filter by role: getAll({ token, params: { roles: 'admin' } })
+* - Search by name: getAll({ token, params: { 'name[contains]': 'john' } })
+* - Filter by branch: getAll({ token, params: { 'branches.branchId': 'branch_123' } })
+* - Active users only: getAll({ token, params: { isActive: true } })
+*/
+var UserApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("users", config);
+	}
+};
+const userApi = new UserApi();
+
+//#endregion
+export { UserApi, userApi };

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

@@ -0,0 +1,102 @@
+import { ApiResponse } from "../../core/api-factory.js";
+import { ManualRejectResponseData, ManualVerifyResponseData } from "../types/webhook.js";
+
+//#region src/platform/api/webhook.d.ts
+type FetchOptions = Omit<RequestInit, 'body' | 'method'>;
+declare class WebhookApi {
+  private baseUrl;
+  constructor();
+  /**
+   * Verify a manual payment (superadmin only)
+   * POST /webhooks/payments/manual/verify
+   *
+   * Flow:
+   * 1. Customer places order with manual payment (cash, bKash, Nagad, bank)
+   * 2. Customer pays and provides transaction reference
+   * 3. Admin verifies payment via this endpoint
+   * 4. Transaction status -> 'verified'
+   * 5. Order payment status -> 'verified', order status -> 'confirmed'
+   *
+   * @param params.transactionId - Transaction ID to verify
+   * @param params.notes - Optional verification notes
+   * @param params.token - Auth token (superadmin required)
+   * @param params.options - Additional fetch options
+   * @returns Verification result with transaction details
+   *
+   * @example
+   * ```typescript
+   * const result = await webhookApi.verifyPayment({
+   *   token: adminToken,
+   *   transactionId: '507f1f77bcf86cd799439011',
+   *   notes: 'Verified bKash TrxID via app',
+   * });
+   * ```
+   */
+  verifyPayment({
+    token,
+    transactionId,
+    notes,
+    options
+  }: {
+    token: string;
+    transactionId: string;
+    notes?: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<ManualVerifyResponseData>>;
+  /**
+   * Reject a manual payment (superadmin only)
+   * POST /webhooks/payments/manual/reject
+   *
+   * Flow:
+   * 1. Customer claims to have paid but admin finds issue
+   * 2. Admin rejects payment with reason via this endpoint
+   * 3. Transaction status -> 'failed', failureReason recorded
+   * 4. Order payment status -> 'failed'
+   *
+   * Common rejection reasons:
+   * - Invalid transaction reference
+   * - Amount mismatch
+   * - Duplicate claim
+   * - Suspected fraud
+   * - Payment not received
+   *
+   * @param params.transactionId - Transaction ID to reject
+   * @param params.reason - Rejection reason (required)
+   * @param params.token - Auth token (superadmin required)
+   * @param params.options - Additional fetch options
+   * @returns Rejection result with failure details
+   *
+   * @example
+   * ```typescript
+   * const result = await webhookApi.rejectPayment({
+   *   token: adminToken,
+   *   transactionId: '507f1f77bcf86cd799439011',
+   *   reason: 'Invalid bKash TrxID - no matching transaction found',
+   * });
+   * ```
+   */
+  rejectPayment({
+    token,
+    transactionId,
+    reason,
+    options
+  }: {
+    token: string;
+    transactionId: string;
+    reason: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<ManualRejectResponseData>>;
+  /**
+   * Alias for verifyPayment - more explicit naming
+   * @deprecated Use verifyPayment instead
+   */
+  verifyManualPayment(params: Parameters<typeof this.verifyPayment>[0]): Promise<ApiResponse<ManualVerifyResponseData>>;
+  /**
+   * Alias for rejectPayment - more explicit naming
+   * @deprecated Use rejectPayment instead
+   */
+  rejectManualPayment(params: Parameters<typeof this.rejectPayment>[0]): Promise<ApiResponse<ManualRejectResponseData>>;
+}
+declare const webhookApi: WebhookApi;
+//#endregion
+export { WebhookApi, webhookApi };