Class: AtlasRb::User

Inherits:
Object
  • Object
show all
Extended by:
FaradayHelper
Defined in:
lib/atlas_rb/user.rb

Overview

Read-only user directory lookups — typeahead search and NUID → name resolution.

This is a user-context binding: calls authenticate as the acting user via the standard ATLAS_TOKEN + User: header pairing, like every other top-level class. It is deliberately not part of System — that namespace is structurally reserved for system-token calls (System::User.find_or_create), and directory lookups are an ordinary logged-in-user capability.

Atlas enforces minimal disclosure: every entry carries nuid + name only (no email, role, or groups), and rows with role anonymous, guest, or system are never returned. Per the layering principle the gem adds nothing on top — no caching, no name parsing, no result shaping; presentation belongs to the host application.

Constant Summary collapse

ROUTE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Atlas REST endpoint prefix for the user directory.

"/users"

Class Method Summary collapse

Methods included from FaradayHelper

connection, multipart, system_connection

Class Method Details

.find_by_nuid(target_nuid, nuid: nil) ⇒ AtlasRb::Mash?

Resolve a single NUID to a directory entry.

Examples:

Sender-name display

AtlasRb::User.find_by_nuid("001234567")
# => { "nuid" => "001234567", "name" => "Doe, Jane" }

Parameters:

  • target_nuid (String) —

    the NUID being looked up — the subject of the call, distinct from the acting nuid: kwarg.

  • nuid (String, nil) (defaults to: nil) —

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (AtlasRb::Mash, nil) —

    the nuid + name entry, or nil when Atlas reports the NUID as absent (unknown, or held by an excluded role — the two are indistinguishable on the wire by design).



62
63
64
65
66
67
 
# File 'lib/atlas_rb/user.rb', line 62

def self.find_by_nuid(target_nuid, nuid: nil)
  response = connection({}, nuid).get("#{ROUTE}/by_nuid/#{target_nuid}")
  return nil if response.status == 404

  AtlasRb::Mash.new(JSON.parse(response.body))
end

.resolve(nuids, nuid: nil) ⇒ Array<AtlasRb::Mash>

Batch-resolve a set of NUIDs to directory entries in one call.

Same response shape as search. Unresolvable NUIDs (unknown or excluded-role) are dropped, so the result may be shorter than the input — callers index by nuid. Atlas caps the batch at 100.

Examples:

Resolve an inbox page of senders in one round-trip

senders = AtlasRb::User.resolve(["001234567", "007654321"])
by_nuid = senders.index_by { |entry| entry["nuid"] }

Parameters:

  • nuids (Array<String>, String) —

    the NUIDs to resolve.

  • nuid (String, nil) (defaults to: nil) —

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (Array<AtlasRb::Mash>) —

    resolved entries, each carrying nuid and name, ordered by name.



85
86
87
88
89
 
# File 'lib/atlas_rb/user.rb', line 85

def self.resolve(nuids, nuid: nil)
  JSON.parse(
    connection({ nuids: Array(nuids).join(",") }, nuid).get(ROUTE)&.body
  ).map { |entry| AtlasRb::Mash.new(entry) }
end

.search(query, nuid: nil) ⇒ Array<AtlasRb::Mash>

Typeahead search of the user directory.

Case-insensitive match on name, prefix match on NUID (so typing a known NUID works too). Atlas caps the result (10 entries) and orders it by name; a blank query resolves to an empty list.

Examples:

Recipient typeahead

AtlasRb::User.search("jan", nuid: "000000002")
# => [{ "nuid" => "001234567", "name" => "Doe, Jane" }, ...]

Parameters:

  • query (String) —

    name fragment or NUID prefix to match.

  • nuid (String, nil) (defaults to: nil) —

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (Array<AtlasRb::Mash>) —

    matching directory entries, each carrying nuid and name.



42
43
44
45
46
 
# File 'lib/atlas_rb/user.rb', line 42

def self.search(query, nuid: nil)
  JSON.parse(
    connection({ q: query }, nuid).get(ROUTE)&.body
  ).map { |entry| AtlasRb::Mash.new(entry) }
end