Request for developer feedback: contacts data-module

Build a Solid App Developer Experience
1

tl:dr: There is a new library to manage :card_index: address books & contacts in Solid Pods. Please try it and give feedback. :woman_technologist:

Hi all,

as part of the solid-data-modules initiative I have built a library that is meant to make it easier for developers to handle address books and contacts in Solid Pods.

  • find address books in a Pod
  • create and read address books
  • create, read and update contacts
  • organize contacts into groups
  • ā€¦

You can do all this through a simple interface, without having to struggle with the details of the (yet to be) contacts client-to-client specification.

The library is interoperable with the address books from SolidOS.

What you can do with the library :bulb:

  • Build your own solid contacts manager app
  • Easily integrate contacts to whatever app your are building, while focussing on the actual domain of your app

Quick start :rocket:

The library currently comes in the ā€œflavorā€ of rdflib, but you do not need to know anything about rdflib to use it.

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

import {Fetcher, graph, UpdateManager} from "rdflib";
import ContactsModuleRdfLib, { ContactsModule } from "@solid-data-module/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 contacts.createAddressBook({
  container: "https://pod.example/alice/",
  name: "new address book"
})

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

const addressBook = await contacts.readAddressBook(uri)
console.log(addressBook)

:speech_balloon: Request for Feedback :heart:

Any feedback is very welcome, even if you do not plan to use the library:

  • What features are you missing?
  • What is confusing?
  • What is valuable?
  • What needs to be added for your use cases?
  • ā€¦

Links

3 Likes
2

Great, trying it out now! Learning curve for me:

2 Likes
3

I think this line of work is awesome, and I hope to see a lot more of this in Solid :D. Good job!

Iā€™ve tinkered with the snippet for a bit, and hereā€™s my first impressions:

  • I like the TypeScript typings, they are helpful and quite easy to follow without looking at the docs. There were some syntax errors (Iā€™ll share them below), but I was able to fix them without much trouble.
  • Calling createAddressBook worked properly, but it doesnā€™t seem like it did anything with the type index. Should I do something to register it? I was expecting it to be done out of the box. Basically, I created an address book and then calling listAddressBooks returned empty arrays, so after reloading I wasnā€™t able to obtain the uri of the bookmark I had created (it was also unintuitive that it asked for a webId when I hadnā€™t provided one to create an address book).
  • I noticed itā€™s always creating documents and containers using a random string. For example I passed /contacts/ to create an address book and it created it under /contacts/QBLL34/. Is there a way to specify the exact container name? And maybe get an error if it already existed or something.
  • Finally, if I were to implement a real app, Iā€™m sure Iā€™d want to add some fields that arenā€™t covered by the library. Do you have any plans for extending the core fields? For example, if I wanted to add the birthday for a contact, how hard would it be to make it work nicely with the library?

PS: Hereā€™s the syntax errors I found in the snippet:

  • The second import is missing the s from @solid-data-modules/contacts-rdflib.
  • The contacts variable doesnā€™t exist (I suppose it should be module instead).
  • The createAddressBook method takes containerUri, not container.
  • The createNewContact method takes contact.phoneNumber, not contact.phone.
2 Likes
4

Thanks a lot for your feedback @michielbdejong

Great that you could resolve it yourself and thanks for the compliment. What do you think would have been needed to not run into the issue at all? I tried to improve the docs in that regard here

:+1:

I adjusted the peer dependencies, this should be fixed with the next release

5

Thank you very much!

I am going to fix those good catch. The markdown did not get the latest changes.

This is a tricky one. I am still unsure what user expectations are: Should everything be indexed by default? Should they be asked? How to decide what goes into private and what into public index? I took a look at how SolidOS handles this for address books, and it does not add anything to the type index unless you check one of those ā€œpublic link toā€ / ā€œprivate link toā€ boxes:

SolidOS type index check boxes for address book

This is why I did not implement it either. There might be reasons to want to create an address book, but not index it. Another reason is that one would need to pass a WebID when creating an address book. That seemd unintuitive to me.

But: I totally get the confusion this creates regarding listAddressBooks. This actually needs the WebID to find the type indexes, so it would be ā€œsymetricā€ to pass a WebID to create as well as to list.

I am thinking about changing the interface and put new address books to the private type index by default. Other options like adding it to the public type index or prevent all indexing could be added optionally. What do you think?

I wanted to keep it simple. You already pass a human readable title for the address book. I thought it might be confusing to differ between container name and address book name. I thought about slugifying the title, but this brings other issues, like title and slug diverging when changing the title or accidentally expose a sensitive address book title via the URI. If this is important to you anyway, please raise a feature request on github. It could still be added as an option.

Contact related fields like birthday should definetly be added to the data-module as a first-class citizen in the long run. For now and for more complex or unrelated properties / statements, you can still use rdflib directly. As a consumer of the library you have to create a store / updater / fetcher anyway. The module makes common address book related things easier, but does not take control away from your rdflib usage.

6

I think itā€™s ok that address books are not listed on the type indexes by default, but I guess Iā€™d improve two things:

  • In the docs and code examples, make sure to mention the type index and how things can be registered using the library. Otherwise, people may not event be aware that those exist.
  • If an address book is not registered, Iā€™m not sure how I can retrieve it after reloading. Hard-coding the url doesnā€™t work, so I guess I should list all the documents in a container and filter the documents containing address books myself? I would also clarify this use case in the docs.
7

The thing is, that the data module does not have any means to add things to a type index. And I donā€™t want to add those since type index is not specific to address books. Currently I am thinking it would be best to implicitly add it to the private type index when an optional owner WebID is passed on create.

You will get the uri as the response to create. An app could store It anywhere it likes, e.g. in local storage write it to some document in a pod. But I see how this burdens the developer which is the opposite of what a data module should do. Which brings me back to the approach of choosing a reasonable default and add it to the private type index.

1 Like