2.1.0 • Public • Published


    An ssb-server plugin for creating, reading, updating relationships between profiles

    Example Usage

    const Server = require('ssb-server')
    const Config = require('ssb-config/inject')
    const config = Config({})
    const server = Server
      .use(require('ssb-whakapapa')) // <<<<<<
      .call(null, config)
    const details = {
      child: '%P5r79KsntEGPMp0Zd24bvfDBMtfx1SADMEE7yxBdVVw=.sha256',
      parent: '%4BmROhXcW6H4VyATrIj7uOWqHyW5q5jFZpDHo5RofSc=.sha256',
    const opts = {
      relationshipType: { set: 'birth' },
      recps: [
    server.whakapapa.child.create(details, opts, (err, linkId) => {
      // ...
    // later:
    server.whakapapa.get('%P5r79KsntEGPMp0Zd24bvfDBMtfx1SADMEE7yxBdVVw=.sha256', (err, data) => {
      // => {
      //   id: '%P5r79KsntEGPMp0Zd24bvfDBMtfx1SADMEE7yxBdVVw=.sha256',
      //   parentLinks: [
      //     {
      //       id: '%4BmROhXcW6H4VyATrIj7uOWqHyW5q5jFZpDHo5RofSc=.sha256',
      //       linkId: '%W5q4BmROhXcW6H4VyATrIj7uOWqHy5jFZpDHo5RofSc=.sha256',
      //       relationshipType: 'birth',
      //       legallyAdopted: null // null means it hasnt been set
      //       tombstone: null
      //     }
      //   ],
      //   childLinks: []
      // }






    Get children and parents of a particular profile.

    server.whakapapa.get(ProfileId, cb)

    • ProfileId String - the id for a profile
    • cb Function - a callback of signature (err, data)

    data format

      parentLinks: [
          id: '%4BmROhXcW6H4VyATrIj7uOWqHyW5q5jFZpDHo5RofSc=.sha256',
          linkId: '%47uOWqHyW5q5jFZpDHo5RofBmROhXcW6H4VyATrIjSc=.sha256',
          relationshipType: 'birth',
          legallyAdopted: null,
          tombstone: null
          id: '%r86qOq2KNY3GlifR6UgQaB05ZfXmHlnxxoFlyi9OI0A=.sha256'
          linkId: '%W5q5j47uOWqHyFZpDHo5RofBmROhXcW6H4VyATrIjSc=.sha256',
          relationshipType: null, // this means relationshipType hasnt been set
          legallyAdopted: null,
          tombstone: {
      childLinks: [
          id: '%pCt2QB3ZxZEsKIYvxGI9QBmytrUNZfuuRbNk8i0V7ug=.sha256',
          linkId: '%yFZpDHo5RoW5q5j47uOWqHfBmROhXcW6H4VyATrIjSc=.sha256',
          relationshipType: 'whangai',
          legallyAdopted: false,
          tombstone: null


    Creates a new updateable message of type whakapapa/child connecting two profiles - a parent and a child.

    server.whakapapa.child.create({ child, parent }, opts, cb)

    • child String a scuttlebutt MessageId pointing to a profile root
    • parent String a scuttlebutt MessageId pointing to a profile root
    • opts Object - describes the values to set on that relationship and who can read it.
    • cb Function - a callback of signature (err, linkId) where linkId is the id of the relationship which has just been created

    opts format

      relationshipType: { set: ParentType }, // optional
      legallyAdopted: { set: Boolean }       // optional
      tombstone: { set: TombStone }          // optional
      recps: [ FeedId ]                      // optional
    • MessageId is scuttlebutt message cypherlink e.g. %4BmROhXcW6H4VyATrIj7uOWqHyW5q5jFZpDHo5RofSc=.sha256
    • ParentType is any of 'birth' | 'adopted' | 'whangai' | 'unknown'
    • legallyAdopted should only be set if relationshipType is 'adopted' or 'whangai'
    • Tombstone is an Object of form { date: UnixTime, reason: String } and marks a link as deleted.
    • recps is an Array of FeedId (e.g. '@ye+QM09iPcDJD6YvQYjoQc7sLF/IFhmNbEqgdzQo3lQ=.ed25519'). If this is provided this relationship will automatically be encrypted so only the mentioned parties will be able to see this. (NOTE - you cannot change this later)


    • If you don't want to add any optional opts, set opts to null or {}
    • this is now a wrapper over

    🚧 TODO

    • add GroupId to recps once we have private-groups released
    • add some way to validate whakapapa links
      • e.g. an approval system so that kaitiaki (custodians) at each end of the relationship can approve the link?
      • need to make sure that can't change pointer for child / parent after an "approval" of link


    This updates a child relationship (not the child themself).

    server.whakapapa.child.update(linkId, opts, cb)

    • linkId MessageId - the root key of the relationship
    • opts Object - same as in child.create, except recps is set for you based on what the first message was.
    • cb function - callback with signature (err)

    🚧 TODO

    • needed for tombstoning


    Fetch a "view" of whakapapa - this is a minimal record which stores the sdetails needed to construct a particular perspective on a graph of relationships.

    e.g. we might want to see all the descendants of a particular ancestor. To do this we store the profileId of that ancestor and the mode of drawing (down!). We might also include preferences about whether to include whangai or adopted descendants for example.

    server.whakapapa.view.get(viewId, cb)

    • viewId MessageId - the id of the root message of a view
    • cb function - a callback of signature (err, data), where data is an Object with properties:
      • name String - the name of this whakapapa view
      • description String - the name of this whakapapa view
      • ignoredProfiles Array - an array of ProfileIds which have been marked to ignore (don't render these please). Returns [] if there are none.
      • focus ProfileId - the id of the profile we start from
      • mode String - the way to draw the graph. (can be 'descendants' | 'ancestors')
      • tombstone Object - date and reason

    If any of these are not set, these properties will still be present, but the values will be null


    Creates a new message of type whakapapa/view

    server.whakapapa.view.create(details, cb)

    • details Object - contains information to start off view
    • cb function - a form (err, viewId)

    The expected form of details is :

      name: { set: String },
      description: { set: String },           // optional
      image: { set: Image },                  // optional
      focus: { set: ProfileId }, 
      mode: { set: Mode },
      tombstone: { set: Tombstone }           // optional
      ignoredProfiles: { add: [ProfileId] },  // optional
      recps: [ FeedId, ... ],                 // optional


    • Mode can be 'descendants' | 'ancestors'
    • Image is an Object of form { blob: '&07xxrn0wWbtRx/gp4IF7THPeWZUT1LWt93IVHTbitFE=.sha256', mimeType: 'image/png' }
    • recps is a special field which encrypts the view (and all subsequent updates) to a specified set of FeedIds
    • Tombstone is an Object of form { reason: String, date: UnixTime }


    server.whakapapa.view.update(viewId, details, cb)

    • viewId MessageId - the id of the view to update
    • details Object - same as in view.create, except
      • ignoredProfiles can also be { ignoredProfiles: { remove: [ProfileId] } } for updates
      • recps is inherrited from the create message (root), so setting it here does nothing.
    • cb function - callback with signature (err){ type, parent, child }, details, cb)

    • type String - the sort of link you want to make. This will become the message type. e.g. link/story-person
      • currently supports:
        • link/profile-profile/child
        • link/profile-profile/partner
        • link/story-*
    • parent MessageId - the id of the "parent" end the link
    • child MessageId - the id of the "child" end of the link
    • details Object - a collection of initial transformations for the link. Useful for storing meta-data, and declaring recps (private recipients). The valid form of this depends on the type
      • ⚠️ TODO - add detail here
    • cb, type, cb)

    • id MessageId - the id of the thing you're inspecting for links
    • type String - the "type" of links you want to surface (e.g link/story-artefact)
    • cb, details, cb)

    • id MessageId - the id of the thing you're inspecting for links
    • details Object - same as #create method details (except you can't change recps here)
    • cb


    npm i ssb-whakapapa

    DownloadsWeekly Downloads






    Unpacked Size

    62.6 kB

    Total Files


    Last publish


    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar