@useparagon/connect 1.0.0 → 1.0.1

package/README.md

@@ -1,19 +1,44 @@
 <p align="center">
-  <a href="https://www.useparagon.com/" target="blank"><img src="../../static/paragon-banner.png" width="320" alt="Paragon Logo" /></a>
+  <a href="https://www.useparagon.com/" target="blank"><img src="https://raw.githubusercontent.com/useparagon/aws-on-prem/master/assets/paragon-logo-dark.png" width="150" alt="Paragon Logo" /></a>
 </p>
 
-## Description
+<p align="center">
+  <b>
+    The embedded integration platform for developers.
+  </b>
+</p>
+
+---
+
+Paragon is an embedded integration platform that 100+ software companies rely on to rapidly accelerate development of native product integrations with 3rd party SaaS apps such as Salesforce, Slack, and QuickBooks. This allows their engineering teams to avoid the heavy costs and risks that come with building and maintaining dozens of their own integrations.
+
+## Usage
+
+To install the Paragon SDK, run this command in your project to add it as a dependency:
+
+```sh
+npm install @useparagon/connect
+```
+
+This package is intended for usage in your frontend application to embed the Paragon connection experience. After importing the **[Paragon SDK](https://docs.useparagon.com/getting-started/installing-the-connect-sdk)**, you can:
 
-Work on [Paragon](https://www.useparagon.com) tasks.
+- Display the **[Connect Portal](https://docs.useparagon.com/connect-portal/connect-portal-customization)**, a prebuilt UI component for your users to connect third-party app accounts
+- Trigger [**Workflows**](https://docs.useparagon.com/workflows/building-workflows), which are observable, durable jobs you define to sync integration data
+- Send [**Connect API**](https://docs.useparagon.com/api/making-api-requests) requests to access integration data in realtime from your app
+- Render a custom integrations UI using the [**Headless Connect Portal**](https://docs.useparagon.com/connect-portal/headless-connect-portal)
 
-## Running the app
+```typescript
+import { paragon } from '@useparagon/connect';
 
-```bash
-# development
-$ yarn run start
+// Authenticate your user with the SDK
+await paragon.authenticate(projectId, paragonUserToken);
 
+// Launch the Connect Portal for Salesforce in your app
+paragon.connect('salesforce');
 ```
 
-## Test
+## Documentation
 
+To start using the Paragon SDK, you will need to [sign up and register for an account](https://dashboard.useparagon.com/signup).
 
+For details on getting started and a reference on all available SDK functions, please see [our documentation](https://docs.useparagon.com/getting-started/introduction).

package/dist/src/ConnectSDK.d.ts

@@ -0,0 +1,189 @@
+import { OauthCallbackResponse } from './entities/credential.interface';
+import { IIntegrationMetadata } from './entities/integration.interface';
+import { PersonaMeta } from './entities/persona.interface';
+import SDKEventEmitter from './SDKEventEmitter';
+import { AuthenticateOptions, AuthenticatedConnectUser, Props as ConnectModalProps, ConnectParams, ConnectUser, EventInfo, IConnectSDK, InstallOptions, TriggerWorkflowRequest } from './types';
+export declare const PARAGON_OVERFLOW_EMPTY_VALUE = "PARAGON_OVERFLOW_EMPTY_VALUE";
+export default class ConnectSDK extends SDKEventEmitter implements IConnectSDK {
+    root: HTMLIFrameElement | undefined;
+    private rootLoaded;
+    private projectId;
+    private modalState;
+    private userState;
+    private loadedConfigs;
+    private loadedIntegrations;
+    private endUserIntegrationConfig;
+    private environments;
+    private project;
+    /**
+     * map b/w integration key name to integration metadata
+     */
+    private metadata;
+    /**
+     * cache service
+     */
+    private cachedApiResponse;
+    /**
+     * in order to not call multiple same GET request at same time
+     * we are storing {key -> promise} map
+     */
+    private keyToRequestPromiseMap;
+    /**
+     * this will store the original overflow style of body
+     * we are using PARAGON_OVERFLOW_EMPTY_VALUE as default
+     * so that we will be able to know whether style is added in body or not
+     */
+    private originalBodyOverflow;
+    private configs;
+    constructor();
+    /**
+     * post message handler
+     * @param event
+     */
+    private eventMessageHandler;
+    private functionInvocationHandler;
+    private createReactRoot;
+    private validateAction;
+    private bootstrapSDKState;
+    setModalState(statePartial: Partial<ConnectModalProps>): void;
+    /**
+     * Loads previous SDK state saved in localStorage.
+     *
+     * **Warning:** This favors stored to current state. This should typically be called in
+     * unauthenticated contexts, as a fallback.
+     */
+    private loadState;
+    /**
+     * Saves the current SDK state into localStorage, if available.
+     */
+    private saveState;
+    /**
+     * Clears the current SDK state from localStorage, if available.
+     */
+    private clearState;
+    private render;
+    /**
+     * this will update container style
+     * @param param0
+     * @returns
+     */
+    updateContainerStyle({ isModalShown }: {
+        isModalShown: boolean;
+    }): void;
+    /**
+     * Authenticate your end user into the Paragon Connect SDK.
+     *
+     * @param projectId Your Paragon project ID.
+     * @param token A JWT signed by your App Server. The JWT should include a user ID and a
+     * session expiration time.
+     */
+    authenticate(projectId: string, token: string, options?: AuthenticateOptions): Promise<void>;
+    /**
+     * Get the Paragon authentication and integration state of your end user.
+     */
+    getUser(): ConnectUser;
+    updateAuthenticatedUser(statePartial: Partial<AuthenticatedConnectUser>): void;
+    /**
+     * Logout the currently authenticated end user from the Paragon SDK.
+     */
+    logout(): void;
+    /**
+     * Display the Paragon Connect modal
+     */
+    connect(action: string, params?: ConnectParams): Promise<void>;
+    _oauthCallback(oauthResponse: OauthCallbackResponse, credentialId?: string): Promise<void>;
+    _oauthErrorCallback(errorMessage: string | object): Promise<void>;
+    /**
+     * Send a Connect API request. Automatically handles authorization and errors.
+     *
+     * @param path The path of the request, including the leading slash, i.e. `/sdk/actions`
+     * @param init Options for the request, excluding headers (automatically added).
+     * @param prefixWithProjectPath Defaults to true. Prepends /projects/${this.projectId}` to the
+     * path.
+     */
+    sendConnectRequest<TResponse>(path: string, init?: RequestInit & {
+        cacheResult?: boolean;
+    }, prefixWithProjectPath?: boolean): Promise<TResponse | undefined>;
+    private sendRequest;
+    /**
+     * Sends a proxy request to an action
+     * @param action
+     * @param path
+     * @param init
+     * @returns api request response
+     */
+    request<TResponse>(action: string, path: string, init: {
+        method: RequestInit['method'];
+        body: RequestInit['body'] | object;
+        headers: RequestInit['headers'];
+    }): Promise<TResponse | undefined>;
+    event(name: string, payload: Record<string, unknown>): Promise<void>;
+    /**
+     * @summary this will be called to close the modal
+     * @param forceClose is set when modal is closed by cross btn
+     * @returns
+     */
+    onClose(forceClose?: boolean): void;
+    /**
+     * @summary this will be called when modal will be visible
+     */
+    onOpen(): void;
+    /**
+     * this is shared in ConnectUserContext
+     * so that event can be trigger from components
+     * @param eventInfo
+     */
+    triggerSDKEvent(eventInfo: EventInfo): void;
+    /**
+     * get single or all metadata info for integrations
+     * @param integrationKeyName
+     * @returns
+     */
+    getIntegrationMetadata(): IIntegrationMetadata[];
+    getIntegrationMetadata(integrationKeyName: string): IIntegrationMetadata;
+    /**
+     * trigger connect endpoint trigger workflow
+     * @param workflowId
+     * @param payload
+     */
+    workflow(workflowId: string, { body, query, headers }?: TriggerWorkflowRequest): Promise<object | undefined>;
+    /**
+     * for programmatically installing an integration
+     */
+    installIntegration(action: string, params?: Partial<Omit<InstallOptions, 'isApiInstallation'>>): Promise<void>;
+    /**
+     * gates headless feature to pro and enterprise users
+     */
+    ensureHeadlessIsSupported(): void;
+    uninstallIntegration(action: string): Promise<void>;
+    disableWorkflow(workflowId: string): Promise<void>;
+    private updateLocalState;
+    /**
+     * also returns false if unable to find workflow in configured workflow property of any integration
+     */
+    private isWorkflowEnabled;
+    /**
+     * gets the user data from api `/sdk/me`
+     */
+    private fetchUserData;
+    /**
+     * Gets the integrations from api `/sdk/integrations`
+     * Required this another request for integrations, as `/sdk/me` provides only minimal data for integrations
+     * we also need integration config and other credentials info which is not included in `sdk/me`
+     */
+    private fetchIntegrations;
+    /**
+     * Updates internal state where integration information may be used.
+     */
+    private updateIntegrations;
+    setUserMetadata(meta: PersonaMeta): Promise<AuthenticatedConnectUser>;
+    getIntegrationConfigs(actionNames: string[]): Promise<void>;
+    /**
+     * @param {host: string;} domain
+     * sets the domain for making http service request
+     * example: configureGlobal({host: 'myDomain.com'}) would set service urls as `https://service.myDomain.com`
+     */
+    configureGlobal(param: {
+        host: string;
+    }): void;
+}

package/dist/src/SDKEventEmitter.d.ts

@@ -0,0 +1,56 @@
+import { AuthenticatedConnectUser, CallbackMap, EventInfo, ListenerFunction, SDK_EVENT } from './types';
+export default class SDKEventEmitter {
+    private eventListenersMap;
+    private integrationStateCallbacks;
+    /**
+     * this will add listener to event listeners list
+     * @param eventName
+     * @returns function to unsubscribe current listener
+     */
+    subscribe(eventName: SDK_EVENT, listener: ListenerFunction): () => boolean;
+    /**
+     * this method add bind callbackMap to integration type
+     * and emit event for particular integration
+     * @param integrationType
+     * @param callbackMap
+     */
+    subscribeToIntegration(integrationType: string, callbackMap: CallbackMap): void;
+    /**
+     * this method removes listener from evenListenerMap
+     * @param eventName
+     * @param listener
+     * @returns true if successfully unsubscribed else false
+     */
+    unsubscribe(eventName: SDK_EVENT, listener: ListenerFunction): boolean;
+    /**
+     * check if event is valid paragon sdk event
+     * @param eventName
+     */
+    private assertEventType;
+    /**
+     * this method call attached listeners with payload for eventName type
+     * @param eventName
+     * @param eventPayload
+     */
+    private emitSafe;
+    /**
+     * this method will call errorCallback for integration
+     * @param error
+     * @param integrationType
+     */
+    emitError(error: Error, integrationType: string): void;
+    /**
+     *  this will call callBack function inside try-catch block
+     * @param integrationType
+     * @param callbackType
+     * @param payload
+     */
+    private invokeCallbackSafe;
+    /**
+     * this will invoke emitSafe method with proper payload
+     * @param event
+     * @param userState
+     * @param modalState
+     */
+    triggerEvent({ type, integrationId, integrationType, workflowId, workflowStateChange }: EventInfo, userState: AuthenticatedConnectUser): void;
+}

package/dist/src/constants.d.ts

@@ -0,0 +1 @@
+export declare const ACTION_CUSTOM = "custom";

package/dist/src/entities/base.entity.d.ts

@@ -0,0 +1,5 @@
+export interface IBaseEntity {
+    id: string;
+    dateCreated: Date;
+    dateUpdated: Date;
+}

package/dist/src/entities/connectCredential.interface.d.ts

@@ -0,0 +1,42 @@
+import { ConnectCredentialConfig } from '../types/connect';
+import { IConnectIntegration } from './integration.interface';
+import { IPersona } from './persona.interface';
+import { IProject } from './project.interface';
+export interface IConnectCredential {
+    id: string;
+    projectId: string;
+    integrationId: string;
+    config: ConnectCredentialConfig;
+    personaId: string;
+    isPreviewCredential: boolean;
+    /**
+     * @property providerId : this property stores user's identifiers in third party database e.g. Shopify
+     */
+    providerId: string;
+    dateCreated: Date;
+    dateUpdated: Date;
+    dateValidUntil?: Date;
+    dateRefreshed: Date;
+    status: CredentialStatus;
+    /**
+     * miscellaneous integration provider data received along with access_token/userinfo
+     */
+    providerData: ConnectCredentialProviderData;
+    /**
+     * count how many times credential failed to refresh
+     */
+    refreshFailureCount: number;
+    /**
+     * track refreshing status
+     */
+    isRefreshing: boolean;
+    project?: IProject;
+    integration?: IConnectIntegration;
+    persona?: IPersona;
+}
+export type ConnectCredentialProviderData = Record<string, string | number | boolean>;
+export declare enum CredentialStatus {
+    PENDING = "PENDING",
+    INVALID = "INVALID",
+    VALID = "VALID"
+}

package/dist/src/entities/credential.interface.d.ts

@@ -0,0 +1,15 @@
+export declare enum AuthenticationScheme {
+    BASIC = "basic",
+    OAUTH = "oauth",
+    OAUTH_CLIENT_CREDENTIAL = "oauth_client_credential",
+    SERVICE_ACCOUNT = "service_account",
+    OAUTH_APP = "oauth_app",
+    IMPERSONATED_APP = "impersonated_app"
+}
+/**
+ * oauth response return from our service
+ */
+export type OauthCallbackResponse = {
+    integrationId: string;
+    payload: Record<string, string | number | boolean | any>;
+};

package/dist/src/entities/customIntegration.interface.d.ts

@@ -0,0 +1,60 @@
+import { IntegrationConnectInput } from '../types/action';
+import { DataType, TokenizedSource } from '../types/resolvers';
+import { IBaseEntity } from './base.entity';
+import { AuthenticationScheme } from './credential.interface';
+import { IConnectIntegration } from './integration.interface';
+import { IProject } from './project.interface';
+import { RequestAuthorization } from './steps';
+export interface ICustomIntegration extends IBaseEntity {
+    /**
+     * the project that authored and maintains this custom integration.
+     */
+    project: IProject;
+    /**
+     * The ID of the project that authored and maintains this custom integration.
+     */
+    projectId: string;
+    name?: string;
+    /**
+     * a slug generated from the name of the custom integration (e.g. `custom.github`)
+     * it's stripped of non-alphanumeric characters and lowercased
+     * they're unique between projects
+     */
+    readonly slug?: string;
+    /**
+     * The CDN path of the custom integration's SVG-format icon file.
+     */
+    icon?: string;
+    /**
+     * Instances of this custom integration configured for a particular project.
+     *
+     * Currently, we only expect that one integration will be associated with a custom integration
+     * at a time. However, this is subject to change and should not be treated as an invariant in
+     * code (hence the array typing).
+     */
+    integrations: IConnectIntegration[];
+    /**
+     * Basic (API keys) and OAuth 2.0 authentication types are supported for custom integrations.
+     */
+    authenticationType?: AuthenticationScheme;
+    inputFields: IntegrationConnectInput[];
+    oauthAuthorizationUrl?: TokenizedSource<DataType.STRING>;
+    oauthAccessTokenUrl?: TokenizedSource<DataType.STRING>;
+    oauthScopes?: string;
+    oauthIncludeClientAuthorizationHeader?: boolean;
+    usePKCEInCodeExchange: boolean;
+    apiBaseUrl?: TokenizedSource<DataType.STRING>;
+    testEndpointPath?: TokenizedSource<DataType.STRING>;
+    apiAuthorization: RequestAuthorization;
+    isPublished: boolean;
+}
+export interface IPublishedCustomIntegration extends ICustomIntegration {
+    isPublished: true;
+    name: string;
+    readonly slug: string;
+    icon: string;
+    authenticationType: AuthenticationScheme;
+    oauthClientId: string;
+    oauthScopes: string;
+}
+export declare function generateSlugForIntegration(customIntegration: ICustomIntegration): string | undefined;

package/dist/src/entities/integration.interface.d.ts

@@ -0,0 +1,33 @@
+import { ICustomIntegration } from './customIntegration.interface';
+import { IConnectIntegrationConfig } from './integrationConfig.interface';
+import { IWorkflowBase } from './workflow.interface';
+export type IConnectIntegration = {
+    id: string;
+    dateCreated: Date;
+    dateUpdated: Date;
+    projectId: string;
+    configs: IConnectIntegrationConfig[];
+    workflows: IWorkflowBase[];
+    type: string;
+    isActive: boolean;
+    customIntegrationId?: string;
+    customIntegration?: ICustomIntegration;
+};
+export interface IConnectIntegrationWithCredentialInfo extends IConnectIntegration {
+    hasCredential: boolean;
+    connectedUserLimitOnDevCred: number;
+    connectedUserLimitReached: boolean;
+}
+export interface IIntegrationMetadata {
+    type: string;
+    name: string;
+    icon: string;
+    brandColor: string;
+}
+export declare function getIntegrationTypeName(integration: IConnectIntegration): string | undefined;
+export declare function isCustomIntegrationTypeName(type: string): boolean;
+export interface IConnectIntegrationWithCredentialInfo extends IConnectIntegration {
+    hasCredential: boolean;
+    connectedUserLimitOnDevCred: number;
+    connectedUserLimitReached: boolean;
+}

package/dist/src/entities/integrationConfig.interface.d.ts

@@ -0,0 +1,9 @@
+import { ModalConfig } from '../types/connect';
+import { IBaseEntity } from './base.entity';
+import { IConnectIntegration } from './integration.interface';
+export interface IConnectIntegrationConfig extends IBaseEntity {
+    id: string;
+    integration: IConnectIntegration;
+    integrationId: string;
+    values: ModalConfig;
+}

package/{src/entities/license.interface.ts → dist/src/entities/license.interface.d.ts}

@@ -1,8 +1,6 @@
-import { ITeam } from "./team.interface";
-
+import { ITeam } from './team.interface';
 export interface ILicense {
     id: string;
     team: ITeam;
     active: boolean;
-  }
-  
+}

package/dist/src/entities/persona.interface.d.ts

@@ -0,0 +1,34 @@
+import { IBaseEntity } from './base.entity';
+import { IConnectCredential } from './connectCredential.interface';
+export type PersonaMeta = {
+    Name?: string;
+    Email?: string;
+} & {
+    [key: string]: unknown;
+};
+export interface IPersona extends IBaseEntity {
+    projectId: string;
+    endUserId: string;
+    meta: PersonaMeta;
+    /**
+     * timestamp value for the latest workflow execution by persona. Will be populated
+     * later on by chronos
+     */
+    dateLastActive: Date;
+    /**
+     * boolean value that tells wether there are integration errors for persona.
+     * In a future work effort this would be populated by the chronos service.
+     */
+    hasIntegrationErrors: boolean;
+    /**
+     * boolean value that tells if persona has any failed workflows. This will be
+     * populated by chronos work effort later
+     */
+    hasWorkflowErrors: boolean;
+    /**
+     * boolean value . A persona may be disabled from connected users dashboard and
+     * will not be able to perform any activity
+     */
+    active: boolean;
+    connectCredentials?: IConnectCredential[];
+}

package/dist/src/entities/project.interface.d.ts

@@ -0,0 +1,32 @@
+import { BillingPlan, ConnectAddOn } from '../types/stripe';
+import { IBaseEntity } from './base.entity';
+import { ICustomIntegration } from './customIntegration.interface';
+import { ITeam } from './team.interface';
+import { IUserSanitized } from './user.interface';
+declare enum ProjectType {
+    PERSONAL = "PERSONAL",
+    BUSINESS = "BUSINESS"
+}
+export interface IProject extends IBaseEntity {
+    title: string;
+    owner: IUserSanitized;
+    ownerId: string;
+    team: ITeam;
+    teamId: string;
+    billingPeriodEndAt?: Date;
+    completedQualification?: boolean;
+    projectType?: ProjectType;
+    projectPurpose?: string;
+    isConnectProject?: boolean;
+    customIntegrations: ICustomIntegration[];
+    isHidden: boolean;
+}
+/**
+ * a light version of a project sent to end users interacting with the connect sdk
+ */
+export interface IConnectSDKProject {
+    id: string;
+    billingPlan: BillingPlan;
+    accessibleFeatures: ConnectAddOn[];
+}
+export {};

package/dist/src/entities/steps.d.ts

@@ -0,0 +1,30 @@
+import { DataType, KeyedSource, TokenizedSource } from '../types/resolvers';
+export type RequestAuthorization = NoAuthorization | BearerAuthorization | BasicAuthorization | QueryParamAuthorization | AuthHeaderAuthorization;
+declare enum RequestAuthorizationType {
+    NONE = "none",
+    BEARER_TOKEN = "bearer",
+    BASIC = "basic",
+    QUERY_PARAMS = "query_params",
+    AUTH_HEADER = "auth_header"
+}
+type NoAuthorization = {
+    type: RequestAuthorizationType.NONE;
+};
+type BearerAuthorization = {
+    type: RequestAuthorizationType.BEARER_TOKEN;
+    token: TokenizedSource<DataType.STRING>;
+};
+type BasicAuthorization = {
+    type: RequestAuthorizationType.BASIC;
+    username: TokenizedSource<DataType.STRING>;
+    password: TokenizedSource<DataType.STRING>;
+};
+type QueryParamAuthorization = {
+    type: RequestAuthorizationType.QUERY_PARAMS;
+    params: KeyedSource<DataType.STRING>[];
+};
+type AuthHeaderAuthorization = {
+    type: RequestAuthorizationType.AUTH_HEADER;
+    headers: KeyedSource<DataType.STRING>[];
+};
+export {};

package/dist/src/entities/team.interface.d.ts

@@ -0,0 +1,19 @@
+import { IBaseEntity } from './base.entity';
+import { ILicense } from './license.interface';
+export interface ITeam extends IBaseEntity {
+    name: string;
+    website?: string;
+    licenses?: ILicense[];
+    organizationId: string;
+}
+export interface ITeamMember {
+    id: string;
+    organizationId: string;
+    userId?: string;
+    role: TeamMemberRole;
+}
+declare enum TeamMemberRole {
+    ADMIN = "ADMIN",
+    MEMBER = "MEMBER"
+}
+export {};

package/dist/src/entities/user.interface.d.ts

@@ -0,0 +1,23 @@
+import { IBaseEntity } from './base.entity';
+import { ITeamMember } from './team.interface';
+export declare enum OnboardingStage {
+    ADD_TEAM_DETAILS = "ADD_TEAM_DETAILS",
+    PROMPT_TUTORIAL = "PROMPT_TUTORIAL",
+    IN_TUTORIAL = "IN_TUTORIAL",
+    COMPLETED = "COMPLETED",
+    COMPLETED_SKIPPED_TUTORIAL = "COMPLETED_SKIPPED_TUTORIAL"
+}
+export interface IUser extends IBaseEntity {
+    firstName: string;
+    middleName: string;
+    lastName: string;
+    email: string;
+    password: string;
+    active: boolean;
+    teamMembers: ITeamMember[];
+    onboardingStage: OnboardingStage;
+    admin: boolean;
+}
+export interface IUserSanitized extends Omit<IUser, 'admin' | 'password'> {
+    impersonated?: boolean;
+}

package/dist/src/entities/workflow.interface.d.ts

@@ -0,0 +1,11 @@
+import { IBaseEntity } from './base.entity';
+import { IProject } from './project.interface';
+export interface IWorkflow extends IBaseEntity {
+    description: string;
+    projectId: string;
+    project: IProject;
+    teamId?: string;
+    isOnboardingWorkflow?: boolean;
+    integrationId?: string;
+}
+export type IWorkflowBase = Omit<IWorkflow, 'project' | 'projectId'>;

package/dist/src/helpers/ConnectUserContext.d.ts

@@ -0,0 +1,18 @@
+import ConnectSDK from '../ConnectSDK';
+import { IConnectSDKProject } from '../entities/project.interface';
+import { ConnectSdkEnvironments } from '../server.types';
+import { AuthenticatedConnectUser } from '../types/connect';
+import { ConnectUser, EventInfo, UserProvidedIntegrationConfig } from '../types/sdk';
+export type IConnectUserContext = {
+    user: ConnectUser;
+    projectId?: string;
+    updateUser?: (user: Partial<AuthenticatedConnectUser>) => void;
+    sendAuthenticatedRequest: ConnectSDK['sendConnectRequest'];
+    environments: ConnectSdkEnvironments;
+    project?: IConnectSDKProject;
+    triggerSDKEvent?: (eventInfo: EventInfo) => void;
+    /**
+     * Ender user supplied integration config
+     */
+    endUserIntegrationConfig?: UserProvidedIntegrationConfig;
+};