synced/tinode-chat
1
0
Fork 0
mirror of https://github.com/tinode/chat.git synced 2025-03-15 09:58:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

add reference to theCard

Browse Source
This commit is contained in:
or-else
2021-05-10 16:35:00 -07:00
parent 33c742c038
commit ca59e6b49d
3 changed files with 74 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/API.md
View File

@ -444,44 +444,8 @@ An empty `ua=""` _user agent_ is not reported. I.e. if user attaches to `me` wit
Topics and subscriptions have `public` and `private` fields. Generally, the fields are application-defined. The server does not enforce any particular structure of these fields except for `fnd` topic. At the same time, client software should use the same format for interoperability reasons.
### Public
The format of the `public` field in group and peer to peer topics is expected to be a [vCard](https://en.wikipedia.org/wiki/VCard) although only `fn` and `photo` fields are currently used by client software:
```js
vcard: {
fn: "John Doe", // string, formatted name
n: {
surname: "Miner", // last of family name
given: "Coal", // first or given name
additional: "Diamond", // additional name, such as middle name or patronymic or nickname.
prefix: "Dr.", // prefix, such as honorary title or gender designation.
suffix: "Jr.", // suffix, such as 'Jr' or 'II'
}, // object, user's structured name
org: "Most Evil Corp", // string, name of the organisation the user belongs to.
title: "CEO", // string, job title
tel: [
{
type: "HOME", // string, optional designation
uri: "tel:+17025551234" // string, phone number
}, ...
], // array of objects, list of phone numbers associated with the user
email: [
{
type: "WORK", // string, optional designation
uri: "email:alice@example.com", // string, email address
}, ...
], // array of objects, list of user's email addresses
impp: [
{
type: "OTHER",
uri: "tinode:usrRkDVe0PYDOo", // string, email address
}, ...
], // array of objects, list of user's IM handles
photo: {
type: "jpeg", // image type
data: "..." // base64-encoded binary image data
} // object, avatar photo. Java does not have a useful bitmap class, so keeping it as bits here.
}
```
The format of the `public` field in group and peer to peer topics is expected to be [theCard](./thecard.md) although only `fn` and `photo` fields are currently used by client software.
The `fnd` topic expects `public` to be a string representing a [search query](#query-language)).

6
docs/drafty.md
View File

@ -211,14 +211,14 @@ Hashtag `data` contains a single `val` field with the hashtag value which the cl
"name": "confirmation",
"act": "url",
"val": "some-value",
"ref": "https://www.example.com/"
"ref": "https://www.example.com/path/?foo=bar"
}
}
```
* `act`: type of action in response to button click:
* `pub`: send a Drafty-formatted `{pub}` message to the current topic with the form data as an attachment:
```js
{ "tp":"EX", "data":{ "mime":"application/json", "val": { "seq": 3, "resp":{ "confirmation": "some-value" } } } }
{ "tp":"EX", "data":{ "mime":"application/json", "val": { "seq": 3, "resp": { "confirmation": "some-value" } } } }
```
* `url`: issue an `HTTP GET` request to the URL from the `data.ref` field. The following query parameters are appended to the URL: `<name>=<val>`, `uid=<current-user-ID>`, `topic=<topic name>`, `seq=<message sequence ID>`.
* `note`: send a `{note}` message to the current topic with `what` set to `data`.
@ -231,6 +231,6 @@ Hashtag `data` contains a single `val` field with the hashtag value which the cl
If the `name` is provided but `val` is not, `val` is assumed to be `1`. If `name` is undefined then nether `name` nor `val` are sent.
The button in the example above will send an HTTP GET to https://www.example.com/?confirmation=some-value&uid=usrFsk73jYRR&topic=grpnG99YhENiQU&seq=3 assuming the current user ID is `usrFsk73jYRR`, the topic is `grpnG99YhENiQU`, and the sequence ID of message with the button is `3`.
The button in the example above will send an HTTP GET to https://www.example.com/path/?foo=bar&confirmation=some-value&uid=usrFsk73jYRR&topic=grpnG99YhENiQU&seq=3 assuming the current user ID is `usrFsk73jYRR`, the topic is `grpnG99YhENiQU`, and the sequence ID of message with the button is `3`.
_IMPORTANT Security Consideration_: the client should restrict URL scheme in the `url` field to `http` and `https` only.

70
docs/thecard.md Normal file
View File

@ -0,0 +1,70 @@
# theCard: Person/Topic Description Format
Tinode uses `theCard` to store and transmit descriptions of people and topics.
_The format used to be called `vCard`, the same as [vCard](https://en.wikipedia.org/wiki/VCard) while being incompatible. That caused some confusion and prompted renaming the format to `theCard`. There are references to `vcard` and `vCard` troughout the code and documentation. It should be assumed that in all those cases it's meant to be `theCard` unless explicitly stated otherwise._
When `JSON` is used to represent `theCard` data, it does it differently than [jCard](https://tools.ietf.org/html/rfc7095). `theCard` and `jCard` are incompatible. The main difference is that `theCard` uses objects to represent logically related data while `jCard` uses ordered arrays.
`theCard` is structured as an object:
```js
vcard: {
fn: "John Doe", // string, formatted name of the person or topic.
photo: { // object, avatar photo; either 'data' or 'ref' must be present, all other fields are optional.
type: "jpeg", // MIME type but with 'image/' dropped.
data: "Rt53jUU...iVBORw0KGgoA==", // base64-encoded binary image data
ref: "https://api.tinode.co/file/s/abcdef12345.jpg", // URL of the image.
width: 512, // integer, image width in pixels.
height: 512, // integer, image height in pixels.
size: 123456 // image size in bytes.
},
//
// None of the following fields are implemented by any known client:
//
n: { // object, person's structured name.
surname: "Miner", // surname or last or family name.
given: "Coal", // first or given name.
additional: "Diamond", // additional name, such as middle name or patronymic.
prefix: "Dr.", // prefix, such as honorary title or gender designation.
suffix: "Jr.", // suffix, such as 'Jr' or 'II'.
},
org: { // object, organisation the person or topic belongs to.
fn: "Most Evil Corp", // string, formatted name of the organisation.
title: "CEO", // string, person's job title at the organisation.
},
tel: [ // array of objects, list of phone numbers associated with the person or topic.
{
type: "HOME", // string, contact designation.
uri: "tel:+17025551234" // string, phone number as URI.
}, ...
],
email: [ // array of objects, list of person's email addresses
{
type: "WORK", // string, optional designation
uri: "email:alice@example.com", // string, email address
}, ...
],
comm: [ // array of objects, list of person's other contact/communication options.
{
type: "WORK",
name: "Tinode",
uri: "tn:usrRkDVe0PYDOo", // string, URI specific to the contact type.
},
{
type: "OTHER",
name: "Website",
uri: "https://tinode.co", // string, URI specific to the contact type.
}, ...
],
bday: { // object, person's birthday.
y: 1970, // integer, year
m: 1, // integer, month 1..12
d: 15 // integer, day 1..31
},
note: "Some notes", // string, notes about the person or topic.
}
```
All fields are optional. Tinode clients currently use only `fn` and `photo` fields. If other fields are needed in the future,
then they will be adopted from the correspondent vCard fields.