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.