npm package: @panoptic-it-solutions/myitprocess-client
Description: Type-safe API client for myITProcess Public API
Latest version: 1.0.5

# myITProcess API Client

Type-safe TypeScript client for the [myITProcess Public API](https://helpdesk.kaseya.com/hc/en-gb/articles/4438175877521-myITprocess-API).

## Installation

```bash
npm install @panoptic-it-solutions/myitprocess-client
```

## Quick Start

```typescript
import { createMyITProcessClient } from '@panoptic-it-solutions/myitprocess-client';

const client = createMyITProcessClient({
  baseUrl: 'https://your-instance.myitprocess.com',
  apiKey: process.env.MYITPROCESS_API_KEY!,
});

// Get all clients
const { data, error } = await client.clients.list();

if (error) {
  console.error('API Error:', error);
} else {
  console.log('Clients:', data?.items);
}
```

## Configuration

```typescript
import { createMyITProcessClient } from '@panoptic-it-solutions/myitprocess-client';

const client = createMyITProcessClient({
  // Required
  baseUrl: 'https://your-instance.myitprocess.com',
  apiKey: 'your-api-key',

  // Optional: default pagination for all requests
  defaultPagination: {
    pageSize: 50,
    page: 1,
  },

  // Optional: additional fetch options
  fetchOptions: {
    // Any standard RequestInit options
  },
});
```

## API Methods

### Clients

```typescript
// List all clients (active and inactive)
const { data } = await client.clients.list();

// With filtering, sorting, and pagination
const { data } = await client.clients.list({
  queryFilters: [
    { field: 'isActive', predicate: 'equal', condition: 'true' }
  ],
  sortingRules: [
    { field: 'name', direction: 'asc' }
  ],
  paginationRule: { page: 1, pageSize: 25 },
});
```

### Reviews

```typescript
// List active reviews
const { data } = await client.reviews.list();

// Get categories overdue for review
const { data } = await client.reviews.categoriesOverdue();
```

### Users

```typescript
const { data } = await client.users.list();
```

### Initiatives

```typescript
const { data } = await client.initiatives.list();
```

### Findings

```typescript
const { data } = await client.findings.list();
```

### Meetings

```typescript
const { data } = await client.meetings.list();
```

### Recommendations

```typescript
// List all recommendations
const { data } = await client.recommendations.list();

// Get configurations for a specific recommendation
const { data } = await client.recommendations.configurations(123);
```

## Using Query Helpers

The client includes helper functions for building queries:

```typescript
import {
  createMyITProcessClient,
  buildFilters,
  buildSorting,
  buildPagination,
} from '@panoptic-it-solutions/myitprocess-client';

const client = createMyITProcessClient({ ... });

const { data } = await client.recommendations.list({
  queryFilters: buildFilters([
    { field: 'status', predicate: 'equal', condition: 'Accepted' },
    { field: 'priority', predicate: 'equal', condition: 'High', operator: 'and' },
  ]),
  sortingRules: buildSorting([
    { field: 'budgetMonth', direction: 'desc' },
  ]),
  paginationRule: buildPagination(1, 50),
});
```

### Filter Predicates

- `equal` - Exact match
- `notEqual` - Not equal
- `greaterThan` - Greater than (for dates/numbers)
- `lessThan` - Less than (for dates/numbers)
- `contains` - Contains substring (for text fields)

### Filter Operators

- `and` - All conditions must match (default)
- `or` - Any condition can match

## Using Types

```typescript
import type {
  Client,
  Recommendation,
  RecommendationStatus,
  Meeting,
  MeetingStatus,
} from '@panoptic-it-solutions/myitprocess-client';

function processRecommendation(rec: Recommendation) {
  const status: RecommendationStatus = rec.status ?? 'NotDiscussed';
  // ...
}
```

### Available Types

**Entities:**
- `Client`, `ClientBase`
- `Review`, `ReviewBase`
- `User`, `UserBase`
- `Initiative`, `InitiativeBase`
- `Finding`
- `Meeting`
- `Recommendation`, `RecommendationFeedback`
- `Configuration`
- `Category`

**Enums:**
- `ReviewStatus`: `'New' | 'EngineerInProgress' | 'EngineerComplete' | 'VcioInProgress' | 'Complete'`
- `MeetingStatus`: `'Upcoming' | 'InProgress' | 'Past' | 'Cancelled'`
- `RecommendationType`: `'Project' | 'TimeMaterial' | 'Maintenance' | 'Strategic' | 'BusinessGoal'`
- `RecommendationStatus`: `'NotDiscussed' | 'Accepted' | 'Rejected' | 'OnHold' | 'InProgress' | 'Completed'`
- `RecommendationPriority`: `'NoPriority' | 'Low' | 'Medium' | 'High'`
- `ResponsibleParty`: `'Us' | 'You' | 'ThirdParty'`
- `FindingType`: `'Legacy' | 'AssignedToRecommendation' | 'UnassignedReviewFinding'`

**Query Types:**
- `QueryFilter`, `QueryFilters`
- `SortingRule`, `SortingRules`
- `PaginationRule`, `PaginationInfo`

## Raw Client Access

For advanced use cases, access the underlying openapi-fetch client:

```typescript
const client = createMyITProcessClient({ ... });

// Direct access to openapi-fetch client
const { data } = await client.raw.GET('/public-api/v1/clients', {
  params: {
    query: {
      paginationRule: { page: 1, pageSize: 10 },
    },
  },
});
```

## Next.js Integration

### 1. Environment Variables

Create `.env.local`:

```env
MYITPROCESS_API_KEY=your-api-key-here
MYITPROCESS_BASE_URL=https://your-instance.myitprocess.com
```

### 2. Create API Client Instance

Create `lib/myitprocess.ts`:

```typescript
import { createMyITProcessClient } from '@panoptic-it-solutions/myitprocess-client';

export const myitprocess = createMyITProcessClient({
  baseUrl: process.env.MYITPROCESS_BASE_URL!,
  apiKey: process.env.MYITPROCESS_API_KEY!,
  defaultPagination: { pageSize: 100, page: 1 },
});
```

### 3. Use in Server Components

```typescript
// app/clients/page.tsx
import { myitprocess } from '@/lib/myitprocess';

export default async function ClientsPage() {
  const { data, error } = await myitprocess.clients.list();

  if (error) {
    return <div>Error loading clients</div>;
  }

  return (
    <ul>
      {data?.items?.map((client) => (
        <li key={client.id}>{client.name}</li>
      ))}
    </ul>
  );
}
```

### 4. Copy Types for AI Visibility

To make types visible to AI tools in your Next.js project:

```bash
# From the myitprocess-client directory
./scripts/copy-types.sh ../your-nextjs-project
```

This copies the generated types to `src/types/myitprocess-api.d.ts`.

Then you can import types directly:

```typescript
import type { Client, Recommendation } from '@/types/myitprocess-api';
```

## Regenerating Types

When the myITProcess API changes, regenerate types:

```bash
# Update the myitprocess-api.yaml file with the new spec, then:
npm run generate-types

# Or rebuild everything:
npm run build
```

## Rate Limiting

The myITProcess API has a throttling limit of **50 requests per minute** per IT Provider. Consider implementing rate limiting in your application if making many requests.

## Error Handling

```typescript
const { data, error, response } = await client.clients.list();

if (error) {
  // error is typed based on the OpenAPI spec
  // Could be ValidationErrors (400), Error (401/500)
  console.error('Status:', response?.status);
  console.error('Error:', error);
}
```

## Development

```bash
# Install dependencies
npm install

# Generate types from OpenAPI spec
npm run generate-types

# Build the package
npm run build

# Type check
npm run typecheck
```

## License

MIT