@monerium/sdk 2.6.4 → 2.7.0

package/README.md

@@ -1,122 +1,339 @@
-# @monerium/sdk
+# Monerium SDK Documentation
 
-Everything you need to interact with the [Monerium API](https://monerium.dev/api-docs) - an electronic money issuer.
+Monerium connects your web3 wallet to any euro bank account with your personal IBAN.
+All incoming euro payments are automatically minted as EURe tokens to your wallet.
+Sending EURe to traditional bank accounts is just as easy.
+With a single signature from your wallet, your EURe is burned and sent as Euros to any bank account.
 
-_This package is in development. Please make sure to check if any future updates contain commits
-that may change the behavior of your application before you upgrade. If you find any issues please report them [here](https://github.com/monerium/sdk/issues)._
+## Table of Contents
 
-[NPM package](https://www.npmjs.com/package/@monerium/sdk)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage Examples](#usage-examples)
+- [API Reference](#api-reference)
+- [Contributing](#contributing)
+- [FAQs](#faqs)
+- [Support](#support)
+- [Release Notes](#release-notes)
+- [License](#license)
 
-[Source code](https://github.com/monerium/sdk)
+## Installation
 
-[SDK Documentation](https://monerium.github.io/sdk/)
+### Prerequisites
 
-[SDK JS-Docs](https://monerium.github.io/sdk/)
-
-[Code coverage](https://monerium.github.io/sdk/coverage)
-
-## Installing
+Node v16.15 or higher is required.
 
 ```sh
-# Node
 yarn add @monerium/sdk
 ```
 
-## Usage
+## Configuration
+
+### Environments - URLs
 
-- `watch`: Run Vite in watch mode to detect changes to files during development
-- `build`: Run Vite to build a production release distributable
+| Environment | Web                  | API                      |
+| ----------- | -------------------- | ------------------------ |
+| sandbox     | https://monerium.dev | https://api.monerium.dev |
+| production  | https://monerium.app | https://api.monerium.app |
 
-### Environments
+### Environments - Networks
 
-#### Sandbox:
+| Environment | Chain    | Network |
+| ----------- | -------- | ------- |
+| sandbox     | ethereum | goerli  |
+|             | polygon  | mumbai  |
+|             | gnosis   | chiado  |
+| production  | ethereum | mainnet |
+|             | polygon  | mainnet |
+|             | gnosis   | mainnet |
 
-chains: `ethereum`, `polygon`, `gnosis`.
+## Usage Examples
+
+We recommend starting in the [Developer Portal](https://monerium.dev/docs/welcome). There you will learn more about `client_id`'s and ways of authenticating.
 
-networks: `goerli`, `mumbai`, `chiado`.
+#### Initialize and authenticate using Client Credentials
 
-#### Production:
+> Client Credentials is used when there's no need for user interaction, and the system-to-system interaction requires authentication.
 
-chains: `ethereum`, `polygon`, `gnosis`.
+```ts
+import { MoneriumClient } from '@monerium/sdk';
+// Initialize the client with credentials
+const monerium = new MoneriumClient({
+  environment: 'sandbox',
+  clientId: 'your_client_credentials_uuid', // replace with your client ID
+  clientSecret: 'your_client_secret', // replace with your client secret
+});
 
-networks: `mainnet`, `mainnet`, `mainnet`.
+// Retrieve authentication data after successful authentication.
+await monerium.getAuthContext();
 
-## Getting started
+// Access tokens are now available for use.
+const { access_token, refresh_token } = monerium.bearerProfile as BearerProfile;
+```
 
-We recommend starting in the [Developer Portal](https://monerium.dev/docs/welcome). There you will learn more about `client_id`'s and ways of authenticating.
+Interfaces:
 
-### Import the SDK and initialize a client
+- {@link client.MoneriumClient}
+- {@link types.BearerProfile}
+
+API documentation:
+
+- [/auth/token](https://monerium.dev/api-docs#operation/auth-token)
+- [/auth/context](https://monerium.dev/api-docs#operation/auth-context)
+
+#### Initialize and authenticate using Authorization Code Flow with PKCE
+
+> Authorization Code Flow with PKCE is used for apps where direct user interaction is involved, and the application is running on an environment where the confidentiality of a secret cannot be safely maintained. It allows the application to authorize users without handling their passwords and mitigates the additional risk involved in this sort of delegation.
+
+First you have to navigate the user to the Monerium authentication flow. This can be done by generating a URL and redirecting the user to it. After the user has authenticated, Monerium will redirect back to your specified URI with a code. You can then finalize the authentication process by exchanging the code for access and refresh tokens.
 
 ```ts
 import { MoneriumClient } from '@monerium/sdk';
 
-// By default, the client will use the sandbox environment.
-// To change to production, pass "production" as the first argument.
-const client = new MoneriumClient('sandbox');
+export function App() {
+  const [authCtx, setAuthCtx] = useState<AuthContext | null>(null);
+  const [monerium, setMonerium] = useState<MoneriumClient>();
+  const [isAuthorized, setIsAuthorized] = useState<boolean>(false);
+
+  useEffect(() => {
+    const sdk = new MoneriumClient({
+      environment: 'sandbox',
+      clientId: 'f99e629b-6dca-11ee-8aa6-5273f65ed05b',
+      redirectUrl: 'http://localhost:4200',
+    });
+    setMonerium(sdk);
+  }, []);
+
+  useEffect(() => {
+    const connect = async () => {
+      if (monerium) {
+        setIsAuthorized(await monerium.connect());
+      }
+    };
+
+    connect();
+
+    return () => {
+      if (monerium) {
+        monerium.disconnect();
+      }
+    };
+  }, [monerium]);
+
+  useEffect(() => {
+    const fetchData = async () => {
+      if (monerium && isAuthorized) {
+        try {
+          setAuthCtx(await monerium.getAuthContext());
+        } catch (err) {
+          console.error('Error fetching data:', err);
+        }
+      }
+    };
+    fetchData();
+  }, [monerium, isAuthorized]);
+
+  return (
+    <div>
+      {!isAuthorized && <button onClick={() => monerium?.authorize()}>Connect</button>}
+
+      <p>{authCtx?.name || authCtx?.email}</p>
+    </div>
+  );
+}
 ```
 
-### Authenticate using client credentials
+Interfaces:
+
+- {@link types.AuthCodeRequest}
+- {@link types.BearerProfile}
+
+API documentation:
+
+- [/auth](https://monerium.dev/api-docs#operation/auth)
+- [/auth/token](https://monerium.dev/api-docs#operation/auth-token)
+- [/auth/context](https://monerium.dev/api-docs#operation/auth-context)
+
+#### Get account information
 
 ```ts
-await client.auth({
- client_id: "your_client_credentials_uuid"
- client_secret: "your_client_secret"
-})
+// Get all profiles for the authenticated user.
+const authCtx: AuthContext = await monerium.getAuthContext();
 
-// User is now authenticated, get authentication data
-await client.getAuthContext()
+// Fetching all accounts for a specific profile
+const { id: profileId, accounts }: Profile = await monerium.getProfile(authCtx.profiles[0].id);
 
-// You can now find your access and refresh token here:
-const { access_token, refresh_token } = client.bearerProfile;
+// Fetching all balances for a specific profile
+const balances: Balances = await monerium.getBalances(profileId);
 ```
 
-### Authenticate using auth flow
+Interfaces:
+
+- {@link types.AuthContext}
+- {@link types.Profile}
+- {@link types.Balances}
+
+API documentation:
+
+- [/auth/context](https://monerium.dev/api-docs#operation/auth-context)
+- [/profile](https://monerium.dev/api-docs#operation/profile)
+- [/profile/{profiledId}/balances](https://monerium.dev/api-docs#operation/profile-balances)
+
+#### Get token information
+
+Get the contract addresses of EURe tokens.
+
+```ts
+const tokens: Token[] = await monerium.getTokens();
+```
+
+Interfaces:
+
+- {@link types.Token}
+
+API documentation:
+
+- [/tokens](https://monerium.dev/api-docs#operation/tokens)
+
+#### Link a new address to Monerium
+
+It's important to understand, when interacting with a blockchain, the user needs to provide a signature in their wallet.
+This signature is used to verify that the user is the owner of the wallet address.
+
+We recommend Viem as an Ethereum interface, see: https://viem.sh/docs/actions/wallet/signMessage.html
 
 ```ts
-// Construct the authFlowUrl for your application and redirect your customer.
-let authFlowUrl = client.getAuthFlowURI({
-  client_id: "your_client_authflow_uuid",
-  redirect_uri: "http://your-webpage.com/monerium-integration"
-  // optional automatic wallet selection:
-  network: "mumbai",
-  chain: "polygon",
-  address: "0xValidAddress72413Fa92980B889A1eCE84dD",
-  signature: "0xValidSignature0df2b6c9e0fc067ab29bdbf322bec30aad7c46dcd97f62498a91ef7795957397e0f49426e000b0f500c347219ddd98dc5080982563055e918031c"
 
+import { constants } from '@monerium/sdk';
+import { walletClient } from '...' // See Viem documentation
+
+const { LINK_MESSAGE } = constants; // "I hereby declare that I am the address owner."
+
+// Send a signature request to the wallet.
+const signature = await walletClient.signMessage({
+  message: LINK_MESSAGE,
 })
-// Store the code verifier in localStorage
-window.localStorage.setItem("myCodeVerifier", client.codeVerifier);
-// Redirecting to the Monerium onboarding / Authentication flow.
-window.location.replace(authFlowUrl)
+
+// Link a new address to Monerium and create accounts for ethereum and gnosis.
+await monerium.linkAddress(profileId, {
+  address: '0xUserAddress72413Fa92980B889A1eCE84dD', // user wallet address
+  message: LINK_MESSAGE
+  signature,
+  accounts: [
+    {"currency":"eur","chain":"ethereum","network":"goerli"},
+    {"currency":"eur","chain":"gnosis","network":"chiado"}
+  ],
+} as LinkAddress);
+```
+
+Interfaces:
+
+- {@link types.LinkAddress}
+
+API documentation:
+
+- [/profile/{profiledId}/addresses](https://monerium.dev/api-docs#operation/profile-addresses)
+
+#### Get and place orders
+
+```ts
+// Get orders for a specific profile
+const orders: Order[] = await monerium.getOrders(profileId);
 ```
 
 ```ts
-// As the final step of the flow, the customer will be routed back to the `redirect_uri` with a `code` parameter attached to it.
-// i.e. http://your-webpage.com/monerium-integration?code=1234abcd
-
-await client.auth({
-  client_id: 'your_client_authflow_uuid',
-  code: new URLSearchParams(window.location.search).get('code'),
-  code_verifier: window.localStorage.getItem('myCodeVerifier'),
-  redirect_url: 'http://your-webpage.com/monerium-integration',
+// Place a redeem order
+import { placeOrderMessage } from '@monerium/sdk';
+import { walletClient } from '...'; // See Viem documentation
+
+const amount = '100'; // replace with the amount in EUR
+const iban = 'EE12341234123412341234'; // replace with requested IBAN
+
+// First you have to form the message that will be signed by the user
+const message = placeOrderMessage(amount, iban);
+
+// The message should look like this, with the current date and time in RFC3339 format:
+// Send EUR 100 to EE12341234123412341234 at Thu, 29 Dec 2022 14:58:29Z
+
+// Send a signature request to the wallet.
+const signature = await walletClient.signMessage({
+  message: message,
 });
 
-// User is now authenticated, get authentication data
-await client.getAuthContext();
+// Place the order
+const order = await monerium.placeOrder({
+  amount,
+  signature,
+  address: '0xUserAddress72413Fa92980B889A1eCE84dD', // user wallet address
+  counterpart: {
+    identifier: {
+      standard: 'iban', // PaymentStandard.iban,
+      iban,
+    },
+    details: {
+      firstName: 'User',
+      lastName: 'Userson',
+      county: 'IS',
+    },
+  },
+  message,
+  memo: 'Powered by Monerium SDK',
+  chain: 'ethereum',
+  network: 'goerli',
+  // supportingDocumentId, see below
+});
+```
+
+Interfaces:
+
+- {@link types.Order}
+- {@link types.PaymentStandard}
+
+API documentation:
 
-// You can now find your access and refresh token here:
-const { access_token, refresh_token } = client.bearerProfile;
+- [GET /orders](https://monerium.dev/api-docs#operation/orders)
+- [POST /orders](https://monerium.dev/api-docs#operation/post-orders)
+
+#### Add supporting documents
+
+When placing orders with payouts above 15,000 EUR, a supporting document is required. The document must be uploaded to Monerium before the order can be placed. Supporting documents can be an invoice or an agreement.
+
+```ts
+// Upload a supporting document
+const supportingDocumentId: SupportingDoc = await uploadSupportingDocument(document);
 ```
 
+Interfaces:
+
+- {@link types.SupportingDoc}
+
+API documentation:
+
+- [/files](https://monerium.dev/api-docs#operation/supporting-document)
+
+## API Reference
+
+[API Documentation](https://monerium.dev/docs/api)
+
 ## Contributing
 
 We are using [commitlint](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional) to enforce that developers format the commit messages according to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) guidelines.
 
 We are using Yarn as a package manager.
 
-```
+```sh
+# Install dependencies
 yarn
+
+# Run Vite to build a production release distributable
 yarn build
+
+# Run Vite in watch mode to detect changes to files during development
+yarn watch
+
+# Update the docs. This will run the build and update the docs in the static folder.
+# Open static/index.html in your browser to view the docs. Refresh the page to see changes.
+yarn docs:watch
 ```
 
 Smart IDEs (such as VSCode) require [special configuration](https://yarnpkg.com/getting-started/editor-sdks) for TypeScript to work when using Yarn Plug'n'Play installs.
@@ -138,6 +355,26 @@ cd ../your-project
 yarn link "@monerium/sdk"
 ```
 
-## Publishing
+If you get an error that there is already a package called '@monerium/sdk' registered, but you can't find it and unlinking does nothing, remove it manually with `rm -rf ~/.config/yarn/link/@monerium` and try again.
+
+#### Documentation
+
+Refer to [Typedocs](https://typedoc.org/) syntaxes to use for this [documentation](https://monerium.github.io/sdk/).
+
+#### Publishing
 
 When changes are merged to the `main` branch that follows the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) standard, [release-please](https://github.com/googleapis/release-please) workflow creates a pull request, preparing for the next release. If kept open, the following commits will also be added to the PR. Merging that PR will create a new release, a workflow will publish it on NPM and tag it on Github.
+
+## FAQs
+
+Common questions developers have regarding the SDK.
+
+## Support
+
+[Support](https://monerium.app/help)
+[Telegram](https://t.me/+lGtM1gY9zWthNGE8)
+[Github Issues](https://github.com/monerium/sdk/issues)
+
+## Release Notes
+
+https://github.com/monerium/sdk/releases

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+import type { AuthArgs, AuthorizationCodeCredentials, AuthContext, Balances, BearerProfile, ClassOptions, ENV, Environment, LinkAddress, MoneriumEvent, MoneriumEventListener, NewOrder, AuthFlowOptions, Order, OrderFilter, PKCERequestArgs, Profile, SupportingDoc, Token, ClientCredentials } from './types';
+export declare class MoneriumClient {
+    #private;
+    /**
+     * @deprecated, use sessionStorage
+     * The PKCE code verifier
+     * */
+    codeVerifier?: string;
+    /** The bearer profile will be available after authentication, it includes the access_token and refresh_token */
+    bearerProfile?: BearerProfile;
+    isAuthorized: boolean;
+    /** Constructor for no arguments, defaults to sandbox */
+    constructor();
+    /** Constructor with only env as an argument*/
+    constructor(env: ENV);
+    /** Constructor with {@link ClassOptions} */
+    constructor(options: ClassOptions);
+    /**
+     * Construct the url to the authorization code flow,
+     * Code Verifier needed for the code challenge is stored in session storage
+     * For automatic wallet link, add the following properties: `address`, `signature` & `chainId`
+     * @returns string
+     * {@link https://monerium.dev/api-docs#operation/auth}
+     */
+    authorize(client?: AuthFlowOptions): Promise<void>;
+    connect(client?: AuthorizationCodeCredentials | ClientCredentials): Promise<boolean>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/auth-token}
+     */
+    getBearerToken(args: AuthArgs): Promise<BearerProfile>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/auth-context}
+     */
+    getAuthContext(): Promise<AuthContext>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/profile}
+     * @param {string} profileId - the id of the profile to fetch.
+  
+     */
+    getProfile(profileId: string): Promise<Profile>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/profile-balances}
+     * @param {string=} profileId - the id of the profile to fetch balances.
+     */
+    getBalances(profileId?: string): Promise<Balances[]>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/orders}
+     */
+    getOrders(filter?: OrderFilter): Promise<Order[]>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/order}
+     */
+    getOrder(orderId: string): Promise<Order>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/tokens}
+     */
+    getTokens(): Promise<Token[]>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/profile-addresses}
+     */
+    linkAddress(profileId: string, body: LinkAddress): Promise<unknown>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/post-orders}
+     */
+    placeOrder(order: NewOrder, profileId?: string): Promise<Order>;
+    /**
+     * {@link https://monerium.dev/api-docs#operation/supporting-document}
+     */
+    uploadSupportingDocument(document: File): Promise<SupportingDoc>;
+    connectOrderSocket(): Promise<void>;
+    subscribeToOrderNotifications: () => WebSocket;
+    disconnect(): Promise<void>;
+    /**
+     * Subscribe to MoneriumEvent to receive notifications using the Monerium API (WebSocket)
+     * We are setting a subscription map because we need the user to have a token to start the WebSocket connection
+     * {@link https://monerium.dev/api-docs#operation/profile-orders-notifications}
+     * @param event The event to subscribe to
+     * @param handler The handler to be called when the event is triggered
+     */
+    subscribeOrders(event: MoneriumEvent, handler: MoneriumEventListener): void;
+    /**
+     * Unsubscribe from MoneriumEvent and close the socket if there are no more subscriptions
+     * @param event The event to unsubscribe from
+     */
+    unsubscribeOrders(event: MoneriumEvent): void;
+    /**
+     * @deprecated since v2.6.4, use {@link getBearerToken} instead.
+     */
+    auth: (args: AuthArgs) => Promise<BearerProfile>;
+    /**
+     * @deprecated since v2.6.4, use {@link authorize} instead.
+     */
+    getAuthFlowURI: (args: PKCERequestArgs) => string;
+    /**
+     *  @deprecated since v2.0.7, use {@link getAuthFlowURI} instead.
+     */
+    pkceRequest: (args: PKCERequestArgs) => string;
+    getEnvironment: () => Environment;
+}

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from './types';
+declare const MONERIUM_CONFIG: Config;
+export { MONERIUM_CONFIG };

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const LINK_MESSAGE = "I hereby declare that I am the address owner.";
+export declare const STORAGE_CODE_VERIFIER = "monerium.sdk.code_verifier";
+export declare const STORAGE_REFRESH_TOKEN = "monerium.sdk.refresh_token";
+declare const constants: {
+    LINK_MESSAGE: string;
+    STORAGE_CODE_VERIFIER: string;
+    STORAGE_REFRESH_TOKEN: string;
+};
+export default constants;

package/dist/helpers/auth.helpers.d.ts

@@ -0,0 +1,23 @@
+import { AuthArgs, AuthCodeRequest, ClientCredentialsRequest, PKCERequestArgs, RefreshTokenRequest } from '../types';
+/** Structure the Auth Flow params, support for ChainId instead of chain & network */
+export declare const getAuthFlowParams: (args: PKCERequestArgs, codeChallenge: string) => string | undefined;
+/**
+ * Find a more secure way to generate a random string
+ * Using crypto-js to generate a random string was causing the following error:
+ * `Error: Native crypto module could not be used to get secure random number.`
+ * https://github.com/brix/crypto-js/issues/256
+ */
+export declare const generateRandomString: () => string;
+/** Generate the PKCE code challenge */
+export declare const generateCodeChallenge: (codeVerifier: string) => string;
+/**
+ * Constructs the Auth Flow URL and stores the code verifier in the session storage
+ */
+export declare const getAuthFlowUrlAndStoreCodeVerifier: (baseUrl: string, args: PKCERequestArgs) => string;
+/**
+ * Clean the query string from the URL
+ */
+export declare const cleanQueryString: () => void;
+export declare const isAuthCode: (args: AuthArgs) => args is AuthCodeRequest;
+export declare const isRefreshToken: (args: AuthArgs) => args is RefreshTokenRequest;
+export declare const isClientCredentials: (args: AuthArgs) => args is ClientCredentialsRequest;

package/dist/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './auth.helpers';
+export * from './service.helpers';

package/dist/helpers/service.helpers.d.ts

@@ -0,0 +1 @@
+export declare const rest: <T>(url: string, method: string, body?: BodyInit | Record<string, string>, headers?: Record<string, string>) => Promise<T>;