@intuned/runtime-dev 0.0.1-split.0

package/src/runtime/executionHelpers.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import {
+  getExecutionContext,
+  runWithContext,
+} from "../common/asyncLocalStorage";
+import { RunError, extendPayload, runInfo } from "./index";
+import { RunEnvironment, RunType } from "./enums";
+
+describe("Execution Helpers", () => {
+  it("should be able to get execution info", () => {
+    runWithContext(
+      {
+        runEnvironment: RunEnvironment.IDE,
+        // runType: RunType.SYNC,
+        runId: "test-run-id",
+        extendedPayloads: [],
+      },
+      () => {
+        expect(runInfo().runId).toEqual("test-run-id");
+      }
+    );
+  });
+
+  it("should be able to mutate extendedPayloads and get the accmulated value at the end ", () => {
+    const context = {
+      extendedPayloads: [],
+      runId: "test-run-id",
+    };
+
+    runWithContext(
+      {
+        runEnvironment: RunEnvironment.IDE,
+        // runType: RunType.SYNC,
+        runId: "test-run-id",
+        extendedPayloads: [],
+      },
+      () => {
+        expect(getExecutionContext()?.extendedPayloads).toEqual([]);
+        extendPayload({
+          api: "test-api",
+          parameters: {},
+        });
+
+        expect(getExecutionContext()?.extendedPayloads).toEqual([
+          {
+            api: "test-api",
+            parameters: {},
+          },
+        ]);
+
+        extendPayload({
+          api: "test-api",
+          parameters: {},
+        });
+        extendPayload({
+          api: "test-api",
+          parameters: {},
+        });
+        extendPayload({
+          api: "test-api",
+          parameters: {},
+        });
+
+        const context = getExecutionContext();
+
+        expect(context?.extendedPayloads).toHaveLength(4);
+      }
+    );
+  });
+});

package/src/runtime/export.d.ts

@@ -0,0 +1,202 @@
+import { RunEnvironment } from "./enums";
+
+/**
+ * ## Description
+ * In the context of a job, extendTimeout will increase the timeout of the currently executing payload.
+ * This is useful when the payload is expected to take a long time. For example, when running pagination code.
+ *
+ * @example
+ * ```typescript Example
+ * import { extendTimeout } from "@intuned/sdk/runtime"
+ *
+ * extendTimeout();
+ * ```
+ *
+ */
+export declare function extendTimeout(): void;
+
+/**
+ * ## Description
+ * In the context of a job or queue execution, extendPayload appends new payloads to the end of the queue of job.
+ * Calling extendPayload will also call extendTimeout.
+ *
+ * @param {Payload | Payload[]} payload - The payload or array of payloads to extend. you can specify the api name and what parameters you want to pass it, the new added apis will use the same proxy and auth-session settings as the api that extended them
+ *
+ * @example
+ * ```typescript Single payload
+ * import { extendPayload } from "@intuned/sdk/runtime"
+ *
+ * // this function will append the exampleApi to the end of the queue or job it's executing in.
+ * extendPayload({ api: 'exampleApi', parameters: { key: 'value' } });
+ * ```
+ *
+ * @example
+ * ```typescript Array of payloads
+ * import { extendPayload } from "@intuned/sdk/runtime"
+ *
+ * const payloadArray: Payload[] = [
+ *   { api: 'exampleApi1', parameters: { key1: 'value1' } },
+ *   { api: 'exampleApi2', parameters: { key2: 'value2' } }
+ * ];
+ *
+ * // this function will append 2 apis to the end of the queue or job it's executing in.
+ * extendPayload(payloadArray);
+ * ```
+ */
+export declare function extendPayload(payload: Payload | Payload[]): void;
+
+/**
+ * @interface Payload
+ * @property {string} api - The API path you want to extend.
+ * @property {Record<string, any>} parameters - A record of key-value pairs representing the parameters to be sent to the API
+ *
+ * @example
+ *
+ * ```typescript payload
+ * import { Payload } from "@intuned/sdk/runtime"
+ *
+ * const payload: Payload = {
+ *   api: 'exampleApi',
+ *   parameters: {
+ *     key1: 'value1',
+ *     key2: 'value2'
+ *   }
+ * };
+ * ```
+ */
+export interface Payload {
+  api: string;
+  parameters: Record<string, any>;
+}
+
+/**
+ * Retrieves information about the current run environment.
+ *
+ * @returns {RunInfo} An object containing details about the run environment and the run ID.
+ *
+ * @example
+ * ```typescript runInfo
+ * import { runInfo } from "@intuned/sdk/runtime"
+ *
+ * const info = runInfo();
+ * console.log(info.runEnvironment); // Outputs the run environment, IDE or DEPLOYED
+ * console.log(info.runId); // Outputs the run ID, if available, in IDE run id will be undefined
+ * ```
+ */
+export declare function runInfo(): RunInfo;
+
+/**
+ * Represents information about the current run.
+ *
+ * @interface RunInfo
+ * @property {RunEnvironment} runEnvironment - the run environment `IDE` or `DEPLOYED`
+ * @property {string} [runId] - Optional. The ID of the current run, in IDE environment, run id will be undefined
+ */
+export interface RunInfo {
+  runEnvironment: RunEnvironment;
+  runId?: string;
+  jobId?: string;
+  jobRunId?: string;
+  queueId?: string;
+  proxy?: string;
+}
+
+/**
+ * @interface RunErrorOptions
+ * @property {boolean} [retryable] - Optional. Indicates whether the error is retryable.
+ * @property {number} [status_code] - Optional. The HTTP status code associated with the error.
+ * @property {string} [error_code] - Optional. A specific error code to identify the type of error.
+ *
+ * @example
+ * ```typescript RunErrorOptions
+ * import { RunErrorOptions } from "@intuned/sdk/runtime"
+ *
+ * const options: RunErrorOptions = {
+ *   retryable: true,
+ *   status_code: 500,
+ *   error_code: 'SERVER_ERROR'
+ * };
+ * ```
+ */
+export interface RunErrorOptions {
+  retryable?: boolean;
+  status_code?: number;
+  error_code?: string;
+}
+
+/**
+ * Represents an error that occurs during a run.
+ *
+ * @class
+ * @extends Error
+ *
+ * @param {string} message - The error message.
+ * @param {RunErrorOptions} [options] - Optional. Additional options for the error.
+ *
+ * @property {RunErrorOptions} options - The options associated with the error.
+ *
+ * @example
+ * ```typescript RunError
+ * import { RunError } from "@intuned/sdk/runtime"
+ *
+ * throw new RunError('An error occurred', {
+ *   retryable: true,
+ *   status_code: 500,
+ *   error_code: 'SERVER_ERROR'
+ * });
+ *
+ * ```
+ */
+export declare class RunError extends Error {
+  constructor(message: string, options?: RunErrorOptions);
+  options: RunErrorOptions;
+}
+
+/**
+ * in the create auth session flow, you might to need a multiple choice answer from the user, requestMultipleChoice prompts the user with the question and possible options and returns their selection.
+ *
+ * **Note:** This function is currently in beta and may be subject to changes.
+ *
+ * @param {string} message - The message to display to the user.
+ * @param {string[]} choices - An array of choices to present to the user.
+ *
+ * @example
+ * ```typescript requestMultipleChoice
+ * // in auth-sessions/create.ts
+ *
+ * import { requestMultipleChoice } from "@intuned/sdk/runtime"
+ *
+ * const message = "What is your favorite color?";
+ * const choices = ["Red", "Blue", "Green", "Yellow"];
+ *
+ * const selectedChoice = yield requestMultipleChoice(message, choices);
+ *
+ * console.log(selectedChoice);
+ * ```
+ */
+export declare function requestMultipleChoice(
+  message: string,
+  choices: string[]
+): unknown;
+
+/**
+ * **Note:** This function is currently in beta and may be subject to changes.
+ *
+ * requestOTP help you to ask the user for an otp in the create auth-session flow.
+ *
+ * @param {string} message - The message to display to the user.
+ *
+ * @example
+ * ```typescript requestOTP
+ * // in auth-sessions/create.ts
+ *
+ * import { requestOTP } from "@intuned/sdk/runtime"
+ *
+ * const message = "please submit and OTP from your authenticator app";
+ *
+ * const otp = yield requestOTP(message);
+ *
+ * console.log(otp);
+ * ```
+ */
+export declare function requestOTP(message: string): unknown;

package/src/runtime/extendPayload.ts

@@ -0,0 +1,22 @@
+import { getExecutionContext } from "../common/asyncLocalStorage";
+import { Payload } from "./export";
+import { extendTimeout } from "./extendTimeout";
+
+export function extendPayload(payload: Payload | Payload[]) {
+  const context = getExecutionContext();
+
+  if (!context) {
+    throw new Error("extendPayload failed due to an internal error.");
+  }
+
+  const items = Array.isArray(payload) ? payload : [payload];
+
+  if (!context.extendedPayloads) {
+    context.extendedPayloads = [...items];
+    return;
+  }
+
+  context?.extendedPayloads.push(...items);
+
+  extendTimeout();
+}

package/src/runtime/extendTimeout.ts

@@ -0,0 +1,32 @@
+import { getExecutionContext } from "../common/asyncLocalStorage";
+
+const _DEBOUNCE_TIME = 60_000;
+
+export function extendTimeout() {
+  const context = getExecutionContext();
+
+  if (!context) {
+    throw new Error("extendTimeout failed due to an internal error.");
+  }
+
+  const { timeoutInfo } = context;
+
+  if (
+    !timeoutInfo ||
+    timeoutInfo.timeoutTimestamp === undefined ||
+    timeoutInfo.timeoutDuration === undefined ||
+    timeoutInfo.extendTimeoutCallback === undefined
+  ) {
+    return;
+  }
+
+  const newTimeoutStamp = Date.now() + timeoutInfo.timeoutDuration;
+
+  if (newTimeoutStamp - timeoutInfo.timeoutTimestamp < _DEBOUNCE_TIME) {
+    return;
+  }
+
+  timeoutInfo.timeoutTimestamp = newTimeoutStamp;
+
+  void timeoutInfo.extendTimeoutCallback().catch(() => undefined);
+}

package/src/runtime/index.ts

@@ -0,0 +1,8 @@
+export { extendPayload } from "./extendPayload";
+export { extendTimeout } from "./extendTimeout";
+export { runInfo } from "./runInfo";
+export { RunError } from "./RunError";
+
+export { requestMultipleChoice, requestOTP } from "./requestMoreInfo";
+
+export {getDownloadDirectoryPath} from "./downloadDirectory";

package/src/runtime/requestMoreInfo.ts

@@ -0,0 +1,40 @@
+interface RequestMoreInfoReturnTypeBase {
+  [REQUEST_MORE_INFO_KEY]: true;
+  action: "request_more_info";
+}
+
+interface RequestMultipleChoiceReturnType
+  extends RequestMoreInfoReturnTypeBase {
+  messageToUser: string;
+  choices: string[];
+  requestType: "multiple_choice";
+}
+
+interface RequestOtpReturnType extends RequestMoreInfoReturnTypeBase {
+  messageToUser: string;
+  requestType: "otp";
+}
+
+const REQUEST_MORE_INFO_KEY: unique symbol = Symbol("REQUEST_MORE_INFO");
+
+export function requestOTP(messageToUser: string): RequestOtpReturnType {
+  return {
+    [REQUEST_MORE_INFO_KEY]: true,
+    action: "request_more_info",
+    messageToUser,
+    requestType: "otp",
+  };
+}
+
+export function requestMultipleChoice(
+  messageToUser: string,
+  choices: string[]
+): RequestMultipleChoiceReturnType {
+  return {
+    [REQUEST_MORE_INFO_KEY]: true,
+    action: "request_more_info",
+    messageToUser,
+    requestType: "multiple_choice",
+    choices,
+  };
+}

package/src/runtime/runInfo.ts

@@ -0,0 +1,19 @@
+import { getExecutionContext } from "../common/asyncLocalStorage";
+import { RunInfo } from "./export";
+import { RunType, RunEnvironment } from "./enums";
+
+export function runInfo(): RunInfo {
+  const context = getExecutionContext();
+
+  if (!context) {
+    return {
+      runEnvironment: RunEnvironment.IDE,
+      // runType: RunType.SYNC,
+    };
+  }
+
+  //remove extendedPayloads from the user exposed data
+  const { extendedPayloads: _extendedPayloads, ...rest } = context;
+
+  return rest;
+}

package/template.tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "target": "ES2021",
+    "lib": [
+      "dom",
+      "es2021"
+    ],
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "skipLibCheck": true
+  }
+}

package/tsconfig.eslint.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["**/*.ts", "**/*.d.ts"],
+  "exclude": ["node_modules"]
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "esnext",
+    "esModuleInterop": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "strict": false,
+    "strictNullChecks": true,
+    "rootDir": "./src",
+    "sourceMap": false,
+    "declaration": true,
+    "emitDeclarationOnly": false,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.d.ts",
+    "types-package/noEmpty.ts",
+    "src/assets/**/*"
+  ],
+  "exclude": ["node_modules", "**/*.test.ts", "**/__tests__/*"]
+}

package/typedoc.json

@@ -0,0 +1,49 @@
+{
+  // base config
+  "out": "docs/content",
+  "tsconfig": "./types-package/tsconfig.json",
+  "entryPoints": ["./types-package/ai-extractors/index.d.ts"],
+
+  // specific inclusions and exclusions
+  // "excludeProtected": true,
+  // "excludeNotDocumented": true,
+
+  "exclude": [
+    "./src.ts/_admin/**/*",
+    "./src.ts/_tests/**/*",
+    "./src.ts/testcases/**/*"
+  ],
+
+  // plugins
+  "plugin": [
+    // "./plugins/reorderSections.mjs",
+    "typedoc-plugin-remove-references", // remove additional references that clutter documentation
+    "typedoc-plugin-markdown", // generate markdown files
+    "typedoc-plugin-frontmatter", // add frontmatter to markdown files, prereq for the below custom plugin
+    "./docs/plugins/typedoc-plugin-mintlify-frontmatter.mjs", // formats frontmatter to match mintlify
+    "./docs/plugins/typedoc-plugin-navigation-output.mjs" // formats navigation to match mintlify
+  ],
+
+  // formatting + mintlify compatibility
+  "fileExtension": ".mdx", // use mdx files for mintlfiy compatibility
+  "entryFileName": "index.mdx", // rename entry from "README.md" to "index.mdx"
+  "hidePageHeader": true, // hide page header, conflicts with mintlify
+  "hidePageTitle": true, // hide page title, conflicts with mintlify
+  "hideBreadcrumbs": true, // hide breadcrumbs, conflicts with mintlify
+  "useCodeBlocks": true, // makes API definitions more readable
+
+  "expandObjects": false,
+  // "parametersFormat": "table", // readability
+  // "propertiesFormat": "table", // readability
+  "navigation": {
+    "includeCategories": true,
+    "includeGroups": false
+  },
+  "disableSources": true,
+  "hideParameterTypesInTitle": false,
+  // "membersWithOwnFile": ["Class", "Enum", "Interface", "Function"],
+  // "hideParameterTypesInTitle": true,
+  "readme": "none",
+  "githubPages": false,
+  "excludeExternals": true
+}

package/vite.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vite";
+import macros from "vite-plugin-babel-macros"
+require('dotenv').config();
+
+export default defineConfig({
+  test: {
+    reporters: ['verbose', "html"],
+    outputFile: { html: './reports/html/index.html' },
+    testTimeout: 30000,
+    env: {
+      RUN_ENVIRONMENT: "AUTHORING",
+    }
+  },
+  plugins: [
+    macros(),
+  ],
+});