api_widgets.go

/*
MX Platform API

The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions.  Just getting started? See our [use case guides](/use-cases/). 

API version: 20111101
*/

// Code generated by OpenAPI Generator (https://openapi-generator.tech); DO NOT EDIT.

package mxplatformgo

import (
	"bytes"
	"context"
	"io"
	"net/http"
	"net/url"
	"strings"
)


// WidgetsAPIService WidgetsAPI service
type WidgetsAPIService service

type ApiRequestConnectWidgetURLRequest struct {
	ctx context.Context
	ApiService *WidgetsAPIService
	userGuid string
	connectWidgetRequestBody *ConnectWidgetRequestBody
}

// Optional config options for WebView (is_mobile_webview, current_institution_code, current_member_guid, update_credentials)
func (r ApiRequestConnectWidgetURLRequest) ConnectWidgetRequestBody(connectWidgetRequestBody ConnectWidgetRequestBody) ApiRequestConnectWidgetURLRequest {
	r.connectWidgetRequestBody = &connectWidgetRequestBody
	return r
}

func (r ApiRequestConnectWidgetURLRequest) Execute() (*ConnectWidgetResponseBody, *http.Response, error) {
	return r.ApiService.RequestConnectWidgetURLExecute(r)
}

/*
RequestConnectWidgetURL (Deprecated) Request connect widget URL

This endpoint will return a URL for an embeddable version of MX Connect.

 @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
 @param userGuid The unique identifier for a `user`, beginning with the prefix `USR-`.
 @return ApiRequestConnectWidgetURLRequest

Deprecated
*/
func (a *WidgetsAPIService) RequestConnectWidgetURL(ctx context.Context, userGuid string) ApiRequestConnectWidgetURLRequest {
	return ApiRequestConnectWidgetURLRequest{
		ApiService: a,
		ctx: ctx,
		userGuid: userGuid,
	}
}

// Execute executes the request
//  @return ConnectWidgetResponseBody
// Deprecated
func (a *WidgetsAPIService) RequestConnectWidgetURLExecute(r ApiRequestConnectWidgetURLRequest) (*ConnectWidgetResponseBody, *http.Response, error) {
	var (
		localVarHTTPMethod   = http.MethodPost
		localVarPostBody     interface{}
		formFiles            []formFile
		localVarReturnValue  *ConnectWidgetResponseBody
	)

	localBasePath, err := a.client.cfg.ServerURLWithContext(r.ctx, "WidgetsAPIService.RequestConnectWidgetURL")
	if err != nil {
		return localVarReturnValue, nil, &GenericOpenAPIError{error: err.Error()}
	}

	localVarPath := localBasePath + "/users/{user_guid}/connect_widget_url"
	localVarPath = strings.Replace(localVarPath, "{"+"user_guid"+"}", url.PathEscape(parameterValueToString(r.userGuid, "userGuid")), -1)

	localVarHeaderParams := make(map[string]string)
	localVarQueryParams := url.Values{}
	localVarFormParams := url.Values{}
	if r.connectWidgetRequestBody == nil {
		return localVarReturnValue, nil, reportError("connectWidgetRequestBody is required and must be specified")
	}

	// to determine the Content-Type header
	localVarHTTPContentTypes := []string{"application/json"}

	// set Content-Type header
	localVarHTTPContentType := selectHeaderContentType(localVarHTTPContentTypes)
	if localVarHTTPContentType != "" {
		localVarHeaderParams["Content-Type"] = localVarHTTPContentType
	}

	// to determine the Accept header
	localVarHTTPHeaderAccepts := []string{"application/vnd.mx.api.v1+json"}

	// set Accept header
	localVarHTTPHeaderAccept := selectHeaderAccept(localVarHTTPHeaderAccepts)
	if localVarHTTPHeaderAccept != "" {
		localVarHeaderParams["Accept"] = localVarHTTPHeaderAccept
	}
	// body params
	localVarPostBody = r.connectWidgetRequestBody
	req, err := a.client.prepareRequest(r.ctx, localVarPath, localVarHTTPMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, formFiles)
	if err != nil {
		return localVarReturnValue, nil, err
	}

	localVarHTTPResponse, err := a.client.callAPI(req)
	if err != nil || localVarHTTPResponse == nil {
		return localVarReturnValue, localVarHTTPResponse, err
	}

	localVarBody, err := io.ReadAll(localVarHTTPResponse.Body)
	localVarHTTPResponse.Body.Close()
	localVarHTTPResponse.Body = io.NopCloser(bytes.NewBuffer(localVarBody))
	if err != nil {
		return localVarReturnValue, localVarHTTPResponse, err
	}

	if localVarHTTPResponse.StatusCode >= 300 {
		newErr := &GenericOpenAPIError{
			body:  localVarBody,
			error: localVarHTTPResponse.Status,
		}
		return localVarReturnValue, localVarHTTPResponse, newErr
	}

	err = a.client.decode(&localVarReturnValue, localVarBody, localVarHTTPResponse.Header.Get("Content-Type"))
	if err != nil {
		newErr := &GenericOpenAPIError{
			body:  localVarBody,
			error: err.Error(),
		}
		return localVarReturnValue, localVarHTTPResponse, newErr
	}

	return localVarReturnValue, localVarHTTPResponse, nil
}

type ApiRequestOAuthWindowURIRequest struct {
	ctx context.Context
	ApiService *WidgetsAPIService
	memberGuid string
	userGuid string
	clientRedirectUrl *string
	enableApp2app *string
	referralSource *string
	skipAggregation *bool
	uiMessageWebviewUrlScheme *string
}

// A URL that MX will redirect to at the end of OAuth with additional query parameters. Only available with `referral_source=APP`.
func (r ApiRequestOAuthWindowURIRequest) ClientRedirectUrl(clientRedirectUrl string) ApiRequestOAuthWindowURIRequest {
	r.clientRedirectUrl = &clientRedirectUrl
	return r
}

// This indicates whether OAuth app2app behavior is enabled for institutions that support it. Defaults to `true`. When set to `false`, any `oauth_window_uri` generated will **not** direct the end user to the institution's mobile application. This setting is not persistent. This setting currently only affects Chase institutions.
func (r ApiRequestOAuthWindowURIRequest) EnableApp2app(enableApp2app string) ApiRequestOAuthWindowURIRequest {
	r.enableApp2app = &enableApp2app
	return r
}

// Must be either `BROWSER` or `APP` depending on the implementation. Defaults to `BROWSER`.
func (r ApiRequestOAuthWindowURIRequest) ReferralSource(referralSource string) ApiRequestOAuthWindowURIRequest {
	r.referralSource = &referralSource
	return r
}

// Setting this parameter to `true` will prevent the member from automatically aggregating after being redirected from the authorization page.
func (r ApiRequestOAuthWindowURIRequest) SkipAggregation(skipAggregation bool) ApiRequestOAuthWindowURIRequest {
	r.skipAggregation = &skipAggregation
	return r
}

// A scheme for routing the user back to the application state they were previously in. Only available with `referral_source=APP`.
func (r ApiRequestOAuthWindowURIRequest) UiMessageWebviewUrlScheme(uiMessageWebviewUrlScheme string) ApiRequestOAuthWindowURIRequest {
	r.uiMessageWebviewUrlScheme = &uiMessageWebviewUrlScheme
	return r
}

func (r ApiRequestOAuthWindowURIRequest) Execute() (*OAuthWindowResponseBody, *http.Response, error) {
	return r.ApiService.RequestOAuthWindowURIExecute(r)
}

/*
RequestOAuthWindowURI Request oauth window uri

This endpoint will generate an `oauth_window_uri` for the specified `member`.

 @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
 @param memberGuid The unique id for a `member`.
 @param userGuid The unique identifier for a `user`, beginning with the prefix `USR-`.
 @return ApiRequestOAuthWindowURIRequest
*/
func (a *WidgetsAPIService) RequestOAuthWindowURI(ctx context.Context, memberGuid string, userGuid string) ApiRequestOAuthWindowURIRequest {
	return ApiRequestOAuthWindowURIRequest{
		ApiService: a,
		ctx: ctx,
		memberGuid: memberGuid,
		userGuid: userGuid,
	}
}

// Execute executes the request
//  @return OAuthWindowResponseBody
func (a *WidgetsAPIService) RequestOAuthWindowURIExecute(r ApiRequestOAuthWindowURIRequest) (*OAuthWindowResponseBody, *http.Response, error) {
	var (
		localVarHTTPMethod   = http.MethodGet
		localVarPostBody     interface{}
		formFiles            []formFile
		localVarReturnValue  *OAuthWindowResponseBody
	)

	localBasePath, err := a.client.cfg.ServerURLWithContext(r.ctx, "WidgetsAPIService.RequestOAuthWindowURI")
	if err != nil {
		return localVarReturnValue, nil, &GenericOpenAPIError{error: err.Error()}
	}

	localVarPath := localBasePath + "/users/{user_guid}/members/{member_guid}/oauth_window_uri"
	localVarPath = strings.Replace(localVarPath, "{"+"member_guid"+"}", url.PathEscape(parameterValueToString(r.memberGuid, "memberGuid")), -1)
	localVarPath = strings.Replace(localVarPath, "{"+"user_guid"+"}", url.PathEscape(parameterValueToString(r.userGuid, "userGuid")), -1)

	localVarHeaderParams := make(map[string]string)
	localVarQueryParams := url.Values{}
	localVarFormParams := url.Values{}

	if r.clientRedirectUrl != nil {
		parameterAddToHeaderOrQuery(localVarQueryParams, "client_redirect_url", r.clientRedirectUrl, "")
	}
	if r.enableApp2app != nil {
		parameterAddToHeaderOrQuery(localVarQueryParams, "enable_app2app", r.enableApp2app, "")
	}
	if r.referralSource != nil {
		parameterAddToHeaderOrQuery(localVarQueryParams, "referral_source", r.referralSource, "")
	}
	if r.skipAggregation != nil {
		parameterAddToHeaderOrQuery(localVarQueryParams, "skip_aggregation", r.skipAggregation, "")
	}
	if r.uiMessageWebviewUrlScheme != nil {
		parameterAddToHeaderOrQuery(localVarQueryParams, "ui_message_webview_url_scheme", r.uiMessageWebviewUrlScheme, "")
	}
	// to determine the Content-Type header
	localVarHTTPContentTypes := []string{}

	// set Content-Type header
	localVarHTTPContentType := selectHeaderContentType(localVarHTTPContentTypes)
	if localVarHTTPContentType != "" {
		localVarHeaderParams["Content-Type"] = localVarHTTPContentType
	}

	// to determine the Accept header
	localVarHTTPHeaderAccepts := []string{"application/vnd.mx.api.v1+json"}

	// set Accept header
	localVarHTTPHeaderAccept := selectHeaderAccept(localVarHTTPHeaderAccepts)
	if localVarHTTPHeaderAccept != "" {
		localVarHeaderParams["Accept"] = localVarHTTPHeaderAccept
	}
	req, err := a.client.prepareRequest(r.ctx, localVarPath, localVarHTTPMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, formFiles)
	if err != nil {
		return localVarReturnValue, nil, err
	}

	localVarHTTPResponse, err := a.client.callAPI(req)
	if err != nil || localVarHTTPResponse == nil {
		return localVarReturnValue, localVarHTTPResponse, err
	}

	localVarBody, err := io.ReadAll(localVarHTTPResponse.Body)
	localVarHTTPResponse.Body.Close()
	localVarHTTPResponse.Body = io.NopCloser(bytes.NewBuffer(localVarBody))
	if err != nil {
		return localVarReturnValue, localVarHTTPResponse, err
	}

	if localVarHTTPResponse.StatusCode >= 300 {
		newErr := &GenericOpenAPIError{
			body:  localVarBody,
			error: localVarHTTPResponse.Status,
		}
		return localVarReturnValue, localVarHTTPResponse, newErr
	}

	err = a.client.decode(&localVarReturnValue, localVarBody, localVarHTTPResponse.Header.Get("Content-Type"))
	if err != nil {
		newErr := &GenericOpenAPIError{
			body:  localVarBody,
			error: err.Error(),
		}
		return localVarReturnValue, localVarHTTPResponse, newErr
	}

	return localVarReturnValue, localVarHTTPResponse, nil
}

type ApiRequestWidgetURLRequest struct {
	ctx context.Context
	ApiService *WidgetsAPIService
	userGuid string
	widgetRequestBody *WidgetRequestBody
	acceptLanguage *string
	xCALLBACKPAYLOAD *string
}

// The widget url configuration options.
func (r ApiRequestWidgetURLRequest) WidgetRequestBody(widgetRequestBody WidgetRequestBody) ApiRequestWidgetURLRequest {
	r.widgetRequestBody = &widgetRequestBody
	return r
}

// The desired language of the widget.
func (r ApiRequestWidgetURLRequest) AcceptLanguage(acceptLanguage string) ApiRequestWidgetURLRequest {
	r.acceptLanguage = &acceptLanguage
	return r
}

// The base64 encoded string defined in this header will be returned in the [Member](/resources/webhooks/member/) and [Member Data Updated](/resources/webhooks/member#member-data-updated) webhooks. This allows you to trace user interactions and workflows initiated externally and internally in the MX Platform. Max 1024 characters.
func (r ApiRequestWidgetURLRequest) XCALLBACKPAYLOAD(xCALLBACKPAYLOAD string) ApiRequestWidgetURLRequest {
	r.xCALLBACKPAYLOAD = &xCALLBACKPAYLOAD
	return r
}

func (r ApiRequestWidgetURLRequest) Execute() (*WidgetResponseBody, *http.Response, error) {
	return r.ApiService.RequestWidgetURLExecute(r)
}

/*
RequestWidgetURL Request widget URL

Get an embeddable URL for integrating a widget into your website or app. The URL expires after ten minutes or upon first use, whichever occurs first. You'll need to obtain a new URL each time the page loads or reloads.

Include the `widget_type` in the request body to specify which widget you want to embed—the Connect Widget, a Personal Financial Management widget, or an Insights widget. Some request parameters are specific to certain widget types.

To embed the Connect Widget, set `widget_type` to `connect_widget`.

For a full list of available widget types, see [Widget Types](/api-reference/platform-api/reference/widgets#widget-types).


 @param ctx context.Context - for authentication, logging, cancellation, deadlines, tracing, etc. Passed from http.Request or context.Background().
 @param userGuid The unique identifier for a `user`, beginning with the prefix `USR-`.
 @return ApiRequestWidgetURLRequest
*/
func (a *WidgetsAPIService) RequestWidgetURL(ctx context.Context, userGuid string) ApiRequestWidgetURLRequest {
	return ApiRequestWidgetURLRequest{
		ApiService: a,
		ctx: ctx,
		userGuid: userGuid,
	}
}

// Execute executes the request
//  @return WidgetResponseBody
func (a *WidgetsAPIService) RequestWidgetURLExecute(r ApiRequestWidgetURLRequest) (*WidgetResponseBody, *http.Response, error) {
	var (
		localVarHTTPMethod   = http.MethodPost
		localVarPostBody     interface{}
		formFiles            []formFile
		localVarReturnValue  *WidgetResponseBody
	)

	localBasePath, err := a.client.cfg.ServerURLWithContext(r.ctx, "WidgetsAPIService.RequestWidgetURL")
	if err != nil {
		return localVarReturnValue, nil, &GenericOpenAPIError{error: err.Error()}
	}

	localVarPath := localBasePath + "/users/{user_guid}/widget_urls"
	localVarPath = strings.Replace(localVarPath, "{"+"user_guid"+"}", url.PathEscape(parameterValueToString(r.userGuid, "userGuid")), -1)

	localVarHeaderParams := make(map[string]string)
	localVarQueryParams := url.Values{}
	localVarFormParams := url.Values{}
	if r.widgetRequestBody == nil {
		return localVarReturnValue, nil, reportError("widgetRequestBody is required and must be specified")
	}

	// to determine the Content-Type header
	localVarHTTPContentTypes := []string{"application/json"}

	// set Content-Type header
	localVarHTTPContentType := selectHeaderContentType(localVarHTTPContentTypes)
	if localVarHTTPContentType != "" {
		localVarHeaderParams["Content-Type"] = localVarHTTPContentType
	}

	// to determine the Accept header
	localVarHTTPHeaderAccepts := []string{"application/vnd.mx.api.v1+json"}

	// set Accept header
	localVarHTTPHeaderAccept := selectHeaderAccept(localVarHTTPHeaderAccepts)
	if localVarHTTPHeaderAccept != "" {
		localVarHeaderParams["Accept"] = localVarHTTPHeaderAccept
	}
	if r.acceptLanguage != nil {
		parameterAddToHeaderOrQuery(localVarHeaderParams, "Accept-Language", r.acceptLanguage, "")
	}
	if r.xCALLBACKPAYLOAD != nil {
		parameterAddToHeaderOrQuery(localVarHeaderParams, "X-CALLBACK-PAYLOAD", r.xCALLBACKPAYLOAD, "")
	}
	// body params
	localVarPostBody = r.widgetRequestBody
	req, err := a.client.prepareRequest(r.ctx, localVarPath, localVarHTTPMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, formFiles)
	if err != nil {
		return localVarReturnValue, nil, err
	}

	localVarHTTPResponse, err := a.client.callAPI(req)
	if err != nil || localVarHTTPResponse == nil {
		return localVarReturnValue, localVarHTTPResponse, err
	}

	localVarBody, err := io.ReadAll(localVarHTTPResponse.Body)
	localVarHTTPResponse.Body.Close()
	localVarHTTPResponse.Body = io.NopCloser(bytes.NewBuffer(localVarBody))
	if err != nil {
		return localVarReturnValue, localVarHTTPResponse, err
	}

	if localVarHTTPResponse.StatusCode >= 300 {
		newErr := &GenericOpenAPIError{
			body:  localVarBody,
			error: localVarHTTPResponse.Status,
		}
		return localVarReturnValue, localVarHTTPResponse, newErr
	}

	err = a.client.decode(&localVarReturnValue, localVarBody, localVarHTTPResponse.Header.Get("Content-Type"))
	if err != nil {
		newErr := &GenericOpenAPIError{
			body:  localVarBody,
			error: err.Error(),
		}
		return localVarReturnValue, localVarHTTPResponse, newErr
	}

	return localVarReturnValue, localVarHTTPResponse, nil
}