meetings.test.ts

packages/fathom-client/test/meetings.test.ts

1. /**
2. * The Fathom client, pinned against how the API actually behaves.
3. *
4. * Two behaviours are worth pinning:
5. *
6. * The pagination sentinel is an empty string. Verified live: `next_cursor: ""`
7. * with `limit: 10`, not null and not absent. A loop written as
8. * `while (cursor !== undefined)` would page forever. Vendor docs and the wire
9. * disagree often enough (Plinth's unassigned sentinel is documented as `---`
10. * and sent as `--`) that the live probe came before this file.
11. *
12. * The 401 message must not diagnose. Fathom's FAQ lists four causes for a 401
13. * that the response cannot tell apart, and a message asserting one of them
14. * (say, "expired") can send someone to invalidate a working credential. The
15. * test asserts the message offers candidates rather than picking one.
16. */
18. import { describe, expect, it } from 'vitest'
19. import { FathomClient, FathomError } from '../src/http.js'
20. import { MeetingsResource } from '../src/resources/meetings.js'
22. const meeting = (id: number) => ({
23. title: `Meeting ${id}`,
24. recording_id: id,
25. url: `https://fathom.video/calls/${id}`,
26. created_at: '2026-09-02T14:00:00Z',
27. shared_with: 'no_teams',
28. calendar_invitees: [],
29. recorded_by: { name: 'Sam Whitaker - Meridian Display', email: 'hello@meridiandisplay.example' },
30. action_items: [],
31. })
33. /** Replays scripted responses and records the URLs asked for. */
34. function fake(pages: { body: unknown; status?: number; headers?: Record<string, string> }[]) {
35. const urls: string[] = []
36. const fetchImpl = (async (url: string) => {
37. urls.push(String(url))
38. const p = pages[urls.length - 1] ?? { body: { items: [], next_cursor: '' } }
39. return new Response(JSON.stringify(p.body), {
40. status: p.status ?? 200,
41. headers: { 'content-type': 'application/json', ...(p.headers ?? {}) },
42. })
43. }) as unknown as typeof fetch
44. return { urls, fetchImpl }
45. }
47. const resource = (fetchImpl: typeof fetch, sleep = async () => {}) =>
48. new MeetingsResource(new FathomClient({ apiKey: 'k', owner: 'Sam', fetchImpl, sleep }))
50. describe('pagination stops on the empty-string cursor', () => {
51. it('stops after one page when next_cursor is ""', async () => {
52. const { urls, fetchImpl } = fake([{ body: { items: [meeting(1)], next_cursor: '', limit: 10 } }])
53. const w = await resource(fetchImpl).listSince('2026-08-01T00:00:00Z')
54. expect(w.meetings).toHaveLength(1)
55. expect(w.pages).toBe(1)
56. expect(w.truncated).toBe(false)
57. expect(urls).toHaveLength(1)
58. })
60. it.each([[null], [undefined]])('also stops on next_cursor=%s', async (sentinel) => {
61. const { fetchImpl } = fake([{ body: { items: [meeting(1)], next_cursor: sentinel } }])
62. const w = await resource(fetchImpl).listSince('2026-08-01T00:00:00Z')
63. expect(w.truncated).toBe(false)
64. expect(w.pages).toBe(1)
65. })
67. it('follows a non-empty cursor and passes it back', async () => {
68. const { urls, fetchImpl } = fake([
69. { body: { items: [meeting(1)], next_cursor: 'CURSOR_A' } },
70. { body: { items: [meeting(2)], next_cursor: '' } },
71. ])
72. const w = await resource(fetchImpl).listSince('2026-08-01T00:00:00Z')
73. expect(w.meetings.map((m) => m.recording_id)).toEqual([1, 2])
74. expect(urls[1]).toContain('cursor=CURSOR_A')
75. expect(w.truncated).toBe(false)
76. })
77. })
79. describe('a capped sweep is labelled, not silently short', () => {
80. it('returns what it fetched with truncated:true', async () => {
81. // Never throw away fetched data to guard against a hypothetical.
82. const pages = Array.from({ length: 5 }, (_, i) => ({
83. body: { items: [meeting(i + 1)], next_cursor: `MORE_${i}` },
84. }))
85. const w = await resource(fake(pages).fetchImpl).listSince('2026-08-01T00:00:00Z', 3)
86. expect(w.pages).toBe(3)
87. expect(w.meetings).toHaveLength(3)
88. expect(w.truncated).toBe(true)
89. })
90. })
92. describe('the request stays out of the heavy bucket', () => {
93. it('asks for action items and NEVER for a transcript or summary', async () => {
94. // include_summary / include_transcript move every call into the bucket that
95. // Fathom can squeeze to five calls a minute. The board needs neither.
96. const { urls, fetchImpl } = fake([{ body: { items: [], next_cursor: '' } }])
97. await resource(fetchImpl).listSince('2026-08-01T00:00:00Z')
98. expect(urls[0]).toContain('include_action_items=true')
99. expect(urls[0]).not.toContain('include_transcript')
100. expect(urls[0]).not.toContain('include_summary')
101. })
103. it('sends the window and an explicit page size', async () => {
104. const { urls, fetchImpl } = fake([{ body: { items: [], next_cursor: '' } }])
105. await resource(fetchImpl).listSince('2026-08-20T00:00:00Z')
106. expect(urls[0]).toContain('created_after=2026-08-20')
107. expect(urls[0]).toContain('limit=10')
108. })
109. })
111. describe('rate limiting waits as long as Fathom says', () => {
112. it('honours Retry-After and then succeeds', async () => {
113. const slept: number[] = []
114. const { fetchImpl } = fake([
115. { body: {}, status: 429, headers: { 'retry-after': '7' } },
116. { body: { items: [meeting(1)], next_cursor: '' } },
117. ])
118. const r = new MeetingsResource(
119. new FathomClient({ apiKey: 'k', fetchImpl, sleep: async (ms) => void slept.push(ms) }),
120. )
121. const w = await r.listSince('2026-08-01T00:00:00Z')
122. expect(slept).toEqual([7000])
123. expect(w.meetings).toHaveLength(1)
124. })
126. it('gives up after the retry budget rather than looping', async () => {
127. const { fetchImpl } = fake(
128. Array.from({ length: 9 }, () => ({ body: {}, status: 429, headers: { 'retry-after': '1' } })),
129. )
130. const r = new MeetingsResource(
131. new FathomClient({ apiKey: 'k', fetchImpl, sleep: async () => {}, maxRetries: 2 }),
132. )
133. await expect(r.listSince('2026-08-01T00:00:00Z')).rejects.toThrow(/rate limit/i)
134. })
135. })
137. describe('auth failures report causes without picking one', () => {
138. it('lists candidates and does not assert a single diagnosis', async () => {
139. const { fetchImpl } = fake([{ body: {}, status: 401 }])
140. const err = await resource(fetchImpl)
141. .listSince('2026-08-01T00:00:00Z')
142. .catch((e: unknown) => e as FathomError)
143. expect(err).toBeInstanceOf(FathomError)
144. const msg = (err as FathomError).message
145. // Several causes offered, and the one the Plinth handler got wrong is absent.
146. expect(msg).toMatch(/revoked/i)
147. expect(msg).toMatch(/deactivated/i)
148. expect(msg).not.toMatch(/most likely/i)
149. })
151. it('names whose key failed, since there is one key per person', async () => {
152. const { fetchImpl } = fake([{ body: {}, status: 403 }])
153. const err = await resource(fetchImpl)
154. .listSince('2026-08-01T00:00:00Z')
155. .catch((e: unknown) => e as FathomError)
156. expect((err as FathomError).message).toContain('Sam')
157. })
159. it('refuses to construct without a key, and says where keys come from', () => {
160. expect(() => new FathomClient({ apiKey: '' })).toThrow(/User Settings/)
161. expect(() => new FathomClient({ apiKey: '' })).toThrow(/per USER/)
162. })
163. })
165. describe('the client cannot write', () => {
166. it('issues only GET', async () => {
167. const seen: string[] = []
168. const fetchImpl = (async (_u: string, init?: RequestInit) => {
169. seen.push(init?.method ?? 'GET')
170. return new Response(JSON.stringify({ items: [], next_cursor: '' }), {
171. status: 200,
172. headers: { 'content-type': 'application/json' },
173. })
174. }) as unknown as typeof fetch
175. await resource(fetchImpl).listSince('2026-08-01T00:00:00Z')
176. expect(seen).toEqual(['GET'])
177. })
178. })