npm package: @snsw/tuo-js-client
Description: Service New South Wales - Tell Us Once's client library
Author: Service NSW
Latest version: 1.0.16

# Install 

```
# For npm
npm install @snsw/tuo-js-client

## Or yarn
yarn add @snsw/tuo-js-client
```

# Usage

```javascript
    let myCustomer = {}
    
    const client = new ServiceNSWTellUsOnce({
        tellUsOnceUrl: "https://communication.testservicensw.net/api"
    })
 
    client.init()
        .then((customer) => {
            myCustomer.firstName = customer.firstName
            myCustomer.familyName = customer.familyName
            myCustomer.primaryEmail = customer.primaryEmail
        })
    
    // Change your local object
    myCustomer.firstName = 'John'
    
    // This call will send changes to the customer profile to 
    // a temporary location while the user approves them.
    client.customer = myCustomer

    // This will render a widget inside an element with id `tuo-widget-location` 
    // that allows the user to submit changes into his/her profile
    client.renderReviewWidget('tuo-widget-location')
```

Run the `client.init()` right after the page is loaded and once the Promise is completed you 
can access the `customer` object.

The `client.init()` will cause the browser to redirect to Single Sign On (SSO) with MyAccount so 
is recommended that the user is already signed in.

The `client.customer = myCustomer` will cause the customer to be sent to the backend system.

The `client.renderReviewWidget('tuo-widget-location')` will render the TUO widget inside an HTML element
with `id="tuo-widget-location"`. The TUO widget allows the user to permanently submit changes that were captured earlier using 
`client.customer = {...}`.

### Parameters

| Parameter     | Optional | Definition | Example |
|---------------|----------|------------|---------|
| tellUsOnceUrl | No       | Specify Tell Us Once API URL | ``` new ServiceNSWTellUsOnce({ tellUsOnceUrl: "https://communication.testservicensw.net/api" }) ``` |
| env           | Yes      | Specify Environment for Single Sign On / MyAccount. Accepted values: it6, psm, prod. If not provided would default to `prod`.| ``` new ServiceNSWTellUsOnce({ tellUsOnceUrl: "...", env: "psm" }) ``` |
| useScriptTag  | Yes      | For Angular app, dynamically append html element to header have an issue in Firefox and ie browser, contact us for solution. |``` new ServiceNSWTellUsOnce({ tellUsOnceUrl: "...", useScriptTag: true }) in html: <link href="${tuo-widget-url}/tuo-review-widget.css?noCache=1440520" rel="stylesheet"> <script src="${tuo-widget-url}/tuo-review-widget.js?noCache=1920121" type="text/javascript"></script>``` 

### Example

The following is an example using VueJs.

```html
<template>
     <div>
         <h1>My Service NSW Transaction</h1>
         <h2>Fill your personal details</h2>
         <div class="form__item">
             <label for="firstName">First Name</label>
             <input v-model="customer.firstName" type="text" id="firstName">
             <div role="tooltip" id="nameHelp" class="form__help-text">Your First Name</div>
         </div>
         <div class="form__item">
             <label for="familyName">Family Name</label>
             <input v-model="customer.familyName" type="text" id="familyName">
             <div role="tooltip" id="addressHelp" class="form__help-text">Your Family Name</div>
         </div>
         <div class="form__item">
             <label for="primaryEmail">Email</label>
             <input v-model="customer.primaryEmail" type="text" id="primaryEmail">
             <div role="tooltip" id="emailHelp" class="form__help-text">Your Primary Email Address</div>
         </div>
     </div>
</template>
 
<script>
    import ServiceNSWTellUsOnce from '@snsw/tuo-js-client'

    export default {
        name: "SampleForm",
        data: () => ({
            customer: {
                firstName: 'First Name',
                familyName: 'Family Name',
                primaryEmail: 'user@email.com'
            }
        }),
        mounted() {
            const client = new ServiceNSWTellUsOnce({
                    tellUsOnceUrl: 'https://communication.testservicensw.net/api',
                    env: 'it6',         // "env" attribute is optional. Default is PSM environment
            })
            client.init()
                .then((customer) => {
                    this.customer.firstName = customer.firstName
                    this.customer.familyName = customer.familyName
                    this.customer.primaryEmail = customer.primaryEmail
                })
        }
    }
</script>
```

### Known Issues

If your client application is hosted locally on your development machine (i.e. http://localhost:8080) and you use
remote TellUsOnce URL (for example, you set `tellUsOnceUrl=https://communication.testservicensw.net/api`), you will get 
an HTTP 401 Error from TellUsOnce's `/customer` endpoint.

The workaround for when developing locally is to serve your content using hostname that you add to your `/etc/hosts` file.

Example:

- Your `/etc/hosts` file (or equivalent for your operating system):
```
127.0.0.1   localhost.testservicenw.net
```

- If your client application is a Vue.js application, you can configure your `vue.config.js` as followed:
```javascript
module.exports = {
    devServer: {
        host: 'localhost.testservicensw.net'
        // ...
    }
}
```

With the above configured, now you can access your client application from http://localhost.testservicensw.net:8080