Amarula.Group (amarula v0.4.2)

View Source

Group chats — the %Amarula.Group{} struct and every group operation.

The struct is the consumer-facing view of group metadata (addresses as Amarula.Address); you get one from metadata/2 and list/1. The operations (create/3, leave/2, update_subject/3, participant and invite management, join-request approval) build a w:g2 IQ and parse the reply. Each returns :ok / {:ok, value} / {:error, {:group_op_failed, code, text}}.

group is a @g.us jid string (e.g. from a group's :address).

A group is a container of participants, not a person: :address names the group (:group kind), :participants are the member Amarula.Addresses.

Summary

Types

affected()

Affected participant in a group op: %{jid, status} (status "200" = ok).

conn()
participant()
t()

Functions

accept_invite(conn, code)

Join a group by invite code. Returns the joined group's jid.

create(conn, subject, participants)

Create a group named subject with the given participant jids. Returns the new group's metadata.

from_metadata(meta)

Build a Group from a Amarula.Protocol.Groups.Metadata map.

invite_code(conn, group)

Fetch the group's invite code.

invite_info(conn, code)

Look up group metadata from an invite code without joining.

join_approval_mode(conn, group, mode)

Turn join-approval (admin approves joiners) :on/:off.

leave(conn, group)

Leave a group.

list(conn)

List all groups we participate in ([%Amarula.Group{}]).

member_add_mode(conn, group, mode)

Who may add members: :admin_add (admins only) or :all_member_add.

metadata(conn, group)

Fetch a group's metadata (%Amarula.Group{}). group is an Address or jid.

participants(conn, group, participants, action)

Add/remove/promote/demote participants. action is :add/:remove/:promote/ :demote. Returns the affected participants with per-jid status.

request_update(conn, group, participants, action)

Approve/reject pending join requests for participants. action is :approve/:reject.

requests(conn, group)

List pending join-approval requests as [%{jid: Amarula.Address.t(), requested_at: integer | nil}] — who asked to join and when. Approve/reject them with request_update/4.

revoke_invite(conn, group)

Revoke + regenerate the group's invite code. Returns the new code.

toggle_ephemeral(conn, group, expiration)

Toggle disappearing messages. 0 = off; otherwise seconds of expiration.

update_description(conn, group, description)

Set (or clear, with nil/"") a group's description.

update_member_tag(conn, group, label)

Set your own member tag (per-group self-label) in group, or clear it with "". Capped at 30 chars (a longer one is rejected, not truncated). A message send (not an IQ op), so it lives on the facade too as Amarula.update_member_tag/3 — this is the group-scoped alias.

update_setting(conn, group, setting)

Change a group setting: :announcement/:not_announcement (only admins post), :locked/:unlocked (only admins edit info).

update_subject(conn, group, subject)

Change a group's subject (title).

Types

affected()

@type affected() :: %{jid: String.t() | nil, status: String.t()}

Affected participant in a group op: %{jid, status} (status "200" = ok).

conn()

@type conn() :: GenServer.server()

participant()

@type participant() :: %{
  address: Amarula.Address.t(),
  admin: :admin | :superadmin | nil
}

t()

@type t() :: %Amarula.Group{
  address: Amarula.Address.t(),
  owner: Amarula.Address.t() | nil,
  participants: [participant()],
  size: non_neg_integer(),
  subject: String.t() | nil
}

Functions

accept_invite(conn, code)

@spec accept_invite(conn(), String.t()) :: {:ok, String.t()} | {:error, term()}

Join a group by invite code. Returns the joined group's jid.

create(conn, subject, participants)

@spec create(conn(), String.t(), [String.t()]) :: {:ok, t()} | {:error, term()}

Create a group named subject with the given participant jids. Returns the new group's metadata.

from_metadata(meta)

@spec from_metadata(map()) :: t()

Build a Group from a Amarula.Protocol.Groups.Metadata map.

invite_code(conn, group)

@spec invite_code(conn(), String.t()) :: {:ok, String.t()} | {:error, term()}

Fetch the group's invite code.

invite_info(conn, code)

@spec invite_info(conn(), String.t()) :: {:ok, t()} | {:error, term()}

Look up group metadata from an invite code without joining.

join_approval_mode(conn, group, mode)

@spec join_approval_mode(conn(), String.t(), :on | :off) :: :ok | {:error, term()}

Turn join-approval (admin approves joiners) :on/:off.

leave(conn, group)

@spec leave(conn(), String.t()) :: :ok | {:error, term()}

Leave a group.

list(conn)

@spec list(conn()) :: {:ok, [t()]} | {:error, term()}

List all groups we participate in ([%Amarula.Group{}]).

member_add_mode(conn, group, mode)

@spec member_add_mode(conn(), String.t(), :admin_add | :all_member_add) ::
  :ok | {:error, term()}

Who may add members: :admin_add (admins only) or :all_member_add.

metadata(conn, group)

@spec metadata(conn(), Amarula.Address.t() | String.t()) ::
  {:ok, t()} | {:error, term()}

Fetch a group's metadata (%Amarula.Group{}). group is an Address or jid.

participants(conn, group, participants, action)

@spec participants(
  conn(),
  String.t(),
  [String.t()],
  Amarula.Protocol.Groups.Ops.action()
) ::
  {:ok, [affected()]} | {:error, term()}

Add/remove/promote/demote participants. action is :add/:remove/:promote/ :demote. Returns the affected participants with per-jid status.

request_update(conn, group, participants, action)

@spec request_update(conn(), String.t(), [String.t()], :approve | :reject) ::
  {:ok, [affected()]} | {:error, term()}

Approve/reject pending join requests for participants. action is :approve/:reject.

requests(conn, group)

@spec requests(conn(), String.t()) ::
  {:ok, [%{jid: Amarula.Address.t(), requested_at: integer() | nil}]}
  | {:error, term()}

List pending join-approval requests as [%{jid: Amarula.Address.t(), requested_at: integer | nil}] — who asked to join and when. Approve/reject them with request_update/4.

revoke_invite(conn, group)

@spec revoke_invite(conn(), String.t()) :: {:ok, String.t()} | {:error, term()}

Revoke + regenerate the group's invite code. Returns the new code.

toggle_ephemeral(conn, group, expiration)

@spec toggle_ephemeral(conn(), String.t(), non_neg_integer()) ::
  :ok | {:error, term()}

Toggle disappearing messages. 0 = off; otherwise seconds of expiration.

update_description(conn, group, description)

@spec update_description(conn(), String.t(), String.t() | nil) ::
  :ok | {:error, term()}

Set (or clear, with nil/"") a group's description.

update_member_tag(conn, group, label)

@spec update_member_tag(conn(), String.t(), String.t()) ::
  Amarula.send_result() | {:error, :member_tag_too_long}

Set your own member tag (per-group self-label) in group, or clear it with "". Capped at 30 chars (a longer one is rejected, not truncated). A message send (not an IQ op), so it lives on the facade too as Amarula.update_member_tag/3 — this is the group-scoped alias.

update_setting(conn, group, setting)

@spec update_setting(conn(), String.t(), Amarula.Protocol.Groups.Ops.setting()) ::
  :ok | {:error, term()}

Change a group setting: :announcement/:not_announcement (only admins post), :locked/:unlocked (only admins edit info).

update_subject(conn, group, subject)

@spec update_subject(conn(), String.t(), String.t()) :: :ok | {:error, term()}

Change a group's subject (title).