@unito/integration-sdk 1.0.3 → 1.0.5

package/dist/src/handler.d.ts

@@ -1,6 +1,6 @@
 import { Router } from 'express';
 import * as API from '@unito/integration-api';
-import { GetItemContext, GetCollectionContext, CreateItemContext, UpdateItemContext, DeleteItemContext, GetCredentialAccountContext, ParseWebhooksContext, UpdateWebhookSubscriptionsContext, AcknowledgeWebhooksContext } from './resources/context.js';
+import { GetBlobContext, GetItemContext, GetCollectionContext, CreateItemContext, UpdateItemContext, DeleteItemContext, GetCredentialAccountContext, ParseWebhooksContext, UpdateWebhookSubscriptionsContext, AcknowledgeWebhooksContext } from './resources/context.js';
 /**
  * Handler called to get an individual item.
  *
@@ -35,6 +35,13 @@ export type UpdateItemHandler = (context: UpdateItemContext<any, any, any>) => P
  * @param context {@link DeleteItemContext}
  */
 export type DeleteItemHandler = (context: DeleteItemContext<any, any>) => Promise<void>;
+/**
+ * Handler called to get a Binary Large Object.
+ *
+ * @param context {@link BlobItemContext}
+ * @returns A {@link ReadableStream} of the Blob.
+ */
+export type GetBlobHandler = (context: GetBlobContext<any, any>) => Promise<ReadableStream<Uint8Array>>;
 /**
  * Handler called to retrieve the account details associated with the credentials.
  *
@@ -83,6 +90,9 @@ export type ItemHandlers = {
     updateItem?: UpdateItemHandler;
     deleteItem?: DeleteItemHandler;
 };
+export type BlobHandlers = {
+    getBlob: GetBlobHandler;
+};
 export type CredentialAccountHandlers = {
     getCredentialAccount: GetCredentialAccountHandler;
 };
@@ -95,7 +105,7 @@ export type WebhookSubscriptionHandlers = {
 export type AcknowledgeWebhookHandlers = {
     acknowledgeWebhooks: AcknowledgeWebhooksHandler;
 };
-export type HandlersInput = ItemHandlers | CredentialAccountHandlers | ParseWebhookHandlers | WebhookSubscriptionHandlers | AcknowledgeWebhookHandlers;
+export type HandlersInput = ItemHandlers | BlobHandlers | CredentialAccountHandlers | ParseWebhookHandlers | WebhookSubscriptionHandlers | AcknowledgeWebhookHandlers;
 export declare class Handler {
     private path;
     private pathWithIdentifier;

package/dist/src/handler.js

@@ -177,6 +177,41 @@ export class Handler {
                 res.status(204).send(null);
             });
         }
+        if (this.handlers.getBlob) {
+            console.debug(`  Enabling getBlob at GET ${this.pathWithIdentifier}`);
+            const handler = this.handlers.getBlob;
+            router.get(this.pathWithIdentifier, async (req, res) => {
+                if (!res.locals.credentials) {
+                    throw new UnauthorizedError();
+                }
+                const blob = await handler({
+                    credentials: res.locals.credentials,
+                    secrets: res.locals.secrets,
+                    logger: res.locals.logger,
+                    signal: res.locals.signal,
+                    params: req.params,
+                    query: req.query,
+                });
+                res.writeHead(200, {
+                    'Content-Type': 'application/octet-stream',
+                });
+                const reader = blob.getReader();
+                let isDone = false;
+                try {
+                    while (!isDone) {
+                        const chunk = await reader.read();
+                        isDone = chunk.done;
+                        if (chunk.value) {
+                            res.write(chunk.value);
+                        }
+                    }
+                }
+                finally {
+                    reader.releaseLock();
+                }
+                res.end();
+            });
+        }
         if (this.handlers.getCredentialAccount) {
             const handler = this.handlers.getCredentialAccount;
             console.debug(`  Enabling getCredentialAccount at GET ${this.pathWithIdentifier}`);

package/dist/src/helpers.d.ts

@@ -0,0 +1,15 @@
+import { FieldSchema } from '@unito/integration-api';
+import { Filter } from './index.js';
+/**
+ * Use this helper function to retrieve the applicable filters from the context object. While using filters
+ * directly from context might work, it doesn't offer any guarantees about the shape of the filters nor the
+ * validity of the fields against which the filters are applied. On the other hand, this function ensures that
+ * all filters are valid and that the fields against which the filters are applied are present in the schema.
+ *
+ * @param context The object containing the raw filters
+ * @param fields The schema of the item against which the filters are applied
+ * @returns The validated filters
+ */
+export declare const getApplicableFilters: (context: {
+    filters: Filter[];
+}, fields: FieldSchema[]) => Filter[];

package/dist/src/helpers.js

@@ -0,0 +1,28 @@
+/**
+ * Use this helper function to retrieve the applicable filters from the context object. While using filters
+ * directly from context might work, it doesn't offer any guarantees about the shape of the filters nor the
+ * validity of the fields against which the filters are applied. On the other hand, this function ensures that
+ * all filters are valid and that the fields against which the filters are applied are present in the schema.
+ *
+ * @param context The object containing the raw filters
+ * @param fields The schema of the item against which the filters are applied
+ * @returns The validated filters
+ */
+export const getApplicableFilters = (context, fields) => {
+    const applicableFilters = [];
+    for (const filter of context.filters) {
+        let field = undefined;
+        const filterFieldParts = filter.field.split(':', 2);
+        switch (filterFieldParts[0]) {
+            case 'semantic':
+                field = fields.find(f => f.semantic === filterFieldParts[1]);
+                break;
+            default:
+                field = fields.find(f => f.name === filterFieldParts[0]);
+        }
+        if (field) {
+            applicableFilters.push({ ...filter, field: field.name });
+        }
+    }
+    return applicableFilters;
+};

package/dist/src/index.cjs

@@ -692,6 +692,41 @@ class Handler {
                 res.status(204).send(null);
             });
         }
+        if (this.handlers.getBlob) {
+            console.debug(`  Enabling getBlob at GET ${this.pathWithIdentifier}`);
+            const handler = this.handlers.getBlob;
+            router.get(this.pathWithIdentifier, async (req, res) => {
+                if (!res.locals.credentials) {
+                    throw new UnauthorizedError();
+                }
+                const blob = await handler({
+                    credentials: res.locals.credentials,
+                    secrets: res.locals.secrets,
+                    logger: res.locals.logger,
+                    signal: res.locals.signal,
+                    params: req.params,
+                    query: req.query,
+                });
+                res.writeHead(200, {
+                    'Content-Type': 'application/octet-stream',
+                });
+                const reader = blob.getReader();
+                let isDone = false;
+                try {
+                    while (!isDone) {
+                        const chunk = await reader.read();
+                        isDone = chunk.done;
+                        if (chunk.value) {
+                            res.write(chunk.value);
+                        }
+                    }
+                }
+                finally {
+                    reader.releaseLock();
+                }
+                res.end();
+            });
+        }
         if (this.handlers.getCredentialAccount) {
             const handler = this.handlers.getCredentialAccount;
             console.debug(`  Enabling getCredentialAccount at GET ${this.pathWithIdentifier}`);
@@ -1080,9 +1115,39 @@ class Provider {
     }
 }
 
+/**
+ * Use this helper function to retrieve the applicable filters from the context object. While using filters
+ * directly from context might work, it doesn't offer any guarantees about the shape of the filters nor the
+ * validity of the fields against which the filters are applied. On the other hand, this function ensures that
+ * all filters are valid and that the fields against which the filters are applied are present in the schema.
+ *
+ * @param context The object containing the raw filters
+ * @param fields The schema of the item against which the filters are applied
+ * @returns The validated filters
+ */
+const getApplicableFilters = (context, fields) => {
+    const applicableFilters = [];
+    for (const filter of context.filters) {
+        let field = undefined;
+        const filterFieldParts = filter.field.split(':', 2);
+        switch (filterFieldParts[0]) {
+            case 'semantic':
+                field = fields.find(f => f.semantic === filterFieldParts[1]);
+                break;
+            default:
+                field = fields.find(f => f.name === filterFieldParts[0]);
+        }
+        if (field) {
+            applicableFilters.push({ ...filter, field: field.name });
+        }
+    }
+    return applicableFilters;
+};
+
 exports.Api = integrationApi__namespace;
 exports.Cache = Cache;
 exports.Handler = Handler;
 exports.HttpErrors = httpErrors;
 exports.Integration = Integration;
 exports.Provider = Provider;
+exports.getApplicableFilters = getApplicableFilters;

package/dist/src/index.d.ts

@@ -5,6 +5,8 @@ export * from './handler.js';
 export { Provider, type Response as ProviderResponse, type RequestOptions as ProviderRequestOptions, type RateLimiter, } from './resources/provider.js';
 export type { Secrets } from './middlewares/secrets.js';
 export type { Credentials } from './middlewares/credentials.js';
+export type { Filter } from './middlewares/filters.js';
 export * as HttpErrors from './httpErrors.js';
+export { getApplicableFilters } from './helpers.js';
 export * from './resources/context.js';
 export { type default as Logger } from './resources/logger.js';

package/dist/src/index.js

@@ -5,5 +5,6 @@ export { default as Integration } from './integration.js';
 export * from './handler.js';
 export { Provider, } from './resources/provider.js';
 export * as HttpErrors from './httpErrors.js';
+export { getApplicableFilters } from './helpers.js';
 export * from './resources/context.js';
 /* c8 ignore stop */

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

@@ -61,6 +61,12 @@ export type Context<P extends Maybe<Params> = Params, Q extends Maybe<Query> = Q
  * @see {@link Context}
  */
 export type GetItemContext<P extends Maybe<Params> = Empty, Q extends Query = Empty> = Context<P, Q>;
+/**
+ * Context received by the `GetBlobHandler`, same as `GetItemContext`.
+ *
+ * @see {@link Context}
+ */
+export type GetBlobContext<P extends Maybe<Params> = Empty, Q extends Query = Empty> = Context<P, Q>;
 /**
  * Context received by the `GetCollectionHandler`.
  *

package/dist/test/helpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/helpers.test.js

@@ -0,0 +1,57 @@
+import { FieldValueType, OperatorType, Semantic } from '@unito/integration-api';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { getApplicableFilters } from '../src/helpers.js';
+describe('Helpers', () => {
+    describe('getApplicableFilters', () => {
+        it('returns only filters for defined fields', () => {
+            const actual = getApplicableFilters({
+                filters: [
+                    { field: 'status', operator: OperatorType.EQUAL, values: ['active', 'pending'] },
+                    { field: 'email', operator: OperatorType.IS_NOT_NULL, values: [] },
+                ],
+            }, [
+                {
+                    name: 'status',
+                    label: 'Status',
+                    type: FieldValueType.STRING,
+                },
+            ]);
+            const expected = [{ field: 'status', operator: OperatorType.EQUAL, values: ['active', 'pending'] }];
+            assert.deepEqual(actual, expected);
+        });
+        it('translates semantics into field names', () => {
+            const actual = getApplicableFilters({
+                filters: [
+                    { field: 'semantic:displayName', operator: OperatorType.START_WITH, values: ['Bob'] },
+                    { field: 'semantic:createdAt', operator: OperatorType.EQUAL, values: ['2021-01-01'] },
+                ],
+            }, [
+                {
+                    name: 'name',
+                    label: 'Name',
+                    type: FieldValueType.STRING,
+                    semantic: Semantic.DISPLAY_NAME,
+                },
+            ]);
+            const expected = [{ field: 'name', operator: OperatorType.START_WITH, values: ['Bob'] }];
+            assert.deepEqual(actual, expected);
+        });
+        it('gracefully handle garbage', () => {
+            const actual = getApplicableFilters({
+                filters: [
+                    { field: '...', operator: OperatorType.EQUAL, values: [] },
+                    { field: ':', operator: OperatorType.EQUAL, values: [] },
+                    { field: '', operator: OperatorType.EQUAL, values: [] },
+                ],
+            }, [
+                {
+                    name: 'status',
+                    label: 'Status',
+                    type: FieldValueType.STRING,
+                },
+            ]);
+            assert.deepEqual(actual, []);
+        });
+    });
+});

package/dist/test/resources/provider.test.js

@@ -3,6 +3,11 @@ import { describe, it } from 'node:test';
 import { Provider } from '../../src/resources/provider.js';
 import * as HttpErrors from '../../src/httpErrors.js';
 import Logger from '../../src/resources/logger.js';
+// There is currently an issue with node 20.12 and fetch mocking. A quick fix is to first call fetch so it's getter
+// get properly instantiated, which allow it to be mocked properly.
+// Issue: https://github.com/nodejs/node/issues/52015
+// PR fix: https://github.com/nodejs/node/pull/52275
+globalThis.fetch = fetch;
 describe('Provider', () => {
     const provider = new Provider({
         prepareRequest: requestOptions => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-sdk",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Integration SDK",
   "type": "module",
   "types": "dist/src/index.d.ts",

package/src/handler.ts

@@ -3,6 +3,7 @@ import * as API from '@unito/integration-api';
 import { InvalidHandler } from './errors.js';
 import { UnauthorizedError, BadRequestError } from './httpErrors.js';
 import {
+  GetBlobContext,
   GetItemContext,
   GetCollectionContext,
   CreateItemContext,
@@ -53,6 +54,14 @@ export type UpdateItemHandler = (context: UpdateItemContext<any, any, any>) => P
  */
 export type DeleteItemHandler = (context: DeleteItemContext<any, any>) => Promise<void>;
 
+/**
+ * Handler called to get a Binary Large Object.
+ *
+ * @param context {@link BlobItemContext}
+ * @returns A {@link ReadableStream} of the Blob.
+ */
+export type GetBlobHandler = (context: GetBlobContext<any, any>) => Promise<ReadableStream<Uint8Array>>;
+
 /**
  * Handler called to retrieve the account details associated with the credentials.
  *
@@ -114,6 +123,10 @@ export type ItemHandlers = {
   deleteItem?: DeleteItemHandler;
 };
 
+export type BlobHandlers = {
+  getBlob: GetBlobHandler;
+};
+
 export type CredentialAccountHandlers = {
   getCredentialAccount: GetCredentialAccountHandler;
 };
@@ -132,6 +145,7 @@ export type AcknowledgeWebhookHandlers = {
 
 export type HandlersInput =
   | ItemHandlers
+  | BlobHandlers
   | CredentialAccountHandlers
   | ParseWebhookHandlers
   | WebhookSubscriptionHandlers
@@ -139,6 +153,7 @@ export type HandlersInput =
 
 type Handlers = Partial<
   ItemHandlers &
+    BlobHandlers &
     CredentialAccountHandlers &
     ParseWebhookHandlers &
     WebhookSubscriptionHandlers &
@@ -380,6 +395,50 @@ export class Handler {
       });
     }
 
+    if (this.handlers.getBlob) {
+      console.debug(`  Enabling getBlob at GET ${this.pathWithIdentifier}`);
+
+      const handler = this.handlers.getBlob;
+
+      router.get(this.pathWithIdentifier, async (req, res) => {
+        if (!res.locals.credentials) {
+          throw new UnauthorizedError();
+        }
+
+        const blob = await handler({
+          credentials: res.locals.credentials,
+          secrets: res.locals.secrets,
+          logger: res.locals.logger,
+          signal: res.locals.signal,
+          params: req.params,
+          query: req.query,
+        });
+
+        res.writeHead(200, {
+          'Content-Type': 'application/octet-stream',
+        });
+
+        const reader = blob.getReader();
+
+        let isDone = false;
+
+        try {
+          while (!isDone) {
+            const chunk = await reader.read();
+            isDone = chunk.done;
+
+            if (chunk.value) {
+              res.write(chunk.value);
+            }
+          }
+        } finally {
+          reader.releaseLock();
+        }
+
+        res.end();
+      });
+    }
+
     if (this.handlers.getCredentialAccount) {
       const handler = this.handlers.getCredentialAccount;
 

package/src/helpers.ts

@@ -0,0 +1,37 @@
+import { FieldSchema } from '@unito/integration-api';
+
+import { Filter } from './index.js';
+
+/**
+ * Use this helper function to retrieve the applicable filters from the context object. While using filters
+ * directly from context might work, it doesn't offer any guarantees about the shape of the filters nor the
+ * validity of the fields against which the filters are applied. On the other hand, this function ensures that
+ * all filters are valid and that the fields against which the filters are applied are present in the schema.
+ *
+ * @param context The object containing the raw filters
+ * @param fields The schema of the item against which the filters are applied
+ * @returns The validated filters
+ */
+export const getApplicableFilters = (context: { filters: Filter[] }, fields: FieldSchema[]): Filter[] => {
+  const applicableFilters: Filter[] = [];
+
+  for (const filter of context.filters) {
+    let field: FieldSchema | undefined = undefined;
+
+    const filterFieldParts = filter.field.split(':', 2);
+
+    switch (filterFieldParts[0]) {
+      case 'semantic':
+        field = fields.find(f => f.semantic === filterFieldParts[1]);
+        break;
+      default:
+        field = fields.find(f => f.name === filterFieldParts[0]);
+    }
+
+    if (field) {
+      applicableFilters.push({ ...filter, field: field.name });
+    }
+  }
+
+  return applicableFilters;
+};

package/src/index.ts

@@ -11,7 +11,9 @@ export {
 } from './resources/provider.js';
 export type { Secrets } from './middlewares/secrets.js';
 export type { Credentials } from './middlewares/credentials.js';
+export type { Filter } from './middlewares/filters.js';
 export * as HttpErrors from './httpErrors.js';
+export { getApplicableFilters } from './helpers.js';
 export * from './resources/context.js';
 export { type default as Logger } from './resources/logger.js';
 /* c8 ignore stop */

package/src/resources/context.ts

@@ -67,6 +67,13 @@ export type Context<P extends Maybe<Params> = Params, Q extends Maybe<Query> = Q
  */
 export type GetItemContext<P extends Maybe<Params> = Empty, Q extends Query = Empty> = Context<P, Q>;
 
+/**
+ * Context received by the `GetBlobHandler`, same as `GetItemContext`.
+ *
+ * @see {@link Context}
+ */
+export type GetBlobContext<P extends Maybe<Params> = Empty, Q extends Query = Empty> = Context<P, Q>;
+
 /**
  * Context received by the `GetCollectionHandler`.
  *

package/test/helpers.test.ts

@@ -0,0 +1,75 @@
+import { FieldValueType, OperatorType, Semantic } from '@unito/integration-api';
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { getApplicableFilters } from '../src/helpers.js';
+
+describe('Helpers', () => {
+  describe('getApplicableFilters', () => {
+    it('returns only filters for defined fields', () => {
+      const actual = getApplicableFilters(
+        {
+          filters: [
+            { field: 'status', operator: OperatorType.EQUAL, values: ['active', 'pending'] },
+            { field: 'email', operator: OperatorType.IS_NOT_NULL, values: [] },
+          ],
+        },
+        [
+          {
+            name: 'status',
+            label: 'Status',
+            type: FieldValueType.STRING,
+          },
+        ],
+      );
+
+      const expected = [{ field: 'status', operator: OperatorType.EQUAL, values: ['active', 'pending'] }];
+
+      assert.deepEqual(actual, expected);
+    });
+
+    it('translates semantics into field names', () => {
+      const actual = getApplicableFilters(
+        {
+          filters: [
+            { field: 'semantic:displayName', operator: OperatorType.START_WITH, values: ['Bob'] },
+            { field: 'semantic:createdAt', operator: OperatorType.EQUAL, values: ['2021-01-01'] },
+          ],
+        },
+        [
+          {
+            name: 'name',
+            label: 'Name',
+            type: FieldValueType.STRING,
+            semantic: Semantic.DISPLAY_NAME,
+          },
+        ],
+      );
+
+      const expected = [{ field: 'name', operator: OperatorType.START_WITH, values: ['Bob'] }];
+
+      assert.deepEqual(actual, expected);
+    });
+
+    it('gracefully handle garbage', () => {
+      const actual = getApplicableFilters(
+        {
+          filters: [
+            { field: '...', operator: OperatorType.EQUAL, values: [] },
+            { field: ':', operator: OperatorType.EQUAL, values: [] },
+            { field: '', operator: OperatorType.EQUAL, values: [] },
+          ],
+        },
+        [
+          {
+            name: 'status',
+            label: 'Status',
+            type: FieldValueType.STRING,
+          },
+        ],
+      );
+
+      assert.deepEqual(actual, []);
+    });
+  });
+});

package/test/resources/provider.test.ts

@@ -5,6 +5,12 @@ import { Provider } from '../../src/resources/provider.js';
 import * as HttpErrors from '../../src/httpErrors.js';
 import Logger from '../../src/resources/logger.js';
 
+// There is currently an issue with node 20.12 and fetch mocking. A quick fix is to first call fetch so it's getter
+// get properly instantiated, which allow it to be mocked properly.
+// Issue: https://github.com/nodejs/node/issues/52015
+// PR fix: https://github.com/nodejs/node/pull/52275
+globalThis.fetch = fetch;
+
 describe('Provider', () => {
   const provider = new Provider({
     prepareRequest: requestOptions => {