@sinch/sdk-core 0.0.4 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +273 -36
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -2,9 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
This package contains the Sinch Client SDK for Node.js. To use it, you will need a Sinch account. Please [sign up](https://dashboard.sinch.com/signup) or [log in](https://dashboard.sinch.com/login) if you already have one.
|
|
4
4
|
|
|
5
|
-
> <span style="color:red; font-weight:bold">Warning:</span>
|
|
6
|
-
> **This SDK is currently available to selected developers for preview use only. It is being provided for the purpose of collecting feedback, and should not be used in production environments.**
|
|
7
|
-
|
|
8
5
|
## Installation
|
|
9
6
|
|
|
10
7
|
### With NPM
|
|
@@ -30,17 +27,19 @@ As there are different authentication schemes, the initialization method will de
|
|
|
30
27
|
```typescript
|
|
31
28
|
import { SinchClient } from '@sinch/sdk-core';
|
|
32
29
|
|
|
33
|
-
|
|
34
|
-
|
|
30
|
+
(async () => {
|
|
31
|
+
// The credentials can be found on the Account dashboard: https://dashboard.sinch.com/account/access-keys
|
|
32
|
+
const sinch: Pick<SinchClient, 'conversation' | 'fax' | 'numbers' | 'sms'> = new SinchClient({
|
|
35
33
|
projectId: 'my-project-id',
|
|
36
34
|
keyId: 'my-key-id',
|
|
37
35
|
keySecret: 'my-key-secret',
|
|
38
|
-
});
|
|
39
|
-
const numbersService = sinch.numbers;
|
|
40
|
-
|
|
41
|
-
const response = await numbersService.availableRegions.list({
|
|
42
|
-
types: 'LOCAL',
|
|
43
|
-
});
|
|
36
|
+
});
|
|
37
|
+
const numbersService = sinch.numbers;
|
|
38
|
+
|
|
39
|
+
const response = await numbersService.availableRegions.list({
|
|
40
|
+
types: ['LOCAL'],
|
|
41
|
+
});
|
|
42
|
+
})();
|
|
44
43
|
```
|
|
45
44
|
The initialization method above will work for the APIs that supports the authentication with OAuth2 (Numbers and SMS on US and EU regions).
|
|
46
45
|
|
|
@@ -51,17 +50,19 @@ If you want to use the SMS API on the other regions (or US and EU too, it will w
|
|
|
51
50
|
```typescript
|
|
52
51
|
import { SinchClient } from '@sinch/sdk-core';
|
|
53
52
|
|
|
54
|
-
|
|
55
|
-
|
|
53
|
+
(async () => {
|
|
54
|
+
// The credentials can be found on the Service APIs dashboard: https://dashboard.sinch.com/sms/api/services
|
|
55
|
+
const sinch: Pick<SinchClient, 'sms'> = new SinchClient({
|
|
56
56
|
servicePlanId: 'my-service-plan-id',
|
|
57
57
|
apiToken: 'my-key-id',
|
|
58
|
-
|
|
59
|
-
});
|
|
60
|
-
const smsService = sinch.sms;
|
|
61
|
-
|
|
62
|
-
const response = await smsService.batches.get({
|
|
58
|
+
smsRegion: 'my-region', // Optional, can be 'us', 'eu', 'br', 'au', 'ca'. Default is 'us'
|
|
59
|
+
});
|
|
60
|
+
const smsService = sinch.sms;
|
|
61
|
+
|
|
62
|
+
const response = await smsService.batches.get({
|
|
63
63
|
batch_id: '01HF28S9AABBBCCCCY92BJB569',
|
|
64
|
-
});
|
|
64
|
+
});
|
|
65
|
+
})();
|
|
65
66
|
```
|
|
66
67
|
|
|
67
68
|
### Signed application authentication
|
|
@@ -71,18 +72,254 @@ Both `Verification` and `Voice` APIs are using this authentication method: the r
|
|
|
71
72
|
```typescript
|
|
72
73
|
import { SinchClient } from '@sinch/sdk-core';
|
|
73
74
|
|
|
74
|
-
|
|
75
|
-
//
|
|
76
|
-
// https://dashboard.sinch.com/
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
75
|
+
(async () => {
|
|
76
|
+
// The credentials can be found on the Verification or Voice dashboard:
|
|
77
|
+
// https://dashboard.sinch.com/verification/apps or
|
|
78
|
+
// https://dashboard.sinch.com/voice/apps
|
|
79
|
+
const sinch: Pick<SinchClient, 'verification' | 'voice'> = new SinchClient({
|
|
80
|
+
applicationId: 'my-application-key',
|
|
81
|
+
applicationSecret: 'my-application-secret',
|
|
82
|
+
});
|
|
83
|
+
const verificationService = sinch.verification;
|
|
84
|
+
|
|
85
|
+
const response = await verificationService.verificationStatus.getById({
|
|
86
|
+
id: '018bfc3e-1234-5678-1234-ebdb3fd6d30f',
|
|
87
|
+
});
|
|
88
|
+
})();
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Importing classes and interfaces from other API packages
|
|
92
|
+
|
|
93
|
+
For convenience, importing `@sinch/sdk-core` is sufficient to be able to access to all the APIs' classes and interfaces. In case you need to use a single API, they are also packaged as single NPM packages:
|
|
94
|
+
- SMS: [`@sinch/sms`](https://www.npmjs.com/package/@sinch/sms)
|
|
95
|
+
- Conversation: [`@sinch/conversation`](https://www.npmjs.com/package/@sinch/conversation)
|
|
96
|
+
- Fax: [`@sinch/fax`](https://www.npmjs.com/package/@sinch/fax)
|
|
97
|
+
- Numbers: [`@sinch/numbers`](https://www.npmjs.com/package/@sinch/numbers)
|
|
98
|
+
- Verification: [`@sinch/verification`](https://www.npmjs.com/package/@sinch/verification)
|
|
99
|
+
- Voice: [`@sinch/voice`](https://www.npmjs.com/package/@sinch/voice)
|
|
100
|
+
|
|
101
|
+
All the interfaces are exported with an alias, equal to the API name: `Sms` for the SMS API, `Conversation` for the Conversation API, `Fax` for the Fax API and so on.
|
|
102
|
+
|
|
103
|
+
Here is an example about using the TypeScript types to send a fax:
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
import {
|
|
107
|
+
Fax, // "Fax" is the alias under which are exported all the interfaces
|
|
108
|
+
FaxService, // This is a class so it is exported as is
|
|
109
|
+
SinchClient,
|
|
110
|
+
} from '@sinch/sdk-core';
|
|
111
|
+
|
|
112
|
+
(async () => {
|
|
113
|
+
const sinch = new SinchClient({
|
|
114
|
+
projectId: 'my-project-id',
|
|
115
|
+
keyId: 'my-key-id',
|
|
116
|
+
keySecret: 'my-key-secret',
|
|
117
|
+
});
|
|
118
|
+
|
|
119
|
+
const faxService: FaxService = sinch.fax;
|
|
120
|
+
|
|
121
|
+
const requestData: Fax.SendFaxRequestData = {
|
|
122
|
+
sendFaxRequestBody: {
|
|
123
|
+
to: 'a valid destination number',
|
|
124
|
+
from: 'a valid origin number',
|
|
125
|
+
contentUrl: 'https://developers.sinch.com/fax/fax.pdf',
|
|
126
|
+
},
|
|
127
|
+
};
|
|
128
|
+
|
|
129
|
+
const response: Fax.Fax = await faxService.faxes.send(requestData);
|
|
130
|
+
})();
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Importing classes for CommonJS
|
|
134
|
+
|
|
135
|
+
Until now, all the examples in this documentation are showcasing ES modules but there may be some cases when the SDK user will want to use CommonJS instead.
|
|
136
|
+
|
|
137
|
+
Here is an example to do the same as above with CommonJS (using `require`):
|
|
138
|
+
```javascript
|
|
139
|
+
const { SinchClient } = require('@sinch/sdk-core');
|
|
140
|
+
|
|
141
|
+
(async () => {
|
|
142
|
+
const sinch = new SinchClient({
|
|
143
|
+
projectId: 'YOUR_project_id',
|
|
144
|
+
keyId: 'YOUR_access_key',
|
|
145
|
+
keySecret: 'YOUR_access_secret',
|
|
146
|
+
});
|
|
147
|
+
|
|
148
|
+
const faxService = sinch.fax;
|
|
149
|
+
|
|
150
|
+
const requestData = {
|
|
151
|
+
sendFaxRequestBody: {
|
|
152
|
+
to: 'a valid destination number',
|
|
153
|
+
from: 'a valid origin number',
|
|
154
|
+
contentUrl: 'https://developers.sinch.com/fax/fax.pdf',
|
|
155
|
+
},
|
|
156
|
+
};
|
|
157
|
+
|
|
158
|
+
const response = await faxService.faxes.send(requestData);
|
|
159
|
+
})();
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## SinchClient parameters override
|
|
163
|
+
|
|
164
|
+
### Hostname and region override
|
|
165
|
+
|
|
166
|
+
For various reasons (development phase, testing, network restrictions, ...), one may need to update the default API endpoint, pointing to production.
|
|
167
|
+
Each API exposes dedicated parameters to override the default hostname and region:
|
|
168
|
+
|
|
169
|
+
| API Name | Parameter | Region |
|
|
170
|
+
|----------------|------------------------------------|--------------------|
|
|
171
|
+
| Authentication | authHostname | N/A |
|
|
172
|
+
| SMS | smsHostname | smsRegion |
|
|
173
|
+
| Conversation | conversationHostname | conversationRegion |
|
|
174
|
+
| | conversationTemplatesHostname | |
|
|
175
|
+
| Fax | faxHostname | faxRegion |
|
|
176
|
+
| Voice | voiceHostname | voiceRegion |
|
|
177
|
+
| | voiceApplicationManagementHostname | |
|
|
178
|
+
| Numbers | numbersHostname | N/A |
|
|
179
|
+
| Verification | verificationHostname | N/A |
|
|
180
|
+
|
|
181
|
+
And here are the list of supported regions per regionalized API:
|
|
182
|
+
|
|
183
|
+
| Api Name | Supported regions |
|
|
184
|
+
|--------------|---------------------------------------------------------------|
|
|
185
|
+
| SMS | SmsRegion.UNITED_STATES |
|
|
186
|
+
| | SmsRegion.EUROPE |
|
|
187
|
+
| | SmsRegion.BRAZIL (not available for OAuth2 authentication) |
|
|
188
|
+
| | SmsRegion.CANADA (not available for OAuth2 authentication) |
|
|
189
|
+
| | SmsRegion.AUSTRALIA (not available for OAuth2 authentication) |
|
|
190
|
+
| Conversation | ConversationRegion.UNITED_STATES |
|
|
191
|
+
| | ConversationRegion.EUROPE |
|
|
192
|
+
| | ConversationRegion.BRAZIL |
|
|
193
|
+
| Fax | FaxRegion.DEFAULT |
|
|
194
|
+
| | FaxRegion.UNITED_STATES |
|
|
195
|
+
| | FaxRegion.EUROPE |
|
|
196
|
+
| | FaxRegion.SOUTH_AMERICA |
|
|
197
|
+
| | FaxRegion.SOUTHEAST_ASIA_1 |
|
|
198
|
+
| | FaxRegion.SOUTHEAST_ASIA_2 |
|
|
199
|
+
| Voice | VoiceRegion.DEFAULT |
|
|
200
|
+
| | VoiceRegion.UNITED_STATES |
|
|
201
|
+
| | VoiceRegion.EUROPE |
|
|
202
|
+
| | VoiceRegion.SOUTH_AMERICA |
|
|
203
|
+
| | VoiceRegion.SOUTHEAST_ASIA_1 |
|
|
204
|
+
| | VoiceRegion.SOUTHEAST_ASIA_2 |
|
|
205
|
+
|
|
206
|
+
**Use case #1:** overriding the region in production
|
|
207
|
+
|
|
208
|
+
```typescript
|
|
209
|
+
import { SinchClientParameters } from '@sinch/sdk-core';
|
|
210
|
+
|
|
211
|
+
const conversationClientParametersEurope: SinchClientParameters = {
|
|
212
|
+
projectId: 'my-project-id',
|
|
213
|
+
keyId: 'my-key-id',
|
|
214
|
+
keySecret: 'my-key-secret',
|
|
215
|
+
conversationRegion: ConversationRegion.EUROPE,
|
|
216
|
+
};
|
|
217
|
+
```
|
|
218
|
+
**Use case #2:** overriding the hostname
|
|
219
|
+
```typescript
|
|
220
|
+
import { SinchClientParameters } from '@sinch/sdk-core';
|
|
221
|
+
|
|
222
|
+
const conversationClientParametersForTest: SinchClientParameters = {
|
|
223
|
+
projectId: 'my-project-id',
|
|
224
|
+
keyId: 'my-key-id',
|
|
225
|
+
keySecret: 'my-key-secret',
|
|
226
|
+
authHostname: 'http://my-test-server:3000',
|
|
227
|
+
conversationHostname: 'http://my-test-server:3001',
|
|
228
|
+
conversationTemplatesHostname: 'http://my-test-server:3002',
|
|
229
|
+
};
|
|
230
|
+
```
|
|
231
|
+
**Note**: when overriding the hostname, the `region` parameter becomes obsolete and is not taken into account when sending the request.
|
|
232
|
+
|
|
233
|
+
**Note**: The region parameter is permissive: instead of the pre-defined list, you can also set any `string`. This covers the case where a new region is added (in production or in preview) and the SDK is not yet ready to support it or the SDK user doesn't want to update its SDK version to benefit from it.
|
|
234
|
+
```typescript
|
|
235
|
+
import { SinchClientParameters } from '@sinch/sdk-core';
|
|
236
|
+
|
|
237
|
+
const conversationClientParametersNewRegion: SinchClientParameters = {
|
|
238
|
+
projectId: 'my-project-id',
|
|
239
|
+
keyId: 'my-key-id',
|
|
240
|
+
keySecret: 'my-key-secret',
|
|
241
|
+
conversationRegion: 'bzh',
|
|
242
|
+
};
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
On top of that, once you have instantiated an API service, it is possible to override the hostname and the region (in case the API endpoint is regionalized). The services expose the following methods:
|
|
246
|
+
- `setHostname()`
|
|
247
|
+
- `setRegion()`
|
|
248
|
+
|
|
249
|
+
These methods can be used at service level (all the APIs will be updated) or at API domain level (for updating only one at a time):
|
|
250
|
+
|
|
251
|
+
**Use case #1:** overriding the hostname per API domain
|
|
252
|
+
|
|
253
|
+
```typescript
|
|
254
|
+
import { SinchClient } from '@sinch/sdk-core';
|
|
255
|
+
|
|
256
|
+
const sinch: SinchClient = new SinchClient({
|
|
257
|
+
projectId: 'my-project-id',
|
|
258
|
+
keyId: 'my-key-id',
|
|
259
|
+
keySecret: 'my-key-secret',
|
|
80
260
|
});
|
|
81
|
-
const
|
|
261
|
+
const numbersService = sinch.numbers;
|
|
262
|
+
numbersService.setHostname('https://my.new.server');
|
|
263
|
+
numbersService.activeNumber.setHostname('https://my.other.server');
|
|
264
|
+
// Result:
|
|
265
|
+
// numbers.availableRegions -> https://my.new.server
|
|
266
|
+
// numbers.availableNumber -> https://my.new.server
|
|
267
|
+
// numbers.activeNumber -> https://my.other.server
|
|
268
|
+
// numbers.callbacks -> https://my.new.server
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
**Use case #2:** overriding the production region per API domain
|
|
272
|
+
import { SinchClient } from '@sinch/sdk-core';
|
|
273
|
+
|
|
274
|
+
```typescript
|
|
275
|
+
import { SinchClient, VoiceRegion } from '@sinch/sdk-core';
|
|
276
|
+
|
|
277
|
+
const sinch: SinchClient = new SinchClient({
|
|
278
|
+
projectId: 'my-project-id',
|
|
279
|
+
keyId: 'my-key-id',
|
|
280
|
+
keySecret: 'my-key-secret',
|
|
281
|
+
});
|
|
282
|
+
const voiceService = sinch.voice;
|
|
283
|
+
voiceService.setRegion(VoiceRegion.SOUTH_AMERICA);
|
|
284
|
+
voiceService.calls.setRegion(VoiceRegion.SOUTHEAST_ASIA_2);
|
|
285
|
+
// Result:
|
|
286
|
+
// voice.applications -> https://callingapi.sinch.com (This one is not regionalized !)
|
|
287
|
+
// voice.conferences -> https://calling-sae1.api.sinch.com
|
|
288
|
+
// voice.calls -> https://calling-apse2.api.sinch.com
|
|
289
|
+
// voice.callouts -> https://calling-sae1.api.sinch.com
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### Request and response plugins addition
|
|
293
|
+
|
|
294
|
+
When instantiating a service, it creates an ApiClient behind the scene (find more in the [@sinch/sdk-client](../sdk-client/README.md) package) which contains some default plugins:
|
|
295
|
+
- request plugins: `VersionRequest` which will add a `user-agent` with the used version of the SDK and Node.js running the program
|
|
296
|
+
- response plugins:
|
|
297
|
+
- `TimezonePlugin` which will ensure that all the dates returned by the server contain a timezone
|
|
298
|
+
- `ExceptionPlugin` which will catch all invalid response from the server and format them in a common way to handle exceptions
|
|
299
|
+
|
|
300
|
+
On top of that, the Service will add its own plugins:
|
|
301
|
+
- for OAuth2 authentication: `Oauth2TokenRequest`
|
|
302
|
+
- for API Token authentication: `ApiTokenRequest`
|
|
303
|
+
- for Application Signed authentication: `XTimestampRequest` and `SigningRequest`
|
|
304
|
+
|
|
305
|
+
And on top on these plugins, it is possible to add even more of them (existing ones or custom ones) with the following properties of the `SinchClientParameters`:
|
|
306
|
+
- `requestPlugins`
|
|
307
|
+
- `responsePlugins`
|
|
308
|
+
|
|
309
|
+
```typescript
|
|
310
|
+
import { SinchClient, AdditionalHeadersRequest, buildHeader } from '@sinch/sdk-core';
|
|
82
311
|
|
|
83
|
-
const
|
|
84
|
-
|
|
312
|
+
const sinch: SinchClient = new SinchClient({
|
|
313
|
+
projectId: 'my-project-id',
|
|
314
|
+
keyId: 'my-key-id',
|
|
315
|
+
keySecret: 'my-key-secret',
|
|
316
|
+
requestPlugins: [
|
|
317
|
+
new AdditionalHeadersRequest({
|
|
318
|
+
headers: buildHeader('customHeader', 'customHeaderValue'),
|
|
319
|
+
}),
|
|
320
|
+
],
|
|
85
321
|
});
|
|
322
|
+
// => All the requests using services registered on this SinchClient will send an extra-header
|
|
86
323
|
```
|
|
87
324
|
|
|
88
325
|
## Examples
|
|
@@ -95,11 +332,11 @@ Developer Experience team: [devexp@sinch.com](mailto:devexp@sinch.com)
|
|
|
95
332
|
|
|
96
333
|
Here is the list of the Sinch API and there level of support by the Node.js SDK:
|
|
97
334
|
|
|
98
|
-
| API Category | API Name
|
|
99
|
-
|
|
100
|
-
| Messaging | SMS API
|
|
101
|
-
| | Conversation API
|
|
102
|
-
| | Fax API
|
|
103
|
-
| Voice and Video | Voice API
|
|
104
|
-
| Numbers & Connectivity | Numbers API
|
|
105
|
-
| Verification | Verification API
|
|
335
|
+
| API Category | API Name | Status |
|
|
336
|
+
|------------------------|------------------|:------:|
|
|
337
|
+
| Messaging | SMS API | ✅ |
|
|
338
|
+
| | Conversation API | ✅ |
|
|
339
|
+
| | Fax API | ✅ |
|
|
340
|
+
| Voice and Video | Voice API | ✅ |
|
|
341
|
+
| Numbers & Connectivity | Numbers API | ✅ |
|
|
342
|
+
| Verification | Verification API | ✅ |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sinch/sdk-core",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"description": "Node.js client for the Sinch API platform",
|
|
5
5
|
"homepage": "",
|
|
6
6
|
"repository": {
|
|
@@ -29,12 +29,12 @@
|
|
|
29
29
|
"compile": "tsc --build --verbose"
|
|
30
30
|
},
|
|
31
31
|
"dependencies": {
|
|
32
|
-
"@sinch/conversation": "^0.0
|
|
33
|
-
"@sinch/fax": "^0.0
|
|
34
|
-
"@sinch/numbers": "^0.0
|
|
35
|
-
"@sinch/sms": "^0.0
|
|
36
|
-
"@sinch/verification": "^0.0
|
|
37
|
-
"@sinch/voice": "^0.0
|
|
32
|
+
"@sinch/conversation": "^1.0.0",
|
|
33
|
+
"@sinch/fax": "^1.0.0",
|
|
34
|
+
"@sinch/numbers": "^1.0.0",
|
|
35
|
+
"@sinch/sms": "^1.0.0",
|
|
36
|
+
"@sinch/verification": "^1.0.0",
|
|
37
|
+
"@sinch/voice": "^1.0.0"
|
|
38
38
|
},
|
|
39
39
|
"devDependencies": {},
|
|
40
40
|
"publishConfig": {
|