@unito/integration-api
Version:
The Unito Integration API
552 lines (551 loc) • 15.3 kB
TypeScript
import { Readable } from 'node:stream';
/**
* A Collection represents a paginated list of ItemSummary available through a Relation.
*/
export interface Collection {
/**
* Contextual information.
*/
info: {
/**
* Link to the next page.
*/
nextPage?: string;
};
/**
* List of item summaries.
*/
data: ItemSummary[];
}
/**
* A CredentialAccount describes the provider account associated to a credential.
*/
export interface CredentialAccount {
/**
* The native id of the provider account.
*/
id: string;
/**
* The display name of the provider account.
*/
displayName: string;
/**
* The emails associated with the provider account.
*/
emails: string[];
/**
* Partition can be used to divide data into different buckets.
*/
partition?: string;
}
/**
* An error is used when an operation doesn't succeed.
*/
export interface Error {
/**
* Specific error code. Usually the HTTP response code.
*/
code: string;
/**
* Raw error message.
*/
message: string;
/**
* Free-form key-value store. For logging/debugging purposes.
*/
details?: {
[k: string]: unknown;
};
originalError?: Error;
}
interface AbstractFieldSchema {
/**
* The main identifier of the field.
*/
name: string;
/**
* The publicly visible label of the field.
*/
label: string;
/**
* The semantic of the field.
*/
semantic?: Semantic;
/**
* Description of the field. For information purposes only.
*/
info?: string;
/**
* Whether the field is read only.
*/
readOnly?: boolean;
/**
* Whether the field returns an array. Defaults to false.
* An array is a non-paginated list of same-type values.
* For pagination, use a relation instead.
*/
isArray?: boolean;
/**
* Whether the field can be empty. Default to true.
*/
nullable?: boolean;
}
export interface BasicFieldSchema extends AbstractFieldSchema {
/**
* The type of the field.
*/
type: Exclude<FieldValueType, typeof FieldValueTypes.BLOB | typeof FieldValueTypes.REFERENCE | typeof FieldValueTypes.OBJECT | typeof FieldValueTypes.DATETIME_RANGE | typeof FieldValueTypes.DATE_RANGE>;
}
export interface BlobFieldSchema extends AbstractFieldSchema {
/**
* The type of the field.
*/
type: typeof FieldValueTypes.BLOB;
}
export interface ReferenceFieldSchema extends AbstractFieldSchema {
/**
* The type of the field.
*/
type: typeof FieldValueTypes.REFERENCE;
/**
* Describe the referenced collection.
*/
reference: ReferenceRelation;
}
/**
* A ReferenceRelation describes a relation that can be used in a ReferenceFieldSchema.
*/
export interface ReferenceRelation {
/**
* The path at which the relation data is available.
*/
path: string;
/**
* The publicly visible label of the relation.
*/
label: string;
/**
* Whether the relation is searchable.
*/
searchable?: boolean;
/**
* The semantic of the relation.
*/
semantic?: RelationSemantic;
/**
* The name for the reference relation.
* @deprecated Will be removed in a future version.
*/
name?: string;
/**
* The shape of the relation.
*/
schema: RelationSchema | '__self';
}
export interface DatetimeRangeFieldSchema extends AbstractFieldSchema {
/**
* The type of the field.
*/
type: typeof FieldValueTypes.DATETIME_RANGE;
/**
* Optional values that can be used in lieu of actual dates. They should represent points in time relative to today.
* e.g. [{ label: 'Yesterday', value: 'yesterday' }, ...]
* These values become valid input for either end of the datetime range.
* e.g. "2023-11-01T08:15:30.000-05:00/yesterday"
*/
optionalValues?: {
label: string;
value: string;
}[];
}
export interface DateRangeFieldSchema extends AbstractFieldSchema {
/**
* The type of the field.
*/
type: typeof FieldValueTypes.DATE_RANGE;
/**
* Optional values that can be used in lieu of actual dates. They should represent points in time relative to today.
* e.g. [{ label: 'Yesterday', value: 'yesterday' }, ...]
* When defined, the name of these fields becomes valid inputs for both startDatetime and endDatetime.
* e.g. "2023-11-01/yesterday"
*/
optionalValues?: {
label: string;
value: string;
}[];
}
export interface ObjectFieldSchema extends AbstractFieldSchema {
/**
* The type of the field.
*/
type: typeof FieldValueTypes.OBJECT;
/**
* Describe the schema of the object.
*/
fields: FieldSchema[];
}
/**
* A FieldSchema describes the shape of a field.
*/
export type FieldSchema = BasicFieldSchema | BlobFieldSchema | ReferenceFieldSchema | ObjectFieldSchema | DateRangeFieldSchema | DatetimeRangeFieldSchema;
/**
* A FieldValueType determines the type of an item's value.
* The type represents a unique scalar value such as a string or an integer.
* For more complex types, use an Item instead.
*/
export declare const FieldValueTypes: {
readonly BLOB: "blob";
readonly BOOLEAN: "boolean";
readonly DATE: "date";
readonly DATE_RANGE: "dateRange";
readonly DATETIME: "datetime";
readonly DATETIME_RANGE: "datetimeRange";
readonly DURATION: "duration";
readonly EMAIL: "email";
readonly RICH_TEXT_HTML: "html";
readonly INTEGER: "integer";
readonly RICH_TEXT_MARKDOWN: "markdown";
readonly NUMBER: "number";
readonly OBJECT: "object";
readonly REFERENCE: "reference";
readonly STRING: "string";
readonly URL: "url";
};
export type FieldValueType = (typeof FieldValueTypes)[keyof typeof FieldValueTypes];
/**
* A Semantic gives meaning to an Item or a Field in the Unito platform.
* An object with a specified semantic is expected to hold a certain type of value that can later be used
* by the consumers of the spec to better understand what that value means.
*/
export declare const Semantics: {
readonly CREATED_AT: "createdAt";
readonly DESCRIPTION: "description";
readonly DISPLAY_NAME: "displayName";
readonly PROVIDER_URL: "providerUrl";
readonly UPDATED_AT: "updatedAt";
readonly USER: "user";
readonly PARENT: "parent";
};
export type Semantic = (typeof Semantics)[keyof typeof Semantics];
/**
* A Relation Semantic gives meaning to a Relation in the Unito platform. A relation with a
* specified semantic is expected to hold a certain type of item that can later be used by
* the consumers of the spec for specific usage.
*/
export declare const RelationSemantics: {
readonly COMMENTS: "comments";
readonly SUBTASKS: "subtasks";
readonly USERS: "users";
readonly ATTACHMENTS: "attachments";
};
export type RelationSemantic = (typeof RelationSemantics)[keyof typeof RelationSemantics];
/**
* An OperatorType represents an operator used in a filter.
*/
export declare const OperatorTypes: {
readonly EQUAL: "=";
readonly NOT_EQUAL: "!=";
readonly GREATER_THAN: ">";
readonly GREATER_THAN_OR_EQUAL: ">=";
readonly LESSER_THAN: "<";
readonly LESSER_THAN_OR_EQUAL: "<=";
readonly INCLUDE: "*=";
readonly EXCLUDE: "!*=";
readonly START_WITH: "^=";
readonly END_WITH: "$=";
readonly IS_NULL: "!!";
readonly IS_NOT_NULL: "!";
};
export type OperatorType = (typeof OperatorTypes)[keyof typeof OperatorTypes];
/**
* An Item represents a syncable entity. It has fields of its own as well as relations to other items.
*/
export interface Item {
/**
* The fields and values of the item.
*/
fields: {
[k: string]: unknown;
};
/**
* The relations of the item
*/
relations: Relation[];
/**
* The canonical path of the item. This is the path / id that uniquely identifies the item in a provider.
* Even if the item is moved in the graph, the canonical path should remain the same.
*/
canonicalPath?: string;
}
/**
* An ItemSummary is a constituent of a collection.
* It links to an item, and can contain additional item information upon request.
*/
export interface ItemSummary {
/**
* Link to this specific item.
*/
path: string;
/**
* Optional list of requested fields and their values.
*/
fields?: {
[k: string]: unknown;
};
/**
* The shape of the request parameters.
*/
requestSchema?: RequestSchema;
/**
* Optional list of relation paths.
*/
relations?: {
[k: string]: string;
};
/**
* The canonical path of the item. This is the path / id that uniquely identifies the item in a provider.
* Even if the item is moved in the graph, the canonical path should remain the same.
*/
canonicalPath?: string;
}
/**
* A BlobSummary contains a path to download the corresponding Blob.
*/
export interface BlobSummary {
/**
* Link to download the Blob.
*/
path: string;
}
/**
* A Relation points to a Collection and describes the shape of the items it contains.
*/
export interface Relation {
/**
* The main identifier of the relation.
*/
name: string;
/**
* The path at which the relation data is available.
*/
path: string;
/**
* The shape of the request parameters.
*/
requestSchema?: RequestSchema;
/**
* The publicly visible label of the relation.
*/
label: string;
/**
* Whether the relation is searchable.
*/
searchable?: boolean;
/**
* The semantic of the relation.
*/
semantic?: RelationSemantic;
/**
* The shape of the relation.
*/
schema: RelationSchema;
}
/**
* A RelationSummary describes the common properties of a relation expected to be found on each item of a relation.
*/
export type RelationSummary = {
/**
* The main identifier of the relation.
*/
name: string;
/**
* The publicly visible label of the relation.
*/
label: string;
/**
* When provided, provides a way to retrieve all the items described by this relation summary.
* This needs to be used in conjunction with a field having a PARENT semantic.
*/
aggregatePath?: string;
/**
* The semantic of the relation.
*/
semantic?: RelationSemantic;
/**
* The shape of the relation.
*/
schema: RelationSchema | '__self';
};
/**
* A Relation Schema describes the shape of an item in a relation.
*/
export interface RelationSchema {
/**
* The publicly visible label of one item in this relation.
*/
label: string;
/**
* Can we create items?
*/
canCreateItem?: boolean;
/**
* Can we update items?
*/
canUpdateItem?: boolean;
/**
* Can we delete items?
*/
canDeleteItem?: boolean;
/**
* Can we add fields to the schema?
*/
canAddFields?: boolean;
/**
* The shape of the fields.
*/
fields: FieldSchema[];
/**
* Summaries of the relations expected to be found on these items.
*/
relations?: RelationSummary[];
}
/**
* A CreateItemRequestPayload describes the shape of a request on an item creation endpoint.
*/
export type CreateItemRequestPayload = Record<string, unknown>;
/**
* A CreateBlobRequestPayload describes the shape of a request on a blob creation endpoint.
*/
export type CreateBlobRequestPayload = {
file: Readable;
mimeType: string;
encoding: string;
filename: string;
};
/**
* A UpdateItemRequestPayload describes the shape of a request on an item update endpoint.
*/
export type UpdateItemRequestPayload = CreateItemRequestPayload & {
__meta?: {
additionalField: {
relationName: string;
field: BasicFieldSchema;
};
};
};
/**
* A Request Schema describes how a path should be accessed.
*/
export interface RequestSchema {
/**
* The shape of the request parameters.
*/
parameters: FieldSchema[];
}
/**
* HTTP code returned by the integration
*/
export declare const StatusCodes: {
readonly OK: 200;
readonly CREATED: 201;
readonly ACCEPTED: 202;
readonly NO_CONTENT: 204;
readonly BAD_REQUEST: 400;
readonly UNAUTHORIZED: 401;
readonly FORBIDDEN: 403;
readonly NOT_FOUND: 404;
readonly NOT_ACCEPTABLE: 406;
readonly REQUEST_TIMEOUT: 408;
readonly UNPROCESSABLE_CONTENT: 422;
readonly LOCKED: 423;
readonly TOO_MANY_REQUESTS: 429;
readonly INTERNAL_SERVER_ERROR: 500;
};
export type StatusCode = (typeof StatusCodes)[keyof typeof StatusCodes];
/**
* A WebhookSubscriptionPayload describes the shape of the request on the "webhook subscription" endpoint.
*/
export interface WebhookSubscriptionRequestPayload {
/**
* The path of the item to which the subscription belongs
*/
itemPath: string;
/**
* The target URL at which events should be sent
*/
targetUrl: string;
/**
* The desired action to be applied to the subscription
*/
action: 'start' | 'stop';
}
/**
* A WebhookParseRequestPayload describes the shape of the request on the "parse webhook" endpoint.
*/
export interface WebhookParseRequestPayload {
/**
* The partition data for which this webhook was received.
*/
partition?: string;
/**
* The raw headers sent by the provider.
*/
headers: Record<string, string | string[]>;
/**
* The raw payload sent by the provider.
*/
payload: string;
/**
* The full URL, including query params, as sent by the provider
*/
url: string;
}
/**
* A WebhookAcknowledgeResponsePayload describes the shape of the request on the "acknowledge webhook" endpoint.
*/
export interface WebhookAcknowledgeResponsePayload {
/**
* The status code that should be returned to the provider.
*/
statusCode: number;
/**
* The headers that should be returned to the provider.
*/
headers?: Record<string, string | string[]>;
/**
* The payload that should be returned to the provider.
*/
payload?: string;
}
/**
* A WebhookParsedItem describes the shape an item found within a webhook's parsed payload.
*/
export interface WebhookParsedItem {
/**
* The path of the item targetted by this event.
*/
itemPath: string;
/**
* The date at which the event took place, expressed as an ISO 8601 string.
* e.g "2023-11-05T08:15:30.000-05:00"
*/
date: string;
/**
* The item's relations impacted by this event.
*/
impactedRelations: {
/**
* The name of the relation.
*/
name: string;
/**
* The list of specific items impacted by this event.
*/
impactedItems: WebhookParsedItem[];
}[];
}
/**
* A WebhookParseResponsePayload describes the shape of the response on the "parse webhook" endpoint.
*/
export type WebhookParseResponsePayload = WebhookParsedItem | WebhookParsedItem[];
export {};