Merge pull request #80 from androozka/sprint-5

Sprint 5

README.md

@@ -16,57 +16,50 @@ A JS library for interacting with the Zendesk API.
 - Send prepared object directly to axios 🤯
 - Mirrors [Zendesk's API documentation](https://developer.zendesk.com/rest_api/docs/zendesk-apis/resources) 👀
 
-## Installing
+_**Note**: Only v2 framework, [v1 deprecated](https://support.zendesk.com/hc/en-us/articles/360002106888-Removal-of-Zendesk-Apps-framework-v1)_
 
-### Using npm
+## Installing
 
 ```bash
+# using npm
 npm install @androozka/zendesk-api-js
-```
-
-### Using yarn
 
-```bash
+# using yarn
 yarn add @androozka/zendesk-api-js
 ```
 
 ## Usage
 
-### Suggested libraries
+### Getting Started
 
 ```javascript
-const base64 = require("js-base64").Base64;
-const axios = require("axios");
+const axios = require('axios'); // Suggested library
+const zdApi = require('@androozka/zendesk-api-js');
 ```
 
-### Zendesk account information
+### Zendesk Info
 
 ```javascript
-const instance = ""; // Name of Zendesk instance
-const email = ""; // Email address of Zendesk user
-const token = ""; // Generated Zendesk token
-
-const encoded = base64.encode(`${email}/token:${token}`);
-
-const headers = {
-  "Content-Type": "application/json",
-  Authorization: `Basic ${encoded}`
+const options = {
+  instance: '', // Zendesk subdomain
+  email: '', // User account to perform requests
+  password: '', // Password for user account
+  token: '' // Generated Zendesk token
 };
+/* Note: Either "password" or "token" is required */
 ```
 
-### Choose framework version
+### Initalize
 
 ```javascript
-const zdApi = require("@androozka/zendesk-api-js");
-const zaf_v2 = zdApi.v2({ instance, headers });
-```
+// Load entire library
+const { support, sunshine } = zdApi.init(options);
 
-- _**Note**: Only v2, [v1 being deprecated](https://support.zendesk.com/hc/en-us/articles/360002106888-Removal-of-Zendesk-Apps-framework-v1)_
+// Load entire API
+const { tickets, groups } = zdApi.support.init(options);
 
-### Selecting API endpoints
-
-```javascript
-const { support, sunshine } = zaf_v2;
+// Load specific endpoint
+const { list, create } = zdApi.support.tickets(options);
 ```
 
 ## Examples
@@ -75,8 +68,11 @@ const { support, sunshine } = zaf_v2;
 
 ```javascript
 try {
+  const { tags } = zdApi.support.init(options);
   const data = { tags: ['tag_1', 'tag_2', ... ] }
-  const req = support.tags.add({ type: 'tickets', id: 123, data });
+
+  const req = tags.add({ type: 'tickets', id: 123, data });
+
   const res = await axios(req);
 } catch (error) {
   // ...
@@ -89,7 +85,13 @@ try {
 
 Search, Users, End Users, Groups, Group Memberships, Custom Agent Roles, Organizations, Organization Subscriptions, Organization Memberships, Tickets, Ticket Import, Suspended Tickets, Ticket Comments, Ticket Metrics, Ticket Activities, Tags, Views, Ticket Forms, Ticket Fields, User Fields, Organization Fields
 
-#### Under Construction
+### Sunshine API
+
+Custom Object Types, Custom Object Records
+
+### Under Construction
+
+#### Support
 
 - [ ] Brands
 - [ ] User Identities

index.js

@@ -1,3 +1,24 @@
-module.exports = {
-  v2: ({ instance, headers }) => require('./src/v2')({ instance, headers })
+const fs = require('fs');
+const path = require('path');
+const { validate } = require('./src/utils/options');
+const load = require('./src/utils/load');
+
+// Read folders to list APIs ('/src/api/*')
+const APIs = fs.readdirSync(path.resolve(__dirname, 'src/api'));
+
+// Load each API (support, sunshine, ...)
+const zdAPIs = {};
+APIs.forEach(api => (zdAPIs[api] = load(api)));
+
+// Initialize each API
+const init = (options = {}) => {
+  const { error } = validate(options);
+  if (error) throw new Error(error.details[0].message);
+
+  const initialized = {};
+  for (const api in zdAPIs) initialized[api] = zdAPIs[api].init(options);
+
+  return initialized;
 };
+
+module.exports = { init, ...zdAPIs };

package.json

@@ -27,7 +27,8 @@
     "src/*"
   ],
   "dependencies": {
-    "@hapi/joi": "^16.1.1"
+    "@hapi/joi": "^16.1.1",
+    "js-base64": "^2.5.1"
   },
   "devDependencies": {
     "@types/jest": "^24.0.18",

src/api/sunshine/object_records.js

@@ -0,0 +1,178 @@
+const Joi = require('@hapi/joi');
+const { validate, prepare } = require('../../utils/options');
+
+// Validation
+const _object_type = Joi.string().min(1);
+const _type = Joi.string().min(1);
+const _id = Joi.number().min(1);
+const _ids = Joi.string().min(1);
+const _relationship_type = Joi.string().min(1);
+const _external_id = Joi.string().min(1);
+const _external_ids = Joi.string().min(1);
+const _data = Joi.object();
+
+// Initialize Endpoint
+module.exports = (options = {}) => {
+  const { error } = validate(options);
+  if (error) throw new Error(error.details[0].message);
+
+  const { url, headers } = prepare(options);
+
+  return {
+    /**
+     * List Object Records (by Object Type, IDs, or Relationship)
+     *
+     * GET /api/sunshine/objects/records?type={object_type}
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#list-object-records-by-type
+     *
+     * GET /api/sunshine/objects/records?ids={id, id, ...}
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#list-object-records-by-id
+     *
+     * GET /api/sunshine/objects/records/{id}/related/{relationship_type}
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#list-related-object-records
+     */
+    list: (options = {}) => {
+      const { error } = Joi.object({
+        object_type: _object_type,
+        ids: _ids,
+        id: _id,
+        relationship_type: _relationship_type
+      }).validate(options);
+      if (error) throw new Error(error.details[0].message);
+
+      const { object_type, ids, id, relationship_type } = options;
+      if (!object_type && !ids && !(id && relationship_type))
+        throw new Error(
+          'object_type, ids, or id with relationship_type required'
+        );
+
+      return {
+        method: 'GET',
+        url: `${url}/api/sunshine/objects/records${
+          object_type
+            ? `?type=${object_type}`
+            : ids
+            ? `?ids=${ids}`
+            : `/${id}/related/${relationship_type}`
+        }`,
+        headers
+      };
+    },
+
+    /**
+     * Show Object Record (by ID,  External ID, or External IDs)
+     *
+     * GET /api/sunshine/objects/records/{id}
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#show-object-record
+     *
+     * GET /api/sunshine/objects/records?type={object_type}&external_id={id}
+     * GET /api/sunshine/objects/records?type={object_type}&external_ids={id, id, ...}
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#show-object-record-by-external-id
+     *
+     */
+    show: (options = {}) => {
+      const { error } = Joi.object({
+        id: _id,
+        object_type: _object_type,
+        external_id: _external_id,
+        external_ids: _external_ids
+      }).validate(options);
+      if (error) throw new Error(error.details[0].message);
+
+      const { id, object_type, external_id, external_ids } = options;
+      if (!id && !object_type) throw new Error('id or object_type required');
+      if (object_type && !external_id && !external_ids)
+        throw new Error(
+          'object_type requires either external_id or external_ids set'
+        );
+
+      return {
+        method: 'GET',
+        url: `${url}/api/sunshine/objects/records${
+          id
+            ? `/${id}`
+            : `?type=${object_type}&external_id${
+                external_id ? `=${external_id}` : `s=${external_ids}`
+              }`
+        }`,
+        headers
+      };
+    },
+
+    /**
+     * Create Object Record
+     *
+     * POST /api/sunshine/objects/records
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#create-object-record
+     */
+    create: (options = {}) => {
+      const { error } = Joi.object({
+        data: _data.required()
+      }).validate(options);
+      if (error) throw new Error(error.details[0].message);
+
+      const { data } = options;
+      return {
+        method: 'POST',
+        url: `${url}/api/sunshine/objects/records`,
+        headers,
+        data
+      };
+    },
+
+    /**
+     * Update Object Record (or Set by External ID)
+     *
+     * PATCH /api/sunshine/objects/records/{id}
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#update-object-record
+     *
+     * PATCH /api/sunshine/objects/records
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#set-object-record-by-external-id
+     */
+    update: (options = {}) => {
+      const { error } = Joi.object({
+        id: _id,
+        data: _data.required()
+      }).validate(options);
+      if (error) throw new Error(error.details[0].message);
+
+      const { id, data } = options;
+      return {
+        method: 'PATCH',
+        url: `${url}/api/sunshine/objects/records${id ? `/${id}` : ''}`,
+        headers,
+        data
+      };
+    },
+
+    /**
+     * Delete Object Record
+     *
+     * DELETE /api/sunshine/objects/records/{id}
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#delete-object-record
+     *
+     * DELETE /api/sunshine/objects/records?external_id={external_id}&type={type}
+     * https://developer.zendesk.com/rest_api/docs/sunshine/resources#delete-object-record-by-external-id
+     */
+    delete: (options = {}) => {
+      const { error } = Joi.object({
+        id: _id,
+        external_id: _external_id,
+        type: _type
+      }).validate(options);
+      if (error) throw new Error(error.details[0].message);
+
+      const { id, external_id, type } = options;
+      if (!id && !(external_id && type))
+        throw new Error('id or external_id with type required');
+
+      return {
+        method: 'DELETE',
+        url: `${url}/api/sunshine/objects/records${
+          id ? `/${id}` : `?external_id=${external_id}&type=${type}`
+        }`,
+        headers
+      };
+    }
+  };
+};