<commit_before># BuildAPIAccess 3.0.2 #

*BuildAPIAccess* is an Objective-C (macOS, iOS and tvOS) wrapper for [Electric Imp’s impCentral™ API](https://developer.electricimp.com/tools/impcentralapi). It is called BuildAPIAccess for historical reasons: it was written to the support Electric Imp’s Build API, the predecessor to the impCentral API. **BuildAPIAccess 3.0.2 does not support the Build API**, which has been deprecated and will shortly be removed from service.

*BuildAPIAccess* requires the (included) classes *Connexion*, *LogStreamEvent* and *Toke*n. All three are convenience classes for combining properties.

- *Connexion* combines an [NSURLSession](https://developer.apple.com/library/prerelease/mac/documentation/Foundation/Reference/NSURLSession_class/index.html) instance and associated impCentral API connection data.
- *Token* is used to store impCentral API authorization data.
- *LogStreamEvent* is a packaging object for Server-Sent Events (SSE) issued by the impCentral API's logging system.

## impCentral API Authorization ##

Making use of the impCentral API requires an Electric Imp account. You will need your account username and password to authorize calls to the API. These are passed into the *login:* method. *BuildAPIAccess* instances do not maintain a permanent record of the selected account; this is the task of the host application.

## Licence and Copyright ##

BuildAPIAccess is &copy; <NAME>, 2015-18 and is offered under the terms of the MIT licence.

The impCentral API is &copy; Electric Imp, 2017-18.

## HTTP User Agent ##

From version 2.0.1, BuildAPIAccess issues HTTPS requests with a custom user agent string of the following form:

```
BuildAPIAccess/<VERSION> <HOST_APP_NAME>/<VERSION> (macOS <VERSION>)
```

## Release Notes ##

- 3.0.2
    - *In development*
    - Finalize multi-password authentication (MPA) support
    - Issue notification on login rejection rather than post an error
    - Unify all non-code error notifications (`@"BuildAPIError"`) to return `{ "message": <error_message>, "code": <error_code> }`
- 3.0.1
    - *Released July 10, 2018*
    - Add *getAccount()* and *gotMyAccount()* methods
- 3.0.0
    - Major revision to support the impCentral API
    - End support for the (deprecated) Build API

## Class Usage ##

Initialize a *BuildAPIAccess* instance using *init:*

```
BuildAPIAccess *api = [[BuildAPIAccess alloc] init];
```

## Class Methods: Login and Authentication ##

### - (void)login:(NSString &#42;)userName :(NSString &#42;)passWord :(BOOL)is2FA ###

Log in using the supplied credentials. The method uses the credentials to retrieve a new API access token, which is used to authorize all further API accesses during the lifetime of the token. Values passed into *is2FA* are currently ignored; this parameter is for future use.

### - (void)twoFactorLogin:(NSString &#42;)loginToken :(NSString &#42;)otp ###

If OTP is enabled for the target account, BuildAPIAccess will return the notification `@"BuildAPINeedOTP"` and return the server-supplied login token within the notification object via the key *token*. The host app should respond to this by requesting access using this method. Pass in the login token and the six-digit OTP code, typically retrieved from a phone app.

### - (void)logout ###

Delete the instance's impCentral API authorization tokens and close any current connections.

### - (void)setEndpoint:(NSString &#42;)pathWithVersion ###

Changes the URL to which BuildAPIAccess accesses the impCentral API. Use this if you are accessing the API within a Private Cloud. If this is not called, all API accesses are made to `https://api.electricimp.com/v5`.

### - (void)getMyAccount ###

Get information on the logged in account. The instance posts the notification `@"BuildAPIGotMyAccount"` when the account data has been received.

### - (void)getAccount:(NSString &#42;)accountID ###<commit_msg>Update for 3.1.0<commit_after># BuildAPIAccess 3.1.0 #

*BuildAPIAccess* is an Objective-C (macOS, iOS and tvOS) wrapper for [Electric Imp’s impCentral™ API](https://developer.electricimp.com/tools/impcentralapi). It is called BuildAPIAccess for historical reasons: it was written to the support Electric Imp’s Build API, the predecessor to the impCentral API. **BuildAPIAccess 3.0.2 does not support the Build API**, which has been deprecated and will shortly be removed from service.

*BuildAPIAccess* requires the (included) classes *Connexion*, *LogStreamEvent* and *Toke*n. All three are convenience classes for combining properties.

- *Connexion* combines an [NSURLSession](https://developer.apple.com/library/prerelease/mac/documentation/Foundation/Reference/NSURLSession_class/index.html) instance and associated impCentral API connection data.
- *Token* is used to store impCentral API authorization data.
- *LogStreamEvent* is a packaging object for Server-Sent Events (SSE) issued by the impCentral API's logging system.

## impCentral API Authorization ##

Making use of the impCentral API requires an Electric Imp account. You will need your account username and password to authorize calls to the API. These are passed into the *login:* method. *BuildAPIAccess* instances do not maintain a permanent record of the selected account; this is the task of the host application.

## Licence and Copyright ##

BuildAPIAccess is &copy; <NAME>, 2015-18 and is offered under the terms of the MIT licence.

The impCentral API is &copy; Electric Imp, 2017-18.

## HTTP User Agent ##

From version 2.0.1, BuildAPIAccess issues HTTPS requests with a custom user agent string of the following form:

```
BuildAPIAccess/<VERSION> <HOST_APP_NAME>/<VERSION> (macOS <VERSION>)
```

## Release Notes ##

- 3.1.0
    - Finalize multi-password authentication (MPA) support
        - Remove *is2FA* parameter from *login:::* (it's redundant)
    - Issue notification on login rejection rather than post an error
    - Unify all non-code error notifications (`@"BuildAPIError"`) to return `{ "message": <error_message>, "code": <error_code> }`
- 3.0.1
    - *Released July 10, 2018*
    - Add *getAccount()* and *gotMyAccount()* methods
- 3.0.0
    - Major revision to support the impCentral API
    - End support for the (deprecated) Build API

## Class Usage ##

Initialize a *BuildAPIAccess* instance using *init:*

```
BuildAPIAccess *api = [[BuildAPIAccess alloc] init];
```

## Class Methods: Login and Authentication ##

### - (void)login:(NSString &#42;)userName :(NSString &#42;)passWord ###

Log in using the supplied credentials. The method uses the credentials to retrieve a new API access token, which is used to authorize all further API accesses during the lifetime of the token.

### - (void)twoFactorLogin:(NSString &#42;)loginToken :(NSString &#42;)otp ###

If OTP is enabled for the target account, BuildAPIAccess will return the notification `@"BuildAPINeedOTP"` and return the server-supplied login token within the notification object via the key *token*. The host app should respond to this by requesting access using this method. Pass in the login token and the six-digit OTP code, typically retrieved from a phone app.

### - (void)logout ###

Delete the instance's impCentral API authorization tokens and close any current connections.

### - (void)setEndpoint:(NSString &#42;)pathWithVersion ###

Changes the URL to which BuildAPIAccess accesses the impCentral API. Use this if you are accessing the API within a Private Cloud. If this is not called, all API accesses are made to `https://api.electricimp.com/v5`.

### - (void)getMyAccount ###

Get information on the logged in account. The instance posts the notification `@"BuildAPIGotMyAccount"` when the account data has been received.

### - (void)getAccount:(NSString &#42;)accountID ###
{'fraction_non_alphanumeric': 0.09455808568120416, 'fraction_numerical': 0.013379647497748616, 'mean_word_length': 4.728813559322034, 'pattern_counts': {'":': 4, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 6, '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': '1103471', 'n_tokens_mistral': 2217, 'n_tokens_neox': 2082, 'n_words': 945}