@panoptic-it-solutions/zoho-projects-client 0.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/types/users.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;GAEG;AACH,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAwCP,CAAC;AAEjB,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;GAEG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGxC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}

package/dist/types/users.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { ZohoPageInfoSchema } from "./common.js";
+/**
+ * User role - Zoho has many role types including custom ones
+ */
+export const UserRoleSchema = z.string();
+/**
+ * User from Zoho Projects API
+ */
+export const UserSchema = z.object({
+    // Identification
+    id: z.string(),
+    zpuid: z.string().optional(),
+    name: z.string(),
+    email: z.string(),
+    // Status
+    active: z.boolean().optional(),
+    // Role & Profile
+    role: UserRoleSchema.optional(),
+    role_name: z.string().optional(),
+    role_id: z.string().optional(),
+    profile_id: z.string().optional(),
+    profile_name: z.string().optional(),
+    profile_type: z.union([z.string(), z.number()]).optional(),
+    // Billing & Budget
+    rate: z.union([z.string(), z.number()]).nullable().optional(), // Hourly rate
+    cost_per_hour: z.union([z.string(), z.number()]).nullable().optional(),
+    user_budget: z.union([z.string(), z.number()]).nullable().optional(),
+    revenue_budget: z.union([z.string(), z.number()]).nullable().optional(),
+    budget_threshold: z.union([z.string(), z.number()]).nullable().optional(),
+    invoice: z.string().nullable().optional(),
+    currency_code: z.string().optional(),
+    // Client-specific fields
+    client_company_name: z.string().nullable().optional(),
+    client_company_id: z.string().nullable().optional(),
+    // Project associations
+    associated_projects: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+    })).optional(),
+    // Timestamps
+    added_time: z.string().optional(),
+    added_time_long: z.number().optional(),
+}).passthrough(); // Allow extra fields we haven't documented
+/**
+ * Response wrapper for listing portal users
+ */
+export const UserListResponseSchema = z.object({
+    users: z.array(UserSchema),
+    page_info: ZohoPageInfoSchema.optional(),
+});
+/**
+ * Response wrapper for getting a single user
+ */
+export const UserResponseSchema = z.object({
+    users: z.array(UserSchema),
+});
+/**
+ * Response wrapper for listing project users
+ */
+export const ProjectUserListResponseSchema = z.object({
+    users: z.array(UserSchema),
+    page_info: ZohoPageInfoSchema.optional(),
+});
+//# sourceMappingURL=users.js.map

package/dist/types/users.js.map

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

package/dist/utils/pagination.d.ts

@@ -0,0 +1,59 @@
+import type { ZohoPageInfo } from "../types/index.js";
+/**
+ * Default page size for Zoho Projects API
+ * Maximum allowed is 200
+ */
+export declare const DEFAULT_PAGE_SIZE = 100;
+/**
+ * Maximum page size allowed by Zoho
+ */
+export declare const MAX_PAGE_SIZE = 200;
+/**
+ * Generic paginated response structure
+ */
+export interface PaginatedResponse<T> {
+    data: T[];
+    pageInfo?: ZohoPageInfo;
+}
+/**
+ * Options for auto-pagination
+ */
+export interface AutoPaginateOptions {
+    /** Maximum number of items to fetch (default: unlimited) */
+    maxItems?: number;
+    /** Number of items per page (default: 100, max: 200) */
+    pageSize?: number;
+}
+/**
+ * Create an async generator that automatically handles pagination
+ *
+ * Usage:
+ * ```ts
+ * for await (const project of autoPaginate((index) =>
+ *   client.projects.list({ index, range: 100 })
+ * )) {
+ *   console.log(project);
+ * }
+ * ```
+ *
+ * @param fetchPage Function that fetches a page given the index (0-based)
+ * @param options Pagination options
+ */
+export declare function autoPaginate<T>(fetchPage: (index: number, range: number) => Promise<PaginatedResponse<T>>, options?: AutoPaginateOptions): AsyncGenerator<T, void, unknown>;
+/**
+ * Collect all items from an async generator into an array
+ *
+ * Usage:
+ * ```ts
+ * const allProjects = await collectAll(autoPaginate(...));
+ * ```
+ */
+export declare function collectAll<T>(generator: AsyncGenerator<T, void, unknown>): Promise<T[]>;
+/**
+ * Helper to create pagination params for Zoho API
+ */
+export declare function createPaginationParams(index?: number, range?: number): {
+    index: number;
+    range: number;
+};
+//# sourceMappingURL=pagination.d.ts.map

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

@@ -0,0 +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"}

package/dist/utils/pagination.js

@@ -0,0 +1,84 @@
+/**
+ * Default page size for Zoho Projects API
+ * Maximum allowed is 200
+ */
+export const DEFAULT_PAGE_SIZE = 100;
+/**
+ * Maximum page size allowed by Zoho
+ */
+export const MAX_PAGE_SIZE = 200;
+/**
+ * Create an async generator that automatically handles pagination
+ *
+ * Usage:
+ * ```ts
+ * for await (const project of autoPaginate((index) =>
+ *   client.projects.list({ index, range: 100 })
+ * )) {
+ *   console.log(project);
+ * }
+ * ```
+ *
+ * @param fetchPage Function that fetches a page given the index (0-based)
+ * @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 itemsYielded = 0;
+    let hasMore = true;
+    while (hasMore && itemsYielded < maxItems) {
+        const response = await fetchPage(index, pageSize);
+        const items = response.data;
+        if (items.length === 0) {
+            // No more items
+            hasMore = false;
+            break;
+        }
+        for (const item of items) {
+            if (itemsYielded >= maxItems) {
+                return;
+            }
+            yield item;
+            itemsYielded++;
+        }
+        // Determine if there are more pages
+        if (response.pageInfo?.has_more_page === false) {
+            hasMore = false;
+        }
+        else if (items.length < pageSize) {
+            // Received fewer items than requested, likely last page
+            hasMore = false;
+        }
+        else {
+            // Move to next page
+            index += pageSize;
+        }
+    }
+}
+/**
+ * Collect all items from an async generator into an array
+ *
+ * Usage:
+ * ```ts
+ * const allProjects = await collectAll(autoPaginate(...));
+ * ```
+ */
+export async function collectAll(generator) {
+    const items = [];
+    for await (const item of generator) {
+        items.push(item);
+    }
+    return items;
+}
+/**
+ * Helper to create pagination params for Zoho API
+ */
+export function createPaginationParams(index = 0, range = DEFAULT_PAGE_SIZE) {
+    return {
+        index,
+        range: Math.min(range, MAX_PAGE_SIZE),
+    };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/utils/pagination.js.map

@@ -0,0 +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"}

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,33 @@
+import Bottleneck from "bottleneck";
+/**
+ * Configuration for rate limiting
+ */
+export interface RateLimiterConfig {
+    /**
+     * Redis configuration for distributed rate limiting
+     * If not provided, uses in-memory limiting (single instance only)
+     */
+    redis?: {
+        url: string;
+    };
+}
+/**
+ * Create a rate limiter for Zoho Projects API
+ *
+ * Uses Bottleneck's reservoir pattern to enforce:
+ * - Max 90 requests per 2 minutes (with 10 request safety margin)
+ * - Min 1.3s between requests
+ * - Max 5 concurrent requests
+ *
+ * Handles 429 responses by pausing for 30-minute lockout
+ */
+export declare function createRateLimiter(config?: RateLimiterConfig): Bottleneck;
+/**
+ * Get rate limiter stats for monitoring
+ */
+export declare function getRateLimiterStats(limiter: Bottleneck): {
+    running: number;
+    queued: number;
+    reservoir: number | null;
+};
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/utils/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AAEpC;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;CACH;AAsBD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAkDxE;AAaD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,GAAG;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAOA"}

package/dist/utils/rate-limiter.js

@@ -0,0 +1,92 @@
+import Bottleneck from "bottleneck";
+/**
+ * Zoho Projects API rate limits:
+ * - 100 requests per 2 minutes (per user/org)
+ * - 429 response triggers 30-minute lockout
+ */
+const ZOHO_RATE_LIMIT = {
+    /** Maximum requests in the time window */
+    maxRequests: 100,
+    /** Time window in milliseconds (2 minutes) */
+    windowMs: 2 * 60 * 1000,
+    /** Safety margin - we use 90 requests to avoid hitting the exact limit */
+    safeMaxRequests: 90,
+    /** Minimum time between requests in milliseconds (~1.3s for safety) */
+    minTime: 1300,
+    /** Maximum concurrent requests */
+    maxConcurrent: 5,
+    /** Lockout duration when rate limited (30 minutes) */
+    lockoutMs: 30 * 60 * 1000,
+};
+/**
+ * Create a rate limiter for Zoho Projects API
+ *
+ * Uses Bottleneck's reservoir pattern to enforce:
+ * - Max 90 requests per 2 minutes (with 10 request safety margin)
+ * - Min 1.3s between requests
+ * - Max 5 concurrent requests
+ *
+ * Handles 429 responses by pausing for 30-minute lockout
+ */
+export function createRateLimiter(config) {
+    const limiterOptions = {
+        // Reservoir pattern for request budget
+        reservoir: ZOHO_RATE_LIMIT.safeMaxRequests,
+        reservoirRefreshAmount: ZOHO_RATE_LIMIT.safeMaxRequests,
+        reservoirRefreshInterval: ZOHO_RATE_LIMIT.windowMs,
+        // Concurrency controls
+        maxConcurrent: ZOHO_RATE_LIMIT.maxConcurrent,
+        minTime: ZOHO_RATE_LIMIT.minTime,
+    };
+    // Add Redis clustering if configured
+    if (config?.redis) {
+        const redisConnection = new Bottleneck.IORedisConnection({
+            client: createRedisClient(config.redis.url),
+        });
+        return new Bottleneck({
+            ...limiterOptions,
+            id: "zoho-projects-rate-limiter",
+            datastore: "ioredis",
+            clearDatastore: false,
+            connection: redisConnection,
+        });
+    }
+    const limiter = new Bottleneck(limiterOptions);
+    // Handle rate limit errors with 30-minute backoff
+    limiter.on("failed", async (error, jobInfo) => {
+        const axiosError = error;
+        if (axiosError.response?.status === 429) {
+            console.warn(`[ZohoProjectsClient] Rate limit exceeded, pausing for ${ZOHO_RATE_LIMIT.lockoutMs / 1000 / 60} minutes`);
+            // Return retry delay in ms - Bottleneck will retry after this delay
+            return ZOHO_RATE_LIMIT.lockoutMs;
+        }
+        // Don't retry other errors
+        return undefined;
+    });
+    limiter.on("retry", (message, jobInfo) => {
+        console.info(`[ZohoProjectsClient] Retrying request after rate limit cooldown`);
+    });
+    return limiter;
+}
+/**
+ * Create Redis client for distributed rate limiting
+ * Lazy import to avoid requiring ioredis when not using Redis
+ */
+function createRedisClient(url) {
+    // Dynamic import to avoid bundling ioredis when not needed
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const Redis = require("ioredis");
+    return new Redis(url);
+}
+/**
+ * Get rate limiter stats for monitoring
+ */
+export function getRateLimiterStats(limiter) {
+    const counts = limiter.counts();
+    return {
+        running: counts.RUNNING,
+        queued: counts.QUEUED,
+        reservoir: null, // Bottleneck doesn't expose current reservoir directly
+    };
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AAepC;;;;GAIG;AACH,MAAM,eAAe,GAAG;IACtB,0CAA0C;IAC1C,WAAW,EAAE,GAAG;IAChB,8CAA8C;IAC9C,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI;IACvB,0EAA0E;IAC1E,eAAe,EAAE,EAAE;IACnB,uEAAuE;IACvE,OAAO,EAAE,IAAI;IACb,kCAAkC;IAClC,aAAa,EAAE,CAAC;IAChB,sDAAsD;IACtD,SAAS,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;CAC1B,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA0B;IAC1D,MAAM,cAAc,GAAkC;QACpD,uCAAuC;QACvC,SAAS,EAAE,eAAe,CAAC,eAAe;QAC1C,sBAAsB,EAAE,eAAe,CAAC,eAAe;QACvD,wBAAwB,EAAE,eAAe,CAAC,QAAQ;QAElD,uBAAuB;QACvB,aAAa,EAAE,eAAe,CAAC,aAAa;QAC5C,OAAO,EAAE,eAAe,CAAC,OAAO;KACjC,CAAC;IAEF,qCAAqC;IACrC,IAAI,MAAM,EAAE,KAAK,EAAE,CAAC;QAClB,MAAM,eAAe,GAAG,IAAI,UAAU,CAAC,iBAAiB,CAAC;YACvD,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;SAC5C,CAAC,CAAC;QAEH,OAAO,IAAI,UAAU,CAAC;YACpB,GAAG,cAAc;YACjB,EAAE,EAAE,4BAA4B;YAChC,SAAS,EAAE,SAAS;YACpB,cAAc,EAAE,KAAK;YACrB,UAAU,EAAE,eAAe;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,cAAc,CAAC,CAAC;IAE/C,kDAAkD;IAClD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC5C,MAAM,UAAU,GAAG,KAA2C,CAAC;QAC/D,IAAI,UAAU,CAAC,QAAQ,EAAE,MAAM,KAAK,GAAG,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CACV,yDAAyD,eAAe,CAAC,SAAS,GAAG,IAAI,GAAG,EAAE,UAAU,CACzG,CAAC;YACF,oEAAoE;YACpE,OAAO,eAAe,CAAC,SAAS,CAAC;QACnC,CAAC;QACD,2BAA2B;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QACvC,OAAO,CAAC,IAAI,CACV,iEAAiE,CAClE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,GAAW;IACpC,2DAA2D;IAC3D,iEAAiE;IACjE,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmB;IAKrD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,IAAI,EAAE,uDAAuD;KACzE,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@panoptic-it-solutions/zoho-projects-client",
+  "version": "0.1.0",
+  "description": "TypeScript client for Zoho Projects V3 API with OAuth 2.0 and rate limiting",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "zoho",
+    "zoho-projects",
+    "api-client",
+    "typescript"
+  ],
+  "author": "Panoptic IT Solutions",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panoptic-it-solutions/zoho-projects-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/panoptic-it-solutions/zoho-projects-client/issues"
+  },
+  "homepage": "https://github.com/panoptic-it-solutions/zoho-projects-client#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "bottleneck": "^2.19.5",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}