@viaaccess/client

TypeScript SDK for ViaAccess level-01 integration: validations, event/alert queries, and webhooks. Providers, rules, and VACP use REST until SDK methods are added.

Install

npm install @viaaccess/client

Quick start

import {
  createViaAccessClient,
  verifyViaAccessWebhookRequest,
  parseViaAccessWebhook,
} from "@viaaccess/client";

const client = createViaAccessClient({
  baseUrl: process.env.VIAACCESS_API_URL!,
  apiKey: process.env.VIAACCESS_API_KEY!,
});

await client.validate({
  memberId: "member-42",
  memberName: "Maria Silva",
  accessPoint: "entrada-principal",
  direction: "ENTRY",
});

const { events, total } = await client.listEvents({ limit: 20 });

listEvents

Lists correlated access events (GET /api/v1/events). Each event may include rule, detectionProvider, memberId, and occurredAt.

const { events, total } = await client.listEvents({
  accessPoint: "entrada-principal",
  outcome: "AUTHORIZED",
  since: "2026-06-25T00:00:00.000Z",
  until: "2026-06-25T23:59:59.999Z",
  memberIds: ["member-42", "member-99"],
  offset: 0,
  limit: 25,
});

// Cursor pagination (alternative to offset):
const page2 = await client.listEvents({
  accessPoint: "entrada-principal",
  limit: 25,
  before: events.at(-1)?.occurredAt as string,
  beforeId: events.at(-1)?.id as string,
});

| Option | Description | |--------|-------------| | outcome | AUTHORIZED or UNAUTHORIZED | | accessPoint | Slug do ponto | | since / until | Intervalo ISO 8601 em occurredAt (inclusive) | | memberIds | Filtra por um ou mais memberId | | offset / limit | Paginação por deslocamento (limit máx. 100) | | before / beforeId | Cursor para página seguinte (ordenado por occurredAt desc) |

Response: { events: [...], total: number } where total matches the active filters.

Webhooks

const rawBody = await request.text();
const verified = verifyViaAccessWebhookRequest({
  secret: process.env.VIAACCESS_WEBHOOK_SECRET!,
  rawBody,
  signatureHeader: request.headers.get("x-viaaccess-signature"),
  timestampHeader: request.headers.get("x-viaaccess-timestamp"),
});
if (!verified.ok) return Response.json({ error: "Unauthorized" }, { status: 401 });

const webhook = parseViaAccessWebhook(
  JSON.parse(rawBody),
  request.headers.get("x-viaaccess-event"),
);

Detection events usually come from bridges on the local network, not from the integrator app. See the ViaAccess docs for Detection Providers.

Docs

• Integration levels
• Node.js
• REST / OpenAPI
• VACP (level 02, REST today)

Requirements

Node.js 20+

Publishing (maintainers)

1. Bump version in package.json and note changes in CHANGELOG.md.
2. Commit and push tag client-v<version> (example: client-v0.1.1).
3. GitHub Actions publishes to npm (NPM_TOKEN secret with access to the @viaaccess org).