theauthapi 1.0.6 → 1.0.7

package/README.md

@@ -1,5 +1,284 @@
-# The Auth API node library
-## Scalable API Key Management and Auth Control
-## Secure your API with best in class API Key management, user access, all with great analytics.
+# Client library for [TheAuthAPI](https://theauthapi.com/)
 
-Client library for [TheAuthAPI.com](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/ApiKeys/ApiKeys.d.ts

@@ -4,10 +4,13 @@ import { ApiKeysInterface } from "./ApiKeysInterface";
 declare class ApiKeys implements ApiKeysInterface {
     api: ApiRequest;
     constructor(apiService: ApiRequest);
-    authenticateKey(apikey: string): Promise<ApiKey>;
+    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

@@ -15,14 +15,24 @@ 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;
     }
-    authenticateKey(apikey) {
+    isValidKey(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}`);
+            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) {
@@ -31,21 +41,21 @@ class ApiKeys {
             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* () {
-            // 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);
-            }
+            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* () {
-            (0, util_1.validateString)("apiKey", apiKey);
-            for (const [key, value] of Object.entries((0, lodash_omit_1.default)(updateTo, "customMetaData"))) {
-                (0, util_1.validateString)(key, value);
-            }
+            this.validateUpdateKeyInput(apiKey, updateTo);
             return yield this.api.request(HttpMethod_1.HttpMethod.PATCH, `/api-keys/${apiKey}`, updateTo);
         });
     }
@@ -55,5 +65,27 @@ class ApiKeys {
             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

@@ -1,6 +1,7 @@
 import { ApiKey, ApiKeyInput, UpdateApiKeyInput } from "../../types";
 export interface ApiKeysInterface {
-    authenticateKey(apiKey: string): Promise<ApiKey>;
+    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>;

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

@@ -1,5 +1,5 @@
 import ApiRequest from "../../services/ApiRequest/ApiRequest";
-import { Project, UpdateProjectInput } from "../../types";
+import { CreateProjectInput, Project, UpdateProjectInput } from "../../types";
 import { ProjectsInterface } from "./ProjectsInterface";
 declare class Projects implements ProjectsInterface {
     api: ApiRequest;
@@ -8,7 +8,9 @@ declare class Projects implements ProjectsInterface {
     getProjects(accountId: string): Promise<Project[]>;
     getProject(projectId: string): Promise<Project>;
     deleteProject(projectId: string): Promise<boolean>;
-    createProject(name: string, accountId: string): Promise<Project>;
-    updateProject(projectId: string, updateTo: UpdateProjectInput): Promise<Project>;
+    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

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 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 {
@@ -34,21 +35,34 @@ class Projects {
             return yield this.api.request(HttpMethod_1.HttpMethod.DELETE, `${this.endpoint}/${projectId}`);
         });
     }
-    createProject(name, accountId) {
+    createProject(project) {
         return __awaiter(this, void 0, void 0, function* () {
-            (0, util_1.validateString)("name", name);
-            (0, util_1.validateString)("accountId", accountId);
-            return yield this.api.request(HttpMethod_1.HttpMethod.POST, this.endpoint, {
-                name,
-                accountId,
-            });
+            this.validateCreateProjectInput(project);
+            return yield this.api.request(HttpMethod_1.HttpMethod.POST, this.endpoint, project);
         });
     }
-    updateProject(projectId, updateTo) {
+    updateProject(projectId, project) {
         return __awaiter(this, void 0, void 0, function* () {
-            (0, util_1.validateString)("projectId", projectId);
-            return this.api.request(HttpMethod_1.HttpMethod.PATCH, `${this.endpoint}/${projectId}`, updateTo);
+            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

@@ -1,8 +1,8 @@
-import { Project, UpdateProjectInput } from "../../types";
+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(name: string, accountId: string): Promise<Project>;
+    createProject(project: CreateProjectInput): Promise<Project>;
     updateProject(name: string, updateTo: UpdateProjectInput): Promise<Project>;
 }

package/dist/services/ApiRequest/ApiRequest.js

@@ -17,6 +17,7 @@ const libraryMeta_1 = require("../../libraryMeta");
 const ApiRequestError_1 = __importDefault(require("./ApiRequestError"));
 const axios_retry_1 = __importDefault(require("axios-retry"));
 const ms_1 = __importDefault(require("ms"));
+const ApiResponseError_1 = __importDefault(require("./ApiResponseError"));
 class ApiRequest {
     constructor(config) {
         const { host, accessKey, headers, retryCount, timeout } = config;
@@ -76,10 +77,10 @@ class ApiRequest {
             catch (error) {
                 if (axios_1.default.isAxiosError(error)) {
                     if (error.response) {
-                        throw new ApiRequestError_1.default(error.response.status, (_a = error.response.data.message) !== null && _a !== void 0 ? _a : error.response.statusText);
+                        throw new ApiResponseError_1.default(error.response.status, (_a = error.response.data.message) !== null && _a !== void 0 ? _a : error.response.statusText);
                     }
                     else if (error.request) {
-                        throw new Error(error.request);
+                        throw new ApiRequestError_1.default(error.message);
                     }
                 }
                 throw error;

package/dist/services/ApiRequest/ApiRequestError.d.ts

@@ -1,4 +1,10 @@
+/**
+ *
+ *  Throws when no response was received from the server
+ *  @param message - error message
+ *
+ * */
 declare class ApiRequestError extends Error {
-    constructor(statusCode: number, message: string);
+    constructor(message: string);
 }
 export default ApiRequestError;

package/dist/services/ApiRequest/ApiRequestError.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ *
+ *  Throws when no response was received from the server
+ *  @param message - error message
+ *
+ * */
 class ApiRequestError extends Error {
-    constructor(statusCode, message) {
-        super(`(${statusCode}): ${message}`);
+    constructor(message) {
+        super(message);
+        this.name = 'ApiRequestError';
     }
 }
 exports.default = ApiRequestError;

package/dist/services/ApiRequest/ApiResponseError.d.ts

@@ -0,0 +1,12 @@
+/**
+ *
+ *  Throws when the server responds with a status code that falls out of the range 2xx
+ *  @param statusCode - HTTP status code the server responded with
+ *  @param message - error message
+ *
+ * */
+declare class ApiResponseError extends Error {
+    statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export default ApiResponseError;

package/dist/services/ApiRequest/ApiResponseError.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ *
+ *  Throws when the server responds with a status code that falls out of the range 2xx
+ *  @param statusCode - HTTP status code the server responded with
+ *  @param message - error message
+ *
+ * */
+class ApiResponseError extends Error {
+    constructor(statusCode, message) {
+        super(`(${statusCode}): ${message}`);
+        this.statusCode = statusCode;
+        this.name = "ApiResponseError";
+    }
+}
+exports.default = ApiResponseError;

package/dist/types/index.d.ts

@@ -47,6 +47,15 @@ export declare type Project = AuthBaseEntity & {
     accountId: string;
     env: string;
 };
+export declare enum Environment {
+    LIVE = "live",
+    TEST = "test"
+}
+export declare type CreateProjectInput = {
+    name: string;
+    accountId: string;
+    env: Environment;
+};
 export declare type UpdateProjectInput = {
     name: string;
 };

package/dist/types/index.js

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthedEntityType = void 0;
+exports.Environment = exports.AuthedEntityType = void 0;
 var AuthedEntityType;
 (function (AuthedEntityType) {
     AuthedEntityType["USER"] = "USER";
     AuthedEntityType["ACCESS_KEY"] = "ACCESS_KEY";
 })(AuthedEntityType = exports.AuthedEntityType || (exports.AuthedEntityType = {}));
+var Environment;
+(function (Environment) {
+    Environment["LIVE"] = "live";
+    Environment["TEST"] = "test";
+})(Environment = exports.Environment || (exports.Environment = {}));

package/dist/util/index.js

@@ -7,7 +7,7 @@ exports.validateString = void 0;
 const lodash_isstring_1 = __importDefault(require("lodash.isstring"));
 function validateString(variableName, value) {
     if (!value || !(0, lodash_isstring_1.default)(value)) {
-        throw new Error(`${variableName} must be a string`);
+        throw new TypeError(`${variableName} must be a string, got: ${value}`);
     }
 }
 exports.validateString = validateString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theauthapi",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Client library for TheAuthAPI.com",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",