@uma-sdk/uma-auth-client v0.0.8
uma-auth-client
The UMA Auth Client SDK for web apps!
Installation
npm install @uma-sdk/uma-auth-client
or
yarn add @uma-sdk/uma-auth-client
Quick Start
See the full UMA Auth documentation here.
Connecting
The UMA Auth Client SDK helps you connect users' UMA wallets to your web app. Here's how you can get started.
First, generate a keypair and publish info about your app.
Next, add the connect button to your app and provide the pubkey you generated.
In React, you can use the UmaConnectButton element:
import { UmaConnectButton } from '@uma-sdk/uma-auth-client';
const App = () => {
return (
<UmaConnectButton
app-identity-pubkey="npub1scmpzl2ehnrtnhu289d9rfrwprau9z6ka0pmuhz6czj2ae5rpuhs2l4j9d"
nostr-relay="wss://nos.lol"
redirect-uri="http://localhost:3001"
required-commands={["pay_invoice", "get_balance"]}
optional-commands={["list_transactions"]}
budget-amount="500"
budget-currency="USD"
budget-period="monthly"
style={{
"--uma-connect-background": "#7366C5",
"--uma-connect-radius": "8px",
"--uma-connect-padding-x": "32px",
"--uma-connect-padding-y": "16px",
"--uma-connect-text-color": "#F9F9F9",
"--uma-connect-font-family": "Arial",
"--uma-connect-font-size": "16px",
"--uma-connect-font-weight": "600",
}}
/>
);
};
Alternatively, in raw HTML or a non-react context, you can use the web component implementation:
<!-- TODO: Host the cjs package in a public CDN. -->
<script src="../../packages/uma-auth-client/dist/uma-auth-client-web-components.umd.cjs"></script>
<uma-connect-button
app-identity-pubkey="npub1scmpzl2ehnrtnhu289d9rfrwprau9z6ka0pmuhz6czj2ae5rpuhs2l4j9d"
nostr-relay="wss://nos.lol"
redirect-uri="http://localhost:3001"
required-commands="pay_invoice,get_balance"
optional-commands="list_transactions"
budget-amount="500"
budget-currency="USD"
budget-period="monthly"
/>
Users can click their button to move through the flow to connect their wallet. Note that like a normal OAuth flow,
the user will be redirected to their wallet app to sign in, so make sure that you persist important state if needed for
when you're redirected back to the redirect-uri
.
Upon successful connection, connect button element will automatically exchange the authorization code for an access token.
If you don't have a connect button element on your redirect page, you can manually complete the exchange using the react hook useOAuth
:
const oAuth = useOAuth();
useEffect(() => {
if (oAuth.codeVerifier) {
oAuth.oAuthTokenExchange().then((res) => {
console.log(res);
});
}
}, [oAuth.codeVerifier]);
const isConnectionValid = oAuth.isConnectionValid();
const nwcConnectionUri = oAuth.nwcConnectionUri;
if (isConnectionValid) {
return <div>Connected!</div>;
}
In non-react contexts, you can still use useOAuth
to complete the token exchange:
const oAuth = useOAuth.getState();
if (oAuth.codeVerifier) {
oAuth.oAuthTokenExchange().then((res) => {
const isConnectionValid = oAuth.isConnectionValid();
const nwcConnectionUri = oAuth.nwcConnectionUri;
if (isConnectionValid) {
return console.log("Connected!", res);
}
});
}
Sending requests
Once you have a valid access token, you can use the react hook useNwcRequester
to send requests to the user's wallet.
const { nwcRequester } = useNwcRequester();
const [balance, setBalance] = useState<
Nip47.GetBalanceResponse | undefined
>();
useEffect(() => {
async function fetchBalance(nwcRequester: NwcRequester) {
const res = await nwcRequester.getBalance();
setBalance(res);
}
if (nwcRequester) {
fetchBalance(nwcRequester);
}
}, [nwcRequester]);
In non-react contexts, you can use the NwcRequester
class directly.
let requester: NwcRequester | null = null;
useOAuth.subscribe((oAuth) => {
if (oAuth.isConnectionValid() && oAuth.nwcConnectionUri && !requester) {
requester = new NwcRequester(oAuth.nwcConnectionUri, oAuth.clearUserAuth, oAuth.oAuthTokenExchange);
requester.getBalance().then((res) => {
console.log("Balance:", res);
});
}
});
If provided a token exchange handler, the NwcRequester will also handle refreshing tokens in case the access token expires (e.g. oAuthTokenExchange
).
If you need to send requests from your backend, you should send all the full token response info to your backend and utilize
any NWC library with the nwcConnectUri
, refreshing the URI with the refreshToken
as needed.