npm package: @otpfy/sdk
Description: This `Node` package will provide you with the interface to interact with your `OTPfy` services like `generate` and `validate`.
Author: Alex Casillas
Latest version: 2.3.1

# OTPfy SDK

This `Node` package will provide you with the interface to interact with your `OTPfy` services like `generate` and `validate`.

## SDK installation

```
yarn add @otpfy/sdk
```

```
npm i --save @otpfy/sdk
```

## SDK import

```ts
import sdk from '@otpfy/sdk';
```

```ts
const sdk = require('@otpfy/sdk');
```

## SDK initialization

In order for a successful initialization your team private key needs to be passed as the only argument to the initialization function. Make sure that this private key is always safe and secure so nobody can make requests on your team's behalf.

```ts
import sdk from '@otpfy/sdk';

const otpfy = sdk('TEAM_PRIVATE_KEY');
```

## `node-fetch` as a peer dependency

This module requires the use of `node-fetch` as a dependency but it's not bundled with the SDK to avoid increasing the bundle size. This means that you will have to separately install `node-fetch` as a dependency of your backend project.

## SDK interface

```ts
export interface OTPfySDK {
  generateOTP: (
    config: GenerateConfig
  ) => Promise<GenerateSuccessResponse | GenerateErrorResponse>;
  verifyOTP: (
    config: VerifyConfig
  ) => Promise<VerifySuccessResponse | VerifyErrorResponse>;
  generateMagicLink: (
    config: GenerateMagicLinkConfig
  ) => Promise<GenerateSuccessResponse | GenerateErrorResponse>;
  checkLicense: () => Promise<LicenseStatus>;
}

type GenerateConfig = {
  key: string;
  external_identifier: string;
  email: string;
  phone?: string;
};

type GenerateMagicLinkConfig = {
  key: string;
  external_identifier: string;
  email: string;
  callbacks: {
    success: string;
    error: string;
  };
};

type VerifyConfig = {
  key: string;
  identifier: string;
  external_identifier: string;
  code: string;
};

export type GenerateSuccessResponse = {
  status: 200;
  code: string;
  identifier: string;
};

export type GenerateErrorResponse = {
  status: number;
  code: string;
  message?: string;
};

export type VerifySuccessResponse = {
  status: 200;
  code: string;
};

export type VerifyErrorResponse = {
  status: number;
  code: string;
  message?: string;
};

export type LicenseStatus = {
  code: 'BAD_REQUEST' | 'UNAUTHORIZED' | 'VALID_LICENSE' | 'TEAM_BLOCKED';
};
```

---

## OTP generation

For OTP generation the `generateOTP` method from the `SDK` must be called with a configuration object:

```ts
import sdk from '@otpfy/sdk';

const otpfy = sdk('TEAM_PRIVATE_KEY');

const generateResponse = await otpfy.generateOTP({
  email: 'no-reply@otpfy.com',
  external_identifier: '978c324ab78dd92',
  key: 'AUTH',
});
```

`sdk.generateOTP(config)` will return you the a `GenerateSuccessResponse` with the unique `OTP identifier` that later on will be used to verify the generated code and the user input or `GenerateErrorResponse` if the generation was not successful.

Let's dive into the `GenerateConfig` properties:

### key

```ts
key: string;
```

This property will take the OTP key string generated on your OTPfy dashboard.

### external_identifier

```ts
external_identifier: string;
```

Unique identifier provided on your side to identify this OTP. Commonly this could be your user's ID or some unique identifier.

### email

```ts
email: string;
```

An email will be sent to this target email with the generated OTP based on the template created and chosen on your OTPfy dashboard.

### phone (not supported yet)

```ts
phone?: string;
```

A SMS will be sent to this target phone with the generated OTP based on the template created and chose on your OTPfy dashboard.

---

## OTP verification

For OTP verification the `verifyOTP` method from the `SDK` must be called with a configuration object:

```ts
import sdk from '@otpfy/sdk';

const otpfy = sdk('TEAM_PRIVATE_KEY');

const verifyResponse = await otpfy.verifyOTP({
  code: '45$6AFd65',
  external_identifier: '978c324ab78dd92',
  key: 'AUTH',
  identifier: '123cb8945bd0943',
});
```

`sdk.verify(config)` will return you a `VerifySuccessResponse` or `VerifyErrorResponse` that will let you know if the verification was successful or not.

Let's dive into the `VerifyConfig` properties:

### code

```ts
code: string;
```

The code that the user has received and you'd like to check.

### external_identifier

```ts
external_identifier: string;
```

Unique identifier provided on your side to identify the OTP previously generated. Commonly this could be your user's ID or some unique identifier.

### key

```ts
key: string;
```

This property will take the OTP key string generated on your OTPfy dashboard.

### identifier

```ts
identifier: string;
```

The unique OTP identifier that was returned by the `sdk.generate(config)` call that will make sure that the correct OTP is verified.

---

## Magic Link generation

For OTP generation the `generateOTP` method from the `SDK` must be called with a configuration object:

```ts
import sdk from '@otpfy/sdk';

const otpfy = sdk('TEAM_PRIVATE_KEY');

const generateResponse = await otpfy.generateMagicLink({
  email: 'no-reply@otpfy.com',
  external_identifier: '978c324ab78dd92',
  key: 'AUTH',
  callbacks: {
    success: 'https://myapp.com/authentication/success?id=123123123
    error: 'https://myapp.com/authentication/error?id=123123123
  }
});
```

`sdk.generateMagicLink(config)` will return you a `GenerateSuccessResponse` or `GenerateErrorResponse` if the generation was not successful.

Let's dive into the `GenerateMagicLinkConfig` properties:

### key

```ts
key: string;
```

This property will take the Magic Link key string generated on your OTPfy dashboard.

### external_identifier

```ts
external_identifier: string;
```

Unique identifier provided on your side to identify this Magic Link. Commonly this could be your user's ID or some unique identifier.

### email

```ts
email: string;
```

An email will be sent to this target email with the generated Magic Link based on the template created and chosen on your OTPfy dashboard.

### callbacks

```ts
callbacks: {
  success: string;
  error: string;
}
```

A callback object that will be used by OTPfy to redirect the user to the given URLs after the Magic Link verification has succeeded or not, redirecting to `callbacks.success` if the verification was successful or to `callbacks.error` if the verification was unsuccessful.

---

## Check License

You can use this handy method from the `OTPfy SDK` in order to check your team's current license status.

```ts
const licenseStatus = await otpfy.checkLicense();
```

`licenseStatus` will hold a string literal with any of the following values and meanings:

- `VALID_LICENSE`

  Your current license is valid and you can make use and have access to any of the `OTPfy services`.

- `UNAUTHORIZED`

  The provided team private key at the initialization of the SDK was not valid and therefore, you're not authorized to check for license statuses.

- `TEAM_BLOCKED`

  Your team is currently blocked from using the OTPfy services due to an unpaid overdue invoice. Please, access your dashboard at https://otpfy.com/license and proceed with the payment of the invoice in order to unblock the license and continue using the OTPfy services.

---

### GenerateSuccessResponse example

```ts
{
  status: 200,
  code: 'SUCCESS',
  identifier: 'example-identifier'
}
```

### GenerateErrorResponse example

```ts
{
  status: 400,
  code: 'BAD_REQUEST'
}
```

### VerifySuccessResponse example

```ts
{
  status: 200,
  code: 'SUCCESS`
}
```

### VerifyErrorResponse example

```ts
{
  status: 400,
  code: 'BAD_REQUEST'
}
```