npm package: @kerko/permissions
Description: Shared permission system for Kerko.com
Author: Kerko Team
Latest version: 1.3.0

# @kerko/permissions

Shared permission system for Kerko.com applications.

## Overview

This package provides a centralized permission system that ensures consistency between frontend and backend services. It defines roles, permissions, and helper functions for access control.

## Installation

```bash
npm install @kerko/permissions
```

## Usage

### Basic Permission Checking

```typescript
import { hasPermission, canPerformAction, getUserRole } from '@kerko/permissions';

const user = { isAdmin: true, id: 'user123' };
const role = getUserRole(user); // 'admin'

// Check if user has a specific permission
const canViewAll = hasPermission(role, 'claims:view_all'); // true

// Check if user can perform action on a resource
const canEditOwn = canPerformAction(role, 'claims:edit_own', 'user123', 'user123'); // true
```

### Backend Service

```typescript
import { PermissionsService } from '@kerko/permissions';

// Check permissions
if (!PermissionsService.hasPermission(user, 'claims:approve')) {
  throw new Error('Permission denied');
}

// Require permissions (throws if not allowed)
PermissionsService.requirePermission(user, 'claims:approve');
PermissionsService.requireAction(user, 'notes:delete_own', noteOwnerId);
```

### Frontend React Hook

```typescript
import { usePermissions } from '@kerko/permissions';

function MyComponent() {
  const { user } = useMe();
  const { hasPermission, canPerformAction, isAdmin } = usePermissions(user);
  
  return (
    <div>
      {hasPermission('notes:add_own') && <AddNoteButton />}
      {isAdmin && <AdminPanel />}
    </div>
  );
}
```

## Roles

- **user**: Basic user with limited access
- **admin**: Administrator with management capabilities
- **super_admin**: Full system access

## Permissions

### Claims
- `claims:create` - Create new claims
- `claims:view_own` - View own claims
- `claims:view_all` - View all claims
- `claims:edit_own` - Edit own claims
- `claims:edit_all` - Edit any claims
- `claims:delete_own` - Delete own claims
- `claims:delete_all` - Delete any claims
- `claims:review` - Review claims
- `claims:approve` - Approve claims
- `claims:reject` - Reject claims
- `claims:force_approve` - Force approve (super admin)
- `claims:force_reject` - Force reject (super admin)

### Notes
- `notes:add_own` - Add notes to own claims
- `notes:add_all` - Add notes to any claim
- `notes:view_own` - View notes on own claims
- `notes:view_all` - View all notes
- `notes:delete_own` - Delete own notes
- `notes:delete_all` - Delete any notes

### Documents
- `documents:upload` - Upload documents
- `documents:view_own` - View own documents
- `documents:view_all` - View all documents
- `documents:verify` - Verify documents
- `documents:download` - Download documents

### Admin
- `admin:access` - Access admin panel
- `admin:users` - Manage users
- `admin:companies` - Manage companies
- `admin:audits` - View audit logs
- `admin:settings` - Manage settings

### System
- `system:manage_claims` - System-level claim management
- `system:manage_users` - System-level user management
- `system:manage_companies` - System-level company management
- `system:view_audits` - View system audit logs
- `system:manage_settings` - Manage system settings

## Development

```bash
# Build the package
npm run build

# Watch for changes
npm run dev

# Clean build artifacts
npm run clean
```