chore: Switch to dates and modern naming conventions (#353)

Author: scottlovegrove

src/TodoistApi.activities.test.ts

@@ -88,7 +88,7 @@ describe('TodoistApi activity endpoints', () => {
             const result = await api.getActivityLogs()
 
             expect(result.results).toHaveLength(2)
-            expect(result.results[0].objectType).toBe('item')
+            expect(result.results[0].objectType).toBe('task') // Converted from 'item' to 'task'
             expect(result.results[0].eventType).toBe('added')
             expect(result.nextCursor).toBeNull()
         })
@@ -161,5 +161,265 @@ describe('TodoistApi activity endpoints', () => {
                 another_unknown: 123,
             })
         })
+
+        test('converts Date objects to YYYY-MM-DD strings', async () => {
+            const requestMock = setupRestClientMock({
+                results: DEFAULT_ACTIVITY_RESPONSE,
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            const sinceDate = new Date('2025-01-15T10:30:00Z')
+            const untilDate = new Date('2025-01-20T15:45:00Z')
+
+            await api.getActivityLogs({
+                since: sinceDate,
+                until: untilDate,
+            })
+
+            expect(requestMock).toHaveBeenCalledWith(
+                'GET',
+                getSyncBaseUri(),
+                ENDPOINT_REST_ACTIVITIES,
+                DEFAULT_AUTH_TOKEN,
+                {
+                    since: '2025-01-15',
+                    until: '2025-01-20',
+                },
+            )
+        })
+
+        test('leaves string dates as-is for backward compatibility', async () => {
+            const requestMock = setupRestClientMock({
+                results: DEFAULT_ACTIVITY_RESPONSE,
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            await api.getActivityLogs({
+                since: '2025-01-15',
+                until: '2025-01-20',
+            })
+
+            expect(requestMock).toHaveBeenCalledWith(
+                'GET',
+                getSyncBaseUri(),
+                ENDPOINT_REST_ACTIVITIES,
+                DEFAULT_AUTH_TOKEN,
+                {
+                    since: '2025-01-15',
+                    until: '2025-01-20',
+                },
+            )
+        })
+
+        test('converts Date objects with correct timezone handling', async () => {
+            const requestMock = setupRestClientMock({
+                results: DEFAULT_ACTIVITY_RESPONSE,
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            // Test with a date that has time components
+            const sinceDate = new Date(2025, 0, 15, 23, 59, 59) // January 15, 2025, 23:59:59 local time
+
+            await api.getActivityLogs({
+                since: sinceDate,
+            })
+
+            const expectedSince = `${sinceDate.getFullYear()}-01-15`
+
+            expect(requestMock).toHaveBeenCalledWith(
+                'GET',
+                getSyncBaseUri(),
+                ENDPOINT_REST_ACTIVITIES,
+                DEFAULT_AUTH_TOKEN,
+                {
+                    since: expectedSince,
+                },
+            )
+        })
+
+        test('converts modern objectType "task" to legacy "item" in API request', async () => {
+            const requestMock = setupRestClientMock({
+                results: DEFAULT_ACTIVITY_RESPONSE,
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            await api.getActivityLogs({
+                objectType: 'task',
+            })
+
+            expect(requestMock).toHaveBeenCalledWith(
+                'GET',
+                getSyncBaseUri(),
+                ENDPOINT_REST_ACTIVITIES,
+                DEFAULT_AUTH_TOKEN,
+                {
+                    objectType: 'item',
+                },
+            )
+        })
+
+        test('converts modern objectType "comment" to legacy "note" in API request', async () => {
+            const requestMock = setupRestClientMock({
+                results: DEFAULT_ACTIVITY_RESPONSE,
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            await api.getActivityLogs({
+                objectType: 'comment',
+            })
+
+            expect(requestMock).toHaveBeenCalledWith(
+                'GET',
+                getSyncBaseUri(),
+                ENDPOINT_REST_ACTIVITIES,
+                DEFAULT_AUTH_TOKEN,
+                {
+                    objectType: 'note',
+                },
+            )
+        })
+
+        test('leaves project objectType unchanged', async () => {
+            const requestMock = setupRestClientMock({
+                results: DEFAULT_ACTIVITY_RESPONSE,
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            await api.getActivityLogs({
+                objectType: 'project',
+            })
+
+            expect(requestMock).toHaveBeenCalledWith(
+                'GET',
+                getSyncBaseUri(),
+                ENDPOINT_REST_ACTIVITIES,
+                DEFAULT_AUTH_TOKEN,
+                {
+                    objectType: 'project',
+                },
+            )
+        })
+
+        test('converts legacy "item" to modern "task" in response', async () => {
+            setupRestClientMock({
+                results: [
+                    {
+                        id: '1',
+                        objectType: 'item',
+                        objectId: '123',
+                        eventType: 'added',
+                        eventDate: '2025-01-10T10:00:00Z',
+                        parentProjectId: null,
+                        parentItemId: null,
+                        initiatorId: 'user123',
+                        extraData: {},
+                    },
+                ],
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            const result = await api.getActivityLogs()
+
+            expect(result.results[0].objectType).toBe('task')
+        })
+
+        test('converts legacy "note" to modern "comment" in response', async () => {
+            setupRestClientMock({
+                results: [
+                    {
+                        id: '1',
+                        objectType: 'note',
+                        objectId: '456',
+                        eventType: 'added',
+                        eventDate: '2025-01-10T10:00:00Z',
+                        parentProjectId: null,
+                        parentItemId: null,
+                        initiatorId: 'user123',
+                        extraData: {},
+                    },
+                ],
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            const result = await api.getActivityLogs()
+
+            expect(result.results[0].objectType).toBe('comment')
+        })
+
+        test('leaves project objectType unchanged in response', async () => {
+            setupRestClientMock({
+                results: [
+                    {
+                        id: '1',
+                        objectType: 'project',
+                        objectId: '789',
+                        eventType: 'updated',
+                        eventDate: '2025-01-10T10:00:00Z',
+                        parentProjectId: null,
+                        parentItemId: null,
+                        initiatorId: 'user123',
+                        extraData: {},
+                    },
+                ],
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            const result = await api.getActivityLogs()
+
+            expect(result.results[0].objectType).toBe('project')
+        })
+
+        test('supports backward compatibility with legacy "item" in request', async () => {
+            const requestMock = setupRestClientMock({
+                results: DEFAULT_ACTIVITY_RESPONSE,
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            await api.getActivityLogs({
+                objectType: 'item',
+            })
+
+            expect(requestMock).toHaveBeenCalledWith(
+                'GET',
+                getSyncBaseUri(),
+                ENDPOINT_REST_ACTIVITIES,
+                DEFAULT_AUTH_TOKEN,
+                {
+                    objectType: 'item',
+                },
+            )
+        })
+
+        test('supports backward compatibility with legacy "note" in request', async () => {
+            const requestMock = setupRestClientMock({
+                results: DEFAULT_ACTIVITY_RESPONSE,
+                nextCursor: null,
+            })
+            const api = getTarget()
+
+            await api.getActivityLogs({
+                objectType: 'note',
+            })
+
+            expect(requestMock).toHaveBeenCalledWith(
+                'GET',
+                getSyncBaseUri(),
+                ENDPOINT_REST_ACTIVITIES,
+                DEFAULT_AUTH_TOKEN,
+                {
+                    objectType: 'note',
+                },
+            )
+        })
     })
 })

src/TodoistApi.ts

@@ -91,6 +91,8 @@ import {
     validateProductivityStats,
     validateActivityEventArray,
 } from './utils/validators'
+import { formatDateToYYYYMMDD } from './utils/urlHelpers'
+import { normalizeObjectTypeForApi, denormalizeObjectTypeFromApi } from './utils/activity-helpers'
 import { z } from 'zod'
 
 import { v4 as uuidv4 } from 'uuid'
@@ -1072,18 +1074,35 @@ export class TodoistApi {
      * @returns A promise that resolves to a paginated response of activity events.
      */
     async getActivityLogs(args: GetActivityLogsArgs = {}): Promise<GetActivityLogsResponse> {
+        // Convert Date objects to YYYY-MM-DD strings and modern object types to legacy API types
+        const processedArgs = {
+            ...args,
+            ...(args.since instanceof Date && { since: formatDateToYYYYMMDD(args.since) }),
+            ...(args.until instanceof Date && { until: formatDateToYYYYMMDD(args.until) }),
+            ...(args.objectType && { objectType: normalizeObjectTypeForApi(args.objectType) }),
+        }
+
         const {
             data: { results, nextCursor },
         } = await request<GetActivityLogsResponse>(
             'GET',
             this.syncApiBase,
             ENDPOINT_REST_ACTIVITIES,
             this.authToken,
-            args,
+            processedArgs as Record<string, unknown>,
         )
 
+        // Convert legacy API object types back to modern SDK types
+        const normalizedResults = results.map((event) => {
+            const normalizedType = denormalizeObjectTypeFromApi(event.objectType)
+            return {
+                ...event,
+                objectType: normalizedType || event.objectType,
+            }
+        }) as unknown[]
+
         return {
-            results: validateActivityEventArray(results),
+            results: validateActivityEventArray(normalizedResults),
             nextCursor,
         }
     }

src/types/entities.ts

@@ -402,10 +402,29 @@ export const ColorSchema = z.object({
  */
 export type Color = z.infer<typeof ColorSchema>
 
+/**
+ * @deprecated Use 'task' instead. This will be removed in the next major version.
+ */
+type DeprecatedItem = 'item'
+
+/**
+ * @deprecated Use 'comment' instead. This will be removed in the next major version.
+ */
+type DeprecatedNote = 'note'
+
 /**
  * Type hints for known object types. Accepts any string for forward compatibility.
+ * Supports both modern naming ('task', 'comment') and legacy naming ('item', 'note').
+ *
+ * **Note**: The legacy values 'item' and 'note' are deprecated. Use 'task' and 'comment' instead.
  */
-export type ActivityObjectType = 'item' | 'note' | 'project' | (string & Record<string, never>)
+export type ActivityObjectType =
+    | 'task'
+    | 'comment'
+    | 'project'
+    | DeprecatedItem
+    | DeprecatedNote
+    | (string & Record<string, never>)
 
 /**
  * Type hints for known event types. Accepts any string for forward compatibility.