XAuth client API

use Vsd\XauthClient\Auth\AuthGate;

$ss     = AuthGate::user();     // the signed-in snapshot
$subsId = $ss->subs_id;         // hex string

import { createXauth } from '@vsd/xauth-client-next/core'
import { xauth } from '@/lib/xauth'          // createNextXauth()

const engine = createXauth().engine
const user   = await xauth.user()
const token  = await xauth.token()           // the actor token
const subsId = user?.subs_id ?? ''

import { Controller, Get, Inject, Query } from '@nestjs/common'
import { XAUTH_GATEWAY, XauthToken, XauthUser } from '@vsd/xauth-client-next/nest'
import type { XauthGateway } from '@vsd/xauth-client-next/core'

@Controller('staff')
export class StaffController {
    constructor(@Inject(XAUTH_GATEWAY) private readonly xauth: XauthGateway) {}

    @Get()
    list(@XauthToken() token: string, @Query('search') search?: string) {
        return this.xauth.engine.roster(token, { search, page: 1, per_page: 50 })
    }
}

$page = AuthGate::userRoster([
    'search'     => 'dara',                 // login name, full name or phone; case-insensitive
    'user_class' => ['member', 'admin'],    // one class, a comma list, or an array
    'branch_ids' => [3, 5],                 // optional; can only NARROW
    'page'       => 1,
    'per_page'   => 50,                     // 1..200, default 20
]);

foreach ($page['data'] ?? [] as $row) {
    echo $row['local_login_name'], ' ', $row['role_name'], $row['can_manage'] ? ' (can manage)' : '', PHP_EOL;
}

const page = await engine.roster(token, {
    search: 'dara',
    user_class: ['member', 'admin'],
    branch_ids: [3, 5],
    page: 1,
    per_page: 50,
})

if (page.status_code !== 200) {
    // unreachable or refused - show an error, NOT "no users"
    throw new Error(page.error_message)
}

page.data.forEach((row) => console.log(row.local_login_name, row.role_name, row.can_manage))

{
  "data": [
    {
      "id": 42, "login_name": "wis-dara", "local_login_name": "dara",
      "full_name": "Dara Sok", "phone_number": "012345678", "email": null,
      "user_class": "admin", "status": 1, "is_locked": 0, "identity_type": null,
      "official_id": null, "official_code": null,
      "role_id": 7, "role_name": "Branch Manager", "authority_rank": 40,
      "branches": [{ "id": 3, "name": "Toul Kork" }],
      "can_manage": true
    }
  ],
  "total": 1, "per_page": 50, "current_page": 1, "last_page": 1
}

// every branch of the subscription, by name
$branches = AuthGate::branchLookup($subsId, null, true);

// only some branches - e.g. to label rows that carry branch_id
$labels = collect(AuthGate::branchLookup($subsId, [3, 5]))
    ->mapWithKeys(fn ($b) => [(int) data_get($b, 'id') => data_get($b, 'name')]);

$ids    = AuthGate::branchIdsBySubs($subsId);   // [3, 5, 9]
$header = AuthGate::branchDetails(3);           // object or null

const branches = await engine.branchLookup(subsId, null, true)   // [] on failure
const labels   = new Map(branches.map((b) => [Number(b.id), String(b.name)]))

const ids    = await engine.branchIdsBySubs(subsId)
const header = await engine.branchDetails(3)                       // null when absent or out of scope

// the options of an "assign role" select: grantable only (the last argument)
$roles = AuthGate::roleOptions($subsId, 'admin', null, 500, true);

$teacher  = AuthGate::roleByName('Teacher', $subsId, true);       // case-insensitive
$members  = $teacher ? AuthGate::roleMembers((int) $teacher->id) : [];

const roles = await engine.roleOptions(subsId, { token, user_class: 'admin', search: 'man', limit: 100 })

const teacher = await engine.roleByName('Teacher', subsId, true)
const members = teacher ? await engine.roleMembers(teacher.id) : []

// every user of a class - for backend jobs; no paging, no role, no branches
$drivers = AuthGate::usersByClass('driver', $subsId, 'id,full_name,phone_number');

// one user by a few allowed columns
$u = AuthGate::userIdentity(['login_name' => 'dara'], 'id,full_name,user_class');

// one value
$phone = AuthGate::userValueBy(['id' => 42], 'phone_number');

// does a login name exist (sign-up forms)
$taken = AuthGate::loginNameExists('dara');

const drivers = await engine.usersByClass('driver', subsId, 'id,full_name,phone_number')
const u       = await engine.userIdentity({ login_name: 'dara' }, 'id,full_name,user_class')
const phone   = await engine.userValueBy<string>({ id: 42 }, 'phone_number')
const taken   = await engine.loginNameExists('dara')

const res = await engine.call<Array<{ id: number; name: string }>>('users_branches', { user_id: 42, token })
// null = engine unreachable; otherwise { status_code, error_message, data }
const branches = res?.status_code === 200 ? res.data ?? [] : []

curl -s -X POST "$XAUTH_BASE_URL/api/xauth/branches/lookup" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-App-Id: $XAUTH_APP_ID" -H "X-App-Secret: $XAUTH_APP_SECRET" \
  -d '{"subs_id": "'"$SUBS_ID"'", "order_by_name": true}'

curl -s -X POST "$XAUTH_BASE_URL/api/xauth/users/roster" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-App-Id: $XAUTH_APP_ID" -H "X-App-Secret: $XAUTH_APP_SECRET" \
  -d '{"token": "'"$USER_TOKEN"'", "search": "dara", "page": 1, "per_page": 20}'

'endpoints' => [
    // ...the published defaults, then:
    'branches_lookup' => '/api/xauth/v2/branches/lookup',
],

import { createXauth } from '@vsd/xauth-client-next/core'

const xauth = createXauth({ endpoints: { branches_lookup: '/api/xauth/v2/branches/lookup' } })