Ssb-submissions NPM

ssb-submissions

An ssb-server plugin for creating, reading and updating submissions in scuttlebutt

Modules

ssb-submissions

Submissions

A submission is a request for another record to be created, updated, or tombstoned, that is stored using ssb.

   A   (the root message)
   |
   B   (approveing or rejecting the proposal A)
  / \
 C   D (two concurrent approves/rejects after B)

Because there might be multiple offline approves/rejects to a submission which didn't know about one-another, it's possible for divergence to happen: C and D wont know about each other.

A submission is an Object which maps the key of each latest edit to the state it perceives the submission to be in:

// submission for the example above
{
  key: MessageId, // submissionId supplied, the root message of the submission
  states: [
    { head: C, state: stateC },
    { head: D, state: stateD },
  ]
}

and the state is an Object which looks like the following:

{
  // static fields
  sourceId: msgId,
  targetType: String,
  details: Object,
  source: RecordSource,

  //
  targetId: msgId,
  approvedBy: SimpleSet of feedIds,
  rejectedBy: SimpleSet of feedIds,
  comments: OverWriteFields of feedIds: String
}

where:

sourceId - is the original record e.g. profileId, the submission proposal is about. E.g. if we are proposing to edit a profile, the sourceId would be the profile we are updating. If we are proposing a new profile, the sourceId is always empty.
targetId - is the "result" record after a submission has been executed. E.g. if we have proposed and executed a submission for a new profile, the targetId is the profileId of the new profile that was created. If we have proposed and executed a submission for an edit to a profile, the targetId is the msgId (profileId) of the update message to that profile.
targetType - is the type of record we are proposing, and the type of record we will get in the result of targetId after we execute the proposal.
details - is the proposed fields we wish to include in the type of record we are creating or updating. E.g. If we are proposing a new profile, the details will be fields accepted on the record type profile/person.
source RecordSource (ahau|webForm) tells us where a record, in this case a submission, came from. E.g. ahau - a record was made in ahau, webForm a record was made from a web registration form

API

`server.submissions.registerHandler(crut)`

In order to check that the proposals are valid, begin by registering a crut that contains:

spec.type String - the type of the target record TODO:
isValid Function - allows you to check the validity of the proposal.

Important: currently uses an extended CRUT, by adding ...crut to the Methods of the desired record. Example use case:

  server.submissions.registerHandler(server.profile.person.public)

`server.submissions.findHandler(content) => crut`

`server.submissions.proposeNew(recordTypeContent, recordDetails, submissionDetails, cb)`

Creates a new submission record and describes details you'd like to have on a new type of record

recordTypeContent Object - content for the type of record you would like to create
- e.g. for a profile/person record:
```
recordTypeContent = {
  type: 'profile/person'
}
```
recordDetails Object - allows you to propose fields for new record.
- e.g. for a profile/person record:
```
// for profile/person
{
  preferredName: 'Colin'
}
```
NOTE: the fields will be validated against the spec for that type of record using the recordTypeContent
submissionDetails Object - additional details you can add to the submission
- comment String - allows you to add an optional comment to the submission.
- source RecordSource (ahau|webForm) - specify where the submission is being created, e.g. from ahau or from a web registration form webForm
- moreInfo Object - specify additional information to be saved to the submission.
```
{
  [key]: [
    {
      label: String,
      value: String
    }
  ]
}
```
  NOTE: This is currently the only format that is supported. If more formats are needed, they can be added
- recps String - Who is allowed to see this submission. The new record may have different recps. // TODO: Submissions should only be seen by kaitiaki group
cb Function - a callback with signature (err, submissionId)

`server.submissions.proposeEdit(recordId, recordDetails, submissionDetails, cb)`

Creates a new submission record and describes details you'd like to have updated on an existing record

recordId String - the cypherlink for the target record (the msgId of the root message for the record)
recordDetails Object - allows you to propose fields for new record.
- e.g. for a profile/person record:
```
// for profile/person
{
  preferredName: 'Colin'
}
```
NOTE: the fields will be validated against the spec for that type of record that recordId points to
submissionDetails Object - additional details you can add to the submission
- comment String - allows you to add an optional comment to the submission.
- recps String - Who is allowed to see this submission. The target record may have different recps. // TODO: Submissions should only be seen by kaitiaki group
cb Function - a callback with signature (err, submissionId)

`server.submissions.proposeTombstone(recordId, submissionDetails, cb)`

Creates a new submission record about which existing record you want tombstoned

recordId String - the cypherlink for the target record (the msgId of the root message for the record)
submissionDetails Object - additional details you can add to the submission
- comment { String } - allows you to add an optional comment to the submission.
cb Function - a callback with signature (err, submissionId)

`server.submissions.approve(submissionId, submissionDetails, cb)`

Updates a submission record by setting server.id to approvedBy and adding the comment

submissionId String - the cypherlink for the target submission (the msgId of the root message for the submission)
submissionDetails Object - additional details you can add to the submission
- targetId String - specify the ID of a message. E.g. the message that was saved upon approval.
- comment String - allows you to add an optional comment to the submission.
cb Function - a callback with signature (err, submissionId)

`server.submissions.executeAndApprove(submissionId, approvedRecordDetails, submissionDetails, cb)`

Handles executing a proposal by either creating or updating the record, with the fields passed in to approvedRecordDetails. It then calls the approve method.

submissionId String - the cypherlink for the target submission (the msgId of the root message for the submission)
approvedRecordDetails Object - similar to recordDetails in the propose methods, but it only holds fields and values that have been approved. These will be saved to the record being created or updated.
submissionDetails Object - additional details you can add to the submission
- comment String - allows you to add an optional comment to the submission.
cb Function - a callback with signature (err, submissionId)

`server.submissions.reject(submissionId, { comment }, cb)`

Updates a submission record by setting server.id to rejectedBy and adding the comment

submissionId String - the cypherlink for the target submission (the msgId of the root message for the submission)
comment { String } - allows you to add an optional comment to the submission.
cb Function - a callback with signature (err, submissionId)

`server.submissions.get(submissionId, cb)`

Retrieves the submission record.

submissionId String - the cypherlink for the target submission (the msgId of the root message for the submission)
cb Function - a callback with signature (err, data)

`server.submissions.tombstone(submissionId, { reason, allowPublic, undo }, cb)`

Tombstones the submission record.

submissionId String - the cypherlink for the target submission (the msgId of the root message for the submission)
cb Function - a callback with signature (err, root)