apps/kyb-app/src/pages/CollectionFlow/hooks/useAdditionalWorkflowContext/useAdditionalWorkflowContext.ts (1)

4-16: Add TypeScript types for better type safety and documentation

Consider adding TypeScript interfaces to clearly define the shape of the context object.

+interface WorkflowContext {
+  query: {
+    token: string | null;
+  };
+}

-export const useAdditionalWorkflowContext = () => {
+export const useAdditionalWorkflowContext = (): WorkflowContext => {

apps/kyb-app/src/components/organisms/DynamicUI/StateManager/components/ActionsHandler/action-handlers/plugin-runner.handler.ts (1)

14-16: Consider adding error handling around plugin execution

While the implementation is functionally correct, consider adding error handling to gracefully handle plugin execution failures and context retrieval issues.

 async run(_: CollectionFlowContext, action: Action<PluginRunnerParams>, api: StateMachineAPI) {
-    await api.invokePlugin(action.params.pluginName);
+    try {
+      await api.invokePlugin(action.params.pluginName);
+      const context = api.getContext();
+      if (!context) {
+        throw new Error('Context not available after plugin execution');
+      }
+      return context;
+    } catch (error) {
+      console.error(`Plugin execution failed: ${action.params.pluginName}`, error);
+      throw error;
+    }
-    return api.getContext();
 }

apps/kyb-app/src/components/organisms/DynamicUI/StateManager/StateManager.tsx (1)

Line range hint 53-53: Remove @ts-ignore comment

There's a @ts-ignore comment that bypasses TypeScript type checking. This could hide potential type-related issues.

Consider fixing the underlying type issue instead of suppressing it. If you need help resolving the type error, I can assist you.

apps/kyb-app/src/components/organisms/DynamicUI/StateManager/hooks/useMachineLogic/useMachineLogic.ts (3)

17-17: Consider adding type validation for additionalContext

While the typing is correct, consider adding runtime validation to ensure the additionalContext meets expected shape/constraints before passing it to plugins.

export const useMachineLogic = (
  machine: WorkflowBrowserSDK,
-  additionalContext?: AnyRecord,
+  additionalContext?: AnyRecord,
+  validate = true,
): { isInvokingPlugin: boolean; machineApi: StateMachineAPI } => {
+  useEffect(() => {
+    if (validate && additionalContext) {
+      // Add validation logic here
+      // Throw or log warning if validation fails
+    }
+  }, [additionalContext, validate]);

---

25-25: Document the impact of additionalContext on plugins

Please add JSDoc comments explaining:

• The expected structure of additionalContext
• How plugins utilize this additional context
• Any side effects or behavioral changes when context is provided

+/**
+ * Invokes a plugin with additional context
+ * @param pluginName - The name of the plugin to invoke
+ * @param additionalContext - Optional context that affects plugin behavior:
+ *   - Expected properties and their purpose
+ *   - How plugins consume this context
+ *   - Any side effects when context is provided
+ */
async (pluginName: string) => {

---

32-32: Consider memoizing additionalContext if it changes frequently

The addition of additionalContext to the dependency array is correct. However, if it changes frequently, consider memoizing it at a higher level to prevent unnecessary callback recreations and potential re-renders.

// In parent component:
const memoizedContext = useMemo(
  () => additionalContext,
  [/* dependencies that should trigger context updates */]
);

sdks/workflow-browser-sdk/src/lib/types.ts (2)

65-65: Add JSDoc documentation for the new property.

The addition of additionalContext aligns well with the PR objectives. However, please add JSDoc documentation to describe:

• The purpose of this property
• Expected structure of the context
• Any constraints or requirements
• Usage examples

Example documentation:

+  /**
+   * Additional context to be passed to the workflow.
+   * This can be used to provide extra data that might be needed during workflow execution.
+   * @example
+   * {
+   *   userId: '123',
+   *   metadata: { source: 'external' }
+   * }
+   */
   additionalContext?: AnyRecord;

---

65-65: Consider using a more specific type for better type safety.

While AnyRecord provides flexibility, it might be too permissive and could lead to runtime issues. Consider:

1. Creating a specific interface for the context
2. Using generics to allow consumers to define their context type
3. Adding runtime validation using a schema validation library

Example using generics:

-export interface WorkflowOptionsBrowser extends Omit<WorkflowOptions, 'workflowActions'> {
+export interface WorkflowOptionsBrowser<TContext extends Record<string, unknown> = AnyRecord> extends Omit<WorkflowOptions, 'workflowActions'> {
   backend?: DeepPartial<BackendOptions>;
   persistStates?: IPersistState[];
   submitStates?: Array<Omit<IPersistState, 'persistence'>>;
-  additionalContext?: AnyRecord;
+  additionalContext?: TContext;
}

sdks/workflow-browser-sdk/src/lib/workflow-browser-sdk.ts (2)

34-34: Consider simplifying the type definition.

The property type definition can be simplified as the | undefined is redundant when using the optional modifier ?.

-  #__additionalContext?: AnyRecord | undefined;
+  #__additionalContext?: AnyRecord;

---

34-34: Consider documenting the additionalContext contract.

The introduction of additionalContext adds flexibility but also introduces potential complexity. Consider:

1. Documenting the expected shape and usage of the additional context.
2. Adding runtime validation for critical context properties.
3. Providing examples in the SDK documentation.

This will help maintain consistency across different implementations and make the feature more maintainable.

Also applies to: 221-232

packages/workflow-core/src/lib/plugins/external-plugin/api-plugin.ts (1)

Line range hint 44-79: Document the additionalContext feature

Consider adding documentation to describe:

1. The purpose and intended use cases of additionalContext
2. The context merging behavior and precedence rules
3. Best practices for plugin authors regarding context usage

This will help plugin authors understand how to safely use this feature without introducing bugs or security issues.

packages/workflow-core/CHANGELOG.md (1)

3-7: Enhance the changelog entry with more details

The current changelog entry could be more helpful to users by including:

• A description of what additionalContext is and its purpose
• Example usage or code snippets
• Any migration steps if needed
• Impact on existing implementations

Consider expanding the entry like this:

 ## 0.6.65

 ### Patch Changes

-Added additionalContext
+- Added `additionalContext` parameter to enhance contextual data handling
+  - Purpose: Allows passing additional context data through workflow components
+  - Usage: `someWorkflowComponent({ additionalContext: { key: 'value' } })`
+  - Note: This is a backward-compatible change and existing implementations will continue to work

sdks/workflow-browser-sdk/CHANGELOG.md (1)

3-10: Enhance the changelog entry with more details.

The changelog entry could be more descriptive to help users understand the changes better. Consider following the conventional changelog format more strictly.

Apply this diff to improve the changelog entry:

 ## 0.6.65
 
 ### Patch Changes
 
-- Added additionalContext
+- feat: Added `additionalContext` parameter to enhance contextual data handling
+  - Allows passing additional context to workflow components
+  - Improves flexibility in data management
+  - See documentation for usage examples
 - Updated dependencies
   - @ballerine/workflow-core@0.6.65

Configuration used: CodeRabbit UI
Review profile: CHILL

#!/bin/bash
# Description: Check how the token is being used and transmitted

# Check for token references in URLs
rg -l "token=" 

# Check for security-related comments or documentation
rg -i "security|token|auth" "*.md"

# Look for cookie or header-based auth patterns
ast-grep --pattern 'cookie' 

#!/bin/bash
# Check the token usage in the collection flow and related files
rg -A 5 -B 5 "token.*searchParams" apps/kyb-app/

# Check how MissingTokenErrorScreen is used
rg -A 5 "MissingTokenErrorScreen" apps/kyb-app/

# Look for token validation or processing
ast-grep --pattern 'searchParams.get("token")'

# Check the workflow controller for token handling
rg -A 10 "token" services/workflows-service/src/workflow/workflow.controller.external.ts

#!/bin/bash
# Check token validation and authentication flow
rg -A 10 "class WorkflowTokenService" services/workflows-service/src/auth/workflow-token/

# Look for token validation middleware or guards
rg -A 10 "validateToken|verifyToken" services/workflows-service/

# Check for token-related errors and handling
rg -A 5 "InvalidAccessTokenError|AccessTokenIsMissingError" apps/kyb-app/

#!/bin/bash
# Check if the workflow SDK expects this parameter
rg -A 5 "createWorkflow.*interface|type" --type typescript

- //@ts-nocheck
- definition: definition as any,
+ definition: definition,

#!/bin/bash
# Description: Find usages of PluginRunnerHandler to verify context handling
# Expected: Locations where the handler is instantiated and its run method is called

# Search for direct usage of the handler
ast-grep --pattern 'new PluginRunnerHandler()' 

# Search for places where the run method result is used
rg -l "pluginRunner.*run\(" 

#!/bin/bash
# Let's examine the usage context in useActionsHandlerLogic.ts and look for run method calls
rg -A 5 "pluginRunner.*run" apps/kyb-app/src/components/organisms/DynamicUI/StateManager/components/ActionsHandler/hooks/useActionsHandlerLogic/useActionsHandlerLogic.ts

# Also search for any await patterns since this might be an async operation
ast-grep --pattern 'await pluginRunner.run($_)'

# Let's also check the interface/type definition of the handler
ast-grep --pattern 'interface $_Handler {
  run($_): $_
}'

#!/bin/bash
# Let's try a broader search for the handler interface and its implementations
ast-grep --pattern 'interface ActionHandler {
  $$$
}'

# Search for the plugin runner handler class definition
ast-grep --pattern 'class PluginRunnerHandler {
  $$$
}'

# Look for any usage of the handler with more context
rg -B 3 -A 3 "PluginRunnerHandler"

#!/bin/bash
# Let's check how the handlers are used in the processing logic
rg -B 3 -A 10 "useActionsProcessingLogic" apps/kyb-app/src/components/organisms/DynamicUI/StateManager/components/ActionsHandler/hooks/useActionsHandlerLogic/hooks/useActionsProcessingLogic.ts

# Let's also check the ActionHandler interface definition
rg -B 2 -A 5 "interface ActionHandler" apps/kyb-app/src/components/organisms/DynamicUI/StateManager/components/ActionsHandler/action-handlers/action-handler.abstract.ts

# And check how the StateMachineAPI is handling context
ast-grep --pattern 'class StateMachineAPI {
  $$$
}'

#!/bin/bash
# Search for plugin implementations to verify compatibility
echo "Searching for plugin implementations..."
rg -l "class.*implements.*Plugin" || rg -l "export.*class.*Plugin"

# Search for plugin invocations to ensure consistent usage
echo -e "\nSearching for plugin invocations..."
rg "invokePlugin\(" -A 2

#!/bin/bash
# Check the implementation of plugins to verify if they can handle additional context
echo "Checking NodePlugin implementation..."
cat sdks/workflow-node-sdk/src/lib/plugins/node-plugin.ts

echo -e "\nChecking TransformerPlugin implementation..."
cat packages/workflow-core/src/lib/plugins/common-plugin/transformer-plugin.ts

echo -e "\nChecking plugin registration and handling in WorkflowRunner..."
cat packages/workflow-core/src/lib/workflow-runner.ts

+interface WorkflowAdditionalContext {
+  // Add expected properties here
+  [key: string]: unknown;
+}

 export interface Workflow {
   subscribe: (eventName: string, callback: (event: WorkflowEvent) => Promise<void>) => void;
-  sendEvent: (event: WorkflowEventWithoutState, additionalContext?: AnyRecord) => Promise<void>;
+  sendEvent: (event: WorkflowEventWithoutState, additionalContext?: WorkflowAdditionalContext) => Promise<void>;
   getSnapshot: () => Record<PropertyKey, any>;
-  invokePlugin: (pluginName: string, additionalContext?: AnyRecord) => Promise<void>;
+  invokePlugin: (pluginName: string, additionalContext?: WorkflowAdditionalContext) => Promise<void>;
   overrideContext: (context: any) => any;
 }

#!/bin/bash
# Search for implementations of sendEvent and invokePlugin
ast-grep --pattern 'class $_ implements Workflow {
  $$$
  sendEvent($$$) {
    $$$
  }
  $$$
}'

ast-grep --pattern 'class $_ implements Workflow {
  $$$
  invokePlugin($$$) {
    $$$
  }
  $$$
}'

#!/bin/bash
# Let's try a different approach to find implementations
# First, find all TypeScript files
rg -t typescript "implements\s+Workflow" -l | while read -r file; do
    echo "=== $file ==="
    # Show the class implementation with context
    rg "implements\s+Workflow" "$file" -A 20 -B 5
done

# Also search for direct implementations of these methods
rg "sendEvent.*additionalContext" -t typescript
rg "invokePlugin.*additionalContext" -t typescript

#!/bin/bash
# Search for implementations without file type flag
rg "implements\s+Workflow" | while read -r line; do
    echo "=== Implementation ==="
    echo "$line"
done

# Search for method implementations
echo -e "\n=== sendEvent implementations ==="
rg "sendEvent.*\(.*additionalContext.*\)"

echo -e "\n=== invokePlugin implementations ==="
rg "invokePlugin.*\(.*additionalContext.*\)"

#!/bin/bash
# Description: Verify the service method signatures in workflow-core package.

# Search for the service method definitions
ast-grep --pattern 'class $_ {
  $$$
  invokePlugin($_, additionalContext$_) {
    $$$
  }
  $$$
  sendEvent($_, additionalContext$_) {
    $$$
  }
  $$$
}'

#!/bin/bash
# Let's try a broader search for service methods using ripgrep
rg -A 5 "invokePlugin|sendEvent" --type ts

# Also search for class definitions containing these methods
ast-grep --pattern 'class $_ {
  $$$
  invokePlugin($_) {
    $$$
  }
  $$$
}'

ast-grep --pattern 'class $_ {
  $$$
  sendEvent($_) {
    $$$
  }
  $$$
}'

#!/bin/bash
# Let's check the workflow-core package for the service implementation
rg -A 5 "class WorkflowRunner" --type ts

# Also search for the createWorkflow function that creates the service
rg -A 5 "createWorkflow" --type ts

#!/bin/bash
# Let's look at the WorkflowRunner class implementation to verify the method signatures
rg -A 10 "async sendEvent|async invokePlugin" packages/workflow-core/src/lib/workflow-runner.ts

#!/bin/bash
# Description: Find header patterns to understand security implications

# Search for header definitions and usage
rg -B 5 "headers.*?{.*?}"

# Search for sensitive patterns in headers
rg -i "(auth|token|key|secret|credential).*header"

#!/bin/bash
# Description: Find all usages of _getPluginUrl to understand what context keys are typically used

# Search for context keys used in URL patterns
rg -A 5 "url.*?{.*?}" 

# Search for _getPluginUrl method calls
ast-grep --pattern 'this._getPluginUrl($context)'

#!/bin/bash
# Let's try a different approach to find _getPluginUrl usage and context patterns

# Search for _getPluginUrl method definition and its usage
rg "_getPluginUrl" -A 5 -B 5

# Search for context spread patterns near _getPluginUrl
rg "\.\.\.context.*_getPluginUrl" -A 5 -B 5

# Search for the class containing _getPluginUrl
ast-grep --pattern 'class $_ {
  $$$
  _getPluginUrl($_) {
    $$$
  }
  $$$
}'