@tiendanube/nexo v0.3.0

@tiendanube/nexo

Nexo provides tools that allow communication between an external application and the Nuvemshop administrator.

Communication between the Admin and the App is done through messages following the observer pattern ( events subscribe/unsubscribe)

The messages that can be exchanged and are defined as Actions, these actions are typed and associated to Helpers that allows them to be used as promises

• @tiendanube/nexo
  • Instalation
  • Getting Started
    • Create a Nexo instance.
    • Check if the app is connected
    • Enable route synchronization
    • Get Session Token
  • Actions
  • Helpers
    • connect
    • iAmReady
    • navigateExit
    • getSessionToken
    • syncPathname
    • getStoreInfo
    • getIsMobileDevice
    • goTo
    • goToOldAdmin
    • copyToClipboard
    • navigateHeader
    • navigateHeaderRemove

Instalation

$ npm install @tiendanube/nexo

$ yarn add @tiendanube/nexo

Getting Started

Create a Nexo instance.

import nexo from '@tiendanube/nexo';

const instance = nexo.create({
  clientId: '123',
  log: true,
});

export default instance;

Check if the app is connected

Through the connect util you can check if the Admin allows you to exchange messages and at the same time with iAmReady notify that your application is ready to show.

To react application

import { useEffect, useState } from 'react';
import { connect, iAmReady } from '@tiendanube/nexo/helpers';
import nexo from './nexoClient'; // Nexo instance

function App() {
  const [isConnect, setIsConnect] = useState(false);

  useEffect(() => {
    connect(nexo).then(() => {
      setIsConnect(true);
      iAmReady(nexo);
    });
  }, []);

  if (!isConnect) return <MyAppSkeleton />;

  return <MyApp />
}

Enable route synchronization

This functionality will allow you to record the app navigation of your app in the browser URL via fragment (#myroute)

This example is made with react-router-dom

import { useEffect } from 'react';

import { useLocation, useHistory } from 'react-router-dom';
import { syncPathname } from '@tiendanube/nexo/helpers';
import nexo from './nexoClient';
import {
  ACTION_NAVIGATE_SYNC,
  NavigateSyncResponse,
} from '@tiendanube/nexo/actions';

function NexoSyncRoute({ children }: { children: React.ReactNode }) {
  const { pathname } = useLocation();
  const { push: goTo, replace: replaceTo } = useHistory();

  //to send the current path of the app to the browser url
  useEffect(() => {
    syncPathname(nexo, pathname);
  }, [pathname]);

  //to navigate in the app if the browser url changes
  useEffect(() => {
    const unsuscribe = nexo.suscribe(
      ACTION_NAVIGATE_SYNC,
      ({ path, replace }: NavigateSyncResponse) => {
        replace ? goTo(path) : replaceTo(path);
      },
    );

    return unsuscribe;
  }, [goTo, replaceTo]);

  return children;

Get Session Token

Through the getSessionToken util we can obtain a session token (JWT) that will be used to verify the authenticity of the request to your Backend. The JWT is signed with the Application's Client Secret

import axios from "axios";
import { getSessionToken } from '@tiendanube/nexo/helpers';
import nexo from "./nexoClient";

const axiosIntance = axios.create({
  baseURL: 'https://my-backend.com',
});

axiosIntance.interceptors.request.use(async (request) => {
  const token = await getSessionToken(nexo);
  const bearerToken = `Bearer ${token}`;
  request.headers = { ...request.headers, Authorization: bearerToken };
  return request;
});

export default axiosIntance;

Actions

Helpers

connect

To wait if the application is ready to render

Arguments nexo (NexoClient): The Nexo Instance ttl (number): Maximum time waiting for the admin, default 3000

Response Promise<void> Success or Fail

Example

connect(nexo).then(() => {
    //success
}).catch(() => {
    //fail
})

iAmReady

To notify that the app is rendering

Arguments nexo (NexoClient): The Nexo Instance

Response void

Example

iAmReady(nexo);

navigateExit

To navigate to the route from which the application was accessed.

Action: app/navigate/exit

Arguments nexo (NexoClient): The Nexo Instance

Response void

Example

navigateExit(nexo);

getSessionToken

To requests the session token (JWT)

Action: app/auth/sessionToken

Arguments nexo (NexoClient): The Nexo Instance

Response Promise<token: string>: Promise with session token

Example

const token = await getSessionToken(nexo);

syncPathname

To update his current location to propagate the internal navegation.

Action: app/navigate/sync

Arguments nexo (NexoClient): The Nexo Instance

Response Promise<token: string>: Promise with session token

Example

syncPathname(nexo, pathname);

getStoreInfo

To request information about current Store

Action: app/store/info

Arguments nexo (NexoClient): The Nexo Instance

Response Promise<StoreInfoResponse>: Promise with store info

StoreInfoResponse {
  id: string;
  name: string;
  url: string;
  country: string;
  language: string;
  currency: string;
}

Example

const storeInfo = await getStoreInfo(nexo);

getIsMobileDevice

To check if the app is being loaded from the Mobile Device

Action: app/device

Arguments nexo (NexoClient): The Nexo Instance

Response Promise<boolean>: True / False

Example

const isMobileDevice = await getIsMobileDevice(nexo);

goTo

To navigate to a specific route in Admin

Action: app/navigate/goTo

Arguments nexo (NexoClient): The Nexo Instance path (string): Specific path to navigate

Response void

Example

goTo(nexo, '/products');

goToOldAdmin

To navigate to a specific route in Old Admin, only available Web mode (non mobile device)

Action: app/navigate/goToOldAdmin

Arguments nexo (NexoClient): The Nexo Instance path (string): Specific path to navigate

Response void

Example

goToOldAdmin(nexo, '/products');

copyToClipboard

To copy the sent text to the device's clipboard

Action: app/utils/copyToClipboard

Arguments nexo (NexoClient): The Nexo Instance text (string): Text to copy

Response Promise<boolean>: If copied successfully

Example

copyToClipboard(nexo, 'text to copy');

navigateHeader

To show the navigation action in the Header Top, only available Web mode (non mobile device)

Action: app/utils/copyToClipboard

Arguments nexo (NexoClient): The Nexo Instance config (NavigateHeaderRequest): Config to navegate header

NavigateHeaderRequest {
  goTo: "back" | string;
  text: string;
};

Response void

Example

navigateHeader(nexo, { goTo: '/', text: 'Product List' });
//or
navigateHeader(nexo, { goTo: 'back', text: 'Back' });

navigateHeaderRemove

Remove the action of Header Top, only available Web mode (non mobile device)

Action: app/utils/copyToClipboard

Arguments nexo (NexoClient): The Nexo Instance

Response void

Example

navigateHeaderRemove(nexo);