1 | # @bearer/js
|
2 |
|
3 | The hassle-free way to use bearer's integrations into any web application
|
4 |
|
5 | ## Getting started
|
6 |
|
7 | Bearer lib can be used instantly in your page or with a package system.
|
8 |
|
9 | ### Directly in your page
|
10 |
|
11 | ```html
|
12 | <script src="https://cdn.jsdelivr.net/npm/@bearer/js@beta6/lib/bearer.production.min.js"></script>
|
13 | <script>
|
14 | // you have now access to a global `bearer` function, initialize your code by passing the `clientId` as parameter
|
15 | const bearerClient = bearer('clientId')
|
16 | </script>
|
17 | ```
|
18 |
|
19 | ### With a build system
|
20 |
|
21 | ```bash
|
22 | yarn add @bearer/js
|
23 | # or
|
24 | npm install @bearer/js
|
25 | ```
|
26 |
|
27 | In your app
|
28 |
|
29 | ```jsx
|
30 | import bearer from '@bearer/js'
|
31 |
|
32 | class MyApp {
|
33 | componentDidMount() {
|
34 | bearer('clientId')
|
35 | }
|
36 | }
|
37 | ```
|
38 |
|
39 | ## Usage
|
40 |
|
41 | ### Invoke Functions
|
42 |
|
43 | The Bearer SDK for JavaScript lets you invoke integration's functions.
|
44 | ```js
|
45 | const integrations = bearer('BEARER_CLIENT_ID');
|
46 |
|
47 | integrations.invoke('INTEGRATION_ID', 'myFunction')
|
48 | .then(console.log)
|
49 | .catch(console.error)
|
50 | ```
|
51 |
|
52 | Passing params to your function works as follow:
|
53 | ```js
|
54 | const integrations = bearer('BEARER_CLIENT_ID');
|
55 |
|
56 | integrations.invoke('INTEGRATION_ID', 'myFunction', {
|
57 | query: { foo: 'bar' }
|
58 | })
|
59 | .then(console.log)
|
60 | .catch(console.error)
|
61 | ```
|
62 |
|
63 | ### i18n
|
64 |
|
65 | `@bearer/js` comes with an i18n module that let you deal with internationalization of Bearer's integrations
|
66 |
|
67 | **bearer.i18n.locale**
|
68 |
|
69 | Lets you change the locale
|
70 |
|
71 | ```js
|
72 | bearer.i18n.locale = 'es'
|
73 | ```
|
74 |
|
75 | **bearer.i18n.load**
|
76 |
|
77 | Lets you load custom translation for integrations
|
78 |
|
79 | ```js
|
80 | // with a simple dictionnary
|
81 | const dictionnary = { titles: { welcome: 'Ola!' } }
|
82 | bearer.i18n.load('integration-uuid', dictionnary)
|
83 |
|
84 | // with a promise returning a dictionnary
|
85 | const promiseReturningADictionnary = Promise.new((resolve, reject) => {
|
86 | // async stuff
|
87 | resolve({ titles: { welcome: 'Ola!' } })
|
88 | })
|
89 | bearer.i18n.load('integration-uuid', promiseReturningADictionnary)
|
90 |
|
91 | // for a given locale
|
92 | const dictionnary = { titles: { welcome: 'Guten Morgen' } }
|
93 | bearer.i18n.load('integration-uuid', dictionnary, { locale: 'de' })
|
94 |
|
95 | // for multiple integrations on a single page
|
96 | const dictionnary = {
|
97 | ['integration-one-uuid']: { title: { welcome: 'Hello my friend' } },
|
98 | ['integration-two-uuid']: { message: { goodbye: 'Bye Bye' } }
|
99 | }
|
100 | bearer.i18n.load(null, dictionnary)
|
101 | ```
|
102 |
|
103 | ### Secure
|
104 |
|
105 | If you want to add a level of security, you can switch to the secure mode:
|
106 |
|
107 | ```js
|
108 | window.bearer.secured = true
|
109 | // at the initialisation time
|
110 | window.bearer('clientId', { secured: true })
|
111 | ```
|
112 |
|
113 | Once this mode is turned on, all your values passed in the properties need to be encrypted using your `ENCRYPTION_KEY`.
|
114 |
|
115 | #### CLI
|
116 |
|
117 | Within the CLI, you can use `bearer encrypt` to get the
|
118 |
|
119 | ```js
|
120 | bearer encrypt ENCRYPTION_KEY MESSAGE
|
121 | ```
|
122 |
|
123 | #### NodeJS
|
124 |
|
125 | ```typescript
|
126 | import Cipher from '@bearer/security'
|
127 |
|
128 | const cipher = new Cipher(ENCRYPTION_KEY)
|
129 | cipher.encrypt(MESSAGE)
|
130 | ```
|
131 |
|
132 | ### connect
|
133 |
|
134 | `connect` lets you easily retrieve the `auth-id` for an integration using OAuth authentication. Before using it, you'll need to generate a `setup-id` with the setup component of your integration
|
135 |
|
136 | ```js
|
137 | bearerClient
|
138 | .connect('integration-uuid', 'setup-id')
|
139 | .then(data => {
|
140 | // user has connected himself to the OAuth provider and you now have access to the authId
|
141 | console.log(data.authId)
|
142 | })
|
143 | .catch(() => {
|
144 | // user canceled the authentication
|
145 | })
|
146 | ```
|
147 |
|
148 | you can pass your own `auth-id` within options parameters as follows
|
149 |
|
150 | ```js
|
151 | bearerClient.connect('integration-uuid', 'setup-id', { authId: 'my-own-non-guessable-auth-id' })
|
152 | ```
|
153 |
|
154 | ### init options
|
155 |
|
156 | _Soon_
|