From 24fc0b161b61d51895fc88520f21936b49778b1c Mon Sep 17 00:00:00 2001 From: Chuck MANCHUCK Reeves Date: Thu, 19 Oct 2023 14:58:09 +0000 Subject: [PATCH] docs: adding relase log --- RELEASES.md | 195 ++++++++++++++++++ packages/accounts/__tests__/accounts.test.ts | 33 ++- packages/accounts/__tests__/secrets.test.ts | 52 ++--- packages/accounts/lib/accounts.ts | 88 +++++--- packages/accounts/lib/index.ts | 5 +- .../lib/interfaces/AccountCallbacks.ts | 4 - .../interfaces/Response/APISecretResponse.ts | 9 - .../Response/AccountUpdateResponse.ts | 7 - .../interfaces/Response/GetBalanceResponse.ts | 4 - .../Response/ListAPISecretsResponse.ts | 12 -- .../Response/TopUpBalanceResponse.ts | 4 - packages/accounts/lib/secrets.ts | 109 +++++++--- .../accounts/lib/types/AccountCallbacks.ts | 28 +++ .../lib/types/Response/APISecretResponse.ts | 23 +++ .../types/Response/AccountUpdateResponse.ts | 37 ++++ .../lib/types/Response/GetBalanceResponse.ts | 14 ++ .../types/Response/ListAPISecretsResponse.ts | 28 +++ .../types/Response/TopUpBalanceResponse.ts | 22 ++ packages/accounts/lib/types/Response/index.ts | 5 + packages/accounts/lib/types/index.ts | 2 + packages/accounts/package.json | 16 +- packages/accounts/tsconfig.json | 35 ++-- packages/accounts/typedoc.json | 6 + 23 files changed, 578 insertions(+), 160 deletions(-) create mode 100644 RELEASES.md delete mode 100644 packages/accounts/lib/interfaces/AccountCallbacks.ts delete mode 100644 packages/accounts/lib/interfaces/Response/APISecretResponse.ts delete mode 100644 packages/accounts/lib/interfaces/Response/AccountUpdateResponse.ts delete mode 100644 packages/accounts/lib/interfaces/Response/GetBalanceResponse.ts delete mode 100644 packages/accounts/lib/interfaces/Response/ListAPISecretsResponse.ts delete mode 100644 packages/accounts/lib/interfaces/Response/TopUpBalanceResponse.ts create mode 100644 packages/accounts/lib/types/AccountCallbacks.ts create mode 100644 packages/accounts/lib/types/Response/APISecretResponse.ts create mode 100644 packages/accounts/lib/types/Response/AccountUpdateResponse.ts create mode 100644 packages/accounts/lib/types/Response/GetBalanceResponse.ts create mode 100644 packages/accounts/lib/types/Response/ListAPISecretsResponse.ts create mode 100644 packages/accounts/lib/types/Response/TopUpBalanceResponse.ts create mode 100644 packages/accounts/lib/types/Response/index.ts create mode 100644 packages/accounts/lib/types/index.ts create mode 100644 packages/accounts/typedoc.json diff --git a/RELEASES.md b/RELEASES.md new file mode 100644 index 00000000..37f7cd44 --- /dev/null +++ b/RELEASES.md @@ -0,0 +1,195 @@ +--- +version: '3.1.1' +release: '2 Mar 2023' +id: vonage-node-sdk +title: 'vonage-node-sdk' +icon: 'node-color' +pkgName: 'Node SDK' +--- + +# Changelog + +All notable changes to this project will be documented in this file. + + +## 3.1.1 + +### Features + +* Ported Audit and Redact packages from Node Server SDK v2. +* Introduced async auth handlers. +* Added simple search for Numbers. +* Added Verify v2. +* Added Video experience composer, captions, audio connector, ACL for JWT generator, SIP and DTMF playing. + +### Bug Fixes + +- Reverts back to ES6 and CommonJS for better Node compatibility. +- Improved response types for Verify v1. +- Fixed wrong case for Messages API parameters. +- Corrected our return types when sending SMS. +- Allowed no filter when getting owned numbers, added required filter when searching available numbers. +- Allowed features to be searched in available numbers. + +Full Changelog: [https://github.com/Vonage/vonage-node-sdk/compare/@vonage/server-sdk@3.0.11...@vonage/server-sdk@3.1.1](https://github.com/Vonage/vonage-node-sdk/compare/@vonage/server-sdk@3.0.11...@vonage/server-sdk@3.1.1) + + +## 3.0.11 + +### Features + +- Added auth docs. +- Fixed readme for all products available. + +Full Changelog: [https://github.com/Vonage/vonage-node-sdk/compare/@vonage/server-sdk@3.0.1...@vonage/server-sdk@3.0.11](https://github.com/Vonage/vonage-node-sdk/compare/@vonage/server-sdk@3.0.1...@vonage/server-sdk@3.0.11) + + +## 3.0.1 + +### Features + +- Added verify and voice. + +### Bug Fixes + +- Fixed a few typos in Number Insights. + +[https://github.com/Vonage/vonage-node-sdk/compare/@vonage/server-sdk@3.0.0...@vonage/server-sdk@3.0.10](https://github.com/Vonage/vonage-node-sdk/compare/@vonage/server-sdk@3.0.1...@vonage/server-sdk@3.0.0) + + +## 3.0.0 + +>This version is a complete rewrite of version 2. Written in Typescript and broken out into smaller packages to reduce package size. Callbacks have been removed, and most functions will take in param objects instead of using positional params. SMS and Messages have been broken out to mirror the API. + +You can find migration guides for each package here: + +- [Accounts](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/accounts/v2_TO_v3_MIGRATION_GUIDE.md) +- [Applications](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/applications/v2_TO_v3_MIGRATION_GUIDE.md) +- [Messages](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/messages/v2_TO_v3_MIGRATION_GUIDE.md) +- [Number Insights](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/number-insights/v2_TO_v3_MIGRATION_GUIDE.md) +- [Numbers](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/numbers/v2_TO_v3_MIGRATION_GUIDE.md) +- [Pricing](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/pricing/v2_TO_v3_MIGRATION_GUIDE.md) +- [SMS](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/sms/v2_TO_v3_MIGRATION_GUIDE.md) +- [Verify](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/verify/v2_TO_v3_MIGRATION_GUIDE.md) +- [Voice](https://github.com/Vonage/vonage-node-sdk/blob/3.x/packages/voice/v2_TO_v3_MIGRATION_GUIDE.md) + + +## 2.11.2 + + - Corrected the issue where downloading a voice recording transcript would throw an exception. + + +## 2.11.0 + +- Added support for the Messages API v1.0 + + +## 2.10.1 + +### Updated + +* Corrected license information. + + +## 2.10.0 + +>This version serves as the change from the Nexmo namespace to the Vonage namespace. The module now resides on NPM as `@vonage/server-sdk`. Prior versions under the Nexmo namespace will remain in maintenance mode for the next 12 months and receive bug and security fixes. All new functionality will only be added to the @vonage namespace. + +### Updated + +- Migrated SDK module from `nexmo` to `@vonage/server-sdk`. + + +## 2.9.1 + +* Fixed: TypeError: Nexmo is not a constructor. + + +## 2.9.0 + +* FIXED: #295 - Nexmo constructor changes of the given options object +* ADDED: Optional `target_api_key` parameter for the `number.buy()` and `number.cancel()` methods. +* ADDED: Typings for Messages API +* UPDATED: Private Key strings now replace `\n` with newlines for easier usage in environment variables. + +## 2.8.0 + +* ADDED: Support for Verify PSD2 requests via `nexmo.verify.psd2()`. + +## 2.7.0 + +* ADDED: Made `apiKey` and `apiSecret` optional when `applicationId` and `privateKey` are present in the Nexmo constructor. + +## 2.6.0 + +* ADDED: Change host via the config object, using `apiHost` & `restHost` + +## 2.5.3 + +* FIXED: URI Encode Signed SMS Message + +## 2.5.2 + +* ADDED: Pricing API support + +## 2.5.1 + +* ADDED: typings for Verify API +* ADDED: Applications API V2 support + +## 2.4.2 + +* Added message signing for sending SMS +* Added `Nexmo.generateSignature` to verify signed messages + +## 2.0.1 + +* FIXED: #116 - default setting of `retry-after` for 429 HTTP status code responses + +## 2.0.0 + +* FIXED: #110 - check the `statusCode` on the response +* FIXED: #114 - handle 429 HTTP status codes +* UPDATED: To allow errors to be programmatically useful the `error` callback objects has been updated to `{statusCode: STATUS_CODE, body: JSON_BODY, headers: HEADERS}` + +## 1.2.0 + +* ADDED: Add File API to the library. `nexmo.files.get` and `nexmo.files.save`. + +## 1.1.2 + +* Fixed: Bug #104 - Fix JSON parsing error + +## 1.1.1 + +* UPDATED: Changed User Agent format to match other libraries +* FIXED: Bug #88 - Undefined method when missing `method` declaration + +## 1.1.0 + +* ADDED: `nexmo.generateJwt` to generate JWT based on instance credentials +* ADDED: `Nexmo.generateJwt` static function to generate JWT + +## [1.0.0] + +* ADDED: `applicationId` and `privateKey` properties to the first constructor parameter to support JWT generation. +* ADDED: `options.logger` to constructor 2nd parameter to allow adding customer logger. +* ADDED: `options.appendToUserAgent` to constructor 2nd parameter to append a custom string to `User-Agent` header sent to Nexmo. +* ADDED: nexmo.calls adding support to `create`, `get`, `update` and `delete` calls. +* ADDED: nexmo.applications adding support to `create`, `get`, `update` and `delete` calls. +* ADDED: Functionality is now namespaced: + * `nexmo.message` + * `nexmo.calls` + * `nexmo.number` + * `nexmo.verify` + * `nexmo.numberInsight` + * `nexmo.account` + * `nexmo.voice` - legacy voice functionality +* CHANGED: `var Nexmo = require('nexmo');` returns a class definition which should be created using the `new` operator e.g. `var nexmo = new Nexmo(args...);`. +* REMOVED: `var nexmo = require('nexmo');` no longer exposes singleton functions offered by "easynexmo". + +## Pre 1.0.0 + +Earlier versions of this library were published as "easynexmo". The "easynexmo" package is now deprecated. + +[1.0.0]: https://github.com/Nexmo/nexmo-node/tree/v1.0.0 diff --git a/packages/accounts/__tests__/accounts.test.ts b/packages/accounts/__tests__/accounts.test.ts index 46abd7f2..d92eba35 100644 --- a/packages/accounts/__tests__/accounts.test.ts +++ b/packages/accounts/__tests__/accounts.test.ts @@ -1,22 +1,22 @@ import nock from 'nock'; -import { Accounts } from '../lib/index' +import { Accounts } from '../lib/index'; import { Auth } from '@vonage/auth'; describe('accounts', () => { let client; beforeEach(() => { - client = new Accounts(new Auth({ apiKey: 'abcd', apiSecret: '1234' })); + client = new Accounts(new Auth({ apiKey: 'abcd', apiSecret: '1234' })); }); afterEach(() => { - client = null; + client = null; }); test("get balance", async () => { const expectedResponse = { "value": 10.28, - "autoReload": false + "autoReload": false, }; nock("https://rest.nexmo.com") @@ -33,7 +33,7 @@ describe('accounts', () => { test("top up balance", async () => { const expectedResponse = { "error-code": "200", - "error-code-label": "success" + "error-code-label": "success", }; nock("https://rest.nexmo.com") @@ -42,9 +42,13 @@ describe('accounts', () => { .query({ api_key: 'abcd', api_secret: '1234' }) .reply(200, expectedResponse); - const lookup = await client.topUpBalance('8ef2447e69604f642ae59363aa5f781b'); + const lookup = await client.topUpBalance( + '8ef2447e69604f642ae59363aa5f781b', + ); expect(lookup['error-code']).toEqual(expectedResponse['error-code']); - expect(lookup['error-code-label']).toEqual(expectedResponse['error-code-label']); + expect( + lookup['error-code-label'], + ).toEqual(expectedResponse['error-code-label']); }); test("update callbacks", async () => { @@ -53,10 +57,13 @@ describe('accounts', () => { "dr-callback-url": "https://example.com/webhooks/delivery-receipt", "max-outbound-request": 30, "max-inbound-request": 30, - "max-calls-per-second": 30 + "max-calls-per-second": 30, }; - const callbacks = {moCallBackUrl: "https://example.com/webhooks/inbound-sms", drCallBackUrl: "https://example.com/webhooks/delivery-receipt"}; + const callbacks = { + moCallBackUrl: "https://example.com/webhooks/inbound-sms", + drCallBackUrl: "https://example.com/webhooks/delivery-receipt", + }; const queryString = new URLSearchParams(callbacks); const re = new RegExp(queryString.toString(), "g"); @@ -67,7 +74,11 @@ describe('accounts', () => { .reply(200, expectedResponse); const lookup = await client.updateAccountCallbacks(callbacks); - expect(lookup['mo-callback-url']).toEqual(expectedResponse['mo-callback-url']); - expect(lookup['dr-callback-url']).toEqual(expectedResponse['dr-callback-url']); + expect( + lookup['mo-callback-url'], + ).toEqual(expectedResponse['mo-callback-url']); + expect( + lookup['dr-callback-url'], + ).toEqual(expectedResponse['dr-callback-url']); }); }); diff --git a/packages/accounts/__tests__/secrets.test.ts b/packages/accounts/__tests__/secrets.test.ts index 6af2e0b3..07e2c60f 100644 --- a/packages/accounts/__tests__/secrets.test.ts +++ b/packages/accounts/__tests__/secrets.test.ts @@ -1,41 +1,41 @@ import nock from 'nock'; -import { Secrets } from '../lib/index' +import { Secrets } from '../lib/index'; import { Auth } from '@vonage/auth'; describe('secrets', () => { let client; beforeEach(() => { - client = new Secrets(new Auth({ apiKey: 'abcd', apiSecret: '1234' })); + client = new Secrets(new Auth({ apiKey: 'abcd', apiSecret: '1234' })); }); afterEach(() => { - client = null; + client = null; }); test("list secrets", async () => { const expectedResponse = { "_links": { "self": { - "href": "abc123" - } + "href": "abc123", + }, }, "_embedded": { "secrets": [ { "_links": { "self": { - "href": "abc123" - } + "href": "abc123", + }, }, "id": "ad6dc56f-07b5-46e1-a527-85530e625800", - "created_at": "2017-03-02T16:34:49Z" - } - ] - } + "created_at": "2017-03-02T16:34:49Z", + }, + ], + }, }; - nock("https://api.nexmo.com", {reqheaders: {'Authorization': 'Basic YWJjZDoxMjM0'} }) + nock("https://api.nexmo.com", { reqheaders: { 'Authorization': 'Basic YWJjZDoxMjM0' } }) .persist() .get('/accounts/abcd/secrets') .reply(200, expectedResponse); @@ -49,16 +49,16 @@ describe('secrets', () => { const expectedResponse = { "_links": { "self": { - "href": "abc123" - } + "href": "abc123", + }, }, "id": "ad6dc56f-07b5-46e1-a527-85530e625800", - "created_at": "2017-03-02T16:34:49Z" + "created_at": "2017-03-02T16:34:49Z", }; - nock("https://api.nexmo.com", {reqheaders: {'Authorization': 'Basic YWJjZDoxMjM0'} }) + nock("https://api.nexmo.com", { reqheaders: { 'Authorization': 'Basic YWJjZDoxMjM0' } }) .persist() - .post('/accounts/abcd/secrets', {secret: 'te5ts3cret!'}) + .post('/accounts/abcd/secrets', { secret: 'te5ts3cret!' }) .reply(200, expectedResponse); const lookup = await client.createSecret('abcd', 'te5ts3cret!'); @@ -71,30 +71,34 @@ describe('secrets', () => { const expectedResponse = { "_links": { "self": { - "href": "abc123" - } + "href": "abc123", + }, }, "id": "ad6dc56f-07b5-46e1-a527-85530e625800", - "created_at": "2017-03-02T16:34:49Z" + "created_at": "2017-03-02T16:34:49Z", }; - nock("https://api.nexmo.com", {reqheaders: {'Authorization': 'Basic YWJjZDoxMjM0'} }) + nock("https://api.nexmo.com", { reqheaders: { 'Authorization': 'Basic YWJjZDoxMjM0' } }) .persist() .get('/accounts/abcd/secrets/ad6dc56f-07b5-46e1-a527-85530e625800') .reply(200, expectedResponse); - const lookup = await client.getSecret('abcd', 'ad6dc56f-07b5-46e1-a527-85530e625800'); + const lookup = await client.getSecret( + 'abcd', + 'ad6dc56f-07b5-46e1-a527-85530e625800', + ); expect(lookup._links).toEqual(expectedResponse._links); expect(lookup.id).toEqual(expectedResponse.id); expect(lookup.created_at).toEqual(expectedResponse.created_at); }); - test("get a secret", async () => { - nock("https://api.nexmo.com", {reqheaders: {'Authorization': 'Basic YWJjZDoxMjM0'} }) + test("delete a secret", async () => { + nock("https://api.nexmo.com", { reqheaders: { 'Authorization': 'Basic YWJjZDoxMjM0' } }) .persist() .delete('/accounts/abcd/secrets/ad6dc56f-07b5-46e1-a527-85530e625800') .reply(204); await client.deleteSecret('abcd', 'ad6dc56f-07b5-46e1-a527-85530e625800'); + expect(nock.isDone()).toBeTruthy(); }); }); diff --git a/packages/accounts/lib/accounts.ts b/packages/accounts/lib/accounts.ts index fcb3ea78..978782d4 100644 --- a/packages/accounts/lib/accounts.ts +++ b/packages/accounts/lib/accounts.ts @@ -1,35 +1,65 @@ -import { AuthenticationType, Client } from '@vonage/server-client' -import { AccountCallbacks } from './interfaces/AccountCallbacks' -import { AccountUpdateResponse } from './interfaces/Response/AccountUpdateResponse' -import { GetBalanceResponse } from './interfaces/Response/GetBalanceResponse' -import { TopUpBalanceResponse } from './interfaces/Response/TopUpBalanceResponse' +import { AuthenticationType, Client } from '@vonage/server-client'; +import { + AccountCallbacks, + AccountUpdateResponse, + GetBalanceResponse, + TopUpBalanceResponse, +} from './types'; +/** + * Class representing the Vonage Account API which enables users to manage + * their Vonage API Account programmatically. + * For more information, see: https://developer.nexmo.com/en/account/overview. + * @extends {Client} + */ export class Accounts extends Client { - protected authType = AuthenticationType.QUERY_KEY_SECRET + /** + * @see {@link Client.authType} + */ + public authType = AuthenticationType.QUERY_KEY_SECRET; - public async getBalance(): Promise { - const response = await this.sendGetRequest( - `${this.config.restHost}/account/get-balance` - ) - return response.data - } + /** + * Retrieves the current balance of the Vonage API account. + * @see {@link https://rest.nexmo.com/account/get-balance} + * @return {Promise} The current balance of the account in EUR. + */ + public async getBalance(): Promise { + const response = await this.sendGetRequest( + `${this.config.restHost}/account/get-balance`, + ); + return response.data; + } - public async topUpBalance(trx: string): Promise { - const response = await this.sendFormSubmitRequest( - `${this.config.restHost}/account/top-up`, - { trx } - ) - return response.data - } + /** + * Tops up the account balance when auto-reload is enabled. + * The top-up amount corresponds to the amount added when auto-reload was enabled. + * @see {@link https://rest.nexmo.com/account/top-up} + * @param {string} trx - The transaction reference for the balance addition and auto-reload activation. + * @return {Promise} Response indicating the success of the operation. + */ + public async topUpBalance(trx: string): Promise { + const response = await this.sendFormSubmitRequest( + `${this.config.restHost}/account/top-up`, + { trx }, + ); + return response.data; + } - public async updateAccountCallbacks( - callbacks: AccountCallbacks - ): Promise { - const response = - await this.sendFormSubmitRequest( - `${this.config.restHost}/account/settings`, - callbacks - ) - return response.data - } + /** + * Updates the default webhook URLs associated with the account for: + * - Inbound SMS messages + * - Delivery receipts + * @see {@link https://rest.nexmo.com/account/settings} + * @param {AccountCallbacks} callbacks - The new callback URLs for the account. + * @return {Promise} Details of the updated or current settings. + */ + public async updateAccountCallbacks( + callbacks: AccountCallbacks, + ): Promise { + const response = await this.sendFormSubmitRequest( + `${this.config.restHost}/account/settings`, + callbacks as Record, + ); + return response.data; + } } diff --git a/packages/accounts/lib/index.ts b/packages/accounts/lib/index.ts index 6665af00..a338f08d 100644 --- a/packages/accounts/lib/index.ts +++ b/packages/accounts/lib/index.ts @@ -1,2 +1,3 @@ -export { Accounts } from './accounts' -export { Secrets } from './secrets' +export { Accounts } from './accounts'; +export { Secrets } from './secrets'; +export * from './types'; diff --git a/packages/accounts/lib/interfaces/AccountCallbacks.ts b/packages/accounts/lib/interfaces/AccountCallbacks.ts deleted file mode 100644 index 54d1a848..00000000 --- a/packages/accounts/lib/interfaces/AccountCallbacks.ts +++ /dev/null @@ -1,4 +0,0 @@ -export interface AccountCallbacks { - moCallBackUrl?: string - drCallBackUrl?: string -} diff --git a/packages/accounts/lib/interfaces/Response/APISecretResponse.ts b/packages/accounts/lib/interfaces/Response/APISecretResponse.ts deleted file mode 100644 index 92c546f8..00000000 --- a/packages/accounts/lib/interfaces/Response/APISecretResponse.ts +++ /dev/null @@ -1,9 +0,0 @@ -export interface APISecretResponse { - _links: { - self: { - href: string - } - } - id: string - created_at: string -} diff --git a/packages/accounts/lib/interfaces/Response/AccountUpdateResponse.ts b/packages/accounts/lib/interfaces/Response/AccountUpdateResponse.ts deleted file mode 100644 index e287c0d4..00000000 --- a/packages/accounts/lib/interfaces/Response/AccountUpdateResponse.ts +++ /dev/null @@ -1,7 +0,0 @@ -export interface AccountUpdateResponse { - 'mo-callback-url': string - 'dr-callback-url': string - 'max-outbound-request': number - 'max-inbound-request': number - 'max-calls-per-second': number -} diff --git a/packages/accounts/lib/interfaces/Response/GetBalanceResponse.ts b/packages/accounts/lib/interfaces/Response/GetBalanceResponse.ts deleted file mode 100644 index f49f8740..00000000 --- a/packages/accounts/lib/interfaces/Response/GetBalanceResponse.ts +++ /dev/null @@ -1,4 +0,0 @@ -export interface GetBalanceResponse { - value: number - autoReload: boolean -} diff --git a/packages/accounts/lib/interfaces/Response/ListAPISecretsResponse.ts b/packages/accounts/lib/interfaces/Response/ListAPISecretsResponse.ts deleted file mode 100644 index af109b0d..00000000 --- a/packages/accounts/lib/interfaces/Response/ListAPISecretsResponse.ts +++ /dev/null @@ -1,12 +0,0 @@ -import { APISecretResponse } from './APISecretResponse' - -export interface ListAPISecretsResponse { - _links: { - self: { - href: string - } - } - _embedded: { - secrets: APISecretResponse[] - } -} diff --git a/packages/accounts/lib/interfaces/Response/TopUpBalanceResponse.ts b/packages/accounts/lib/interfaces/Response/TopUpBalanceResponse.ts deleted file mode 100644 index 5617626d..00000000 --- a/packages/accounts/lib/interfaces/Response/TopUpBalanceResponse.ts +++ /dev/null @@ -1,4 +0,0 @@ -export interface TopUpBalanceResponse { - 'error-code': string - 'error-code-label': string -} diff --git a/packages/accounts/lib/secrets.ts b/packages/accounts/lib/secrets.ts index 9e9463b6..96c8afe7 100644 --- a/packages/accounts/lib/secrets.ts +++ b/packages/accounts/lib/secrets.ts @@ -1,41 +1,82 @@ -import { AuthenticationType, Client } from '@vonage/server-client' -import { APISecretResponse } from './interfaces/Response/APISecretResponse' -import { ListAPISecretsResponse } from './interfaces/Response/ListAPISecretsResponse' +import { AuthenticationType, Client } from '@vonage/server-client'; +import { APISecretResponse, ListAPISecretsResponse } from './types'; +/** + * The `Secrets` class provides methods to manage API secrets using the Vonage API. + */ export class Secrets extends Client { - protected authType = AuthenticationType.BASIC + public authType = AuthenticationType.BASIC; - public async createSecret( - apiKey: string, - secret: string - ): Promise { - const response = await this.sendPostRequest( - `${this.config.apiHost}/accounts/${apiKey}/secrets`, - { secret } - ) - return response.data - } + /** + * Create a new API secret for a given API key. + * + * @param {string} apiKey - The API key to manage secrets for. + * @param {string} secret - The new secret. It must follow the provided rules: + * - Minimum 8 characters. + * - Maximum 25 characters. + * - At least 1 lowercase character. + * - At least 1 uppercase character. + * - At least 1 digit. + * + * @return {Promise} A promise that resolves to an object representing the created API secret. + * + * @example + * const result = await createSecret('your_api_key', 'example-4PI-secret'); + */ + public async createSecret( + apiKey: string, + secret: string, + ): Promise { + const response = await this.sendPostRequest( + `${this.config.apiHost}/accounts/${apiKey}/secrets`, + { secret }, + ); + return response.data; + } - public async deleteSecret(apiKey: string, id: string): Promise { - await this.sendDeleteRequest( - `${this.config.apiHost}/accounts/${apiKey}/secrets/${id}` - ) - } + /** + * Revoke (delete) an existing API secret for a given API key. + * + * @param {string} apiKey - The API key to manage secrets for. + * @param {string} id - The ID of the API secret to revoke. + * + * @return {Promise} A promise that resolves when the secret has been revoked. + */ + public async deleteSecret(apiKey: string, id: string): Promise { + await this.sendDeleteRequest( + `${this.config.apiHost}/accounts/${apiKey}/secrets/${id}`, + ); + } - public async getSecret( - apiKey: string, - id: string - ): Promise { - const response = await this.sendGetRequest( - `${this.config.apiHost}/accounts/${apiKey}/secrets/${id}` - ) - return response.data - } + /** + * Retrieve the details of a specific API secret for a given API key. + * + * @param {string} apiKey - The API key to manage secrets for. + * @param {string} id - The ID of the API secret to retrieve. + * + * @return {Promise} A promise that resolves to an object representing the API secret. + */ + public async getSecret( + apiKey: string, + id: string, + ): Promise { + const response = await this.sendGetRequest( + `${this.config.apiHost}/accounts/${apiKey}/secrets/${id}`, + ); + return response.data; + } - public async listSecrets(apiKey: string): Promise { - const response = await this.sendGetRequest( - `${this.config.apiHost}/accounts/${apiKey}/secrets` - ) - return response.data - } + /** + * List all the secrets associated with a particular API key. + * + * @param {string} apiKey - The API key for which to list secrets. + * + * @return {Promise} A promise that resolves to an object containing a list of API secrets. + */ + public async listSecrets(apiKey: string): Promise { + const response = await this.sendGetRequest( + `${this.config.apiHost}/accounts/${apiKey}/secrets`, + ); + return response.data; + } } diff --git a/packages/accounts/lib/types/AccountCallbacks.ts b/packages/accounts/lib/types/AccountCallbacks.ts new file mode 100644 index 00000000..e6eb645f --- /dev/null +++ b/packages/accounts/lib/types/AccountCallbacks.ts @@ -0,0 +1,28 @@ +/** + * Represents the callbacks associated with an account. + */ +export type AccountCallbacks = { + /** + * The default webhook URL for inbound SMS. If an SMS is received at a Vonage + * number that does not have its own inboud SMS webhook configured, Vonage + * makes a request here. + * + * @remarks + * + * Send an empty string to unset this value. + * + * @example https://example.com/webhooks/inbound-sms + */ + moCallBackUrl?: string; + + /** + * The webhook URL that Vonage makes a request to when a + * delivery receipt is available for an SMS sent by one of your Vonage numbers. + * + * @remarks + * Send an empty string to unset this value. + * + * @example https://example.com/webhooks/delivery-receipt + */ + drCallBackUrl?: string; +} diff --git a/packages/accounts/lib/types/Response/APISecretResponse.ts b/packages/accounts/lib/types/Response/APISecretResponse.ts new file mode 100644 index 00000000..c7951f87 --- /dev/null +++ b/packages/accounts/lib/types/Response/APISecretResponse.ts @@ -0,0 +1,23 @@ +import { APILinks } from '@vonage/server-client'; + +/** + * Represents the response structure for an individual API secret. + * + * @remarks + * Many of the Vonage APIs are accessed using an API key and secret. It is recommended to manage + * and occasionally rotate these secrets for security purposes. This structure provides details + * for a single API secret. + * + * @see {@link APILinks} + */ +export type APISecretResponse = APILinks & { + /** + * The unique identifier for the API secret. + */ + id: string; + + /** + * The timestamp indicating when the API secret was created. + */ + created_at: string; +} diff --git a/packages/accounts/lib/types/Response/AccountUpdateResponse.ts b/packages/accounts/lib/types/Response/AccountUpdateResponse.ts new file mode 100644 index 00000000..3304b6e6 --- /dev/null +++ b/packages/accounts/lib/types/Response/AccountUpdateResponse.ts @@ -0,0 +1,37 @@ +/** + * Represents the response structure when updating account settings. + * + * @remarks + * Settings were updated if supplied; the details of the current settings are included in the response. + */ +export type AccountUpdateResponse = { + /** + * The current or updated inbound message webhook URI. + * @example https://example.com/webhooks/inbound-sms + */ + 'mo-callback-url': string; + + /** + * The current or updated delivery receipt webhook URI. + * @example https://example.com/webhooks/delivery-receipt + */ + 'dr-callback-url': string; + + /** + * The maximum number of outbound messages per second. + * @example 30 + */ + 'max-outbound-request': number; + + /** + * The maximum number of inbound messages per second. + * @example 30 + */ + 'max-inbound-request': number; + + /** + * The maximum number of API calls per second. + * @example 30 + */ + 'max-calls-per-second': number; +} diff --git a/packages/accounts/lib/types/Response/GetBalanceResponse.ts b/packages/accounts/lib/types/Response/GetBalanceResponse.ts new file mode 100644 index 00000000..81ba7e8a --- /dev/null +++ b/packages/accounts/lib/types/Response/GetBalanceResponse.ts @@ -0,0 +1,14 @@ +/** + * Represents the response structure when querying for account balance. + */ +export type GetBalanceResponse = { + /** + * The current balance value. + */ + value: number; + + /** + * Indicates if the auto-reload feature is enabled. + */ + autoReload: boolean; +} diff --git a/packages/accounts/lib/types/Response/ListAPISecretsResponse.ts b/packages/accounts/lib/types/Response/ListAPISecretsResponse.ts new file mode 100644 index 00000000..8e35eed8 --- /dev/null +++ b/packages/accounts/lib/types/Response/ListAPISecretsResponse.ts @@ -0,0 +1,28 @@ +import { APISecretResponse } from './APISecretResponse'; +import { APILinks } from '@vonage/server-client'; + +/** + * Represents the response structure when listing API secrets. + * + * @remarks + * + * Many of the Vonage APIs are accessed using an API key and secret. It is recommended that you + * change or "rotate" your secrets from time to time for security purposes. This section provides + * the API interface for achieving this. Note: to work on secrets for your secondary accounts, + * you may authenticate with your primary credentials and supply the secondary API keys as URL + * parameters to these API endpoints. + * + */ +export type ListAPISecretsResponse = APILinks & { + /** + * Contains the embedded secrets information. + */ + _embedded: { + + /** + * An array of API secrets. + * @see {@link APISecretResponse} + */ + secrets: APISecretResponse[]; + }; +} diff --git a/packages/accounts/lib/types/Response/TopUpBalanceResponse.ts b/packages/accounts/lib/types/Response/TopUpBalanceResponse.ts new file mode 100644 index 00000000..b49b1e6f --- /dev/null +++ b/packages/accounts/lib/types/Response/TopUpBalanceResponse.ts @@ -0,0 +1,22 @@ +/** + * Represents the response structure when performing a top-up operation for account balance. + * + * @remarks + * You can top up your account using this API when you have enabled auto-reload in the dashboard. + * The amount added by the top-up operation will be the same amount as was added in the payment when + * auto-reload was enabled. Your account balance is checked every 5-10 minutes and if it falls below + * the threshold and auto-reload is enabled, then it will be topped up automatically. Use this endpoint + * if you need to top up at times when your credit may be exhausted more quickly than the auto-reload + * may occur. + */ +export type TopUpBalanceResponse = { + /** + * The code associated with any potential errors during the top-up process. + */ + 'error-code': string; + + /** + * A descriptive label for the error code. + */ + 'error-code-label': string; +} diff --git a/packages/accounts/lib/types/Response/index.ts b/packages/accounts/lib/types/Response/index.ts new file mode 100644 index 00000000..026af431 --- /dev/null +++ b/packages/accounts/lib/types/Response/index.ts @@ -0,0 +1,5 @@ +export * from './APISecretResponse'; +export * from './AccountUpdateResponse'; +export * from './GetBalanceResponse'; +export * from './ListAPISecretsResponse'; +export * from './TopUpBalanceResponse'; diff --git a/packages/accounts/lib/types/index.ts b/packages/accounts/lib/types/index.ts new file mode 100644 index 00000000..b42a04ad --- /dev/null +++ b/packages/accounts/lib/types/index.ts @@ -0,0 +1,2 @@ +export * from './AccountCallbacks'; +export * from './Response'; diff --git a/packages/accounts/package.json b/packages/accounts/package.json index 4e5d63da..fe37e2ac 100644 --- a/packages/accounts/package.json +++ b/packages/accounts/package.json @@ -1,4 +1,5 @@ { + "$schema": "https://json.schemastore.org/package.json", "name": "@vonage/accounts", "version": "1.9.0", "description": "Vonage Account Management API", @@ -11,7 +12,16 @@ "url": "git+https://github.com/Vonage/vonage-node-sdk.git" }, "license": "Apache-2.0", - "author": "Chris Tankersley ", + "contributors": [ + { + "name": "Chris Tankersley", + "email": "chris@ctankersley.com" + }, + { + "name": "Chuck \"MANCHUCK\" Reeves", + "email": "chuck@manchuck.com" + } + ], "main": "dist/index.js", "types": "dist/index.d.ts", "directories": { @@ -22,6 +32,7 @@ "/dist" ], "scripts": { + "prepublishOnly": "npm run build", "build": "npm run clean && npm run compile", "clean": "npx shx rm -rf dist tsconfig.tsbuildinfo", "compile": "npx tsc --build --verbose" @@ -35,6 +46,5 @@ }, "publishConfig": { "directory": "dist" - }, - "gitHead": "328f18e5c8a458cb4d06d7955ec2399a6ce6f5d8" + } } diff --git a/packages/accounts/tsconfig.json b/packages/accounts/tsconfig.json index caf8c2ea..cd40b0e3 100644 --- a/packages/accounts/tsconfig.json +++ b/packages/accounts/tsconfig.json @@ -1,23 +1,24 @@ { - "extends": "../../tsconfig.json", + "$schema": "https://json.schemastore.org/tsconfig", - "compilerOptions": { - "rootDir": "lib", - "outDir": "dist" - }, + "extends": "../../tsconfig.json", - "exclude": [ - "__tests__", - "jest.config.js", - "dist" - ], + "compilerOptions": { + "rootDir": "lib", + "outDir": "dist" + }, - "references": [ - { "path": "../server-client" }, - { "path": "../auth" } - ], + "exclude": [ + "__tests__", + "dist" + ], - "ts-node": { - "esm": true - } + "references": [ + { "path": "../server-client" }, + { "path": "../auth" } + ], + + "ts-node": { + "esm": true + } } diff --git a/packages/accounts/typedoc.json b/packages/accounts/typedoc.json new file mode 100644 index 00000000..c218c2fa --- /dev/null +++ b/packages/accounts/typedoc.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "extends": ["../../typedoc.base.json"], + "entryPoints": ["lib/index.ts"], + "name": "Vonage Accounts" +}