@pol-studios/db 1.0.19 → 1.0.21

package/dist/with-auth/index.d.ts

@@ -0,0 +1,704 @@
+import { u as useSupabase } from '../useSupabase-DvWVuHHE.js';
+import { P as ProfileStatus } from '../setupAuthContext-Kv-THH-h.js';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { useMutation, useQuery } from '@tanstack/react-query';
+export { e as UserMetadataContextProvider, c as UserMetadataContextType, a as UserMetadataInsert, U as UserMetadataRow, b as UserMetadataUpdate, u as useLiveChangesIndicator, h as useSetUserMetadata, i as useUserMetadataState, g as useUserMetadataValue, d as userMetadataContext } from '../UserMetadataContext-B8gVWGMl.js';
+import { UseQuerySingleReturn } from '@supabase-cache-helpers/postgrest-react-query';
+import { T as Tables } from '../database.types-ChFCG-4M.js';
+import 'react/jsx-runtime';
+import '@supabase/supabase-js/dist/module/lib/types.js';
+import 'react';
+import '@supabase/supabase-js';
+
+/**
+ * Consent types supported by the system
+ */
+type ConsentType = "terms_of_service" | "privacy_policy" | "marketing" | "data_processing" | "cookies" | string;
+/**
+ * A single consent record from the database
+ */
+interface ConsentRecord {
+    id: number;
+    userId: string;
+    consentType: ConsentType;
+    consentVersion: string;
+    consentGiven: boolean;
+    consentText: string | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    createdAt: string;
+}
+/**
+ * Summary of a user's consent status for each type
+ */
+interface ConsentSummary {
+    consentType: ConsentType;
+    consentGiven: boolean;
+    consentVersion: string;
+    consentedAt: string;
+}
+/**
+ * Options for recording consent
+ */
+interface RecordConsentOptions {
+    /** Optional snapshot of the consent text shown to the user */
+    consentText?: string;
+    /** Optional IP address (usually captured server-side) */
+    ipAddress?: string;
+}
+/**
+ * Return type for the useConsent hook
+ */
+interface UseConsentReturn {
+    /**
+     * Records a consent decision for a specific type and version
+     * @param type - The type of consent (e.g., 'terms_of_service', 'privacy_policy')
+     * @param version - The version of the document being consented to
+     * @param given - Whether consent is being given (true) or withdrawn (false)
+     * @param options - Optional additional data (consent text snapshot, IP address)
+     * @returns Promise resolving to the created consent record or null on error
+     */
+    recordConsent: (type: ConsentType, version: string, given: boolean, options?: RecordConsentOptions) => Promise<ConsentRecord | null>;
+    /**
+     * Fetches all consent records for the current user
+     * @returns Array of consent records
+     */
+    consents: ConsentRecord[];
+    /**
+     * Gets the latest consent status for each consent type
+     * @returns Array of consent summaries
+     */
+    consentSummary: ConsentSummary[];
+    /**
+     * Records consent withdrawal for a specific type
+     * Creates a new consent record with consentGiven: false
+     * @param type - The type of consent to withdraw
+     * @param version - The version of the current document
+     * @returns Promise resolving to the created withdrawal record or null on error
+     */
+    withdrawConsent: (type: ConsentType, version: string) => Promise<ConsentRecord | null>;
+    /**
+     * Checks if the user has active (non-withdrawn) consent for a type
+     * @param type - The consent type to check
+     * @returns boolean indicating if consent is currently active
+     */
+    hasActiveConsent: (type: ConsentType) => boolean;
+    /**
+     * Gets the latest consent record for a specific type
+     * @param type - The consent type to look up
+     * @returns The latest consent record or undefined if none exists
+     */
+    getLatestConsent: (type: ConsentType) => ConsentRecord | undefined;
+    /**
+     * Whether consent data is currently being loaded
+     */
+    isLoading: boolean;
+    /**
+     * Any error that occurred while loading consents
+     */
+    error: Error | null;
+    /**
+     * Refetch consent data from the server
+     */
+    refetch: () => void;
+}
+/**
+ * Hook for managing GDPR-compliant consent records
+ *
+ * Provides functionality to:
+ * - Record new consent decisions
+ * - Fetch user's consent history
+ * - Withdraw consent
+ * - Check consent status
+ *
+ * @example
+ * ```tsx
+ * function ConsentManager() {
+ *   const {
+ *     recordConsent,
+ *     withdrawConsent,
+ *     hasActiveConsent,
+ *     consentSummary,
+ *     isLoading
+ *   } = useConsent();
+ *
+ *   const handleAcceptTerms = async () => {
+ *     await recordConsent('terms_of_service', 'v1.0', true, {
+ *       consentText: 'I agree to the Terms of Service...'
+ *     });
+ *   };
+ *
+ *   const handleWithdrawMarketing = async () => {
+ *     await withdrawConsent('marketing', 'v1.0');
+ *   };
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <div>
+ *       {consentSummary.map(consent => (
+ *         <div key={consent.consentType}>
+ *           {consent.consentType}: {consent.consentGiven ? 'Accepted' : 'Declined'}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useConsent(): UseConsentReturn;
+/**
+ * Standalone function to record consent during registration
+ * Use this when the useConsent hook is not available (e.g., during sign-up flow)
+ *
+ * @param supabase - Supabase client instance
+ * @param userId - The user's ID
+ * @param type - Consent type
+ * @param version - Document version
+ * @param given - Whether consent is given
+ * @param options - Optional additional data
+ * @returns Promise resolving to the created record or null on error
+ *
+ * @example
+ * ```tsx
+ * // In registration handler
+ * const response = await supabase.auth.signUp({ email, password });
+ * if (response.data.user) {
+ *   await recordConsentForUser(
+ *     supabase,
+ *     response.data.user.id,
+ *     'terms_of_service',
+ *     'v1.0',
+ *     true,
+ *     { consentText: 'I agree to the Terms of Service...' }
+ *   );
+ * }
+ * ```
+ */
+declare function recordConsentForUser(supabase: ReturnType<typeof useSupabase>, userId: string, type: ConsentType, version: string, given: boolean, options?: RecordConsentOptions): Promise<ConsentRecord | null>;
+
+/**
+ * Deletion request status
+ */
+type DeletionStatus = "pending" | "cancelled" | "completed";
+/**
+ * Account deletion request details
+ */
+interface DeletionRequest {
+    id: number;
+    status: DeletionStatus;
+    requestedAt: string;
+    scheduledDeletionAt: string;
+    completedAt: string | null;
+    cancelledAt: string | null;
+    reason: string | null;
+    daysRemaining: number | null;
+}
+/**
+ * Response from get_deletion_status RPC
+ */
+interface DeletionStatusResponse {
+    hasRequest: boolean;
+    request: DeletionRequest | null;
+}
+/**
+ * Response from request_account_deletion RPC
+ */
+interface RequestDeletionResponse {
+    success: boolean;
+    error?: string;
+    requestId?: number;
+    requestedAt?: string;
+    scheduledDeletionAt?: string;
+    gracePeriodDays?: number;
+    message?: string;
+    existingRequest?: {
+        id: number;
+        requestedAt: string;
+        scheduledDeletionAt: string;
+        status: DeletionStatus;
+    };
+}
+/**
+ * Response from cancel_account_deletion RPC
+ */
+interface CancelDeletionResponse {
+    success: boolean;
+    error?: string;
+    requestId?: number;
+    cancelledAt?: string;
+    message?: string;
+}
+/**
+ * Hook for managing GDPR-compliant account deletion
+ *
+ * Provides functionality to:
+ * - Request account deletion (with 30-day grace period)
+ * - Cancel a pending deletion request
+ * - Check current deletion status
+ *
+ * @example
+ * ```tsx
+ * function AccountSettings() {
+ *   const {
+ *     deletionStatus,
+ *     isLoading,
+ *     isPendingDeletion,
+ *     daysRemaining,
+ *     requestDeletion,
+ *     cancelDeletion,
+ *     isRequesting,
+ *     isCancelling
+ *   } = useAccountDeletion();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   if (isPendingDeletion) {
+ *     return (
+ *       <div>
+ *         <p>Your account is scheduled for deletion in {daysRemaining} days</p>
+ *         <button onClick={() => cancelDeletion()}>Cancel Deletion</button>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => requestDeletion("No longer using the service")}>
+ *       Delete My Account
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useAccountDeletion(): {
+    requestDeletion: (reason?: string) => Promise<RequestDeletionResponse>;
+    cancelDeletion: () => Promise<CancelDeletionResponse>;
+    refreshStatus: () => void;
+    isRequesting: boolean;
+    isCancelling: boolean;
+    requestError: Error;
+    cancelError: Error;
+    requestResult: RequestDeletionResponse;
+    cancelResult: CancelDeletionResponse;
+    /** Current deletion request (if any) */
+    deletionRequest: DeletionRequest;
+    /** Whether user has a pending deletion request */
+    isPendingDeletion: boolean;
+    /** Whether user has a cancelled deletion request */
+    isCancelledDeletion: boolean;
+    /** Whether user has a completed deletion (account anonymized) */
+    isCompletedDeletion: boolean;
+    /** Days remaining until deletion (null if not pending) */
+    daysRemaining: number;
+    /** Scheduled deletion date (null if not pending) */
+    scheduledDeletionAt: Date;
+    /** Original request date */
+    requestedAt: Date;
+    /** Date when request was cancelled */
+    cancelledAt: Date;
+    /** Reason provided for deletion */
+    reason: string;
+    deletionStatus: DeletionStatusResponse;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error;
+};
+/**
+ * Type exports for consumers
+ */
+type UseAccountDeletionReturn = ReturnType<typeof useAccountDeletion>;
+
+/**
+ * User status information from get_user_status RPC
+ */
+interface UserStatusInfo {
+    exists: boolean;
+    userId?: string;
+    status?: ProfileStatus;
+    archivedAt?: string | null;
+    archivedBy?: string | null;
+    isActive?: boolean;
+}
+/**
+ * Response from archive_user RPC
+ */
+interface ArchiveUserResponse {
+    success: boolean;
+    error?: string;
+    userId?: string;
+    archivedAt?: string;
+    archivedBy?: string;
+    message?: string;
+}
+/**
+ * Response from unarchive_user RPC
+ */
+interface UnarchiveUserResponse {
+    success: boolean;
+    error?: string;
+    userId?: string;
+    restoredAt?: string;
+    restoredBy?: string;
+    message?: string;
+}
+/**
+ * Hook for managing user profile status (archival)
+ *
+ * Provides functionality to:
+ * - Check a user's current status
+ * - Archive a user (admin only)
+ * - Unarchive/restore a user (admin only)
+ *
+ * @param targetUserId - Optional user ID to check. Defaults to current user.
+ *
+ * @example
+ * ```tsx
+ * // Check current user's status
+ * function MyProfile() {
+ *   const { status, isArchived } = useUserStatus();
+ *
+ *   if (isArchived) {
+ *     return <p>Your account has been archived</p>;
+ *   }
+ *
+ *   return <p>Your account is active</p>;
+ * }
+ *
+ * // Admin managing another user
+ * function UserManagement({ userId }: { userId: string }) {
+ *   const {
+ *     status,
+ *     isArchived,
+ *     archiveUser,
+ *     unarchiveUser,
+ *     isArchiving,
+ *     isUnarchiving
+ *   } = useUserStatus(userId);
+ *
+ *   return (
+ *     <div>
+ *       <p>Status: {status}</p>
+ *       {isArchived ? (
+ *         <button onClick={() => unarchiveUser(userId)} disabled={isUnarchiving}>
+ *           Restore Access
+ *         </button>
+ *       ) : (
+ *         <button onClick={() => archiveUser(userId)} disabled={isArchiving}>
+ *           Archive User
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useUserStatus(targetUserId?: string): {
+    archiveUser: (userId: string, reason?: string) => Promise<ArchiveUserResponse>;
+    unarchiveUser: (userId: string) => Promise<UnarchiveUserResponse>;
+    refreshStatus: () => void;
+    invalidateUserStatus: (userIdToInvalidate: string) => void;
+    isArchiving: boolean;
+    isUnarchiving: boolean;
+    archiveError: Error;
+    unarchiveError: Error;
+    archiveResult: ArchiveUserResponse;
+    unarchiveResult: UnarchiveUserResponse;
+    /** User exists in system */
+    exists: boolean;
+    /** Current profile status */
+    status: ProfileStatus | undefined;
+    /** Whether user profile is active */
+    isActive: boolean;
+    /** Whether user profile is archived */
+    isArchived: boolean;
+    /** Whether user profile is suspended */
+    isSuspended: boolean;
+    /** Timestamp when user was archived */
+    archivedAt: Date;
+    /** ID of admin who archived the user */
+    archivedBy: string;
+    statusData: UserStatusInfo;
+    isLoading: boolean;
+    isError: boolean;
+    error: Error;
+};
+/**
+ * Type exports for consumers
+ */
+type UseUserStatusReturn = ReturnType<typeof useUserStatus>;
+
+/**
+ * GDPR Article 20 compliant personal data export metadata
+ */
+interface DataExportMetadata {
+    exportId: string;
+    exportedAt: string;
+    userId: string;
+    gdprArticle: string;
+    format: string;
+    version: string;
+}
+/**
+ * Profile data structure in export
+ */
+interface ExportedProfile {
+    id: string;
+    email: string;
+    firstName: string;
+    middleName: string;
+    lastName: string;
+    fullName: string;
+    phone: string;
+    profilePath: string | null;
+    metadata: Record<string, unknown> | null;
+}
+/**
+ * Access permission record
+ */
+interface ExportedAccessPermission {
+    accessKey: string;
+    source: "direct" | "group";
+}
+/**
+ * Group membership record
+ */
+interface ExportedGroupMembership {
+    groupId: number;
+    groupName: string;
+    groupDescription: string | null;
+    grantedAt: string;
+    grantedBy: string | null;
+    expiresAt: string | null;
+}
+/**
+ * User metadata key-value pair
+ */
+interface ExportedUserMetadata {
+    key: string;
+    value: string;
+}
+/**
+ * Device/push token information
+ */
+interface ExportedDevice {
+    deviceType: string | null;
+    deviceOS: string | null;
+    deviceOSVersion: string | null;
+    deviceModel: string | null;
+    platform: string | null;
+    appVersion: string | null;
+    isActive: boolean;
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+/**
+ * Audit log entry
+ */
+interface ExportedAuditLogEntry {
+    schemaName: string;
+    tableName: string;
+    operation: string;
+    changeAt: string;
+    recordPrimaryKey: Record<string, unknown>;
+}
+/**
+ * Saved query record
+ */
+interface ExportedSavedQuery {
+    id: number;
+    title: string;
+    description: string | null;
+    categoryId: string;
+    schema: string;
+    table: string;
+    path: string;
+    visibility: string;
+    createdAt: string;
+}
+/**
+ * Comment record
+ */
+interface ExportedComment {
+    id: string;
+    message: string;
+    createdAt: string;
+    commentSectionId: string;
+}
+/**
+ * Notification record
+ */
+interface ExportedNotification {
+    title: string;
+    message: string;
+    link: string | null;
+    scheduledAt: string | null;
+    types: string[];
+}
+/**
+ * Recent activity section
+ */
+interface ExportedRecentActivity {
+    auditLog: ExportedAuditLogEntry[];
+    retentionPeriod: string;
+}
+/**
+ * Complete personal data export structure
+ * Follows GDPR Article 20 requirements for data portability
+ */
+interface PersonalDataExport {
+    exportMetadata: DataExportMetadata;
+    profile: ExportedProfile;
+    accessPermissions: ExportedAccessPermission[];
+    groupMemberships: ExportedGroupMembership[];
+    userMetadata: ExportedUserMetadata[];
+    devices: ExportedDevice[];
+    recentActivity: ExportedRecentActivity;
+    savedQueries: ExportedSavedQuery[];
+    comments: ExportedComment[];
+    notifications: ExportedNotification[];
+}
+/**
+ * Export request history record
+ */
+interface DataExportHistoryRecord {
+    id: string;
+    requestedAt: string;
+    completedAt: string | null;
+    status: "pending" | "processing" | "completed" | "failed";
+    downloadCount: number;
+    lastDownloadedAt: string | null;
+    expiresAt: string | null;
+}
+/**
+ * Hook return type
+ */
+interface UseDataExportReturn {
+    /** Trigger a personal data export */
+    exportMyData: () => Promise<PersonalDataExport>;
+    /** Export mutation state */
+    exportMutation: ReturnType<typeof useMutation<PersonalDataExport, Error, void>>;
+    /** Download data as JSON file */
+    downloadAsJson: (data: PersonalDataExport, filename?: string) => void;
+    /** Export history query */
+    historyQuery: ReturnType<typeof useQuery<DataExportHistoryRecord[], Error>>;
+    /** Get export history */
+    getExportHistory: () => DataExportHistoryRecord[];
+    /** Refresh export history */
+    refreshHistory: () => void;
+    /** Loading state for export */
+    isExporting: boolean;
+    /** Loading state for history */
+    isLoadingHistory: boolean;
+}
+/**
+ * Hook for GDPR Article 20 compliant personal data export
+ *
+ * @example
+ * ```tsx
+ * function DataExportButton() {
+ *   const { exportMyData, downloadAsJson, isExporting } = useDataExport();
+ *
+ *   const handleExport = async () => {
+ *     const data = await exportMyData();
+ *     downloadAsJson(data);
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleExport} disabled={isExporting}>
+ *       {isExporting ? 'Preparing...' : 'Download My Data'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useDataExport(): UseDataExportReturn;
+
+type TaskRequest = {
+    handlerId: string;
+    title: string;
+    description: string;
+    body?: any;
+};
+declare function useBackgroundTask(): {
+    startTask: (request: TaskRequest) => Promise<void>;
+    retryTask: (taskId: number) => Promise<any>;
+    cancelTask: (taskId: number) => Promise<void>;
+};
+
+declare function useUserMetadata(key: string): [
+    UseQuerySingleReturn<Tables<"UserMetadata"> | null>,
+    (value: string) => Promise<any>
+];
+
+/**
+ * Metadata to store in storage.objects.metadata
+ */
+interface StorageUploadMetadata {
+    processingStatus?: "None" | "Processing" | "Error";
+    contentType?: string;
+    contentHeight?: number;
+    contentWidth?: number;
+    originalFileName?: string;
+}
+type UploadInput = {
+    /** The file to upload */
+    file: File | Blob;
+    /** Optional custom filename (defaults to original file name) */
+    fileName?: string;
+    /** Optional directory prefix within the bucket */
+    directory?: string;
+    /** Optional custom metadata to store with the file */
+    metadata?: StorageUploadMetadata;
+    /** Progress callback */
+    onUploadProgress?: (bytesUploaded: number, bytesTotal: number) => void;
+};
+type UploadResult = {
+    /** The storage path (e.g., "14/abc-123.jpg") */
+    path: string;
+    /** The bucket ID */
+    bucketId: string;
+    /** Original filename */
+    originalFileName: string;
+    /** Content type from file */
+    contentType: string;
+};
+type UseStorageUploadOptions = {
+    /** The storage bucket ID - required */
+    bucketId: string;
+};
+/**
+ * Hook for uploading files to Supabase Storage with path-based references.
+ *
+ * Unlike useDbAttachmentUpload, this hook:
+ * - Does NOT create Attachment records
+ * - Returns the storage path for the caller to store
+ * - Sets metadata directly on storage.objects
+ *
+ * @example
+ * ```tsx
+ * import { BUCKETS } from "@pol-studios/db";
+ *
+ * const upload = useStorageUpload({ bucketId: BUCKETS.AVATARS });
+ *
+ * const handleUpload = async (file: File) => {
+ *   const result = await upload.mutateAsync({ file });
+ *   // Store result.path on the entity
+ *   await updateProfile({ profilePath: result.path });
+ * };
+ * ```
+ */
+declare function useStorageUpload(options: UseStorageUploadOptions): ReturnType<typeof useMutation<UploadResult, Error, UploadInput>>;
+/**
+ * Convenience hook that combines upload with entity update.
+ * Uploads the file and then updates the specified entity with the path.
+ */
+declare function useStorageUploadWithEntity<T extends Record<string, unknown>>(options: UseStorageUploadOptions & {
+    /** Field name on the entity to store the path */
+    pathField: string;
+    /** Function to update the entity after upload */
+    updateEntity: (entity: T, path: string) => Promise<void>;
+}): _tanstack_react_query.UseMutationResult<UploadResult, Error, UploadInput & {
+    entity: T;
+}, unknown>;
+
+export { type ArchiveUserResponse, type CancelDeletionResponse, type ConsentRecord, type ConsentSummary, type ConsentType, type DataExportHistoryRecord, type DataExportMetadata, type DeletionRequest, type DeletionStatus, type DeletionStatusResponse, type ExportedAccessPermission, type ExportedAuditLogEntry, type ExportedComment, type ExportedDevice, type ExportedGroupMembership, type ExportedNotification, type ExportedProfile, type ExportedRecentActivity, type ExportedSavedQuery, type ExportedUserMetadata, type PersonalDataExport, type RecordConsentOptions, type RequestDeletionResponse, type StorageUploadMetadata, type TaskRequest, type UnarchiveUserResponse, type UseAccountDeletionReturn, type UseConsentReturn, type UseDataExportReturn, type UseUserStatusReturn, type UserStatusInfo, recordConsentForUser, useAccountDeletion, useBackgroundTask, useConsent, useDataExport, useStorageUpload, useStorageUploadWithEntity, useUserMetadata, useUserStatus };