@vperms/client

@vperms/client loads resolved subjects over HTTP and evaluates them locally.

Factory

interface VPermsConfig {
  prefix?: string; // default "/vperms"
  subjectResolver?: SubjectResolver;
  fetch?: FetchLike;
  fetchOptions?: RequestInit;
}

interface VPermsClient {
  readonly origin: string;
  readonly prefix: string;
  getResolvedSubject(
    subjectId?: SubjectId | Principal,
  ): Promise<ResolvedSubject>;
  getAbility(subjectId?: SubjectId | Principal): Promise<PermissionAbility>;
}

function createVPerms(origin: string, config?: VPermsConfig): VPermsClient;

• origin may be absolute (https://api.example.com), relative (/api) or empty ("").
• With an explicit subject, the client requests /subject/:subjectId; with no argument it uses subjectResolver(), falling back to /subject/me when it returns null or undefined.

Ability

class PermissionAbility {
  readonly subject: ResolvedSubject;
  readonly permissions: ResolvedPermission[];
  can(permission: string): boolean;
}

const Ability = PermissionAbility;

function createAbility(subject: ResolvedSubject): PermissionAbility;

PermissionAbility is an immutable wrapper over one ResolvedSubject snapshot. can() is synchronous and only evaluates the resolved permissions using canResolved precedence — no inheritance, adapters or network.

HTTP

class VPermsHttpError extends Error {
  readonly status: number;
  readonly url: string;
}

interface FetchResolvedSubjectOptions {
  fetch?: FetchLike;
  requestInit?: RequestInit;
}

function fetchResolvedSubject(
  url: string,
  options?: FetchResolvedSubjectOptions,
): Promise<ResolvedSubject>;

Validates the response with ResolvedSubjectSchema and throws VPermsHttpError on non-2xx responses.

Other exports

DEFAULT_PREFIX ("/vperms"), FetchLike, SubjectResolver, resolveSubjectId, and the re-exported SubjectType, Subject, SubjectId, Principal, ResolvedSubject, ResolvedPermission, ResolvedPermissionSchema, ResolvedSubjectSchema.