feat: add purchase statistics endpoints and update API version to 1.3.0

Author: aeltorio

README.md

@@ -126,6 +126,10 @@ The REST API exchanges all objects in JSON format. The API provides the followin
 - **GET `/api/purchases/refunded`** - Get a list of the authenticated tester's refunded purchases - requires read:api permission
   - Optional parameters: `?page=1&limit=10&sort=date&order=desc`
   - Response: `{success: boolean, data: [{id: string, date: string, order: string, description: string, amount: number}], total: number, page: number, limit: number}`
+
+- **GET `/api/purchases/ready-to-refund`** - Get a list of purchases ready for refund (with feedback and publication) - requires read:api permission
+  - Optional parameters: `?page=1&limit=10&sort=date&order=desc`
+  - Response: `{success: boolean, data: [{id: string, date: string, order: string, description: string, amount: number, feedback: string, feedbackDate: string, publicationDate: string, publicationScreenShot: string}], total: number, page: number, limit: number}`
 
 - **GET `/api/purchase-status`** - Get the status of all purchases with feedback/publication/refund status - requires read:api permission
   - Optional parameters: `?page=1&limit=10&sort=date&order=desc&limitToNotRefunded=false`
@@ -162,6 +166,17 @@ The REST API exchanges all objects in JSON format. The API provides the followin
 - **GET `/api/refund/:id`** - Get information about a specific refund - requires read:api permission
   - Response: `{success: boolean, data: {date: string, purchase: string, refundDate: string, amount: number, transactionId?: string}}`
 
+### Statistics
+
+- **GET `/api/stats/refund-balance`** - Get balance between purchases and refunds - requires read:api permission
+  - Response: `{success: boolean, purchasedAmount: number, refundedAmount: number, balance: number}`
+
+- **GET `/api/stats/refund-delay`** - Get statistics about refund delays - requires read:api permission
+  - Response: `{success: boolean, data: [{purchaseId: string, purchaseAmount: number, refundAmount: number, delayInDays: number, purchaseDate: string, refundDate: string}], averageDelayInDays: number}`
+
+- **GET `/api/stats/purchases`** - Get purchase statistics overview - requires read:api permission
+  - Response: `{success: boolean, data: {totalPurchases: number, totalRefundedPurchases: number, totalRefundedAmount: number}}`
+
 ### Database Management
 
 - **GET `/api/backup/json`** - Backup the database - requires backup:api permission
@@ -287,5 +302,5 @@ Add a new user (Admin menu, dark mode)
 
 API  
 <img width="1124" alt="image" src="https://github.com/user-attachments/assets/cb2d57f5-d18c-481b-ba22-ee3455fbb044" />
-````
+`````
 

client/get-openapi.ts

@@ -8,13 +8,13 @@ const options = {
   format: "json",
   info: {
     title: "Feedback Flow API",
-    version: "1.2.0",
+    version: "1.3.0",
   },
   definition: {
     openapi: "3.0.0",
     info: {
       title: "Feedback Flow API",
-      version: "1.2.0",
+      version: "1.3.0",
     },
   }, // You can move properties from definition here if needed
   apis: ["../cloudflare-worker/src/routes/index.ts"], // Path to the API docs

client/public/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.0",
   "info": {
     "title": "Feedback Flow API",
-    "version": "1.2.0"
+    "version": "1.3.0"
   },
   "paths": {
     "/api/testers": {
@@ -1164,6 +1164,53 @@
         }
       }
     },
+    "/api/stats/purchases": {
+      "get": {
+        "summary": "Get purchase statistics",
+        "description": "Returns purchase statistics for the authenticated user. Requires read permission.",
+        "tags": [
+          "Statistics"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully retrieved purchase statistics",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean",
+                      "example": true
+                    },
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "totalPurchases": {
+                          "type": "integer",
+                          "example": 10
+                        },
+                        "totalRefundedPurchases": {
+                          "type": "integer",
+                          "example": 2
+                        },
+                        "totalRefundedAmount": {
+                          "type": "number",
+                          "example": 50
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Unauthorized request"
+          }
+        }
+      }
+    },
     "/api/backup/json": {
       "get": {
         "summary": "Backup database to JSON",

cloudflare-worker/src/db/d1-db.ts

@@ -30,6 +30,7 @@ import {
 	IdMapping,
 	Publication,
 	Purchase,
+	PurchasesStatisticsData,
 	Refund,
 	Tester,
 } from "../types/data";
@@ -867,6 +868,38 @@ export class CloudflareD1DB implements FeedbackFlowDB {
 				pageInfo,
 			} as PurchaseStatusResponse;
 		},
+		/**
+		 * Get some statistics of purchases for a tester
+		 * @param testerUuid UUID of the tester
+		 * @returns Promise<PurchasesStatisticsData> Statistics data for the tester's purchases
+		 */
+		getPurchaseStatistics: async (
+			testerUuid: string,
+		): Promise<PurchasesStatisticsData> => {
+			const { results } = await this.db
+				.prepare(
+					`SELECT 
+						SUM(CASE WHEN refunded = 1 THEN 1 ELSE 0 END) as nb_refunded,
+						SUM(CASE WHEN refunded = 0 THEN 1 ELSE 0 END) as nb_not_refunded,
+						SUM(CASE WHEN refunded = 0 AND id IN (SELECT purchase_id FROM feedbacks) AND id IN (SELECT purchase_id FROM publications) THEN 1 ELSE 0 END) as nb_ready_for_refund,
+						COUNT(*) as nb_total,
+						SUM(CASE WHEN refunded = 1 THEN amount ELSE 0 END) as total_refunded_amount,
+						SUM(CASE WHEN refunded = 0 THEN amount ELSE 0 END) as total_not_refunded_amount,
+						SUM(amount) as total_amount
+					FROM purchases WHERE tester_uuid = ?`
+				).bind(testerUuid)
+				.all();
+			const stats = results[0];
+			return {
+				nbRefunded: stats.nb_refunded as number,
+				nbNotRefunded: stats.nb_not_refunded as number,
+				nbReadyForRefund: stats.nb_ready_for_refund as number,
+				nbTotal: stats.nb_total as number,
+				totalRefundedAmount: stats.total_refunded_amount as number,
+				totalNotRefundedAmount: stats.total_not_refunded_amount as number,
+				totalPurchaseAmount: stats.total_amount as number,
+			} as PurchasesStatisticsData;
+		},
 	};
 
 	/**

cloudflare-worker/src/db/db.ts

@@ -29,6 +29,7 @@ import {
 	IdMapping,
 	Publication,
 	Purchase,
+	PurchasesStatisticsData,
 	Refund,
 	Tester,
 } from "../types/data";
@@ -279,6 +280,14 @@ export interface PurchasesRepository {
 		sort?: string,
 		order?: string,
 	): Promise<PurchaseStatusResponse>;
+
+	/**
+	 * Get some statistics of purchases for a tester
+	 * @param testerUuid UUID of the tester
+	 * @returns Promise<PurchasesStatisticsData> Statistics data for the tester's purchases
+	 */
+	getPurchaseStatistics(
+		testerUuid: string): Promise<PurchasesStatisticsData>;
 }
 
 export interface FeedbacksRepository {

cloudflare-worker/src/db/in-memory-db.ts

@@ -26,7 +26,7 @@
 
 import { v4 as uuidv4 } from "uuid";
 
-import { Feedback, Publication, Purchase, Refund, Tester } from "../types/data";
+import { Feedback, Publication, Purchase, Refund, Tester, PurchasesStatisticsData } from "../types/data";
 
 import { DATABASESCHEMA, DEFAULT_PAGINATION, FeedbackFlowDB, PaginatedResult, PurchaseStatus, PurchaseStatusResponse, PurchaseWithFeedback } from "./db";
 
@@ -646,6 +646,51 @@ export class InMemoryDB implements FeedbackFlowDB {
 				pageInfo,
 			};
 			return response;
+		},
+		/**
+		 * Get statistics about purchases
+		 * @param testerUuid UUID of the tester
+		 * @returns {PurchasesStatisticsData} Statistics data for the tester's purchases
+		 */
+		getPurchaseStatistics: async (testerUuid: string): Promise<PurchasesStatisticsData> => {
+			const purchases = this.data.purchases.filter(
+				(purchase) => purchase.testerUuid === testerUuid,
+			);
+
+			const totalAmount = purchases.reduce((acc, purchase) => {
+				return acc + purchase.amount;
+			}, 0);
+
+			const nbRefunded = purchases.filter((p) => p.refunded).length;
+			const nbNotRefunded = purchases.filter((p) => !p.refunded).length;
+			const nbReadyForRefund = purchases.filter(
+				(p) =>
+					!p.refunded &&
+					this.data.feedbacks.some((feedback) => feedback.purchase === p.id) &&
+					this.data.publications.some(
+						(publication) => publication.purchase === p.id,
+					),
+			).length;
+			const nbTotal = purchases.length;
+			const totalRefundedAmount = purchases
+				.filter((p) => p.refunded)
+				.reduce((acc, purchase) => {
+					return acc + purchase.amount;
+				}, 0);
+			const totalNotRefundedAmount = purchases
+				.filter((p) => !p.refunded)
+				.reduce((acc, purchase) => {
+					return acc + purchase.amount;
+				}, 0);
+			return {
+				nbRefunded,
+				nbNotRefunded,
+				nbReadyForRefund,
+				nbTotal,
+				totalRefundedAmount,
+				totalNotRefundedAmount,
+				totalPurchaseAmount: totalAmount,
+			} as PurchasesStatisticsData;
 		}
 	};
 

cloudflare-worker/src/routes/index.ts

@@ -2228,6 +2228,99 @@ const statsRoutes = (router: Router, env: Env) => {
 		},
 		env.READ_PERMISSION,
 	);
+	/**
+	 * @openapi
+	 * /api/stats/purchases:
+	 *   get:
+	 *     summary: Get purchase statistics
+	 *     description: Returns purchase statistics for the authenticated user. Requires read permission.
+	 *     tags:
+	 *       - Statistics
+	 *     responses:
+	 *       200:
+	 *         description: Successfully retrieved purchase statistics
+	 *         content:
+	 *           application/json:
+	 *             schema:
+	 *               type: object
+	 *               properties:
+	 *                 success:
+	 *                   type: boolean
+	 *                   example: true
+	 *                 data:
+	 *                   type: object
+	 *                   properties:
+	 *                     totalPurchases:
+	 *                       type: integer
+	 *                       example: 10
+	 *                     totalRefundedPurchases:
+	 *                       type: integer
+	 *                       example: 2
+	 *                     totalRefundedAmount:
+	 *                       type: number
+	 *                       example: 50.00
+	 *       403:
+	 *         description: Unauthorized request
+	 */
+	router.get("/api/stats/purchases", async () => {
+		const db = getDatabase(env);
+			
+			// Get user ID from authenticated user
+			const userId = router.jwtPayload.sub;
+			
+			if (!userId) {
+				return router.handleUnauthorizedRequest();
+			}
+			
+			// Find tester by user ID
+			const testerUuid = await db.idMappings.getTesterUuid(userId);
+			
+			if (!testerUuid) {
+				return new Response(
+					JSON.stringify({ success: false, error: "Unauthorized" }),
+					{
+						status: 403,
+						headers: {
+							...router.corsHeaders,
+							"Content-Type": "application/json",
+						},
+					},
+				);
+			}
+			try {
+				// Get purchase statistics
+				const purchaseStats = await db.purchases.getPurchaseStatistics(testerUuid);
+				
+				return new Response(
+					JSON.stringify({
+						success: true,
+						data: purchaseStats,
+					}),
+					{
+						status: 200,
+						headers: {
+							...router.corsHeaders,
+							"Content-Type": "application/json",
+						},
+					},
+				);
+			} catch (error) {
+				return new Response(
+					JSON.stringify({
+						success: false,
+						error: `Error fetching purchase statistics: ${(error as Error).message}`,
+					}),
+					{
+						status: 500,
+						headers: {
+							...router.corsHeaders,
+							"Content-Type": "application/json",
+						},
+					},
+				);
+			}
+
+	},env.READ_PERMISSION);
 };
 
 /**

cloudflare-worker/src/types/data.ts

@@ -316,3 +316,19 @@ export interface RefundBalanceResponse {
   refundedAmount: number;
   balance: number;
 }
+
+export interface PurchasesStatisticsData {
+  nbRefunded: number;
+  nbNotRefunded: number;
+  nbReadyForRefund: number;
+  nbTotal: number;
+  totalRefundedAmount: number;
+  totalNotRefundedAmount: number;
+  totalPurchaseAmount: number;
+}
+
+export interface PurchaseStatisticsResponse {
+  success: boolean;
+  data: PurchasesStatisticsData;
+  error?: string;
+}