refactor: adding v3 trace types

packages/base-types/src/node/utils/trace.ts

@@ -20,9 +20,11 @@ export enum TraceType {
   CHANNEL_ACTION = 'channel-action',
 
   // Voiceflow V3
-  IMAGE = 'image',
-  JSON = 'json',
-  VIDEO = 'video',
+  V3_TEXT = 'v3.text',
+  V3_IMAGE = 'v3.image',
+  V3_JSON = 'v3.json',
+  V3_VIDEO = 'v3.video',
+  V3_DEBUG = 'v3.debug',
 }
 
 export interface BaseTraceFramePath<Event extends BaseEvent = BaseEvent> {

packages/base-types/src/trace/index.ts

@@ -130,4 +130,5 @@ export type AnyTrace =
   | V3.ImageTrace
   | V3.JSONTrace
   | V3.VideoTrace
-  | V3.TextTrace;
+  | V3.TextTrace
+  | V3.DebugTrace;

packages/base-types/src/trace/v3/debug.ts

@@ -0,0 +1,76 @@
+import { BaseTraceFrame, TraceType } from '../../node/utils';
+
+/**
+ * The logging level of the debug trace. This property can be used to
+ * filter for particular debug messages
+ *
+ * Definition of error levels is based on this article: https://sematext.com/blog/logging-levels/
+ */
+export enum DebugInfoLevel {
+  /**
+   * Used for finely detailed information to gain full visibility into the
+   * `general-runtime` and debug a Voiceflow porgram.
+   *
+   * Messages of this nature can be extremely verbose, e.g, may annotate each
+   * step of an algorithm.
+   */
+  Trace = 'trace',
+
+  /**
+   * Less granular, but still detailed information compared to `Trace`.
+   * Used for troubleshooting and diagnosing issues or running an application
+   * in a dev environment.
+   */
+  Debug = 'debug',
+
+  /**
+   * Standard log level indicating an event occurred in the `general-runtime`.
+   *
+   * Should not contain important debugging information, as this setting should not
+   * be enabled on a regular basis.
+   */
+  Info = 'info',
+
+  /**
+   * Indicates an unexpected event that does NOT impede code execution. This
+   * may not necessarily be an error.
+   */
+  Warn = 'warn',
+
+  /**
+   * Indicates an error that impedes code execution and causes non-business-logic
+   * to break, e.g, payment API call did not go through.
+   */
+  Error = 'error',
+
+  /**
+   * Indicates a critical error that impedes critical business functionality, e.g,
+   * could not start the Voiceflow program because it was not compiled.
+   */
+  Fatal = 'fatal',
+}
+
+/**
+ * Indicates the concern or component that spawned this particular debug message.
+ */
+export enum DebugCode {
+  /**
+   * Debug information that is not pinned down to any particular component.
+   */
+  General = 'general',
+
+  /**
+   * Debug information arises from the knowledge base.
+   */
+  KnowledgeBase = 'knowledge_base',
+}
+
+interface StepData {
+  code: DebugCode;
+  level: DebugInfoLevel;
+  details: Record<string, any>;
+}
+
+export interface TraceFrame extends BaseTraceFrame<StepData> {
+  type: TraceType.V3_DEBUG;
+}

packages/base-types/src/trace/v3/image.ts

@@ -5,5 +5,5 @@ interface StepData {
 }
 
 export interface TraceFrame extends BaseTraceFrame<StepData> {
-  type: TraceType.IMAGE;
+  type: TraceType.V3_IMAGE;
 }

packages/base-types/src/trace/v3/index.ts

@@ -1,3 +1,4 @@
+export { TraceFrame as DebugTrace } from './debug';
 export { TraceFrame as ImageTrace } from './image';
 export { TraceFrame as JSONTrace } from './json';
 export { TraceFrame as TextTrace } from './text';

packages/base-types/src/trace/v3/json.ts

@@ -5,5 +5,5 @@ interface StepData {
 }
 
 export interface TraceFrame extends BaseTraceFrame<StepData> {
-  type: TraceType.JSON;
+  type: TraceType.V3_JSON;
 }

packages/base-types/src/trace/v3/text.ts

@@ -7,5 +7,5 @@ interface StepData {
 }
 
 export interface TraceFrame extends BaseTraceFrame<StepData> {
-  type: TraceType.TEXT;
+  type: TraceType.V3_TEXT;
 }

packages/base-types/src/trace/v3/video.ts

@@ -5,5 +5,5 @@ interface StepData {
 }
 
 export interface TraceFrame extends BaseTraceFrame<StepData> {
-  type: TraceType.VIDEO;
+  type: TraceType.V3_VIDEO;
 }