Ltix.MembershipsService (Ltix v0.1.0)

Copy Markdown View Source

Query context membership (roster) from a platform using the Names and Roles Provisioning Service (NRPS) v2.0.

Given a successful LTI 1.3 launch that includes the memberships endpoint claim, retrieve the list of users enrolled in the course or resource link.

From a launch context

{:ok, client} = Ltix.MembershipsService.authenticate(launch_context)
{:ok, roster} = Ltix.MembershipsService.get_members(client)

Enum.each(roster, fn member ->
  IO.puts("#{member.name}: #{inspect(member.roles)}")
end)

From a registration

alias Ltix.LaunchClaims.MembershipsEndpoint

{:ok, client} = Ltix.MembershipsService.authenticate(registration,
  endpoint: MembershipsEndpoint.new("https://lms.example.com/memberships")
)

{:ok, roster} = Ltix.MembershipsService.get_members(client, role: :learner)

Streaming large rosters

{:ok, stream} = Ltix.MembershipsService.stream_members(client)

stream
|> Stream.filter(&(&1.status == :active))
|> Enum.each(&process_member/1)

Summary

Functions

authenticate(context_or_registration, opts \\ [])

Acquire an OAuth token for the memberships service.

authenticate!(context_or_registration, opts \\ [])

Same as authenticate/2 but raises on error.

get_members(client, opts \\ [])

Fetch all members from the memberships endpoint.

get_members!(client, opts \\ [])

Same as get_members/2 but raises on error.

stream_members(client, opts \\ [])

Fetch members as a lazy stream.

stream_members!(client, opts \\ [])

Same as stream_members/2 but raises on error.

Functions

authenticate(context_or_registration, opts \\ [])

@spec authenticate(
  Ltix.LaunchContext.t() | Ltix.Registration.t(),
  keyword()
) :: {:ok, Ltix.OAuth.Client.t()} | {:error, Exception.t()}

Acquire an OAuth token for the memberships service.

Accepts a %LaunchContext{} or a %Registration{}. With a launch context, the endpoint is extracted from the launch claims. With a registration, pass the endpoint via the :endpoint option.

From a launch context

{:ok, client} = Ltix.MembershipsService.authenticate(launch_context)

From a registration

{:ok, client} = Ltix.MembershipsService.authenticate(registration,
  endpoint: MembershipsEndpoint.new("https://lms.example.com/memberships")
)

Options (launch context)

Options (registration)

authenticate!(context_or_registration, opts \\ [])

@spec authenticate!(
  Ltix.LaunchContext.t() | Ltix.Registration.t(),
  keyword()
) :: Ltix.OAuth.Client.t()

Same as authenticate/2 but raises on error.

get_members(client, opts \\ [])

@spec get_members(
  Ltix.OAuth.Client.t(),
  keyword()
) ::
  {:ok, Ltix.MembershipsService.MembershipContainer.t()}
  | {:error, Exception.t()}

Fetch all members from the memberships endpoint.

Follows all rel="next" pagination links and returns a complete %MembershipContainer{}. The container implements Enumerable, so you can pipe it directly into Enum or Stream functions.

Options

  • :endpoint (struct of type Ltix.LaunchClaims.MembershipsEndpoint) - Override the endpoint stored on the client.

  • :role (atom/0 | String.t/0 | struct of type Ltix.LaunchClaims.Role) - Filter by role. Accepts a role atom (e.g., :learner), URI string, %Role{} struct, or short name string (e.g., "Learner").

  • :resource_link_id (String.t/0) - Query resource link membership.

  • :per_page (integer/0) - Page size hint. The platform may return more or fewer than requested.

  • :max_members (integer/0 | :infinity) - Safety limit for eager fetch. Returns a RosterTooLarge error if exceeded. Set to :infinity to disable. The default value is 10000.

get_members!(client, opts \\ [])

@spec get_members!(
  Ltix.OAuth.Client.t(),
  keyword()
) :: Ltix.MembershipsService.MembershipContainer.t()

Same as get_members/2 but raises on error.

stream_members(client, opts \\ [])

@spec stream_members(
  Ltix.OAuth.Client.t(),
  keyword()
) :: {:ok, Enumerable.t()} | {:error, Exception.t()}

Fetch members as a lazy stream.

Returns {:ok, stream} where each element is a %Member{}. Use this instead of get_members/2 for large rosters where you want to process members incrementally or stop early.

Options

stream_members!(client, opts \\ [])

@spec stream_members!(
  Ltix.OAuth.Client.t(),
  keyword()
) :: Enumerable.t()

Same as stream_members/2 but raises on error.