@useparagon/core 0.0.1-canary.1

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@useparagon/core",
+  "version": "0.0.1-canary.1",
+  "description": "Core libraries for paragraph",
+  "repository": "https://github.com/useparagon/paragraph",
+  "packageManager": "yarn@3.4.1",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "require": "./dist/index.js"
+    },
+    "./*": {
+      "import": "./src/*/index.ts",
+      "require": "./dist/*/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*/index.d.js",
+        "./dist/index.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "yarn clean && tsc -b tsconfig.release.json",
+    "build:watch": "tsc -b tsconfig.release.json -w",
+    "build:dev": "tsc -b tsconfig.json",
+    "build:dev:watch": "tsc -b tsconfig.json -w",
+    "clean": "rimraf ./dist ./coverage",
+    "format": "prettier --ignore-path ../../.prettierignore --config ../../.prettierrc --write .",
+    "format:check": "prettier --ignore-path ../../.prettierignore --config ../../.prettierrc --check .",
+    "lint": "eslint --ignore-path ../../.eslintignore --config ../../.eslintrc.json --ext .ts .",
+    "lint:fix": "eslint --ignore-path ../../.eslintignore --config ../../.eslintrc.json --ext .ts --fix .",
+    "release:publish:canary": "npm publish --access restricted --tag next",
+    "start:dev": "ts-node -r tsconfig-paths/register src/index.ts"
+  },
+  "dependencies": {
+    "cron-parser": "^4.9.0",
+    "stacktrace-parser": "^0.1.8",
+    "tslib": "2.3.1",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "^4.2.0",
+    "@types/node": "^18.13.0",
+    "@types/uuid": "^9.0.1",
+    "@typescript-eslint/eslint-plugin": "^5.21.0",
+    "@typescript-eslint/parser": "^5.21.0",
+    "eslint": "^8.14.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jest": "^27.0.1",
+    "prettier": "^2.2.1",
+    "prettier-plugin-organize-imports": "^3.2.3",
+    "rimraf": "~4.4.0",
+    "ts-node": "10.9.1",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^4.4.4"
+  }
+}

package/src/event/event.interface.ts

@@ -0,0 +1,18 @@
+export interface IEvent<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /**
+   * id of event
+   */
+  id?: string;
+
+  /**
+   * name of event
+   */
+  name: string;
+
+  /**
+   * schema of event
+   */
+  schema: T;
+}

package/src/event/index.ts

@@ -0,0 +1 @@
+export * from './event.interface';

package/src/execution/context.constants.ts

@@ -0,0 +1,9 @@
+/**
+ * special reserved key used by proxies to get keys accessed while traversing an object
+ */
+export const PROXY_KEY_GET_KEYS: string = '@@__PROXY_KEY_GET_KEYS__@@';
+
+/**
+ * special reserved key used by proxies to get the step which the proxy refers to
+ */
+export const PROXY_KEY_GET_STEP: string = '@@__PROXY_KEY_GET_STEP__@@';

package/src/execution/context.interface.ts

@@ -0,0 +1,39 @@
+import { ISecretOutput } from '../secret';
+import { IActionStep } from '../steps/library/action/action.interface';
+import { IFanOutStep } from '../steps/library/fanout/fanout.interface';
+import { IFunctionStep } from '../steps/library/function';
+import { IEventStep } from '../triggers/event/event.interface';
+
+/**
+ * creates a type from the first elememt of an array
+ *
+ * @todo move to utility file
+ */
+export type FirstElementType<T> = T extends [infer U, ...unknown[]] ? U : never;
+
+/**
+ * an object containing methods to get metadata about an execution
+ */
+export interface IContext {
+  /**
+   * get a reference to the output of a step execution
+   * @param step
+   */
+  getOutput<S extends IEventStep<any>>(step: S): S['schema'];
+  getOutput<I extends Record<string, unknown>, O, S extends IActionStep>(
+    step: S,
+  ): O;
+  getOutput<
+    S extends IFanOutStep,
+    O = FirstElementType<S['parameters']['iterator']>,
+  >(
+    step: S,
+  ): O;
+  getOutput<S extends IFunctionStep>(step: S): { result: any };
+
+  /**
+   * get a reference to an environment secret
+   * @param key
+   */
+  getEnvironmentSecret(key: string): ISecretOutput;
+}

package/src/execution/context.ts

@@ -0,0 +1,72 @@
+import { ISecretOutput } from '../secret/secret.interface';
+import { IActionStep } from '../steps/library/action/action.interface';
+import { IFanOutStep } from '../steps/library/fanout/fanout.interface';
+import { IFunctionStep } from '../steps/library/function/function.interface';
+import { IStep } from '../steps/step.interface';
+import { IEventStep } from '../triggers/event/event.interface';
+import { PROXY_KEY_GET_KEYS, PROXY_KEY_GET_STEP } from './context.constants';
+import { FirstElementType, IContext } from './context.interface';
+
+export enum TokenizedIdentifiers {
+  START = '__TOKENIZED_START__',
+  END = '__TOKENIZED_END__',
+}
+
+export class Context implements IContext {
+  /**
+   * get a reference to the output of a step execution
+   *
+   * @param step
+   * @todo implement recursive proxy
+   * @todo add missing type definitions for steps
+   */
+  getOutput<S extends IEventStep>(step: S): S['parameters']['payload'];
+  getOutput<I extends Record<string, unknown>, O, S extends IActionStep>(
+    step: S,
+  ): O;
+  getOutput<
+    S extends IFanOutStep,
+    O = FirstElementType<S['parameters']['iterator']>,
+  >(step: S): O;
+  getOutput<S extends IFunctionStep>(step: S): { result: any };
+  getOutput(step: IStep): any {
+    const keys: string[] = [];
+    const proxy = new Proxy(step, {
+      get(_target: any, property: string | Symbol): any {
+        if (property === '_isMockFunction') {
+          return false;
+        } else if (
+          typeof property === 'string' &&
+          property.startsWith('@@__IMMUTABLE_')
+        ) {
+          return undefined;
+        } else if (property === Symbol.toPrimitive) {
+          return () =>
+            `${TokenizedIdentifiers.START}steps:${step.id}:${keys.join('.')}${
+              TokenizedIdentifiers.END
+            }`;
+        } else if (property === PROXY_KEY_GET_KEYS) {
+          return (): string[] => [...keys];
+        } else if (property === PROXY_KEY_GET_STEP) {
+          return (): IStep => step;
+        }
+
+        if (!keys.includes(property.toString())) {
+          keys.push(property.toString());
+        }
+        return proxy;
+      },
+    });
+    return proxy;
+  }
+
+  /**
+   * get a reference to an environment secret
+   *
+   * @param key
+   * @todo implement `getEnvironmentSecret` method
+   */
+  getEnvironmentSecret(_key: string): ISecretOutput {
+    throw new Error('Not implemented!');
+  }
+}

package/src/execution/context.utils.ts

@@ -0,0 +1,53 @@
+import nodeUtils from 'node:util';
+
+import { DataType, VariableSource } from '../resolvers/resolvers.interface';
+import { IStep } from '../steps';
+import { PROXY_KEY_GET_KEYS, PROXY_KEY_GET_STEP } from './context.constants';
+
+/**
+ * determines if an object is an instance of a Proxy
+ *
+ * @param maybeProxy
+ */
+export function isProxy(maybeProxy: any): boolean {
+  return nodeUtils.types.isProxy(maybeProxy);
+}
+
+/**
+ * returns the keys that were accessed in the proxy
+ *
+ * @param proxy
+ * @returns
+ */
+export function getKeysAccessedFromProxy(proxy: any): string[] {
+  return proxy[PROXY_KEY_GET_KEYS]();
+}
+
+/**
+ * returns the step that a proxy references
+ *
+ * @param proxy
+ * @returns
+ */
+export function getStepFromProxy(proxy: any): IStep {
+  return proxy[PROXY_KEY_GET_STEP]();
+}
+
+/**
+ * converts a proxy to variable source
+ *
+ * @param proxy
+ * @returns
+ */
+export function proxyToVariableSource<T extends DataType>(
+  proxy: any,
+): VariableSource<T> {
+  const step: IStep = getStepFromProxy(proxy);
+  const keys: string[] = getKeysAccessedFromProxy(proxy);
+
+  return {
+    type: 'VARIABLE',
+    stepId: step.id,
+    path: keys,
+  };
+}

package/src/execution/index.ts

@@ -0,0 +1,2 @@
+export * from './context';
+export * from './context.interface';

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './integration';
+export { StateMachine } from './stateMachine/stateMachine.interface';
+export * from './steps';
+export * from './triggers';
+export * from './user';
+export * from './workflow';

package/src/integration/custom-integration.interface.ts

@@ -0,0 +1,20 @@
+import { IIntegration } from './integration.interface';
+
+/**
+ * different mechanisms for authentication
+ */
+export enum AuthenticationScheme {
+  BASIC = 'basic',
+  OAUTH = 'oauth',
+  OAUTH_CLIENT_CREDENTIAL = 'oauth_client_credential',
+  SERVICE_ACCOUNT = 'service_account',
+  OAUTH_APP = 'oauth_app',
+  IMPERSONATED_APP = 'impersonated_app',
+}
+
+/**
+ * an entity representing a custom integration
+ */
+export interface ICustomIntegration extends IIntegration {
+  authenticationType: AuthenticationScheme;
+}

package/src/integration/index.ts

@@ -0,0 +1,2 @@
+export * from './integration.interface';
+export * from './integration-config.interface';

package/src/integration/integration-config.interface.ts

@@ -0,0 +1,19 @@
+/**
+ * configuration for an integration
+ */
+export interface IIntegrationConfig {
+  /**
+   * a short description for the integration
+   */
+  description: string;
+
+  /**
+   * a detailed description for the integration displayed in the Connect Portal
+   */
+  overviewText: string;
+
+  /**
+   * scopes needed for the integration
+   */
+  scopes: string;
+}

package/src/integration/integration.interface.ts

@@ -0,0 +1,16 @@
+import { IBaseStep, StepType } from '../steps/step.interface-base';
+
+/**
+ * an entity representing an outside datasource
+ */
+export interface IIntegration {}
+
+/**
+ * an action step used by an integration
+ */
+export interface IIntegrationActionStep extends IBaseStep {
+  /**
+   * the step type
+   */
+  type: StepType.ACTION;
+}

package/src/operator/index.ts

@@ -0,0 +1,2 @@
+export { default as BooleanTrue } from './operators/BooleanTrue';
+export { default as StringContains } from './operators/StringContains';

package/src/operator/operator.interface.ts

@@ -0,0 +1,6 @@
+import { VariableSource } from '../resolvers/resolvers.interface';
+
+/**
+ * a value that can be used in an operator function
+ */
+export type IOperatorValue = VariableSource | string | number | boolean;

package/src/operator/operators/BooleanTrue.ts

@@ -0,0 +1,20 @@
+import { resolveToSource } from '../../resolvers/resolver.utils';
+import {
+  Condition,
+  DataType,
+  Operator,
+} from '../../resolvers/resolvers.interface';
+import { IOperatorValue } from '../operator.interface';
+
+/**
+ * evaluates whether a value is truthy
+ *
+ * @param variable value to evaluate
+ */
+export default function BooleanTrue(variable: IOperatorValue): Condition {
+  const variableAsSource = resolveToSource(variable, DataType.BOOLEAN);
+  return {
+    operator: Operator.BooleanTrue,
+    variable: variableAsSource,
+  };
+}

package/src/operator/operators/StringContains.ts

@@ -0,0 +1,27 @@
+import { resolveToSource } from '../../resolvers/resolver.utils';
+import {
+  Condition,
+  DataType,
+  Operator,
+} from '../../resolvers/resolvers.interface';
+import { IOperatorValue } from '../operator.interface';
+
+/**
+ * constructs a `StringContains` operator
+ *
+ * @param variable
+ * @param argument
+ */
+export default function StringContains(
+  variable: IOperatorValue,
+  argument: IOperatorValue,
+): Condition {
+  const variableAsSource = resolveToSource(variable, DataType.STRING);
+  const argumentAsSource = resolveToSource(argument, DataType.STRING);
+
+  return {
+    operator: Operator.StringContains,
+    variable: variableAsSource,
+    argument: argumentAsSource,
+  };
+}

package/src/resolvers/index.ts

@@ -0,0 +1,2 @@
+export * from './resolver.utils';
+export * from './resolvers.interface';

package/src/resolvers/resolver.utils.ts

@@ -0,0 +1,157 @@
+import { TokenizedIdentifiers } from '../execution/context';
+import { isProxy, proxyToVariableSource } from '../execution/context.utils';
+import {
+  isConditionalInput,
+  parseConditionInput,
+} from '../steps/library/conditional/conditional.utils';
+import {
+  DataType,
+  DataTypeValues,
+  KeyedSource,
+  Source,
+  TokenizedValue,
+} from './resolvers.interface';
+
+/**
+ * break tokenized string to parts
+ * @param input
+ * @returns
+ */
+const tokenizedStringToParts = (input: string): string[] => {
+  const parts: string[] = [];
+  let count: number = 0;
+  input
+    .split(/(__TOKENIZED_START__|__TOKENIZED_END__)/)
+    .forEach((part: string) =>
+      part === TokenizedIdentifiers.START
+        ? count++
+        : part === TokenizedIdentifiers.END && count > 0
+        ? count--
+        : count > 0
+        ? parts.push(
+            `${TokenizedIdentifiers.START}${part}${TokenizedIdentifiers.END}`,
+          )
+        : part && parts.push(part),
+    );
+  return parts;
+};
+
+/**
+ * check if string is valid json or not
+ * @param maybeJson
+ * @returns
+ */
+const isValidJSON = (maybeJson: unknown): boolean => {
+  if (
+    !maybeJson ||
+    !(typeof maybeJson === 'string' || typeof maybeJson === 'object')
+  ) {
+    return false;
+  } else if (typeof maybeJson === 'string') {
+    try {
+      const parsedJson = JSON.parse(maybeJson);
+      if (parsedJson === null) {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * resolve source string to source object
+ * @param value
+ * @param dataType
+ * @returns
+ */
+export const resolveToSource = <T extends DataType>(
+  value: unknown,
+  dataType: T,
+): Source<T> => {
+  if (isProxy(value)) {
+    return { ...proxyToVariableSource(value), dataType };
+  } else if (typeof value === 'number') {
+    return {
+      dataType,
+      type: 'VALUE',
+      value: value,
+    } as DataTypeValues[T];
+  } else if (
+    typeof value === 'string' &&
+    value.includes(TokenizedIdentifiers.START)
+  ) {
+    const parts: string[] = tokenizedStringToParts(value);
+
+    return {
+      dataType,
+      type: 'TOKENIZED',
+      parts: parts.map((part: string): TokenizedValue<DataType> => {
+        if (part.startsWith(TokenizedIdentifiers.START)) {
+          const sanitizedPart: string = part
+            .replace(TokenizedIdentifiers.START, '')
+            .replace(TokenizedIdentifiers.END, '');
+          const [type, typeId, paths]: string[] = sanitizedPart.split(':');
+
+          switch (type) {
+            case 'steps':
+              return {
+                dataType,
+                type: 'VARIABLE',
+                stepId: typeId,
+                path: paths.split('.'),
+              };
+            default:
+              throw new Error('Invalid tokenized string passed');
+          }
+        } else {
+          let dataType: string = DataType.STRING;
+          if (isValidJSON(part)) {
+            dataType = DataType.OBJECT;
+          }
+
+          return {
+            dataType,
+            type: 'VALUE',
+            value: part,
+          } as DataTypeValues[T];
+        }
+      }),
+    };
+  } else if (isConditionalInput(value)) {
+    return {
+      type: 'CONDITION',
+      condition: parseConditionInput(value),
+    };
+  }
+
+  return {
+    type: 'VALUE',
+    value: value as DataTypeValues[T],
+    dataType,
+  };
+};
+
+/**
+ * convert {key:value} to [{key:source}]
+ * @param param
+ */
+export const resolveParamsToSources = <T extends DataType = DataType.ANY>(
+  param: Record<string, unknown>,
+  dataType: T = DataType.ANY as T,
+): KeyedSource<T>[] => {
+  const paramsWithSources: KeyedSource<T>[] = Object.keys(param).reduce(
+    (sources: KeyedSource<T>[], key: string): KeyedSource<T>[] => {
+      const value = param[key];
+      const keyedSource: KeyedSource<T> = {
+        key,
+        source: resolveToSource(value, dataType),
+      };
+      return [...sources, keyedSource];
+    },
+    [],
+  );
+
+  return paramsWithSources;
+};