@plyaz/types 1.38.0 → 1.38.2

package/dist/api/index.d.ts

@@ -39,6 +39,7 @@ export type * from './pubsub/types';
 export type * from './hooks/types';
 export type * from './services/types';
 export type * from './encryption/types';
+export type * from './upload';
 export type * from './endpoints/types';
 export type * from './endpoints/health/types';
 export type * from './endpoints/campaigns/types';

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

@@ -0,0 +1,212 @@
+/**
+ * Upload Types
+ * Types for upload functionality with progress tracking
+ */
+import type { RetryConfig } from '../retry';
+/**
+ * Upload error details passed to onError handler
+ */
+export interface UploadError {
+    /** Error message */
+    message: string;
+    /** HTTP status code (if available) */
+    status?: number;
+    /** HTTP status text (if available) */
+    statusText?: string;
+    /** Original error object */
+    cause?: Error;
+    /** Whether the error is retryable */
+    retryable: boolean;
+    /** Current retry attempt (0 = first attempt) */
+    attempt: number;
+    /** Maximum retry attempts configured */
+    maxAttempts: number;
+}
+/**
+ * Error handler callback for upload errors
+ */
+export type UploadErrorHandler = (error: UploadError) => void;
+/**
+ * Upload progress event data
+ */
+export interface UploadProgressEvent {
+    /** Bytes uploaded so far */
+    loaded: number;
+    /** Total bytes to upload */
+    total: number;
+    /** Percentage complete (0-100) */
+    percentage: number;
+    /** Upload speed in bytes per second */
+    speed?: number;
+    /** Estimated time remaining in seconds */
+    estimatedTimeRemaining?: number;
+}
+/**
+ * Progress callback function
+ */
+export type UploadProgressCallback = (event: UploadProgressEvent) => void;
+/**
+ * Options for uploadWithProgress function
+ */
+export interface UploadWithProgressOptions {
+    /** Target URL to upload to */
+    url: string;
+    /** Data to upload (Buffer in Node.js, Blob/ArrayBuffer in browser) */
+    data: globalThis.Buffer | Blob | ArrayBuffer | Uint8Array;
+    /** HTTP method (default: PUT) */
+    method?: 'PUT' | 'POST';
+    /** Additional headers to send (merged with global config headers if useGlobalConfig is true) */
+    headers?: Record<string, string>;
+    /** Content-Type header (default: application/octet-stream) */
+    contentType?: string;
+    /** Progress callback */
+    onProgress?: UploadProgressCallback;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Chunk size for progress reporting in bytes (default: 65536 = 64KB) */
+    chunkSize?: number;
+    /** Minimum time between progress events in ms (default: 100) */
+    throttleMs?: number;
+    /**
+     * Whether to use global API client configuration.
+     * When true, merges config from getGlobalConfig() with provided options.
+     * Affects: headers, timeout, baseURL, retry, onError, withCredentials
+     * Default: true
+     */
+    useGlobalConfig?: boolean;
+    /**
+     * Timeout in milliseconds. If not provided and useGlobalConfig is true,
+     * uses timeout from global config.
+     */
+    timeout?: number;
+    /**
+     * Base URL to prepend to relative URLs.
+     * If url starts with '/', baseURL will be prepended.
+     * If not provided and useGlobalConfig is true, uses baseURL from global config.
+     *
+     * @example
+     * ```typescript
+     * uploadWithProgress({
+     *   baseURL: 'https://api.example.com',
+     *   url: '/upload', // becomes https://api.example.com/upload
+     *   data: buffer,
+     * });
+     * ```
+     */
+    baseURL?: string;
+    /**
+     * Retry configuration for failed uploads.
+     * Set to false to disable retries.
+     * If not provided and useGlobalConfig is true, uses retry from global config.
+     *
+     * @example
+     * ```typescript
+     * uploadWithProgress({
+     *   url: 'https://api.example.com/upload',
+     *   data: buffer,
+     *   retry: {
+     *     attempts: 3,
+     *     delay: 1000,
+     *     backoff: 2,
+     *   },
+     * });
+     * ```
+     */
+    retry?: RetryConfig | false;
+    /**
+     * Error handler callback called on upload errors.
+     * Called for each error including retries.
+     * If not provided and useGlobalConfig is true, uses onError from global config.
+     */
+    onError?: UploadErrorHandler;
+    /**
+     * Include credentials (cookies) in cross-origin requests.
+     * Only applicable in browser environments.
+     * If not provided and useGlobalConfig is true, uses withCredentials from global config.
+     */
+    withCredentials?: boolean;
+}
+/**
+ * Result from uploadWithProgress function
+ */
+export interface UploadWithProgressResult {
+    /** HTTP status code */
+    status: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response body (if any) */
+    data?: string;
+    /** Response headers */
+    headers?: Record<string, string>;
+    /** Whether the upload was successful (2xx status) */
+    success: boolean;
+    /** Number of retry attempts made (0 = succeeded on first attempt) */
+    attempts?: number;
+}
+/**
+ * Upload state for tracking
+ */
+export type UploadStatus = 'pending' | 'uploading' | 'completed' | 'failed' | 'aborted';
+/**
+ * Internal upload state tracking
+ */
+export interface UploadState {
+    /** Current status */
+    status: UploadStatus;
+    /** Start time of upload */
+    startTime: number;
+    /** Bytes uploaded */
+    bytesUploaded: number;
+    /** Total bytes */
+    totalBytes: number;
+    /** Last progress update time */
+    lastProgressTime: number;
+    /** Last bytes uploaded (for speed calculation) */
+    lastBytesUploaded: number;
+    /** Error if failed */
+    error?: Error;
+}
+/**
+ * Merged configuration for upload operations
+ * Created by combining global config with per-request options
+ */
+export interface MergedUploadConfig {
+    /** Headers to send with the upload */
+    headers: Record<string, string>;
+    /** Timeout in milliseconds */
+    timeout: number;
+    /** Base URL to prepend to relative URLs */
+    baseURL?: string;
+    /** Retry configuration or false to disable */
+    retry: RetryConfig | false;
+    /** Error handler callback */
+    onError?: UploadErrorHandler;
+    /** Include credentials in cross-origin requests */
+    withCredentials: boolean;
+}
+/**
+ * Context for retry operations
+ */
+export interface RetryContext {
+    /** Merged upload configuration */
+    config: MergedUploadConfig;
+    /** Maximum number of retry attempts */
+    maxAttempts: number;
+    /** Current attempt number (0-based) */
+    attempt: number;
+}
+/**
+ * Parameters for retry error notification
+ */
+export interface RetryErrorParams {
+    /** Retry context */
+    ctx: RetryContext;
+    /** Error message */
+    message: string;
+    /** HTTP status code */
+    status?: number;
+    /** HTTP status text */
+    statusText?: string;
+    /** Original error cause */
+    cause?: Error;
+}

package/dist/payments/gateways/provider/fee/types.d.ts

@@ -1,6 +1,7 @@
 import type { CurrencyCode } from '../../../../locale/types';
 import type { PAYMENT_METHOD, PAYMENT_PROVIDER_TYPE } from '../../../provider';
-import type { Money } from '../../../transaction';
+import type { FeeBreakdown, Money } from '../../../transaction';
+import type { ProviderFeeConfiguration } from '../types';
 import type { FEE_CONTEXT, FEE_TYPE } from './enum';
 export interface CalculateFeeParams {
     amount: Money;
@@ -11,14 +12,6 @@ export interface CalculateFeeParams {
     expedite?: boolean;
     highRisk?: boolean;
 }
-export interface FeeMetadata {
-    processingRate?: number;
-    platformRate?: number;
-    crossBorderRate?: number;
-    conversionRate?: number;
-    calculatedAt: Date;
-    ruleVersion?: string;
-}
 /**
  * Unified Fee Rule
  */
@@ -36,3 +29,31 @@ export interface FeeRule<TMetadata extends object = {}> {
     maxLimit?: number;
     metadata?: TMetadata;
 }
+export type HandlerParams = CalculateFeeParams;
+export type FeeSection = Partial<{
+    processingFee: Money;
+    platformFee: Money;
+    crossBorderFee: Money;
+    currencyConversionFee: Money;
+    riskFee: Money;
+    complianceFee: Money;
+    expediteFee: Money;
+    networkFee: Money;
+    gasFee: Money;
+    chargebackFee: Money;
+    refundFee: Money;
+}>;
+export type FeeMetadata = Partial<{
+    calculatedAt: Date;
+    processingRate: number;
+    platformRate: number;
+    crossBorderRate: number;
+    conversionRate: number;
+}>;
+export interface ApplyFeeRuleType {
+    config: FeeRule;
+    params: CalculateFeeParams;
+    fees: Partial<FeeBreakdown>;
+    metadata: FeeMetadata;
+    calculation: ProviderFeeConfiguration['calculation'];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.38.0",
+  "version": "1.38.2",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",