@panoptic-it-solutions/zoho-projects-client 0.1.4 → 0.2.0

package/templates/commands/zoho-examples.md

@@ -0,0 +1,375 @@
+# Zoho Projects Client - Common Usage Examples
+
+## Setup
+
+```typescript
+import { createZohoProjectsClient } from '@panoptic-it-solutions/zoho-projects-client';
+import 'dotenv/config';
+
+const client = createZohoProjectsClient({
+  clientId: process.env.ZOHO_CLIENT_ID!,
+  clientSecret: process.env.ZOHO_CLIENT_SECRET!,
+  refreshToken: process.env.ZOHO_REFRESH_TOKEN!,
+  portalId: process.env.ZOHO_PORTAL_ID!,
+});
+```
+
+## Projects
+
+### List All Projects
+
+```typescript
+// Get first page
+const response = await client.projects.list();
+console.log(response.projects);
+
+// Get all projects (auto-paginate)
+const allProjects = await client.projects.listAll();
+
+// Iterate through all projects (memory-efficient)
+for await (const project of client.projects.iterate()) {
+  console.log(project.name);
+}
+
+// With filters
+const activeProjects = await client.projects.listAll({
+  status: 'active',
+});
+```
+
+### Create a Project
+
+```typescript
+const newProject = await client.projects.create({
+  name: 'New Website Redesign',
+  description: 'Complete redesign of company website',
+  start_date: '2025-01-15',
+  end_date: '2025-06-30',
+  status: 'active',
+});
+
+console.log('Created project:', newProject.projects[0].id_string);
+```
+
+### Update a Project
+
+```typescript
+await client.projects.update(projectId, {
+  name: 'Updated Project Name',
+  status: 'on_hold',
+});
+```
+
+### Delete a Project
+
+```typescript
+await client.projects.delete(projectId);
+```
+
+## Tasks
+
+### List Tasks in a Project
+
+```typescript
+const tasks = await client.tasks.list(projectId);
+
+// With filters
+const openTasks = await client.tasks.list(projectId, {
+  status: 'open',
+  owner: 'userId',
+});
+
+// Get all tasks
+const allTasks = await client.tasks.listAll(projectId);
+```
+
+### Create a Task
+
+```typescript
+const task = await client.tasks.create(projectId, {
+  name: 'Implement user authentication',
+  description: 'Add OAuth 2.0 login flow',
+  start_date: '2025-01-20',
+  end_date: '2025-01-25',
+  priority: 'high',
+  owners: ['userId1', 'userId2'],
+  tasklist_id: tasklistId,
+});
+```
+
+### Update a Task
+
+```typescript
+await client.tasks.update(projectId, taskId, {
+  status: 'completed',
+  percent_complete: 100,
+});
+```
+
+## Task Lists
+
+### Create a Task List
+
+```typescript
+const tasklist = await client.tasklists.create(projectId, {
+  name: 'Sprint 1 Tasks',
+  flag: 'internal',
+});
+```
+
+### List Task Lists
+
+```typescript
+const tasklists = await client.tasklists.list(projectId);
+```
+
+## Time Logs
+
+### Log Time
+
+```typescript
+await client.timelogs.create(projectId, {
+  task_id: taskId,
+  date: '2025-01-20',
+  hours: 2,
+  minutes: 30,
+  bill_status: 'Billable',
+  notes: 'Implemented login UI',
+});
+```
+
+### Get Time Logs for a Task
+
+```typescript
+const timelogs = await client.timelogs.list(projectId, {
+  task_id: taskId,
+});
+```
+
+## Issues/Bugs
+
+### Create a Bug
+
+```typescript
+const bug = await client.issues.create(projectId, {
+  title: 'Login button not working on mobile',
+  description: 'The login button is unresponsive on iOS Safari',
+  severity: 'major',
+  reproducible: 'Always',
+  module: 'Authentication',
+});
+```
+
+### List Bugs
+
+```typescript
+const bugs = await client.issues.list(projectId, {
+  status: 'open',
+});
+```
+
+## Comments
+
+### Add a Comment to a Task
+
+```typescript
+const taskComments = client.comments.forTask(projectId, taskId);
+
+await taskComments.create({
+  content: 'This task is blocked waiting for API access.',
+});
+
+// List comments
+const comments = await taskComments.list();
+```
+
+### Add a Comment to a Bug
+
+```typescript
+const bugComments = client.comments.forIssue(projectId, bugId);
+
+await bugComments.create({
+  content: 'Unable to reproduce this issue.',
+});
+```
+
+## Followers
+
+### Add Followers to a Task
+
+```typescript
+const taskFollowers = client.followers.forTask(projectId, taskId);
+
+await taskFollowers.add({
+  users: ['userId1', 'userId2'],
+});
+
+// List followers
+const followers = await taskFollowers.list();
+```
+
+## Users
+
+### List All Users
+
+```typescript
+const users = await client.users.listAll();
+
+for (const user of users) {
+  console.log(`${user.name} (${user.email})`);
+}
+```
+
+### Get a Specific User
+
+```typescript
+const user = await client.users.get(userId);
+```
+
+## Search
+
+### Global Search
+
+```typescript
+const results = await client.search.search({
+  search_term: 'authentication',
+  entity_type: 'task', // 'all', 'project', 'task', 'bug', etc.
+});
+
+for (const result of results.results || []) {
+  console.log(`${result.entity_type}: ${result.name}`);
+}
+```
+
+## Dashboards and Widgets
+
+### List Dashboards
+
+```typescript
+const dashboards = await client.dashboards.list();
+```
+
+### Get Dashboard Widgets
+
+```typescript
+const widgets = await client.dashboards.listWidgets(dashboardId);
+```
+
+## Error Handling
+
+```typescript
+import {
+  ZohoProjectsError,
+  ZohoRateLimitError,
+  ZohoAuthError,
+  ZohoNotFoundError,
+} from '@panoptic-it-solutions/zoho-projects-client';
+
+async function safeApiCall() {
+  try {
+    const project = await client.projects.get(projectId);
+    return project;
+  } catch (error) {
+    if (error instanceof ZohoNotFoundError) {
+      console.log('Project not found');
+      return null;
+    }
+    if (error instanceof ZohoRateLimitError) {
+      console.log(`Rate limited. Retry after ${error.retryAfter}ms`);
+      await new Promise(r => setTimeout(r, error.retryAfter));
+      return safeApiCall(); // Retry
+    }
+    if (error instanceof ZohoAuthError) {
+      console.log('Authentication failed - check credentials');
+      throw error;
+    }
+    if (error instanceof ZohoProjectsError) {
+      console.log(`API Error: ${error.message} (${error.code})`);
+      throw error;
+    }
+    throw error;
+  }
+}
+```
+
+## Batch Operations
+
+### Create Multiple Tasks
+
+```typescript
+async function createTasks(projectId: string, tasks: CreateTaskInput[]) {
+  const results = [];
+  for (const taskInput of tasks) {
+    const result = await client.tasks.create(projectId, taskInput);
+    results.push(result);
+  }
+  return results;
+}
+
+// Usage
+await createTasks(projectId, [
+  { name: 'Task 1', tasklist_id: tasklistId },
+  { name: 'Task 2', tasklist_id: tasklistId },
+  { name: 'Task 3', tasklist_id: tasklistId },
+]);
+```
+
+### Bulk Update Status
+
+```typescript
+async function completeAllTasks(projectId: string, taskIds: string[]) {
+  for (const taskId of taskIds) {
+    await client.tasks.update(projectId, taskId, {
+      status: 'completed',
+      percent_complete: 100,
+    });
+  }
+}
+```
+
+## Reports
+
+### Get Report Data
+
+```typescript
+const reports = await client.reports.list();
+
+// Execute a report
+const reportData = await client.reports.execute(reportId, {
+  start_date: '2025-01-01',
+  end_date: '2025-01-31',
+});
+
+for (const row of reportData.data) {
+  console.log(row);
+}
+```
+
+## Trash Management
+
+### List Deleted Items
+
+```typescript
+const trashedItems = await client.trash.list({
+  entity_type: 'task',
+});
+
+for (const item of trashedItems.trash || []) {
+  console.log(`${item.name} - deleted by ${item.deleted_person}`);
+}
+```
+
+### Restore a Deleted Item
+
+```typescript
+await client.trash.restore(itemId);
+```
+
+## Best Practices
+
+1. **Use listAll() for small datasets** - It loads all pages into memory
+2. **Use iterate() for large datasets** - Memory-efficient streaming
+3. **Handle rate limits** - Catch `ZohoRateLimitError` and retry
+4. **Use specific scopes** - Only request the OAuth scopes you need
+5. **Cache user data** - User lists don't change often
+6. **Batch operations carefully** - Zoho has rate limits per minute

package/templates/commands/zoho-projects.md

@@ -0,0 +1,183 @@
+# Zoho Projects API Reference
+
+This project uses `@panoptic-it-solutions/zoho-projects-client` - a TypeScript client for the Zoho Projects V3 API.
+
+## Client Initialization
+
+```typescript
+import { createZohoProjectsClient } from '@panoptic-it-solutions/zoho-projects-client';
+
+const client = createZohoProjectsClient({
+  clientId: process.env.ZOHO_CLIENT_ID!,
+  clientSecret: process.env.ZOHO_CLIENT_SECRET!,
+  refreshToken: process.env.ZOHO_REFRESH_TOKEN!,
+  portalId: process.env.ZOHO_PORTAL_ID!,
+  // Optional: specify data center (default: 'com')
+  // dataCenterExtension: 'eu' | 'in' | 'com.au' | 'jp' | 'com'
+});
+```
+
+## API Namespaces
+
+### Portal-Level APIs (no projectId required)
+
+| Namespace | Description | Methods |
+|-----------|-------------|---------|
+| `client.projects` | Projects CRUD | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.users` | Users management | `list`, `listAll`, `iterate`, `get` |
+| `client.tags` | Tags CRUD | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.roles` | Roles CRUD | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.profiles` | Profiles CRUD | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.clients` | Clients/Customers | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.contacts` | Contacts CRUD | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.groups` | Project Groups | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.leaves` | Leave management | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.teams` | Teams CRUD | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.dashboards` | Dashboards + widgets | `list`, `listAll`, `iterate`, `get`, `create`, `update`, `delete` |
+| `client.reports` | Reports + execute | `list`, `listAll`, `iterate`, `get`, `execute` |
+| `client.search` | Global search | `search` |
+| `client.trash` | Trash management | `list`, `listAll`, `iterate`, `restore`, `deletePermanently` |
+
+### Project-Scoped APIs (require projectId as first argument)
+
+| Namespace | Description | Methods |
+|-----------|-------------|---------|
+| `client.tasks` | Tasks CRUD | `list(projectId)`, `get(projectId, taskId)`, `create`, `update`, `delete` |
+| `client.tasklists` | Task Lists | `list(projectId)`, `get(projectId, tasklistId)`, `create`, `update`, `delete` |
+| `client.phases` | Milestones | `list(projectId)`, `get(projectId, phaseId)`, `create`, `update`, `delete` |
+| `client.issues` | Bugs/Issues | `list(projectId)`, `get(projectId, issueId)`, `create`, `update`, `delete` |
+| `client.forums` | Forums | `list(projectId)`, `get(projectId, forumId)`, `create`, `update`, `delete` |
+| `client.events` | Events/Calendar | `list(projectId)`, `get(projectId, eventId)`, `create`, `update`, `delete` |
+| `client.timelogs` | Time logs | `list(projectId)`, `get(projectId, timelogId)`, `create`, `update`, `delete` |
+| `client.attachments` | File attachments | `list(projectId)`, `upload`, `download`, `delete` |
+| `client.documents` | Documents + folders | `list(projectId)`, `get`, `create`, `update`, `delete`, `listFolders`, `createFolder` |
+
+### Polymorphic Sub-Resources
+
+Comments and followers can be attached to different entity types:
+
+```typescript
+// Comments on tasks
+const taskComments = client.comments.forTask(projectId, taskId);
+await taskComments.list();
+await taskComments.create({ content: 'My comment' });
+
+// Comments on issues/bugs
+const issueComments = client.comments.forIssue(projectId, issueId);
+await issueComments.list();
+
+// Followers on tasks
+const taskFollowers = client.followers.forTask(projectId, taskId);
+await taskFollowers.list();
+await taskFollowers.add({ users: ['userId1', 'userId2'] });
+```
+
+### Nested Resources
+
+Widgets are nested under dashboards:
+
+```typescript
+// List widgets for a dashboard
+const widgets = await client.dashboards.listWidgets(dashboardId);
+
+// Create a widget
+await client.dashboards.createWidget(dashboardId, {
+  name: 'Task Summary',
+  type: 'chart',
+});
+```
+
+## Common Patterns
+
+### Auto-Pagination
+
+```typescript
+// Get all items (auto-paginate through all pages)
+const allProjects = await client.projects.listAll();
+
+// Memory-efficient iteration (fetches pages as needed)
+for await (const project of client.projects.iterate()) {
+  console.log(project.name);
+}
+
+// With filters
+const openTasks = await client.tasks.listAll(projectId, {
+  status: 'open',
+});
+```
+
+### Error Handling
+
+```typescript
+import {
+  ZohoProjectsError,
+  ZohoRateLimitError,
+  ZohoAuthError,
+} from '@panoptic-it-solutions/zoho-projects-client';
+
+try {
+  await client.projects.get('invalid-id');
+} catch (error) {
+  if (error instanceof ZohoRateLimitError) {
+    // Rate limited - wait and retry
+    console.log(`Rate limited. Retry after ${error.retryAfter}ms`);
+  } else if (error instanceof ZohoAuthError) {
+    // Authentication failed - check credentials
+    console.log('Authentication failed:', error.message);
+  } else if (error instanceof ZohoProjectsError) {
+    // General API error
+    console.log('API error:', error.message, error.code);
+  }
+}
+```
+
+### Pagination Parameters
+
+```typescript
+// Manual pagination control
+const page1 = await client.projects.list({
+  index: 0,    // Start index (0-based)
+  range: 100,  // Items per page (max usually 200)
+});
+
+// Access pagination info
+console.log(page1.page_info?.has_next_page);
+console.log(page1.page_info?.total_count);
+```
+
+## Type Exports
+
+All types are exported from the main package:
+
+```typescript
+import type {
+  // Projects
+  Project,
+  CreateProjectInput,
+  UpdateProjectInput,
+
+  // Tasks
+  Task,
+  CreateTaskInput,
+  UpdateTaskInput,
+
+  // Common
+  ZohoPageInfo,
+  OwnerRef,
+
+  // And many more...
+} from '@panoptic-it-solutions/zoho-projects-client';
+```
+
+## Environment Variables
+
+Required environment variables:
+
+```bash
+ZOHO_CLIENT_ID=your_client_id
+ZOHO_CLIENT_SECRET=your_client_secret
+ZOHO_REFRESH_TOKEN=your_refresh_token
+ZOHO_PORTAL_ID=your_portal_id
+```
+
+See `/zoho-auth` for OAuth 2.0 setup instructions.