SDK
الأعضاء
`members.list` و`get` و`add` و`update` و`remove` و`grantAddress` و`revokeAddress`.
كل التوابع
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 حرفًا؛ ويُرفض معرّف ليس عنوانًا على مساحة العمل هذه. ويُكتب الدور أولًا ثم تتبعه المنح واحدة تلو الأخرى، فمعرّف سيئ يترك العضو منشأً بعناوين أقل مما طلبت. والعلاج هو إعادة إرسال المتن نفسه، لأن كلتا الكتابتين تُدرج أو تُحدِّث.
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`: أشخاص يحملون عناوين من قبل وجود الأدوار ولم يمنحهم أحد دورًا منذ ذلك الحين.