types.ts

packages/ninety-client/src/types.ts

1. /**
2. * Schemas and normalized domain types.
3. *
4. * Field names below are verified against live responses from GET /teams and
5. * POST /todos/query. Two things the live data shows that shape this file:
6. *
7. * 1. `createdBy` is a display name ("Ines Carvalho") sitting right next to
8. * `createdByUserId`. That is a free id -> name pair on every single to-do,
9. * and it cuts most of the GET /users/{id} traffic out of roster building.
10. * 2. `teamName` is denormalized onto the to-do, so nothing needs to join
11. * against /teams just to render a row.
12. */
14. import { z } from 'zod'
15. import { MERIDIAN_TZ, dueLabel, localDay } from './dates.js'
17. /** A person, after roster hydration. Never expose a bare id above the client. */
18. export interface Person {
19. id: string
20. /** Falls back to "unknown user". Never a raw ObjectId. */
21. name: string
22. }
24. export const UNKNOWN_PERSON = (id: string): Person => ({ id, name: 'unknown user' })
25. export const UNASSIGNED: Person = { id: '', name: 'unassigned' }
27. // --- raw (wire) schemas -----------------------------------------------------
29. /**
30. * Live shape confirmed. Still `.passthrough()` because Ninety may add fields,
31. * and optional on everything Meridian's data does not exercise.
32. */
33. export const RawTodoSchema = z
34. .object({
35. _id: z.string(),
36. userId: z.string().optional(),
37. teamId: z.string().optional(),
38. teamName: z.string().optional(),
39. title: z.string().optional(),
40. /** HTML, not plain text. See stripHtml(). */
41. description: z.string().optional(),
42. dueDate: z.string().nullable().optional(),
43. originalDueDate: z.string().nullable().optional(),
44. isPersonal: z.boolean().optional(),
45. /** Display name of the creator. The free half of a roster entry. */
46. createdBy: z.string().optional(),
47. createdByUserId: z.string().optional(),
48. createdDate: z.string().optional(),
49. /** "Weekly", "Monthly", "Never", ... */
50. repeat: z.string().nullable().optional(),
51. /** Shared by every materialized instance of a recurring to-do. */
52. seriesId: z.string().nullable().optional(),
53. companyId: z.string().optional(),
54. milestoneId: z.string().nullable().optional(),
55. autoGenerated: z.boolean().optional(),
56. dueDateChanged: z.boolean().optional(),
57. comments: z.array(z.unknown()).optional(),
58. archived: z.boolean().optional(),
59. archivedDate: z.string().nullable().optional(),
60. completed: z.boolean().optional(),
61. completedDate: z.string().nullable().optional(),
62. completedByUserId: z.string().nullable().optional(),
63. deleted: z.boolean().optional(),
64. followers: z.array(z.string()).optional(),
65. ordinal: z.number().nullable().optional(),
66. /**
67. * Nullable, and that is not defensive typing: live records carry `null`
68. * here as well as numbers, and nothing reads `_version`, so strictness on it
69. * would only discard records (rule 4).
70. *
71. * On a record we do not control, prefer `.nullable().optional()` for
72. * anything not actually consumed. Strictness
73. * should defend the fields decisions are made from, not fields nobody reads.
74. */
75. _version: z.number().nullable().optional(),
76. })
77. .passthrough()
79. export type RawTodo = z.infer<typeof RawTodoSchema>
81. /**
82. * Live shape confirmed. Note what is not here: any form of
83. * membership. No users, no members, no userIds. The roster harvest in roster.ts
84. * is required, not a fallback.
85. */
86. export const RawTeamSchema = z
87. .object({
88. _id: z.string(),
89. name: z.string().optional(),
90. companyId: z.string().optional(),
91. /** Ninety models projects as teams. Usually not wanted on a team dashboard. */
92. project: z.boolean().optional(),
93. deleted: z.boolean().optional(),
94. })
95. .passthrough()
97. export type RawTeam = z.infer<typeof RawTeamSchema>
99. /**
100. * GET /todos/company returns a different, thinner row than POST /todos/query:
101. * exactly these nine fields on every row, verified against live data, with
102. * nothing else.
103. *
104. * The two differences that will bite:
105. *
106. * 1. `id`, not `_id`. Every other endpoint uses `_id`. Normalize before use.
107. * 2. No `completed`, `archived`, `deleted`, `isPersonal`, `seriesId`,
108. * `milestoneId`, `createdByUserId`. So you cannot filter on completion
109. * client-side from this payload, and you cannot collapse recurrence.
110. *
111. * (2) is fine in practice because the endpoint's own defaults already exclude
112. * completed, archived, deleted, and personal items; the absent fields are
113. * absent precisely because every row is open. But it means this is an index,
114. * not a record. When you need the full shape, hydrate via GET /todos/{id},
115. * which returns all 33 fields. See TodosResource.company()
116. * vs companyDetailed().
117. *
118. * The compensation: `ownerFirstName` / `ownerLastName` ride along, so rendering
119. * a name needs no roster join at all.
120. */
121. export const RawCompanyTodoSchema = z
122. .object({
123. id: z.string(),
124. companyId: z.string().optional(),
125. teamId: z.string().optional(),
126. userId: z.string().optional(),
127. title: z.string().optional(),
128. /** HTML, same as the fat shape. See stripHtml(). */
129. description: z.string().optional(),
130. dueDate: z.string().nullable().optional(),
131. ownerFirstName: z.string().optional(),
132. ownerLastName: z.string().optional(),
133. })
134. .passthrough()
136. export type RawCompanyTodo = z.infer<typeof RawCompanyTodoSchema>
138. /**
139. * Thin index row -> the fat wire shape, so one normalizer serves both endpoints.
140. *
141. * The `false` defaults are not guesses. GET /todos/company returns only open,
142. * non-archived, non-deleted, non-personal to-dos, so those four values are known
143. * even though the fields are absent. Everything genuinely unknowable (seriesId,
144. * milestoneId, completedDate) stays null, and hydration is how you learn it.
145. */
146. export function companyTodoToRaw(row: RawCompanyTodo): RawTodo {
147. const { id, ownerFirstName, ownerLastName, ...rest } = row
148. return {
149. ...rest,
150. _id: id,
151. completed: false,
152. archived: false,
153. deleted: false,
154. isPersonal: false,
155. } as RawTodo
156. }
158. /** "Hazel Okafor" from the inline owner fields, or null if neither is present. */
159. export function companyOwnerName(row: RawCompanyTodo): string | null {
160. const joined = [row.ownerFirstName, row.ownerLastName].filter(Boolean).join(' ').trim()
161. return joined || null
162. }
164. /**
165. * From GET /users, which returns all active users in the company with
166. * `firstName` / `lastName`. Kept permissive because `GET /users/{id}` has not
167. * been captured on its own and may differ.
168. */
169. export const RawUserSchema = z
170. .object({
171. _id: z.string().optional(),
172. id: z.string().optional(),
173. firstName: z.string().optional(),
174. lastName: z.string().optional(),
175. fullName: z.string().optional(),
176. name: z.string().optional(),
177. email: z.string().optional(),
178. active: z.boolean().optional(),
179. })
180. .passthrough()
182. export type RawUser = z.infer<typeof RawUserSchema>
184. // --- normalized domain types ------------------------------------------------
186. export interface Todo {
187. id: string
188. title: string
189. /** HTML stripped. Safe for a model's context and for a text cell. */
190. description: string
191. /** Original markup, for a dashboard that wants to render it. */
192. descriptionHtml: string
193. /** Raw instant from Ninety. Correct for comparisons, wrong to slice for display. */
194. dueDate: string | null
195. /**
196. * The calendar day the due date actually falls on, in Meridian's timezone.
197. * "2026-08-07" for a wire value of "2026-08-08T04:59:59.999Z".
198. * Display and grouping use this. See dates.ts for why.
199. */
200. dueDateLocal: string | null
201. /** "Aug 7 (2 days overdue)". For humans and for models. */
202. dueLabel: string
203. completed: boolean
204. completedDate: string | null
205. archived: boolean
206. deleted: boolean
207. /** Hydrated from userId. Never a bare id. */
208. owner: Person
209. /** Hydrated from createdByUserId, usually free via the createdBy name. */
210. createdBy: Person
211. teamId: string | null
212. /** Denormalized by Ninety. No join needed. */
213. teamName: string | null
214. isPersonal: boolean
215. /** "Weekly" etc, or null for a one-off. */
216. repeat: string | null
217. /** Shared across every instance of a recurring to-do. See collapseSeries(). */
218. seriesId: string | null
219. /** Set when the to-do hangs off a rock milestone. */
220. milestoneId: string | null
221. followers: string[]
222. createdAt: string | null
223. raw: RawTodo
224. }
226. export interface Team {
227. id: string
228. name: string
229. companyId: string | null
230. /** Ninety models projects as teams. Filter these out of team views. */
231. isProject: boolean
232. deleted: boolean
233. raw: RawTeam
234. }
236. // --- helpers ----------------------------------------------------------------
238. /**
239. * Ninety stores to-do descriptions as HTML, inline styles and all.
240. *
241. * Feeding that to a model burns context on markup, and dropping it into a page
242. * unescaped is an injection. Strip to text; keep the original alongside for any
243. * consumer that genuinely wants to render it (and can sanitize properly).
244. */
245. export function stripHtml(html: string): string {
246. return html
247. .replace(/<\s*(br|\/li|\/p|\/div|\/tr)\s*\/?>/gi, '\n')
248. .replace(/<\s*li[^>]*>/gi, '- ')
249. .replace(/<[^>]+>/g, '')
250. .replace(/ /gi, ' ')
251. .replace(/&/gi, '&')
252. .replace(/&lt;/gi, '<')
253. .replace(/>/gi, '>')
254. .replace(/"/gi, '"')
255. .replace(/'/gi, "'")
256. .replace(/[ \t]+/g, ' ')
257. .replace(/\n{3,}/g, '\n\n')
258. .trim()
259. }
261. export interface NormalizeOptions {
262. /** Defaults to America/Chicago. */
263. tz?: string
264. /** Injectable for deterministic tests. */
265. now?: Date
266. }
268. export function normalizeTodo(
269. raw: RawTodo,
270. resolve: (id: string | null | undefined) => Person,
271. opts: NormalizeOptions = {},
272. ): Todo {
273. const html = raw.description ?? ''
274. const tz = opts.tz ?? MERIDIAN_TZ
275. const now = opts.now ?? new Date()
276. const due = raw.dueDate ?? null
277. return {
278. id: raw._id,
279. title: raw.title?.trim() || '(untitled)',
280. description: stripHtml(html),
281. descriptionHtml: html,
282. dueDate: due,
283. dueDateLocal: due ? localDay(due, tz) : null,
284. dueLabel: dueLabel(due, now, tz),
285. completed: raw.completed ?? false,
286. completedDate: raw.completedDate ?? null,
287. archived: raw.archived ?? false,
288. deleted: raw.deleted ?? false,
289. owner: resolve(raw.userId),
290. createdBy: resolve(raw.createdByUserId),
291. teamId: raw.teamId ?? null,
292. teamName: raw.teamName ?? null,
293. isPersonal: raw.isPersonal ?? false,
294. repeat: raw.repeat && raw.repeat !== 'Never' ? raw.repeat : null,
295. seriesId: raw.seriesId ?? null,
296. milestoneId: raw.milestoneId ?? null,
297. followers: raw.followers ?? [],
298. createdAt: raw.createdDate ?? null,
299. raw,
300. }
301. }
303. export function normalizeTeam(raw: RawTeam): Team {
304. return {
305. id: raw._id,
306. name: raw.name?.trim() || '(unnamed team)',
307. companyId: raw.companyId ?? null,
308. isProject: raw.project ?? false,
309. deleted: raw.deleted ?? false,
310. raw,
311. }
312. }
314. export function normalizeUserName(raw: RawUser): string | null {
315. const pick = (...v: (string | undefined)[]) => v.find((s) => typeof s === 'string' && s.length > 0) ?? null
316. const full = pick(raw.fullName, raw.name)
317. if (full) return full
318. const joined = [raw.firstName, raw.lastName].filter(Boolean).join(' ').trim()
319. return joined || pick(raw.email)
320. }
322. /**
323. * Collapse recurring to-dos to one row per series.
324. *
325. * A weekly recurring to-do is materialized by Ninety as a separate to-do per
326. * occurrence, all sharing a seriesId, so the same to-do can be open twice a
327. * week apart.
328. *
329. * So a naive "count of open to-dos" counts one piece of work N times, and every
330. * uncompleted past occurrence stays on the overdue list forever. On a dashboard
331. * whose whole value is that people trust the number before the morning meeting, that is not
332. * a cosmetic problem.
333. *
334. * Default keeps the earliest-due open occurrence, because that is the one that
335. * is actually late. Undated items sort last. Non-recurring to-dos pass through.
336. *
337. * Keyed by series and owner. Recurrence duplicates a row for one person; it
338. * never spreads one across several. Shared assignment does the opposite: the
339. * same title on two or three different owners, and collapsing those would
340. * erase who owes what, which is the
341. * one thing the workload panel exists to show. Keying on seriesId alone would do
342. * exactly that if Ninety ever files a shared item under a common series. Owner is
343. * therefore part of the key, permanently, and not as a defensive maybe.
344. *
345. * For the shared-assignment case you want assignmentGroups(), not this.
346. */
347. export function collapseSeries(todos: Todo[], keep: 'earliest' | 'latest' = 'earliest'): Todo[] {
348. const bySeries = new Map<string, Todo>()
349. const out: Todo[] = []
351. for (const t of todos) {
352. if (!t.seriesId) {
353. out.push(t)
354. continue
355. }
356. // U+0000 as the separator, because it cannot occur in a Ninety id and so
357. // cannot collide the way any printable delimiter could.
358. //
359. // Written as an escape, not a raw byte (rule 8). A literal 0x00 compiles
360. // fine but makes `file` classify the source as binary, and grep then prints
361. // nothing for it, with no error. The escape is the same string at runtime
362. // (length 3, codePointAt(1) === 0). Do not "simplify" it back.
363. const key = `${t.seriesId}\u0000${t.owner.id}`
364. const held = bySeries.get(key)
365. if (!held) {
366. bySeries.set(key, t)
367. continue
368. }
369. bySeries.set(key, preferred(held, t, keep))
370. }
372. return [...out, ...bySeries.values()]
373. }
375. /**
376. * One commitment carried by several people, as opposed to one repeating for one
377. * person. These are opposites and the dashboard must not confuse them.
378. *
379. * On live data, titles that appear more than once belong to distinct owners,
380. * not to one owner repeating, so a headline count of rows ("31 assignments")
381. * overstates the work ("24 commitments").
382. *
383. * Heuristic, and honestly so. Ninety exposes no link field joining the copies:
384. * the index payload has none, and whether the hydrated records share a seriesId
385. * or milestoneId is what sharedLinkAudit() is for. Until that says otherwise the
386. * join is title + team, which will occasionally merge two genuinely different
387. * items that happen to share a name. That is why `basis` is on every group:
388. * surface it, do not bury it.
389. *
390. * Per-person views must keep every row. Only company-level counts dedupe.
391. */
392. export interface AssignmentGroup {
393. /** Normalized join key. Not stable across title edits; do not persist it. */
394. key: string
395. title: string
396. teamId: string | null
397. todos: Todo[]
398. owners: Person[]
399. /** How the grouping was decided. 'title' is heuristic; say so in the UI. */
400. basis: 'title'
401. /** True when more than one person carries this commitment. */
402. shared: boolean
403. }
405. export function assignmentGroups(todos: Todo[]): AssignmentGroup[] {
406. const groups = new Map<string, AssignmentGroup>()
408. for (const t of todos) {
409. // U+0000 separator, as an escape rather than a raw byte -- see the note in
410. // collapseSeries() above for why that distinction is load-bearing.
411. const key = `${normalizeTitle(t.title)}\u0000${t.teamId ?? ''}`
412. let g = groups.get(key)
413. if (!g) {
414. g = { key, title: t.title, teamId: t.teamId, todos: [], owners: [], basis: 'title', shared: false }
415. groups.set(key, g)
416. }
417. g.todos.push(t)
418. if (!g.owners.some((o) => o.id === t.owner.id)) g.owners.push(t.owner)
419. g.shared = g.owners.length > 1
420. }
422. return [...groups.values()]
423. }
425. /**
426. * The two numbers that belong next to each other on the page.
427. *
428. * `assignments` is how many rows exist; `commitments` is how many distinct
429. * pieces of work they represent. Showing one without the other is how a count
430. * becomes an argument in the morning meeting.
431. */
432. export function assignmentSpread(todos: Todo[]): {
433. assignments: number
434. commitments: number
435. sharedCommitments: number
436. maxOwners: number
437. } {
438. const groups = assignmentGroups(todos)
439. return {
440. assignments: todos.length,
441. commitments: groups.length,
442. sharedCommitments: groups.filter((g) => g.shared).length,
443. maxOwners: groups.reduce((m, g) => Math.max(m, g.owners.length), 0),
444. }
445. }
447. /**
448. * Answers the open question: do shared copies share a link field, or is title
449. * matching all we have?
450. *
451. * Run this against hydrated to-dos (companyDetailed), because the index payload
452. * carries neither seriesId nor milestoneId. If `sharesSeriesId` or
453. * `sharesMilestoneId` comes back true for every shared group, replace the title
454. * heuristic in assignmentGroups() with that field and delete this function's
455. * reason for existing. If both are false, the heuristic is the ceiling and the
456. * UI should say "grouped by title" wherever it dedupes.
457. */
458. export function sharedLinkAudit(todos: Todo[]): {
459. sharedGroups: number
460. sharesSeriesId: number
461. sharesMilestoneId: number
462. linkable: boolean
463. detail: { title: string; owners: number; seriesId: string | null; milestoneId: string | null }[]
464. } {
465. const shared = assignmentGroups(todos).filter((g) => g.shared)
466. const detail = shared.map((g) => {
467. const series = new Set(g.todos.map((t) => t.seriesId))
468. const milestone = new Set(g.todos.map((t) => t.milestoneId))
469. return {
470. title: g.title,
471. owners: g.owners.length,
472. seriesId: series.size === 1 ? ([...series][0] ?? null) : null,
473. milestoneId: milestone.size === 1 ? ([...milestone][0] ?? null) : null,
474. }
475. })
476. const sharesSeriesId = detail.filter((d) => d.seriesId !== null).length
477. const sharesMilestoneId = detail.filter((d) => d.milestoneId !== null).length
478. return {
479. sharedGroups: shared.length,
480. sharesSeriesId,
481. sharesMilestoneId,
482. linkable: shared.length > 0 && (sharesSeriesId === shared.length || sharesMilestoneId === shared.length),
483. detail,
484. }
485. }
487. /** Whitespace and case only. Deliberately not fuzzy; near-matches must not merge. */
488. function normalizeTitle(title: string): string {
489. return title.replace(/\s+/g, ' ').trim().toLowerCase()
490. }
492. function preferred(a: Todo, b: Todo, keep: 'earliest' | 'latest'): Todo {
493. const ta = a.dueDate ? Date.parse(a.dueDate) : Number.POSITIVE_INFINITY
494. const tb = b.dueDate ? Date.parse(b.dueDate) : Number.POSITIVE_INFINITY
495. if (ta === tb) return a
496. if (keep === 'earliest') return ta < tb ? a : b
497. const fa = Number.isFinite(ta) ? ta : Number.NEGATIVE_INFINITY
498. const fb = Number.isFinite(tb) ? tb : Number.NEGATIVE_INFINITY
499. return fa > fb ? a : b
500. }
502. /** How many extra rows recurrence is contributing. Worth logging on every sync. */
503. export function seriesInflation(todos: Todo[]): { total: number; collapsed: number; duplicates: number } {
504. const collapsed = collapseSeries(todos).length
505. return { total: todos.length, collapsed, duplicates: todos.length - collapsed }
506. }