@plyaz/types 1.15.20 → 1.16.0

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

@@ -0,0 +1,5 @@
+/**
+ * AWS API Type Definitions
+ * Types for AWS services and authentication
+ */
+export type * from './signature';

package/dist/api/aws/signature.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AWS Signature V4 Type Definitions
+ * Types for AWS authentication and signing
+ */
+/**
+ * Options for generating AWS Signature Version 4
+ */
+export interface AWSSignatureV4Options {
+    /** AWS Access Key ID */
+    accessKeyId: string;
+    /** AWS Secret Access Key */
+    secretAccessKey: string;
+    /** AWS Session Token (optional, for temporary credentials) */
+    sessionToken?: string;
+    /** AWS Region (e.g., 'us-east-1') */
+    region: string;
+    /** AWS Service name (e.g., 'cloudfront', 's3') */
+    service: string;
+    /** HTTP method (e.g., 'GET', 'POST') */
+    method: string;
+    /** Request path (e.g., '/2020-05-31/distribution/E1234/invalidation') */
+    path: string;
+    /** Query string (optional, e.g., 'key1=value1&key2=value2') */
+    queryString?: string;
+    /** Additional headers to include in signature */
+    headers: Record<string, string>;
+    /** Request body/payload */
+    payload: string;
+    /** ISO 8601 timestamp (optional, auto-generated if not provided) */
+    timestamp?: string;
+    /** Host header (e.g., 'cloudfront.amazonaws.com') - Required for AWS Signature V4 */
+    host: string;
+}
+/**
+ * Result of AWS Signature V4 generation
+ */
+export interface AWSSignatureV4Result {
+    /** Signed headers including Host, X-Amz-Date, and optionally X-Amz-Security-Token */
+    headers: Record<string, string>;
+    /** Authorization header value with signature */
+    authorization: string;
+}

package/dist/api/endpoints/cdn/endpoints.d.ts

@@ -0,0 +1,57 @@
+/**
+ * CDN Provider Endpoint Type Definitions
+ *
+ * This file contains endpoint type definitions for CDN cache invalidation operations:
+ * - Cloudflare cache purging
+ * - AWS CloudFront invalidation
+ * - Fastly URL purging
+ *
+ * @see ./types.ts
+ */
+import type { Endpoint, Req } from 'fetchff';
+import type { CloudflarePurgeCacheRequest, CloudflarePurgeCacheResponse, CloudFrontInvalidationRequest, CloudFrontInvalidationResponse, FastlyPurgeUrlRequest, FastlyPurgeUrlResponse } from './types';
+/**
+ * Cloudflare CDN endpoint types
+ * Cache purging endpoints for Cloudflare
+ */
+export interface CloudflareEndpointTypes {
+    /**
+     * POST /zones/:zoneId/purge_cache - Purge files from cache
+     * Zone-based cache purging with URL list
+     */
+    cloudflarePurgeCache: Endpoint<Req<CloudflarePurgeCacheResponse, CloudflarePurgeCacheRequest>>;
+}
+/**
+ * CloudFront CDN endpoint types
+ * Note: CloudFront uses AWS SDK, not REST endpoints
+ */
+export interface CloudFrontEndpointTypes {
+    /**
+     * CloudFront CreateInvalidation (AWS SDK)
+     * Creates invalidation batch for specified paths
+     */
+    cloudFrontCreateInvalidation: Endpoint<Req<CloudFrontInvalidationResponse, CloudFrontInvalidationRequest>>;
+}
+/**
+ * Fastly CDN endpoint types
+ * URL-based cache purging for Fastly
+ */
+export interface FastlyEndpointTypes {
+    /**
+     * POST /service/:serviceId/purge/:url - Purge single URL
+     * Instant soft-purge of specific URL
+     */
+    fastlyPurgeUrl: Endpoint<Req<FastlyPurgeUrlResponse, FastlyPurgeUrlRequest>>;
+}
+/**
+ * All CDN endpoint types combined
+ */
+export interface CDNEndpointTypes extends CloudflareEndpointTypes, CloudFrontEndpointTypes, FastlyEndpointTypes {
+}
+/**
+ * Type guards to check if an endpoint key is valid
+ */
+export type CloudflareEndpointKey = keyof CloudflareEndpointTypes;
+export type CloudFrontEndpointKey = keyof CloudFrontEndpointTypes;
+export type FastlyEndpointKey = keyof FastlyEndpointTypes;
+export type CDNEndpointKey = keyof CDNEndpointTypes;

package/dist/api/endpoints/cdn/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CDN Provider Types Export
+ * Aggregates all CDN-related type definitions
+ */
+export type { CloudflareEndpointTypes, CloudFrontEndpointTypes, FastlyEndpointTypes, CDNEndpointTypes, CloudflareEndpointKey, CloudFrontEndpointKey, FastlyEndpointKey, CDNEndpointKey, } from './endpoints';
+export type { CloudflarePurgeCacheRequest, CloudflarePurgeCacheBody, CloudflarePurgeCacheResponse, CloudFrontInvalidationRequest, CloudFrontInvalidationResponse, FastlyPurgeUrlRequest, FastlyPurgeUrlResponse, CDNInvalidationRequest, CDNInvalidationResponse, } from './types';

package/dist/api/endpoints/cdn/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * CDN Provider API Type Definitions
+ *
+ * Types for CDN cache invalidation operations:
+ * - Cloudflare cache purging
+ * - AWS CloudFront invalidation
+ * - Fastly URL purging
+ *
+ * Based on Cloudflare API v4, AWS CloudFront API, and Fastly API specifications
+ * @see https://developers.cloudflare.com/api/operations/zone-purge
+ * @see https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateInvalidation.html
+ * @see https://developer.fastly.com/reference/api/purging/
+ */
+/**
+ * Cloudflare cache purge request (service function payload)
+ * POST /zones/{zoneId}/purge_cache
+ */
+export interface CloudflarePurgeCacheRequest {
+    /** Zone ID to purge cache for */
+    zoneId: string;
+    /** Cloudflare API Token with Cache Purge permission */
+    apiToken: string;
+    /** List of fully qualified URLs to purge */
+    files: string[];
+}
+/**
+ * Cloudflare cache purge body (HTTP request body)
+ */
+export interface CloudflarePurgeCacheBody {
+    /** List of fully qualified URLs to purge */
+    files: string[];
+}
+/**
+ * Cloudflare cache purge response
+ */
+export interface CloudflarePurgeCacheResponse {
+    /** Success status */
+    success: boolean;
+    /** Error messages (if any) */
+    errors?: Array<{
+        code: number;
+        message: string;
+    }>;
+    /** Purge result */
+    result?: {
+        /** Purge ID for tracking */
+        id: string;
+    };
+}
+/**
+ * CloudFront invalidation request (service function payload)
+ * POST /2020-05-31/distribution/{distributionId}/invalidation
+ */
+export interface CloudFrontInvalidationRequest {
+    /** CloudFront Distribution ID */
+    distributionId: string;
+    /** AWS Access Key ID (for AWS Signature V4) */
+    accessKeyId: string;
+    /** AWS Secret Access Key (for AWS Signature V4) */
+    secretAccessKey: string;
+    /** AWS Region (default: us-east-1) */
+    region?: string;
+    /** AWS Session Token (optional, for temporary credentials) */
+    sessionToken?: string;
+    /** List of paths to invalidate (e.g., ['/images/*', '/styles/main.css']) */
+    paths: string[];
+}
+/**
+ * CloudFront invalidation body (HTTP request body - XML format)
+ * Note: This is converted to XML in the service function
+ */
+export interface CloudFrontInvalidationBody {
+    /** Paths to invalidate */
+    Paths: {
+        Quantity: number;
+        Items: string[];
+    };
+    /** Unique caller reference (timestamp-based) */
+    CallerReference: string;
+}
+/**
+ * CloudFront invalidation response (XML parsed to JSON)
+ */
+export interface CloudFrontInvalidationResponse {
+    /** Invalidation details */
+    Invalidation?: {
+        /** Unique invalidation ID */
+        Id: string;
+        /** Invalidation status (InProgress, Completed) */
+        Status: string;
+        /** Creation time */
+        CreateTime: string;
+        /** Invalidation batch details */
+        InvalidationBatch: {
+            Paths: {
+                Quantity: number;
+                Items: string[];
+            };
+            CallerReference: string;
+        };
+    };
+}
+/**
+ * Fastly URL purge request
+ * POST /service/{serviceId}/purge/{url}
+ */
+export interface FastlyPurgeUrlRequest {
+    /** Fastly Service ID */
+    serviceId: string;
+    /** Fastly API Token with Purge permission */
+    apiToken: string;
+    /** URL to purge (will be URL-encoded) */
+    url: string;
+}
+/**
+ * Fastly URL purge response
+ */
+export interface FastlyPurgeUrlResponse {
+    /** Purge status */
+    status: 'ok' | 'error';
+    /** Purge ID for tracking */
+    id?: string;
+}
+/**
+ * Unified CDN invalidation request
+ * Used by service functions to handle all CDN providers
+ */
+export interface CDNInvalidationRequest {
+    /** CDN provider type */
+    provider: 'cloudflare' | 'cloudfront' | 'fastly';
+    /** Provider-specific configuration */
+    config: CloudflarePurgeCacheRequest | CloudFrontInvalidationRequest | FastlyPurgeUrlRequest;
+    /** URLs to invalidate */
+    urls: string[];
+}
+/**
+ * Unified CDN invalidation response
+ * Normalized response across all providers
+ */
+export interface CDNInvalidationResponse {
+    /** Provider that handled the invalidation */
+    provider: 'cloudflare' | 'cloudfront' | 'fastly';
+    /** Success status */
+    success: boolean;
+    /** URLs that were invalidated */
+    urls: string[];
+    /** Provider-specific invalidation ID */
+    invalidationId: string;
+    /** Error message (if failed) */
+    error?: string;
+}

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

@@ -1,4 +1,6 @@
 export type * from './campaigns';
 export type * from './health';
 export type * from './infobip';
+export type * from './virustotal';
+export type * from './cdn';
 export type * from './types';

package/dist/api/endpoints/types.d.ts

@@ -1,6 +1,8 @@
 import type { CampaignEndpointTypes } from './campaigns';
 import type { PollingEndpointTypes } from './health';
 import type { InfobipEndpointTypes } from './infobip';
+import type { VirusTotalEndpointTypes } from './virustotal';
+import type { CloudflareEndpointTypes, CloudFrontEndpointTypes, FastlyEndpointTypes } from './cdn';
 /**
  * Query parameters type - matches fetchff's flexible param handling
  * Supports objects, URLSearchParams, and arrays of name-value pairs
@@ -9,5 +11,5 @@ export type QueryParams = Record<string, string | number | boolean | string[] |
 /**
  * All endpoint types combined
  */
-export interface EndpointTypes extends CampaignEndpointTypes, PollingEndpointTypes, InfobipEndpointTypes {
+export interface EndpointTypes extends CampaignEndpointTypes, PollingEndpointTypes, InfobipEndpointTypes, VirusTotalEndpointTypes, CloudflareEndpointTypes, CloudFrontEndpointTypes, FastlyEndpointTypes {
 }

package/dist/api/endpoints/virustotal/endpoints.d.ts

@@ -0,0 +1,37 @@
+/**
+ * VirusTotal Endpoint Type Definitions
+ *
+ * This file contains endpoint type definitions for virus/malware scanning operations:
+ * - File upload for scanning
+ * - Analysis result retrieval
+ * - API health checks
+ *
+ * @see ./types.ts
+ */
+import type { Endpoint, Req } from 'fetchff';
+import type { VirusTotalUploadFileRequest, VirusTotalUploadFileResponse, VirusTotalGetAnalysisResponse, VirusTotalGetAnalysisParams, VirusTotalGetVersionResponse } from './types';
+/**
+ * VirusTotal API endpoint types
+ * Complete type definitions for virus scanning endpoints
+ */
+export interface VirusTotalEndpointTypes {
+    /**
+     * POST /files - Upload file for scanning
+     * Supports multipart/form-data uploads up to 650MB (free tier)
+     */
+    uploadFileForScanning: Endpoint<Req<VirusTotalUploadFileResponse, VirusTotalUploadFileRequest>>;
+    /**
+     * GET /analyses/:id - Get analysis result
+     * Retrieve scan results for previously uploaded file
+     */
+    getAnalysisResult: Endpoint<Req<VirusTotalGetAnalysisResponse, never, VirusTotalGetAnalysisParams>>;
+    /**
+     * GET /version - Get API version (health check)
+     * Simple endpoint to verify API availability
+     */
+    getApiVersion: Endpoint<Req<VirusTotalGetVersionResponse>>;
+}
+/**
+ * Type guard to check if an endpoint key is a valid VirusTotal endpoint
+ */
+export type VirusTotalEndpointKey = keyof VirusTotalEndpointTypes;

package/dist/api/endpoints/virustotal/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * VirusTotal API Endpoint Types
+ * Export all VirusTotal-related types
+ */
+export type { VirusTotalEndpointTypes, VirusTotalEndpointKey } from './endpoints';
+export type { VirusTotalErrorCode, VirusTotalUploadFileRequest, VirusTotalUploadFileResponse, VirusTotalUploadFileError400, VirusTotalUploadFileError401, VirusTotalUploadFileError413, VirusTotalUploadFileError429, VirusTotalGetAnalysisRequest, VirusTotalGetAnalysisParams, VirusTotalGetAnalysisResponse, VirusTotalGetAnalysisError404, VirusTotalGetAnalysisError401, VirusTotalAnalysisStatus, VirusTotalResultCategory, VirusTotalEngineResult, VirusTotalAnalysisStats, VirusTotalGetVersionResponse, VirusTotalErrorResponse, } from './types';

package/dist/api/endpoints/virustotal/types.d.ts

@@ -0,0 +1,202 @@
+/**
+ * VirusTotal API Type Definitions
+ *
+ * Types for virus/malware scanning operations:
+ * - File upload for scanning
+ * - Analysis result retrieval
+ * - API health checks
+ *
+ * Based on VirusTotal API v3 specification
+ * @see https://developers.virustotal.com/reference/overview
+ */
+import type { STORAGE_ERROR_CODES } from '../../../errors/codes';
+/**
+ * Upload file for scanning request
+ * POST /files
+ *
+ * Service function payload (not the raw HTTP request)
+ */
+export interface VirusTotalUploadFileRequest {
+    /** File buffer to scan */
+    file: globalThis.Buffer;
+    /** Original filename */
+    filename: string;
+}
+/**
+ * Upload file response - returns analysis ID for polling
+ */
+export interface VirusTotalUploadFileResponse {
+    data: {
+        /** Resource type (always "analysis") */
+        type: 'analysis';
+        /** Analysis ID - use this to poll for results */
+        id: string;
+        /** Additional links */
+        links?: {
+            self: string;
+        };
+    };
+    /** Additional metadata */
+    meta?: {
+        file_info?: {
+            /** SHA256 hash of uploaded file */
+            sha256?: string;
+            /** File size in bytes */
+            size?: number;
+        };
+    };
+}
+/**
+ * VirusTotal API error code types
+ */
+export type VirusTotalErrorCode = typeof STORAGE_ERROR_CODES.VIRUSTOTAL_BAD_REQUEST | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_AUTHENTICATION_REQUIRED | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_WRONG_CREDENTIALS | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_FILE_TOO_LARGE | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_QUOTA_EXCEEDED | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_ANALYSIS_NOT_FOUND | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_SCAN_TIMEOUT | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_SCAN_FAILED;
+/**
+ * Upload file error responses
+ */
+export interface VirusTotalUploadFileError400 {
+    error: {
+        message: string;
+        code: typeof STORAGE_ERROR_CODES.VIRUSTOTAL_BAD_REQUEST;
+    };
+}
+export interface VirusTotalUploadFileError401 {
+    error: {
+        message: string;
+        code: typeof STORAGE_ERROR_CODES.VIRUSTOTAL_AUTHENTICATION_REQUIRED | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_WRONG_CREDENTIALS;
+    };
+}
+export interface VirusTotalUploadFileError413 {
+    error: {
+        message: string;
+        code: typeof STORAGE_ERROR_CODES.VIRUSTOTAL_FILE_TOO_LARGE;
+    };
+}
+export interface VirusTotalUploadFileError429 {
+    error: {
+        message: string;
+        code: typeof STORAGE_ERROR_CODES.VIRUSTOTAL_QUOTA_EXCEEDED;
+    };
+}
+/**
+ * Get analysis result request
+ * GET /analyses/:id
+ *
+ * Service function payload
+ */
+export interface VirusTotalGetAnalysisRequest {
+    /** Analysis ID from upload response */
+    analysisId: string;
+}
+/**
+ * Get analysis result params
+ * URL path parameters for GET /analyses/:id
+ */
+export interface VirusTotalGetAnalysisParams {
+    /** Analysis ID in URL path */
+    id: string;
+}
+/**
+ * Analysis status
+ */
+export type VirusTotalAnalysisStatus = 'queued' | 'in-progress' | 'completed';
+/**
+ * Individual engine result category
+ */
+export type VirusTotalResultCategory = 'malicious' | 'suspicious' | 'undetected' | 'harmless' | 'type-unsupported' | 'failure' | 'timeout';
+/**
+ * Individual antivirus engine scan result
+ */
+export interface VirusTotalEngineResult {
+    /** Detection category */
+    category: VirusTotalResultCategory;
+    /** Antivirus engine name */
+    engine_name: string;
+    /** Detected malware name (if any) */
+    result: string | null;
+    /** Detection method */
+    method: string;
+    /** Engine version */
+    engine_version?: string;
+    /** Engine update timestamp */
+    engine_update?: string;
+}
+/**
+ * Analysis statistics
+ */
+export interface VirusTotalAnalysisStats {
+    /** Number of engines that detected malware */
+    malicious: number;
+    /** Number of engines that flagged as suspicious */
+    suspicious: number;
+    /** Number of engines with no detection */
+    undetected: number;
+    /** Number of engines that marked as harmless */
+    harmless: number;
+    /** Number of engines that don't support this file type */
+    'type-unsupported': number;
+    /** Number of engines that failed to scan */
+    failure: number;
+    /** Number of engines that timed out */
+    timeout: number;
+}
+/**
+ * Get analysis result response
+ */
+export interface VirusTotalGetAnalysisResponse {
+    data: {
+        /** Resource type (always "analysis") */
+        type: 'analysis';
+        /** Analysis ID */
+        id: string;
+        /** Analysis attributes */
+        attributes: {
+            /** Current analysis status */
+            status: VirusTotalAnalysisStatus;
+            /** Aggregated statistics */
+            stats: VirusTotalAnalysisStats;
+            /** Individual engine results (only when status is "completed") */
+            results?: Record<string, VirusTotalEngineResult>;
+            /** Analysis date */
+            date?: number;
+            /** File info */
+            file_info?: {
+                sha256: string;
+                md5: string;
+                sha1: string;
+                size: number;
+            };
+        };
+        /** Additional links */
+        links?: {
+            self: string;
+            item?: string;
+        };
+    };
+}
+/**
+ * Get analysis error responses
+ */
+export interface VirusTotalGetAnalysisError404 {
+    error: {
+        message: string;
+        code: typeof STORAGE_ERROR_CODES.VIRUSTOTAL_ANALYSIS_NOT_FOUND;
+    };
+}
+export interface VirusTotalGetAnalysisError401 {
+    error: {
+        message: string;
+        code: typeof STORAGE_ERROR_CODES.VIRUSTOTAL_AUTHENTICATION_REQUIRED | typeof STORAGE_ERROR_CODES.VIRUSTOTAL_WRONG_CREDENTIALS;
+    };
+}
+/**
+ * Get API version response (used for health checks)
+ */
+export interface VirusTotalGetVersionResponse {
+    data: {
+        version: string;
+    };
+}
+/**
+ * All possible VirusTotal error responses
+ */
+export type VirusTotalErrorResponse = VirusTotalUploadFileError400 | VirusTotalUploadFileError401 | VirusTotalUploadFileError413 | VirusTotalUploadFileError429 | VirusTotalGetAnalysisError404 | VirusTotalGetAnalysisError401;