feat: add Sunsama API TypeScript wrapper as workspace package

[devin-ai-integration]

Summary

Thêm package @workspace/sunsama-api vào monorepo tại lib/integrations/sunsama-api/, dựa trên robertn702/sunsama-api.

Package này cung cấp TypeScript wrapper type-safe cho Sunsama GraphQL API, hỗ trợ quản lý công việc hàng ngày (daily planning & task management).

Tính năng chính:

• SunsamaClient với xác thực email/password hoặc session token
• CRUD tasks: tạo, xóa, hoàn thành, cập nhật text/notes/stream/due date
• Quản lý subtasks: tạo, đổi tên, hoàn thành/bỏ hoàn thành
• Lên lịch & sắp xếp thứ tự task trong ngày
• Tạo & cập nhật calendar events (sync với Google Calendar, v.v.)
• Collaborative editing với Yjs cho task notes
• Chuyển đổi HTML ↔ Markdown
• Validation input với Zod
• Sinh task ID kiểu MongoDB ObjectId

Cấu trúc:

lib/integrations/sunsama-api/
├── package.json          # @workspace/sunsama-api
├── tsconfig.json
└── src/
    ├── client/           # SunsamaClient (inheritance chain)
    │   ├── base.ts       # Auth, HTTP, session management
    │   ├── index.ts      # Assembled client class
    │   └── methods/      # Domain-specific methods
    ├── queries/          # GraphQL queries & mutations
    ├── types/            # TypeScript type definitions
    ├── errors/           # Custom error hierarchy
    └── utils/            # Validation, conversion, dates, collab

Sử dụng trong các package khác:

import { SunsamaClient } from '@workspace/sunsama-api';

const client = new SunsamaClient();
await client.login('email', 'password');
const tasks = await client.getTasksByDay('2026-05-04');

Review & Testing Checklist for Human

• Verify pnpm install và pnpm run typecheck pass thành công
• Kiểm tra @workspace/sunsama-api có thể import được từ các package khác (ví dụ: api-server)
• Test thử kết nối với Sunsama API bằng credentials thật (login + getUser)

Notes

• Package được đặt ở lib/integrations/sunsama-api/ theo workspace pattern lib/integrations/* đã có sẵn trong pnpm-workspace.yaml
• Build artifacts (dist/, *.tsbuildinfo) đã được gitignore
• Không bao gồm test files từ repo gốc — có thể thêm sau nếu cần

Link to Devin session: https://app.devin.ai/sessions/03643b5d5c78409099bb9567ea048010
Requested by: @TanUIUX

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Devin Review found 2 potential issues.

View 6 additional findings in Devin Review.

[devin-ai-integration]

🟡 timeEstimate: 0 silently converted to null due to || operator

At task-lifecycle.ts:333, options?.timeEstimate || null uses the logical OR operator, which treats 0 as falsy. If a user passes timeEstimate: 0 to explicitly set zero minutes (e.g., to clear the estimate on a new task), it gets converted to null ("no estimate"). The updateTaskPlannedTime method at task-updates.ts:256-257 explicitly documents 0 as a valid value for clearing the time estimate, confirming that 0 is semantically meaningful. The nullish coalescing operator ?? should be used instead.

Suggested change

	timeEstimate: options?.timeEstimate || null,
	timeEstimate: options?.timeEstimate ?? null,

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 ObjectId counter off-by-one: % 0xffffff never produces the max 3-byte value

In the getNextCounter method, (counter + 1) % 0xffffff produces values in the range [0, 0xfffffe] (0 to 16777214), skipping 0xffffff (16777215). A 3-byte counter should cover the full range [0, 0xffffff], so the modulus should be 0x1000000 (16777216). Additionally, the initial value at base.ts:301 (Math.floor(Math.random() * 0xffffff)) also never produces 0xffffff; it should be Math.floor(Math.random() * 0x1000000).

Suggested change

	SunsamaClientBase._counter = (SunsamaClientBase._counter + 1) % 0xffffff;
	SunsamaClientBase._counter = (SunsamaClientBase._counter + 1) % 0x1000000;

---

Was this helpful? React with 👍 or 👎 to provide feedback.