roster.ts

packages/ninety-client/src/roster.ts

1. /**
2. * Roster: user id -> name.
3. *
4. * `GET /users` returns every active user in the company, and
5. * `GET /users/team/{teamId}` returns team membership that `GET /teams` does not
6. * carry. Harvesting from payloads is still the cheapest source, and it is what
7. * runs. Every to-do carries `createdBy` next to
8. * `createdByUserId`, and every company to-do carries `ownerFirstName` /
9. * `ownerLastName` inline, which resolves the whole roster on that path for zero
10. * extra requests. `note()` is how those get recorded.
11. *
12. * Sources, cheapest first:
13. * 1. SEED - pinned roster.json. Never expires, never overwritten. Keeps
14. * someone with zero to-dos visible instead of silently absent:
15. * the company sweep only returns people with open work.
16. * 2. NOTED - free pairs off to-do payloads. No request at all.
17. * 3. FETCH - GET /users/{id} for whoever is still unknown.
18. *
19. * Merge, never replace. A refresh that drops people is worse than a stale name.
20. */
22. import type { HttpClient } from './http.js'
23. import { NinetyError } from './errors.js'
24. import { RawUserSchema, normalizeUserName, UNASSIGNED, UNKNOWN_PERSON, type Person } from './types.js'
26. export interface RosterEntry {
27. id: string
28. name: string
29. }
31. export interface RosterOptions {
32. /** Pinned entries from roster.json. Always win. */
33. seed?: RosterEntry[]
34. /** How long a fetched name stays fresh. Default 24h; people rarely rename. */
35. ttlMs?: number
36. now?: () => number
37. }
39. type Source = 'seed' | 'noted' | 'fetch'
41. interface CacheEntry {
42. name: string
43. fetchedAt: number
44. source: Source
45. }
47. export class Roster {
48. private readonly cache = new Map<string, CacheEntry>()
49. private readonly inflight = new Map<string, Promise<void>>()
50. private readonly failed = new Set<string>()
51. private readonly ttlMs: number
52. private readonly now: () => number
54. constructor(
55. private readonly http: HttpClient,
56. opts: RosterOptions = {},
57. ) {
58. this.ttlMs = opts.ttlMs ?? 24 * 60 * 60 * 1000
59. this.now = opts.now ?? (() => Date.now())
60. for (const e of opts.seed ?? []) {
61. this.cache.set(e.id, { name: e.name, fetchedAt: this.now(), source: 'seed' })
62. }
63. }
65. /**
66. * Record a free id -> name pair seen in a payload (e.g. createdByUserId +
67. * createdBy on a to-do). Costs nothing and removes the id from the fetch list.
68. * Never overrides a pinned seed entry.
69. */
70. note(id: string, name: string): void {
71. if (!id || !name) return
72. if (this.cache.get(id)?.source === 'seed') return
73. this.cache.set(id, { name, fetchedAt: this.now(), source: 'noted' })
74. this.failed.delete(id)
75. }
77. /** Synchronous lookup. Never returns a raw id as a name. */
78. lookup(id: string | null | undefined): Person {
79. if (!id) return UNASSIGNED
80. const hit = this.cache.get(id)
81. return hit ? { id, name: hit.name } : UNKNOWN_PERSON(id)
82. }
84. /** Fuzzy name -> entries. */
85. find(query: string): RosterEntry[] {
86. const q = query.trim().toLowerCase()
87. if (!q) return []
88. return [...this.cache]
89. .filter(([, e]) => e.name.toLowerCase().includes(q))
90. .map(([id, e]) => ({ id, name: e.name }))
91. .sort((a, b) => a.name.localeCompare(b.name))
92. }
94. /** Ensure every id is resolved. Deduped; the HTTP token bucket paces it. */
95. async resolveMany(ids: Iterable<string>): Promise<void> {
96. const wanted = [...new Set([...ids].filter((id) => id && this.needsFetch(id)))]
97. await Promise.all(wanted.map((id) => this.resolveOne(id)))
98. }
100. private needsFetch(id: string): boolean {
101. if (this.failed.has(id)) return false
102. const hit = this.cache.get(id)
103. if (!hit) return true
104. // Seeded and noted names came from a trusted payload; do not spend a request
105. // re-confirming them.
106. if (hit.source !== 'fetch') return false
107. return this.now() - hit.fetchedAt > this.ttlMs
108. }
110. private resolveOne(id: string): Promise<void> {
111. const existing = this.inflight.get(id)
112. if (existing) return existing
114. const p = (async () => {
115. try {
116. const raw = await this.http.get(`/users/${encodeURIComponent(id)}`)
117. const parsed = RawUserSchema.safeParse(raw)
118. const name = parsed.success ? normalizeUserName(parsed.data) : null
119. if (name) {
120. if (this.cache.get(id)?.source !== 'seed') {
121. this.cache.set(id, { name, fetchedAt: this.now(), source: 'fetch' })
122. }
123. } else {
124. this.failed.add(id)
125. }
126. } catch (err) {
127. // A deactivated or invisible user must not fail the whole sync. Auth
128. // failures are different: those mean nothing will work, so re-throw.
129. if (err instanceof NinetyError && (err.status === 401 || err.status === 403)) throw err
130. this.failed.add(id)
131. } finally {
132. this.inflight.delete(id)
133. }
134. })()
136. this.inflight.set(id, p)
137. return p
138. }
140. /** Ids that could not be resolved. Surface these; do not swallow them. */
141. get unresolved(): string[] {
142. return [...this.failed]
143. }
145. /** Where the names came from. Useful for a sync log line. */
146. stats(): Record<Source, number> & { unresolved: number } {
147. const out = { seed: 0, noted: 0, fetch: 0, unresolved: this.failed.size }
148. for (const e of this.cache.values()) out[e.source]++
149. return out
150. }
152. /** Everything known, for pinning back into roster.json. */
153. toEntries(): RosterEntry[] {
154. return [...this.cache]
155. .map(([id, e]) => ({ id, name: e.name }))
156. .sort((a, b) => a.name.localeCompare(b.name))
157. }
158. }