join or create message?

[jonasfj]

Looking at the clientside API, it's really hard to:

• see why you a join failed not allowde, internal error, or document doesn't exist
• It's also impossible to create a document with a specific id

I propose we add a method to join-or-create a document with a given id.

[jonasfj]

Idealy, we should perhaps just have one message:

{
  command: 'join',
  documentId: '...',
  createIfNotExists: true || false,
  token: '...',
  userId: '...'
}

With a response:

{
  responseType: 'document',
  error: "" || null,
  version: 1,
  document: {documentId: '...', content: '...'},
  readOnly: true || false
}

So you call with command: join and tell if the document should be created, if it doesn't exist.
And you get a responseType: document, if you are allowed read/write access you get that, if you're only allowed read-only access, that is all you get.

Otherwise clients have to know if they are allowed to join a document readonly or read/write... And this complicates things, especially since there aren't any formal error codes to rely on.

We could add a property acceptReadOnly: true || false to the request, so clients can indicate that they aren't interested in joining readonly, even if that is the only access they can get.

[Jeffail]

This seems reasonable. I'm marking this as a bug since confusing APIs aren't an intended feature! The internal workings of leaps have changed significantly since the client API was first slapped together so it might be worth completely reworking them, possibly with respect to some of the other issues you've raised (like user IDs vs auth tokens etc).

[Jeffail]

This should probably be tackled after #8 is resolved.