@unito/integration-sdk 1.0.15 → 1.0.16

package/dist/src/handler.d.ts

@@ -1,6 +1,6 @@
 import { Router } from 'express';
 import * as API from '@unito/integration-api';
-import { GetBlobContext, GetItemContext, GetCollectionContext, CreateItemContext, UpdateItemContext, DeleteItemContext, GetCredentialAccountContext, ParseWebhooksContext, UpdateWebhookSubscriptionsContext, AcknowledgeWebhooksContext } from './resources/context.js';
+import { GetBlobContext, GetItemContext, GetCollectionContext, CreateBlobContext, CreateItemContext, UpdateItemContext, DeleteItemContext, GetCredentialAccountContext, ParseWebhooksContext, UpdateWebhookSubscriptionsContext, AcknowledgeWebhooksContext } from './resources/context.js';
 /**
  * Handler called to get an individual item.
  *
@@ -15,6 +15,13 @@ export type GetItemHandler = (context: GetItemContext<any, any>) => Promise<API.
  * @return An {@link API.Collection} containing requested items and a link to the next page, if applicable.
  */
 export type GetCollectionHandler = (context: GetCollectionContext<any, any>) => Promise<API.Collection>;
+/**
+ * Handler called to create an item.
+ *
+ * @param context {@link CreateBlobContext}
+ * @returns An {@link API.Item} containing a path to the created item.
+ */
+export type CreateBlobHandler = (context: CreateBlobContext<any, any>) => Promise<API.Item>;
 /**
  * Handler called to create an item.
  *
@@ -86,12 +93,14 @@ export type AcknowledgeWebhooksHandler = (context: AcknowledgeWebhooksContext<an
 export type ItemHandlers = {
     getItem?: GetItemHandler;
     getCollection?: GetCollectionHandler;
+    createBlob?: CreateBlobHandler;
     createItem?: CreateItemHandler;
     updateItem?: UpdateItemHandler;
     deleteItem?: DeleteItemHandler;
 };
 export type BlobHandlers = {
     getBlob: GetBlobHandler;
+    createBlob?: CreateBlobHandler;
 };
 export type CredentialAccountHandlers = {
     getCredentialAccount: GetCredentialAccountHandler;

package/dist/src/handler.js

@@ -1,6 +1,7 @@
 import { Router } from 'express';
 import { InvalidHandler } from './errors.js';
 import { UnauthorizedError, BadRequestError } from './httpErrors.js';
+import busboy from 'busboy';
 function assertValidPath(path) {
     if (!path.startsWith('/')) {
         throw new InvalidHandler(`The provided path '${path}' is invalid. All paths must start with a '/'.`);
@@ -121,6 +122,39 @@ export class Handler {
                 res.status(201).send(createItemSummary);
             });
         }
+        if (this.handlers.createBlob) {
+            const handler = this.handlers.createBlob;
+            console.debug(`  Enabling createBlob at POST ${this.pathWithIdentifier}`);
+            router.post(this.path, async (req, res) => {
+                if (!res.locals.credentials) {
+                    throw new UnauthorizedError();
+                }
+                /**
+                 * Some of the integrations, servicenow for example,
+                 * will need to add more information to the form data that is being passed to the upload attachment handler.
+                 * This is why we need to use busboy to parse the form data, extract the information about the file and pass it to the handler.
+                 */
+                const bb = busboy({ headers: req.headers });
+                bb.on('file', async (_name, file, info) => {
+                    const createdBlob = await handler({
+                        credentials: res.locals.credentials,
+                        secrets: res.locals.secrets,
+                        body: {
+                            file: file,
+                            mimeType: info.mimeType,
+                            encoding: info.encoding,
+                            filename: info.filename,
+                        },
+                        logger: res.locals.logger,
+                        signal: res.locals.signal,
+                        params: req.params,
+                        query: req.query,
+                    });
+                    res.status(201).send(createdBlob);
+                });
+                req.pipe(bb);
+            });
+        }
         if (this.handlers.getItem) {
             const handler = this.handlers.getItem;
             console.debug(`  Enabling getItem at GET ${this.pathWithIdentifier}`);

package/dist/src/index.cjs

@@ -4,6 +4,8 @@ var integrationApi = require('@unito/integration-api');
 var cachette = require('cachette');
 var crypto = require('crypto');
 var express = require('express');
+var busboy = require('busboy');
+var https = require('https');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -667,6 +669,39 @@ class Handler {
                 res.status(201).send(createItemSummary);
             });
         }
+        if (this.handlers.createBlob) {
+            const handler = this.handlers.createBlob;
+            console.debug(`  Enabling createBlob at POST ${this.pathWithIdentifier}`);
+            router.post(this.path, async (req, res) => {
+                if (!res.locals.credentials) {
+                    throw new UnauthorizedError();
+                }
+                /**
+                 * Some of the integrations, servicenow for example,
+                 * will need to add more information to the form data that is being passed to the upload attachment handler.
+                 * This is why we need to use busboy to parse the form data, extract the information about the file and pass it to the handler.
+                 */
+                const bb = busboy({ headers: req.headers });
+                bb.on('file', async (_name, file, info) => {
+                    const createdBlob = await handler({
+                        credentials: res.locals.credentials,
+                        secrets: res.locals.secrets,
+                        body: {
+                            file: file,
+                            mimeType: info.mimeType,
+                            encoding: info.encoding,
+                            filename: info.filename,
+                        },
+                        logger: res.locals.logger,
+                        signal: res.locals.signal,
+                        params: req.params,
+                        query: req.query,
+                    });
+                    res.status(201).send(createdBlob);
+                });
+                req.pipe(bb);
+            });
+        }
         if (this.handlers.getItem) {
             const handler = this.handlers.getItem;
             console.debug(`  Enabling getItem at GET ${this.pathWithIdentifier}`);
@@ -1080,6 +1115,52 @@ class Provider {
             },
         });
     }
+    async postForm(endpoint, form, options) {
+        const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
+        const absoluteUrl = this.generateAbsoluteUrl(providerUrl, endpoint, options.queryParams);
+        const headers = { ...form.getHeaders(), ...providerHeaders, ...options.additionnalheaders };
+        const reqOptions = {
+            method: 'POST',
+            headers,
+        };
+        /**
+         * For some obscure reason we can't use the fetch API to send a form data, so we have to use the native https module
+         * It seems that there is a miscalculation of the Content-Length headers that generates an error :
+         *  --> headers length is different from the actual body length
+         * The goto solution recommended across the internet for this, is to simply drop the header.
+         * However, some integrations like Servicenow, will not accept the request if it doesn't contain that header
+         */
+        const callToProvider = async () => {
+            return new Promise((resolve, reject) => {
+                try {
+                    const request = https.request(absoluteUrl, reqOptions, response => {
+                        response.setEncoding('utf8');
+                        let responseBody = '';
+                        response.on('data', chunk => {
+                            responseBody += chunk;
+                        });
+                        response.on('end', () => {
+                            try {
+                                const body = JSON.parse(responseBody);
+                                resolve({ status: 201, headers: response.headers, body });
+                            }
+                            catch (error) {
+                                reject(this.handleError(500, `Failed to parse response body: "${error}"`));
+                            }
+                        });
+                    });
+                    request.on('error', error => {
+                        reject(this.handleError(400, `Error while calling the provider: "${error}"`));
+                    });
+                    form.pipe(request);
+                }
+                catch (error) {
+                    reject(this.handleError(500, `Unexpected error while calling the provider: "${error}"`));
+                }
+            });
+        };
+        return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
+    }
     /**
      * Performs a PUT request to the provider.
      *
@@ -1144,8 +1225,7 @@ class Provider {
             },
         });
     }
-    async fetchWrapper(endpoint, body, options) {
-        const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
+    generateAbsoluteUrl(providerUrl, endpoint, queryParams) {
         let absoluteUrl;
         if (/^https?:\/\//.test(endpoint)) {
             absoluteUrl = endpoint;
@@ -1153,9 +1233,14 @@ class Provider {
         else {
             absoluteUrl = [providerUrl, endpoint.charAt(0) === '/' ? endpoint.substring(1) : endpoint].join('/');
         }
-        if (options.queryParams) {
-            absoluteUrl = `${absoluteUrl}?${new URLSearchParams(options.queryParams)}`;
+        if (queryParams) {
+            absoluteUrl = `${absoluteUrl}?${new URLSearchParams(queryParams)}`;
         }
+        return absoluteUrl;
+    }
+    async fetchWrapper(endpoint, body, options) {
+        const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
+        const absoluteUrl = this.generateAbsoluteUrl(providerUrl, endpoint, options.queryParams);
         const headers = { ...options.defaultHeaders, ...providerHeaders, ...options.additionnalheaders };
         let stringifiedBody = null;
         if (body) {

package/dist/src/resources/context.d.ts

@@ -10,6 +10,7 @@ type Query = {
     [key: string]: undefined | string | string[] | Query | Query[];
 };
 type CreateItemBody = API.CreateItemRequestPayload;
+type CreateBlobBody = API.CreateBlobRequestPayload;
 type UpdateItemBody = API.UpdateItemRequestPayload;
 /**
  * The base context object is passed to every handler function.
@@ -103,6 +104,9 @@ export type GetCollectionContext<P extends Maybe<Params> = Empty, Q extends Quer
 export type CreateItemContext<P extends Maybe<Params> = Empty, Q extends Maybe<Query> = Empty, B extends CreateItemBody = API.CreateItemRequestPayload> = Context<P, Q> & {
     body: B;
 };
+export type CreateBlobContext<P extends Maybe<Params> = Empty, Q extends Maybe<Query> = Empty, B extends CreateBlobBody = API.CreateBlobRequestPayload> = Context<P, Q> & {
+    body: B;
+};
 export type UpdateItemContext<P extends Maybe<Params> = Empty, Q extends Maybe<Query> = Empty, B extends UpdateItemBody = API.UpdateItemRequestPayload> = Context<P, Q> & {
     body: B;
 };

package/dist/src/resources/provider.d.ts

@@ -1,3 +1,4 @@
+import FormData from 'form-data';
 import * as HttpErrors from '../httpErrors.js';
 import { Credentials } from '../middlewares/credentials.js';
 import Logger from '../resources/logger.js';
@@ -143,6 +144,7 @@ export declare class Provider {
      * @returns The {@link Response} extracted from the provider.
      */
     post<T>(endpoint: string, body: Record<string, unknown>, options: RequestOptions): Promise<Response<T>>;
+    postForm<T>(endpoint: string, form: FormData, options: RequestOptions): Promise<Response<T>>;
     /**
      * Performs a PUT request to the provider.
      *
@@ -181,6 +183,7 @@ export declare class Provider {
      * @returns The {@link Response} extracted from the provider.
      */
     delete<T = undefined>(endpoint: string, options: RequestOptions): Promise<Response<T>>;
+    private generateAbsoluteUrl;
     private fetchWrapper;
     private handleError;
 }

package/dist/src/resources/provider.js

@@ -1,3 +1,4 @@
+import https from 'https';
 import { buildHttpError } from '../errors.js';
 /**
  * The Provider class is a wrapper around the fetch function to call a provider's HTTP API.
@@ -108,6 +109,52 @@ export class Provider {
             },
         });
     }
+    async postForm(endpoint, form, options) {
+        const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
+        const absoluteUrl = this.generateAbsoluteUrl(providerUrl, endpoint, options.queryParams);
+        const headers = { ...form.getHeaders(), ...providerHeaders, ...options.additionnalheaders };
+        const reqOptions = {
+            method: 'POST',
+            headers,
+        };
+        /**
+         * For some obscure reason we can't use the fetch API to send a form data, so we have to use the native https module
+         * It seems that there is a miscalculation of the Content-Length headers that generates an error :
+         *  --> headers length is different from the actual body length
+         * The goto solution recommended across the internet for this, is to simply drop the header.
+         * However, some integrations like Servicenow, will not accept the request if it doesn't contain that header
+         */
+        const callToProvider = async () => {
+            return new Promise((resolve, reject) => {
+                try {
+                    const request = https.request(absoluteUrl, reqOptions, response => {
+                        response.setEncoding('utf8');
+                        let responseBody = '';
+                        response.on('data', chunk => {
+                            responseBody += chunk;
+                        });
+                        response.on('end', () => {
+                            try {
+                                const body = JSON.parse(responseBody);
+                                resolve({ status: 201, headers: response.headers, body });
+                            }
+                            catch (error) {
+                                reject(this.handleError(500, `Failed to parse response body: "${error}"`));
+                            }
+                        });
+                    });
+                    request.on('error', error => {
+                        reject(this.handleError(400, `Error while calling the provider: "${error}"`));
+                    });
+                    form.pipe(request);
+                }
+                catch (error) {
+                    reject(this.handleError(500, `Unexpected error while calling the provider: "${error}"`));
+                }
+            });
+        };
+        return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
+    }
     /**
      * Performs a PUT request to the provider.
      *
@@ -172,8 +219,7 @@ export class Provider {
             },
         });
     }
-    async fetchWrapper(endpoint, body, options) {
-        const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
+    generateAbsoluteUrl(providerUrl, endpoint, queryParams) {
         let absoluteUrl;
         if (/^https?:\/\//.test(endpoint)) {
             absoluteUrl = endpoint;
@@ -181,9 +227,14 @@ export class Provider {
         else {
             absoluteUrl = [providerUrl, endpoint.charAt(0) === '/' ? endpoint.substring(1) : endpoint].join('/');
         }
-        if (options.queryParams) {
-            absoluteUrl = `${absoluteUrl}?${new URLSearchParams(options.queryParams)}`;
+        if (queryParams) {
+            absoluteUrl = `${absoluteUrl}?${new URLSearchParams(queryParams)}`;
         }
+        return absoluteUrl;
+    }
+    async fetchWrapper(endpoint, body, options) {
+        const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
+        const absoluteUrl = this.generateAbsoluteUrl(providerUrl, endpoint, options.queryParams);
         const headers = { ...options.defaultHeaders, ...providerHeaders, ...options.additionnalheaders };
         let stringifiedBody = null;
         if (body) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-sdk",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "Integration SDK",
   "type": "module",
   "types": "dist/src/index.d.ts",
@@ -33,6 +33,7 @@
     "ci:test": "npm run test"
   },
   "devDependencies": {
+    "@types/busboy": "^1.5.4",
     "@types/express": "4.x",
     "@types/node": "20.x",
     "@typescript-eslint/eslint-plugin": "7.x",
@@ -46,8 +47,10 @@
   },
   "dependencies": {
     "@unito/integration-api": "0.x",
+    "busboy": "^1.6.0",
     "cachette": "2.x",
-    "express": "^5.0.0-beta.3"
+    "express": "^5.0.0-beta.3",
+    "form-data": "^4.0.0"
   },
   "keywords": [
     "typescript",

package/src/handler.ts

@@ -6,6 +6,7 @@ import {
   GetBlobContext,
   GetItemContext,
   GetCollectionContext,
+  CreateBlobContext,
   CreateItemContext,
   UpdateItemContext,
   DeleteItemContext,
@@ -15,6 +16,7 @@ import {
   AcknowledgeWebhooksContext,
 } from './resources/context.js';
 
+import busboy, { FileInfo } from 'busboy';
 /**
  * Handler called to get an individual item.
  *
@@ -31,6 +33,14 @@ export type GetItemHandler = (context: GetItemContext<any, any>) => Promise<API.
  */
 export type GetCollectionHandler = (context: GetCollectionContext<any, any>) => Promise<API.Collection>;
 
+/**
+ * Handler called to create an item.
+ *
+ * @param context {@link CreateBlobContext}
+ * @returns An {@link API.Item} containing a path to the created item.
+ */
+export type CreateBlobHandler = (context: CreateBlobContext<any, any>) => Promise<API.Item>;
+
 /**
  * Handler called to create an item.
  *
@@ -118,6 +128,7 @@ export type AcknowledgeWebhooksHandler = (
 export type ItemHandlers = {
   getItem?: GetItemHandler;
   getCollection?: GetCollectionHandler;
+  createBlob?: CreateBlobHandler;
   createItem?: CreateItemHandler;
   updateItem?: UpdateItemHandler;
   deleteItem?: DeleteItemHandler;
@@ -125,6 +136,7 @@ export type ItemHandlers = {
 
 export type BlobHandlers = {
   getBlob: GetBlobHandler;
+  createBlob?: CreateBlobHandler;
 };
 
 export type CredentialAccountHandlers = {
@@ -323,6 +335,43 @@ export class Handler {
       });
     }
 
+    if (this.handlers.createBlob) {
+      const handler = this.handlers.createBlob;
+
+      console.debug(`  Enabling createBlob at POST ${this.pathWithIdentifier}`);
+
+      router.post(this.path, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+        /**
+         * Some of the integrations, servicenow for example,
+         * will need to add more information to the form data that is being passed to the upload attachment handler.
+         * This is why we need to use busboy to parse the form data, extract the information about the file and pass it to the handler.
+         */
+        const bb = busboy({ headers: req.headers });
+        bb.on('file', async (_name, file, info: FileInfo) => {
+          const createdBlob = await handler({
+            credentials: res.locals.credentials,
+            secrets: res.locals.secrets,
+            body: {
+              file: file,
+              mimeType: info.mimeType,
+              encoding: info.encoding,
+              filename: info.filename,
+            },
+            logger: res.locals.logger,
+            signal: res.locals.signal,
+            params: req.params,
+            query: req.query,
+          });
+          res.status(201).send(createdBlob);
+        });
+
+        req.pipe(bb);
+      });
+    }
+
     if (this.handlers.getItem) {
       const handler = this.handlers.getItem;
 

package/src/resources/context.ts

@@ -1,6 +1,5 @@
 /* c8 ignore start */
 import * as API from '@unito/integration-api';
-
 import Logger from './logger.js';
 import { Credentials } from '../middlewares/credentials.js';
 import { Secrets } from 'src/middlewares/secrets.js';
@@ -13,6 +12,7 @@ type Query = {
   [key: string]: undefined | string | string[] | Query | Query[];
 };
 type CreateItemBody = API.CreateItemRequestPayload;
+type CreateBlobBody = API.CreateBlobRequestPayload;
 type UpdateItemBody = API.UpdateItemRequestPayload;
 
 /**
@@ -114,6 +114,12 @@ export type CreateItemContext<
   B extends CreateItemBody = API.CreateItemRequestPayload,
 > = Context<P, Q> & { body: B };
 
+export type CreateBlobContext<
+  P extends Maybe<Params> = Empty,
+  Q extends Maybe<Query> = Empty,
+  B extends CreateBlobBody = API.CreateBlobRequestPayload,
+> = Context<P, Q> & { body: B };
+
 export type UpdateItemContext<
   P extends Maybe<Params> = Empty,
   Q extends Maybe<Query> = Empty,

package/src/resources/provider.ts

@@ -1,3 +1,6 @@
+import https from 'https';
+import FormData from 'form-data';
+
 import { buildHttpError } from '../errors.js';
 import * as HttpErrors from '../httpErrors.js';
 import { Credentials } from '../middlewares/credentials.js';
@@ -177,6 +180,57 @@ export class Provider {
     });
   }
 
+  public async postForm<T>(endpoint: string, form: FormData, options: RequestOptions): Promise<Response<T>> {
+    const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
+    const absoluteUrl = this.generateAbsoluteUrl(providerUrl, endpoint, options.queryParams);
+    const headers = { ...form.getHeaders(), ...providerHeaders, ...options.additionnalheaders };
+
+    const reqOptions = {
+      method: 'POST',
+      headers,
+    };
+    /**
+     * For some obscure reason we can't use the fetch API to send a form data, so we have to use the native https module
+     * It seems that there is a miscalculation of the Content-Length headers that generates an error :
+     *  --> headers length is different from the actual body length
+     * The goto solution recommended across the internet for this, is to simply drop the header.
+     * However, some integrations like Servicenow, will not accept the request if it doesn't contain that header
+     */
+    const callToProvider = async (): Promise<Response<T>> => {
+      return new Promise((resolve, reject) => {
+        try {
+          const request = https.request(absoluteUrl, reqOptions, response => {
+            response.setEncoding('utf8');
+            let responseBody = '';
+
+            response.on('data', chunk => {
+              responseBody += chunk;
+            });
+
+            response.on('end', () => {
+              try {
+                const body = JSON.parse(responseBody) as T;
+                resolve({ status: 201, headers: response.headers as unknown as Headers, body });
+              } catch (error) {
+                reject(this.handleError(500, `Failed to parse response body: "${error}"`));
+              }
+            });
+          });
+
+          request.on('error', error => {
+            reject(this.handleError(400, `Error while calling the provider: "${error}"`));
+          });
+
+          form.pipe(request);
+        } catch (error) {
+          reject(this.handleError(500, `Unexpected error while calling the provider: "${error}"`));
+        }
+      });
+    };
+
+    return this.rateLimiter ? this.rateLimiter(options, callToProvider) : callToProvider();
+  }
+
   /**
    * Performs a PUT request to the provider.
    *
@@ -248,13 +302,7 @@ export class Provider {
     });
   }
 
-  private async fetchWrapper<T>(
-    endpoint: string,
-    body: Record<string, unknown> | null,
-    options: RequestOptions & { defaultHeaders: { 'Content-Type'?: string; Accept?: string }; method: string },
-  ): Promise<Response<T>> {
-    const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
-
+  private generateAbsoluteUrl(providerUrl: string, endpoint: string, queryParams?: { [key: string]: string }): string {
     let absoluteUrl;
 
     if (/^https?:\/\//.test(endpoint)) {
@@ -263,10 +311,19 @@ export class Provider {
       absoluteUrl = [providerUrl, endpoint.charAt(0) === '/' ? endpoint.substring(1) : endpoint].join('/');
     }
 
-    if (options.queryParams) {
-      absoluteUrl = `${absoluteUrl}?${new URLSearchParams(options.queryParams)}`;
+    if (queryParams) {
+      absoluteUrl = `${absoluteUrl}?${new URLSearchParams(queryParams)}`;
     }
+    return absoluteUrl;
+  }
 
+  private async fetchWrapper<T>(
+    endpoint: string,
+    body: Record<string, unknown> | null,
+    options: RequestOptions & { defaultHeaders: { 'Content-Type'?: string; Accept?: string }; method: string },
+  ): Promise<Response<T>> {
+    const { url: providerUrl, headers: providerHeaders } = this.prepareRequest(options);
+    const absoluteUrl = this.generateAbsoluteUrl(providerUrl, endpoint, options.queryParams);
     const headers = { ...options.defaultHeaders, ...providerHeaders, ...options.additionnalheaders };
 
     let stringifiedBody: string | null = null;