Skip to content

@saif/platform

The TypeScript/JavaScript counterpart to the .NET SAIF.Platform package: a browser-side Platform class that wires up OpenTelemetry and an auth service from Vite env vars, plus the auth primitives and utilities consumed by @saif/platform-react.

Platform setup

Platform combines OpenTelemetry and AuthService behind one options object. Everything is optional and defaults to VITE_* env var names, so a golden-path frontend can construct it with no arguments once the corresponding env vars are set:

import { Platform } from '@saif/platform';

const platform = new Platform();
platform.initialize();

initialize() starts the OpenTelemetry pipeline (see below); constructing Platform alone does not have side effects.

Override the env var names, or pass explicit values through the nested options, when an app doesn't follow the default naming:

const platform = new Platform({
  ENV_BACKEND_URL: 'VITE_BACKEND_URL',
  ENV_FRONTEND_URL: 'VITE_FRONTEND_URL',
  openTelemetryOptions: {
    ENV_OTEL_SERVICE_NAME: 'VITE_OTEL_SERVICE_NAME',
  },
  authServiceOptions: {
    loginPath: '/auth/login',
  },
});

ENV_BACKEND_URL doubles as the default for OpenTelemetry's CORS trace-header propagation target and for the auth server URL, unless those are set explicitly in openTelemetryOptions/ authServiceOptions. ENV_FRONTEND_URL (and the optional ENV_FRONTEND_PATH) similarly seed AuthService's default post-login/logout return URL.

OpenTelemetry

OpenTelemetry.initialize() sets up a WebTracerProvider, LoggerProvider, and MeterProvider (traces, logs, and metrics over OTLP/HTTP), registers the web auto-instrumentations, and installs ZoneContextManager for async context propagation. It's a no-op if ENV_OTEL_SERVICE_NAME or ENV_OTEL_EXPORTER_OTLP_ENDPOINT isn't set, so it's safe to call unconditionally in environments (like local dev) that don't export telemetry:

import { OpenTelemetry } from '@saif/platform';

new OpenTelemetry({
  ENV_OTEL_SERVICE_NAME: 'VITE_OTEL_SERVICE_NAME',
  ENV_OTEL_EXPORTER_OTLP_ENDPOINT: 'VITE_OTEL_EXPORTER_OTLP_ENDPOINT',
}).initialize();

Used through Platform, this is already wired up by platform.initialize().

Auth primitives

AuthService is a thin client for a same-origin (or configured cross-origin) auth server: it redirects to login/logout paths with a computed returnUrl, and fetches the current User from a me endpoint.

import { AuthService } from '@saif/platform';

const authService = new AuthService();

authService.login(); // redirects to `${authServerUrl}/auth/login?returnUrl=...`
const user = await authService.me(); // { isAuthenticated, claims? }

isConfigured reports whether an auth server URL env var is actually set — login/logout are no-ops otherwise, and me() resolves to an unauthenticated User instead of throwing. User and Claim are the plain data shapes returned by me(); they carry no behavior of their own.

@saif/platform-react's AuthProvider wraps AuthService in React context and query-cache invalidation — use it there instead of calling AuthService directly in component code.

Utils

trim/trimStart/trimEnd trim a specific character (not just whitespace) from a string, e.g. stripping a trailing slash from a configured base URL:

import { trimEnd } from '@saif/platform';

trimEnd('https://example.com/', '/'); // 'https://example.com'
  • @saif/platform-react — React bindings: PlatformProvider context, AuthProvider, and a Kiota + TanStack Query layer built on top of this package.

View source on GitHub