pilot-api

Official API client for Pilot - A modern workspace and collaboration platform.

Installation

npm install pilot-api
# or
yarn add pilot-api
# or
pnpm add pilot-api

Quick Start

import { createApiClient } from 'pilot-api';

// Create an API client instance
const api = createApiClient({
  baseUrl: 'https://your-pilot-instance.com',
  token: 'your-auth-token',
});

// Or use a dynamic token getter (useful for React/Next.js apps)
const api = createApiClient({
  baseUrl: 'https://your-pilot-instance.com',
  getToken: () => localStorage.getItem('authToken'),
});

Usage Examples

Spaces

// List all spaces
const { data, success } = await api.spaces.list();
if (success) {
  console.log(data.spaces);
}

// Create a new space
const result = await api.spaces.create({
  name: 'My Workspace',
  slug: 'my-workspace',
  description: 'A collaborative workspace',
});

// Get a specific space
const space = await api.spaces.get('my-workspace');

// Update a space
await api.spaces.update('my-workspace', {
  name: 'Updated Workspace Name',
});

// Delete a space
await api.spaces.delete('my-workspace');

Projects & Issues

// List projects in a space
const projects = await api.projects.list('my-workspace');

// Create a project
const project = await api.projects.create('my-workspace', {
  name: 'My Project',
  code: 'PROJ',
  description: 'Project description',
});

// List issues in a project
const issues = await api.issues.list('my-workspace', 'PROJ');

// Create an issue
const issue = await api.issues.create('my-workspace', 'PROJ', {
  title: 'Fix login bug',
  description: 'Users cannot login with SSO',
  priority: 'high',
  status: 'todo',
});

// Update an issue
await api.issues.update('my-workspace', 'PROJ', 'issue-id', {
  status: 'in_progress',
  assignee: 'user-id',
});

Chat & Messaging

// List conversations
const conversations = await api.chat.conversations.list('my-workspace');

// Create a conversation
const conversation = await api.chat.conversations.create('my-workspace', {
  type: 'private',
  participantIds: ['user-id-1', 'user-id-2'],
});

// Send a message
await api.chat.messages.create('my-workspace', 'conversation-id', {
  content: 'Hello, team!',
});

// List messages
const messages = await api.chat.messages.list('my-workspace', 'conversation-id', {
  limit: 50,
});

Channels & Posts (Forum)

// List channels
const channels = await api.channels.list('my-workspace');

// Create a channel
const channel = await api.channels.create('my-workspace', {
  name: 'announcements',
  description: 'Company announcements',
});

// Create a post
const post = await api.posts.create('my-workspace', 'announcements', {
  title: 'Welcome to the team!',
  content: 'We are excited to have you here...',
});

// React to a post
await api.posts.react('my-workspace', 'announcements', 'post-id', {
  type: 'upvote',
});

Wiki

// List wiki pages
const pages = await api.wiki.list('my-workspace');

// Create a wiki page
const page = await api.wiki.create('my-workspace', {
  title: 'Getting Started',
  content: '# Welcome to our wiki...',
});

// Update a wiki page
await api.wiki.update('my-workspace', 'page-id', {
  content: '# Updated content...',
});

Email

// List emails
const emails = await api.mail.list('my-workspace', { label: 'inbox' });

// Send an email
await api.mail.send('my-workspace', {
  to: ['[email protected]'],
  subject: 'Hello',
  htmlBody: '<p>Hello World!</p>',
});

Meetings

// List meeting rooms
const rooms = await api.meetings.list('my-workspace');

// Create a meeting room
const room = await api.meetings.create('my-workspace', {
  name: 'Team Standup',
  type: 'video',
});

// Join a meeting
const { token, serverUrl } = await api.meetings.join('my-workspace', 'room-id');

Notifications

// List notifications
const notifications = await api.notifications.list({ limit: 20 });

// Mark a notification as read
await api.notifications.markRead('notification-id');

// Mark all notifications as read
await api.notifications.markAllRead();

User Profile

// Get current user
const user = await api.user.me();

// Update profile
await api.user.update({
  fullName: 'John Doe',
  bio: 'Software Engineer',
});

// Change password
await api.user.changePassword({
  currentPassword: 'old-password',
  newPassword: 'new-password',
});

API Response Format

All API methods return a promise that resolves to an ApiResponse<T> object:

type ApiResponse<T> =
  | { success: true; data: T }
  | { success: false; error: string };

Example usage with error handling:

const result = await api.spaces.list();

if (result.success) {
  // TypeScript knows result.data is available
  console.log(result.data.spaces);
} else {
  // Handle error
  console.error(result.error);
}

TypeScript Support

This package is written in TypeScript and provides full type definitions. All request/response types are exported:

import {
  createApiClient,
  type ApiClient,
  type ApiClientConfig,
  type SpaceInfo,
  type ProjectInfo,
  type IssueInfo,
  type IssueStatus,
  type IssuePriority,
  // ... and many more
} from 'pilot-api';

Configuration Options

interface ApiClientConfig {
  baseUrl?: string;              // Base URL of your Pilot instance
  headers?: Record<string, string>; // Custom headers to include in requests
  token?: string;                // Static authentication token
  getToken?: () => string | null | Promise<string | null>; // Dynamic token getter
}

License

MIT