@MomsFriendlyDevCo/Freedcamp

Freedcamp API wrapper.

This module provides a generic Freedcamp API wrapper which includes Auth and Issues access.

import {FCAuth, FCIssues} from '@momsfriendlydevco/freedcamp';

let fcAuth = new FCAuth({
    // Freedcamp API access
    secret: 'XXX',
    apikey: 'XXX',
    project: 'XXX',

    // Caching options
    // This will work out of the box using the local filesystem
    // For more complex config see https://github.com/MomsFriendlyDevCo/generic-cache
    cache: {},
});

// Establish access
await fcAuth.init();


// Access Freedcamp issues
let fcIssues = new FCIssues({auth: fcAuth});

// Fetch everything
await fcIssues.fetchAll() //= Array<Object>


// Fetch an issue by its reference (e.g. `ABC-1234`)
await fcIssues.get('ABC-1234') //= Object

API

Below is a selection of relevent API methods. See the source code for the full JSDoc commented function definitions and data specs.

FCAuth(options)

Class constructor for a Freedcamp Authorization instance.

Options can be the strings secret, apikey, project to specify Freedcamp options

Caching options can be specified via cache matching the spec used by @MomsFriendlyDevCo/cache - but will work out of the box using the local filesystem.

FCAuth.init()

Setup the auth library, optionally reading in .env files or environment variables.

FCIssues(options)

Class constructor for a Freedcamp Issues instance.

Options can be auth which is a FCAuth instance and/or cache which is an overriding cache if this differs from that in the auth option.

FCIssues.Issue

Issue specifier format used by this module. This format is used for individual issues returned by FCIssues.get() or all issues from FCIssues.fetchAll().

| Property | Type | Description | |--------------------|-----------------|-------------------------------------------------------------------------------------| | id | String | The FC ID of the issue | | ref | String | The human readable reference | | title | String | The issue title | | assignee | String | The name of the person assigned | | status | String | The status title of the issue | | url | String | The URL of the issue | | html | String | HTML body of the issue | | raw | Object | The raw, original issue object (only provided if FCIssues.includeRaw is truthy) | | comments | Array<Object> | Optional comment stream (available via FCIssues.get(ref, {comments: true})) | | comments.id | String | The FC comment ID | | comments.created | Number | The original creation date of the comment in JavaScript Unix epoc | | comments.edited | Number | Comment last updated (or omitted if not) | | comments.user | String | The name of the poster | | comments.url | String | Direct link to the comment | | comments.html | String | HTML body of the comment | | comments.raw | String | The raw, original comment object (only provided if FCIssues.includeRaw is truthy) |

FCIssues.fetchAll(options)

Fetch all issues and optionally cache for future reference This function uses caching by default unless options.cache.enabled=false.

Options can be:

| Option | Type | Default | Description | |----------|-----------|---------|----------------------------------------------------------------------------------------------------------------| | force | Boolean | false | Whether to force the search, even if caching is present | | limit | Number | 100 | How many issues to pull down at once | | offset | Number | -1 | Overriding offset to start pulling from, will pull once only and ignore page calculations, use -1 to disable |

Returns a promise which will resolve with the full collection of all issues fetched.

FCIssues.get(ref, options)

Fetch an issue by its ref (e.g. ABC-1234). This will use the cached issue if it is available.

Options can be:

| Option | Type | Default | Description | |------------|-----------|---------|------------------------------------------| | comments | Boolean | false | Also fetch associated comment collection | | cache | Object | | cache.worker() options |

Returns a promise which will resolve with the found issue, if any.