@trilitech-umami/umami-embed/README.md

[WIP - not ready for production use] A simple embeddable Umami wallet

# Umami Embed - WIP, not ready for production use

Umami-Embed is a component designed to integrate an instance of Umami Wallet into a webpage through an iFrame. It securely encapsulates user details and offers an API for the host application to interact with the Tezos blockchain.

Umami-Embed allows users to engage with decentralized applications (dApps) directly, eliminating the requirement for a separate wallet application.

For the demo implementation and more information, please visit the [Umami-Embed Github repository](https://github.com/trilitech/umami-embed).

## Network Access

- `ghostnet` - available for anyone to use.
- `mainnet` - requires allowlisting. Please contact us at umami-support@trili.tech to get your domain added to the allowlist for mainnet access.

## Supported Features

Methods are expected to be called in a synchronized manner. Each operation must be completed before another can be initiated.

Each method returns a promise that resolves upon successful completion or fails with error details if something goes wrong.

Public user data is stored in local storage to prevent the need for unnecessary re-logins. Logout removes the stored data.

### Workflow

#### Initialization / Deinitialization

Set up or tear down the Umami-Embed environment.

The initialization step is required before any other method can be called.

If the user has logged in previously and their data is saved in local storage, it will be retrieved at this step.

On init, `UmamiEmbedConfig` can be applied. It includes the following parameters:

- `network` - required, either `mainnet` or `ghostnet`.
- `iframeParent` - optional `HTMLElement` to attach the iFrame to. Defaults to `document.body`.
- `useLocalEmbedIframe` - `false` by default. When `true`, it looks for an iframe at [http://localhost:5173/](http://localhost:5173/) (works on `ghostnet` only).
- `loginOptions` - defaults to including all login types. You can specify an array with any of these options: `google`, `reddit`, `twitter`, `facebook`.
- `theme` - `light` by default. Supports `light` and `dark` options.
- `logsLevel` - `none` by default. Can be set to `none`, `info`, `warn`, `error`.

Check [types.ts](../src/types.ts) for more information about supported values.

##### Example

```
const umami = new UmamiEmbed();

const config: UmamiEmbedConfig = { network: 'ghostnet' };
await umami.init(config);

// prints true
console.log(umami.isInitialized);

// prints user data if saved in local storage
if (umami.isLoggedIn) {
    console.log(umami.user);
}

umami.destroy();

```

#### Login / Logout

Authenticate users through selected supported social logins.

`login()` returns user information upon successful execution.

If user data is present in local storage, it can be accessed by calling `user` property. The property will be `null` otherwise.

##### Example

```
const umami = new UmamiEmbed();
await umami.init({ network: 'ghostnet' });

if (umami.isLoggedIn) {
    const userData = umami.user;
    await umami.logout();
} else {
    const userData = await umami.login();
    console.log(userData);
}

```

#### Sending Tezos Operations

Send a list of Tezos operations for user approval. If user is not logged in, this method will throw an error.

Before displaying the confirmation modal, Umami Embed validates the operation and precomputes the fee. If the computation fails, the promise will resolve with an error. Otherwise, the confirmation modal will be displayed to the user.

Please note that the computation process may take some time. It is recommended to provide feedback to the user indicating that the operation has started, as nothing will be shown on our side until the computation completes.

Operations must be provided in `PartialTezosOperation` format. Refer to `@airgap/beacon-sdk` and the [operation request doc](https://docs.walletbeacon.io/getting-started/first-dapp/#operation-request) for more details.

`send()` returns operation hash if the operation submission is successful.

##### Example

```
const umami = new UmamiEmbed();
await umami.init({ network: 'ghostnet' });
await umami.login();

umamiEmbed.send([ { "kind" : "transaction", "destination" : "tz1...", "amount" : "1000" } ]);
```

#### Signing Payload

Send a payload for user to sign. If user is not logged in, this method will throw an error.

This method allows users to approve and sign arbitrary data from a decentralized application.

`sign()` returns the signature of the payload after the user approves it through the confirmation modal. If user declines singing, the method will throw an error.

The payload can be signed using different signing types, such as RAW, OPERATION, or MICHELINE.

##### Example

```
const umami = new UmamiEmbed();
await umami.init({ network: 'ghostnet' });
await umami.login();

const payload = 'some-payload-data';  // This could be any payload you want to sign
const signature = await umami.sign(SigningType.RAW, payload);
```

## License

This project is licensed under the MIT License. For more details, please visit the [LICENSE file](https://github.com/trilitech/umami-embed/blob/main/LICENSE).