Contacts - Solid Data Module

A data module to manage address books and contacts in Solid Pods in an interoperable way.

Specification

• Client-to-Client specification for contacts.
• Description of SolidOS de-facto standard.

Usage

Installation via npm

npm install rdflib @solid-data-modules/contacts-rdflib
Copy

Usage in the brower via CDN

You can use the module directly in the browser (without any install or build step) by using the esm.sh CDN and an import map:

<script type="importmap">
  {
    "imports": {
      "@solid-data-modules/contacts-rdflib": "https://esm.sh/@solid-data-modules/contacts-rdflib",
      "rdflib": "https://esm.sh/rdflib"
    }
  }
</script>
<script type="module">
  import ContactsModuleRdfLib from "@solid-data-modules/contacts-rdflib";
  import { Fetcher, graph, UpdateManager } from "rdflib";
  // ... use the module as described in the quick start
</script>
Copy

Quick start

import {Fetcher, graph, UpdateManager} from "rdflib";
import ContactsModuleRdfLib, { ContactsModule } from "@solid-data-modules/contacts-rdflib";

// 1️⃣ create rdflib store, fetcher and updater as usual
const store = graph();
const fetcher = new Fetcher(
        store,
        // 💡 pass an authenticated fetch
        // to be able to access private resources*
        /* fetch: authenticatedFetch */
);
const updater = new UpdateManager(store);

// 2️⃣ create the contacts module
const module: ContactsModule = new ContactsModuleRdfLib({store, fetcher, updater});

// 3️⃣ use the module to interact with address books and contacts
const uri = await module.createAddressBook({
  containerUri: "https://pod.example/alice/",
  name: "new address book"
})

const contactUri = await module.createNewContact({
  addressBookUri: uri,
  contact: {
      name: "Maurice Moss",
      email: "maurice.moss@reynholm-industries.example",
      phoneNumber: "0118-999-881-99-9119-725-3"
  },
});

const addressBook = await module.readAddressBook(uri)
console.log(addressBook)
Copy

Example scripts

Executable example scripts how to use the module can be found in ./examples folder.

The development server needs to be running and initialized for this.

After that you can run an example script like this:

npm run build
node ./examples/read-address-book.mjs
Copy

Available features

For a description of all features available please take a look at the module API documentation.

Development

Run tests

Unit and integration tests

npm test
Copy

End-to-end tests

The tests will start and stop their own solid server on port 3456. This port needs to be available.

npm run test:e2e
Copy

The server is seeded with data from src/e2e-tests/test-data initially. After a test run you can investigate the pod file system at src/e2e-tests/.test-data/<test-id> where <test-id> is a random id generated for each run.

Build

npm run build
Copy

Development server

Start server

You can start a development solid server via:

npm run pod
Copy

This will seed an account and an empty pod for test user alice. Find the credentials of that account in ./dev-server/seed.json

Initialize example data

To add some example data to this pod run

npm run pod:init
Copy

To start from scratch run

npm run pod:clean
Copy

and repeat from start of the section.

Funding

This project is funded through NGI0 Entrust, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.