farm-budgets-sdk

NodeJS SDK for the farm-budgets-app. farmbudgets.org

• Quick Start
• Methods
• Rest API
• Schemas
• Classes
• Units

Quick Start

Install sdk

npm install farm-budgets-sdk

Visit farmbudgets.org, create an account if you don't have one, then login and click 'My Setup' -> 'My Account'. Copy the developer token. If the token is expired, click 'Generate New Token'.

Note, you can also setup and run farm-budgets-app locally if you wish.

Once you have the token, open a text editor and enter:

var sdk = require('farm-budgets-sdk')({
  host : 'http://farmbudgets.org',
  token : 'your-developer-key-here'
});

// list all the authorities I belong to.
sdk.authorities.list(function(resp){
     console.log(resp);
});

Or a more complete example. This will load your user data, preform an empty search, load the first budget returned, then display it's total.

var sdk = require('farm-budgets-sdk')(require('/etc/farm-budgets-sdk/setup.json'));

sdk.login(function(resp){
  console.log('Hello, '+sdk.me().display_name);

  sdk.budgets.search({}, function(resp){
    console.log('Loading: '+resp.results[0].id+' '+resp.results[0].name);
    sdk.loadBudget(resp.results[0].id, onBudgetLoad);
  });
});

// load() returns a Budget Class, not raw data object
function onBudgetLoad(budget) {
  console.log(budget.getName());
  console.log(sdk.getTotal());
}

Methods

The following are the top level methods for the SDK.

getBudget()

Returns the currently loaded Budget Class.

newBudget() / reset()

Create a new (empty) budget. Resets the state of all controllers. Returns the currently created and loaded empty Budget Class. reset() does the same thing.

loadBudget(id, callback)

Load a budget with the given id string. Callback response is either an error object or a new Budget Class.

setBudget(data)

Set budget initializes the controllers and returns a new Budget Class instance. The data parameter should match the response format of the API call budgets.load(id):

{
  budget : {
    // raw budget schema object
  },
  materials : [
    // list of raw material schema objects
  ]
}

login(callback)

Set your user data. This should be called before using the SDK as it is used to locally check access to objects (speeds up error detection) as well as set default authority values.

me()

Returns your user account object.

getTotal()

Returns the current total of the budget.

createMaterial(data)

Returns a new Material Class instance. If the data object is not provided, the material instance will be empty. This material will NOT be registered to the material controller (ie available to the budget). You must call budget.addMaterial(material) to add the material to the budget. See the Budget Class for more information.

Rest API

• Authorities API
• Materials API
• Budgets API

All callback functions return a single response object. If an error occurred a error = true flag will be set along with a message property. If message = 'request error', there was an issue with the http call, and additional response property will be set containing the full http response object. API errors will NOT contain the response object.

Authorities API

Calls to view, create, edit authorities.

authorities.list(callback)

Returns list of all authorities you have access to.

authorities.get(authorityName, callback)

• authorityName: name of authority. Ex: 'AHB'.

Returns name, description and list of members.

authorities.create(authority, callback)

• authority: authority object. See authority schema below.

Returns {success:true} on success.

authorities.update(authority, callback)

Update authority. currently only the description can be updated. The name is permanent.

• authority: authority object. See authority schema below.

Returns {success:true} on success.

authorities.grantAccess(authorityName, email, callback)

Add user to authority.

• authorityName: name of authority
• email: email address of user to add.

Returns {success:true} on success.

authorities.removeAccess(authorityName, email, callback)

remove user from authority.

• authorityName: name of authority
• email: email address of user to remove.

Returns {success:true} on success.

Materials API

Calls to view, create, edit, search and delete materials.

materials.get(id, callback)

Get a material by unique material id.

• id: unique material id.

Returns material object. See schema below.

materials.hasRequired(id, callback)

Given a complex material id. Does the materials authority have the required materials in the same location.

• id: unique material id.

Returns object.

materials.search(query, callback)

Search for materials. All MongoDB queries are allowed.

• query: query object. see here, all fields optional, but object is required:

{
  query : {} // mongodb query
  start : 0, // start index
  stop : 10, // stop index
}

materials.suggest(queryText, callback)

Suggest existing materials for given queryText

• queryText: string to find material suggestions for. Ex: 'tractor'. Query text can contain locations and authorities to help limit the suggestions. Ex: 'tractor california'

Returns list or material objects.

materials.save(material, callback)

Create or update material

• material: material object. See schema below. If id is provided an update will be preformed, otherwise insert.

Returns {succes:true} on success.

materials.delete(id, callback)

Delete material with given unique id.

• id: unique material id

Returns {succes:true} on success.

Budgets API

Calls to view, create, edit, search and delete budget.

budgets.get(id, callback)

Get a budget by unique budget id.

• id: unique budget id.

Returns budget object. See schema below.

budgets.contributedTo(callback)

Get a list of budgets you have contributed to.

Returns list of budget objects.

budgets.uses(materialId, callback)

Get a list of budgets that use the given material. This is good to check BEFORE you delete a material.

• materialId: unique material id.

Returns list of budget objects.

budgets.search(query, callback)

Search for budgets. All MongoDB queries are allowed.

• query: query object. see here, all fields optional, but object is required:

{
  query : {} // mongodb query
  start : 0, // start index
  stop : 10, // stop index
}

budgets.getData()

Returns current budget raw data schema.

budgets.save(budget, callback)

Create or update budget.

• budget: budget object. See schema below. If id is provided an update will be preformed, otherwise insert.

Returns {succes:true} on success.

budgets.delete(id, callback)

Delete budget with given unique id.

• id: unique budget id

Returns {succes:true} on success.

Schemas

Below are the 'raw' object schemas use and returned by the API requests.

• Authority Schema
• Material Schema
• Budget Schema

Authority Schema

{
  name : "", // authority name
  description : "" // description of authority
}

Material Schema

There are two material schemas. There type is determined by the type property. Material type can be 'simple' or complex

Simple Material Schema

Simple or base material

{
  authority : 'string', // name of authority (required)
  source : 'string', // source information.  Can be markdown
  class : 'string', // class (group) of material
  id : 'string', // uid of material
  locality : 'array', // array of string locations for authority (required)
  name : 'string', // name of material (required)
  description : 'string', // description of material
  price : 'number', // price of material
  year : 'number', // year for material price
  type : 'string', // must be 'simple'.  (required)
  units : 'string' // material units.  Needs to follow UCUM format.  See more below
}

Complex Material Schema

A material that requires other materials

{
  authority : 'string', // name of authority (required)
  class : 'string', // source information.  Can be markdown
  source : 'string', // class (group) of material
  id : 'string', // uid of material
  locality : 'array', // array of string locations for authority (required)
  name : 'string', // name of material (required)
  description : 'string', // description of material
  type : 'string', // must be 'complex'.  (required)
  units : 'string', // material units.  Needs to follow UCUM format.  See more below

  // require materials
  // this objects property keys should be the name of the require materials.
  // required materials can be simple or complex.  There is no relation to required
  // materials other than the name.
  materials : {
    _material_name_ : {
      amount : 'number', // amount of require material
      units : 'string' // amount units of require materials. Needs to follow UCUM format.  See more below
    }
  },

  // unique required simple materials.  You can add simple materials to a complex
  // material that are only used by this complex material and cannot be shared
  // with other materials.
  // This objects properties should be the name of the simple materials
  unique : {
    _material_name_ : {
      price : 'number', // price of simple material
      units : 'string' // units of price for simple material. Needs to follow UCUM format.  See more below
    }
  }
}

Budget Schema

To help readability the budget object has been split into two parts.

Base Budget Schema

{
  authority : 'string', // name of authority (required)
  locality : 'array', // array of string locations for authority (required)
  name : 'string', // budget name
  id : 'string', // unique budget id
  materialIds : 'array', // array of material ids currently associated with this budget
  reference : 'string', // unique budget id of reference budget.  If provided, the operations
  // property should be omited.
  commodity : 'string', // name of crop

  // information about the farm
  farm : {
    name : 'string', // farm name
    size : 'string', // farm size
    units : 'string' // units for farm size.  Needs to follow UCUM format.  See more below
  },

  operations : [] // array of operation objects, see more below
}

Budget Operations Schema

{
  name : 'string', // operation name
  units : 'string', // units for operation. Needs to follow UCUM format.  See more below

  // array of objects.  
  schedule : [{
    date : 'string', // start date.  Format:  YYYY-MM-DD
    length : 'string', // length of operation
    units : 'string' // length of operation units.  Options: 'year', 'month' or 'day'
  }],

  // array of require materials for operation
  materials : [{
    amount : 'number', // amount of material required
    id : 'string', // unique material id being used
    name : 'string', // name of material
    note : 'string', // note about material usage
    units : 'string' // units for material amount. Needs to follow UCUM format.  See more below
  }]
}

Classes

Helper classes that add some sugar to working with farm-budget-app objects.

• Budget Class
• Operation Class
• Material Class

Budget Class

First, to create a budget class, use the SDK's load method.

var sdk = require('farm-budget-sdk')({
  // config
});

sdk.load('budget-id-i-wish-to-load', function(budget){
  if( budget.error ) {
    throw(new Error(budget.message));
  }
  // 'budget' is an instance of the budget class
});

The budget class is wired into the farm budget app's calculator. So using it's methods to update operations will automatically trigger recalc events.

Budget.addOperation(name)

Add a new operation to the budget with the given name.

• name: String name of new operation.

Returns Operation Class instance.

Budget.getOperation(name)

Get operation(s) with the given name. Because operations can have the same name, an array will be returned. If no name is provided, all operation instances are returned.

• name: String name of operation(s) to retrieve.

Returns array of Operation Class instances.

Budget.getFarm()

Get the farm data object. Contains name, size and units.

Returns JavaScript Object.

Budget.setFarm(name, size, units)

Set the farm information.

• name: String name of farm.
• size: Number size of farm.
• units: String units of farm.

Budget.getAuthority()

Return the authority name of budget

Returns authority string.

Budget.setAuthority(authority)

Set the budget authority

• authority: String authority name.

Budget.getLocality()

Return the locality array.

Returns array of strings representing the locality of the budget.

Budget.setLocality(locality)

Set the locality array.

• locality: array of strings representing the locality of the budget

Budget.getName()

Get the name of the budget.

Return string name of budget.

Budget.setName(name)

Set the name of the budget.

• name: String name of the budget

Budget.getId()

Get the budgets unique id.

Return string budget id

Budget.setReference(budgetId)

Set this budget to be a reference budget. Reference budgets will not use their own operations, rather the operations of the reference. If you wish to undo this operation, simply pass null instead of a budget id.

• budgetId: String unique budget id to set reference to.

Budget.isReference()

Is this budget a reference budget.

Returns boolean, true if reference, false otherwise.

Budget.getCommodity()

Return the name of the commodity for this budget

Returns string commodity name

Budget.setCommodity(commodity)

Set the commodity of the budget.

• commodity: String name of the commodity

Budget.addMaterial(material)

Add a material to the list of budget materials to use.

• material: Material Class of material to add.

Operation Class

Operation.schedule(startDate, length, units)

Schedule the operation.

• startDate: String or Date Object. If string, should be in format YYYY-MM-DD.
• length: number length of operation
• units: units for length. Options: 'year', 'month' or 'day'

Operation.unschedule(schedule)

Remove a schedule event. Schedule should either be a numeric index or the schedule event object itself. Both can be discovered using the Operation.getSchedule() method.

• schedule: index of scheduled event to remove or scheduled event object instance to remove.

Operation.getSchedule()

Get array of schedule event objects.

Returns array of schedule event objects with the follow structure:

{
  name : "",
  length : "",
  units : ""
}

Operation.addRequiredMaterial(name, amount, units)

Add a required material to the operation.

• name: String name of the material.
• amount: number amount of required material.
• units: string units for amount of material.

Operation.getRequiredMaterials()

Get a list of the required material objects.

Returns list of required material objects with the following structure:

{
  name : "",
  amount : 0,
  units : ""
}

Operation.removeMaterial(index)

Remove a required material. The index can be found using Operation.getRequiredMaterials() which will return the entire list of materials.

• index: number index of material to remove.

Operation.getName()

Returns the operation name

Operation.setName(name)

Set the operation name.

• name: string name of the operation

Operation.getUnits()

Returns the operation units.

Operation.setUnits(units)

Set the operation units.

• units: string name of the units. Should be in UCUM format. See below.

Material Class

First, to create a Material Class, use the SDK's createMaterial method.

var sdk = require('farm-budget-sdk')({
  // config
});

var material = sdk.createMaterial(data);

A Material Class instance is returned. The data is optional. If you do pass data, it should be in the form of the Material Schema.

Material.getName()

Material.setName(name)

Material.getDescription()

Material.setDescription(description)

Material.getUnits()

Material.setUnits(units)

Material.getType()

Material.setType(type)

Material.getPrice()

Material.setPrice(price)

Material.getAuthority()

Material.setAuthority(authority)

Material.getLocality()

Material.setLocality(locality)

Material.getYear()

Material.setYear(year)

Material.getSource()

Material.setSource(source)

Material.getClass()

Material.setClass(class)

Material.save()

Units

All units MUST be provided in UCUM format http://unitsofmeasure.org/ucum.html

Helpers

The SDK provides some helper methods for units.

units.cleanDollars

Currently the default (and only supported currency) is us$. This, however, is not supported by ucum. This function will remove us$ and replace it with the base 1 so the unit can be parsed by ucum.

TODO: In the future, this should be made to cleanCurrency and support several currencies.

units.ucumParse(units)

This is a simple wrapper method around ucum lib's ucum.parse(units) method. This method can be expensive and calling it hundreds/thousands of times can really slow things down. units.ucumParse(units) adds a simple in memory cache of all calls made to the method, returning the cached value if available.

units.getLabel(baseUnit)

The SDK has a (slowly) growing list of labels for ucum units. This method returns a 'nice' label if available. Example: ucum's '[acr_us]' would return 'acre'.