<commit_before>The following examples explain the Invoices section of the SDK.  The API documentation on Invoices can be found [here](https://developer.xero.com/documentation/api/invoices).

### Supported functions

* Create New Invoices
* Retrieve Invoices (all, paginated, by ID, with 'where' clause)
* Update Invoices

These functions are explained further below.

### Entity Helper

The entity helper that has been created for the invoices functions exists in the following place:

`client.core.invoices`

This helper contains the following functions:

* `newInvoice(data[, options])`
* `saveInvoices(invoices[, options])`
* `getInvoices([options])`
* `getInvoice(id[, modifiedAfter])`
* `streamInvoice(id, format, stream)`

### Creating a new draft invoice

This code assumes you've already created a client using the xero-node sdk. 

```javascript

var sampleInvoice = {
    Type: 'ACCREC',
    Contact: {
        Name: 'Department of Testing'
    },
    DueDate: new Date().toISOString().split("T")[0],
    LineItems: [{
        Description: 'Services',
        Quantity: 2,
        UnitAmount: 230,
        AccountCode: '200'
    }]
};

var invoiceObj = xeroClient.core.invoices.newInvoice(sampleInvoice);

invoiceObj.save()
    .then(function(invoices) {
        //Invoice has been created 
        var myInvoice = invoices.entities[0];
    })
    .catch(function(err) {
        //Some error occurred
    });
```

Some points to note with the code snippet above:

* The `.newInvoice()` function doesn't actually make any API call to Xero.  It only creates an object according to the invoice schema that _can_ be saved using the `.save()` function at some point in future.
* The `.save()` function returns a promise that can be met using the `.then()` function, and rejections can be caught using the `.catch()` function.
* The promise that is returned by the `.save()` function contains a response object.  This has a bunch of information about the state of the response, but also contains an `entities` array.  This array is what actually contains the object that was just created. 
* For single object saving, this `entities` array should only ever contain one element, but some objects support a multiple object save and in this case the `entities` array will contain all of the objects that were created.

### Updating a Invoice

This functionality shows how a invoice can be updated to a status of 'AUTHORISED'.

```javascript

var invoiceID = '39580864-26a9-40fd-840a-da4c61564476';

//Get the draft invoice, update it, and save it.
currentApp.core.invoices.getInvoice(invoiceID)
    .then(function(invoice) {

        invoice.Status = 'AUTHORISED';

        invoice.save()
            .then(function(savedInvoice) {
                console.log(savedInvoice.entities[0].Status); //'AUTHORISED'
            });
```

### Retrieving All Invoices

This example shows how to retrieve all invoices in a single call.

```javascript

xeroClient.core.invoices.getInvoices()
   .then(function(invoices) {
      //We've got some invoices
      invoices.forEach(function(invoice){
         //do something useful
         console.log(invoice.Type); //ACCPAY
      });
   })
```

* When using the getInvoices method, as no object is being saved there is no `entities` array.  Instead you are provided an array of invoice objects that you can use directly in your application.

### Retrieving Invoice by ID<commit_msg>Proposal intuitive syntax to get entities[0]<commit_after>The following examples explain the Invoices section of the SDK.  The API documentation on Invoices can be found [here](https://developer.xero.com/documentation/api/invoices).

### Supported functions

* Create New Invoices
* Retrieve Invoices (all, paginated, by ID, with 'where' clause)
* Update Invoices

These functions are explained further below.

### Entity Helper

The entity helper that has been created for the invoices functions exists in the following place:

`client.core.invoices`

This helper contains the following functions:

* `newInvoice(data[, options])`
* `saveInvoices(invoices[, options])`
* `getInvoices([options])`
* `getInvoice(id[, modifiedAfter])`
* `streamInvoice(id, format, stream)`

### Creating a new draft invoice

This code assumes you've already created a client using the xero-node sdk. 

```javascript

var sampleInvoice = {
    Type: 'ACCREC',
    Contact: {
        Name: 'Department of Testing'
    },
    DueDate: new Date().toISOString().split("T")[0],
    LineItems: [{
        Description: 'Services',
        Quantity: 2,
        UnitAmount: 230,
        AccountCode: '200'
    }]
};

var invoiceObj = xeroClient.core.invoices.newInvoice(sampleInvoice);

invoiceObj.save()
    .then(function(invoices) {
        //Invoice has been created 
        var [ myInvoice ] = invoices.entities;
        console.log(myInvoice)
    })
    .catch(function(err) {
        //Some error occurred
    });
```

Some points to note with the code snippet above:

* The `.newInvoice()` function doesn't actually make any API call to Xero.  It only creates an object according to the invoice schema that _can_ be saved using the `.save()` function at some point in future.
* The `.save()` function returns a promise that can be met using the `.then()` function, and rejections can be caught using the `.catch()` function.
* The promise that is returned by the `.save()` function contains a response object.  This has a bunch of information about the state of the response, but also contains an `entities` array.  This array is what actually contains the object that was just created. 
* For single object saving, this `entities` array should only ever contain one element, but some objects support a multiple object save and in this case the `entities` array will contain all of the objects that were created.

### Updating a Invoice

This functionality shows how a invoice can be updated to a status of 'AUTHORISED'.

```javascript

var invoiceID = '39580864-26a9-40fd-840a-da4c61564476';

//Get the draft invoice, update it, and save it.
currentApp.core.invoices.getInvoice(invoiceID)
    .then(function(invoice) {

        invoice.Status = 'AUTHORISED';

        invoice.save()
            .then(function(savedInvoice) {
                var [ mySavedInvoice ] = savedInvoice.entities
                console.log(mySavedInvoice.Status); //'AUTHORISED'
            });
```

### Retrieving All Invoices

This example shows how to retrieve all invoices in a single call.

```javascript

xeroClient.core.invoices.getInvoices()
   .then(function(invoices) {
      //We've got some invoices
      invoices.forEach(function(invoice){
         //do something useful
         console.log(invoice.Type); //ACCPAY
      });
   })
```

* When using the getInvoices method, as no object is being saved there is no `entities` array.  Instead you are provided an array of invoice objects that you can use directly in your application.

### Retrieving Invoice by ID
{'fraction_non_alphanumeric': 0.09752589182968929, 'fraction_numerical': 0.009925201380897584, 'mean_word_length': 3.5683311432325886, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5726954', 'n_tokens_mistral': 2087, 'n_tokens_neox': 1966, 'n_words': 768}