wulf-pulse/README.md

# Autotask API Integration Dashboard

A modern Next.js application for interacting with the Autotask PSA REST API, built with React, TypeScript, shadcn/ui, and Tailwind CSS.

## Features

- **Dashboard Overview** - View tickets, tasks, and company information
- **Ticket Management** - List, filter, and manage support tickets
- **Task Tracking** - Monitor and update project tasks
- **Company Selector** - Filter data by company
- **Resource Management** - Filter by assigned resources
- **Modern UI** - Beautiful interface built with shadcn/ui components
- **Dark Mode Support** - Automatic dark/light theme
- **Real-time Updates** - Fetch latest data from Autotask API
- **Secure Authentication** - API credentials stored in environment variables

## Tech Stack

- **Framework**: Next.js 15 with App Router
- **Language**: TypeScript
- **Styling**: Tailwind CSS v4
- **UI Components**: shadcn/ui
- **Icons**: Lucide React
- **Date Handling**: date-fns
- **API Integration**: Native fetch with custom client

## Prerequisites

Before you begin, ensure you have:

1. Node.js 18+ installed
2. Autotask API credentials:
   - API Username (format: `apiuser@YOURDOMAIN.COM`)
   - API Secret/Password
   - API Integration Code
   - API Base URL (e.g., `https://webservices1.autotask.net/atservicesrest/v1.0`)

## Installation

1. Clone the repository and navigate to the app directory:
```bash
cd /Users/lorentz/projects/PSA-Utils/autotask-app
```

2. Install dependencies:
```bash
npm install
```

3. Create a `.env.local` file in the root directory:
```env
# Autotask API Configuration
AUTOTASK_API_URL=https://webservices1.autotask.net/atservicesrest/v1.0
AUTOTASK_USERNAME=your-api-username@yourdomain.com
AUTOTASK_SECRET=your-api-password
AUTOTASK_API_INTEGRATION_CODE=your-tracking-code
```

4. Run the development server:
```bash
npm run dev
```

5. Open [http://localhost:3000](http://localhost:3000) in your browser

## Project Structure

```
autotask-app/
├── app/
│   ├── api/              # API route handlers
│   │   ├── tickets/      # Ticket endpoints
│   │   ├── tasks/        # Task endpoints
│   │   ├── companies/    # Company endpoints
│   │   ├── resources/    # Resource endpoints
│   │   └── picklists/    # Picklist endpoints
│   └── page.tsx          # Main dashboard page
├── components/
│   ├── tickets/          # Ticket-related components
│   ├── tasks/            # Task-related components
│   ├── companies/        # Company-related components
│   └── ui/               # shadcn/ui components
├── lib/
│   ├── services/         # API client and services
│   │   ├── autotask-client.ts
│   │   └── autotask-factory.ts
│   ├── types/            # TypeScript type definitions
│   │   └── autotask.ts
│   └── hooks/            # Custom React hooks
│       └── use-api.ts
└── public/               # Static assets
```

## API Endpoints

The application provides the following API routes:

- `GET /api/tickets` - Fetch tickets (with optional filters)
- `POST /api/tickets` - Create a new ticket
- `GET /api/tasks` - Fetch tasks (with optional filters)
- `POST /api/tasks` - Create a new task
- `GET /api/companies` - Fetch all active companies
- `GET /api/resources` - Fetch resources/users
- `GET /api/picklists` - Fetch picklist values for dropdowns

## Key Features Implementation

### Rate Limiting
The API client includes built-in rate limiting (10 requests/second) to comply with Autotask API limits.

### Error Handling
Comprehensive error handling with user-friendly error messages and retry capabilities.

### Type Safety
Full TypeScript support with detailed type definitions for all Autotask entities.

### Responsive Design
Mobile-friendly interface that works on all device sizes.

## Development

### Adding New Features

1. **New API Endpoints**: Add route handlers in `app/api/`
2. **New Components**: Create components in `components/`
3. **New Entity Types**: Update types in `lib/types/autotask.ts`
4. **New API Methods**: Extend `lib/services/autotask-client.ts`

### Testing

Run the development server and test with your Autotask sandbox environment:
```bash
npm run dev
```

### Building for Production

```bash
npm run build
npm start
```

## Security Considerations

- Never commit `.env.local` or any file containing API credentials
- Use environment variables for all sensitive configuration
- Implement proper authentication for production deployment
- Consider adding user authentication layer
- Use HTTPS in production

## Common Issues & Solutions

### API Connection Issues
- Verify your API credentials are correct
- Check the API URL matches your Autotask zone
- Ensure your API user has appropriate permissions

### Rate Limiting
- The client automatically handles rate limiting
- If you encounter 429 errors, the client will retry

### CORS Issues
- API routes act as a proxy to avoid CORS issues
- All Autotask API calls go through Next.js API routes

## Future Enhancements

- [ ] Add Redis caching for improved performance
- [ ] Implement real-time updates with WebSockets
- [ ] Add attachment upload functionality
- [ ] Create ticket/task editing forms
- [ ] Add user authentication and session management
- [ ] Implement advanced search and filtering
- [ ] Add data export functionality
- [ ] Create dashboard widgets and analytics

## Contributing

Feel free to submit issues and enhancement requests!

## License

This project is for internal use. Please refer to your organization's policies.

## Support

For issues related to:
- **Autotask API**: Consult the [Autotask REST API Documentation](https://ww1.autotask.net/help/DeveloperHelp/Content/APIs/REST/REST_API_Home.htm)
- **Application Issues**: Create an issue in this repository

---

Built with ❤️ using Next.js, React, and shadcn/ui