myITProcess API Client

Type-safe TypeScript client for the myITProcess Public API.

Installation

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

Quick Start

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

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

// 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

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

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

Users

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

Initiatives

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

Findings

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

Meetings

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

Recommendations

// 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:

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

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:

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:

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

2. Create API Client Instance

Create lib/myitprocess.ts:

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

// 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:

# 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:

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

Regenerating Types

When the myITProcess API changes, regenerate types:

# 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

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

# 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