@panoptic-it-solutions/zoho-projects-client 0.2.4 → 0.2.6

package/dist/types/workdrive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workdrive.d.ts","sourceRoot":"","sources":["../../src/types/workdrive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAmBhB,CAAC;AAEjB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAE1B,CAAC;AAEjB,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;GAEG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAQtB,CAAC;AAEjB,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAMhB,CAAC;AAEjB,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE;;GAEG;AACH,eAAO,MAAM,0BAA0B;IACrC,oCAAoC;;IAEpC,wDAAwD;;IAExD,sEAAsE;;;;;;;;;;EAEtE,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

package/dist/types/workdrive.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+// ─────────────────────────────────────────────────────────────────────────────
+// WORKDRIVE SCHEMAS
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * WorkDrive file upload response
+ */
+export const WorkDriveFileSchema = z.object({
+    id: z.string(),
+    type: z.string().optional(),
+    attributes: z.object({
+        name: z.string(),
+        type: z.string().optional(),
+        extn: z.string().optional(),
+        resource_id: z.string().optional(),
+        parent_id: z.string().optional(),
+        storage_info: z.object({
+            size: z.string().optional(),
+            files_count: z.string().optional(),
+            folders_count: z.string().optional(),
+        }).optional(),
+        download_url: z.string().optional(),
+        permalink: z.string().optional(),
+        created_time: z.string().optional(),
+        modified_time: z.string().optional(),
+    }).passthrough(),
+}).passthrough();
+/**
+ * WorkDrive upload response schema
+ */
+export const WorkDriveUploadResponseSchema = z.object({
+    data: z.array(WorkDriveFileSchema),
+}).passthrough();
+/**
+ * WorkDrive team folder schema
+ */
+export const WorkDriveTeamFolderSchema = z.object({
+    id: z.string(),
+    type: z.string().optional(),
+    attributes: z.object({
+        name: z.string(),
+        is_default: z.boolean().optional(),
+        parent_id: z.string().optional(),
+    }).passthrough(),
+}).passthrough();
+/**
+ * WorkDrive team schema
+ */
+export const WorkDriveTeamSchema = z.object({
+    id: z.string(),
+    type: z.string().optional(),
+    attributes: z.object({
+        name: z.string(),
+    }).passthrough(),
+}).passthrough();
+// ─────────────────────────────────────────────────────────────────────────────
+// INPUT SCHEMAS
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Input for uploading a file to WorkDrive
+ */
+export const WorkDriveUploadInputSchema = z.object({
+    /** Parent folder ID in WorkDrive */
+    parent_id: z.string(),
+    /** Optional custom filename (URL-encoded with UTF-8) */
+    filename: z.string().optional(),
+    /** If true, overwrites existing file with same name as new version */
+    override_name_exist: z.boolean().optional(),
+});
+//# sourceMappingURL=workdrive.js.map

package/dist/types/workdrive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workdrive.js","sourceRoot":"","sources":["../../src/types/workdrive.ts"],"names":[],"mappings":"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"}

package/dist/utils/pagination.d.ts

@@ -27,19 +27,19 @@ export interface AutoPaginateOptions {
 /**
  * Create an async generator that automatically handles pagination
  *
- * Usage:
+ * Usage (V3 API - page-based):
  * ```ts
- * for await (const project of autoPaginate((index) =>
- *   client.projects.list({ index, range: 100 })
+ * for await (const project of autoPaginate((page, per_page) =>
+ *   client.projects.list({ page, per_page })
  * )) {
  *   console.log(project);
  * }
  * ```
  *
- * @param fetchPage Function that fetches a page given the index (0-based)
+ * @param fetchPage Function that fetches a page given page number (1-based) and page size
  * @param options Pagination options
  */
-export declare function autoPaginate<T>(fetchPage: (index: number, range: number) => Promise<PaginatedResponse<T>>, options?: AutoPaginateOptions): AsyncGenerator<T, void, unknown>;
+export declare function autoPaginate<T>(fetchPage: (page: number, per_page: number) => Promise<PaginatedResponse<T>>, options?: AutoPaginateOptions): AsyncGenerator<T, void, unknown>;
 /**
  * Collect all items from an async generator into an array
  *
@@ -50,10 +50,10 @@ export declare function autoPaginate<T>(fetchPage: (index: number, range: number
  */
 export declare function collectAll<T>(generator: AsyncGenerator<T, void, unknown>): Promise<T[]>;
 /**
- * Helper to create pagination params for Zoho API
+ * Helper to create pagination params for Zoho V3 API
  */
-export declare function createPaginationParams(index?: number, range?: number): {
-    index: number;
-    range: number;
+export declare function createPaginationParams(page?: number, per_page?: number): {
+    page: number;
+    per_page: number;
 };
 //# sourceMappingURL=pagination.d.ts.map

package/dist/utils/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAuB,YAAY,CAAC,CAAC,EACnC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAC1E,OAAO,GAAE,mBAAwB,GAChC,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAqClC;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,SAAS,EAAE,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAC1C,OAAO,CAAC,CAAC,EAAE,CAAC,CAMd;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,GAAE,MAAU,EACjB,KAAK,GAAE,MAA0B,GAChC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAKlC"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAuB,YAAY,CAAC,CAAC,EACnC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAC5E,OAAO,GAAE,mBAAwB,GAChC,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAqClC;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,SAAS,EAAE,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAC1C,OAAO,CAAC,CAAC,EAAE,CAAC,CAMd;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,GAAE,MAAU,EAChB,QAAQ,GAAE,MAA0B,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKpC"}

package/dist/utils/pagination.js

@@ -10,26 +10,26 @@ export const MAX_PAGE_SIZE = 200;
 /**
  * Create an async generator that automatically handles pagination
  *
- * Usage:
+ * Usage (V3 API - page-based):
  * ```ts
- * for await (const project of autoPaginate((index) =>
- *   client.projects.list({ index, range: 100 })
+ * for await (const project of autoPaginate((page, per_page) =>
+ *   client.projects.list({ page, per_page })
  * )) {
  *   console.log(project);
  * }
  * ```
  *
- * @param fetchPage Function that fetches a page given the index (0-based)
+ * @param fetchPage Function that fetches a page given page number (1-based) and page size
  * @param options Pagination options
  */
 export async function* autoPaginate(fetchPage, options = {}) {
     const pageSize = Math.min(options.pageSize ?? DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE);
     const maxItems = options.maxItems ?? Infinity;
-    let index = 0;
+    let page = 1; // V3 API uses 1-based pages
     let itemsYielded = 0;
     let hasMore = true;
     while (hasMore && itemsYielded < maxItems) {
-        const response = await fetchPage(index, pageSize);
+        const response = await fetchPage(page, pageSize);
         const items = response.data;
         if (items.length === 0) {
             // No more items
@@ -53,7 +53,7 @@ export async function* autoPaginate(fetchPage, options = {}) {
         }
         else {
             // Move to next page
-            index += pageSize;
+            page++;
         }
     }
 }
@@ -73,12 +73,12 @@ export async function collectAll(generator) {
     return items;
 }
 /**
- * Helper to create pagination params for Zoho API
+ * Helper to create pagination params for Zoho V3 API
  */
-export function createPaginationParams(index = 0, range = DEFAULT_PAGE_SIZE) {
+export function createPaginationParams(page = 1, per_page = DEFAULT_PAGE_SIZE) {
     return {
-        index,
-        range: Math.min(range, MAX_PAGE_SIZE),
+        page,
+        per_page: Math.min(per_page, MAX_PAGE_SIZE),
     };
 }
 //# sourceMappingURL=pagination.js.map

package/dist/utils/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAoBjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,YAAY,CACjC,SAA0E,EAC1E,UAA+B,EAAE;IAEjC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,iBAAiB,EAAE,aAAa,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC;IAE9C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,OAAO,GAAG,IAAI,CAAC;IAEnB,OAAO,OAAO,IAAI,YAAY,GAAG,QAAQ,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;QAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,gBAAgB;YAChB,OAAO,GAAG,KAAK,CAAC;YAChB,MAAM;QACR,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,YAAY,IAAI,QAAQ,EAAE,CAAC;gBAC7B,OAAO;YACT,CAAC;YACD,MAAM,IAAI,CAAC;YACX,YAAY,EAAE,CAAC;QACjB,CAAC;QAED,oCAAoC;QACpC,IAAI,QAAQ,CAAC,QAAQ,EAAE,aAAa,KAAK,KAAK,EAAE,CAAC;YAC/C,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;YACnC,wDAAwD;YACxD,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,oBAAoB;YACpB,KAAK,IAAI,QAAQ,CAAC;QACpB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,SAA2C;IAE3C,MAAM,KAAK,GAAQ,EAAE,CAAC;IACtB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAgB,CAAC,EACjB,QAAgB,iBAAiB;IAEjC,OAAO;QACL,KAAK;QACL,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC;KACtC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAoBjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,YAAY,CACjC,SAA4E,EAC5E,UAA+B,EAAE;IAEjC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,iBAAiB,EAAE,aAAa,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC;IAE9C,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,4BAA4B;IAC1C,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,OAAO,GAAG,IAAI,CAAC;IAEnB,OAAO,OAAO,IAAI,YAAY,GAAG,QAAQ,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;QAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,gBAAgB;YAChB,OAAO,GAAG,KAAK,CAAC;YAChB,MAAM;QACR,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,YAAY,IAAI,QAAQ,EAAE,CAAC;gBAC7B,OAAO;YACT,CAAC;YACD,MAAM,IAAI,CAAC;YACX,YAAY,EAAE,CAAC;QACjB,CAAC;QAED,oCAAoC;QACpC,IAAI,QAAQ,CAAC,QAAQ,EAAE,aAAa,KAAK,KAAK,EAAE,CAAC;YAC/C,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;YACnC,wDAAwD;YACxD,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,oBAAoB;YACpB,IAAI,EAAE,CAAC;QACT,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,SAA2C;IAE3C,MAAM,KAAK,GAAQ,EAAE,CAAC;IACtB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAe,CAAC,EAChB,WAAmB,iBAAiB;IAEpC,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panoptic-it-solutions/zoho-projects-client",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "TypeScript client for Zoho Projects V3 API with OAuth 2.0 and rate limiting",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:integration": "vitest run --config vitest.integration.config.ts",
+    "oauth": "npx tsx scripts/get-refresh-token.ts",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "keywords": [
@@ -55,6 +56,7 @@
     "@faker-js/faker": "^9.3.0",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^2.1.0",
+    "dotenv": "^17.2.3",
     "msw": "^2.7.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/templates/CLAUDE.md

@@ -19,6 +19,9 @@ const client = createZohoProjectsClient({
   clientSecret: process.env.ZOHO_CLIENT_SECRET!,
   refreshToken: process.env.ZOHO_REFRESH_TOKEN!,
   portalId: process.env.ZOHO_PORTAL_ID!,
+  // For EU region:
+  apiUrl: 'https://projectsapi.zoho.eu',
+  accountsUrl: 'https://accounts.zoho.eu',
 });
 ```
 
@@ -29,8 +32,173 @@ ZOHO_CLIENT_ID=     # OAuth client ID from Zoho API Console
 ZOHO_CLIENT_SECRET= # OAuth client secret
 ZOHO_REFRESH_TOKEN= # Refresh token from OAuth flow
 ZOHO_PORTAL_ID=     # Your Zoho Projects portal ID
+
+# Optional - Region URLs (defaults to US)
+ZOHO_API_URL=https://projectsapi.zoho.eu
+ZOHO_ACCOUNTS_URL=https://accounts.zoho.eu
+```
+
+## Required OAuth Scopes
+
+For full V3 API functionality:
+```
+ZohoProjects.projects.ALL,ZohoProjects.tasks.ALL,ZohoProjects.tasklists.ALL,ZohoProjects.portals.READ,ZohoProjects.users.ALL,ZohoProjects.timesheets.ALL,ZohoProjects.bugs.ALL,ZohoProjects.milestones.ALL,ZohoProjects.events.ALL,ZohoProjects.forums.ALL,ZohoProjects.documents.ALL,ZohoProjects.tags.ALL,ZohoProjects.status.READ,ZohoProjects.search.READ
+```
+
+**For file attachments (requires WorkDrive integration):**
+```
+ZohoPC.files.ALL,WorkDrive.team.ALL,WorkDrive.workspace.ALL,WorkDrive.files.ALL,WorkDrive.teamfolders.ALL
 ```
 
+Use `scripts/get-refresh-token.ts` to generate a token with all scopes. This script will open a browser window for OAuth authorization and automatically request all required scopes.
+
+---
+
+## File Attachment Workflow (AI Agent Instructions)
+
+Zoho Projects uses **WorkDrive** for file storage. There are two methods to attach files to tasks:
+
+### Method 1: Simple Direct Upload (Recommended)
+
+Use the legacy `/restapi/` endpoint with `uploaddoc` form field. This is the **simplest and most reliable** method - it handles WorkDrive upload and task association in a single request.
+
+#### Required OAuth Scopes
+
+| Scope | Purpose |
+|-------|---------|
+| `ZohoProjects.tasks.ALL` | Task operations |
+| `ZohoProjects.documents.ALL` | Document access |
+| `ZohoPC.files.ALL` | Attachments API |
+
+#### Upload File to Task
+
+```typescript
+import FormData from 'form-data';
+import axios from 'axios';
+
+const formData = new FormData();
+formData.append('uploaddoc', fileBuffer, {
+  filename: 'test.txt',
+  contentType: 'text/plain'
+});
+
+const response = await axios.post(
+  `https://projectsapi.zoho.eu/restapi/portal/${portalId}/projects/${projectId}/tasks/${taskId}/attachments/`,
+  formData,
+  {
+    headers: {
+      Authorization: `Zoho-oauthtoken ${accessToken}`,
+      ...formData.getHeaders()
+    }
+  }
+);
+
+// Response contains the attachment with WorkDrive file ID
+const attachment = response.data.thirdparty_attachments[0];
+console.log('Attachment ID:', attachment.attachment_id);
+console.log('WorkDrive File ID:', attachment.third_party_file_id);
+```
+
+#### List Task Attachments
+
+```typescript
+// Via V3 API (preferred)
+const listRes = await axios.get(
+  `https://projectsapi.zoho.eu/api/v3/portal/${portalId}/projects/${projectId}/attachments`,
+  {
+    params: { entity_type: 'task', entity_id: taskId },
+    headers: { Authorization: `Zoho-oauthtoken ${accessToken}` }
+  }
+);
+// V3 returns { attachment: [...] } (singular key)
+const attachments = listRes.data.attachment || [];
+```
+
+### Method 2: Manual WorkDrive Upload (Advanced)
+
+For more control over the upload process, you can upload to WorkDrive first, then register with Zoho Projects.
+
+#### Additional OAuth Scopes Required
+
+| Scope | Purpose |
+|-------|---------|
+| `WorkDrive.team.ALL` | Access WorkDrive teams |
+| `WorkDrive.workspace.ALL` | Access workspaces |
+| `WorkDrive.files.ALL` | Upload/manage files |
+| `WorkDrive.teamfolders.ALL` | Access team folders |
+
+#### Step 1: Get WorkDrive User Info
+```typescript
+const userRes = await axios.get('https://workdrive.zoho.eu/api/v1/users/me', {
+  headers: {
+    Authorization: `Zoho-oauthtoken ${accessToken}`,
+    Accept: 'application/vnd.api+json'
+  }
+});
+const preferredTeamId = userRes.data.data.attributes.preferred_team_id;
+```
+
+#### Step 2: Find the "Zoho Projects" Team Folder
+```typescript
+const foldersRes = await axios.get(
+  `https://workdrive.zoho.eu/api/v1/teams/${preferredTeamId}/teamfolders`,
+  { headers: workdriveHeaders }
+);
+
+const projectsFolder = foldersRes.data.data.find(
+  f => f.attributes.name === 'Zoho Projects'
+);
+const projectsFolderId = projectsFolder.id;
+```
+
+#### Step 3: Find the Project-Specific Subfolder
+```typescript
+const subFoldersRes = await axios.get(
+  `https://workdrive.zoho.eu/api/v1/teamfolders/${projectsFolderId}/folders`,
+  { headers: workdriveHeaders }
+);
+
+// Find folder named like "PA-{num}-{projectName}-Attachments"
+const projectFolder = subFoldersRes.data.data.find(
+  f => f.attributes.name.includes(projectName) && f.attributes.name.includes('-Attachments')
+);
+```
+
+#### Step 4: Upload File to WorkDrive
+```typescript
+const formData = new FormData();
+formData.append('content', fileBuffer, {
+  filename: 'test.txt',
+  contentType: 'text/plain'
+});
+formData.append('parent_id', projectFolderId);
+
+const uploadRes = await axios.post(
+  'https://workdrive.zoho.eu/api/v1/upload',
+  formData,
+  { headers: { ...workdriveHeaders, ...formData.getHeaders() } }
+);
+
+const workdriveFileId = uploadRes.data.data[0].attributes.resource_id;
+```
+
+### Regional API URLs
+
+| Region | WorkDrive API | Projects API | Accounts URL |
+|--------|--------------|--------------|--------------|
+| US | workdrive.zoho.com | projectsapi.zoho.com | accounts.zoho.com |
+| EU | workdrive.zoho.eu | projectsapi.zoho.eu | accounts.zoho.eu |
+| IN | workdrive.zoho.in | projectsapi.zoho.in | accounts.zoho.in |
+| AU | workdrive.zoho.com.au | projectsapi.zoho.com.au | accounts.zoho.com.au |
+
+### Troubleshooting
+
+- **INVALID_OAUTHSCOPE on V3 `/attachments` endpoint**: Use Method 1 (direct upload via `/restapi/`) instead
+- **No team folders found**: Use `users/me` to get `preferred_team_id`, then query `/teams/{teamId}/teamfolders`
+- **Project folder not found**: Zoho automatically creates project folders; wait a moment after project creation
+
+---
+
 ## Available Namespaces
 
 ### Portal-Level (no projectId needed)
@@ -46,6 +214,9 @@ ZOHO_PORTAL_ID=     # Your Zoho Projects portal ID
 ## Common Patterns
 
 ```typescript
+// List with V3 pagination (page/per_page)
+const { data, pageInfo } = await client.projects.list({ page: 1, per_page: 100 });
+
 // List all (auto-paginate)
 const allProjects = await client.projects.listAll();
 
@@ -54,12 +225,24 @@ for await (const project of client.projects.iterate()) {
   console.log(project.name);
 }
 
-// CRUD operations
-await client.tasks.create(projectId, { name: 'New task', tasklist_id: tasklistId });
+// Create task (V3 uses nested tasklist object)
+await client.tasks.create(projectId, {
+  name: 'New task',
+  tasklist: { id: tasklistId },
+});
+
+// Update and delete
 await client.tasks.update(projectId, taskId, { status: 'completed' });
 await client.tasks.delete(projectId, taskId);
 ```
 
+## V3 API Notes
+
+- **Pagination**: Uses `page` (1-based) and `per_page` instead of `index`/`range`
+- **IDs**: Returns string IDs, not numbers
+- **Nested objects**: Many fields like `owner`, `status`, `tasklist` are nested objects
+- **Response format**: V3 returns data directly, not wrapped in arrays
+
 ## Package Documentation
 
 - [GitHub Repository](https://github.com/Panoptic-IT-Solutions/zoho-projects-client)