theauthapi 1.0.4 → 1.0.7

package/README.md

@@ -1,2 +1,284 @@
-# theauthapi
-Client library for TheAuthAPI.com
+# Client library for [TheAuthAPI](https://theauthapi.com/)
+
+**Contents**
+
+- [Client library for TheAuthAPI](#client-library-for-theauthapi)
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+  - [Usage](#usage)
+    - [Example: Validating an api-key](#example-validating-an-api-key)
+    - [Example: Listing the projects of an account](#example-listing-the-projects-of-an-account)
+    - [Example: Listing projects and associated API Keys](#example-listing-projects-and-associated-api-keys)
+    - [Example: Creating an API Key](#example-creating-an-api-key)
+    - [Handling Errors](#handling-errors)
+    - [Typescript](#typescript)
+    - [📙 Further Reading](#-further-reading)
+
+**Scalable API Key Management and Auth Control**
+Secure your API with best in class API Key management, user access, all with great analytics.
+
+## Installation
+
+This library is published on [npm](https://www.npmjs.com/package/theauthapi), you can add it as a dependency using the following
+command
+
+```bash
+npm install theauthapi
+# or
+yarn add theauthapi
+```
+
+## Configuration
+
+You'll need to configure the library with your `access key` and `account id`, you can grab these from [TheAuthAPI](https://app.theauthapi.com/dashboard) dashboard.
+
+For further instructions on creating an account, check out our [how to guides](https://thatapicompany.notion.site/The-Auth-API-Knowledge-Base-21660cee84e640729714fad43d9ce546).
+
+### Imports
+
+#### CommonJS
+
+```javascript
+const TheAuthAPI = require("theauthapi").default;
+```
+
+#### ES Modules
+
+```typescript
+import TheAuthAPI from "theauthapi";
+```
+
+initialize the client using your access key:
+
+```javascript
+const theAuthAPI = new TheAuthAPI("YOUR_ACCESS_KEY");
+```
+
+You can also provide custom options:
+
+```javascript
+const theAuthAPI = new TheAuthAPI("YOUR_ACCESS_KEY", {
+  timeout: 3600,
+  retryCount: 2,
+});
+```
+
+**Full option types:**
+
+```typescript
+type Options = {
+  // server url
+  host?: string;
+  // request timeout in ms
+  timeout?: string | number;
+  // number of retries before failing
+  retryCount?: number;
+};
+```
+
+## Usage
+
+After initiating the client, you can access endpoint methods using the following pattern:
+`[object instance].[endpoint].[method]`
+
+For example, getting the projects for an account would be: `theAuthApiClient.projects.getProjects("ACCOUNT_ID")`,
+
+Similarly, getting the api keys would be:
+`theAuthApiClient.apiKeys.getKeys("PROJECT_ID")`
+
+| endpoint  | attribute | example                                       |
+| --------- | --------- | --------------------------------------------- |
+| /api-keys | apiKeys   | `client.apiKeys.createKey("MY_KEY")`          |
+| /projects | projects  | `client.projects.createProject("MY_PROJECT")` |
+| /accounts | accounts  | `client.accounts.createAccount("MY_ACCOUNT")` |
+
+For details on each endpoint accepted values, please reference these docs: [docs.theauthapi.com](https://docs.theauthapi.com/)
+
+All methods return a promise containing the returned JSON as a javascript object. Each method of an endpoint maps HTTP methods to
+
+| HTTP Method | method name | example                                                                   |
+| ----------- | ----------- | ------------------------------------------------------------------------- |
+| POST        | create\*    | `client.apiKeys.createKey({ name: "KEY_NAME", projectId: "PROJECT_ID" })` |
+| GET         | get\*       | `client.apiKeys.getKeys("PROJECT_ID")`                                    |
+| DELETE      | delete\*    | `client.apiKeys.deleteKey("MY_KEY")`                                      |
+| PATCH       | update\*    | `client.apiKeys.updateKey("MY_KEY", { name: "UPDATED_KEY_NAME" })`        |
+
+#### Example: Validating an api-key
+
+You can easily validate an API key using `apiKeys.isValidKey` which returns `true` if the key is valid, `false` otherwise.
+`isValidKey` throws an `ApiRequestError` if there's a network issue, it's advised to wrap it in a `try/catch` to handle the potential error
+
+```javascript
+theAuthAPI.apiKeys
+  .isValidKey("API_KEY")
+  .then((isValidKey) => {
+    if (isValidKey) {
+      console.log("The API is valid!");
+    } else {
+      console.log("Invalid API key!");
+    }
+  })
+  .catch((error) => {
+    // handle network error
+  });
+```
+
+**Using async/await**
+
+```javascript
+try {
+  const isValidKey = await theAuthAPI.apiKeys.isValidKey("API_KEY");
+  if (isValidKey) {
+    console.log("The API is valid!");
+  } else {
+    console.log("Invalid API key!");
+  }
+} catch (error) {
+  // handle network error
+}
+```
+
+#### Example: Listing the projects of an account
+
+```javascript
+theAuthAPI.projects
+  .getProjects("ACCOUNT_ID")
+  .then((projects) => console.log(projects))
+  .catch((error) => console.log(error));
+```
+
+**Using async/await**
+
+```javascript
+try {
+  const projects = await client.projects.getProjects("ACCOUNT_ID");
+} catch (error) {
+  console.log(error);
+}
+```
+
+#### Example: Listing projects and associated API Keys
+
+```javascript
+async function getProjectsWithKeys(accountId: string) {
+  try {
+    const projects = await theAuthAPI.projects.getProjects(accountId);
+    const projectsKeys = projects.map(async (project) => {
+      const keys = await theAuthAPI.apiKeys.getKeys(project.id);
+      return { project, keys };
+    });
+    return await Promise.all(projectsKeys);
+  } catch (error) {
+    // handle error
+  }
+}
+```
+
+#### Example: Creating an API Key
+
+```javascript
+theAuthAPI.apiKeys
+  .createKey({
+    projectId: "PROJECT_ID",
+    customMetaData: { metadata_val: "value to store" },
+    customAccountId: "[any info you want]",
+    name: "[any info you want e.g. name of customer or the key]",
+  })
+  .then((key) => console.log("Key created > ", key))
+  .catch((error) => console.log("Couldn't make the key", error));
+```
+
+**Using async/await**
+
+```javascript
+try {
+  const key = await theAuthAPI.apiKeys.createKey({
+    projectId: "PROJECT_ID",
+    customMetaData: { metadata_val: "value to store" },
+    customAccountId: "[any info you want]",
+    name: "[any info you want e.g. name of customer or the key]",
+  });
+  console.log("Key created > ", key);
+} catch (error) {
+  console.log("Couldn't make the key ", error);
+}
+```
+
+### Handling Errors
+
+[comment]: <> (All methods that return a promise throw 3 types of errors)
+
+##### ApiRequestError
+
+Thrown when there's a network or a connectivity issue, for example, if the client didn't establish any network connection with the host
+
+```
+ApiRequestError: getaddrinfo EAI_AGAIN api.theauthapi.com
+```
+
+##### ApiResponseError
+
+Thrown when the server responds with an HTTP status code not in the `2xx` range. `ApiRequestError` provides two properties to distinguish the type of the error
+
+- `statusCode` HTTP status code
+- `message` the message the server responded with in the body
+
+This is the most common thrown error, you should expect and handle it each time you use any of the library methods
+
+##### Example: Getting a key throws an ApiResponseError if the key is invalid
+
+If you try to GET an invalid key using `apiKeys.getKey("invalid-key")`, the server responds with a 404 error and an `ApiResponseError` is thrown
+
+```
+ApiResponseError: (404): Invalid client key
+```
+
+"404" is the `statusCode`, "Invalid client Key" is the `message`, you can access these properties using `error.statusCode` and `error.message` respectively
+
+##### Error
+
+Unknown error, just a normal javascript error
+
+#### Handling Errors the Right Way
+
+Since all the possible thrown errors are instances of classes, we can check the type of the thrown error and handle it accordingly
+
+```javascript
+try {
+  const key = await theAuthAPI.apiKeys.getKey("KEY");
+} catch (error) {
+  if (error instanceof ApiResponseError) {
+    // handle response error
+  }
+  if (error instanceof ApiRequestError) {
+    // handle network error
+  }
+  // unknown error
+  throw error;
+}
+```
+
+### Typescript
+
+This library is written in [Typescript](https://www.typescriptlang.org/), types are provided out of the box.
+
+Example of usage with Typescript:
+
+```typescript
+import TheAuthAPI from "theauthapi";
+import { Project } from "theauthapi/types";
+
+const client = new TheAuthAPI("ACCESS_KEY");
+
+async function getProjectsIds(accountId: string): Promise<string[]> {
+  const projects: Project[] = await client.projects.getProjects(accountId);
+  return projects.map((project) => project.name);
+}
+```
+
+### 📙 Further Reading
+
+- Create your account [https://theauthapi.com](https://theauthapi.com)
+- View our [Knowledge Base](https://thatapicompany.notion.site/The-Auth-API-Knowledge-Base-21660cee84e640729714fad43d9ce546) help centre
+- Articles on best Auth practice - [https://theauthapi.com/articles](https://theauthapi.com/articles)
+- Meet the team behind The Auth API - [That API Company](https://thatapicompany.com/)

package/dist/endpoints/Accounts/Accounts.d.ts

@@ -0,0 +1,10 @@
+import { AccountsInterface } from "./AccountsInterface";
+import ApiRequest from "../../services/ApiRequest/ApiRequest";
+import { Account } from "../../types";
+declare class Accounts implements AccountsInterface {
+    api: ApiRequest;
+    endpoint: string;
+    constructor(apiService: ApiRequest);
+    getAccount(accountId: string): Promise<Account>;
+}
+export default Accounts;

package/dist/endpoints/Accounts/Accounts.js

@@ -0,0 +1,26 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const HttpMethod_1 = require("../../services/ApiRequest/HttpMethod");
+const util_1 = require("../../util");
+class Accounts {
+    constructor(apiService) {
+        this.api = apiService;
+        this.endpoint = "/accounts";
+    }
+    getAccount(accountId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, util_1.validateString)("accountId", accountId);
+            return yield this.api.request(HttpMethod_1.HttpMethod.GET, `${this.endpoint}/${accountId}`);
+        });
+    }
+}
+exports.default = Accounts;

package/dist/endpoints/Accounts/AccountsInterface.d.ts

@@ -0,0 +1,4 @@
+import { Account } from "../../types";
+export interface AccountsInterface {
+    getAccount(accountId: string): Promise<Account>;
+}

package/dist/endpoints/Accounts/AccountsInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/endpoints/ApiKeys/ApiKeys.d.ts

@@ -0,0 +1,16 @@
+import ApiRequest from "../../services/ApiRequest/ApiRequest";
+import { ApiKey, ApiKeyInput, UpdateApiKeyInput } from "../../types";
+import { ApiKeysInterface } from "./ApiKeysInterface";
+declare class ApiKeys implements ApiKeysInterface {
+    api: ApiRequest;
+    constructor(apiService: ApiRequest);
+    isValidKey(apikey: string): Promise<boolean>;
+    getKeys(projectId: string): Promise<ApiKey[]>;
+    getKey(apikey: string): Promise<ApiKey>;
+    createKey(apiKey: ApiKeyInput): Promise<ApiKey>;
+    updateKey(apiKey: string, updateTo: UpdateApiKeyInput): Promise<ApiKey>;
+    deleteKey(apiKey: string): Promise<boolean>;
+    private validateCreateKeyInput;
+    private validateUpdateKeyInput;
+}
+export default ApiKeys;

package/dist/endpoints/ApiKeys/ApiKeys.js

@@ -0,0 +1,91 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const HttpMethod_1 = require("../../services/ApiRequest/HttpMethod");
+const lodash_omit_1 = __importDefault(require("lodash.omit"));
+const util_1 = require("../../util");
+const ApiResponseError_1 = __importDefault(require("../../services/ApiRequest/ApiResponseError"));
+class ApiKeys {
+    constructor(apiService) {
+        this.api = apiService;
+    }
+    isValidKey(apikey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, util_1.validateString)("apikey", apikey);
+            try {
+                const key = yield this.api.request(HttpMethod_1.HttpMethod.GET, `/api-keys/${apikey}`);
+                return key.key !== undefined;
+            }
+            catch (error) {
+                if (error instanceof ApiResponseError_1.default && error.statusCode === 404) {
+                    return false;
+                }
+                throw error;
+            }
+        });
+    }
+    getKeys(projectId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, util_1.validateString)("projectId", projectId);
+            return yield this.api.request(HttpMethod_1.HttpMethod.GET, `/api-keys/?projectId=${projectId}`);
+        });
+    }
+    getKey(apikey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, util_1.validateString)("apikey", apikey);
+            return yield this.api.request(HttpMethod_1.HttpMethod.GET, `/api-keys/${apikey}`);
+        });
+    }
+    createKey(apiKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.validateCreateKeyInput(apiKey);
+            return yield this.api.request(HttpMethod_1.HttpMethod.POST, "/api-keys", apiKey);
+        });
+    }
+    updateKey(apiKey, updateTo) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.validateUpdateKeyInput(apiKey, updateTo);
+            return yield this.api.request(HttpMethod_1.HttpMethod.PATCH, `/api-keys/${apiKey}`, updateTo);
+        });
+    }
+    deleteKey(apiKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, util_1.validateString)("apiKey", apiKey);
+            return yield this.api.request(HttpMethod_1.HttpMethod.DELETE, `/api-keys/${apiKey}`);
+        });
+    }
+    validateCreateKeyInput(apiKey) {
+        if (!apiKey) {
+            throw new TypeError("apiKey must be an object");
+        }
+        if (!apiKey.name || !apiKey.projectId) {
+            throw TypeError("apiKey object must contain the properties [name, projectId]");
+        }
+        // validate string properties only
+        for (const [key, value] of Object.entries((0, lodash_omit_1.default)(apiKey, ["customMetaData", "rateLimitConfigs"]))) {
+            (0, util_1.validateString)(key, value);
+        }
+    }
+    validateUpdateKeyInput(apiKey, updatedKey) {
+        if (!updatedKey) {
+            throw new TypeError("updatedKey must be an object");
+        }
+        if (!updatedKey.name) {
+            throw TypeError("updatedKey object must contain the property [name]");
+        }
+        (0, util_1.validateString)("apiKey", apiKey);
+        (0, util_1.validateString)("name", updatedKey.name);
+    }
+}
+exports.default = ApiKeys;

package/dist/endpoints/ApiKeys/ApiKeysInterface.d.ts

@@ -0,0 +1,9 @@
+import { ApiKey, ApiKeyInput, UpdateApiKeyInput } from "../../types";
+export interface ApiKeysInterface {
+    isValidKey(apiKey: string): Promise<boolean>;
+    getKey(apiKey: string): Promise<ApiKey>;
+    getKeys(projectId: string): Promise<ApiKey[]>;
+    createKey(apiKey: ApiKeyInput): Promise<ApiKey>;
+    updateKey(apiKey: string, updateTo: UpdateApiKeyInput): Promise<ApiKey>;
+    deleteKey(apiKey: string): Promise<boolean>;
+}

package/dist/endpoints/ApiKeys/ApiKeysInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/endpoints/Projects/Projects.d.ts

@@ -0,0 +1,16 @@
+import ApiRequest from "../../services/ApiRequest/ApiRequest";
+import { CreateProjectInput, Project, UpdateProjectInput } from "../../types";
+import { ProjectsInterface } from "./ProjectsInterface";
+declare class Projects implements ProjectsInterface {
+    api: ApiRequest;
+    endpoint: string;
+    constructor(apiService: ApiRequest);
+    getProjects(accountId: string): Promise<Project[]>;
+    getProject(projectId: string): Promise<Project>;
+    deleteProject(projectId: string): Promise<boolean>;
+    createProject(project: CreateProjectInput): Promise<Project>;
+    updateProject(projectId: string, project: UpdateProjectInput): Promise<Project>;
+    private validateCreateProjectInput;
+    private validateUpdateProjectInput;
+}
+export default Projects;

package/dist/endpoints/Projects/Projects.js

@@ -0,0 +1,68 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("../../types");
+const HttpMethod_1 = require("../../services/ApiRequest/HttpMethod");
+const util_1 = require("../../util");
+class Projects {
+    constructor(apiService) {
+        this.api = apiService;
+        this.endpoint = "/projects";
+    }
+    getProjects(accountId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, util_1.validateString)("accountId", accountId);
+            return yield this.api.request(HttpMethod_1.HttpMethod.GET, `${this.endpoint}?accountId=${accountId}`);
+        });
+    }
+    getProject(projectId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, util_1.validateString)("projectId", projectId);
+            return yield this.api.request(HttpMethod_1.HttpMethod.GET, `${this.endpoint}/${projectId}`);
+        });
+    }
+    deleteProject(projectId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, util_1.validateString)("projectId", projectId);
+            return yield this.api.request(HttpMethod_1.HttpMethod.DELETE, `${this.endpoint}/${projectId}`);
+        });
+    }
+    createProject(project) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.validateCreateProjectInput(project);
+            return yield this.api.request(HttpMethod_1.HttpMethod.POST, this.endpoint, project);
+        });
+    }
+    updateProject(projectId, project) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.validateUpdateProjectInput(projectId, project);
+            return this.api.request(HttpMethod_1.HttpMethod.PATCH, `${this.endpoint}/${projectId}`, project);
+        });
+    }
+    validateCreateProjectInput(project) {
+        if (!project) {
+            throw new TypeError("project must be an object");
+        }
+        (0, util_1.validateString)("name", project.name);
+        (0, util_1.validateString)("accountId", project.accountId);
+        if (!Object.values(types_1.Environment).includes(project.env)) {
+            throw TypeError(`expected env to be one of [${Object.values(types_1.Environment).map((v) => `"${v}"`)}], got: ${project.env}`);
+        }
+    }
+    validateUpdateProjectInput(projectId, project) {
+        if (!project) {
+            throw new TypeError("project must be an object");
+        }
+        (0, util_1.validateString)("projectId", projectId);
+        (0, util_1.validateString)("name", project.name);
+    }
+}
+exports.default = Projects;

package/dist/endpoints/Projects/ProjectsInterface.d.ts

@@ -0,0 +1,8 @@
+import { CreateProjectInput, Project, UpdateProjectInput } from "../../types";
+export interface ProjectsInterface {
+    getProjects(accountId: string): Promise<Project[]>;
+    getProject(projectId: string): Promise<Project>;
+    deleteProject(projectId: string): Promise<boolean>;
+    createProject(project: CreateProjectInput): Promise<Project>;
+    updateProject(name: string, updateTo: UpdateProjectInput): Promise<Project>;
+}

package/dist/endpoints/Projects/ProjectsInterface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import ApiRequest from "./services/ApiRequest/ApiRequest";
+import ApiKeys from "./endpoints/ApiKeys/ApiKeys";
+import Projects from "./endpoints/Projects/Projects";
+import Accounts from "./endpoints/Accounts/Accounts";
+declare type Options = {
+    host?: string;
+    timeout?: string | number;
+    cacheTTL?: number;
+    enable?: boolean;
+    retryCount?: number;
+};
+declare class TheAuthAPI {
+    queue: [];
+    accessKey: string;
+    host: string;
+    timeout: number | string | undefined;
+    cacheTTL: number;
+    api: ApiRequest;
+    apiKeys: ApiKeys;
+    projects: Projects;
+    accounts: Accounts;
+    /**
+     * Initialize a new `Analytics` with your Segment project's `writeKey` and an
+     * optional dictionary of `options`.
+     *
+     * @param {String} accessKey
+     * @param {Object} [options] (optional)
+     *   @property {Number} flushAt (default: 20)
+     *   @property {Number} flushInterval (default: 10000)
+     *   @property {String} host (default: 'https://api.segment.io')
+     *   @property {Boolean} enable (default: true)
+     */
+    constructor(accessKey: string, options?: Options);
+    authenticateAPIKey(key: string, callback?: (err: any, data: any) => any): Promise<unknown>;
+}
+export default TheAuthAPI;