Merge Realm JS and Realm Web TypeScript declarations

[kraenhansen]

Users are experiencing duplicate and diverging types across Realm JS and Realm Web.

Besides merging the type definitions, we also have to update the implementation and any tests relying on this:

• Rename the identity property on a User to id.
• Rename the token property on a User to accessToken.
• Expose the refresh token of a User as refreshToken.
• Change the allUsers from an instance method to a getter-property.
• Change the currentUser from an instance method to a getter-property.
• Make the logOut method on the User return a resolved promise (Promise<void>), instead of returning undefined synchronously.
• Rename API to Api for the auth related classes (here, here)
• Rename from UserAPIKeyProviderClient to ApiKeyProvider ApiKeyAuth (loosing User and Client & gaining Auth), in the internal C++ implementation.
• Rename from EmailPasswordProviderClient to EmailPasswordProvider EmailPasswordAuth (loosing Client & gaining Auth), in the internal C++ implementation.
• Rename methods of the ApiKeyProvider (loosing the "APIKey" suffix is fine, since its already called on an ApiKeyProvider which has no other methods that handle anything else than api-keys):
  • createAPIKey → create
  • fetchAPIKey → fetch
  • fetchAPIKeys → fetchAll
  • deleteAPIKey → delete
  • enableAPIKey → enable
  • disableAPIKey → disable
• Rename methods of the EmailPasswordProvider:
  • registerEmail → registerUser
  • resendConfirmation → resendConfirmationEmail
• Add the callResetPasswordFunction method to the EmailPasswordProvider.

NOTE: This should probably be implemented as a PR against the kh/v10-merged-types branch to keep the changes together when merged into v10.

[cmelchior]

Comparing this to the Java types. I saw the following differences:

• App.logOut() is on User, so User.logOut()
• We have io.realm.mongodb.auth.ApiKeyAuth. It was based on the conclusions from this discussion where the Provider suffix was deemed to vague: https://docs.google.com/document/d/1Vaciwbl093c252-2F5j3o6u33jLUoQ2A9_8hJ7hMzn0/edit#heading=h.a514whou3ddc. We kept the names from the original Stitch API so createApiKey, deleteApiKey, disableApiKey, enableApiKey, fetchApiKey and fetchAllApiKeys().
• EmailPassword is called io.realm.mongodb.auth.EmailPasswordAuth. We have registerUser and resendConfirmationEmail

Personal comment:

• How do you expect the call site to be for the auth provider? I can see loosing APIKey make sense if it is somehow present in the call chain, but not sure how you envision it, so JS would commonly be user.apikeyProvider.create() ?

[kraenhansen]

App.logOut() is on User, so User.logOut()

Yeah - it's already on the User, my suggestion is to add it on the App instance for convenience (since Realm Web already has that).
We could also leave it out (removing it from Realm Web) for simplicity and a unified API across SDKs?

We kept the names from the original Stitch API so createApiKey, deleteApiKey, disableApiKey, enableApiKey, fetchApiKey and fetchAllApiKeys().

Would you be open for a change to simplify this?
There are no methods on the ApiKeyAuth that does not operate on ApiKey's and that suffix is redundant from my perspective (just like Realm#create is not Realm#createObject)

We have registerUser and resendConfirmationEmail

Okay, I'll update Realm Web from resendConfirmation → resendConfirmationEmail instead.

How do you expect the call site to be for the auth provider?

await app.currentUser.auth.apiKeys.create( /*...*/ )

[kraenhansen]

We have io.realm.mongodb.auth.ApiKeyAuth. It was based on the conclusions from this discussion where the Provider suffix was deemed too vague.

The way I read the document (and remember the meeting) I thought Java was landing on EmailPasswordAuthProvider and ApiKeyAuthProvider, but I do see the conclusion mentioning "Auth-suffix".

I don't particularly like this name - Auth is equally vague in my opinion, but if that is what we collectively decided, let's go adopt that.

[cmelchior]

Yeah - it's already on the User, my suggestion is to add it on the App instance for convenience (since Realm Web already has that). We could also leave it out (removing it from Realm Web) for simplicity and a unified API across SDKs?

I would probably just keep it on User since it keeps the App "cleaner", but I will leave that up to you.

Would you be open for a change to simplify this?

I'm a bit torn on this because it massively depends on how you envision the usage.

// Java
ApiKeyAuth apiKeys = user.getApiKeyAuth()
apiKeys.create() // Very readable

ApiKeyAuth provider = user.getApiKeyAuth()
provider.create(); // Confusing

// Kotlin
user.apiKeyAuth.create() // Readable
val provider = user.apiKeyAuth
provider.create() // Confusing

I would probably tend to agree with you that your simplications make sense since the type is ApiKeyAuth.create(), and avoiding an API just because we don't think end developers can give good variable names is maybe a bit too pessimistic.

resendConfirmation was a bit too vaque as it wasn't clear exactly how it was sent. In that case resendConfirmationEmail() is much better IMO.