feat: add etag support to getNote method

  - Add etag field to RequestOptions type
  - Implement conditional requests with If-None-Match header
  - Add proper handling of 304 Not Modified responses
  - Extract etag from response headers
  - Include etag in response data when requested
  - Add comprehensive test coverage for etag functionality

Author: bagnier

nodejs/src/index.ts

@@ -3,7 +3,8 @@ import { CreateNoteOptions, GetMe, GetUserHistory, GetUserNotes, GetUserNote, Cr
 import * as HackMDErrors from './error'
 
 export type RequestOptions = {
-  unwrapData?: boolean
+  unwrapData?: boolean;
+  etag?: string | undefined;
 }
 
 const defaultOption: RequestOptions = {
@@ -146,7 +147,14 @@ export class API {
   }
 
   async getNote<Opt extends RequestOptions> (noteId: string, options = defaultOption as Opt): Promise<OptionReturnType<Opt, GetUserNote>> {
-    return this.unwrapData(this.axios.get<GetUserNote>(`notes/${noteId}`), options.unwrapData) as unknown as OptionReturnType<Opt, GetUserNote>
+    // Prepare request config with etag if provided in options
+    const config = options.etag ? {
+      headers: { 'If-None-Match': options.etag },
+      // Consider 304 responses as successful
+      validateStatus: (status: number) => (status >= 200 && status < 300) || status === 304
+    } : undefined
+    const request = this.axios.get<GetUserNote>(`notes/${noteId}`, config)
+    return this.unwrapData(request, options.unwrapData, true) as unknown as OptionReturnType<Opt, GetUserNote>
   }
 
   async createNote<Opt extends RequestOptions> (payload: CreateNoteOptions, options = defaultOption as Opt): Promise<OptionReturnType<Opt, CreateUserNote>> {
@@ -189,12 +197,17 @@ export class API {
     return this.axios.delete<AxiosResponse>(`teams/${teamPath}/notes/${noteId}`)
   }
 
-  private unwrapData<T> (reqP: Promise<AxiosResponse<T>>, unwrap = true) {
-    if (unwrap) {
-      return reqP.then(response => response.data)
-    } else {
+  private unwrapData<T> (reqP: Promise<AxiosResponse<T>>, unwrap = true, includeEtag = false) {
+    if (!unwrap) {
+      // For raw responses, etag is available via response.headers
       return reqP
     }
+    return reqP.then(response => {
+      const data = response.data
+      if (!includeEtag) return data
+      const etag = response.headers.etag || response.headers['ETag']
+      return { ...data, status: response.status, etag }
+    })
   }
 }
 

nodejs/tests/etag.spec.ts

@@ -0,0 +1,202 @@
+import { server } from './mock'
+import { API } from '../src'
+import { http, HttpResponse } from 'msw'
+
+let client: API
+
+beforeAll(() => {
+  client = new API(process.env.HACKMD_ACCESS_TOKEN!)
+  return server.listen()
+})
+
+afterEach(() => {
+  server.resetHandlers()
+})
+
+afterAll(() => {
+  server.close()
+  // Add explicit cleanup to ensure Jest exits properly
+  return new Promise(resolve => setTimeout(resolve, 100))
+})
+
+describe('Etag support', () => {
+  // Helper to reset server between tests
+  beforeEach(() => {
+    server.resetHandlers()
+  })
+  
+  test('response includes etag when server provides it (unwrapData: true)', async () => {
+    // Setup mock server to return an etag
+    const mockEtag = 'W/"123456789"'
+    
+    server.use(
+      http.get('https://api.hackmd.io/v1/notes/test-note-id', () => {
+        return HttpResponse.json(
+          { 
+            id: 'test-note-id',
+            title: 'Test Note'
+          },
+          {
+            headers: {
+              'ETag': mockEtag
+            }
+          }
+        )
+      })
+    )
+
+    // Make request with default unwrapData: true
+    const response = await client.getNote('test-note-id')
+
+    // Verify response has etag property
+    expect(response).toHaveProperty('etag', mockEtag)
+    
+    // Verify data properties still exist
+    expect(response).toHaveProperty('id', 'test-note-id')
+    expect(response).toHaveProperty('title', 'Test Note')
+  })
+  
+  test('response includes etag in headers when unwrapData is false', async () => {
+    // Setup mock server to return an etag
+    const mockEtag = 'W/"123456789"'
+    
+    server.use(
+      http.get('https://api.hackmd.io/v1/notes/test-note-id', () => {
+        return HttpResponse.json(
+          { 
+            id: 'test-note-id',
+            title: 'Test Note'
+          },
+          {
+            headers: {
+              'ETag': mockEtag
+            }
+          }
+        )
+      })
+    )
+
+    // Make request with unwrapData: false
+    const response = await client.getNote('test-note-id', { unwrapData: false })
+
+    // Verify response headers contain etag
+    expect(response.headers.etag).toBe(mockEtag)
+    
+    // Verify data is in response.data
+    expect(response.data).toHaveProperty('id', 'test-note-id')
+    expect(response.data).toHaveProperty('title', 'Test Note')
+  })
+
+  test('sends If-None-Match header when etag is provided', async () => {
+    // Setup mock server to check for If-None-Match header
+    let ifNoneMatchValue: string | null = null
+    const mockEtag = 'W/"123456789"'
+    
+    server.use(
+      http.get('https://api.hackmd.io/v1/notes/test-note-id', ({ request }) => {
+        // Store the If-None-Match header value for verification
+        ifNoneMatchValue = request.headers.get('If-None-Match')
+        
+        return HttpResponse.json(
+          { 
+            id: 'test-note-id',
+            title: 'Test Note'
+          },
+          {
+            headers: {
+              'ETag': mockEtag
+            }
+          }
+        )
+      })
+    )
+
+    // Make request with etag in options
+    await client.getNote('test-note-id', { etag: mockEtag })
+
+    // Verify the If-None-Match header was sent with correct value
+    expect(ifNoneMatchValue).toBe(mockEtag)
+  })
+
+  test('handles 304 Not Modified responses correctly (unwrapData: false)', async () => {
+    // Setup mock server to return 304 when etag matches
+    const mockEtag = 'W/"123456789"'
+    
+    server.use(
+      http.get('https://api.hackmd.io/v1/notes/test-note-id', ({ request }) => {
+        const ifNoneMatch = request.headers.get('If-None-Match')
+        
+        // Return 304 when etag matches
+        if (ifNoneMatch === mockEtag) {
+          return new HttpResponse(null, {
+            status: 304,
+            headers: {
+              'ETag': mockEtag
+            }
+          })
+        }
+        
+        return HttpResponse.json(
+          { 
+            id: 'test-note-id',
+            title: 'Test Note'
+          },
+          {
+            headers: {
+              'ETag': mockEtag
+            }
+          }
+        )
+      })
+    )
+
+    // Request with unwrapData: false to get full response including status
+    const response = await client.getNote('test-note-id', { etag: mockEtag, unwrapData: false })
+
+    // Verify we get a 304 status code
+    expect(response.status).toBe(304)
+    
+    // Verify etag is still available in headers
+    expect(response.headers.etag).toBe(mockEtag)
+  })
+  
+  test('handles 304 Not Modified responses correctly (unwrapData: true)', async () => {
+    // Setup mock server to return 304 when etag matches
+    const mockEtag = 'W/"123456789"'
+    
+    server.use(
+      http.get('https://api.hackmd.io/v1/notes/test-note-id', ({ request }) => {
+        const ifNoneMatch = request.headers.get('If-None-Match')
+        
+        // Return 304 when etag matches
+        if (ifNoneMatch === mockEtag) {
+          return new HttpResponse(null, {
+            status: 304,
+            headers: {
+              'ETag': mockEtag
+            }
+          })
+        }
+        
+        return HttpResponse.json(
+          { 
+            id: 'test-note-id',
+            title: 'Test Note'
+          },
+          {
+            headers: {
+              'ETag': mockEtag
+            }
+          }
+        )
+      })
+    )
+
+    // Request with default unwrapData: true
+    const response = await client.getNote('test-note-id', { etag: mockEtag })
+
+    // With unwrapData: true and a 304 response, we just get the etag
+    expect(response).toHaveProperty('etag', mockEtag)
+    expect(response).toHaveProperty('status', 304)
+  })
+})