✨ Add types for integration entity concept

Author: lauravikanis

README.md

@@ -1,12 +1,32 @@
 # sipgate Integration Bridge Framework
 
-This is the sipgate Integration Bridge framework to integrate sipgate apps with external services. It provides a unified way to connect apps to any provider of external data management, like contacts or calendar events.
+This is the sipgate Integration Bridge framework to integrate sipgate apps with external services. It provides a unified
+way to connect apps to any provider of external data management, like contacts or calendar events.
+
+## Developing locally
+
+To test your changes to the integration-bridge framework locally, follow these steps:
+
+* Run `npm run dev` in sipgate-integration-bridge repo
+* Run `npm link @sipgate/integration-bridge` in *-integration-bridge-repo
+* Add the following to your `tsconfig.json`:
+  ```json
+  {
+    "compilerOptions": {
+      "paths": {
+        "@sipgate/integration-bridge": ["node_modules/@sipgate/integration-bridge/src"]
+      }
+    }
+  }
+  ```
 
 ## Publishing a version
 To publish a new framework version, simply create a new tag and push it:
 ```
+
 npm version <minor|patch>
 git push --follow-tags
+
 ```
 This will automatically publish the package in the npm registry via the CI pipeline. 
 
@@ -31,27 +51,27 @@ The minimum adapter implements the `getContacts` method:
 const bridge = require("@sipgate/integration-bridge");
 const fetch = require("node-fetch");
 
-const { ServerError } = bridge;
+const {ServerError} = bridge;
 
 const adapter = {
-  getContacts: async ({ apiKey, apiUrl }) => {
-    // Fetch contacts using apiUrl and apiKey
-    const response = await fetch(`${apiUrl}/api/contacts`, {
-      headers: { Authorization: `Bearer ${apiKey}` },
-    });
-
-    if (response.status === 401) {
-      throw new ServerError(401, "Unauthorized");
-    }
-
-    if (!response.ok) {
-      throw new ServerError(500, "Could not fetch contacts");
-    }
-    
-    // TODO: Convert contacts to the structure below
-    const contacts = await response.json();
-    return contacts;
-  },
+    getContacts: async ({apiKey, apiUrl}) => {
+        // Fetch contacts using apiUrl and apiKey
+        const response = await fetch(`${apiUrl}/api/contacts`, {
+            headers: {Authorization: `Bearer ${apiKey}`},
+        });
+
+        if (response.status === 401) {
+            throw new ServerError(401, "Unauthorized");
+        }
+
+        if (!response.ok) {
+            throw new ServerError(500, "Could not fetch contacts");
+        }
+
+        // TODO: Convert contacts to the structure below
+        const contacts = await response.json();
+        return contacts;
+    },
 };
 
 bridge.start(adapter);
@@ -61,21 +81,37 @@ Contacts are accepted in this format:
 
 ```js
 {
-  id: "abc123",
-  // Provide either the full name or first and last name, not both
-  name: null, // or null
-  firstName: "Walter", // or null
-  lastName: "Geoffrey", // or null
-  organization: "Rocket Science Inc.", // or null
-  contactUrl: "http://myapp.com/contacts/abc123", // or null
-  avatarUrl: "http://myapp.com/avatar/abc123.png", // or null
-  email: "[email protected]", // or null
-  phoneNumbers: [
-    {
-      label: "MOBILE", // or "WORK" or "HOME"
-      phoneNumber: "+4915799912345"
-    }
-  ]
+    id: "abc123",
+        // Provide either the full name or first and last name, not both
+        name
+:
+    null, // or null
+        firstName
+:
+    "Walter", // or null
+        lastName
+:
+    "Geoffrey", // or null
+        organization
+:
+    "Rocket Science Inc.", // or null
+        contactUrl
+:
+    "http://myapp.com/contacts/abc123", // or null
+        avatarUrl
+:
+    "http://myapp.com/avatar/abc123.png", // or null
+        email
+:
+    "[email protected]", // or null
+        phoneNumbers
+:
+    [
+        {
+            label: "MOBILE", // or "WORK" or "HOME"
+            phoneNumber: "+4915799912345"
+        }
+    ]
 }
 ```
 
@@ -87,4 +123,5 @@ The sipgate Integration Bridge supports configuration through the following envi
 - `OAUTH2_IDENTIFIER`: Name of the Integration to identify credentials in uppercase e. g. "MY_CRM"
 - `REDIS_URL`: URL of a Redis instance to cache responses, otherwise memory cache will be used
 - `CACHE_DISABLED`: Disable caching
-- `CACHE_REFRESH_INTERVAL`: Time a contact in cache is not refreshed (in seconds), only used if redis or memory cache is active
+- `CACHE_REFRESH_INTERVAL`: Time a contact in cache is not refreshed (in seconds), only used if redis or memory cache is
+  active

package.json

@@ -8,16 +8,6 @@
     "dist"
   ],
   "repository": "github:sipgate/integration-bridge",
-  "contributors": [
-    {
-      "name": "Benjamin Kluck",
-      "email": "[email protected]"
-    },
-    {
-      "name": "Felix Gladisch",
-      "email": "[email protected]"
-    }
-  ],
   "bugs": {
     "url": "https://github.com/sipgate/integration-bridge/issues"
   },
@@ -28,17 +18,17 @@
   ],
   "license": "UNLICENSED",
   "scripts": {
+    "dev": "npm run build && npm link && tsc --watch",
     "prepare": "husky install",
     "test": "jest",
     "compile": "tsc",
     "build": "npm test && rimraf dist && npm run compile",
     "precommit": "lint-staged",
     "prepublishOnly": "npm run build",
-    "format": "prettier --write '**/*.ts'",
-    "link": "npm link"
+    "format": "prettier --write '**/*.ts'"
   },
   "lint-staged": {
-    "*.{ts}": [
+    "*.ts": [
       "prettier --write",
       "git add"
     ]

src/index.ts

@@ -4,7 +4,12 @@ import cors from "cors";
 import express from "express";
 import { Server } from "http";
 import { errorHandlerMiddleware, extractHeaderMiddleware } from "./middlewares";
-import { Adapter, ContactCache, Controller } from "./models";
+import {
+  Adapter,
+  ContactCache,
+  Controller,
+  IntegrationEntityBridgeRequest,
+} from "./models";
 import { CustomRouter } from "./models/custom-router.model";
 import { getContactCache } from "./util/get-contact-cache";
 
@@ -32,7 +37,6 @@ export function start(
   cache = getContactCache();
 
   const controller: Controller = new Controller(adapter, cache);
-
   app.get("/contacts", (req, res, next) =>
     controller.getContacts(req, res, next)
   );
@@ -45,6 +49,11 @@ export function start(
   app.delete("/contacts/:id", (req, res, next) =>
     controller.deleteContact(req, res, next)
   );
+  app.get(
+    "/entity/:type/:id",
+    (req: IntegrationEntityBridgeRequest, res, next) =>
+      controller.getEntity(req, res, next)
+  );
   app.get("/calendar", (req, res, next) =>
     controller.getCalendarEvents(req, res, next)
   );

src/models/adapter.model.ts

@@ -8,7 +8,9 @@ import {
   Contact,
   ContactTemplate,
   ContactUpdate,
+  LabeledIntegrationEntity,
 } from ".";
+import { IntegrationEntityType } from "./integration-entity.model";
 
 export interface Adapter {
   getToken?: (config: Config) => Promise<{ apiKey: string }>;
@@ -43,6 +45,11 @@ export interface Adapter {
   ) => Promise<void>;
   deleteCalendarEvent?: (config: Config, id: string) => Promise<void>;
   handleCallEvent?: (config: Config, event: CallEvent) => Promise<string>;
+  getEntity?: (
+    providerConfig: Config,
+    id: string,
+    type: IntegrationEntityType
+  ) => Promise<LabeledIntegrationEntity>;
   handleConnectedEvent?: (config: Config) => Promise<void>;
   getHealth?: () => Promise<void>;
   getOAuth2RedirectUrl?: (req?: Request, res?: Response) => Promise<string>;

src/models/bridge-request.model.ts

@@ -1,11 +1,11 @@
+import { IntegrationEntityType } from "./integration-entity.model";
 import { Request } from "express";
 import { Config } from "./config.model";
-import { UpdateCallEventBody } from "./call-event.model";
 
 export interface BridgeRequest extends Request {
   providerConfig?: Config;
 }
 
-export interface UpdateCallEventBridgeRequest extends BridgeRequest {
-  body: UpdateCallEventBody;
+export interface IntegrationEntityBridgeRequest extends BridgeRequest {
+  params: { id: string; type: IntegrationEntityType };
 }

src/models/contact.model.ts

@@ -1,3 +1,5 @@
+import { IntegrationEntity } from "./integration-entity.model";
+
 export enum PhoneNumberLabel {
   WORK = "WORK",
   MOBILE = "MOBILE",
@@ -37,6 +39,7 @@ export type ContactResult = {
   contactUrl: string | null;
   avatarUrl: string | null;
   readonly?: boolean;
+  relatesTo?: IntegrationEntity[];
 };
 
 export type ContactTemplate = BaseContact & {

src/models/controller.model.ts

@@ -3,7 +3,6 @@ import { NextFunction, Request, Response } from "express";
 import { stringify } from "querystring";
 import {
   Adapter,
-  BridgeRequest,
   CalendarEvent,
   CalendarEventTemplate,
   CallEvent,
@@ -16,12 +15,16 @@ import {
 import { calendarEventsSchema, contactsSchema } from "../schemas";
 import { anonymizeKey } from "../util/anonymize-key";
 import { shouldSkipCallEvent } from "../util/call-event.util";
+import { errorLogger, infoLogger } from "../util/logger.util";
 import { parsePhoneNumber } from "../util/phone-number-utils";
 import { validate } from "../util/validate";
 import { APIContact } from "./api-contact.model";
+import {
+  BridgeRequest,
+  IntegrationEntityBridgeRequest,
+} from "./bridge-request.model";
 import { CacheItemStateType } from "./cache-item-state.model";
 import { CalendarFilterOptions } from "./calendar-filter-options.model";
-import { errorLogger, infoLogger } from "../util/logger.util";
 import { IntegrationErrorType } from "./integration-error.model";
 
 const CONTACT_FETCH_TIMEOUT: number = 3000;
@@ -585,6 +588,36 @@ export class Controller {
     }
   }
 
+  public async getEntity(
+    req: IntegrationEntityBridgeRequest,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> {
+    const { providerConfig } = req;
+    try {
+      if (!providerConfig) {
+        throw new ServerError(400, "Missing parameters");
+      }
+
+      if (!this.adapter.getEntity) {
+        throw new ServerError(501, "Fetching Entity is not implemented");
+      }
+
+      const fetchedEntity = await this.adapter.getEntity(
+        providerConfig,
+        req.params.id,
+        req.params.type
+      );
+
+      infoLogger(`[${fetchedEntity}] `, providerConfig);
+
+      res.status(200).send(fetchedEntity);
+    } catch (error) {
+      errorLogger("Could not get entity:", providerConfig, error);
+      next(error);
+    }
+  }
+
   public async getHealth(
     req: BridgeRequest,
     res: Response,

src/models/index.ts

@@ -12,3 +12,4 @@ export * from "./custom-router.model";
 export * from "./server-error.model";
 export * from "./user.model";
 export * from "./integration-error.model";
+export * from "./integration-entity.model";

src/models/integration-entity.model.ts

@@ -0,0 +1,14 @@
+export type IntegrationEntity = {
+  id: string;
+  type: IntegrationEntityType;
+  source: string;
+};
+
+export type LabeledIntegrationEntity = IntegrationEntity & {
+  label: string;
+};
+
+export enum IntegrationEntityType {
+  DEALS = "deals",
+  COMPANIES = "companies",
+}