Pre-built Routes

The @elcto/api library includes pre-built route functions for common API operations. These functions handle GraphQL/REST queries internally and provide typed responses.

Config-first

Every route helper takes an ApiClientConfig as its first argument. Pass getApiConfig() from @/lib/api (the library reads no env itself):

import { getApiConfig } from "@/lib/api";
import { getActiveSessions } from "@elcto/api";

const { sessions } = await getActiveSessions(getApiConfig(), currentToken, {
  accessToken: session.accessToken,
});

User data

There are no REST route helpers for user profile / permissions / accounts. Fetch user data over GraphQL instead — the userProfile, userPermissions, user and users operations in the GraphQL API. The apps wrap these in their own /api/user/* routes.

Session Routes

Functions for managing user sessions.

import {
  getActiveSessions,
  revokeSession,
  revokeAllOtherSessions,
} from "@elcto/api";

getActiveSessions

Get all active sessions for the authenticated user. Pass the current session token to flag which session is current; pass GraphQL request options (including accessToken) to authenticate.

const { sessions, currentSessionId } = await getActiveSessions(getApiConfig(), currentToken, {
  accessToken: session.accessToken,
});

// Mark current session
const sessionsWithCurrent = sessions.map(s => ({
  ...s,
  isCurrent: s.id === currentSessionId,
}));

Parameters:

Parameter	Type	Description
`config`	`ApiClientConfig`	API client config — use `getApiConfig()`
`currentToken`	`string`	Optional session token identifying the current session
`options`	`GraphQLRequestOptions`	Optional GraphQL request options (including `accessToken`)

Returns: Promise<ActiveSessionsResponse>

interface ActiveSessionsResponse {
  sessions: ActiveSession[];
  currentSessionId: string | null;
}

revokeSession

Revoke a specific session. Cannot revoke the current session.

const result = await revokeSession(getApiConfig(), sessionId, currentToken, {
  accessToken: session.accessToken,
});

if (result.success) {
  console.log(result.message);
}

Parameters:

Parameter	Type	Description
`config`	`ApiClientConfig`	API client config — use `getApiConfig()`
`sessionId`	`string`	ID of the session to revoke
`currentToken`	`string`	Optional session token to prevent revoking the current session
`options`	`GraphQLRequestOptions`	Optional GraphQL request options (including `accessToken`)

Returns: Promise<RevokeSessionResponse>

interface RevokeSessionResponse {
  success: boolean;
  message: string;
}

revokeAllOtherSessions

Revoke all sessions except the current one.

const result = await revokeAllOtherSessions(getApiConfig(), currentToken, {
  accessToken: session.accessToken,
});

console.log(`Revoked ${result.revokedCount} sessions`);

Parameters:

Parameter	Type	Description
`config`	`ApiClientConfig`	API client config — use `getApiConfig()`
`currentToken`	`string`	Optional session token to exclude from revocation
`options`	`GraphQLRequestOptions`	Optional GraphQL request options (including `accessToken`)

Returns: Promise<RevokeAllSessionsResponse>

interface RevokeAllSessionsResponse {
  success: boolean;
  revokedCount: number;
  message: string;
}

Audit Routes

Functions for accessing and managing audit logs.

import {
  getMyAuditLog,
  getUserAuditLog,
  getAllAuditEvents,
  logAuditEvent,
  reportAuditEvent,
  getMyAuditReports,
} from "@elcto/api";

getMyAuditLog

Get the current user's activity log.

const auditPage = await getMyAuditLog(
  getApiConfig(),
  {
    page: 1,
    limit: 20,
    eventType: "login",
    status: "success",
  },
  headers
);

console.log(`Found ${auditPage.totalCount} events`);

Parameters:

Parameter	Type	Description
`config`	`ApiClientConfig`	API client config — use `getApiConfig()`
`query`	`AuditEventQuery`	Query parameters
`headers`	`Record<string, string>`	Optional headers

Returns: Promise<AuditEventPage>

getUserAuditLog

Get audit log for a specific user (admin only).

const auditPage = await getUserAuditLog(
  getApiConfig(),
  userId,
  { page: 1, limit: 50 },
  headers
);

Parameters:

Parameter	Type	Description
`config`	`ApiClientConfig`	API client config — use `getApiConfig()`
`userId`	`string`	Target user ID
`query`	`AuditEventQuery`	Query parameters
`headers`	`Record<string, string>`	Optional headers

Returns: Promise<AuditEventPage>

Required Permission: audit:read

getAllAuditEvents

Get all audit events with advanced filtering (admin only).

const auditPage = await getAllAuditEvents(
  getApiConfig(),
  {
    page: 1,
    limit: 50,
    eventType: "login_failed",
    sourceService: "id",
    startDate: "2024-01-01T00:00:00Z",
    endDate: "2024-01-31T23:59:59Z",
    sortField: "createdAt",
    sortDirection: "desc",
    isReported: true,
  },
  headers
);

Query Parameters:

Parameter	Type	Description
`page`	`number`	Page number (1-indexed)
`limit`	`number`	Items per page
`eventType`	`string`	Filter by event type
`eventTypes`	`string`	Comma-separated event types
`userId`	`string`	Filter by user ID
`userSearch`	`string`	Search by username
`resourceType`	`string`	Filter by resource type
`status`	`string`	Filter by status ("success" or "failure")
`sourceService`	`string`	Filter by source service
`startDate`	`string`	Start date (ISO 8601)
`endDate`	`string`	End date (ISO 8601)
`sortField`	`string`	Sort field
`sortDirection`	`string`	"asc" or "desc"
`isReported`	`boolean`	Filter reported events

Required Permission: audit:read

logAuditEvent

Log an audit event programmatically.

import { AuditEventTypes, AuditResourceTypes, AuditSourceServices } from "@elcto/api";

const event = await logAuditEvent(
  getApiConfig(),
  {
    userId: user.id,
    eventType: AuditEventTypes.USER_UPDATED,
    resourceType: AuditResourceTypes.USER,
    resourceId: targetUserId,
    description: "Custom action performed",
    metadata: { action: "example" },
    ipAddress: clientIp,
    userAgent: userAgent,
    status: "success",
    sourceService: AuditSourceServices.BACKEND,
  },
  headers
);

Parameters:

Field	Type	Required	Description
`userId`	`string`	No	User ID (optional for system events)
`eventType`	`string`	Yes	Event type constant
`resourceType`	`string`	No	Resource type
`resourceId`	`string`	No	Resource ID
`actorId`	`string`	No	Actor user ID (if different from userId)
`description`	`string`	No	Human-readable description
`metadata`	`object`	No	Additional data
`ipAddress`	`string`	No	Client IP address
`userAgent`	`string`	No	Client user agent
`status`	`string`	No	"success" or "failure"
`errorMessage`	`string`	No	Error message (if failure)
`sourceService`	`string`	No	Source service identifier

reportAuditEvent

Report an audit event as suspicious activity.

const result = await reportAuditEvent(
  getApiConfig(),
  {
    auditEventId: event.id,
    reason: "not_me",
    description: "I didn't perform this action",
  },
  headers
);

if (result.success) {
  console.log("Report submitted:", result.report?.id);
}

Input:

Field	Type	Required	Description
`auditEventId`	`string`	Yes	Audit event ID to report
`reason`	`string`	Yes	Reason: "not_me", "suspicious", "unknown_device", "unknown_location", "other"
`description`	`string`	No	Additional details

Returns: Promise<ReportAuditEventResponse>

getMyAuditReports

Get the current user's submitted reports.

const reports = await getMyAuditReports(getApiConfig(), headers);

const pendingReports = reports.filter(r => r.status === "pending");

Parameters:

Parameter	Type	Description
`config`	`ApiClientConfig`	API client config — use `getApiConfig()`
`headers`	`Record<string, string>`	Optional headers

Returns: Promise<AuditEventReport[]>

Admin Audit Routes

Additional audit functions for administrators.

import {
  getAllAuditReports,
  updateAuditReport,
} from "@elcto/api";

getAllAuditReports

Get all audit reports (admin only).

const reportPage = await getAllAuditReports(
  getApiConfig(),
  {
    page: 1,
    limit: 20,
    status: "pending",
  },
  headers
);

Query Parameters:

Parameter	Type	Description
`page`	`number`	Page number
`limit`	`number`	Items per page
`status`	`string`	Filter by status: "pending", "reviewed", "resolved", "dismissed"

Required Permission: audit:read

updateAuditReport

Update an audit report status (admin only).

const result = await updateAuditReport(
  getApiConfig(),
  {
    reportId: report.id,
    status: "resolved",
    resolutionNotes: "Confirmed unauthorized access. User notified and security measures taken.",
  },
  headers
);

Input:

Field	Type	Required	Description
`reportId`	`string`	Yes	Report ID
`status`	`string`	Yes	New status: "reviewed", "resolved", "dismissed"
`resolutionNotes`	`string`	No	Notes about resolution

Required Permission: audit:write

Vessel Routes (AIS)

GraphQL-based read helpers for the AIS vessel query API. See Vessels API for the full endpoint reference. There is intentionally no getVesselTrack helper — the registry is static-only and positions are never persisted to Postgres; live positions stream over the WebSocket "vessels" channel instead.

import { getVessels, getVessel } from "@elcto/api";

getVessels

List vessels from the static registry (paginated, filterable by name / ship type). Position fields are always null in this list. Requires ais:read.

const page = await getVessels(
  getApiConfig(),
  { filter: { name: "rena", shipTypeCode: 70 }, page: 1, limit: 20 },
  { Authorization: `Bearer ${session.accessToken}` }
);

console.log(`Found ${page.total} vessels`);

Parameters:

Parameter	Type	Description
`config`	`ApiClientConfig`	API client config — use `getApiConfig()`
`params.filter`	`VesselFilterInput`	Optional `{ name?, shipTypeCode? }` filter
`params.page`	`number`	Page number (1-indexed), default `1`
`params.limit`	`number`	Items per page, default `20`
`headers`	`Record<string, string>`	Headers to extract the caller's Bearer token from

Returns: Promise<PaginatedVessel>

getVessel

Get a single vessel by MMSI. Reads the Redis hot cache first (live position included), falling back to the static registry (position fields null) on a cache miss. Requires ais:read.

const vessel = await getVessel(getApiConfig(), 211234560, {
  Authorization: `Bearer ${session.accessToken}`,
});

if (vessel?.lat != null) {
  console.log(`Live position: ${vessel.lat}, ${vessel.lng}`);
}

Parameters:

Parameter	Type	Description
`config`	`ApiClientConfig`	API client config — use `getApiConfig()`
`mmsi`	`number`	Vessel MMSI
`headers`	`Record<string, string>`	Headers to extract the caller's Bearer token from

Returns: Promise<Vessel | null> — null if the vessel is in neither Redis nor the registry.

Usage in Next.js API Routes

Example: Session Management

// src/app/api/sessions/route.ts
import { NextRequest, NextResponse } from "next/server";
import { getServerSession } from "next-auth";
import { authOptions } from "@/lib/auth";
import { getActiveSessions, handleApiError } from "@elcto/api";
import { getApiConfig } from "@/lib/api";

export async function GET(request: NextRequest) {
  try {
    const session = await getServerSession(authOptions);
    if (!session?.user?.id) {
      return NextResponse.json(
        { error: "Unauthorized", code: "UNAUTHORIZED" },
        { status: 401 }
      );
    }

    const result = await getActiveSessions(getApiConfig(), undefined, {
      accessToken: session.accessToken,
    });

    return NextResponse.json(result);
  } catch (error) {
    return handleApiError(request, error, {
      route: "sessions/list",
      defaultMessage: "Failed to fetch sessions",
    });
  }
}

Example: Audit Activity Page

// src/app/api/account/activity/route.ts
import { NextRequest, NextResponse } from "next/server";
import { getServerSession } from "next-auth";
import { authOptions } from "@/lib/auth";
import { getMyAuditLog, handleApiError } from "@elcto/api";
import { getApiConfig } from "@/lib/api";

export async function GET(request: NextRequest) {
  try {
    const session = await getServerSession(authOptions);
    if (!session?.user?.id) {
      return NextResponse.json(
        { error: "Unauthorized", code: "UNAUTHORIZED" },
        { status: 401 }
      );
    }

    const { searchParams } = new URL(request.url);
    const page = parseInt(searchParams.get("page") || "1");
    const limit = parseInt(searchParams.get("limit") || "20");
    const eventType = searchParams.get("eventType") || undefined;

    const headers = {
      Authorization: `Bearer ${session.accessToken}`,
    };

    const result = await getMyAuditLog(
      getApiConfig(),
      { page, limit, eventType },
      headers
    );

    return NextResponse.json(result);
  } catch (error) {
    return handleApiError(request, error, {
      route: "account/activity",
      defaultMessage: "Failed to fetch activity log",
    });
  }
}

Session Routes​

getActiveSessions​

revokeSession​

revokeAllOtherSessions​

Audit Routes​

getMyAuditLog​

getUserAuditLog​

getAllAuditEvents​

logAuditEvent​

reportAuditEvent​

getMyAuditReports​

Admin Audit Routes​

getAllAuditReports​

updateAuditReport​

Vessel Routes (AIS)​

getVessels​

getVessel​

Usage in Next.js API Routes​

Example: Session Management​

Example: Audit Activity Page​

Session Routes

getActiveSessions

revokeSession

revokeAllOtherSessions

Audit Routes

getMyAuditLog

getUserAuditLog

getAllAuditEvents

logAuditEvent

reportAuditEvent

getMyAuditReports

Admin Audit Routes

getAllAuditReports

updateAuditReport

Vessel Routes (AIS)

getVessels

getVessel

Usage in Next.js API Routes

Example: Session Management

Example: Audit Activity Page