http.ts

packages/fathom-client/src/http.ts

1. /**
2. * Fathom HTTP layer.
3. *
4. * Read-only by construction: this client can issue exactly one verb (GET) to
5. * one path prefix. There is no write method here and adding one should be a
6. * deliberate, reviewed act: the Fathom API can create and delete webhooks,
7. * which would mean pointing someone's meeting content at a URL.
8. */
10. import { FATHOM_BASE_URL } from './constants.js'
12. export interface FathomOptions {
13. apiKey: string
14. /** Whose key this is. Used only in error messages, so a failure names a person. */
15. owner?: string
16. baseUrl?: string
17. maxRetries?: number
18. fetchImpl?: typeof fetch
19. sleep?: (ms: number) => Promise<void>
20. }
22. export class FathomError extends Error {
23. constructor(
24. message: string,
25. readonly status?: number,
26. readonly owner?: string,
27. ) {
28. super(owner ? `${message} [key: ${owner}]` : message)
29. this.name = 'FathomError'
30. }
31. }
33. export class FathomClient {
34. private readonly apiKey: string
35. private readonly owner: string | undefined
36. private readonly baseUrl: string
37. private readonly maxRetries: number
38. private readonly fetchImpl: typeof fetch
39. private readonly sleep: (ms: number) => Promise<void>
41. constructor(opts: FathomOptions) {
42. if (!opts.apiKey) {
43. throw new FathomError(
44. 'No Fathom API key. Keys are per USER, not per org. Generate one at ' +
45. 'User Settings > API Access and export it from the shell profile. ' +
46. 'This repo has no .env reader.',
47. undefined,
48. opts.owner,
49. )
50. }
51. this.apiKey = opts.apiKey
52. this.owner = opts.owner
53. this.baseUrl = opts.baseUrl ?? FATHOM_BASE_URL
54. this.maxRetries = opts.maxRetries ?? 3
55. this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis)
56. this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)))
57. }
59. /**
60. * One GET, with 429 handled by waiting exactly as long as Fathom says to.
61. *
62. * A 401 reports what happened and does not diagnose it (rule 1). Fathom's
63. * own FAQ lists several causes (wrong key, revoked key, deactivated user,
64. * malformed header) and the response cannot tell them apart, so the error
65. * lists all of them.
66. */
67. async get<T>(path: string, params: Record<string, string | number | boolean | undefined>): Promise<T> {
68. const url = new URL(`${this.baseUrl}${path}`)
69. for (const [k, v] of Object.entries(params)) {
70. if (v !== undefined) url.searchParams.set(k, String(v))
71. }
73. for (let attempt = 0; ; attempt++) {
74. const res = await this.fetchImpl(url.toString(), {
75. method: 'GET',
76. headers: { 'X-Api-Key': this.apiKey, accept: 'application/json' },
77. })
79. if (res.status === 429) {
80. // Retry-After is authoritative; the heavy bucket can drop to 5/60s under
81. // someone else's load, so guessing a backoff here would guess wrong.
82. if (attempt >= this.maxRetries) {
83. throw new FathomError('Fathom rate limit exceeded and retries exhausted.', 429, this.owner)
84. }
85. const after = Number(res.headers.get('retry-after') ?? '') || 60
86. await this.sleep(after * 1000)
87. continue
88. }
90. if (res.status === 401 || res.status === 403) {
91. throw new FathomError(
92. `Fathom refused the key (HTTP ${res.status}). Candidate causes, which the ` +
93. `response cannot distinguish: the key is wrong or was regenerated; the key ` +
94. `was revoked; the user it belongs to was deactivated or removed from the ` +
95. `team, which stops their key working; or the header is malformed. Check the ` +
96. `key in User Settings > API Access and that the user is still active.`,
97. res.status,
98. this.owner,
99. )
100. }
102. if (!res.ok) {
103. throw new FathomError(`Fathom returned HTTP ${res.status}.`, res.status, this.owner)
104. }
106. return (await res.json()) as T
107. }
108. }
109. }