@unito/integration-sdk 0.1.11 → 1.0.0

package/dist/src/handler.d.ts

@@ -3,40 +3,79 @@ import * as API from '@unito/integration-api';
 import { GetItemContext, GetCollectionContext, CreateItemContext, UpdateItemContext, DeleteItemContext, GetCredentialAccountContext, ParseWebhooksContext, UpdateWebhookSubscriptionsContext, AcknowledgeWebhooksContext } from './resources/context.js';
 /**
  * Handler called to get an individual item.
+ *
+ * @param context {@link GetItemContext}
+ * @returns The requested {@link API.Item}.
  */
 export type GetItemHandler = (context: GetItemContext<any, any>) => Promise<API.Item>;
 /**
  * Handler called to retrieve a collection of items.
+ *
+ * @param context {@link GetCollectionContext}
+ * @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 CreateItemContext}
+ * @returns An {@link API.ItemSummary} containing a path to the created item.
  */
 export type CreateItemHandler = (context: CreateItemContext<any, any, any>) => Promise<API.ItemSummary>;
 /**
  * Handler called to update an item.
+ *
+ * @param context {@link UpdateItemContext}
+ * @returns The updated {@link API.Item}.
  */
 export type UpdateItemHandler = (context: UpdateItemContext<any, any, any>) => Promise<API.Item>;
 /**
  * Handler called to delete an item.
+ *
+ * @param context {@link DeleteItemContext}
  */
 export type DeleteItemHandler = (context: DeleteItemContext<any, any>) => Promise<void>;
 /**
  * Handler called to retrieve the account details associated with the credentials.
+ *
+ * @param context {@link GetCredentialAccountContext}
+ * @returns The {@link API.CredentialAccount} associated with the credentials.
  */
 export type GetCredentialAccountHandler = (context: GetCredentialAccountContext<any, any>) => Promise<API.CredentialAccount>;
 /**
  * Handler called to parse the content of an incoming webhook.
+ *
+ * @param context {@link ParseWebhooksContext}
+ * @returns The parsed content of the webhook as a {@link API.WebhookParseResponsePayload}.
  */
 export type ParseWebhooksHandler = (context: ParseWebhooksContext<any, any, any>) => Promise<API.WebhookParseResponsePayload>;
 /**
  * Handler called to subscribe or unsubscribe to a particular webhook.
+ *
+ * @param context {@link UpdateWebhookSubscriptionsContext}
  */
 export type UpdateWebhookSubscriptionsHandler = (context: UpdateWebhookSubscriptionsContext<any, any, any>) => Promise<void>;
 /**
  * Handler called to acknowledge the reception of a webhook.
+ *
+ * @param context {@link AcknowledgeWebhooksContext}
+ * @returns The {@link API.WebhookAcknowledgeResponsePayload} to be sent back to the webhook provider.
  */
 export type AcknowledgeWebhooksHandler = (context: AcknowledgeWebhooksContext<any, any, any>) => Promise<API.WebhookAcknowledgeResponsePayload>;
+/**
+ * Defines the implementation of the operations available for a given `Item`.
+ * - In some cases (e.g. defining the `root` or {@link https://dev.unito.io/docs/connectors/apiSpecification/credentialAccount | me}
+ *   handlers), only a {@link GetItemHandler | getItem} handler is necessary.
+ * - In most cases, you will want to define {@link GetCollectionHandler | getCollection},
+ *   most likely {@link GetItemHandler | getItem}, and any other handlers relevant to the item.
+ *
+ * The `ItemHandlers` object can contain any of the following:
+ * - {@link GetItemHandler | getItem}: A handler called to get an individual item.
+ * - {@link GetCollectionHandler | getCollection}: A handler called to retrieve a collection of items.
+ * - {@link CreateItemHandler | createItem}: A handler called to create an item.
+ * - {@link UpdateItemHandler | updateItem}: A handler called to update an item.
+ * - {@link DeleteItemHandler | deleteItem}: A handler called to delete an item.
+ */
 export type ItemHandlers = {
     getItem?: GetItemHandler;
     getCollection?: GetCollectionHandler;

package/dist/src/handler.js

@@ -94,6 +94,7 @@ export class Handler {
                     selects: res.locals.selects,
                     filters: res.locals.filters,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -113,6 +114,7 @@ export class Handler {
                     secrets: res.locals.secrets,
                     body: req.body,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -130,6 +132,7 @@ export class Handler {
                     credentials: res.locals.credentials,
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -149,6 +152,7 @@ export class Handler {
                     secrets: res.locals.secrets,
                     body: req.body,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -166,6 +170,7 @@ export class Handler {
                     credentials: res.locals.credentials,
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -183,6 +188,7 @@ export class Handler {
                     credentials: res.locals.credentials,
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });
@@ -197,6 +203,7 @@ export class Handler {
                 const response = await handler({
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                     body: req.body,
@@ -212,6 +219,7 @@ export class Handler {
                 const response = await handler({
                     secrets: res.locals.secrets,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                     body: req.body,
@@ -232,6 +240,7 @@ export class Handler {
                     credentials: res.locals.credentials,
                     body: req.body,
                     logger: res.locals.logger,
+                    signal: res.locals.signal,
                     params: req.params,
                     query: req.query,
                 });

package/dist/src/httpErrors.d.ts

@@ -1,25 +1,54 @@
+/**
+ * Error class meant to be returned by integrations in case of exceptions. These errors will be caught and handled
+ * appropriately. Any other error would result in an unhandled server error accompanied by a 500 status code.
+ *
+ * @field message - The error message
+ * @field status - The HTTP status code to return
+ */
 export declare class HttpError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
 }
+/**
+ * Used to generate a 400 Bad Request. Usually used when something is missing to properly handle the request.
+ */
 export declare class BadRequestError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * Used to generate a 401 Unauthorized. Usually used when the credentials are missing or invalid.
+ */
 export declare class UnauthorizedError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * Used to generate a 404 Not Found. Usually used when the requested `Item` is not found.
+ */
 export declare class NotFoundError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * Used to generate a 408 Timeout Error. Usually used when the call length exceeds the received Operation Deadline.
+ */
 export declare class TimeoutError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * Used to generate a 410 Resource Gone.
+ */
 export declare class ResourceGoneError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * Used to generate a 422 Unprocessable Entity. Usually used when an operation is invalid.
+ */
 export declare class UnprocessableEntityError extends HttpError {
     constructor(message?: string);
 }
+/**
+ * Used to generate a 429 Unprocessable Entity. Usually used when an operation triggers or would trigger a rate limit
+ * error on the provider's side.
+ */
 export declare class RateLimitExceededError extends HttpError {
     constructor(message?: string);
 }

package/dist/src/httpErrors.js

@@ -1,40 +1,70 @@
+/**
+ * Error class meant to be returned by integrations in case of exceptions. These errors will be caught and handled
+ * appropriately. Any other error would result in an unhandled server error accompanied by a 500 status code.
+ *
+ * @field message - The error message
+ * @field status - The HTTP status code to return
+ */
 export class HttpError extends Error {
     status;
     constructor(message, status) {
         super(message);
         this.status = status;
+        this.name = this.constructor.name;
     }
 }
+/**
+ * Used to generate a 400 Bad Request. Usually used when something is missing to properly handle the request.
+ */
 export class BadRequestError extends HttpError {
     constructor(message) {
         super(message || 'Bad request', 400);
     }
 }
+/**
+ * Used to generate a 401 Unauthorized. Usually used when the credentials are missing or invalid.
+ */
 export class UnauthorizedError extends HttpError {
     constructor(message) {
         super(message || 'Unauthorized', 401);
     }
 }
+/**
+ * Used to generate a 404 Not Found. Usually used when the requested `Item` is not found.
+ */
 export class NotFoundError extends HttpError {
     constructor(message) {
         super(message || 'Not found', 404);
     }
 }
+/**
+ * Used to generate a 408 Timeout Error. Usually used when the call length exceeds the received Operation Deadline.
+ */
 export class TimeoutError extends HttpError {
     constructor(message) {
         super(message || 'Not found', 408);
     }
 }
+/**
+ * Used to generate a 410 Resource Gone.
+ */
 export class ResourceGoneError extends HttpError {
     constructor(message) {
         super(message || 'Resource gone or unavailable', 410);
     }
 }
+/**
+ * Used to generate a 422 Unprocessable Entity. Usually used when an operation is invalid.
+ */
 export class UnprocessableEntityError extends HttpError {
     constructor(message) {
         super(message || 'Unprocessable Entity', 422);
     }
 }
+/**
+ * Used to generate a 429 Unprocessable Entity. Usually used when an operation triggers or would trigger a rate limit
+ * error on the provider's side.
+ */
 export class RateLimitExceededError extends HttpError {
     constructor(message) {
         super(message || 'Rate Limit Exceeded', 429);