SDK

Участники

`members.list`, `get`, `add`, `update`, `remove`, `grantAddress` и `revokeAddress`.

Все методы

members.ts

const people = await openemail.members.list()const member = await openemail.members.get(people[0]!.userId) const sam = await openemail.members.add({  email: '[email protected]',  roleId: support.id,  addressIds: ['2b81de07-…'],  access: 'member',}) await openemail.members.update(sam.userId, { roleId: viewerRoleId }) await openemail.members.grantAddress(sam.userId, {  addressId: 'c40a95f2-…',  access: 'viewer',})await openemail.members.revokeAddress(sam.userId, 'c40a95f2-…') await openemail.members.remove(sam.userId)

На человека приходится два разрешения, и сливать их нельзя. role — это что ему можно делать, addresses — с чем именно. Оба должны совпадать: роль с emails:send и access: "viewer" на invoices@ — это человек, который может отправлять почту и не может отправлять её с этого адреса.

Все методы принимают userId, а не адрес. Единственное исключение — add, и в нём же причина исключения: у вызывающего есть адрес и пока нет идентификатора пользователя, а это и есть вся первая половина того, что делает этот вызов.

implied: true означает, что роль никто не выбирал. У человека есть адреса и нет строки роли, поэтому роль выведена из самого широкого имеющегося разрешения. Считайте это «ещё не решено»; превращает вывод в решение update. До тех пор расширение его доступа к адресам молча расширяет и то, что ему можно делать.

Владелец рабочего пространства — первая строка, помеченная isOwner: true, при этом add, update и remove всё равно отказывают по нему с member_is_owner. Рабочее пространство, которым ни с кем не поделились, сообщает об одном участнике, а не о нуле, поэтому при подсчёте мест исключайте isOwner.

remove забирает обе оси — и роль, И все выдачи адресов в этом рабочем пространстве — и сообщает addressesRevoked. revokeAddress — узкий вариант, для того, кто сменил команду, а не ушёл.

Параметры

emailstringобязательно: Кого пригласить — с обрезкой пробелов и приведением к нижнему регистру. Аккаунт пока не нужен: приглашение уходит кому угодно, а роль и выдачи применяются, когда человек его примет. Тот, кто уже в рабочем пространстве, даёт `member_is_owner` (422).
roleIdstringобязательно: Роль, которую он получит, от 1 до 128 символов, и это должна быть роль этого рабочего пространства: неизвестный идентификатор даёт `role_not_found` (404). Роль владельца выдать нельзя, она возвращает `role_immutable` (409), потому что сделать кого-то владельцем — это передача рабочего пространства, а такого вызова здесь нет.
addressIdsstring[]: Адреса, передаваемые тем же вызовом: не более 64 идентификаторов длиной от 1 до 128 символов каждый; идентификатор, не являющийся адресом этого рабочего пространства, отклоняется. Сначала записывается роль, затем выдачи по одной, поэтому неверный идентификатор оставит созданного участника с меньшим числом адресов, чем вы просили. Лечится повторной отправкой того же тела, поскольку обе записи выполняются как upsert.
access'member' | 'viewer': Что ему можно делать с каждым идентификатором из `addressIds`: `member` читает адрес и отправляет от его имени, `viewer` только читает. По умолчанию `member` — уровень, который всегда использовали консоль и прежний механизм общего доступа, поэтому один и тот же вызов означает одно и то же из скрипта и с экрана; чтобы выдать разные уровни, вызовите затем `grantAddress` для тех, что отличаются.

Ответ

object'member': Всегда `member`. Удаление отвечает тем же значением, его `userId`, `deleted: true` и `addressesRevoked` — и ни одним из остальных полей ниже.
userIdstring: Идентификатор его аккаунта и тот ключ, который все прочие вызовы участников принимают в пути: get, update, remove и оба вызова по адресам. Добавление — единственный вызов, работающий вместо этого по адресу, потому что тот, кто добавляет коллегу, знает его адрес, а не идентификатор.
emailstring: Адрес на его аккаунте, возвращаемый в том виде, в каком его хранит та строка. Этот ресурс его никогда не записывает, а приведение к нижнему регистру в `add` касается адреса, который вы отправляете для поиска, а не того, что приходит обратно. После владельца список участников отсортирован по нему, а не по дате присоединения, потому что список читают, чтобы найти конкретного человека, а не чтобы увидеть, что изменилось.
namestring | null: Его отображаемое имя, взятое из аккаунта, где колонка объявлена NOT NULL. Null в типе — это подстраховка, а не состояние, которое этот API когда-либо выдавал. Имя принадлежит человеку, а не рабочему пространству, поэтому ничто в этом ресурсе не может его задать.
imagestring | null: Его аватар, взятый из аккаунта; null, если он его не задал.
role.idstring | null: Идентификатор роли, которой он обладает, или null, если её никто не выбирал. См. `implied`. Null здесь — единственный случай, когда `role` сообщает вывод, а не чьё-то решение.
role.namestring: Имя роли. У подразумеваемого участника это имя встроенного шаблона, к которому свёлся его доступ, а не строки в этом рабочем пространстве.
role.builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null: Какой встроенной роли соответствует эта роль, или null для пользовательской. `owner` встречается только в строке самого владельца, рядом с `isOwner: true`; назначение этой роли кому-либо отклоняется с `role_immutable` (409).
isOwnerboolean: True ровно в одной строке — у аккаунта, на который завязано рабочее пространство. Он обладает всеми правами, что бы ни говорила его строка роли, сортируется первым, а `add`, `update` и `remove` отказывают по нему с `member_is_owner`. При подсчёте мест его исключайте.
impliedboolean: True, когда у человека есть выдачи адресов и нет строки участника, то есть роль была выведена, а не выбрана: любая выдача `member` сводится к встроенной роли Member, иначе к Viewer. Для владельца никогда не true. Показывайте это как «подразумевается доступом». Пока PATCH не превратит вывод в решение, расширение его доступа к адресам молча расширяет и то, что ему можно делать.
permissionsPermission[]: Права роли, развёрнутые прямо на участнике, чтобы одно чтение отвечало на вопрос «можно ли ему?» без запроса роли. У подразумеваемого участника они берутся из встроенного ШАБЛОНА, а не из строки роли этого рабочего пространства, поэтому правка встроенной роли Member не меняет того, чем обладает подразумеваемый участник.
addressesMemberAddress[]: Выданные ему адреса, отсортированные по адресу, каждый со своим уровнем доступа. Пусто у того, у кого есть роль и нет выдач, — именно так выглядит новый участник, пока ему не выдан адрес, и это правильный вид отказа, пока вы ещё решаете, что ему следует видеть.
addresses[].addressIdstring: Идентификатор адреса; именно его принимают `grantAddress` и `revokeAddress`. Идентификатор, не являющийся адресом этого рабочего пространства, отклоняется в обоих вызовах, вместо того чтобы сообщить об отзыве, которого не было.
addresses[].addressstring: Полный адрес в нижнем регистре, собранный заново из локальной части и домена.
addresses[].access'member' | 'viewer': Что ему можно делать с этим конкретным адресом: `member` читает его и отправляет от его имени, `viewer` только читает. Отправка происходит, лишь когда её разрешают и это поле, и роль, поэтому роль с `emails:send` поверх выдачи `viewer` не отправляет ни с одного адреса; в хранилище колонка называется `role`, и здесь она переименована, чтобы один объект не нёс два `role` из двух разных словарей.
createdAtstring | null: Когда была создана его строка участника, ISO-8601; null, когда строки участника нет вовсе. Этот null описывает ту же группу, что и `implied: true`: людей, у которых адреса остались с времён до появления ролей и которым с тех пор никто роль не назначил.