Amatino Swift 0.0.10 Released

A new version of Amatino Swift has been released. 0.0.10 adds some Custom Unit capabilities, slims some method signatures, and various smaller bits and pieces.

Note that release 0.0.9 was skipped for reasons of… science. 0.0.8 is the previously released Swift library version.

  • Big breaking change: Session is no longer required as an argument for Performance, Position, Transaction, Balance, and RecursiveBalance
  • Build out the previously useless CustomUnit, including .retrieve().create(), .createMany(), and update() methods
  • Added unit tests for new CustomUnit methods.
  • Simplify internal AmatinoObject protocol (no change to public API)
  • Entity now conforms to Equatable protocol
  • Add Entity.delete() method
  • Add EntityList object
  • Fixed a bug causing Ledger and RecursiveLedger iterators to skip the first row in the Ledger

Amatino Python 0.0.7 Released

Amatino Python 0.0.7 has been released! This is a major new release, introducing a vast array of capabilities. It is not backwards compatible with 0.0.6. You can install Amatino via PyPi:

$ pip install amatino

Or, if you already have Amatino Python installed, upgrade:

$ pip install --upgrade amatino

Here’s the full list of changes:

  • Added Entity class including .create(), .retrieve()
  • Added Account class including .create(), .retrieve(), .update()
  • Added Transaction class including .create(), .retrieve(), .update(), .delete()
  • Added Entry class including various convenience initialisers
  • Added GlobalUnit class including .retrieve()
  • Added CustomUnit class including .create(), .retrieve()
  • Added User class including .retrieve()
  • Added Ledger & RecursiveLedger classes
  • Added internal Denomination abstract class
  • Added internal enumeration HTTPMethod
  • Added internal interface Encodable
  • Added some internal error types to provide more robust error explanations
  • Added tests for new classes
  • Removed AmatinoAlpha class & attendant tests

The high level

0.0.7 is the first Amatino Python release to include expressive, object-oriented syntax. Previous releases required manual composition of requests using the AmatinoAlpha object.

Documentation

So many new goodies. But how do we use them? Documentation to the rescue! All the new classes included in 0.0.7 are documented in Amatino Python’s GitHub Wiki. For example, you can check out the Transaction page to see all the Transaction class’s properties and methods.

The future

The most glaring omissions are 0.0.7 are probably Balance, Position, and Performance. Expect 0.0.8 to add those bad boys in the near future.

Enjoy!

– Hugh

Amatino JS 0.0.12 Released

Amatino’s Node.js library has receive a big ‘ol update. 0.0.12 lifts Amatino JS out of bare-bones alpha territory. New classes allow you to build accounting & finance functions into Node.js applications.

0.0.12 is by no means a ‘feature complete’ or beta release. Most Amatino services still lack dedicated classes. However, it is a major step towards such a release. To see plans for 0.0.13 and beyond, check out the newly populated GitHub issue tracker, and Projects page within which future work is organised into planned releases.

New capabilities

Amatino JS now offers the following classes:

Allowing you to easily access and manipulate the `Primary Objects’ discussed in Amatino’s HTTP documentation.

Amatino Javascript Documentation

This release includes the first version of Amatino’s Javascript documentation. The docs are hosted on the Amatino JS GitHub wiki. They provide comprehensive reference for all properties and methods, and example code.

Screenshot from the Amatino JS docs Account page

Installation & Usage

You can install Amatino JS via NPM. For more information about NPM, check out npmjs.com.

$ npm install amatino

Amatino classes may then be accessed by requiring Amatino:

const Amatino = require('Amatino');
Amatino.Transaction.create(...);

The Amatino JS Readme has been updated with a getting-started guide, including example code showing you how to start utilising Amatino services. Check it out on the Amatino JS GitHub page.

What’s next?

Check out the Amatino JS Projects page to see the roadmap for future releases. These plans are totally in flux: Feel free to contact me via Twitter (@hugh_jeremy), email (hugh@amatino.io), or on the Amatino discussion forums, and tell me what you would like to see next.

Special thanks must go to James Robb (jamesrobb.co.uk). Over the past few weeks, James has provided substantial and invaluable advice about how to move the Amatino JS project forward. Thank you James!

– Hugh

 

 

Amatino Swift 0.0.8 Released

A new version of Amatino Swift has been released. 0.0.8 makes Amatino Swift CocoaPods compatible. You can now install Amatino by adding it to your Podfile:

pod 'Amatino', '>= 0.0.8'

The underlying library is unchanged. Here’s the full changelog:

  • Added Amatino.podspec
  • Changed macOS target to 10.10 (arbitrary at this point)
  • Changed iOS target to 10.3 (arbitrary at this point)
  • Added MIT license
  • Updated readme.md to reflect latest development of the library

– Hugh

Amatino Swift v0.0.7 Released

Amatino Swift 0.0.7 is now available! You can install it via Carthage or get the source code from GitHub. 0.0.7 is a major new release that adds significant capability. The powerful Tree, Position, and Performance objects are now available. Here’s the full change-log:

    • Remove InternalLibraryError, which sneakily survived the error consolidation purge in 0.0.6
    • Add Account.update() method
    • Add Account.delete() method
    • Add Account.deleteRecursively() method
    • Add Tree class
    • Add Position class
    • Add Performance class
    • Add Node protocol
    • Add Node conforming TreeNode and PlaceholderNode classes (used by Tree, Position, and Performance)
  • Consolidate SessionCreateArguments & SessionAttributes into Session
  • Consolidate BalanceRetrieveArguments into Balance
  • Drastically simplified and empowered the internal EntityObject protocol, reducing code complexity and duplication (does not affect public API)
  • Added unit tests for new features

Plant some Trees

Trees present the entire chart of accounts of an Entity as a hierarchical object. Each node in the Tree summarises an Account, including an individual and recursive balances.

Each node is represented by an instance of a class conforming to the Node protocol. Two such classes existing: TreeNode and PlaceholderNode.

TreeNodes present summarised account data, including individual and recursive balances. PlaceholderNodes stand in for TreeNodes where the requesting User does not have read permissions for the Account in question. A PlaceholderNode still includes children, which may include TreeNodes if the User has permission to read from accounts further down the hierarchy.

Determine Position

Positions are generic representations of the accounting construct variously known as a balance sheet, statement of financial position, or something else depending on your jurisdiction. They include hierarchical representations of all asset, liability, and equity Accounts inside an Entity.

Like the Tree, each Account is represented by an instance of an object conforming to the Node protocol.

Measure Performance

Performances are generic representations of the accounting construct variously known as an income statement, statement of financial performance, or comprehensive income statement, depending on your jurisdiction. They include hierarchical representations of all income and expense accounts inside an Entity.

Like the Tree and Position objects, each Account is represented by an instance of an object conforming to the Node protocol.

Updating & Deleting Accounts

Account instances now feature .update() and delete() methods, which do what it says on the tin. Here’s an example of an update operation:

Delete operations require a bit of thought. Deleting an Account does not delete any Transactions with Entries party to that Account. As such, you must supply an Account you wish to transfer any Entries to upon deletion. Here’s an example:

What next…

0.0.8 will probably focus on units of account, i.e. GlobalUnits & CustomUnits. In particular, loading CustomUnits into an Entity so that you can denominate Transactions in whatever unit suits you.

– Hugh

Amatino Swift v0.0.6 Released

Amatino Swift 0.0.6 has arrived! 0.0.6 makes lots of under the hood changes, the most important being to the error types emitted by the library. Here’s the changelog:

  • Added Transaction.update() method
  • Added Transaction.delete() method
  • Added session and entity properties to Transaction(A side-effect of the addition of .update() and .delete())
  • Consolidated all errors emitted by Amatino Swift under a single error type, AmatinoError
  • Potential API response errors (e.g. server errors) are now gracefully & descriptively emitted by instances of AmatinoError.
  • Consolidated creation, update, and retrieval argument structs into Transaction, e.g. TransactionCreateArguments -> Transaction.CreateArguments
  • Consolidated AccountCreateArguments struct into Account as Account.CreateArguments
  • Replaced overloaded Account.create() & .retrieve() with Account.createMany() & .retrieveMany()
  • Internally re-plumbed Transaction to conform to a new internal EntityObject protocol, reducing code duplication (causes no changes to API)
  • Renamed UrlParameters(:Entity:[UrlTarget]) entity label from entityWithTargets to entity
  • Removed defunct ObjectCore, AmatinoObjectError, and ConstraintError types
  • Consolidated EntityCreateArguments struct into Entity.CreateArguments
  • New unit tests for new features

New Error Handling

Before 0.0.6, errors thrown by Amatino Swift were an absolute mess. There was AmatinoObjectError, ConstraintError, ResponseError, and even just plain old Error. Now, you can be sure that any error thrown by Amatino Swift will be of type AmatinoError.

AmatinoError provides an enum, Kind, off of which you can switch via AmatinoError.kind. For example, a Transaction.retrieve() request might yield a .notFound case when the Amatino API returns 404. You can get a verbose String description of an error by examining the AmatinoError.message property.

Some objects, such as Transaction, provide a superclass of AmatinoError called ConstraintError, which provides more detailed information about input constraint violations. For example, when you supply  Transaction.create() with a description that is too long.

You can still handled these more verbose ConstraintError cases with a plain AmatinoError handler, as AmatinoError will flag them with the .constraintViolated case.

Transaction Update & Deletion

Sometimes you might which to change a Transaction after storing it. Perhaps an error was made, or underlying facts have changed. You can now do so using the update() instance method. Here’s an example:

You may also flat out delete a Transaction using the delete() instance method. Example:

Consolidation of ancillary structs

Many Amatino Swift classes depend on a variety of ancillary structs to perform their work. For example, Transaction uses CreateArguments and UpdateArguments, as well as several internal types. These types were previously in their own files.

This arrangement was causing the Amatino Swift project to be a bit jumbled. Code completion when typing the start of an object name was also getting crowded. So, as a matter of preference, I’ve been moving all ancillary types into their relevant classes. For example, TransactionCreateArguments has become Transaction.CreateArguments.

This process started in 0.0.5, and is ongoing in 0.0.6. There are a few cases of the old style left, which I’ll probably get to in 0.0.7.

Enjoy!

– Hugh

Amatino Swift v0.0.5 Released

Amatino is a double entry accounting API, and Amatino Swift allows macOS & iOS developers to utilise Amatino in a Swift application. v0.0.5 is a major new Alpha release introducing the Ledger class, and some attendant smaller changes.

  • Added new Ledger class
  • Added new RecursiveLedger class
  • Added new LedgerPage class, a low level class underpinning Ledger and RecursiveLedger
  • Added new LedgerRow struct, used by Ledgers
  • parentAccount renamed to parent in AccountCreateArguments initialisers
  • AccountType is now inferred by AccountCreateArguments when a parent is supplied
  • Added new Account.create() async initialisers for various attribute mixes
  • Transaction will now throw ConstraintError if debits & credits do not balance on creation
  • Fixed a bug whereby all times sent to the Amatino API were in local system timezone rather than UTC
  • Added new Ledger-related unit tests

Retrieving a Ledger

Multiple Ledger.retrieve() overloads are available, allowing you to tailor the Ledger to your needs. For example, you might want to retrieve a specific timeframe or denominate the ledger in a particular unit (e.g. a non-native currency). You can also reverse-order the Ledger such that the first pages retrieves the most recent transactions.

RecursiveLedger syntax is identical to Ledger, but delivers every Transaction in the target Account and all of its children.

Installation

Amatino Swift may be installed via Carthage. Add github "amatino-code/amatino-swift"to your Cartfile.

Enjoy, and be sure to tell me what you think!

– Hugh

API v0.0.5 Released – Ledger Changes

A new version of the Amatino API has been deployed to all regions. 0.0.5 contains breaking changes to the Ledger object, and is not backward compatible with 0.0.4.

  • Ledgers may now only be retrieved one at a time
  • Ledgers are now paginated in rows of 500
  • Ledgers may now be returned in order of ascending or descending transaction time
  • Ledgers now require a order_oldest_first boolean argument
  • Returned Ledger root type is now a JSON Object rather than a JSON Array
  • Returned Ledger start_time and end_time will now be the start and end of the Ledger window, rather than the earliest and latest Transaction in the Ledger
  • Ledger end_time will now default to now at UTC if supplied as null
  • Ledger start_time will now default to end_time – 1 year if supplied as null
  • Fixed a bug that could cause Amatino to return a stale cached Ledger when null had previously been provided as a Ledger start time
  • Fixed a bug that caused Transactions to be stored with incorrect times (The transaction_time field was not being properly interpreted as UTC)

All the above changes also apply identically to the RecursiveLedger object.

The Amatino API obeys the Semantic Versioning convention: Any version before 1.0.0 should be considered unstable, and breaking changes may occur at any time. Even so, I don’t want to cause breaking changes unnecessarily, and don’t take this lightly.

These changes are aimed at making Ledger objects more useful in real world applications. They are the result of experimentation during development of the upcoming Amatino Swift v0.0.5.

– Hugh