# xumm-oauth2-pkce

> Xumm JS SDK for client side only OAuth2 PKCE (implicit flow) auth.

Latest version **2.8.7** (published 2024-11-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install xumm-oauth2-pkce
pnpm add xumm-oauth2-pkce
yarn add xumm-oauth2-pkce
bun add xumm-oauth2-pkce
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.8.7 |
| Published | 2024-11-07 |
| First published | 2022-06-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 341.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Maintainers | kevinkoobs, koen_xrpl-labs, wietsewind |
| Keywords | xrp, xrpl, ledger, xumm, sdk, pkce, oauth2, client, authorization, flow, auth |

## Links

- npm: https://www.npmjs.com/package/xumm-oauth2-pkce
- Repository: https://github.com/XRPL-Labs/XummPkce
- Homepage: https://github.com/XRPL-Labs/XummPkce/#readme
- Issues: https://github.com/XRPL-Labs/XummPkce/issues
- npm.io page: https://npm.io/package/xumm-oauth2-pkce

## Dependencies (4)

- [debug](https://npm.io/package/debug.md) ^4.1.1
- [events](https://npm.io/package/events.md) ^3.3.0
- [xumm-sdk](https://npm.io/package/xumm-sdk.md) ^1.11.0
- [xumm-js-pkce](https://npm.io/package/xumm-js-pkce.md) ^1.0.2

## Alternatives

- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads
- [escher-request](https://npm.io/package/escher-request.md) — 545 weekly downloads

## Recent versions

- 2.8.7 (latest) — 2024-11-07
- 2.8.5 — 2023-12-18
- 2.8.4 — 2023-12-15
- 2.8.3 — 2023-11-13
- 2.8.2 — 2023-06-20
- 2.8.1 — 2023-06-20
- 2.8.0 — 2023-05-16
- 2.7.9 — 2023-03-29
- 2.7.8 — 2023-03-24
- 2.7.7 — 2023-03-24
- 2.7.6 — 2023-02-16
- 2.7.5 — 2023-01-22
- 2.7.4 — 2023-01-22
- 2.7.3 — 2022-12-29
- 2.7.2 — 2022-12-21
- … 24 more at https://npm.io/package/xumm-oauth2-pkce/versions

## README

# Xumm OAuth2 Authorization Code PKCE flow

#### Part of the "Xumm Universal SDK", which is the preferred way of interacting with the Xumm ecosystem from JS/TS environments: https://www.npmjs.com/package/xumm - https://github.com/XRPL-Labs/Xumm-Universal-SDK

Xumm JS SDK for client side only OAuth2 PKCE (Authorization Code flow) auth [![npm version](https://badge.fury.io/js/xumm-oauth2-pkce.svg)](https://badge.fury.io/js/xumm-oauth2-pkce)

Questions? https://xumm.readme.io/discuss

Demo? https://oauth2-pkce-demo.xumm.dev

NPM:
[https://www.npmjs.com/package/xumm-oauth2-pkce](https://www.npmjs.com/package/xumm-oauth2-pkce)

## Constructor

```
new XummPkce('api-key-uuidv4', { options })
```

#### Options

```
interface XummPkceOptions {
  redirectUrl: string;      // Defaults to `document.location.href`, e.g. to add state params.
  rememberJwt: boolean;     // Defaults to `true`
  storage: Storage;         // Defaults to window.localStorage
  implicit: boolean;        // Defaults to `false`, `true` allows x-browser sign in, but it less secure
}
```

## Samples:

#### Event based

Please note: please use the Event based sample (above) if possible: this is more compatible with future
releases than the promise-based (await/async) method as displayed below.

### See [this example (source code)](https://github.com/XRPL-Labs/XummPkce/blob/main/sample/jsmodule.html) :)

#### Events (emitted)

- `success` = User signed in successfully, `sdk.state()` returns `.me` and `.sdk` objects
- `retrieved` = Retrieved existing session after e.g. browser refresh or mobile redirect, `sdk.state()` returns `.me` and `.sdk` objects
- `error` = Error, expected (e.g. user cancelled) or unexpected (...), returns argument `error` with an `Error()` object, `sdk.state()` returns null


#### Promise based sample

```javascript
const xumm = new XummPkce("uuid-uuid-uuid-uuid");

const xummSignInHandler = (state) => {
  if (state.me) {
    const { sdk, me } = state;
    console.log("state", me);
    // Also: sdk » xumm-sdk (npm)
  }
};
// To pick up on mobile client redirects:
xumm.on("retrieved", async () => {
  console.log("Retrieved: from localStorage or mobile browser redirect");
  xummSignInHandler(await xumm.state());
});

// E.g. when clicking a button:
document.getElementById("somebutton").onclick = () => {
  xumm.authorize().then((session) => {
    xummSignInHandler(session);
  });
};
```


### CDN (browser):

A browserified version (latest) is available at [JSDelivr](https://cdn.jsdelivr.net/npm/xumm-oauth2-pkce/dist/browser.min.js) & direclty from the `xumm.app` domain:

```html
<script src="https://xumm.app/assets/cdn/xumm-oauth2-pkce.min.js"></script>
```

---
_Source: https://npm.io/package/xumm-oauth2-pkce · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._