@wise/dynamic-flow-types 2.7.0 → 2.9.0

package/build/next/feature/Action.d.ts

@@ -1,14 +1,70 @@
 import type { ActionType } from './ActionType';
 import type { HttpMethod } from '../misc/HttpMethod';
 import type { JsonElement } from '../JsonElement';
+/**
+* An action may be performed by the user when submitting a step. Actions can submit to an endpoint, progress the flow, or exit the flow.
+* An action typically defines its URL and HTTP method to submit step data, and can optionally indicate that on success
+* this action will end the flow.
+* An endpoint can respond to a submitting action with an error status code and the standard error response format in order to display errors to the user.
+* ### Behaviour
+* #### Non-Exiting Actions
+* If an action does not specify the `exit` property as true, it is expected that the action will submit the step payload.
+* For example, the following action is a non-exiting action.
+* ```kt
+* action {
+*     url = "/submitForm"
+*     method = HttpMethod.POST
+* }
+* ```
+* #### Exiting Actions
+* If an action specifies `exit` as `true`, it is expected that this action should terminate the flow. For exiting actions,
+* the `url` property is optional.
+* #### Submitting Exiting Actions
+* If the `url` property is specified, the step payload will be submitted. On a successful response, the `result` property of the action (if provided)
+* will be merged with the response to the submission, and that combined result will be used as the result of the flow, which will terminate. In case
+* of any conflicts in the merge, the value of the result property of the action takes precedence.
+* #### Non-Submitting Exiting Actions
+* If the `url` property is not specified, when the action is taken the flow will be terminated and the value of the result
+* property will be used as the result of the flow.
+* ##### Example
+* Given the following action:
+* ```kt
+* action {
+*     exit = true
+*     result = encodeToJsonElement(mapOf(
+*         "someKey" to "someValue"
+*     ))
+* }
+* ```
+* When this action is taken, the flow will be completed and the result of the flow will be:
+* ```json
+* {
+*   "someKey": "someValue"
+* }
+* ```
+* #### Actions Which Sometimes Exit
+* In some cases, the provider of the step will not know if a submitting action will exit. For example, depending on the data entered by the user,
+* the flow may be complete, or we may need to ask them some follow-up questions. In these cases the `exit` property shouldn’t be specified. Instead,
+* the response to the submission should include an `X-DF-Response-Type: exit` header. When the client receives this header
+* in the response, it will continue in the same way as it would for a submitting exiting action. See [com.wise.dynamicflow.responses.FlowResponse].
+* #### Summary
+* This tree summarises the possible paths an action can lead to:
+* - If `exit` is `true`:
+*   - If `url` is `null`:
+*     - Exit flow with value of `result`
+*   - If `url` is non-null:
+*     - Submit to `url`
+*     - Merge value of `result` into response body
+*     - Exit flow with the merged result
+* - If `exit` is `false`:
+*   - Submit to `url`
+*   - If response has header `X-DF-Response-Type: "exit"`:
+*     - Merge value of `result` into response body
+*     - Exit flow with the merged result
+*   - If response does not have header `X-DF-Response-Type: "exit"`:
+*     - The response is handles as normal
+*/
 export type Action = {
-    id?: string;
-    url?: string;
-    method?: HttpMethod;
-    exit?: boolean;
-    result?: JsonElement;
-    data?: JsonElement;
-    timeout?: number;
     /**
     * @deprecated Please use Button.title instead
     */
@@ -22,14 +78,46 @@ export type Action = {
     */
     disabled?: boolean;
     /**
+    * A unique id which can be used to refer to the action.
     * @deprecated Please use 'id' instead
     */
     $id?: string;
     /**
+    * A reference to an action in the actions array.
     * @deprecated Action references are deprecated.
     */
     $ref?: string;
     /**
+    * A unique id which can be used for analytics purposes.
+    */
+    id?: string;
+    /**
+    * The URL to use for the submission.
+    */
+    url?: string;
+    /**
+    * The HTTP method to use for the async submission. Defaults to POST.
+    */
+    method?: HttpMethod;
+    /**
+    * See 'Exiting Actions'.
+    */
+    exit?: boolean;
+    /**
+    * See 'Exiting Actions'.
+    */
+    result?: JsonElement;
+    /**
+    * An object to be merged with the step data before submission.
+    */
+    data?: JsonElement;
+    /**
+    * Suggested 'timeout' duration, in seconds, for the network request resulting from this action. Typically used when the endpoint is expected
+    * to take a long time to respond.
+    */
+    timeout?: number;
+    /**
+    * Indicates that the action should not trigger client-side validation.
     * @experimental This feature may be changed in the future without notice.
     */
     skipValidation?: boolean;

package/build/next/feature/External.d.ts

@@ -1,3 +1,38 @@
+/**
+* External specifies a URL to be opened automatically when a step loads. Url-opening behaviour depends on the platform.
+* General guidance is as follows:
+* Web:
+* - Open a URL in a new browser tab.
+* Mobile:
+* - Open a URL in the default browser.
+* - Or open another app via a universal link.
+* External is typically used alongside [Polling].
+* ### Example
+* ```kt
+* Step.build {
+*     id = "external example"
+*     title = ""
+*     external {
+*         url = "https://foo.bar/external-request?id=12345"
+*     }
+*     layout {
+*         heading {
+*             text = "Your bank is opening in another window"
+*         }
+*         paragraph {
+*             text = "Please follow their instructions."
+*         }
+*         markdown {
+*             // Note that the "Reopen window" button/link is just a normal Markdown link that happens to specify the same URL as External.
+*             content = "[Reopen window](https://foo.bar/external-request?id=12345)"
+*         }
+*     }
+* }
+* ```
+*/
 export type External = {
+    /**
+    * The URL to open.
+    */
     url: string;
 };

package/build/next/feature/Help.d.ts

@@ -1,3 +1,9 @@
+/**
+* Help provides additional information to users, such as how to provide some data.
+*/
 export type Help = {
+    /**
+    * The markdown-formatted string to use as the content.
+    */
     markdown: string;
 };

package/build/next/feature/LinkHandler.d.ts

@@ -1,5 +1,59 @@
 import type { Action } from './Action';
+/**
+* A pattern which is matched against any incoming universal links, with an action to trigger when the pattern is matched.
+* Link handling is typically used alongside [External].
+* ### Action Data
+* When the action is performed, the payload will contain all the data usually submitted with an action. Additionally,
+* the data will be merged with an object containing the following structure:
+* ```json
+* {
+*     "url": "https://wise.com/some-url"
+* }
+* ```
+* Where "https://wise.com/some-url" is the full URL that was matched against the pattern.
+* ### Example
+* Given the step below, the client will listen for any deep or universal links that are used to open the app.
+* ```kt
+* Step.build {
+*     layout { }
+*     linkHandlers = listOf(
+*         LinkHandler(
+*             regexPattern = """https:\/\/wise.com\/success-callback.""",
+*             action = Action.build {
+*                 url = "/handle-success-callback"
+*                 data = encodeToJsonElement(mapOf("some-additional-data" to true))
+*             }
+*         ),
+*         LinkHandler(
+*             regexPattern = """https:\/\/wise\.com\/failure-callback.*""",
+*             action = Action.build {
+*                 url = "/handle-failure-callback"
+*             }
+*         )
+*     )
+* }
+* ```
+* If the user is on this step and then opens a universal or deep link, it'll be matched against the patterns
+* in the array, and any matching action will be executed.
+* For example, if the user opens the app with the universal link "https://wise.com/success-callback?token=1234",
+* this will be matched against the first pattern in the array. The corresponding action will be executed, and
+* the payload will also contain the url that was matched - for example in this case the following data
+* would be submitted to "/handle-success-callback":
+* ```json
+* {
+*     "some-additional-data": true,
+*     "url": "https://wise.com/success-callback?token=1234"
+* }
+* ```
+* If a link is opened which doesn't match any of the patterns then no action is taken.
+*/
 export type LinkHandler = {
+    /**
+    * A regex pattern to be matched against any incoming universal links.
+    */
     regexPattern: string;
+    /**
+    * An action to be triggered when the regex pattern is matched.
+    */
     action: Action;
 };

package/build/next/feature/Navigation.d.ts

@@ -1,11 +1,21 @@
 import type { NavigationBackBehaviour } from './NavigationBackBehaviour';
+import type { NavigationStackBehavior } from './NavigationStackBehavior';
 /**
+* Allows configuration of how navigating between steps should happen.
+* For example, it can be used to control what happens when the user navigates back from a step.
 * @experimental This feature may be changed in the future without notice.
 */
 export type Navigation = {
-    back?: NavigationBackBehaviour;
     /**
     * @deprecated Please use 'back' instead
     */
     backButton?: NavigationBackBehaviour;
+    /**
+    * Configure custom back behaviour which overrides any native back behaviour of the client.
+    */
+    back?: NavigationBackBehaviour;
+    /**
+    * Configure the behaviour of the navigation stack when this step is presented.
+    */
+    stackBehavior?: NavigationStackBehavior;
 };

package/build/next/feature/NavigationBackBehaviour.d.ts

@@ -1,8 +1,16 @@
 import type { Action } from './Action';
 /**
+* Describes how back navigation should be handled.
 * @experimental This feature may be changed in the future without notice.
 */
 export type NavigationBackBehaviour = {
+    /**
+    * A title describing the back action.
+    */
     title?: string;
+    /**
+    * The [com.wise.dynamicflow.feature.Action] triggered when the user navigates back.
+    * Note that this action will not validate the model against the schema before submitting.
+    */
     action: Action;
 };

package/build/next/feature/NavigationStackBehavior.d.ts

@@ -0,0 +1,5 @@
+/**
+* Describes the behaviour of the navigation stack when the step is presented.
+* @experimental This feature may be changed in the future without notice.
+*/
+export type NavigationStackBehavior = 'default' | 'remove-previous' | 'remove-all' | 'replace-current';

package/build/next/feature/PersistAsync.d.ts

@@ -1,9 +1,82 @@
 import type { Schema } from '../schema/Schema';
 import type { HttpMethod } from '../misc/HttpMethod';
+/**
+* Persist Async allows you to submit part of a step asynchronously to an endpoint, then submit an identifier from that asynchronous submission
+* as part of the main step submission. This can be useful in cases where the content of a field is very large (for example file upload),
+* or for if you need to tokenize part of the form for security reasons (e.g. submitting card numbers to a PCI-compliant server).
+* This functionality is specified using the `persistAsync` property of a [com.wise.dynamicflow.schema.Schema].
+* Note that the schema on which the `persistAsync` property is set should reflect the value that is
+* submitted (i.e. the token/identifier), while the [schema] property defines
+* the schema that is shown to the user and submitted to the persist async endpoint.
+* ### Example
+* When the value of the field changes, a request is sent to the URL defined in the `persistAsync` object, where the request body is
+* a JSON object containing the value of the field under a property matching the value of `persistAsync.param`.
+* For example, if the schema was defined as:
+* ```kt
+* Step.build {
+*     layout { }
+*     schemas {
+*         string {
+*             persistAsync  {
+*                 url = "/persistCard"
+*                 param = "number"
+*                 idProperty = "token"
+*                 schema = StringSchema.build {
+*                     title = "Card Number"
+*                 }
+*             }
+*         }
+*     }
+* }
+* ```
+* Then a text input titled "Card Number" would be rendered in the form to represent this schema. When the user enters a card number
+* of "1234567890", a `POST` request would be made to the `/persistCard` endpoint with the following body:
+* ```json
+* {
+*   "number": "1234567890"
+* }
+* ```
+* On success, the response body should be a JSON object which contains an identifier that should be used in the main submission
+* under the property specified in `persistAsync.idProperty` - for example:
+* ```json
+* {
+*   "token": "ce0a93b2-f11d-49a4-ab02-705bb66f5b39"
+* }
+* ```
+* When the user submits the form, the submission will contain this identifier as the value of the schema.
+* ### Error Handling
+* In the case of an error, the standard [StepError] response can be used.
+* In the card example above, the server could respond as follows with a non-2xx status code to show an error
+* on the card number field:
+* ```json
+* {
+*   "validation": {
+*     "number": "This card number is invalid"
+*   }
+* }
+* ```
+* If a persist async call fails, the client should re-attempt it on the next form submission. A failure should prevent
+* submission and display an error to the user.
+*/
 export type PersistAsync = {
+    /**
+    * The name of the property under which the value of the schema will be sent in the request body.
+    */
     param: string;
+    /**
+    * The name of the property under which the value used in the main submission can be found in the response body.
+    */
     idProperty: string;
+    /**
+    * The schema which will be shown to the user, and whose value will be sent in the Persist Async submission.
+    */
     schema: Schema;
+    /**
+    * The URL used for the async submission.
+    */
     url: string;
+    /**
+    * The HTTP method used for the async submission. Defaults to POST.
+    */
     method: HttpMethod;
 };

package/build/next/feature/Polling.d.ts

@@ -1,7 +1,50 @@
 import type { PollingOnError } from './PollingOnError';
+/**
+* Polling instructs the client to periodically make an HTTP GET request to the specified URL and eventually trigger an action.
+* Polling is typically used alongside [External]. For example, a step may first open an external URL and then poll for a server state change.
+* The client may continue to another step or end the flow.
+* ### Example
+* Given the step below, the client will start making requests to the specified URL every 5 seconds.
+* If the response is a json object with an `action` property, for instance `{ action: { url: "/next-step", "data": "all-ok" } }`, then the action is "executed". This usually loads the next step, or exits the flow.
+* If the response body is not a json object with an `action` property, but the status code is 2xx, then the client continues to make requests until an `action` is found or `maxAttempts` is reached.
+* ```kt
+* Step.build {
+*     layout { }
+*     polling {
+*         url = "https://bar.foo/status?id=12345"
+*         interval = 5
+*         maxAttempts = 100
+*         onError {
+*             action {
+*                 exit = true
+*                 result = encodeToJsonElement(mapOf("exit-action-data" to "EXIT!!!"))
+*             }
+*         }
+*     }
+* }
+* ```
+* #### Error handling
+* Given the above step, the action in the `onError` object is triggered if:
+* - the response status code is a failure (>=400).
+* - the number of attempts exceeds the specified `maxAttempts`
+*/
 export type Polling = {
+    /**
+    * The URL to open.
+    */
     url: string;
+    /**
+    * The time interval between requests, in seconds.
+    */
     interval: number;
+    /**
+    * The maximum number of requests that may be attempted, before triggering the [onError] action.
+    * @see onError
+    */
     maxAttempts: number;
+    /**
+    * An object with one action property to be triggered when polling fails.
+    * @see maxAttempts
+    */
     onError: PollingOnError;
 };

package/build/next/feature/PollingOnError.d.ts

@@ -1,4 +1,7 @@
 import type { Action } from './Action';
 export type PollingOnError = {
+    /**
+    * The [com.wise.dynamicflow.feature.Action] to be triggered when polling fails.
+    */
     action: Action;
 };

package/build/next/feature/StepError.d.ts

@@ -1,5 +1,42 @@
 import type { JsonElement } from '../JsonElement';
+/**
+* Errors which should be displayed to the user when the step loads.
+*/
 export type StepError = {
+    /**
+    * A general error message, not related to any particular schema.
+    */
     error?: string;
+    /**
+    * Error messages related to specific fields. The structure of this value must match the structure of the data
+    * to be validated.
+    * For example, given the following model:
+    * ```
+    * {
+    *   "name": "A Person",
+    *   "bankDetails": {
+    *     "accountNumber": "31510604",
+    *     "sortCode": "100000"
+    *   }
+    * }
+    * ```
+    * A validation message for the "sortCode" field should be provided as follows:
+    * ```
+    * {
+    *   "bankDetails": {
+    *     "sortCode": "Please enter a valid sort code"
+    *   }
+    * }
+    * ```
+    * Multiple validation messages can be returned at once, for example:
+    * ```
+    * {
+    *   "name": "Please enter a full name",
+    *   "bankDetails": {
+    *     "sortCode": "Please enter a valid sort code"
+    *   }
+    * }
+    * ```
+    */
     validation?: JsonElement;
 };

package/build/next/feature/Summary.d.ts

@@ -1,3 +1,7 @@
 import type { SummaryProvider } from './SummaryProvider';
 import type { SummarySummariser } from './SummarySummariser';
+/**
+* Summary specifies a configuration to produce user-facing copy for child schemas of [com.wise.dynamicflow.schema.ArraySchema.List].
+* Default values may be specified to be used if values are not provided on child schemas.
+*/
 export type Summary = SummaryProvider | SummarySummariser;

package/build/next/feature/SummaryProvider.d.ts

@@ -1,6 +1,21 @@
+/**
+* A schema which provides values for the summary.
+*/
 export type SummaryProvider = {
+    /**
+    * If true, the value of this schema can be used as a summary title.
+    */
     providesTitle?: boolean;
+    /**
+    * If true, the value of this schema can be used as a summary description.
+    */
     providesDescription?: boolean;
+    /**
+    * If true, the icon of this schema can be used as a summary icon.
+    */
     providesIcon?: boolean;
+    /**
+    * If true, the image of this schema can be used as a summary image.
+    */
     providesImage?: boolean;
 };

package/build/next/feature/SummarySummariser.d.ts

@@ -1,12 +1,40 @@
 import type { Icon } from '../misc/Icon';
 import type { ImageLayout } from '../layout/ImageLayout';
+/**
+* A schema which summarises its child schemas.
+* Default values can be specified for the summary if values are not provided by its child schemas.
+*/
 export type SummarySummariser = {
+    /**
+    * A title to be used for the summary if a title is not provided by a child schema.
+    */
     defaultTitle?: string;
+    /**
+    * A description to be used for the summary if a description is not provided by a child schema.
+    */
     defaultDescription?: string;
+    /**
+    * An icon to be used for the summary if an icon is not provided by a child schema.
+    */
     defaultIcon?: Icon;
+    /**
+    * An image to be used for the summary if an image is not provided by a child schema.
+    */
     defaultImage?: ImageLayout;
+    /**
+    * If true, the value of this schema can be used as a summary title.
+    */
     providesTitle?: boolean;
+    /**
+    * If true, the value of this schema can be used as a summary description.
+    */
     providesDescription?: boolean;
+    /**
+    * If true, the icon of this schema can be used as a summary icon.
+    */
     providesIcon?: boolean;
+    /**
+    * If true, the image of this schema can be used as a summary image.
+    */
     providesImage?: boolean;
 };

package/build/next/feature/UploadSource.d.ts

@@ -0,0 +1,4 @@
+/**
+* The possible sources for a file
+*/
+export type UploadSource = 'camera' | 'file';

package/build/next/feature/ValidateAsync.d.ts

@@ -1,6 +1,62 @@
 import type { HttpMethod } from '../misc/HttpMethod';
+/**
+* Validation Async allows you to validate the value of a field on change by calling an endpoint.
+* This allows for more complex validation than is possible using local validation rules.
+* When the value of a schema with a [ValidateAsync] configuration changes, first any local validation
+* is run. If this local validation passes, a request is sent to the URL defined at [url],
+* where the request body is a JSON object containing the value of the field under a property matching
+* the value of [param].
+* On success, the server should respond with a `2xx` status code and either an empty body, in which
+* case no feedback is given to the user, or a JSON body with a `message` property, which will be shown
+* to the user. On failure, the server should respond with a `422` status code and a JSON body with
+* a `message` property which will be shown to the user.
+* **Note that "failed" validation does not prevent the client from submitting the step in the case of async validation.**
+* Also, in the case where the validation-async network call fails or returns an unexpected response,
+* the client ignores the problem and allows the user to submit.
+* For these reasons, any validation which is critical should also be performed by the server on submission.
+* ### Example
+* Given a schema defined as:
+* ```kt
+* string {
+*     title = "IBAN"
+*     validationAsync = ValidateAsync(
+*         param = "iban",
+*         method = HttpMethod.POST,
+*         url = "/validate-iban"
+*     )
+* }
+* ```
+* When the user enters a value, e.g. "NL30ABNA7619995846", a `POST` request would be made to the `/validate-iban` endpoint with the following body:
+* ```json
+* {
+*   "iban": "NL30ABNA7619995846"
+* }
+* ```
+* On success, the server responds with a `200` status code and the response body should either be empty, in which case no feedback will be given to the user, or a JSON body with the following structure:
+* ```json
+* {
+*   "message": "Valid IBAN"
+* }
+* ```
+* In which case the message will be displayed to the user to let them know the value they have entered is valid.
+* On failure, the server should respond with a `422` status code and a json body giving a message to display to the user:
+* ```json
+* {
+*   "message": "This IBAN is invalid. Please check it again."
+* }
+* ```
+*/
 export type ValidateAsync = {
+    /**
+    * The name of the property under which the value of the schema will be sent in the request body.
+    */
     param: string;
+    /**
+    * The HTTP method to use for the request. Only methods which allow a request body are supported.
+    */
     method: HttpMethod;
+    /**
+    * The URL to use for the request.
+    */
     url: string;
 };

package/build/next/layout/AlertLayout.d.ts

@@ -1,9 +1,29 @@
 import type { Context } from '../misc/Context';
 import type { Size } from '../misc/Size';
+/**
+* Show an attention-grabbing message.
+* Alerts can be used to communicate important messages to the user, drawing more attention than a standard paragraph or info layout.
+*/
 export type AlertLayout = {
+    /**
+    * It must be `alert`.
+    */
     type: 'alert';
+    /**
+    * The content of the alert as string. The following subset of markdown features are supported:
+    * Emphasis, strong emphasis.
+    */
     markdown: string;
+    /**
+    * The semantics of the alert. Defaults to `neutral`.
+    */
     context?: Context;
+    /**
+    * Specify a particular control to use to represent the layout. If the control is unknown, it will be ignored.
+    */
     control?: string;
+    /**
+    * The vertical margin to apply above this component. Defaults to `md`.
+    */
     margin?: Size;
 };

package/build/next/layout/BoxLayout.d.ts

@@ -1,10 +1,31 @@
 import type { Layout } from './Layout';
 import type { Size } from '../misc/Size';
+/**
+* A container for a group of components with an optional border.
+*/
 export type BoxLayout = {
+    /**
+    * It must be `box`.
+    */
     type: 'box';
+    /**
+    * The contained components.
+    */
     components: Layout[];
+    /**
+    * The width of the box. Defaults to `xl`.
+    */
     width?: Size;
+    /**
+    * If true, a border is displayed around the box. Defaults to false.
+    */
     border?: boolean;
+    /**
+    * Specify a particular control to use to represent the layout. If the control is unknown, it will be ignored.
+    */
     control?: string;
+    /**
+    * The vertical margin to apply above this component. Defaults to `md`.
+    */
     margin?: Size;
 };