feat: add createMigration and createWriteClient

[lihbr]

Implements: https://www.notion.so/prismic/RFC-Migration-API-Client-7365f2cce2ac43178955287dbad82e9c

Description

This Pull Request implements a new WriteClient allowing users to communicate with Prismic write APIs, namely the Migration API with ease, thanks to a helper Migration class working in concert with the new client.

Reworked structure

• Client's fetching logic has been abstracted in a new abstract BaseClient class, shaving off some ~300 lines from the Client class itself.
• createClient.ts file has been split into createClient.ts containing only the factory, and Client.ts containing the class itself.
• A similar pattern has been followed for the WriteClient and Migration classes.
• Overall, WriteClient extends Client which itself extends BaseClient, allowing for better tree shakability.

Reworked constructor

• Client's constructor has been updated to favor a repositoryName to be used as the first argument when creating a client. It now emits warnings when the repositoyName cannot be inferred.
• WriteClient's constructor will also warn when running in a browser-like environment to let users know that they credentials might be leaking.
• Related messages have been created to provide more directions when encountering the added warnings:
  • https://github.com/prismicio/prismic-client/blob/lh/migration-client/messages/prefer-repository-name.md
  • https://github.com/prismicio/prismic-client/blob/lh/migration-client/messages/avoid-write-client-in-browser.md

New types

• Asset API and Migration request and response types were added under src/types/api/asset and src/types/api/migration respectively.
• Migration API dedicated types were added under src/types/migration
• Some related types tests were added for complex types to ensure they keep working properly:
  • https://github.com/prismicio/prismic-client/blob/lh/migration-client/test/types/migration.types.ts
  • https://github.com/prismicio/prismic-client/blob/lh/migration-client/test/types/migration-document.types.ts
• Overall I kept the export quite minimal for now, and it's all pretty much open for discussion!

New internal helpers

• New internal helpers (lib) have been added to support the new WriteClient, namely patchMigrationDocumentData which contains all the crawling logic for correctly patching fields from a migration document with final field values and their updated IDs.

New exports

• WriteClient has two exposed methods, migrate() and getAssets(), the other ones are kept private. It is exported alongside its factory createWriteClient
• WriteClient's migrate() methods supports a reporter option reporting various events happening during the migration process. Thoses event types are exported as MigrateReporterEvents
• Migration is exported alongside its factory createMigration
• Migration document and field types are also exported.

Tests

• I faced some concurrency issues while writing tests due to the way Vitest now works, so I reworked createRepositoryName to ensure repository names are unique for each tests.
• Each Migration methods are fully tested:
  • createAsset()
  • createDocument()
  • getByUID()
  • getSingle()
• Each WriteClient public methods are fully tested:
  • migrate()
    • Creating assets
    • Creating documents
    • Updating documents' image, link, link to media, and simple field (had to split them because Vitest was having some performance issues when I had them all in one file due to the fake timers I'm using in testMigrationFieldPatching
    • Miscellaneous
  • getAssets()
• I preferred to also test some of the core WriteClient private methods, cheering my way through TypeScript:
  • createAsset()
  • createAssetTag()
  • fetchForeignAsset()
  • createDocument()
  • updateDocument()
  • I struggled testing the AbortController on most of them, I left a comment pointing to the suspected upstream issue related to that one, but I don't really get what's going wrong and where because other tests not going through p-limit are fine 🤔

Todos

• Prepare a PR on prismic-ts-codegen to also extend createMigration and createWriteClient factory types.
  • feat: support new @prismicio/client's WriteClient prismic-ts-codegen#65
• Documentation

Checklist

• If my changes require tests, I added them.
• If my changes affect backward compatibility, it has been discussed.
• If my changes require an update to the CONTRIBUTING.md guide, I updated it.

How to QA ¹

Use the following zip as a starting point: https://prismic-team.slack.com/files/U014KACFM6K/F07LY4GDLRE/migration-client-demo.zip

Following the README.md gives you a basic flow.

Footnotes

1. Please use these labels when submitting a review:
   ❓ #ask: Ask a question.
   💡 #idea: Suggest an idea.
   ⚠️ #issue: Strongly suggest a change.
   🎉 #nice: Share a compliment. ↩

[lihbr]

Thank you so much for this first batch of reviews! I addressed them all and replied where necessary. Let's have a quick sync chat tonight to close some topics if you're available 👌

[angeloashmore]

New comments for the tests! Addressing these comments are less important than the ones made on the implementation.

[angeloashmore]

⚠️ #issue: Should the test check for alt, credits, and notes? Otherwise, we don't know if the data was passed through.

[lihbr]

The issue I had here is that it's passed as a FormData so I cannot read it on the mocked API side unless we manage to upgrade MSW (out of scope here).

I'll add a TODO comment to rework this test when we update MSW.

[angeloashmore]

This is excellent. The latest version is simpler and might be less prone to bugs.

I left a few comments, none of which are blocking.

[lihbr]

Thank you so much! Addressed the last comments, should be good to go now 🎉

I'll hold off on merging until we're ready on the documentation end of things.