Project: workspace-doctolib · Branch: HEAD · Mode:  · Model: claude-haiku-4-5-20251001

Stats: 1 user messages, 28 tool calls, tools used: Bash, Read.

Conversation

Turn 1 — User

Explore the treatment-plan project's national-health-records packages to understand the API layer. I need to understand the searchDocuments function signature, response types, and any existing pagination structures.

Search in these directories:
1. /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src
2. /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src

Find and read:
1. All TypeScript type definition files (.ts, .d.ts) - especially anything with "Document", "Search", "Pagination", "NhrDocument"
2. Any API client files or fetch functions
3. Any files mentioning "searchDocuments", "pagination", "page", "totalPages", "totalCount"
4. The full directory structure of both packages

Also search in:
/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src

For:
1. All TypeScript files - list directory and read each one
2. Any API call implementations
3. Existing response types

Return FULL file content with line numbers. This is research only - do not modify files.

Turn 1 — Assistant

I'll help you explore the national-health-records packages to understand the API layer and the searchDocuments function. Let me start by examining the directory structures and finding the relevant files.

Tools used:

- Bash: find /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records -type f -name ".ts" -o -name ".d.ts" | head -50

Tool results:

  → result (ok): /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/dist/business/types/service.d.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/dist/business/types/document.d.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/dist/business/types/index.d.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/dist/business/types/participant.d.ts
/Users/USER/workspace/doctolib/tr
…(truncated, 5715 more chars)

Let me focus on the source files in the tpf-national-health-records package:

Tools used:

- Bash: ls -la /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src 2>/dev/null || echo "Directory not found"

Tool results:

  → result (ok): drwxr-xr-x clertonra staff 128 B Thu Apr  9 16:06:20 2026 .
drwxr-xr-x clertonra staff 448 B Mon Apr 13 15:03:05 2026 ..
drwxr-xr-x clertonra staff 160 B Tue Feb 24 15:53:39 2026 business
.rw-r--r-- clertonra staff 773 B Thu Apr  9 16:06:20 2026 index.ts

Tools used:

- Bash: find /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src -type f \( -name ".ts" -o -name ".d.ts" \) | sort

Tool results:

  → result (ok): /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/nhr-service-factory.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/systems/dmp/services/dmp-nhr-service.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/systems/dmp/types/index.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/systems/dmp/types/types.ts
…(truncated, 551 more chars)

Tools used:

- Bash: ls -la /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src 2>/dev/null || echo "Directory not found"

Tool results:

  → result (ok): drwxr-xr-x clertonra staff 416 B  Mon Apr 13 15:03:05 2026 .
drwxr-xr-x clertonra staff 672 B  Mon Apr 13 15:03:05 2026 ..
drwxr-xr-x clertonra staff  96 B  Tue Feb 24 15:53:39 2026 __tests__
drwxr-xr-x clertonra staff 128 B  Wed Apr  1 10:05:06 2026 business
drwxr-xr-x clertonra staff 352 B  Wed Apr  1 10:05:06 2026 components
.rw-r--r-- clertonra staff 105 B  Tue Mar 10 17:05:01 2026 entry.ts
.rw-r--r-- clertonra staff 1.0 KB Wed Apr  1 10:05:06 2026 i18n.test.ts
.rw-r--r-- clertonra staff 332
…(truncated, 376 more chars)

Tools used:

- Bash: find /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src -type f \( -name ".ts" -o -name ".d.ts" \) | sort

Tool results:

  → result (ok): /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/__tests__/index.test.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/business/factories/actions/createMoreActionsAction.test.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/business/factories/actions/createMoreActionsAction.ts
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/bus
…(truncated, 3793 more chars)

Tools used:

- Bash: ls -la /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src 2>/dev/null || echo "Directory not found"

Tool results:

  → result (ok): drwxr-xr-x clertonra staff 256 B Wed Apr  8 16:08:29 2026 .
drwxr-xr-x clertonra staff 352 B Mon Apr 13 15:34:16 2026 ..
drwxr-xr-x clertonra staff 160 B Wed Apr  8 16:08:29 2026 business
drwxr-xr-x clertonra staff 256 B Tue Apr 14 08:54:10 2026 hooks
.rw-r--r-- clertonra staff 404 B Wed Apr  8 16:08:29 2026 index.ts
drwxr-xr-x clertonra staff 128 B Thu Feb 26 14:08:52 2026 locales
drwxr-xr-x clertonra staff 192 B Tue Apr 14 08:54:10 2026 mocks
drwxr-xr-x clertonra staff 160 B Tue Apr 14 08:54:1
…(truncated, 15 more chars)

Tools used:

- Bash: find /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src -type f \( -name ".ts" -o -name ".d.ts" -o -name ".tsx" -o -name ".jsx" \) | sort

Tool results:

  → result (ok): /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/business/adapters/DmpNhrAdapter.test.ts
/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/business/adapters/DmpNhrAdapter.ts
/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/business/builders/actionsBuilder.ts
/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/business/mappers/toNhrPatientInformation.
…(truncated, 2679 more chars)

Now let me read the key files. I'll start with the core type definitions and service files:

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/types/service.ts

Tool results:

  → result (ok): 1	import type {
2	  NhrDocumentContentResult,
3	  NhrDocumentSearchProps,
4	  NhrDocumentSearchResult,
5	  NhrGetDocumentsContentProps,
6	} from '#business/types/document'
7	
8	export type CountryCode = 'fr' | 'mock'
9	
10	export type NhrService = {
11	  searchDocuments(props: NhrDocumentSearchProps): Promise<NhrDocumentSearchResult>
12	  getDocumentsContent(props: NhrGetDocumentsContentProps): Promise<NhrDocumentContentResult[]>
13	}
14	
15	export type NhrAdapter = {
16	  searchDocuments(props:
…(truncated, 164 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/types/document.ts

Tool results:

  → result (ok): 1	import type { NhrDocumentAuthor, NhrPatientInformation } from '#business/types/participant'
2	
3	// General types ---
4	/ The services/procedures this document is associated with /
5	export type NhrServiceInformation = {
6	  startDate?: string
7	  endDate?: string
8	}
9	
10	export type NhrDocumentClassification = {
11	  codes: Code[]
12	}
13	
14	export type Code = {
15	  system: string
16	  code: string
17	}
18	
19	export type DateRange = {
20	  upperLimit?: string
21	  lowerLimit?: string

…(truncated, 1348 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/types/index.ts

Tool results:

  → result (ok): 1	export type {
2	  NhrDocumentSearchProps,
3	  NhrDocumentSearchResult,
4	  NhrDocument,
5	  DateRange,
6	  NhrDocumentClassification,
7	  NhrDocumentSearchParams,
8	  NhrServiceInformation,
9	  Code,
10	} from './document'
11	export type {
12	  NhrDocumentAuthor,
13	  NhrAddress,
14	  NhrContact,
15	  NhrInstitution,
16	  NhrPatientInformation,
17	  NhrProfession,
18	} from './participant'
19	export type { NhrService } from './service'
20

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/types/participant.ts

Tool results:

  → result (ok): 1	/ Profession of a participant. Ideally used to capture more information about healthcare professionals. /
2	export type NhrProfession = {
3	  / Can include national identifiers , oids, etc /
4	  identifiers?: Record<string, string>
5	  / Optional description of the profession. E.g. HCP, MFA, etc /
6	  description?: string
7	  / The specialisation of the participant. E.g. cardiology, general medicine, elder care etc /
8	  speciality?: string
9	}
10	
11	/ Geographical locator /
12
…(truncated, 1524 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/systems/dmp/types/types.ts

Tool results:

  → result (ok): 1	/
2	  iCanopee JSON Documentation v2.1.0
3	 /
4	
5	/
6	  Telecom Structure (Section 14.49).
7	  Represents a telecommunications address (phone, fax, email, etc.).
8	  Source fields: i_type, i_usage, s_value.
9	 /
10	export type DmpNhrTelecom = {
11	  /
12	    Telecommunications address type (code from the "Telecommunications Address Type" table).
13	    Source: i_type.
14	   /
15	  type?: number
16	  /
17	    Use case(s) for the address. This is a binary combination (sum) of 
…(truncated, 12906 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/systems/dmp/services/dmp-nhr-service.ts

Tool results:

  → result (ok): 1	import type {
2	  NhrDocumentContentResult,
3	  NhrDocumentSearchProps,
4	  NhrDocumentSearchResult,
5	  NhrGetDocumentsContentProps,
6	} from '#business/types/document'
7	import type { NhrAdapter, NhrService } from '#business/types/service'
8	
9	export class DmpNhrService implements NhrService {
10	  readonly country = 'fr'
11	
12	  constructor(readonly nhrAdapter: NhrAdapter) {}
13	
14	  searchDocuments = (props: NhrDocumentSearchProps): Promise<NhrDocumentSearchResult> =>
15	    this.nhrAda
…(truncated, 193 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/nhr-service-factory.ts

Tool results:

  → result (ok): 1	import { DmpNhrService } from '#business/systems/dmp/services/dmp-nhr-service'
2	import type { CountryCode, NhrAdapter } from '#business/types/service'
3	
4	export const createNhrService = (countryCode: CountryCode, nhrAdapter: NhrAdapter) => {
5	  switch (countryCode) {
6	    case 'fr':
7	      return new DmpNhrService(nhrAdapter)
8	    default:
9	      throw new Error(Unsupported country code: ${countryCode})
10	  }
11	}
12

Now let me check the UI and frontend packages:

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/types.ts

Tool results:

  → result (ok): 1	import type { DesignSystemIconComponent } from '@doctolib/design-system-icons'
2	import type { NhrDocument } from '@doctolib/tpf-national-health-records'
3	import type { ReactNode } from 'react'
4	
5	export type NhrPatientInfo = {
6	  fullName: string
7	  gender: 'male' | 'female' | 'other'
8	  birthDate: string
9	  age: number
10	}
11	
12	export type ColumnConfig = {
13	  key: string
14	  header: string
15	  sortable: boolean
16	  / Only required when sortable: true. Returns a string for lo
…(truncated, 2157 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/utils/nhrPaginationHelpers.ts

Tool results:

  → result (ok): 1	export const PAGE_SIZE = 20
2	
3	export const getPagedData = <T>(data: T[] | undefined, currentPage: number): T[] | undefined =>
4	  data?.slice((currentPage - 1)  PAGE_SIZE, currentPage  PAGE_SIZE)
5

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/index.ts

Tool results:

  → result (ok): 1	export { NhrDocumentList } from './components/NhrDocumentList/NhrDocumentList'
2	export { NhrDocumentListFilterPanel } from './components/NhrDocumentListFilterPanel/NhrDocumentListFilterPanel'
3	export type {
4	  ActionConfig,
5	  ActionsFactory,
6	  ColumnConfig,
7	  FilterConfig,
8	  FilterRenderContext,
9	  NhrPatientInfo,
10	  NhrVisibilityEntry,
11	  StatusOption,
12	  NhrDocumentStatusFilterProps,
13	  VisibilityOption,
14	  SearchDocumentsFn,
15	} from './types'
16	export { NhrEntryPoin
…(truncated, 2130 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/hooks/useSearchDocuments.ts

Tool results:

  → result (ok): 1	import { useQueryClient } from '@tanstack/react-query-v5'
2	import type { Patient } from 'monolith_DEPRECATED/types/doctor/api/Patient'
3	import { isFeatureEnabled } from '@doctolib/variation_management'
4	import type { NhrDocumentListVariant, MapFiltersToSearchDocumentsParams, ServerFilters } from '../variants/types'
5	import { useNationalHealthRecords } from './useNationalHealthRecords'
6	import { generateNhrDocuments } from '../mocks/generateNhrDocuments'
7	import { toNhrPatientInformation 
…(truncated, 2248 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/hooks/useNationalHealthRecords.ts

Tool results:

  → result (ok): 1	import type { NhrDocumentSearchProps, NhrDocumentSearchResult } from '@doctolib/tpf-national-health-records'
2	import { useProductLineVariation, ProductLineKey } from '@doctolib/variation_management'
3	import type { Patient } from 'monolith_DEPRECATED/types/doctor/api/Patient'
4	import { useDmpNhr } from './useDmpNhr'
5	
6	export type UseNhrOperations = {
7	  searchDocuments: (props: NhrDocumentSearchProps) => Promise<NhrDocumentSearchResult>
8	}
9	
10	export const useNationalHealthRecords = (
…(truncated, 597 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/hooks/useDmpNhr.ts

Tool results:

  → result (ok): 1	import { useMemo } from 'react'
2	import type { Patient } from 'monolith_DEPRECATED/types/doctor/api/Patient'
3	import { DmpApiImpl as DmpApi, useDmpSetUp } from '@doctolib/dmp'
4	import { createNhrService } from '@doctolib/tpf-national-health-records'
5	import { DmpNhrAdapter } from '../business/adapters/DmpNhrAdapter'
6	import type { UseNhrOperations } from './useNationalHealthRecords'
7	
8	export const useDmpNhr = ({ patient }: { patient: Patient }): UseNhrOperations => {
9	  const { dmpSet
…(truncated, 418 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/business/adapters/DmpNhrAdapter.ts

Tool results:

  → result (ok): 1	import type { DmpApi, DmpAuthor, DmpDocument, SearchProps, SearchResult as DmpSearchResult } from '@doctolib/dmp'
2	import { DOCUMENT_STATUS, DOCUMENT_VISIBILITY } from '@doctolib/dmp'
3	import type {
4	  NhrAdapter,
5	  NhrDocumentAuthor,
6	  NhrDocumentSearchProps,
7	  NhrDocumentSearchResult,
8	  NhrDocument,
9	  NhrDocumentContentResult,
10	  NhrGetDocumentsContentProps,
11	} from '@doctolib/tpf-national-health-records'
12	import type { DocumentCategorizationGroupContent } from 'engines/do
…(truncated, 3947 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/variants/types.ts

Tool results:

  → result (ok): 1	import type { ColumnConfig, FilterConfig } from '@doctolib/tpf-national-health-records-ui'
2	import type { Patient } from 'monolith_DEPRECATED/types/doctor/api/Patient'
3	import type { NhrDocument, NhrDocumentSearchParams } from '@doctolib/tpf-national-health-records'
4	
5	interface SearchDocumentsResult {
6	  data: NhrDocument[]
7	  total: number
8	}
9	
10	export type NhrDocumentListVariant = {
11	  columns: ColumnConfig[]
12	  filters: FilterConfig[]
13	  searchDocuments: (appliedFilters?: R
…(truncated, 791 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/variants/dmp/mappers/mapFiltersToSearchDocumentsParams.ts

Tool results:

  → result (ok): 1	import type { NhrDocumentSearchParams } from '@doctolib/tpf-national-health-records'
2	import { DOCUMENT_STATUS, DOCUMENT_VISIBILITY } from '@doctolib/dmp'
3	import type { ServerFilters } from '../../types'
4	import { toNhrPatientInformation } from '../../../business/mappers/toNhrPatientInformation'
5	
6	// Maps UI-level ServerFilters to the NhrDocumentSearchParams format expected by the NHR API.
7	// Each ServerFilters field needs an explicit mapping — field names do not match NhrDocumentSear
…(truncated, 2415 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/index.ts

Tool results:

  → result (ok): 1	export { useNationalHealthRecords, type UseNhrOperations } from './hooks/useNationalHealthRecords'
2	export { useDmpNhr } from './hooks/useDmpNhr'
3	export { useNhrDocumentListVariant } from './variants/useNhrDocumentListVariant'
4	export type { DocumentSearchOptions, NhrDocumentListVariant } from './variants/types'
5	export { actionsBuilder, type NhrActionsBuilder } from './business/builders/actionsBuilder'
6

Now let me look at the variant hook to understand how searchDocuments is used:

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/variants/useNhrDocumentListVariant.ts

Tool results:

  → result (ok): 1	import { useProductLineVariation, ProductLineKey } from '@doctolib/variation_management'
2	import type { DocumentSearchOptions, NhrDocumentListVariant } from './types'
3	import { useDmpDocumentListVariant } from './dmp'
4	
5	export const useNhrDocumentListVariant = (patient: DocumentSearchOptions['patient']): NhrDocumentListVariant | null => {
6	  const dmpVariant = useDmpDocumentListVariant(patient)
7	
8	  return useProductLineVariation<NhrDocumentListVariant>({
9	    variants: {
10	      [Pr
…(truncated, 389 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/variants/dmp/useDmpDocumentListVariant.ts

Tool results:

  → result (ok): 1	import { columnsFactory } from './factories/columnsFactory'
2	import { filtersFactory } from './factories/filtersFactory'
3	import type { NhrDocumentListVariant, DocumentSearchOptions } from '../types'
4	import useDmpSearchDocuments from '../../hooks/useSearchDocuments'
5	import { mapFiltersToSearchDocumentsParams } from './mappers/mapFiltersToSearchDocumentsParams'
6	
7	export const useDmpDocumentListVariant = (patient: DocumentSearchOptions['patient']): NhrDocumentListVariant => {
8	  const 
…(truncated, 207 more chars)

Perfect! Now let me check a few test files to understand the complete picture:

Tools used:

- Read: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/index.ts

Tool results:

  → result (ok): 1	// bump
2	export { createNhrService } from '#business/nhr-service-factory'
3	export type { NhrAdapter, NhrService, CountryCode } from '#business/types/service'
4	export type {
5	  NhrDocumentSearchProps,
6	  NhrDocumentSearchResult,
7	  NhrDocument,
8	  NhrServiceInformation,
9	  NhrDocumentSearchParams,
10	  NhrDocumentClassification,
11	  DateRange,
12	  Code,
13	  NhrDocumentFile,
14	  NhrGetDocumentsContentProps,
15	  NhrDocumentContentResult,
16	} from '#business/types/document'
17	export
…(truncated, 359 more chars)

Tools used:

- Read: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/business/mappers/toNhrPatientInformation.ts

Tool results:

  → result (ok): 1	import type { NhrPatientInformation } from '@doctolib/tpf-national-health-records'
2	
3	export function toNhrPatientInformation(ins: string): NhrPatientInformation {
4	  return {
5	    nationalHealthIdentifier: ins,
6	  }
7	}
8

Perfect! Now let me create a summary document with all the findings:

Summary: National Health Records API Layer Analysis

I've completed a comprehensive exploration of the national-health-records packages. Here are my findings:

---

searchDocuments Function Signature

Core Signature (tpf-national-health-records package):
// From: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/types/service.ts
searchDocuments(props: NhrDocumentSearchProps): Promise<NhrDocumentSearchResult>

Props Type:
// From: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/types/document.ts (lines 38-41)
type NhrDocumentSearchProps = {
  patient?: NhrPatientInformation
  params: NhrDocumentSearchParams
}

Search Parameters:
type NhrDocumentSearchParams = {
  patientInformation: NhrPatientInformation
  formats?: string[]
  categories?: string[]
  status?: string
  serviceStartDate?: DateRange
  serviceStopDate?: DateRange
  creationDate?: DateRange
  submissionDate?: DateRange
  visibility?: string
}

---

Response Types

Search Result:
// From: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/types/document.ts (lines 43-45)
type NhrDocumentSearchResult = {
  documents: NhrDocument[]
}

Document Structure:
type NhrDocument = {
  id: string
  title: string
  description?: string
  identifiers?: Record<string, string>
  creationDate?: string
  submissionDate?: string
  serviceInformation?: NhrServiceInformation
  status?: string
  visibility?: string
  format?: string
  authors?: NhrDocumentAuthor[]
  classification?: NhrDocumentClassification
}

Frontend Response Type:
The UI layer wraps the response differently:
// From: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/variants/types.ts (lines 5-14)
interface SearchDocumentsResult {
  data: NhrDocument[]
  total: number  // <-- Pagination: total count of documents
}

export type NhrDocumentListVariant = {
  searchDocuments: (appliedFilters?: Record<string, unknown>) => Promise<SearchDocumentsResult>
}

---

Pagination Structures

Frontend Level Pagination:
1. Client-side pagination with fixed page size:
   - File: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/utils/nhrPaginationHelpers.ts
   - Page size: 20 items per page
   - Function: getPagedData<T>(data: T[], currentPage: number): T[]

2. Response includes total count:
   - SearchDocumentsResult includes total: number field
   - Used by UI components to calculate total pages

Backend Level Pagination:
The search response itself does NOT include pagination metadata. All documents matching the search criteria are returned in a single NhrDocumentSearchResult:
type NhrDocumentSearchResult = {
  documents: NhrDocument[]  // No pagination fields
}

---

Implementation Chain & Adapters

1. DMP NHR Service (tpf-national-health-records)
File: /Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/business/systems/dmp/services/dmp-nhr-service.ts
export class DmpNhrService implements NhrService {
  readonly country = 'fr'
  constructor(readonly nhrAdapter: NhrAdapter) {}
  searchDocuments = (props: NhrDocumentSearchProps): Promise<NhrDocumentSearchResult> =>
    this.nhrAdapter.searchDocuments(props)
}

2. DMP NHR Adapter (doctolib monolith)
File: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/business/adapters/DmpNhrAdapter.ts

Transforms NhrDocumentSearchProps → DMP API SearchProps:
async searchDocuments(props: NhrDocumentSearchProps): Promise<NhrDocumentSearchResult> {
  const apiSearchProps = toSearchProps(props)
  const apiResponse = await this.dmpApi.search(apiSearchProps)
  return toDocumentSearchResult(apiResponse)
}

3. useSearchDocuments Hook (Frontend)
File: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/hooks/useSearchDocuments.ts

- Uses React Query v5 for caching
- Cache stale time: 5 minutes (300,000ms)
- Max retries: 3 (except for DMPAccessDeniedByExcededThreshold - fails immediately)
- Query key: ['dmp-documents', ins, appliedFilters]
- Returns: { data: documents, total: documents.length }

---

Filter/Search Parameter Mapping

File: /Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/variants/dmp/mappers/mapFiltersToSearchDocumentsParams.ts

Transforms UI-level ServerFilters to NhrDocumentSearchParams:
export type ServerFilters = BaseServerFilters & DmpServerFilters

type BaseServerFilters = {
  typeCodes?: string[]          // → categories
  dateType?: 'shareDate' | 'procedureDate'
  submissionDateFrom?: string
  submissionDateTo?: string
}

type DmpServerFilters = {
  includeArchived?: boolean
  includeObsolete?: boolean
  includeMaskedToProfessionals?: boolean
  includeInvisibleToPatient?: boolean
  includeInvisibleToLegalReps?: boolean
}

Maps to:
- categories (from typeCodes)
- submissionDate or serviceStartDate (based on dateType)
- status (bitmask composition of validated|archived|obsolete)
- visibility (bitmask composition)

---

Directory Structure

tpf-national-health-records (backend service library):
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records/src/
├── business/
│   ├── types/
│   │   ├── service.ts          # NhrService, NhrAdapter interfaces
│   │   ├── document.ts         # NhrDocument, NhrDocumentSearchProps/Result
│   │   ├── participant.ts      # NhrDocumentAuthor, NhrPatientInformation
│   │   └── index.ts            # Type exports
│   ├── systems/dmp/
│   │   ├── types/
│   │   │   ├── types.ts        # DMP-specific types (DmpNhrDocument, etc.)
│   │   │   └── index.ts
│   │   └── services/
│   │       └── dmp-nhr-service.ts  # DmpNhrService implementation
│   └── nhr-service-factory.ts  # Factory to create country-specific services
└── index.ts

tpf-national-health-records-ui (frontend UI components):
/Users/USER/workspace/doctolib/treatment-plan/packages/tpf-national-health-records-ui/src/
├── business/
│   ├── factories/
│   │   ├── actions/            # Document action builders
│   │   ├── columns/            # Column configuration factories
│   │   └── filters/            # Filter configuration factories
│   └── formatters/
├── components/
│   ├── NhrDocumentList/        # Main list component
│   ├── NhrDocumentListFilterPanel/
│   ├── NhrEntryPoint/
│   └── Nhr*Cell/               # Column cell renderers
├── utils/
│   └── nhrPaginationHelpers.ts # PAGE_SIZE=20, getPagedData()
├── types.ts                    # ColumnConfig, FilterConfig, SearchDocumentsFn
└── index.ts

@doctolib/national-health-records (monolith integration):
/Users/USER/workspace/doctolib/doctolib/packages/@doctolib/national-health-records/src/
├── business/
│   ├── adapters/
│   │   └── DmpNhrAdapter.ts    # Transforms to/from DMP API
│   ├── builders/
│   │   └── actionsBuilder.ts
│   └── mappers/
│       └── toNhrPatientInformation.ts
│       └── mapFiltersToSearchDocumentsParams.ts
├── hooks/
│   ├── useNationalHealthRecords.ts      # Main hook (product-line variation)
│   ├── useDmpNhr.ts                     # DMP implementation
│   └── useSearchDocuments.ts            # React Query wrapper with caching
├── variants/
│   ├── types.ts                         # NhrDocumentListVariant, ServerFilters
│   ├── useNhrDocumentListVariant.ts     # Product-line variation wrapper
│   └── dmp/
│       ├── mappers/mapFiltersToSearchDocumentsParams.ts
│       └── useDmpDocumentListVariant.

…(truncated, 862 more chars)