From 079bbc1458bd417c903e4b580efd5b6a3eb4a579 Mon Sep 17 00:00:00 2001 From: krollins-mdb Date: Fri, 5 Jul 2024 14:00:05 -0500 Subject: [PATCH] - Generate snippets - Update API doc links - Update includes --- .../authentication/api-keys/LoginManager.tsx | 10 +++-- .../authentication/api-keys/steps/Step1.tsx | 36 ++++++++-------- .../authentication/api-keys/steps/Step2.tsx | 11 +++++ ...LoginManager.snippet.api-key-login.tsx.rst | 9 ++++ .../Step1.snippet.create-user-api-key.tsx.rst | 3 ++ ...Step1.snippet.user-api-key-imports.tsx.rst | 3 ++ .../v12/Step1.snippet.user-api-key.tsx.rst | 11 +++++ .../v12/Step2.snippet.api-key-delete.tsx.rst | 3 ++ .../v12/Step2.snippet.api-key-disable.tsx.rst | 3 ++ .../v12/Step2.snippet.api-key-enable.tsx.rst | 3 ++ ...Step2.snippet.look-up-user-api-key.tsx.rst | 10 +++++ .../manage-users/authenticate-users.txt | 13 ++++-- .../manage-users/manage-user-api-keys.txt | 42 ++++++++++--------- 13 files changed, 112 insertions(+), 45 deletions(-) create mode 100644 source/examples/generated/react-native/v12/LoginManager.snippet.api-key-login.tsx.rst create mode 100644 source/examples/generated/react-native/v12/Step1.snippet.create-user-api-key.tsx.rst create mode 100644 source/examples/generated/react-native/v12/Step1.snippet.user-api-key-imports.tsx.rst create mode 100644 source/examples/generated/react-native/v12/Step1.snippet.user-api-key.tsx.rst create mode 100644 source/examples/generated/react-native/v12/Step2.snippet.api-key-delete.tsx.rst create mode 100644 source/examples/generated/react-native/v12/Step2.snippet.api-key-disable.tsx.rst create mode 100644 source/examples/generated/react-native/v12/Step2.snippet.api-key-enable.tsx.rst create mode 100644 source/examples/generated/react-native/v12/Step2.snippet.look-up-user-api-key.tsx.rst diff --git a/examples/react-native/v12/TestApp/src/components/authentication/api-keys/LoginManager.tsx b/examples/react-native/v12/TestApp/src/components/authentication/api-keys/LoginManager.tsx index 8f9911ca69..09b4c7f283 100644 --- a/examples/react-native/v12/TestApp/src/components/authentication/api-keys/LoginManager.tsx +++ b/examples/react-native/v12/TestApp/src/components/authentication/api-keys/LoginManager.tsx @@ -2,7 +2,7 @@ import React, {useState} from 'react'; import {View, Text, TextInput, StyleSheet, Pressable} from 'react-native'; import {useAuth, useEmailPasswordAuth} from '@realm/react'; -import {LoginManagerProps, RegisterButtonProps} from '../../types'; +import {ApiKey, LoginManagerProps, RegisterButtonProps} from '../../types'; export const LoginManager = ({apiKey}: LoginManagerProps) => { const [email, setEmail] = useState(''); @@ -15,13 +15,15 @@ export const LoginManager = ({apiKey}: LoginManagerProps) => { logIn({email, password}); }; - const loginApiKeyUser = async () => { + // :snippet-start: api-key-login + const loginApiKeyUser = async (apiKey: ApiKey) => { try { logInWithApiKey(apiKey!.key); } catch (error) { console.log(error); } }; + // :snippet-end: return ( @@ -35,7 +37,9 @@ export const LoginManager = ({apiKey}: LoginManagerProps) => { + onPress={() => { + loginApiKeyUser(apiKey); + }}> Log in with API key diff --git a/examples/react-native/v12/TestApp/src/components/authentication/api-keys/steps/Step1.tsx b/examples/react-native/v12/TestApp/src/components/authentication/api-keys/steps/Step1.tsx index 59fd272976..fd0b7188bc 100644 --- a/examples/react-native/v12/TestApp/src/components/authentication/api-keys/steps/Step1.tsx +++ b/examples/react-native/v12/TestApp/src/components/authentication/api-keys/steps/Step1.tsx @@ -1,14 +1,29 @@ +// :snippet-start: user-api-key-imports +import {useUser} from '@realm/react'; +// :snippet-end: + import React, {useState, useEffect} from 'react'; import {View, Text, TextInput, StyleSheet, Pressable} from 'react-native'; -import {useUser} from '@realm/react'; import {StepProps} from '../../../types'; export const Step1 = ({currentStep, apiKey, setApiKey}: StepProps) => { + const [apiKeyName, setApiKeyName] = useState(''); + + // :snippet-start: user-api-key const user = useUser(); - const [apiKeyName, setApiKeyName] = useState(''); - const [createKeyError, setCreateKeyError] = useState(false); + const createUserApiKey = async () => { + // :snippet-start: create-user-api-key + const {_id, key, name, disabled} = await user?.apiKeys.create(apiKeyName); + // :snippet-end: + + // ...Do something with API key like save it + // or share it with external service that authenticates + // on user's behalf. + setApiKey({_id, key, name, disabled}); // :remove: + }; + // :snippet-end: // This useEffect runs once every time the component is rendered. Deletes all // existing api keys for the current user. @@ -30,25 +45,10 @@ export const Step1 = ({currentStep, apiKey, setApiKey}: StepProps) => { setApiKey(undefined); }, []); - const createUserApiKey = async () => { - try { - const {_id, key, name, disabled} = await user?.apiKeys.create(apiKeyName); - setApiKey({_id, key, name, disabled}); - - if (createKeyError) { - setCreateKeyError(false); - } - } catch (error) { - setCreateKeyError(true); - } - }; - return ( Step {currentStep + 1}: Create a user API Key - {createKeyError && Couldn't create the API key.} - {apiKey ? ( diff --git a/examples/react-native/v12/TestApp/src/components/authentication/api-keys/steps/Step2.tsx b/examples/react-native/v12/TestApp/src/components/authentication/api-keys/steps/Step2.tsx index 6295104a2e..38edcd8347 100644 --- a/examples/react-native/v12/TestApp/src/components/authentication/api-keys/steps/Step2.tsx +++ b/examples/react-native/v12/TestApp/src/components/authentication/api-keys/steps/Step2.tsx @@ -12,7 +12,9 @@ export const Step2 = ({currentStep, apiKey, setApiKey}: StepProps) => { const [cloudKeyDeleted, setCloudKeyDeleted] = useState(false); const deleteUserApiKey = async () => { + // :snippet-start: api-key-delete await user!.apiKeys.delete(cloudApiKey!._id); + // :snippet-end: setApiKey(undefined); setCloudApiKey(undefined); @@ -20,22 +22,31 @@ export const Step2 = ({currentStep, apiKey, setApiKey}: StepProps) => { }; const disableUserApiKey = async () => { + // :snippet-start: api-key-disable await user!.apiKeys.disable(cloudApiKey!._id); + // :snippet-end: await getUserApiKey(); }; const enableUserApiKey = async () => { + // :snippet-start: api-key-enable await user!.apiKeys.enable(cloudApiKey!._id); + // :snippet-end: await getUserApiKey(); }; + // :snippet-start: look-up-user-api-key const getUserApiKey = async () => { + // List all of a user's keys + const keys = await user.apiKeys.fetchAll(); + // Get a specific key by its ID const key = await user!.apiKeys.fetch(apiKey!._id); setCloudApiKey(key); }; + // :snippet-end: if (cloudKeyDeleted) { return API key successfully deleted!; diff --git a/source/examples/generated/react-native/v12/LoginManager.snippet.api-key-login.tsx.rst b/source/examples/generated/react-native/v12/LoginManager.snippet.api-key-login.tsx.rst new file mode 100644 index 0000000000..7c6c988a09 --- /dev/null +++ b/source/examples/generated/react-native/v12/LoginManager.snippet.api-key-login.tsx.rst @@ -0,0 +1,9 @@ +.. code-block:: typescript + + const loginApiKeyUser = async (apiKey: ApiKey) => { + try { + logInWithApiKey(apiKey!.key); + } catch (error) { + console.log(error); + } + }; diff --git a/source/examples/generated/react-native/v12/Step1.snippet.create-user-api-key.tsx.rst b/source/examples/generated/react-native/v12/Step1.snippet.create-user-api-key.tsx.rst new file mode 100644 index 0000000000..911db36c18 --- /dev/null +++ b/source/examples/generated/react-native/v12/Step1.snippet.create-user-api-key.tsx.rst @@ -0,0 +1,3 @@ +.. code-block:: typescript + + const {_id, key, name, disabled} = await user?.apiKeys.create(apiKeyName); diff --git a/source/examples/generated/react-native/v12/Step1.snippet.user-api-key-imports.tsx.rst b/source/examples/generated/react-native/v12/Step1.snippet.user-api-key-imports.tsx.rst new file mode 100644 index 0000000000..ee4a949a7f --- /dev/null +++ b/source/examples/generated/react-native/v12/Step1.snippet.user-api-key-imports.tsx.rst @@ -0,0 +1,3 @@ +.. code-block:: typescript + + import {useUser} from '@realm/react'; diff --git a/source/examples/generated/react-native/v12/Step1.snippet.user-api-key.tsx.rst b/source/examples/generated/react-native/v12/Step1.snippet.user-api-key.tsx.rst new file mode 100644 index 0000000000..57bc71e310 --- /dev/null +++ b/source/examples/generated/react-native/v12/Step1.snippet.user-api-key.tsx.rst @@ -0,0 +1,11 @@ +.. code-block:: typescript + + const user = useUser(); + + const createUserApiKey = async () => { + const {_id, key, name, disabled} = await user?.apiKeys.create(apiKeyName); + + // ...Do something with API key like save it + // or share it with external service that authenticates + // on user's behalf. + }; diff --git a/source/examples/generated/react-native/v12/Step2.snippet.api-key-delete.tsx.rst b/source/examples/generated/react-native/v12/Step2.snippet.api-key-delete.tsx.rst new file mode 100644 index 0000000000..580aa1393d --- /dev/null +++ b/source/examples/generated/react-native/v12/Step2.snippet.api-key-delete.tsx.rst @@ -0,0 +1,3 @@ +.. code-block:: typescript + + await user!.apiKeys.delete(cloudApiKey!._id); diff --git a/source/examples/generated/react-native/v12/Step2.snippet.api-key-disable.tsx.rst b/source/examples/generated/react-native/v12/Step2.snippet.api-key-disable.tsx.rst new file mode 100644 index 0000000000..486aae5ec3 --- /dev/null +++ b/source/examples/generated/react-native/v12/Step2.snippet.api-key-disable.tsx.rst @@ -0,0 +1,3 @@ +.. code-block:: typescript + + await user!.apiKeys.disable(cloudApiKey!._id); diff --git a/source/examples/generated/react-native/v12/Step2.snippet.api-key-enable.tsx.rst b/source/examples/generated/react-native/v12/Step2.snippet.api-key-enable.tsx.rst new file mode 100644 index 0000000000..5ddc89d5b4 --- /dev/null +++ b/source/examples/generated/react-native/v12/Step2.snippet.api-key-enable.tsx.rst @@ -0,0 +1,3 @@ +.. code-block:: typescript + + await user!.apiKeys.enable(cloudApiKey!._id); diff --git a/source/examples/generated/react-native/v12/Step2.snippet.look-up-user-api-key.tsx.rst b/source/examples/generated/react-native/v12/Step2.snippet.look-up-user-api-key.tsx.rst new file mode 100644 index 0000000000..5c83f13140 --- /dev/null +++ b/source/examples/generated/react-native/v12/Step2.snippet.look-up-user-api-key.tsx.rst @@ -0,0 +1,10 @@ +.. code-block:: typescript + + const getUserApiKey = async () => { + // List all of a user's keys + const keys = await user.apiKeys.fetchAll(); + // Get a specific key by its ID + const key = await user!.apiKeys.fetch(apiKey!._id); + + setCloudApiKey(key); + }; diff --git a/source/sdk/react-native/manage-users/authenticate-users.txt b/source/sdk/react-native/manage-users/authenticate-users.txt index 31826608e5..aaec0edc54 100644 --- a/source/sdk/react-native/manage-users/authenticate-users.txt +++ b/source/sdk/react-native/manage-users/authenticate-users.txt @@ -161,11 +161,16 @@ API Key User The :ref:`API key ` authentication provider allows server processes to access your app directly or on behalf of a user. -To log in with an API key, create an API Key credential with a server or user -API key and pass it to ``App.logIn()``: +Before you can log a user in with an API key, you need to +:ref:`create an API key `. -.. literalinclude:: /examples/generated/node/authenticate.snippet.server-api-key-login.js - :language: javascript +To log in with an API key: + +#. Destructure ``loginWithApiKey`` and ``result`` from the ``useAuth`` hook. +#. Pass your API key to ``loginWithApiKey()``. + +.. literalinclude:: /examples/generated/react-native/v12/LoginManager.snippet.api-key-login.tsx.rst + :language: typescript .. _react-native-custom-jwt-login: .. _react-native-login-custom-jwt: diff --git a/source/sdk/react-native/manage-users/manage-user-api-keys.txt b/source/sdk/react-native/manage-users/manage-user-api-keys.txt index 058cd855ab..9a79211f84 100644 --- a/source/sdk/react-native/manage-users/manage-user-api-keys.txt +++ b/source/sdk/react-native/manage-users/manage-user-api-keys.txt @@ -15,14 +15,17 @@ User API keys allow devices or services to communicate with App Services on beha that users credentials. User API keys can be revoked at any time by the authenticated user. User API keys do not expire on their own. -You can manage a user API key with the :js-sdk:`ApiKeyAuth ` +You can manage a user API key with the :js-sdk:`ApiKeyAuth ` client accessed with an authenticated user's :js-sdk:`User.apiKeys -` property. +` property. If you are using ``@realm/react``, you can access a user's ``ApiKeyAuth`` client with the ``useUser()`` hook in a component wrapped by ``UserProvider``. -.. literalinclude:: /examples/generated/react-native/ts/user-api-keys.test.snippet.user-api-key.tsx +.. literalinclude:: /examples/generated/react-native/v12/Step1.snippet.user-api-key-imports.tsx.rst + :language: typescript + +.. literalinclude:: /examples/generated/react-native/v12/Step1.snippet.user-api-key.tsx.rst :language: typescript .. _react-native-create-a-user-api-key: @@ -32,7 +35,7 @@ Create a User API Key To create a new :ref:`user API key `, pass a name that's unique among all of the user's API keys to -:js-sdk:`ApiKeyAuth.create() `. +:js-sdk:`ApiKeyAuth.create() `. The SDK returns the value of the user API key when you create it. Make sure to store the ``key`` value securely so that you can use it to log in. @@ -43,9 +46,8 @@ You **cannot** create a user API key for a :ref:`server API key ` or an :ref:`anonymous user `. -.. literalinclude:: /examples/generated/node/authenticate.snippet.create-user-api-key.js - :language: javascript - :start-after: const user = app.currentUser; +.. literalinclude:: /examples/generated/react-native/v12/Step1.snippet.create-user-api-key.tsx.rst + :language: typescript .. _react-native-look-up-a-user-api-key: @@ -53,14 +55,13 @@ Look up a User API Key ---------------------- To get an array that lists all of a user's API keys, call -:js-sdk:`ApiKeyAuth.fetchAll() `. +:js-sdk:`ApiKeyAuth.fetchAll() `. To find a specific API key, pass the key's ``_id`` to -:js-sdk:`ApiKeyAuth.fetch() `. +:js-sdk:`ApiKeyAuth.fetch() `. -.. literalinclude:: /examples/generated/node/authenticate.snippet.look-up-user-api-key.js +.. literalinclude:: /examples/generated/react-native/v12/Step2.snippet.look-up-user-api-key.tsx.rst :language: javascript - :start-after: const user = app.currentUser; .. _react-native-enable-or-disable-a-user-api-key: @@ -68,13 +69,15 @@ Enable or Disable an API Key ---------------------------- To enable or disable a user API key, pass the key's ``_id`` to -:js-sdk:`ApiKeyAuth.enable() ` or -:js-sdk:`ApiKeyAuth.disable() `. When a key +:js-sdk:`ApiKeyAuth.enable() ` or +:js-sdk:`ApiKeyAuth.disable() `. When a key is disabled, it cannot be used to log in on behalf of the user. -.. literalinclude:: /examples/generated/node/authenticate.snippet.enable-disable-user-api-key.js - :language: javascript - :start-after: const user = app.currentUser; +.. literalinclude:: /examples/generated/react-native/v12/Step2.snippet.api-key-enable.tsx.rst + :language: typescript + +.. literalinclude:: /examples/generated/react-native/v12/Step2.snippet.api-key-disable.tsx.rst + :language: typescript .. _react-native-delete-a-user-api-key: @@ -82,9 +85,8 @@ Delete an API Key ----------------- To permanently delete a user API, pass the key's ``_id`` to -:js-sdk:`ApiKeyAuth.delete() `. Deleted keys +:js-sdk:`ApiKeyAuth.delete() `. Deleted keys cannot be recovered. -.. literalinclude:: /examples/generated/node/authenticate.snippet.delete-user-api-key.js - :language: javascript - :start-after: const user = app.currentUser; +.. literalinclude:: /examples/generated/react-native/v12/Step2.snippet.api-key-delete.tsx.rst + :language: typescript