# spire-js

> Spire JavaScript Client

Latest version **0.2.1** (published 2019-07-16) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install spire-js
pnpm add spire-js
yarn add spire-js
bun add spire-js
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.2.1 |
| Published | 2019-07-16 |
| First published | 2017-10-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 79.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Spire Systems Inc. |
| Maintainers | mattkalina |

## Links

- npm: https://www.npmjs.com/package/spire-js
- Repository: https://github.com/spiresystems/spire-js
- Homepage: https://github.com/spiresystems/spire-js#readme
- Issues: https://github.com/spiresystems/spire-js/issues
- npm.io page: https://npm.io/package/spire-js

## Dependencies (7)

- [big.js](https://npm.io/package/big.js.md) ^5.2.2
- [lodash.assign](https://npm.io/package/lodash.assign.md) ^4.2.0
- [ampersand-model](https://npm.io/package/ampersand-model.md) ^8.0.1
- [ampersand-events](https://npm.io/package/ampersand-events.md) ^2.0.2
- [ampersand-collection](https://npm.io/package/ampersand-collection.md) ^2.0.2
- [ampersand-rest-collection](https://npm.io/package/ampersand-rest-collection.md) ^6.0.0
- [ampersand-collection-lodash-mixin](https://npm.io/package/ampersand-collection-lodash-mixin.md) ^4.0.0

## Recent versions

- 0.2.1 (latest) — 2019-07-16
- 0.2.0 — 2018-10-15
- 0.1.2 — 2017-12-01
- 0.1.1 — 2017-10-19
- 0.1.0 — 2017-10-19

## README

# Spire JavaScript Client

This package provides convenient access to the Spire REST API from applications
written in JavaScript.

## Installation

Install the package with:

    npm install spire-js

## Usage

### Import the Spire package

```javascript
var spire = require('spire-js');
```

Or if your JavaScript environment supports ES6:

```javascript
import spire from 'spire-js';
```

### Connect to Your Spire Server

Supply a hostname or IP address for your Spire server.

```javascript
spire.connectServer(address);
```

If your Spire Server is running on a different port than the default (10880) you
can pass the port to `connectServer`:

```javascript
spire.connectServer('127.0.0.1', 10881);
```

#### Connections from Server Environment (Node.js)

For Spire Server 3.2 and earlier using a self-signed certificate you will need
to disable certificate validation:

    export NODE_TLS_REJECT_UNAUTHORIZED=0

### Authenticate a User

Supply a username and password for a Spire account on the connected server:

```javascript
spire.authenticate(username, password);
```

### Listing Companies

To list companies that have been setup on your Spire server, create a
`CompanyList` instance and call `fetch`:

```javascript
var companies = new spire.company.CompanyList();
companies.fetch({
  success: function(results) {
    var company = results.get('inspire');
    // Do stuff with company...
  }
});
```

The `CompanyList` collection will be populated with instances of `Company` for
each company that is configured on your server. See [Company](docs/company.md)
for details about the attributes of a `Company` object.

### Setting Company

Requests for resources owned by a particular company require the company to be
set on your Spire API instance prior to using them. Provide a `Company` instance
obtained above, or a company name (`string`) as the company argument here:

```javascript
spire.setCompany('inspire');
```

### Working With Collections

The following collections are provided by this package:

|  | Description |
| --- | --- |
| `spire.company.CompanyList` | Companies |
| `spire.customer.CustomerList` | Customers |
| `spire.employee.EmployeeList` | Employees |
| `spire.gl.GLAccountList` | GL Accounts |
| `spire.gl.GLTransactionList` | GL Transactions |
| `spire.inventory.InventoryAdjustmentList` | Inventory Adjustments and Transfers |
| `spire.inventory.InventoryList` | Inventory |
| `spire.inventory.PriceMatrixList` | Price Matrices |
| `spire.job.JobList` | Jobs |
| `spire.paymentMethod.PaymentMethodList` | Payment Methods |
| `spire.paymentTerms.PaymentTermsList` | Payment Terms |
| `spire.payroll.TimecardList` | Timecards |
| `spire.purchasing.PurchaseHistoryList` | Purchase History |
| `spire.purchasing.PurchaseOrderList` | Purchase Orders |
| `spire.sales.SalesHistoryList` | Sales History |
| `spire.sales.SalesOrderList` | Sales Orders |
| `spire.salesperson.SalespersonList` | Salespeople |
| `spire.territory.TerritoryList` | Territories |
| `spire.vendor.VendorList` | Vendors |

Collections can be queried by providing an object to the `fetch()` method:

```javascript
var salesOrders = new spire.sales.SalesOrderList();

salesOrders.fetch({
  data: {
    start: 0,                // Starting offset
    limit: 100,              // Limit number of results
    //fields: 'id,orderNo',  // Comma separated list of fields to return (defaults to all fields)
    //q: 'search query',     // Search for keywords

    // Filter results
    filter: JSON.stringify({
        orderDate: spire.utils.formatDate(new Date())  // Today's orders
    })
  },

  success: function(collection, response, options) {
    // Actions to perform on success
    collection.map(function(order) {
      // 'Inflate' order
      order.fetch({
        success: function(order) {
          console.log(order);
        }
      });
    });
  },

  error: function(collection, response, options) {
    // Actions to perform on error
  },

  reset: false  // Reset collection with new objects or append to it
                // (defaults to append)
});
```

Model instances populated during a fetch operation may not have all of their
attributes defined because the collection endpoint on the Spire server does not
always provide a complete representation. This is more common with complex
objects like orders, and is generally to preserve the performance of the list.
To "inflate" the Model instance you can call `fetch()` on each one (which
dispatches a request to the server for the complete representation) and will
populate the undefined attributes.

Alternately, you can get a specific record from the server using the
`getOrFetch` method on the collection (model instances returned will be fully
inflated):

```javascript
salesOrders.getOrFetch(1, function(err, model) {
  if(err) {
    console.log('An error occurred');
  } else {
    console.log(model);
  }
});
```

Once a collection is populated with model instances (following a successful
`fetch`) you can `get` a specific ID from the collection using either its
primary key (usually 'id'), or by specifying a user-facing key like `orderNo`
(this may not work in all cases).

```javascript
salesOrders.get(1);

// OR

salesOrders.get('00000100-0', 'orderNo');
```

More information about working with collections can be found here:

[ampersand-rest-collection](https://ampersandjs.com/docs/#ampersand-rest-collection)

### Working With Model Objects

The following models are provided by this package:

|  | Description |
| --- | --- |
| [`spire.company.Company`](docs/company.md) | Spire Company |
| [`spire.customer.Customer`](docs/customer.md) | Customer |
| [`spire.employee.Employee`](docs/employee.md) | Employee |
| [`spire.gl.GLAccount`](docs/gl.md#gl-account) | GL Account |
| [`spire.gl.GLTransaction`](docs/gl.md#gl-transaction) | GL Transaction |
| [`spire.gl.GLTransactionItem`](docs/gl.md#gl-transaction-item) | GL Transaction Item |
| [`spire.inventory.InventoryAdjustment`](docs/inventory.md#inventory-adjustment) | Inventory Adjustment and Transfer |
| [`spire.inventory.InventoryAdjustmentItem`](docs/inventory.md#inventory-adjustment-item) | Inventory Adjustment Item |
| [`spire.inventory.Inventory`](docs/inventory.md#inventory) | Inventory |
| [`spire.inventory.PriceMatrix`](docs/inventory.md#price-matrix) | Price Matrix |
| [`spire.paymentMethod.PaymentMethod`](docs/payment_method.md) | Payment Method |
| [`spire.paymentTerms.PaymentTerms`](docs/payment_terms.md) | Payment Terms |
| [`spire.payroll.Timecard`](docs/payroll.md#timecard) | Timecard |
| [`spire.payroll.TimecardEntry`](docs/payroll.md#timecard-entry) | Timecard Entry |
| [`spire.purchasing.PurchaseHistory`](docs/purchasing.md#purchase-history) | Purchase History |
| [`spire.purchasing.PurchaseOrder`](docs/purchasing.md#purchase-order) | Purchase Order |
| [`spire.purchasing.PurchaseOrderItem`](docs/purchasing.md#purchase-order-item) | Purchase Order Item |
| [`spire.sales.SalesHistory`](docs/sales.md#sales-history) | Sales History |
| [`spire.sales.SalesHistoryItem`](docs/sales.md#sales-history-item) | Sales History Item |
| [`spire.sales.SalesOrder`](docs/sales.md#sales-order) | Sales Order |
| [`spire.sales.SalesOrderItem`](docs/sales.md#sales-order-item) | Sales Order Item |
| [`spire.sales.SalesOrderPayment`](docs/sales.md#sales-order-payment) | Sales Order Payment |
| [`spire.salesperson.Salesperson`](docs/salesperson.md) | Salesperson |
| [`spire.territory.Territory`](docs/territory.md) | Territory |
| [`spire.vendor.Vendor`](docs/vendor.md) | Vendor |

The create, read, update, delete (CRUD) functions are provided by the following
methods on a Model instance:

| Method | Description
| --- | --- |
| `save` | Creates the object if new (`POST`), otherwise updates it (`PUT`) |
| `destroy` | Attempts to delete the object (`DELETE`) |
| `fetch` | Refreshes the object from the server |

To load a specific object by ID:

```javascript
var salesOrder = new spire.sales.SalesOrder({id: 1});
salesOrder.fetch({
  success: function() {
    console.log('Successfully loaded object');
  },

  error: function() {
    console.log('An error occurred');
  }
});
```

To delete an object:

```javascript
salesOrder.destroy({
  success: function() {
    console.log('Successfully deleted object');
  },

  error: function() {
    console.log('An error occurred');
  }
});
```

Change an attribute and update the object:

```javascript
salesOrder.requiredDate = new Date();
salesOrder.save();
```

#### Example Sales Order Creation

```javascript
// Create an order instance
var salesOrder = new spire.sales.SalesOrder();

// Create a customer
var customer = new spire.customer.Customer();
customer.name = 'Arya Stark';
customer.save();
salesOrder.customer = customer;

// Create an item
var item = new spire.sales.SalesOrderItem();
item.inventory.whse = '00';
item.inventory.partNo = 'TEST';  // partNo must exist in whse
salesOrder.items.add(item);

salesOrder.save();
```

More information about working with individual model objects can be found here:

[ampersand-model](https://ampersandjs.com/docs/#ampersand-model)

### Custom Types

#### Decimal

Generally values returned from the Spire API as JSON map to native JavaScript
types. A notable exception is decimal values returned from the Spire API as
`string`s. It is inconvenient to work with `string` and `int` objects for
business operations, and native floating point `Numeric` objects won't work for
this purpose, so this library provides a `types.Decimal` type. Objects returned
from the API are automatically deserialized with this type where necessary, and
serialized back to `string`s for persistence operations. The decimal type
currently employed is actually a [big.js](http://mikemcl.github.io/big.js)
object that has been lightly modified to add thousands separators via the
`format()` method.

Example:

```javascript
var dec = new spire.types.Decimal('1021.25');
dec.format();
// 1,021.25
```

### Utilities

#### Date Formatting

The Spire API expects local date strings to be in the format 'YYYY-MM-DD' for
communication with the server. The `spire.utils` namespace provides the
`formatDate` function that will take a JavaScript Date object and serialize it
into a string in the expected format. This is generally not required when
working with collections and model objects; however, it can be helpful when
building filter criteria.

```javascript
spire.utils.formatDate(new Date());
// '2017-10-16'
```

---
_Source: https://npm.io/package/spire-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._