client.ts

packages/ninety-client/src/client.ts

1. /**
2. * NinetyClient: the thing everything else imports.
3. *
4. * Read-only by design: write methods are deliberately absent. The board has no
5. * write-back to Ninety (rule 12).
6. */
8. import { HttpClient, type HttpOptions } from './http.js'
9. import { Roster, type RosterEntry, type RosterOptions } from './roster.js'
10. import { TodosResource, type HydrationFailure } from './resources/todos.js'
11. import { TeamsResource } from './resources/teams.js'
12. import { assignmentSpread, seriesInflation, sharedLinkAudit, type Todo } from './types.js'
13. import { MERIDIAN_TZ } from './dates.js'
15. export interface NinetyClientOptions extends HttpOptions {
16. /** Pinned roster entries, normally loaded from roster.json. */
17. roster?: RosterEntry[]
18. rosterOptions?: Omit<RosterOptions, 'seed'>
19. /**
20. * Timezone for date display and grouping. Defaults to America/Chicago.
21. *
22. * This is not cosmetic. Ninety serializes due dates as end-of-day local time
23. * in UTC, so getting this wrong shifts every date by a day. See dates.ts.
24. */
25. tz?: string
26. }
28. export interface SyncSnapshot {
29. todos: Todo[]
30. /** When the sync ran. Put this on the page; polling means never live. */
31. syncedAt: string
32. roster: ReturnType<Roster['stats']>
33. /** How many rows recurrence is contributing. Log it; it explains count drift. */
34. recurrence: ReturnType<typeof seriesInflation>
35. /** Ids that stayed "unknown user". Non-empty is a problem worth seeing. */
36. unresolvedUsers: string[]
37. }
39. export interface CompanySnapshot {
40. todos: Todo[]
41. /** When the sync ran. Put this on the page; polling means never live. */
42. syncedAt: string
43. /** False means the thin index shape: no seriesId, milestoneId or date churn. */
44. detailed: boolean
45. /**
46. * Assignments vs commitments. Show both. On live data a real share of rows are
47. * one commitment shared between two or three people, so a headline counting
48. * rows overstates the work and hides the fact that some of it is jointly
49. * owned.
50. */
51. spread: ReturnType<typeof assignmentSpread>
52. /** How many rows recurrence contributed. Log it; it explains count drift. */
53. recurrence: ReturnType<typeof seriesInflation>
54. /** null when detailed:false; the audit needs fields the index does not carry. */
55. sharedLinks: ReturnType<typeof sharedLinkAudit> | null
56. /** Rows that stayed on their thin version, with the reason. See HydrationFailure. */
57. hydrationFailures: HydrationFailure[]
58. roster: ReturnType<Roster['stats']>
59. unresolvedUsers: string[]
60. }
62. export class NinetyClient {
63. readonly http: HttpClient
64. readonly roster: Roster
65. readonly todos: TodosResource
66. readonly teams: TeamsResource
67. readonly tz: string
69. constructor(opts: NinetyClientOptions) {
70. this.http = new HttpClient(opts)
71. this.roster = new Roster(this.http, { ...opts.rosterOptions, seed: opts.roster })
72. this.tz = opts.tz ?? MERIDIAN_TZ
73. this.todos = new TodosResource(this.http, this.roster, { tz: this.tz })
74. this.teams = new TeamsResource(this.http)
75. }
77. /**
78. * One open-to-do sweep with everything the dashboard needs to render and to
79. * explain itself.
80. *
81. * Deliberately does not collapse recurring series; that is a presentation
82. * decision. It does report how many duplicate rows recurrence produced, so a
83. * count that looks wrong can be explained instead of argued about.
84. */
85. async snapshot(opts: { teamId?: string; now?: () => Date } = {}): Promise<SyncSnapshot> {
86. const now = opts.now ?? (() => new Date())
87. const query = opts.teamId ? { teamId: opts.teamId } : {}
88. const todos = await this.todos.list(query)
89. return {
90. todos,
91. syncedAt: now().toISOString(),
92. roster: this.roster.stats(),
93. recurrence: seriesInflation(todos),
94. unresolvedUsers: this.roster.unresolved,
95. }
96. }
98. /**
99. * The company-wide sweep. This is what the dashboard and the morning briefing
100. * actually run on.
101. *
102. * One token, every person, via GET /todos/company. Requires Owner or Admin in
103. * Ninety. A 403 here means the role, not the code, and NinetyForbiddenError
104. * says so.
105. *
106. * `detailed` defaults to true because the thin index row carries no seriesId,
107. * milestoneId or dueDateChanged, and without those you cannot collapse
108. * recurrence, link a to-do to its rock, or spot a date that has moved four
109. * times. Pass false only when you want a fast headcount and nothing else.
110. *
111. * Like snapshot(), this deliberately does not collapse or dedupe. Both are
112. * presentation decisions and both have a correct answer that depends on the
113. * panel: per-person views keep every row, company counts dedupe. What it does
114. * instead is hand you the numbers to explain either one.
115. */
116. async companySnapshot(
117. opts: { detailed?: boolean; now?: () => Date; maxPages?: number } = {},
118. ): Promise<CompanySnapshot> {
119. const now = opts.now ?? (() => new Date())
120. const detailed = opts.detailed ?? true
121. const iterOpts = opts.maxPages === undefined ? {} : { maxPages: opts.maxPages }
123. const { todos, hydrationFailures } = detailed
124. ? await this.todos.companyDetailed(iterOpts)
125. : { todos: await this.todos.company(iterOpts), hydrationFailures: [] as HydrationFailure[] }
127. return {
128. todos,
129. syncedAt: now().toISOString(),
130. detailed,
131. spread: assignmentSpread(todos),
132. recurrence: seriesInflation(todos),
133. sharedLinks: detailed ? sharedLinkAudit(todos) : null,
134. hydrationFailures,
135. roster: this.roster.stats(),
136. unresolvedUsers: this.roster.unresolved,
137. }
138. }
139. }
141. /**
142. * Where a missing credential actually comes from.
143. *
144. * Naming the shell rather than the code is the point. There is no .env reader in
145. * this repo, so "NINETY_TOKEN is not set" almost always means this shell never
146. * sourced the profile (a new terminal, or one an editor spawned). The same
147. * wording is in preflight() in apps/dashboard/src/main.ts.
148. */
149. const SHELL_HINT =
150. 'Credentials come from the shell profile; this repo has no .env reader. ' +
151. 'See credentials.example.sh, then open a NEW terminal; an existing one keeps ' +
152. 'the old environment. Check what the shell has: env | grep NINETY'
154. /** Build a client from environment variables. */
155. export function clientFromEnv(
156. env: Record<string, string | undefined>,
157. roster?: RosterEntry[],
158. ): NinetyClient {
159. const token = env.NINETY_TOKEN
160. if (!token) {
161. // Points at the shell profile, never at a credentials file: nothing reads
162. // one, and the message must not send people to create the thing the
163. // credentials policy forbids.
164. throw new Error(
165. 'NINETY_TOKEN is not set. It must be a Personal Access Token belonging to a ' +
166. 'company Owner or Admin. ' + SHELL_HINT,
167. )
168. }
169. const opts: NinetyClientOptions = { token }
170. if (env.NINETY_BASE_URL) opts.baseUrl = env.NINETY_BASE_URL
171. if (env.NINETY_RPS) opts.rps = Number(env.NINETY_RPS)
172. if (env.NINETY_DEBUG === 'true') opts.debug = true
173. if (roster) opts.roster = roster
174. return new NinetyClient(opts)
175. }