https://github.com/bitjson/couple-api
Unofficial Couple CLI and node library (incomplete)
https://github.com/bitjson/couple-api
Last synced: 11 months ago
JSON representation
Unofficial Couple CLI and node library (incomplete)
- Host: GitHub
- URL: https://github.com/bitjson/couple-api
- Owner: bitjson
- License: mit
- Created: 2015-03-26T02:05:51.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2016-11-11T16:56:58.000Z (over 9 years ago)
- Last Synced: 2024-10-22T16:18:54.688Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 42 KB
- Stars: 10
- Watchers: 6
- Forks: 4
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/couple-api) [](https://travis-ci.org/bitjson/couple-api) [](https://coveralls.io/r/bitjson/couple-api) [](https://david-dm.org/bitjson/couple-api)
# Couple API
An unofficial Node client and command-line interface for the [Couple App](https://couple.me/) API.
An excellent [web client](https://app.couple.me/) is available for Couple, but it seems to be using a somewhat outdated version of Couple's internal API ("Juliet" Version: `1.40`). For stability and access to the latest features, this library is built around the API methods used by the Couple iOS app ("Juliet" Version: `1.70`).
**WIP** : Please note, methods marked "WIP" are not yet implemented.
This library is currently only intended for interaction with the Couple timeline, and does not include methods for interacting with `Lists`, `Settings`, or the `Calendar`. Please feel free to [open an issue](https://github.com/bitjson/couple-api/issues), if you'd like to see it expanded!
## Node Client
Before interacting with the Couple API, you'll need to authenticate your client instance.
### Authenticate
The `authenticate` method retrieves your Couple App `authObject` using your username and password.
The `authObject` contains both your user profile and the profile of your `other`. It also contains your `authToken`, which is needed to authenticate other API calls. The `authToken` seems to expire at least monthly, as well as when the user's password is changed.
```js
var couple = new Couple();
var email = 'email@example.com';
var password = 'hunter2';
couple.authenticate(email, password, function(err, resObj) {
if(err) return console.error(err);
console.log('Client `couple` is authenticated:');
console.log(couple.identify());
});
```
### WIP: Timeline
All events – messages, stickers, nudges (`Thinking of you...`), etc. – are recorded in the `Timeline`. Upon logging in, the mobile apps begin downloading the timeline, 1600 events at a time, fetching and downloading media as it's encountered.
The `Timeline` function accepts an options object and a callback, and returns a `Timeline` object. The `Timeline` object includes all the information returned by the Couple API, as well as some convenience properties to make consecutive calls easier.
```js
var options = {
// using defaults:
// limit: 1600,
// order: desc,
// after: ''
};
couple.timeline(options, function(err, timeline) {
if(err) return console.error(err);
console.log(timeline);
});
```
#### Moments
Note, the web app (API version `1.40`) has a `/moments` endpoint (not currently implemented in this library), but the mobile apps rely on caching the timeline to generate the `Moments` section.
### WIP: Sending
[Coming soon...]
## Client API
```js
var couple = require('couple-api');
```
All library methods are documented below. This library strives for 100% test coverage, so examples of all implemented functionality and sample Couple API responses can be found in the [`test`](/test) directory.
### Authenticate
```js
couple.authenticate(email, password, callback);
```
Authenticates the `couple-api` instance. The method fetches the users `AuthObject` which contains a variety of information and is needed to authenticate all other calls.
#### Params
Name | Description
---------- | -------------------------
`email` | The user's email address.
`password` | The user's password.
#### callback(err, responseObject)
Called when the Couple API returns a response. All other methods can be called on the Couple instance after this callback is called. See tests for more detail.
### Identify
```js
couple.identify();
```
Returns an `identify` object.
Name | Description
----------- | -------------------------------------------------------------------------------------
`userID` | The ID (email address) of the authenticated user.
`authToken` | The user's base64 encoded authentication token.
`otherID` | The ID (email address) of the other user paired with the authenticated user.
`apiHost` | The full URL for Couple API server assigned to the user (to which requests are made).
`userUuid` | A unique version 4 UUID assigned to the user by Couple.
`pairUuid` | A unique version 4 UUID assigned to the pair by Couple.
### WIP: Timeline
```js
couple.timeline(options, callback);
```
Returns a segment of the authenticated user's Couple timeline.
#### Options
Name | Description
------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`limit` | The number of events to return. It seems that Couple has not yet implemented a maximum `limit`, but it's probably best to rely on pagination in your app, rather than downloading the whole timeline at once. If not set, this property will use the default value used by the mobile apps, `1600`.
`order` | Chronological order of results. Options: `desc` or `asc`. Defaults to `desc`.
`after` | Sets the starting point of the timeline segment retrieved. Accepts the `itemID` of the event occurring immediately before the first event in the response. By default, this is an empty string: `''`, causing the response to begin before the `pair` event, the first event in the whole timeline.
#### Callback(err, timeline)
Called when the Couple API returns a response.
##### timeline
The `timeline` object contains the `events` returned by the Couple API and additional properties.
```js
// timeline:
{
'firstItemID': 'timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx',
'lastItemID': 'timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx',
'events': [
{
// event object
},
{
// event object
},
...
]
}
```
##### events
Every entry in the Couple `timeline` is an `event`. The Couple timeline contains several types of events. All events have a number of similar properties.
Property | Value
----------- | ----------------------------------------------------------------------------------------------------------------------------------
`cver` | Couple app version which created the event. Prefix `i` for iOS (eg. `i1.9.9`), `a` for android, and `w` for the web client.
`eventType` | The event type.
`from` | The email of the user who created the event.
`itemID` | A unique identifier – the event's timestamp, concatenated with a version 4 UUID. (`timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`)
`lID` | A unique 9 character, numerical ID – seems to be used internally by the mobile apps.
`pairingID` | A unique version 4 UUID assigned to the pair by Couple.
`timeStamp` | The timestamp of the event in milliseconds.
Each `eventType` also has a number of unique properties.
###### text
The text event is a normal message.
Property | Value
------------- | ------------------------------------------------------------------------------------------------------------------------------------
`eventType` | Set to `text`.
`enc` | Text encoding. Only set on `text` events sent from the iOS app, which base64 encodes the `text` field. When set, the value is `b64`.
`text` | The contents of the message. May be base64 encoded.
`decodedText` | Property added to all `text` events by `couple-api`. Always contains the contents of the message.
###### pair
The pair event is the first event in the timeline.
Property | Value
----------- | ---------------------------------
`eventType` | Set to `pair`.
`pairType` | Seems to always be set to `pair`.
The `pair` event does not contain the `cver`, `from`, or `lID` properties.
###### sticker
The sticker event displays a sticker from a Couple sticker pack.
```js
{
"cver": "i1.9.9",
"eventType": "sticker",
"from": "user@example.com",
"itemID": "timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
"lID": "#########",
"pack": 19,
"pairingID": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
"sticker": 3,
"timeStamp": 1430522000000
}
```
###### nudge
```js
{
"cver": "i1.9.9",
"eventType": "nudge",
"from": "user@example.com",
"itemID": "timeStampxxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
"lID": "#########",
"pairingID": "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx",
"timeStamp": 1430522000000
}
```
# WIP: CLI