@pol-studios/db 1.0.0 → 1.0.1

package/dist/auth/guards.d.ts

@@ -0,0 +1,180 @@
+import { b as EntityPermissionCheck, a as EntityAction } from '../EntityPermissions-DwFt4tUd.js';
+
+/**
+ * Check if a user has access to a specific permission key.
+ * Owners bypass all permission checks.
+ *
+ * @param accessKeys - Array of access keys the user has
+ * @param key - The access key to check for
+ * @param options - Additional options for the check
+ * @param options.isArchived - Whether the user is archived
+ * @param options.isSuspended - Whether the user is suspended
+ * @returns boolean - true if user has the specified access
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const canAccess = hasAccess(['admin', 'viewer'], 'admin'); // true
+ * const cannotAccess = hasAccess(['viewer'], 'admin'); // false
+ *
+ * // Owner bypasses all checks
+ * const ownerAccess = hasAccess(['owner'], 'any-key'); // true
+ *
+ * // Empty key always returns true (no permission required)
+ * const noKeyRequired = hasAccess(['viewer'], ''); // true
+ *
+ * // Archived/suspended users have no access
+ * const archivedUser = hasAccess(['admin'], 'admin', { isArchived: true }); // false
+ * ```
+ */
+declare function hasAccess(accessKeys: string[] | undefined | null, key: string, options?: {
+    isArchived?: boolean;
+    isSuspended?: boolean;
+}): boolean;
+/**
+ * Check if a user has any of the specified access keys.
+ *
+ * @param accessKeys - Array of access keys the user has
+ * @param keys - Array of access keys to check for (OR logic)
+ * @param options - Additional options for the check
+ * @returns boolean - true if user has any of the specified keys
+ *
+ * @example
+ * ```ts
+ * const hasAny = hasAnyAccess(['viewer'], ['admin', 'editor', 'viewer']); // true
+ * const hasNone = hasAnyAccess(['viewer'], ['admin', 'editor']); // false
+ * ```
+ */
+declare function hasAnyAccess(accessKeys: string[] | undefined | null, keys: string[], options?: {
+    isArchived?: boolean;
+    isSuspended?: boolean;
+}): boolean;
+/**
+ * Check if a user has all of the specified access keys.
+ *
+ * @param accessKeys - Array of access keys the user has
+ * @param keys - Array of access keys to check for (AND logic)
+ * @param options - Additional options for the check
+ * @returns boolean - true if user has all of the specified keys
+ *
+ * @example
+ * ```ts
+ * const hasAll = hasAllAccess(['admin', 'editor'], ['admin', 'editor']); // true
+ * const hasPartial = hasAllAccess(['admin'], ['admin', 'editor']); // false
+ * ```
+ */
+declare function hasAllAccess(accessKeys: string[] | undefined | null, keys: string[], options?: {
+    isArchived?: boolean;
+    isSuspended?: boolean;
+}): boolean;
+
+/**
+ * Check if a user has entity-level access based on permission check result.
+ * Owners (users with 'owner' access key) bypass entity permissions entirely.
+ *
+ * @param permission - The permission check result from getPermission/usePermission
+ * @param action - The action to check for
+ * @param options - Additional options for the check
+ * @param options.accessKeys - User's access keys (for owner check)
+ * @param options.isArchived - Whether the user is archived
+ * @param options.isSuspended - Whether the user is suspended
+ * @returns boolean - true if user has permission for the action
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const permission = await getPermission('Project', 123);
+ * const canEdit = hasEntityAccess(permission, 'edit');
+ *
+ * // With owner bypass
+ * const canEditAsOwner = hasEntityAccess(permission, 'edit', {
+ *   accessKeys: ['owner'],
+ * }); // true, owners bypass all checks
+ *
+ * // Check loading state
+ * if (permission.isLoading) {
+ *   return false; // Wait for permission to load
+ * }
+ * ```
+ */
+declare function hasEntityAccess(permission: EntityPermissionCheck | null | undefined, action: EntityAction, options?: {
+    accessKeys?: string[] | null;
+    isArchived?: boolean;
+    isSuspended?: boolean;
+}): boolean;
+/**
+ * Check if a user has any of the specified entity actions.
+ *
+ * @param permission - The permission check result
+ * @param actions - Array of actions to check for (OR logic)
+ * @param options - Additional options for the check
+ * @returns boolean - true if user has permission for any of the actions
+ *
+ * @example
+ * ```ts
+ * const canEditOrDelete = hasAnyEntityAccess(permission, ['edit', 'delete']);
+ * ```
+ */
+declare function hasAnyEntityAccess(permission: EntityPermissionCheck | null | undefined, actions: EntityAction[], options?: {
+    accessKeys?: string[] | null;
+    isArchived?: boolean;
+    isSuspended?: boolean;
+}): boolean;
+/**
+ * Check if a user has all of the specified entity actions.
+ *
+ * @param permission - The permission check result
+ * @param actions - Array of actions to check for (AND logic)
+ * @param options - Additional options for the check
+ * @returns boolean - true if user has permission for all of the actions
+ *
+ * @example
+ * ```ts
+ * // Check if user can edit AND delete (admin-like permissions)
+ * const isAdmin = hasAllEntityAccess(permission, ['edit', 'delete', 'share']);
+ * ```
+ */
+declare function hasAllEntityAccess(permission: EntityPermissionCheck | null | undefined, actions: EntityAction[], options?: {
+    accessKeys?: string[] | null;
+    isArchived?: boolean;
+    isSuspended?: boolean;
+}): boolean;
+/**
+ * Check if entity access was explicitly denied.
+ * Useful for distinguishing between "no permission" and "explicitly blocked".
+ *
+ * @param permission - The permission check result
+ * @returns boolean - true if access was explicitly denied
+ *
+ * @example
+ * ```ts
+ * const permission = await getPermission('Project', 123);
+ * if (isEntityAccessDenied(permission)) {
+ *   showBlockedMessage('You have been explicitly denied access to this project');
+ * }
+ * ```
+ */
+declare function isEntityAccessDenied(permission: EntityPermissionCheck | null | undefined): boolean;
+/**
+ * Type guard to check if permission data is loaded and available.
+ *
+ * @param permission - The permission check result
+ * @returns boolean - true if permission data is loaded
+ *
+ * @example
+ * ```ts
+ * const permission = usePermission('Project', projectId);
+ *
+ * if (!isPermissionLoaded(permission)) {
+ *   return <Spinner />;
+ * }
+ *
+ * // TypeScript knows permission is fully loaded here
+ * return permission.canEdit ? <Editor /> : <Viewer />;
+ * ```
+ */
+declare function isPermissionLoaded(permission: EntityPermissionCheck | null | undefined): permission is EntityPermissionCheck & {
+    isLoading: false;
+};
+
+export { hasAccess, hasAllAccess, hasAllEntityAccess, hasAnyAccess, hasAnyEntityAccess, hasEntityAccess, isEntityAccessDenied, isPermissionLoaded };