Permissions SDK

SDK de permissões (core + bindings React) com TTL em memória, dedupe de requisições em voo, throttle, e suporte a ETag/304.

Instalação

npm install @admincodeform/permissions-sdk

Ajuste o escopo do pacote conforme o seu registro (ex.: @cartoriocriciuma/permissions-sdk).

Bootstrap (Core)

Inicialize o SDK uma vez no bootstrap do host (shell):

import { bootstrapPermissionsSDK } from '@admincodeform/permissions-sdk';

bootstrapPermissionsSDK({
  getToken: () => localStorage.getItem('AUTH_TOKEN') || null,
  getOrganizationId: () => window.__PLATAFORMA_CURRENT_ORG__?.id ?? null,
  fetchPermissions: async ({ token, organizationId, etag }) => {
    const headers: Record<string, string> = {};
    if (token) headers['Authorization'] = `Bearer ${token}`;
    if (organizationId) headers['X-Organization-Id'] = String(organizationId);
    if (etag) headers['If-None-Match'] = etag;

    const res = await fetch(`${process.env.API_BASE_URL}/rbac/me/permissions`, {
      method: 'GET',
      headers,
    });
    const status = res.status;
    const data = status === 304 ? null : await res.json();
    const et = res.headers.get('etag');
    const lastMod = res.headers.get('last-modified');
    return { status, data, etag: et, lastModified: lastMod };
  },
  ttlMs: 60_000,
  throttleMs: 2_000,
  broadcastChannelName: 'cc:permissions',
});

React (Provider + Hook)

Envolva a aplicação com o provider e use o hook para acessar permissões e refresh.

import { PermissionsProvider, usePermissions } from '@admincodeform/permissions-sdk/react';

export function AppRoot() {
  return (
    <PermissionsProvider>
      <App />
    </PermissionsProvider>
  );
}

function MyComponent() {
  const { permissions, isLoading, refresh } = usePermissions();
  // Comentário: `permissions` contém lista normalizada { code: string }
  // Comentário: `refresh()` respeita TTL/throttle e ETag/304
  return null;
}

API (Core)

• permissions.getSnapshot()
• permissions.hasPermission(code)
• permissions.hasAny(codes[])
• permissions.hasAll(codes[])
• permissions.subscribe(listener)
• permissions.refresh({ force? })

Eventos Globais de Autenticação

O SDK escuta automaticamente:

• cc:auth:logged-in → zera snapshot e força refresh
• cc:auth:logged-out → zera snapshot
• cc:auth:organization-switched → força refresh

Os listeners são idempotentes e com anti-loop.

Notas de Implementação

Exports adicionais

• @admincodeform/permissions-sdk/react

  • PermissionsProvider, usePermissions, useHasPermission, useHasPermissions, PermissionGate

• @admincodeform/permissions-sdk/react/router

  • ProtectedRoute (peer: react-router-dom >= 6)

• @admincodeform/permissions-sdk/mui

  • PermissionButton, PermissionIconButton, PermissionTooltip (peer: @mui/material >= 5)

• O SDK utiliza singleton global (via globalThis) para evitar duplicação de estado entre as entradas core e react.

• TTL padrão: 60s. Throttle padrão: 2s. Ajustáveis via config de bootstrap.

• Suporte a ETag/304 para atualizações baratas quando não houver mudanças.