@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.