# ssb-issues

Issue tracking built on secure-scuttlebutt

## Schema

#### type: issue

An issue. Represents something that should be fixed.

```js
{
  type: 'issue',
  project: Link?,
  title: string?,
  text: string?,
  labels: [LabelRef]?
}
```

#### issue edits

Edits to an issue open/closed state may be done by ssb message type
`issue-edit`, `post`, or `git-update`. For example, you can make a post that
updates an issue, or push a git commit that updates an issue.  Other issue
edits should be done with message type `issue-edit`.

```js
{
  type: 'issue-edit'|'post'|'git-update',
  issues: [{
    link: IssueRef,
    open: boolean?,
    labels: {
      add: [IssueRef]?,
      remove: [IssueRef]?,
    }?
  }]
}
```

#### issue labels

An issue label represents a tag that can be applied to issues in a repo/project.
It can be renamed using `about` messages. Issue labels can be added to or removed from issues using `issue-edit` messages.

```js
{
  type: 'issue-label',
  project: Link?,
  name: string?,
  issues: [issueRef]?
}
```

- `issues`: initial set of issues to add the label to

## API

```js
var Issues = require('ssb-issues')
var issues = Issues.init(sbot)
```

#### get: async

Get an issue by its id

```js
issues.get(issueId, cb)
```

The resulting issue object is as follows:

```js
{
  id: MsgRef,
  author: FeedRef,
  project: Ref?,
  projectAuthor: FeedRef?,
  created_at: number, 
  updated_at: number,
  open: boolean,
  msg: Msg,
  labels: MsgRefs
}
```

- `id`: id of the issue
- `author`: author of the issue
- `created_at` (timestamp): when the issue was created
- `updated_at` (timestamp): when the issue was last updated
- `title`: title of the issue (deprecated)
- `open`: whether the issue is open (true) or closed (false)
- `project`: the project that the issue is for
- `projectAuthor`: the author of the project
- `msg`: ssb message object that created the issue (with
    `.key` and `.value`).
- `labels`: ids of issue-labels associated with the issue

#### list: source

Get a stream of issues 

```js
issues.list({ project:, open:, author:, live:, gt:, gte:, lt:, lte:, reverse: })
```

 - `project` (Ref): get only issues for the given target
 - `open` (boolean): get only open or closed issues
 - `author` (FeedRef): get only issues from the given feed
 - `live` (boolean, default: `false`): Keep the stream open and emit new messages as they are received.
 - `gt` (greater than), `gte` (greater than or equal): maximum `[timestamp, id]`
 - `lt` (less than), `lte` (less than or equal): minimum `[timestamp, id]`
 - `reverse` (boolean, default: `false`): reverse the order of results

#### new: async

Create a new issue

```js
issues.new({ project:, title:, text: }, cb)
```

- `project` (Ref): id of an ssb object representing the target of the issue
- `title` (string): title of the issue (deprecated)
- `text` (string): text describing the issue

#### close: async

```js
issues.close(id, cb)
```

Mark an issue as closed.

`id` (MsgRef): id of the issue to reopen

#### reopen: async

```js
issues.reopen(id, cb)`
```

Mark an issue as open.

`id` (MsgRef): id of the issue to reopen
`text` (string): text to accompany the open action

#### edit: async

```js
issues.edit(id, opts, cb)`
```

Edit an issue.

`id` (MsgRef): id of the issue to reopen
`opts.open` (boolean): set open/closed status
`opts.title` (string): set title (deprecated)

#### isStatusChanged: sync

```js
var open = issueSchemas.isStatusChanged(issue, msg)
```

Check if a message changes an issue's status

- `msg` (Msg in metadata): message to check
- `issue` (Issue): issue to check for update
- `open` (boolean?): whether the message updates the issue to be open (true)
  closed (false), or does not affect it (null)

#### getMention: sync

```js
var mention = issueSchemas.getMention(issue, msg)
```

Get a mention of an issue in a message, if any

- `msg` (Msg in metadata): message to check
- `issue` (Issue): issue to check for update
- `mention` (object?): mention object, with properties like
  - `mention.open` (boolean?): whether the issue is updated to be open (true),
    closed (false), or not (null)

#### deinit: async

Deinit the issues object. Closes all live streams. Since `issues` uses live
streams, you should call `deinit` when you are done with the issues and want
your program to exit or free up resources.

```js
pulls.deinit(cb)
```

### schemas

```js
var issueSchemas = Issues.schemas
```

#### `issueSchemas.new(project, title, text)`

Create a new issue.

- `project` (Ref): id of project to associate the issue with
- `title` (string): title to give the issue (deprecated)
- `text` (string): text body for the issue

#### `issueSchemas.newLabel(project, name, issues)`

Create a new issue label.

- `project` (Ref): id of project to associate the issue/label with
- `name` (string): name to give the issue (optional)
- `issues` (IssueRefs): ids of issues to add the label to

#### `issueSchemas.edit(id, opts)`

Edit an issue.

- `opts.open` (boolean): open or close the issue
- `opts.title` (string): set the title of the issue (deprecated)
- `opts.addLabels` (LabelRefs): ids of labels to add to issue
- `opts.removeLabels` (LabelRefs): ids of labels to remove from issue

#### `issueSchemas.close(id)`

Close an issue.

- `id` (MsgRef): id of an issue to mark as closed

#### `issueSchemas.reopen(id)`

Reopen an issue.

- `id` (MsgRef): id of an issue to mark as open

#### `issueSchemas.closes(msg, id)`

Mutate a message to make it close an issue

- `msg` (Msg): message object to update
- `id` (MsgRef): id of an issue to mark as closed

#### `issueSchemas.reopens(msg, id)`

Mutate a message to make it reopen an issue

- `msg` (Msg): message object to update
- `id` (MsgRef): id of an issue to mark as open

## License

Copyright (c) 2016, 2020 Charles Lehner

Usage of the works is permitted provided that this instrument is
retained with the works, so that any entity that uses the works is
notified of this instrument.

DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.