packages/pass/lib/import/guidelines.md

   1 # Importer Guidelines
   2
   3 Importers handle data from different password managers.
   4
   5 ## Directory Structure
   6
   7 ```
   8 importer/
   9 ├── helpers/
  10 │   └── ... (common utilities)
  11 ├── providers/
  12 │   ├── {provider-name-1}/
  13 │   │   ├── mocks/
  14 │   │   │   └── ... (mock files)
  15 │   │   ├── {provider-name-1}.reader.ts
  16 │   │   ├── {provider-name-1}.reader.spec.ts
  17 │   │   └── {provider-name-1}.types.ts
  18 │   ├── {provider-name-2}/
  19 │   │   ├── mocks/
  20 │   │   │   └── ... (mock files)
  21 │   │   ├── {provider-name-2}.reader.ts
  22 │   │   ├── {provider-name-2}.reader.spec.ts
  23 │   │   └── {provider-name-2}.types.ts
  24 │   └── ... (other providers)
  25 └── reader.ts
  26 └── types.ts
  27 ```
  28
  29 ## Conventions
  30
  31 -   Place all importers in `packages/pass/lib/import/providers`, with each provider in its own folder.
  32 -   Include mock files for each provider in their respective folders.
  33 -   When exporting utility functions, include the provider name (e.g., `extractLastPassCustomFields` instead of `extractCustomFields`).
  34 -   Define import file structures in `provider.types.ts` for each provider. Types should closely match actual data as no data-validation is implemented yet.
  35 -   Reader functions should map raw file content to an `ImportPayload` type.
  36
  37 ## Adding a New Import Provider
  38
  39 1. Define a new provider in the `ImportProvider` enum.
  40 2. Add provider configuration to `PROVIDER_INFO_MAP` constant.
  41 3. Add an appropriate icon in `ImportIcon.tsx`.
  42 4. Implement the provider-specific reader function.
  43 5. Add test cases with a custom import mock.
  44 6. Add a case in the main `fileReader` function.