@deliverart/sdk-js-stats 2.9.0

package/README.md

@@ -0,0 +1,263 @@
+# @deliverart/sdk-js-stats
+
+Statistics and analytics package for the DeliverArt JavaScript SDK.
+
+## Installation
+
+```bash
+npm install @deliverart/sdk-js-stats @deliverart/sdk-js-core
+# or
+pnpm add @deliverart/sdk-js-stats @deliverart/sdk-js-core
+# or
+yarn add @deliverart/sdk-js-stats @deliverart/sdk-js-core
+```
+
+## Exported Types
+
+### Models
+
+#### CourierDailyStats
+```typescript
+interface CourierDailyStats {
+  id: string
+  day: string
+  pointOfSale?: string
+  courierUser?: string
+  source: OrderSource
+  partner: OrderPartner | null
+  paymentMethod: PaymentMethod | null
+  ordersCount: number
+  totalCountableItems: number
+  totalAmount: string
+  calculatedAt: string
+}
+```
+Daily statistics for courier deliveries.
+
+**Properties:**
+- `id: string` - Unique statistics identifier
+- `day: string` - Date in YYYY-MM-DD format
+- `pointOfSale?: string` - Point of sale IRI (optional)
+- `courierUser?: string` - Courier user IRI (optional)
+- `source: OrderSource` - Order source ('application', 'ecommerce', 'partner')
+- `partner: OrderPartner | null` - Partner identifier (nullable)
+- `paymentMethod: PaymentMethod | null` - Payment method used (nullable)
+- `ordersCount: number` - Total number of orders
+- `totalCountableItems: number` - Total number of countable items
+- `totalAmount: string` - Total amount (monetary value as string)
+- `calculatedAt: string` - Calculation timestamp (ISO 8601)
+
+#### CourierDailyStatsQueryParams
+```typescript
+interface CourierDailyStatsQueryParams {
+  pointOfSale?: string | string[]
+  courierUser?: string | string[]
+  partner?: OrderPartner | OrderPartner[]
+  source?: OrderSource | OrderSource[]
+  paymentMethod?: PaymentMethod | PaymentMethod[]
+  'day[before]'?: string
+  'day[strictly_before]'?: string
+  'day[after]'?: string
+  'day[strictly_after]'?: string
+  'calculatedAt[before]'?: string
+  'calculatedAt[strictly_before]'?: string
+  'calculatedAt[after]'?: string
+  'calculatedAt[strictly_after]'?: string
+  'order[day]'?: 'asc' | 'desc'
+  'order[calculatedAt]'?: 'asc' | 'desc'
+  page?: number
+}
+```
+Query parameters for filtering and sorting courier daily statistics.
+
+**Filter Parameters:**
+- `pointOfSale?: string | string[]` - Filter by point of sale IRI(s)
+- `courierUser?: string | string[]` - Filter by courier user IRI(s)
+- `partner?: OrderPartner | OrderPartner[]` - Filter by partner(s)
+- `source?: OrderSource | OrderSource[]` - Filter by order source(s)
+- `paymentMethod?: PaymentMethod | PaymentMethod[]` - Filter by payment method(s)
+
+**Date Range Filters:**
+- `day[before]?: string` - Days before (inclusive)
+- `day[strictly_before]?: string` - Days strictly before (exclusive)
+- `day[after]?: string` - Days after (inclusive)
+- `day[strictly_after]?: string` - Days strictly after (exclusive)
+
+**Calculation Date Range Filters:**
+- `calculatedAt[before]?: string` - Calculated before (inclusive)
+- `calculatedAt[strictly_before]?: string` - Calculated strictly before (exclusive)
+- `calculatedAt[after]?: string` - Calculated after (inclusive)
+- `calculatedAt[strictly_after]?: string` - Calculated strictly after (exclusive)
+
+**Sort Parameters:**
+- `order[day]?: 'asc' | 'desc'` - Sort by day
+- `order[calculatedAt]?: 'asc' | 'desc'` - Sort by calculation date
+
+**Pagination:**
+- `page?: number` - Page number (default: 1)
+
+### IRI Types
+
+#### CourierDailyStatsIri
+```typescript
+type CourierDailyStatsIri = string
+```
+Courier daily statistics IRI type (format: `/courier_daily_stats/:id`)
+
+## Available Requests
+
+### Courier Daily Statistics
+
+#### GetCourierDailyStats
+Retrieve a list of courier daily statistics with filtering and pagination.
+
+```typescript
+import { GetCourierDailyStats } from '@deliverart/sdk-js-stats';
+
+const stats = await sdk.call(new GetCourierDailyStats({
+  query: {
+    'day[after]': '2024-01-01',
+    'day[before]': '2024-12-31',
+    source: 'application',
+    'order[day]': 'desc',
+    page: 1
+  }
+}));
+```
+
+**Query Parameters:**
+See `CourierDailyStatsQueryParams` above for all available filters.
+
+**Response:**
+Returns a paginated list of `CourierDailyStats` objects.
+
+---
+
+#### GetCourierDailyStatsDetails
+Retrieve detailed information for a specific courier daily statistics entry.
+
+```typescript
+import { GetCourierDailyStatsDetails } from '@deliverart/sdk-js-stats';
+
+const stats = await sdk.call(new GetCourierDailyStatsDetails('stats-123'));
+```
+
+**Parameters:**
+- `courierDailyStatsId: string` (required) - The statistics ID
+
+**Response:**
+Returns a single `CourierDailyStats` object.
+
+---
+
+#### GetCourierDailyStatsFromPointOfSale
+Retrieve courier daily statistics for a specific point of sale.
+
+```typescript
+import { GetCourierDailyStatsFromPointOfSale } from '@deliverart/sdk-js-stats';
+
+const stats = await sdk.call(new GetCourierDailyStatsFromPointOfSale('pos-123', {
+  query: {
+    'day[after]': '2024-01-01',
+    source: 'application',
+    page: 1
+  }
+}));
+```
+
+**Parameters:**
+- `pointOfSaleId: string` (required) - The point of sale ID
+- `query?: CourierDailyStatsQueryParams` (optional) - Query parameters for filtering
+
+**Response:**
+Returns a paginated list of `CourierDailyStats` objects for the specified point of sale.
+
+---
+
+#### GetCourierDailyStatsFromUser
+Retrieve courier daily statistics for a specific user (courier).
+
+```typescript
+import { GetCourierDailyStatsFromUser } from '@deliverart/sdk-js-stats';
+
+const stats = await sdk.call(new GetCourierDailyStatsFromUser('user-123', {
+  query: {
+    'day[after]': '2024-01-01',
+    'day[before]': '2024-01-31',
+    'order[day]': 'asc',
+    page: 1
+  }
+}));
+```
+
+**Parameters:**
+- `userId: string` (required) - The user (courier) ID
+- `query?: CourierDailyStatsQueryParams` (optional) - Query parameters for filtering
+
+**Response:**
+Returns a paginated list of `CourierDailyStats` objects for the specified courier.
+
+---
+
+## Usage Examples
+
+### Get Statistics for a Date Range
+```typescript
+import { GetCourierDailyStats } from '@deliverart/sdk-js-stats';
+
+// Get all stats for January 2024
+const januaryStats = await sdk.call(new GetCourierDailyStats({
+  query: {
+    'day[after]': '2024-01-01',
+    'day[strictly_before]': '2024-02-01',
+    'order[day]': 'asc'
+  }
+}));
+```
+
+### Get Statistics by Point of Sale and Source
+```typescript
+import { GetCourierDailyStatsFromPointOfSale } from '@deliverart/sdk-js-stats';
+
+const posStats = await sdk.call(new GetCourierDailyStatsFromPointOfSale('pos-123', {
+  query: {
+    source: ['application', 'ecommerce'],
+    'day[after]': '2024-01-01'
+  }
+}));
+```
+
+### Get Courier Performance
+```typescript
+import { GetCourierDailyStatsFromUser } from '@deliverart/sdk-js-stats';
+
+const courierStats = await sdk.call(new GetCourierDailyStatsFromUser('courier-456', {
+  query: {
+    'day[after]': '2024-01-01',
+    'order[day]': 'desc'
+  }
+}));
+
+// Analyze courier performance
+courierStats.member.forEach(stat => {
+  console.log(`${stat.day}: ${stat.ordersCount} orders, ${stat.totalAmount} revenue`);
+});
+```
+
+### Filter by Payment Method
+```typescript
+import { GetCourierDailyStats } from '@deliverart/sdk-js-stats';
+
+const cashStats = await sdk.call(new GetCourierDailyStats({
+  query: {
+    paymentMethod: 'cash',
+    'day[after]': '2024-01-01'
+  }
+}));
+```
+
+---
+
+## License
+
+See the main SDK repository for license information.