@plyaz/types 1.15.20 → 1.16.0

package/dist/storage/schemas.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Storage Package Zod Schemas
+ * @module @plyaz/types/storage/schemas
+ *
+ * Validation schemas for storage webhooks and other features
+ */
+import { z } from 'zod';
+/**
+ * Storage media processing job status
+ */
+export declare enum STORAGE_PROCESSING_STATUS {
+    Queued = "queued",
+    Processing = "processing",
+    Completed = "completed",
+    Failed = "failed"
+}
+/**
+ * Storage media processing output schema
+ */
+export declare const StorageProcessingOutputSchema: z.ZodObject<{
+    url: z.ZodString;
+    format: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    size: z.ZodNumber;
+    bitrate: z.ZodOptional<z.ZodNumber>;
+    codec: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StorageProcessingOutput = z.infer<typeof StorageProcessingOutputSchema>;
+/**
+ * Storage media processing webhook payload schema
+ */
+export declare const StorageMediaProcessingPayloadSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    status: z.ZodEnum<typeof STORAGE_PROCESSING_STATUS>;
+    input: z.ZodObject<{
+        url: z.ZodString;
+        objectKey: z.ZodString;
+        bucket: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    output: z.ZodOptional<z.ZodObject<{
+        primary: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            format: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            duration: z.ZodOptional<z.ZodNumber>;
+            size: z.ZodNumber;
+            bitrate: z.ZodOptional<z.ZodNumber>;
+            codec: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        thumbnail: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            format: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            duration: z.ZodOptional<z.ZodNumber>;
+            size: z.ZodNumber;
+            bitrate: z.ZodOptional<z.ZodNumber>;
+            codec: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        variants: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            format: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            duration: z.ZodOptional<z.ZodNumber>;
+            size: z.ZodNumber;
+            bitrate: z.ZodOptional<z.ZodNumber>;
+            codec: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        duration: z.ZodOptional<z.ZodNumber>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        format: z.ZodOptional<z.ZodString>;
+        codec: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    progress: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    timestamp: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    provider: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StorageMediaProcessingPayload = z.infer<typeof StorageMediaProcessingPayloadSchema>;
+/**
+ * ============================================================================
+ * Cloudflare R2 Webhook Schemas
+ * ============================================================================
+ * S3-compatible event notifications
+ * https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-content-structure.html
+ */
+export declare const R2EventRecordSchema: z.ZodObject<{
+    eventVersion: z.ZodString;
+    eventSource: z.ZodString;
+    awsRegion: z.ZodOptional<z.ZodString>;
+    eventTime: z.ZodString;
+    eventName: z.ZodString;
+    userIdentity: z.ZodOptional<z.ZodObject<{
+        principalId: z.ZodString;
+    }, z.core.$strip>>;
+    requestParameters: z.ZodOptional<z.ZodObject<{
+        sourceIPAddress: z.ZodString;
+    }, z.core.$strip>>;
+    responseElements: z.ZodOptional<z.ZodObject<{
+        'x-amz-request-id': z.ZodOptional<z.ZodString>;
+        'x-amz-id-2': z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    s3: z.ZodObject<{
+        s3SchemaVersion: z.ZodString;
+        configurationId: z.ZodOptional<z.ZodString>;
+        bucket: z.ZodObject<{
+            name: z.ZodString;
+            ownerIdentity: z.ZodOptional<z.ZodObject<{
+                principalId: z.ZodString;
+            }, z.core.$strip>>;
+            arn: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        object: z.ZodObject<{
+            key: z.ZodString;
+            size: z.ZodOptional<z.ZodNumber>;
+            eTag: z.ZodOptional<z.ZodString>;
+            versionId: z.ZodOptional<z.ZodString>;
+            sequencer: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const R2WebhookPayloadSchema: z.ZodObject<{
+    Records: z.ZodArray<z.ZodObject<{
+        eventVersion: z.ZodString;
+        eventSource: z.ZodString;
+        awsRegion: z.ZodOptional<z.ZodString>;
+        eventTime: z.ZodString;
+        eventName: z.ZodString;
+        userIdentity: z.ZodOptional<z.ZodObject<{
+            principalId: z.ZodString;
+        }, z.core.$strip>>;
+        requestParameters: z.ZodOptional<z.ZodObject<{
+            sourceIPAddress: z.ZodString;
+        }, z.core.$strip>>;
+        responseElements: z.ZodOptional<z.ZodObject<{
+            'x-amz-request-id': z.ZodOptional<z.ZodString>;
+            'x-amz-id-2': z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        s3: z.ZodObject<{
+            s3SchemaVersion: z.ZodString;
+            configurationId: z.ZodOptional<z.ZodString>;
+            bucket: z.ZodObject<{
+                name: z.ZodString;
+                ownerIdentity: z.ZodOptional<z.ZodObject<{
+                    principalId: z.ZodString;
+                }, z.core.$strip>>;
+                arn: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            object: z.ZodObject<{
+                key: z.ZodString;
+                size: z.ZodOptional<z.ZodNumber>;
+                eTag: z.ZodOptional<z.ZodString>;
+                versionId: z.ZodOptional<z.ZodString>;
+                sequencer: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type R2WebhookPayload = z.infer<typeof R2WebhookPayloadSchema>;
+export type R2EventRecord = z.infer<typeof R2EventRecordSchema>;
+/**
+ * ============================================================================
+ * Supabase Storage Webhook Schemas
+ * ============================================================================
+ * Database webhook events from storage.objects table
+ */
+export declare const SupabaseStorageObjectSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    bucket_id: z.ZodString;
+    name: z.ZodString;
+    owner: z.ZodNullable<z.ZodOptional<z.ZodUUID>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    last_accessed_at: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    metadata: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    version: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    owner_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export declare const SupabaseWebhookPayloadSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        DELETE: "DELETE";
+        UPDATE: "UPDATE";
+        INSERT: "INSERT";
+    }>;
+    table: z.ZodLiteral<"objects">;
+    schema: z.ZodLiteral<"storage">;
+    record: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+        id: z.ZodUUID;
+        bucket_id: z.ZodString;
+        name: z.ZodString;
+        owner: z.ZodNullable<z.ZodOptional<z.ZodUUID>>;
+        created_at: z.ZodString;
+        updated_at: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        last_accessed_at: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        metadata: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        version: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        owner_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>;
+    old_record: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+        id: z.ZodUUID;
+        bucket_id: z.ZodString;
+        name: z.ZodString;
+        owner: z.ZodNullable<z.ZodOptional<z.ZodUUID>>;
+        created_at: z.ZodString;
+        updated_at: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        last_accessed_at: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        metadata: z.ZodNullable<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        version: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        owner_id: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type SupabaseWebhookPayload = z.infer<typeof SupabaseWebhookPayloadSchema>;
+export type SupabaseStorageObject = z.infer<typeof SupabaseStorageObjectSchema>;

package/dist/storage/webhooks.d.ts

@@ -0,0 +1,340 @@
+import { type STORAGE_OPERATION, type STORAGE_SIGNATURE_METHOD, type STORAGE_WEBHOOK_EVENT_TYPE, type RETRY_STRATEGY } from './enums';
+import type { CoreIdempotencyStoreConfig } from '../core';
+/**
+ * Base webhook payload structure
+ */
+export interface StorageWebhookPayload<T = unknown> {
+    /** HTTP method */
+    method: string;
+    /** Request URL */
+    url: string;
+    /** HTTP headers */
+    headers: Record<string, string | string[]>;
+    /** Parsed body */
+    body: T;
+    /** Raw body (for signature verification) */
+    rawBody?: string;
+}
+/**
+ * Processed webhook event
+ * This is what gets emitted after webhook processing
+ */
+export interface ProcessedStorageWebhookEvent {
+    /** Event type */
+    eventType: STORAGE_WEBHOOK_EVENT_TYPE;
+    /** File ID (if applicable) */
+    fileId?: string;
+    /** Bucket name */
+    bucketName?: string;
+    /** Bucket name (alias) */
+    bucket?: string;
+    /** Object key/path */
+    objectKey: string;
+    /** Storage operation */
+    operation: STORAGE_OPERATION;
+    /** Event timestamp */
+    timestamp: Date;
+    /** Provider name (r2, supabase, mediaconvert, etc.) */
+    provider: string;
+    /** File size in bytes */
+    fileSize?: number;
+    /** Content type */
+    contentType?: string;
+    /** ETag */
+    etag?: string;
+    /** Version ID */
+    versionId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Webhook verification result
+ */
+export interface StorageWebhookVerificationResult {
+    /** Whether signature is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Additional verification details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Webhook processing result
+ */
+export interface StorageWebhookProcessingResult {
+    /** Whether processing succeeded */
+    success: boolean;
+    /** Processed events */
+    events: ProcessedStorageWebhookEvent[];
+    /** Whether this was a duplicate request (idempotency) */
+    duplicate?: boolean;
+    /** Error if processing failed */
+    error?: Error;
+    /** Processing metadata */
+    metadata?: {
+        /** Processing time in milliseconds */
+        processingTime?: number;
+        /** Number of events processed */
+        eventCount?: number;
+        /** Number of retry attempts made */
+        retryAttempts?: number;
+        /** Whether max retries were exceeded */
+        maxRetriesExceeded?: boolean;
+        /** Retry errors encountered */
+        retryErrors?: Array<{
+            attempt: number;
+            error: string;
+            timestamp: number;
+        }>;
+    };
+}
+/**
+ * Base webhook adapter configuration
+ */
+export interface StorageBaseWebhookAdapterConfig {
+    /** Webhook secret for signature verification */
+    secret: string;
+    /** Signature verification method */
+    signatureMethod?: STORAGE_SIGNATURE_METHOD;
+    /** Header containing signature */
+    signatureHeader?: string;
+    /** Header containing timestamp (for replay attack prevention) */
+    timestampHeader?: string;
+    /** Timestamp tolerance in milliseconds */
+    timestampTolerance?: number;
+    /** Allowed source IPs (CIDR notation) */
+    allowedIPs?: string[];
+    /** Logger instance */
+    logger?: unknown;
+    /** Security configuration (alternative to individual properties) */
+    security?: StorageWebhookSecurityConfig;
+}
+/**
+ * Security configuration for webhooks
+ */
+export interface StorageWebhookSecurityConfig {
+    /** Allowed source IPs (CIDR notation) */
+    allowedIPs?: string[];
+    /** Require IP whitelist check */
+    requireIPWhitelist?: boolean;
+    /** Maximum timestamp age in milliseconds (replay attack prevention) */
+    maxTimestampAge?: number;
+    /** Require timestamp validation */
+    requireTimestamp?: boolean;
+    /** Rate limit configuration */
+    rateLimit?: {
+        /** Maximum requests per window */
+        maxRequests: number;
+        /** Time window in milliseconds */
+        windowMs: number;
+    };
+}
+/**
+ * Webhook adapter interface
+ * Note: TSchema is the validation schema type (implementation detail is hidden)
+ */
+export interface StorageWebhookAdapter<TPayload = unknown, TSchema = unknown> {
+    /** Provider name (r2, supabase, mediaconvert, etc.) */
+    readonly providerName: string;
+    /** Event type this adapter handles */
+    readonly eventType: STORAGE_WEBHOOK_EVENT_TYPE | string;
+    /** Validation schema for payload (implementation agnostic) */
+    readonly schema: TSchema;
+    /** Priority (lower = higher priority, default: 100) */
+    readonly priority?: number;
+    /**
+     * Verify webhook signature
+     */
+    verify(payload: StorageWebhookPayload<unknown>): StorageWebhookVerificationResult | Promise<StorageWebhookVerificationResult>;
+    /**
+     * Process webhook payload
+     */
+    process(payload: StorageWebhookPayload<TPayload>): ProcessedStorageWebhookEvent[] | Promise<ProcessedStorageWebhookEvent[]>;
+    /**
+     * Generate idempotency key from payload
+     */
+    getIdempotencyKey?(payload: StorageWebhookPayload<TPayload>): string;
+    /**
+     * Check if this adapter should process the webhook
+     * Useful when multiple adapters handle same provider/event
+     */
+    shouldProcess?(payload: StorageWebhookPayload<unknown>): boolean;
+    /**
+     * Handle errors during processing
+     */
+    handleError?(error: Error, payload: StorageWebhookPayload<unknown>): void | Promise<void>;
+}
+/**
+ * Webhook manager configuration
+ */
+export interface StorageWebhookManagerConfig {
+    /** Enable/disable webhook processing */
+    enabled?: boolean;
+    /** Webhook processing timeout in milliseconds */
+    timeout?: number;
+    /** Idempotency store configuration */
+    idempotency?: CoreIdempotencyStoreConfig;
+    /** Retry configuration */
+    retry?: StorageWebhookRetryConfig;
+    /** Security configuration */
+    security?: StorageWebhookSecurityConfig;
+    /** Webhook scope (service or adapter level) */
+    scope?: 'service' | 'adapter';
+    /** Adapter name (for adapter-level webhooks) */
+    adapterName?: string;
+}
+/**
+ * Webhook retry configuration
+ */
+export interface StorageWebhookRetryConfig {
+    /** Enable/disable retry */
+    enabled?: boolean;
+    /** Retry strategy */
+    strategy?: RETRY_STRATEGY;
+    /** Maximum retry attempts */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds */
+    initialDelay?: number;
+    /** Maximum delay in milliseconds */
+    maxDelay?: number;
+    /** Backoff multiplier for exponential strategy */
+    backoffMultiplier?: number;
+    /** Error codes that should NOT be retried (permanent failures) */
+    nonRetryableErrorCodes?: string[];
+    /** Callback on retry attempt */
+    onRetry?: (attempt: number, error: Error, payload: StorageWebhookPayload) => void;
+}
+/**
+ * External idempotency store interface
+ */
+export interface StorageExternalIdempotencyStore {
+    /**
+     * Check if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Set key with TTL
+     */
+    set(key: string, ttl: number, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Delete key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all keys (optional)
+     */
+    clear?(): Promise<void>;
+}
+/**
+ * Idempotency record
+ */
+export interface StorageIdempotencyRecord {
+    /** Unique key */
+    key: string;
+    /** When processed */
+    processedAt: Date;
+    /** When expires */
+    expiresAt: Date;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Webhook middleware
+ */
+export interface StorageWebhookMiddleware {
+    /** Middleware name */
+    name: string;
+    /** Priority (lower = runs earlier) */
+    priority?: number;
+    /**
+     * Run before webhook processing
+     * Can modify payload
+     */
+    before?(payload: StorageWebhookPayload): Promise<StorageWebhookPayload | void>;
+    /**
+     * Run after webhook processing
+     * Can modify result
+     */
+    after?(result: StorageWebhookProcessingResult, payload: StorageWebhookPayload): Promise<StorageWebhookProcessingResult | void>;
+    /**
+     * Handle errors
+     */
+    onError?(error: Error, payload: StorageWebhookPayload): Promise<void>;
+}
+/**
+ * Webhook audit log entry
+ */
+export interface WebhookAuditLogEntry {
+    /** Unique audit ID */
+    id: string;
+    /** Event timestamp */
+    timestamp: Date;
+    /** Event type */
+    eventType: STORAGE_WEBHOOK_EVENT_TYPE | string;
+    /** Storage operation */
+    operation: STORAGE_OPERATION;
+    /** File ID */
+    fileId?: string;
+    /** Bucket name */
+    bucketName?: string;
+    /** Object key */
+    objectKey: string;
+    /** Provider name */
+    provider: string;
+    /** Source IP address */
+    sourceIP: string;
+    /** Whether signature was valid */
+    signatureValid: boolean;
+    /** Compliance checks results */
+    complianceChecks?: {
+        retentionPolicyRespected: boolean;
+        immutabilityRespected: boolean;
+        jurisdictionCompliant?: boolean;
+    };
+    /** Processing result */
+    result: 'success' | 'failed' | 'blocked' | 'duplicate';
+    /** Error message */
+    error?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Storage service webhook configuration
+ * Can be configured at service level or adapter level
+ */
+export interface StorageWebhookConfig {
+    /** Enable/disable webhooks */
+    enabled?: boolean;
+    /** Webhook adapters to register */
+    adapters?: StorageWebhookAdapter[];
+    /** Webhook middleware */
+    middleware?: StorageWebhookMiddleware[];
+    /** Webhook manager configuration */
+    config?: StorageWebhookManagerConfig;
+}
+/**
+ * ============================================================================
+ * Provider-Specific Webhook Config Interfaces
+ * ============================================================================
+ * Note: Schemas and types are in schemas.ts
+ */
+/**
+ * Cloudflare R2 Webhook Configuration
+ */
+export interface CloudflareR2WebhookConfig extends StorageBaseWebhookAdapterConfig {
+    /**
+     * Provider name (default: 'cloudflare-r2')
+     */
+    providerName?: string;
+}
+/**
+ * Supabase Storage Webhook Configuration
+ */
+export interface SupabaseStorageWebhookConfig extends StorageBaseWebhookAdapterConfig {
+    /**
+     * Provider name (default: 'supabase-storage')
+     */
+    providerName?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.15.20",
+  "version": "1.16.0",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",
@@ -185,6 +185,11 @@
       "import": "./dist/payments/index.js",
       "require": "./dist/payments/index.cjs"
     },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js",
+      "require": "./dist/storage/index.cjs"
+    },
     "./db": {
       "types": "./dist/db/index.d.ts",
       "import": "./dist/db/index.js",