@elobdev/zoho-projects-wrapper 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.codex ADDED
File without changes
package/README.md CHANGED
@@ -1,3 +1,53 @@
1
- # Temporary Holding Version
1
+ # Zoho Projects Wrapper
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ TypeScript SDK for the Zoho Projects V3 API.
4
+
5
+ ## Features
6
+
7
+ - OAuth helper for auth URL generation, code exchange, refresh, and revoke
8
+ - Typed client namespaces for portals, projects, task lists, tasks, issues, custom fields, module metadata, and records
9
+ - OpenAI-compatible tool definitions and a dispatcher so a model can call the SDK through function calling
10
+ - Root exports for the resource classes, so you can import from the package entrypoint instead of deep paths
11
+ - Raw `request()` escape hatch for undocumented endpoints
12
+ - Zoho-style JSON query serialization and form-data support
13
+ - Typed API errors with status, request id, retryability, and raw response payload
14
+
15
+ ## Usage
16
+
17
+ ```ts
18
+ import { ZohoProjectsClient } from './src/index.ts';
19
+
20
+ const client = new ZohoProjectsClient({
21
+ accessToken: 'your-access-token',
22
+ clientId: 'your-client-id',
23
+ clientSecret: 'your-client-secret',
24
+ redirectUri: 'https://example.com/callback',
25
+ });
26
+
27
+ const portals = await client.portals.listPortals();
28
+ const authUrl = client.oauth.authorizationUrl();
29
+ ```
30
+
31
+ ### Tooling for model runtimes
32
+
33
+ ```ts
34
+ import { ZohoProjectsClient, executeZohoProjectsTool, zohoProjectsTools } from './src/index.ts';
35
+
36
+ const client = new ZohoProjectsClient({ accessToken: 'your-access-token' });
37
+
38
+ // Pass `zohoProjectsTools` to your model/runtime as function tools.
39
+ // When the model picks one, call the dispatcher with the same name and payload.
40
+ const result = await executeZohoProjectsTool(client, 'zoho_projects_projects', {
41
+ action: 'list',
42
+ portal_id: 123456789,
43
+ query: { page: 1, per_page: 10 },
44
+ });
45
+ ```
46
+
47
+ ## Test
48
+
49
+ ```bash
50
+ npm test
51
+ ```
52
+
53
+ The tests use Node's built-in TypeScript stripping, so no extra toolchain is required for local verification.
package/docs/zoho- ADDED
File without changes
@@ -0,0 +1,368 @@
1
+ # Zoho Projects API Coverage Matrix
2
+
3
+ Referencia oficial: https://projects.zoho.com/api-docs
4
+
5
+ ## Leyenda
6
+
7
+ - `✅` implementado en el wrapper
8
+ - `🟡` parcialmente cubierto
9
+ - `❌` no lo veo implementado
10
+
11
+ ## 1. Portals
12
+
13
+ | Endpoint | Estado | Implementación |
14
+ | --- | --- | --- |
15
+ | `GET /api/v3/portal` | ✅ | `PortalsResource.listPortals()` |
16
+ | `GET /api/v3/portal/{portalId}` | ✅ | `PortalsResource.getPortalDetails()` |
17
+ | `POST /api/v3/portal/{portalId}/portal_export` | ✅ | `PortalsResource.scheduleDataBackup()` |
18
+ | `GET /api/v3/portal/{portalId}/portal_export/{exportId}/status` | ✅ | `PortalsResource.getDataBackupStatus()` |
19
+ | `GET /api/v3/portal/{portalId}/portal_export/history` | ✅ | `PortalsResource.getDataBackupHistory()` |
20
+ | `GET /api/v3/portal/{portalId}/bin` | ✅ | `PortalsResource.getTrashedRecords()` |
21
+ | `POST /api/v3/portal/{portalId}/trash` | ✅ | `PortalsResource.moveRecordsToTrash()` |
22
+ | `DELETE /api/v3/portal/{portalId}/bin` | ✅ | `PortalsResource.deleteRecords()` |
23
+ | `POST /api/v3/portal/{portalId}/bin/restore` | ✅ | `PortalsResource.restoreRecordsFromTrash()` |
24
+ | `DELETE /api/v3/portal/{portalId}/bin` | ✅ | `PortalsResource.emptyRecycleBin()` |
25
+
26
+ ## 2. Module Meta / Settings
27
+
28
+ | Endpoint | Estado | Implementación |
29
+ | --- | --- | --- |
30
+ | `GET /api/v3/portal/{portalId}/settings/modules` | ✅ | `SettingsResource.listModules()` |
31
+ | `GET /api/v3/portal/{portalId}/settings/modules/{module}` | ✅ | `SettingsResource.getModule()` |
32
+ | `POST /api/v3/portal/{portalId}/settings/modules` | ✅ | `SettingsResource.createModule()` |
33
+ | `PATCH /api/v3/portal/{portalId}/settings/modules/{module}` | ✅ | `SettingsResource.updateModule()` |
34
+ | `POST /api/v3/portal/{portalId}/settings/modules/{module}/status` | ✅ | `SettingsResource.updateModuleStatus()` |
35
+ | `POST /api/v3/portal/{portalId}/settings/modules/{module}/trash` | ✅ | `SettingsResource.trashModule()` |
36
+ | `DELETE /api/v3/portal/{portalId}/settings/modules/{module}` | ✅ | `SettingsResource.deleteModule()` |
37
+ | `POST /api/v3/portal/{portalId}/settings/modules/{module}/restore` | ✅ | `SettingsResource.restoreModule()` |
38
+ | `GET /api/v3/portal/{portalId}/settings/modules/{module}/configuration` | ✅ | `SettingsResource.getModuleConfiguration()` |
39
+ | `PATCH /api/v3/portal/{portalId}/settings/modules/{module}/activate` | ✅ | `SettingsResource.activateModule()` |
40
+ | `PATCH /api/v3/portal/{portalId}/settings/modules/{module}/deactivate` | ✅ | `SettingsResource.deactivateModule()` |
41
+
42
+ ### Layouts
43
+
44
+ | Endpoint | Estado | Implementación |
45
+ | --- | --- | --- |
46
+ | `GET /api/v3/portal/{portalId}/settings/layouts` | ✅ | `SettingsResource.listLayouts()` |
47
+ | `GET /api/v3/portal/{portalId}/settings/layouts/default-layout` | ✅ | `SettingsResource.getDefaultLayout()` |
48
+ | `GET /api/v3/portal/{portalId}/settings/layouts/{layoutId}` | ✅ | `SettingsResource.getLayoutDetails()` |
49
+ | `POST /api/v3/portal/{portalId}/settings/layouts` | ✅ | `SettingsResource.createLayout()` |
50
+ | `PATCH /api/v3/portal/{portalId}/settings/layouts/{layoutId}` | ✅ | `SettingsResource.updateLayout()` |
51
+ | `DELETE /api/v3/portal/{portalId}/settings/layouts/{layoutId}` | ✅ | `SettingsResource.deleteLayout()` |
52
+ | `DELETE /api/v3/portal/{portalId}/settings/layouts/{layoutId}/fields/{fieldId}` | ✅ | `SettingsResource.disassociateFieldFromLayout()` |
53
+ | `GET /api/v3/portal/{portalId}/settings/layouts/{layoutId}/entities` | ✅ | `SettingsResource.getAssociatedEntitiesOfLayout()` |
54
+ | `PUT /api/v3/portal/{portalId}/settings/layouts/{layoutId}/sections` | ✅ | `SettingsResource.createOrUpdateSection()` |
55
+ | `DELETE /api/v3/portal/{portalId}/settings/layouts/{layoutId}/sections` | ✅ | `SettingsResource.deleteSection()` |
56
+
57
+ ### Fields
58
+
59
+ | Endpoint | Estado | Implementación |
60
+ | --- | --- | --- |
61
+ | `GET /api/v3/portal/{portalId}/settings/fields?module=...` | ✅ | `SettingsResource.listFields()` |
62
+ | `PUT /api/v3/portal/{portalId}/settings/fields` | ✅ | `SettingsResource.createOrUpdateField()` |
63
+ | `DELETE /api/v3/portal/{portalId}/settings/fields` | ✅ | `SettingsResource.deleteField()` |
64
+ | `GET /api/v3/portal/{portalId}/settings/fields/{fieldId}/associated-layouts` | ✅ | `SettingsResource.getAssociatedLayouts()` |
65
+ | `GET /api/v3/portal/{portalId}/settings/fields` wrapper | ✅ | `CustomFieldsResource.getFields()` |
66
+
67
+ ### Options
68
+
69
+ | Endpoint | Estado | Implementación |
70
+ | --- | --- | --- |
71
+ | `GET /api/v3/portal/{portalId}/settings/options` | ✅ | `SettingsResource.getOptionsListForField()` |
72
+ | `POST /api/v3/portal/{portalId}/settings/options` | ✅ | `SettingsResource.createBulkOptions()` |
73
+ | `DELETE /api/v3/portal/{portalId}/settings/options` | ✅ | `SettingsResource.deleteOrDisassociateBulkOptions()` |
74
+ | `PATCH /api/v3/portal/{portalId}/settings/options` | ✅ | `SettingsResource.updateBulkOptions()` |
75
+
76
+ ### Integration / Views
77
+
78
+ | Endpoint | Estado | Implementación |
79
+ | --- | --- | --- |
80
+ | `GET /api/v3/portal/{portalId}/integration-field/service/{serviceId}/module/{moduleId}/fields` | ✅ | `SettingsResource.getModuleIntegrationField()` |
81
+ | `GET /api/v3/portal/{portalId}/views/{viewId}` | ✅ | `SettingsResource.getViews()` |
82
+
83
+ ## 3. Projects
84
+
85
+ | Endpoint | Estado | Implementación |
86
+ | --- | --- | --- |
87
+ | `GET /api/v3/portal/{portalId}/projects` | ✅ | `ProjectsResource.list()` |
88
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}` | ✅ | `ProjectsResource.getById()` |
89
+ | `POST /api/v3/portal/{portalId}/projects` | ✅ | `ProjectsResource.create()` |
90
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}` | ✅ | `ProjectsResource.update()` |
91
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}` | ✅ | `ProjectsResource.deleteById()` |
92
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/trash` | ✅ | `ProjectsResource.trash()` |
93
+ | `POST /api/v3/portal/{portalId}/projects/customview/{customViewId}/markfavourite` | ✅ | `ProjectsResource.markFavouriteCustomView()` |
94
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/comments` | ✅ | `ProjectsResource.listComments()` |
95
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/comments/{commentId}` | ✅ | `ProjectsResource.getComment()` |
96
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/comments` | ✅ | `ProjectsResource.addComment()` |
97
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/comments/{commentId}` | ✅ | `ProjectsResource.updateComment()` |
98
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/comments/{commentId}` | ✅ | `ProjectsResource.deleteComment()` |
99
+
100
+ Nota: `ProjectsResource.listComments()` también acepta `view_id`, `milestone_ids` y `sort_by`, alineado con la doc oficial de comentarios de proyecto.
101
+
102
+ ## 3b. Project Groups
103
+
104
+ | Endpoint | Estado | Implementación |
105
+ | --- | --- | --- |
106
+ | `GET /api/v3/portal/{portalId}/project-groups` | ✅ | `ProjectGroupsResource.list()` |
107
+ | `GET /api/v3/portal/{portalId}/my-project-groups` | ✅ | `ProjectGroupsResource.listMine()` |
108
+ | `POST /api/v3/portal/{portalId}/project-groups` | ✅ | `ProjectGroupsResource.create()` |
109
+ | `PATCH /api/v3/portal/{portalId}/project-groups/{groupId}` | ✅ | `ProjectGroupsResource.update()` |
110
+ | `DELETE /api/v3/portal/{portalId}/project-groups/{groupId}` | ✅ | `ProjectGroupsResource.deleteById()` |
111
+
112
+ ### Huecos visibles en Projects
113
+
114
+ | Área | Estado | Nota |
115
+ | --- | --- | --- |
116
+ | Activity / edits de proyecto | ❌ | No veo helpers dedicados |
117
+ | Recent projects | ❌ | No veo helpers dedicados |
118
+ | Default visibility / access settings | ❌ | No veo helpers dedicados |
119
+ | Templates / gallery templates | ❌ | No veo helpers dedicados |
120
+ | Add project from template | ❌ | No veo helpers dedicados |
121
+ | Export custom status timeline | ❌ | No veo helpers dedicados |
122
+
123
+ ## 4. Phases / Milestones
124
+
125
+ | Endpoint | Estado | Implementación |
126
+ | --- | --- | --- |
127
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/phases` | ✅ | `PhasesResource.list()` |
128
+ | `GET /api/v3/portal/{portalId}/phases` | ✅ | `PhasesResource.listAll()` |
129
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}` | ✅ | `PhasesResource.getById()` |
130
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/phases` | ✅ | `PhasesResource.create()` |
131
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}` | ✅ | `PhasesResource.update()` |
132
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}` | ✅ | `PhasesResource.deleteById()` |
133
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/status-timeline` | ✅ | `PhasesResource.statusTimeline()` |
134
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/move` | ✅ | `PhasesResource.move()` |
135
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/followers` | ✅ | `PhasesResource.getFollowers()` |
136
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/follow` | ✅ | `PhasesResource.addFollowers()` |
137
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/unfollow` | ✅ | `PhasesResource.removeFollowers()` |
138
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/comments` | ✅ | `PhasesResource.listComments()` |
139
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/comments/{commentId}` | ✅ | `PhasesResource.getComment()` |
140
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/comments` | ✅ | `PhasesResource.addComment()` |
141
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/comments/{commentId}` | ✅ | `PhasesResource.updateComment()` |
142
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/phases/{phaseId}/comments/{commentId}` | ✅ | `PhasesResource.deleteComment()` |
143
+
144
+ ### Huecos visibles en Phases
145
+
146
+ | Área | Estado | Nota |
147
+ | --- | --- | --- |
148
+ | Comments | ❌ | No veo helpers dedicados |
149
+ | Attachments | ❌ | No veo helpers dedicados |
150
+ | Operaciones extra de milestone | ❌ | No veo helpers dedicados |
151
+
152
+ ## 5. Tasklists
153
+
154
+ | Endpoint | Estado | Implementación |
155
+ | --- | --- | --- |
156
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/tasklists` | ✅ | `TasklistsResource.list()` |
157
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}` | ✅ | `TasklistsResource.getById()` |
158
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/tasklists` | ✅ | `TasklistsResource.create()` |
159
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/default-tasklists` | ✅ | `TasklistsResource.createDefault()` |
160
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}` | ✅ | `TasklistsResource.update()` |
161
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}` | ✅ | `TasklistsResource.deleteById()` |
162
+ | `GET /api/v3/portal/{portalId}/all-tasklists` | ✅ | `TasklistsResource.listAll()` |
163
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/comments` | ✅ | `TasklistsResource.getComments()` |
164
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/comments/{commentId}` | ✅ | `TasklistsResource.getComment()` |
165
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/comments` | ✅ | `TasklistsResource.addComment()` |
166
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/comments/{commentId}` | ✅ | `TasklistsResource.updateComment()` |
167
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/comments/{commentId}` | ✅ | `TasklistsResource.deleteComment()` |
168
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/make-as-template` | ✅ | `TasklistsResource.makeAsTemplate()` |
169
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/followers` | ✅ | `TasklistsResource.getFollowers()` |
170
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/follow` | ✅ | `TasklistsResource.addFollowers()` |
171
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/tasklists/{tasklistId}/unfollow` | ✅ | `TasklistsResource.removeFollowers()` |
172
+
173
+ ### Huecos visibles en Tasklists
174
+
175
+ | Área | Estado | Nota |
176
+ | --- | --- | --- |
177
+ | Attachments de comments | ❌ | No veo helpers dedicados |
178
+ | Acciones accesorias adicionales | ❌ | No veo helpers dedicados |
179
+
180
+ ## 6. Tasks
181
+
182
+ | Endpoint | Estado | Implementación |
183
+ | --- | --- | --- |
184
+ | `GET /api/v3/portal/{portalId}/tasks` | ✅ | `TasksResource.listAll()` |
185
+ | `GET /api/v3/portal/{portalId}/mytasks` | ✅ | `TasksResource.listMyTasks()` |
186
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/tasks` | ✅ | `TasksResource.list()` |
187
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/tasks/{taskId}` | ✅ | `TasksResource.getById()` |
188
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/tasks` | ✅ | `TasksResource.create()` |
189
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/tasks/{taskId}` | ✅ | `TasksResource.update()` |
190
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/tasks/{taskId}` | ✅ | `TasksResource.deleteById()` |
191
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/taskstatushistory` | ✅ | `TasksResource.getStatusHistory()` |
192
+ | `GET /api/v3/portal/{portalId}/issues/associated-tasks` | ✅ | `TasksResource.getAssociatedTasksByIssues()` |
193
+
194
+ ### Huecos visibles en Tasks
195
+
196
+ | Área | Estado | Nota |
197
+ | --- | --- | --- |
198
+ | Comments | ❌ | No veo helpers dedicados |
199
+ | Followers | ❌ | No veo helpers dedicados |
200
+ | Attachments | ❌ | No veo helpers dedicados |
201
+ | Subtasks / child tasks | 🟡 | Hay `parental_info` en el payload, pero no helpers específicos |
202
+ | Recurrence | ❌ | No veo helpers dedicados |
203
+ | Owners/work avanzados | 🟡 | El tipo soporta el payload, pero no hay helpers específicos |
204
+ | Otras acciones de tarea | ❌ | No veo helpers dedicados |
205
+
206
+ ## 7. Issues
207
+
208
+ | Endpoint | Estado | Implementación |
209
+ | --- | --- | --- |
210
+ | `GET /api/v3/portal/{portalId}/issues` | ✅ | `IssuesResource.listAll()` |
211
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues` | ✅ | `IssuesResource.list()` |
212
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}` | ✅ | `IssuesResource.getById()` |
213
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues` | ✅ | `IssuesResource.create()` |
214
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}` | ✅ | `IssuesResource.deleteById()` |
215
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/customviews` | ✅ | `IssuesResource.listCustomViews()` |
216
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/move` | ✅ | `IssuesResource.move()` |
217
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/comments` | ✅ | `IssuesResource.getComments()` |
218
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/comments/{commentId}` | ✅ | `IssuesResource.getComment()` |
219
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/comments` | ✅ | `IssuesResource.addComment()` |
220
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/comments/{commentId}` | ✅ | `IssuesResource.updateComment()` |
221
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/comments/{commentId}` | ✅ | `IssuesResource.deleteComment()` |
222
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues/bulk-associate-tasks` | ✅ | `IssuesResource.bulkAssociateTasks()` |
223
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues/bulk-link-bugs` | ✅ | `IssuesResource.bulkLinkIssues()` |
224
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}` | ✅ | `IssuesResource.update()` |
225
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/followers` | ✅ | `IssuesResource.getFollowers()` |
226
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/followers` | ✅ | `IssuesResource.addFollowers()` |
227
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/followers` | ✅ | `IssuesResource.removeFollowers()` |
228
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/linkedissues` | ✅ | `IssuesResource.getLinkedIssues()` |
229
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/associate-tasks` | ✅ | `IssuesResource.associateTasks()` |
230
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/associated-tasks` | ✅ | `IssuesResource.getAssociatedTasks()` |
231
+ | `GET /api/v3/portal/{portalId}/issues/associated-tasks` | ✅ | `IssuesResource.getAssociatedTasksByIssues()` |
232
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/attachments` | ✅ | `IssuesResource.getAttachments()` |
233
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/attachments` | ✅ | `IssuesResource.addAttachments()` |
234
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/attachments/{attachmentId}` | ✅ | `IssuesResource.removeAttachment()` |
235
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/task/{taskId}` | ✅ | `IssuesResource.dissociateTask()` |
236
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/statustransition` | ✅ | `IssuesResource.getStatusTransition()` |
237
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/resolution` | ✅ | `IssuesResource.addResolution()` |
238
+ | `PUT /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/resolution` | ✅ | `IssuesResource.updateResolution()` |
239
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/issues/{issueId}/attachments/comments?comment_id=...` | ✅ | `IssuesResource.getCommentAttachment()` |
240
+
241
+ ### Huecos visibles en Issues
242
+
243
+ | Área | Estado | Nota |
244
+ | --- | --- | --- |
245
+ | Create issue | ❌ | No veo helper dedicado |
246
+ | Delete issue | ❌ | No veo helper dedicado |
247
+ | CRUD de comments | ❌ | Solo veo lectura de comments |
248
+ | Linked issues | ❌ | No veo helpers dedicados |
249
+ | Change link type / unlink | ❌ | No veo helpers dedicados |
250
+ | Followers | ❌ | No veo helpers dedicados |
251
+ | Otras operaciones de issue management | ❌ | No veo helpers dedicados |
252
+
253
+ ## 8. Records dinámicos
254
+
255
+ | Endpoint | Estado | Implementación |
256
+ | --- | --- | --- |
257
+ | `POST /api/v3/portal/{portalId}/module/{moduleName}/entities` | ✅ | `RecordsResource.createRecord()` |
258
+ | `GET /api/v3/portal/{portalId}/module/{moduleName}/entity/{entityId}/edits` | ✅ | `RecordsResource.listEntityEdits()` |
259
+ | `GET /api/v3/portal/{portalId}/module/{moduleName}/entity/{entityId}/edits/{editId}` | ✅ | `RecordsResource.getEditsByAuditId()` |
260
+ | `GET /api/v3/portal/{portalId}/module/{moduleName}/entity/{entityId}/attachmentcount` | ✅ | `RecordsResource.getAttachmentCount()` |
261
+ | `GET /api/v3/portal/{portalId}/module/{moduleName}/entity/{entityId}/followers` | ✅ | `RecordsResource.getFollowers()` |
262
+ | `POST /api/v3/portal/{portalId}/module/{moduleName}/entity/{entityId}/follow` | ✅ | `RecordsResource.addFollower()` |
263
+ | `POST /api/v3/portal/{portalId}/module/{moduleName}/entity/{entityId}/followers` | ✅ | `RecordsResource.addOrRemoveFollowers()` |
264
+ | `DELETE /api/v3/portal/{portalId}/module/{moduleName}/entity/{entityId}/unfollow` | ✅ | `RecordsResource.removeFollower()` |
265
+ | `POST /api/v3/portal/{portalId}/module/{moduleName}/entity/{entityId}/comment` | ✅ | `RecordsResource.addComment()` |
266
+
267
+ ### Huecos visibles en Records
268
+
269
+ | Área | Estado | Nota |
270
+ | --- | --- | --- |
271
+ | Tipado fino por entidad | 🟡 | Mucho retorno sigue siendo `unknown` |
272
+ | Más operaciones de módulo dinámico | ❌ | No veo helpers adicionales |
273
+
274
+ ## 8b. Time Logs
275
+
276
+ Nota: la doc oficial mezcla rutas `logs` para las operaciones principales y rutas `timelogs` para bulk, reports, pins, timers y settings.
277
+
278
+ | Endpoint | Estado | Implementación |
279
+ | --- | --- | --- |
280
+ | `GET /api/v3/portal/{portalId}/logs` | ✅ | `TimeLogsResource.listPortalTimeLogs()` |
281
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/logs` | ✅ | `TimeLogsResource.listProjectTimeLogs()` |
282
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/logs/{logId}` | ✅ | `TimeLogsResource.getTimeLogDetail()` |
283
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/logs` | ✅ | `TimeLogsResource.addTimeLog()` |
284
+ | `PATCH /api/v3/portal/{portalId}/timelogs` | ✅ | `TimeLogsResource.bulkUpdateTimeLogs()` |
285
+ | `DELETE /api/v3/portal/{portalId}/timelogs` | ✅ | `TimeLogsResource.bulkDeleteTimeLogs()` |
286
+ | `GET /api/v3/portal/{portalId}/timelogs/report` | ✅ | `TimeLogsResource.getPortalTimeLogReport()` |
287
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/timelogs/report` | ✅ | `TimeLogsResource.getProjectTimeLogReport()` |
288
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/timelogs/approver` | ✅ | `TimeLogsResource.getDefaultApprover()` |
289
+ | `GET /api/v3/portal/{portalId}/timelogs/pin` | ✅ | `TimeLogsResource.listPinnedPortalTimeLogs()` |
290
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/timelogs/pin` | ✅ | `TimeLogsResource.listPinnedProjectTimeLogs()` |
291
+ | `POST /api/v3/portal/{portalId}/timelogs/pin` | ✅ | `TimeLogsResource.createPinnedPortalTimeLog()` |
292
+ | `PATCH /api/v3/portal/{portalId}/timelogs/pin` | ✅ | `TimeLogsResource.updatePinnedPortalTimeLog()` |
293
+ | `DELETE /api/v3/portal/{portalId}/timelogs/pin` | ✅ | `TimeLogsResource.deletePinnedPortalTimeLog()` |
294
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/timelogs/pin` | ✅ | `TimeLogsResource.createPinnedProjectTimeLog()` |
295
+ | `PATCH /api/v3/portal/{portalId}/projects/{projectId}/timelogs/pin` | ✅ | `TimeLogsResource.updatePinnedProjectTimeLog()` |
296
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/timelogs/pin` | ✅ | `TimeLogsResource.deletePinnedProjectTimeLog()` |
297
+ | `GET /api/v3/portal/{portalId}/timelogs/timers` | ✅ | `TimeLogsResource.listRunningTimers()` |
298
+ | `POST /api/v3/portal/{portalId}/timelogs/timers` | ✅ | `TimeLogsResource.startTimer()` |
299
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/{entityType}/logs/{logId}/timers` | ✅ | `TimeLogsResource.getTimerDetailsByLogId()` |
300
+ | `PATCH /api/v3/portal/{portalId}/timelogs/timers/{timerId}/pause` | ✅ | `TimeLogsResource.pauseTimer()` |
301
+ | `PATCH /api/v3/portal/{portalId}/timelogs/timers/{timerId}/resume` | ✅ | `TimeLogsResource.resumeTimer()` |
302
+ | `PATCH /api/v3/portal/{portalId}/timelogs/timers/{timerId}/stop` | ✅ | `TimeLogsResource.stopTimer()` |
303
+ | `DELETE /api/v3/portal/{portalId}/timelogs/timers/{timerId}` | ✅ | `TimeLogsResource.deleteTimer()` |
304
+ | `GET /api/v3/portal/{portalId}/settings/timelog/meta-data` | ✅ | `TimeLogsResource.getTimeLogSettingsMetaData()` |
305
+ | `GET /api/v3/portal/{portalId}/settings/timelog` | ✅ | `TimeLogsResource.getTimeLogSettings()` |
306
+ | `PATCH /api/v3/portal/{portalId}/settings/timelog` | ✅ | `TimeLogsResource.updateTimeLogSettings()` |
307
+
308
+ ### Legacy helpers still exposed
309
+
310
+ | Endpoint | Estado | Implementación |
311
+ | --- | --- | --- |
312
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/tasks/{taskId}/logs` | ✅ | `TimeLogsResource.listTaskLogs()` |
313
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/tasks/{taskId}/logs` | ✅ | `TimeLogsResource.addTaskLog()` |
314
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/tasks/{taskId}/logs/{logId}` | ✅ | `TimeLogsResource.updateTaskLog()` |
315
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/tasks/{taskId}/logs/{logId}/approval` | ✅ | `TimeLogsResource.approveTaskLog()` |
316
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/tasks/{taskId}/logs/{logId}` | ✅ | `TimeLogsResource.deleteTaskLog()` |
317
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/bugs/{issueId}/logs` | ✅ | `TimeLogsResource.listBugLogs()` |
318
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/bugs/{issueId}/logs` | ✅ | `TimeLogsResource.addBugLog()` |
319
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/bugs/{issueId}/logs/{logId}` | ✅ | `TimeLogsResource.updateBugLog()` |
320
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/bugs/{issueId}/logs/{logId}/approval` | ✅ | `TimeLogsResource.approveBugLog()` |
321
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/bugs/{issueId}/logs/{logId}` | ✅ | `TimeLogsResource.deleteBugLog()` |
322
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/logs` | ✅ | `TimeLogsResource.addGeneralLog()` |
323
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/logs/{logId}` | ✅ | `TimeLogsResource.updateGeneralLog()` |
324
+ | `POST /api/v3/portal/{portalId}/projects/{projectId}/logs/{logId}/approval` | ✅ | `TimeLogsResource.approveGeneralLog()` |
325
+ | `DELETE /api/v3/portal/{portalId}/projects/{projectId}/logs/{logId}` | ✅ | `TimeLogsResource.deleteGeneralLog()` |
326
+ | `GET /api/v3/portal/{portalId}/projects/{projectId}/timesheetlayouts` | ✅ | `TimeLogsResource.getTimesheetLayoutDetails()` |
327
+ | `GET /api/v3/portal/{portalId}/timesheetcustomfields` | ✅ | `TimeLogsResource.getAllTimesheetCustomFields()` |
328
+
329
+ ## 9. Infraestructura transversal
330
+
331
+ | Piezas | Estado | Implementación |
332
+ | --- | --- | --- |
333
+ | OAuth helper | ✅ | `ZohoOAuthClient` |
334
+ | HTTP client propio | ✅ | `ZohoHttpClient` |
335
+ | `request()` escape hatch | ✅ | `ZohoProjectsClient.request()` |
336
+ | Query serialization | ✅ | `serializeQuery()` |
337
+ | Filtrado Zoho | ✅ | `mergeQuery()` / `withFilter()` |
338
+ | Errores tipados | ✅ | `APIError`, `ValidationError`, `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `RateLimitError`, `ServerError` |
339
+ | Soporte JSON/FormData | ✅ | `ZohoHttpClient.request()` |
340
+ | Tests de transporte y OAuth | ✅ | `test/http.test.ts`, `test/oauth.test.ts`, `test/query.test.ts` |
341
+
342
+ ## 10. Huecos de empaquetado
343
+
344
+ | Área | Estado | Nota |
345
+ | --- | --- | --- |
346
+ | Reexports completos en `src/index.ts` | 🟡 | El cliente tiene más recursos que el entrypoint público |
347
+ | `portals` / `projects` / `tasks` / `tasklists` / `issues` / `customFields` desde root | ❌ | No se reexportan hoy |
348
+ | Tipos fuertes de response/body | 🟡 | Hay bastante `unknown` y `Record<string, unknown>` |
349
+
350
+ ## 11. Bloques grandes que no veo
351
+
352
+ | Área | Estado | Nota |
353
+ | --- | --- | --- |
354
+ | Users / miembros / perfiles | ❌ | No veo recurso dedicado |
355
+ | Files / documents | ❌ | No veo recurso dedicado |
356
+ | Forums / discussions | ❌ | No veo recurso dedicado |
357
+ | Timesheets / time logs | ✅ | `TimeLogsResource` |
358
+ | Reports / dashboards | ❌ | No veo recurso dedicado |
359
+ | Notifications / search / activity general | ❌ | No veo recurso dedicado |
360
+
361
+ ## Conclusión rápida
362
+
363
+ - El wrapper ya cubre bien el núcleo: auth, HTTP, portals, projects, settings, tasklists, tasks, issues, phases, records y time logs.
364
+ - Lo más flojo ahora mismo está en:
365
+ - `Tasks`
366
+ - `Issues`
367
+ - el empaquetado público del root `index.ts`
368
+ - y la falta de recursos grandes como users, files, forums o timesheets.
package/package.json CHANGED
@@ -1,6 +1,25 @@
1
1
  {
2
2
  "name": "@elobdev/zoho-projects-wrapper",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "publishConfig": {
5
+ "access": "public"
6
+ },
7
+ "description": "TypeScript wrapper for the Zoho Projects V3 API",
8
+ "type": "module",
9
+ "engines": {
10
+ "node": ">=22.6.0"
11
+ },
12
+ "scripts": {
13
+ "test": "node --import ./test/register-path-alias.js --test --experimental-strip-types test/**/*.test.ts"
14
+ },
15
+ "keywords": [
16
+ "zoho",
17
+ "projects",
18
+ "sdk",
19
+ "typescript"
20
+ ],
21
+ "license": "UNLICENSED",
22
+ "devDependencies": {
23
+ "typescript": "^6.0.3"
24
+ }
25
+ }
package/src/client.ts ADDED
@@ -0,0 +1,75 @@
1
+ import { createDefaultHttpClient, ZohoHttpClient } from '@/http.ts';
2
+ import { ZohoOAuthClient } from '@/oauth.ts';
3
+ import { CustomFieldsResource } from '@/resources/custom-fields.ts';
4
+ import { IssuesResource } from '@/resources/issues.ts';
5
+ import { PhasesResource } from '@/resources/phases.ts';
6
+ import { RecordsResource } from '@/resources/records.ts';
7
+ import { PortalsResource } from '@/resources/portals.ts';
8
+ import { ProjectsResource } from '@/resources/projects.ts';
9
+ import { ProjectGroupsResource } from '@/resources/project-groups.ts';
10
+ import { SettingsResource } from '@/resources/settings.ts';
11
+ import { TimeLogsResource } from '@/resources/time-logs.ts';
12
+ import { TasklistsResource } from '@/resources/tasklists.ts';
13
+ import { TasksResource } from '@/resources/tasks.ts';
14
+ import type { ZohoClientConfig } from '@/types.ts';
15
+
16
+ export class ZohoProjectsClient {
17
+ private readonly config: ZohoClientConfig;
18
+ readonly oauth: ZohoOAuthClient;
19
+ readonly portals: PortalsResource;
20
+ readonly projects: ProjectsResource;
21
+ readonly projectGroups: ProjectGroupsResource;
22
+ readonly phases: PhasesResource;
23
+ readonly tasklists: TasklistsResource;
24
+ readonly tasks: TasksResource;
25
+ readonly issues: IssuesResource;
26
+ readonly customFields: CustomFieldsResource;
27
+ readonly settings: SettingsResource;
28
+ readonly moduleMeta: SettingsResource;
29
+ readonly records: RecordsResource;
30
+ readonly timeLogs: TimeLogsResource;
31
+ private http: ZohoHttpClient;
32
+
33
+ constructor(config: ZohoClientConfig = {}) {
34
+ this.config = config;
35
+ this.http = createDefaultHttpClient({
36
+ fetchImpl: config.fetch ?? fetch,
37
+ ...(config.apiBaseUrl !== undefined ? { baseUrl: config.apiBaseUrl } : {}),
38
+ ...(config.accessToken !== undefined ? { accessToken: config.accessToken } : {}),
39
+ ...(config.userAgent !== undefined ? { userAgent: config.userAgent } : {}),
40
+ });
41
+
42
+ this.oauth = new ZohoOAuthClient(
43
+ {
44
+ clientId: config.clientId ?? '',
45
+ ...(config.clientSecret !== undefined ? { clientSecret: config.clientSecret } : {}),
46
+ ...(config.redirectUri !== undefined ? { redirectUri: config.redirectUri } : {}),
47
+ ...(config.accountsBaseUrl !== undefined ? { accountsBaseUrl: config.accountsBaseUrl } : {}),
48
+ ...(config.scope !== undefined ? { scope: config.scope } : {}),
49
+ },
50
+ config.fetch ?? fetch,
51
+ );
52
+
53
+ this.portals = new PortalsResource(this.http);
54
+ this.projects = new ProjectsResource(this.http);
55
+ this.projectGroups = new ProjectGroupsResource(this.http);
56
+ this.phases = new PhasesResource(this.http);
57
+ this.tasklists = new TasklistsResource(this.http);
58
+ this.tasks = new TasksResource(this.http);
59
+ this.issues = new IssuesResource(this.http);
60
+ this.customFields = new CustomFieldsResource(this.http);
61
+ this.settings = new SettingsResource(this.http);
62
+ this.moduleMeta = this.settings;
63
+ this.records = new RecordsResource(this.http);
64
+ this.timeLogs = new TimeLogsResource(this.http);
65
+ }
66
+
67
+ setAccessToken(accessToken: string): this {
68
+ this.http = this.http.setAccessToken(accessToken);
69
+ return this;
70
+ }
71
+
72
+ async request<T>(path: string, init: Parameters<ZohoHttpClient['request']>[1] = {}): Promise<T> {
73
+ return this.http.request<T>(path, init);
74
+ }
75
+ }
package/src/errors.ts ADDED
@@ -0,0 +1,34 @@
1
+ import type { ZohoApiErrorInfo } from '@/types.ts';
2
+
3
+ export class APIError extends Error {
4
+ readonly status: number;
5
+ readonly requestId?: string | undefined;
6
+ readonly retryable: boolean;
7
+ readonly responseBody: unknown;
8
+
9
+ constructor(message: string, info: ZohoApiErrorInfo) {
10
+ super(message);
11
+ this.name = this.constructor.name;
12
+ this.status = info.status;
13
+ this.requestId = info.requestId;
14
+ this.retryable = info.retryable;
15
+ this.responseBody = info.responseBody;
16
+ }
17
+ }
18
+
19
+ export class ValidationError extends APIError {}
20
+ export class AuthenticationError extends APIError {}
21
+ export class ForbiddenError extends APIError {}
22
+ export class NotFoundError extends APIError {}
23
+ export class RateLimitError extends APIError {}
24
+ export class ServerError extends APIError {}
25
+
26
+ export function createApiError(message: string, info: ZohoApiErrorInfo): APIError {
27
+ if (info.status === 400) return new ValidationError(message, info);
28
+ if (info.status === 401) return new AuthenticationError(message, info);
29
+ if (info.status === 403) return new ForbiddenError(message, info);
30
+ if (info.status === 404) return new NotFoundError(message, info);
31
+ if (info.status === 429) return new RateLimitError(message, info);
32
+ if (info.status >= 500) return new ServerError(message, info);
33
+ return new APIError(message, info);
34
+ }