feat: support formsort env in secure embeds

packages/react-embed/README.md

@@ -48,12 +48,14 @@ import { SecureEmbedFlow } from '@formsort/react-embed';
   initialAnswers={{
     firstName: 'Olivia',
   }}
+  formsortEnv="staging"
 />;
 ```
 
-`responderUuid` and `initialAnswers` are optional. `SecureEmbedFlow` does not
-accept `queryParams` or `formsortEnv`. It has the same configuration and event
-props as `EmbedFlow`.
+`responderUuid`, `initialAnswers`, and `formsortEnv` are optional.
+`SecureEmbedFlow` does not accept `queryParams`. It sends `responderUuid` and
+`initialAnswers` in the POST body. It adds `formsortEnv` to the navigation URL.
+It has the same configuration and event props as `EmbedFlow`.
 
 ### Events
 
@@ -82,12 +84,13 @@ You can add event listeners to flows like `Flowloaded`, `redirect` etc. See [all
 
 `SecureEmbedFlow` supports `clientLabel`, `flowLabel`, `variantLabel`,
 `embedConfig`, and all event props from `EmbedFlow`. It also supports these
-secure POST props:
+secure embed props:
 
 | Prop name      | Description                           | Required | Example values                         |
 | -------------- | ------------------------------------- | -------- | -------------------------------------- |
 | responderUuid  | responder UUID sent in the POST body  | no       | `e4923baa-dc2d-4555-813c-a166952292fa` |
 | initialAnswers | initial answers sent in the POST body | no       | `{ firstName: 'Olivia' }`              |
+| formsortEnv    | integrations environment              | no       | `staging`                              |
 
 ### Loading a specific variant revision
 

packages/react-embed/src/__tests__/EmbedFlow.test.tsx

@@ -155,6 +155,7 @@ describe('EmbedFlow component', () => {
         clientLabel="test-client"
         responderUuid={responderUuid}
         initialAnswers={initialAnswers}
+        formsortEnv="staging"
       />
     );
 
@@ -168,7 +169,8 @@ describe('EmbedFlow component', () => {
       'test-flow',
       undefined,
       responderUuid,
-      initialAnswers
+      initialAnswers,
+      'staging'
     );
   });
 });

packages/react-embed/src/index.tsx

@@ -39,7 +39,7 @@ export type EmbedFlowProps = ILoadProps & IReactEmbedEventMap;
 
 export type SecureEmbedFlowProps = Pick<
   ILoadProps,
-  'clientLabel' | 'flowLabel' | 'variantLabel' | 'embedConfig'
+  'clientLabel' | 'flowLabel' | 'variantLabel' | 'embedConfig' | 'formsortEnv'
 > & {
   responderUuid?: string;
   initialAnswers?: FormsortInitialAnswers;
@@ -122,6 +122,7 @@ const onSecureMount = (
     embedConfig,
     responderUuid,
     initialAnswers,
+    formsortEnv,
     ...eventListeners
   } = props;
   const embed = FormsortSecureWebEmbed(containerElement, embedConfig);
@@ -131,7 +132,8 @@ const onSecureMount = (
     flowLabel,
     variantLabel,
     responderUuid,
-    initialAnswers
+    initialAnswers,
+    formsortEnv
   );
   return embed;
 };

packages/web-embed-api/README.md

@@ -38,10 +38,11 @@ const embed = FormsortSecureWebEmbed(document.body);
 
 embed.loadFlow(
   'formsort',
-  'onboarding'
-  // 'main', // [optional] variantLabel
-  // 'e4923baa-dc2d-4555-813c-a166952292fa', // [optional] responderUuid
-  // { firstName: 'Olivia' } // [optional] initialAnswers
+  'onboarding',
+  'main',
+  'e4923baa-dc2d-4555-813c-a166952292fa',
+  { firstName: 'Olivia' },
+  'staging'
 );
 ```
 
@@ -54,16 +55,17 @@ objects. The secure embed uses the same configuration, methods, and events as
 Initializes a secure Formsort iframe. It has the same configuration, methods,
 and events as `FormsortWebEmbed`.
 
-Its `loadFlow` method accepts optional `responderUuid` and `initialAnswers`
-values. It does not accept query parameters:
+Its `loadFlow` method accepts optional `responderUuid`, `initialAnswers`, and
+`formsortEnv` values. It does not accept general query parameters.
 
 ```ts
 loadFlow(
   clientLabel: string,
   flowLabel: string,
   variantLabel?: string,
   responderUuid?: string,
-  initialAnswers?: FormsortInitialAnswers
+  initialAnswers?: FormsortInitialAnswers,
+  formsortEnv?: string
 ) => void;
 ```
 

packages/web-embed-api/src/index.test.ts

@@ -931,4 +931,29 @@ describe('FormsortSecureWebEmbed', () => {
     expect(submitSpy).toHaveBeenCalledTimes(1);
     submitSpy.mockRestore();
   });
+
+  test('adds an encoded formsort environment to the POST URL', () => {
+    const submitSpy = jest
+      .spyOn(HTMLFormElement.prototype, 'submit')
+      .mockImplementation(jest.fn());
+    const embed = FormsortSecureWebEmbed(document.body);
+
+    embed.loadFlow(
+      clientLabel,
+      flowLabel,
+      undefined,
+      undefined,
+      undefined,
+      'test & preview'
+    );
+
+    const form = document.body.querySelector('form')!;
+    expect(form.action).toBe(
+      `https://testclient.formsort.app/flow/${flowLabel}` +
+        '?formsortEnv=test%20%26%20preview'
+    );
+    expect(form.querySelectorAll('input, select')).toHaveLength(0);
+    expect(submitSpy).toHaveBeenCalledTimes(1);
+    submitSpy.mockRestore();
+  });
 });

packages/web-embed-api/src/index.ts

@@ -35,7 +35,8 @@ interface IFormsortSecureWebEmbed extends IFormsortEmbedControls {
     flowLabel: string,
     variantLabel?: string,
     responderUuid?: string,
-    initialAnswers?: FormsortInitialAnswers
+    initialAnswers?: FormsortInitialAnswers,
+    formsortEnv?: string
   ) => void;
 }
 
@@ -217,7 +218,8 @@ const createFormsortWebEmbed = (
     flowLabel: string,
     variantLabel?: string,
     queryParamsOrResponderUuid?: Array<[string, string]> | string,
-    initialAnswers?: FormsortInitialAnswers
+    initialAnswers?: FormsortInitialAnswers,
+    formsortEnv?: string
   ) => {
     let urlBase: string;
     if (config.origin) {
@@ -255,6 +257,10 @@ const createFormsortWebEmbed = (
       return;
     }
 
+    if (formsortEnv) {
+      url += `?formsortEnv=${encodeURIComponent(formsortEnv)}`;
+    }
+
     formEl?.remove();
     const nextFormEl = document.createElement('form');
     formEl = nextFormEl;