@oondemand/oon-core-front 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,533 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { AxiosInstance } from 'axios';
+
+/** Tipos de campo emitidos pelo `fields` do back (Seção 2.4). */
+type FieldKind = "string" | "number" | "boolean" | "date" | "ref" | "enum" | "currency" | "currencyCode" | "currencyConverted" | "raw";
+/** Metadata de um campo de model, vinda de `metaFields` no back. */
+interface FieldMeta {
+    name: string;
+    kind: FieldKind;
+    label?: string;
+    searchable?: boolean;
+    /** model referenciada quando kind === "ref". */
+    ref?: string;
+    /** valores possíveis quando kind === "enum". */
+    options?: string[];
+    /** moeda base quando kind === "currencyConverted". */
+    base?: string;
+}
+/** Resumo de uma model (resposta de /core/models e /core/models/:name). */
+interface ModelSummary {
+    name: string;
+    singular: string;
+    /** basePath em que o CRUD está montado no back (ex.: "/cotacoes"). */
+    basePath: string;
+    crud: boolean;
+    roles: {
+        read?: string[];
+        write?: string[];
+    };
+    fields: FieldMeta[];
+    searchable: string[];
+}
+interface MenuMeta {
+    label: string;
+    href?: string;
+    icon?: string;
+    section?: string;
+    order?: number;
+    permissions?: string[];
+}
+/** Resposta completa de GET /core/metadata. */
+interface CoreMetadata {
+    service: {
+        name: string;
+        version: string;
+    };
+    models: ModelSummary[];
+    collections: unknown[];
+    documents: unknown[];
+    pipelines: unknown[];
+    integrations: unknown[];
+    features: unknown[];
+    menus: MenuMeta[];
+}
+interface Pagination {
+    currentPage: number;
+    totalPages: number;
+    totalItems: number;
+    itemsPerPage: number;
+}
+interface PaginatedResult<T = Record<string, unknown>> {
+    results: T[];
+    pagination: Pagination;
+}
+interface ListParams {
+    pageIndex?: number;
+    pageSize?: number;
+    searchTerm?: string;
+    /** ex.: "nome.asc" | "criadoEm.desc" */
+    sort?: string;
+    /** filtros adicionais viram query string. */
+    [filter: string]: unknown;
+}
+/** Erro normalizado (errorNormalizer). */
+interface OonError {
+    code: string;
+    message: string;
+    status?: number;
+    details?: unknown;
+    requestId?: string;
+}
+/** Origem de auditoria enviada nos headers x-oon-* das mutações. */
+type AuditOrigin = "datagrid" | "form" | "workflow" | "assistant" | "import" | "integration";
+interface AuditContext {
+    origem?: AuditOrigin;
+    module?: string;
+    entity?: string;
+}
+interface OonUser {
+    tipo: string;
+    nome: string;
+    email: string;
+    [extra: string]: unknown;
+}
+interface OonAppConfig {
+    id: string;
+    name: string;
+    title?: string;
+    logo?: string;
+    favicon?: string;
+    version?: string;
+}
+interface OonApiConfig {
+    baseUrl: string;
+    assistantBaseUrl?: string;
+    meusAppsUrl?: string;
+    /** Prefixo de versão concatenado às chamadas. Default: "". */
+    versionPrefix?: string;
+    timeout?: number;
+}
+interface OonAuthConfig {
+    mode?: "bearer" | "cookie" | "external-sso";
+    /** URL de login externo (Meus Apps) para redirect quando sem token. */
+    loginUrl?: string;
+    /** Nome do query param que carrega o token na volta do SSO. Default: "code". */
+    tokenParam?: string;
+}
+interface OonSecurityConfig {
+    enableRouteGuard?: boolean;
+    enablePermissionGate?: boolean;
+    redactAssistantContext?: boolean;
+    disableConsoleInProduction?: boolean;
+}
+interface OonCoreFrontConfig {
+    app: OonAppConfig;
+    api: OonApiConfig;
+    auth?: OonAuthConfig;
+    theme?: Record<string, unknown>;
+    modules?: OonModule[];
+    /**
+     * Declaração de UI no estilo `central.ui.json` (Seção 9). Atalho para
+     * registrar coleções/documentos/esteiras sem escrever um módulo inteiro.
+     */
+    ui?: OonUiManifest;
+    security?: OonSecurityConfig;
+    /** Elemento DOM onde montar. Default: #root. */
+    rootElementId?: string;
+}
+interface OonRoute {
+    path: string;
+    element: ReactNode;
+    /** rota pública não passa pelo RouteGuard. */
+    public?: boolean;
+    permissions?: string[];
+}
+interface OonMenuItem {
+    label: string;
+    href: string;
+    icon?: ReactNode;
+    section?: string;
+    order?: number;
+    permissions?: string[];
+}
+interface OonModule {
+    id: string;
+    label: string;
+    version?: string;
+    routes?: OonRoute[];
+    menu?: OonMenuItem[];
+    /** views declarativas que o Core transforma em rota + menu. */
+    views?: OonViewDefinition[];
+}
+type CollectionMode = "full" | "minimal" | "dynamic";
+interface OonColumnDef {
+    field: string;
+    label?: string;
+    /** kind sobrescreve o inferido da metadata. */
+    kind?: FieldKind;
+    sortable?: boolean;
+    width?: number;
+}
+interface OonFormFieldDef {
+    field: string;
+    label?: string;
+    kind?: FieldKind;
+    required?: boolean;
+    options?: string[];
+}
+/** Definição de uma coleção nas três formas da Seção 4.4. */
+interface CollectionViewDef {
+    type: "collection";
+    /** id de rota/menu; default = model em minúsculas. */
+    id?: string;
+    model: string;
+    label?: string;
+    path?: string;
+    icon?: ReactNode;
+    section?: string;
+    /** "dynamic" monta tudo a partir de /core/models/:model. */
+    mode?: CollectionMode;
+    /** modo "full": colunas explícitas. */
+    columns?: OonColumnDef[];
+    /** modo "full": campos de formulário explícitos. */
+    form?: OonFormFieldDef[];
+    importExport?: boolean;
+    permissions?: string[];
+}
+interface DocumentViewDef {
+    type: "document";
+    id?: string;
+    model: string;
+    label?: string;
+    path?: string;
+    icon?: ReactNode;
+    section?: string;
+    approval?: boolean;
+    attachments?: boolean;
+    permissions?: string[];
+}
+interface PipelineViewDef {
+    type: "pipeline";
+    id?: string;
+    /** model dos cards (tickets). */
+    model: string;
+    label?: string;
+    path?: string;
+    icon?: ReactNode;
+    section?: string;
+    /** campo do registro que define a etapa/coluna. */
+    stageField?: string;
+    /** etapas fixas; se omitido, derivadas do enum de stageField. */
+    stages?: Array<{
+        id: string;
+        label: string;
+    }>;
+    permissions?: string[];
+}
+interface DashboardViewDef {
+    type: "dashboard";
+    id?: string;
+    label?: string;
+    path?: string;
+    icon?: ReactNode;
+    section?: string;
+    widgets?: DashboardWidgetDef[];
+}
+interface DashboardWidgetDef {
+    id: string;
+    label: string;
+    /** model de onde puxar a contagem/agregação. */
+    model?: string;
+    kind?: "count" | "sum" | "custom";
+    /** campo somado quando kind === "sum". */
+    field?: string;
+    render?: () => ReactNode;
+}
+type OonViewDefinition = CollectionViewDef | DocumentViewDef | PipelineViewDef | DashboardViewDef;
+interface OonUiManifest {
+    views: OonViewDefinition[];
+}
+
+/**
+ * Ponto de entrada único de uma Central (Seção 3.2). O `main.tsx` da Central
+ * só chama isto — não conhece providers, router, auth, layout nem serviços.
+ *
+ *   import { start } from "@oondemand/oon-core-front";
+ *   import { appConfig } from "./central.ui";
+ *   start(appConfig);
+ */
+declare function start(config: OonCoreFrontConfig): void;
+/** Alias namespaced, compatível com a doc (`oonCoreFront.start`). */
+declare const oonCoreFront: {
+    start: typeof start;
+};
+
+/**
+ * Schema do `central.ui.json` (Seção 9 do escopo). É o que o frontend
+ * consumidor gerado pelo `create-central-oon` carrega — declaração pura, sem
+ * código de UI. O Core converte isto em `OonCoreFrontConfig`.
+ */
+interface CentralUiManifest {
+    name: string;
+    slug: string;
+    backend?: {
+        metadataUrl?: string;
+    };
+    navigation?: {
+        mode?: "auto" | "manual";
+    };
+    collections?: Array<{
+        model: string;
+        mode?: CollectionMode;
+        path?: string;
+        label?: string;
+        section?: string;
+    }>;
+    pipelines?: Array<{
+        name?: string;
+        model?: string;
+        mode?: string;
+        stageField?: string;
+        path?: string;
+        label?: string;
+        section?: string;
+    }>;
+    documents?: Array<{
+        model: string;
+        mode?: string;
+        path?: string;
+        label?: string;
+        section?: string;
+        approval?: boolean;
+        attachments?: boolean;
+    }>;
+}
+/** Dados de runtime que o `central.ui.json` não carrega (vêm do .env). */
+interface ManifestRuntime {
+    apiBaseUrl: string;
+    meusAppsUrl?: string;
+    assistantBaseUrl?: string;
+    versionPrefix?: string;
+}
+/** Converte o manifesto declarativo + runtime em config do Core. */
+declare function manifestToConfig(manifest: CentralUiManifest, runtime: ManifestRuntime): OonCoreFrontConfig;
+/**
+ * Bootstrap a partir do `central.ui.json`. É a única linha que o `main.tsx` de
+ * uma Central gerada precisa:
+ *
+ *   import manifest from "../central.ui.json";
+ *   startFromManifest(manifest, { apiBaseUrl: import.meta.env.VITE_API_URL });
+ */
+declare function startFromManifest(manifest: CentralUiManifest, runtime: ManifestRuntime): void;
+
+/**
+ * Helpers declarativos (API pública da Seção 4.3). São identidades tipadas que
+ * fixam o `type` da view — servem para o autocomplete e para registrar a view
+ * num módulo ou no `ui.views` da config.
+ */
+declare function defineCollectionView(def: Omit<CollectionViewDef, "type">): CollectionViewDef;
+declare function defineDocumentView(def: Omit<DocumentViewDef, "type">): DocumentViewDef;
+declare function definePipelineView(def: Omit<PipelineViewDef, "type">): PipelineViewDef;
+declare function defineDashboard(def: Omit<DashboardViewDef, "type">): DashboardViewDef;
+/** Açúcar para declarar um módulo com tipagem. */
+declare function defineOonModule(mod: OonModule): OonModule;
+
+interface CoreCollectionProps {
+    model: string;
+    label?: string;
+    /**
+     * Três formas de declarar a coleção (Seção 4.4):
+     *  - "full"    : colunas + form explícitos (passe `columns` e `form`).
+     *  - "minimal" : só `model`; Core busca a metadata e deriva tudo.
+     *  - "dynamic" : 100% dirigido por /core/models/:model (default).
+     */
+    mode?: CollectionMode;
+    /** basePath do recurso; default vem da metadata da model. */
+    endpoint?: string;
+    columns?: OonColumnDef[];
+    form?: OonFormFieldDef[];
+    importExport?: boolean;
+}
+/**
+ * Componente Core de coleção. Renderiza grid + form de qualquer model do back
+ * sem código de UI por entidade. No modo dinâmico, lê /core/models/:model e
+ * monta colunas, formulário e endpoint a partir da metadata — esse é o
+ * critério de pronto da Fase 3.
+ */
+declare function CoreCollection({ model, label, mode, endpoint, columns, form, importExport }: CoreCollectionProps): react.JSX.Element;
+
+interface CoreDocumentProps {
+    model: string;
+    label?: string;
+    endpoint?: string;
+    columns?: OonColumnDef[];
+    form?: OonFormFieldDef[];
+    /** liga ações de aprovar/reprovar (RESTful: /:id/actions/approve|reject). */
+    approval?: boolean;
+    /** liga gestão de anexos (futuro: /:id/files). */
+    attachments?: boolean;
+}
+/**
+ * Tipo documental. Hoje reusa a coleção genérica (list + CRUD). Quando
+ * `approval` está ligado, expõe o helper `approveDocument` para as ações
+ * RESTful do back (Seção 5.2) — documentos fiscais e cadastrais viram
+ * configuração, não páginas escritas à mão.
+ */
+declare function CoreDocument({ model, label, endpoint, columns, form }: CoreDocumentProps): react.JSX.Element;
+
+interface CorePipelineProps {
+    model: string;
+    label?: string;
+    endpoint?: string;
+    /** campo do registro que define a coluna/etapa. Default: "status". */
+    stageField?: string;
+    /** etapas fixas; se omitido, derivadas do enum de `stageField`. */
+    stages?: Array<{
+        id: string;
+        label: string;
+    }>;
+    /** campo exibido como título do card. Default: primeiro string. */
+    titleField?: string;
+}
+/**
+ * Esteira (kanban) genérica do Core. Agrupa registros por `stageField` em
+ * colunas. As etapas vêm das props ou são derivadas do enum declarado na
+ * metadata da model — nenhuma esteira específica hardcoded.
+ */
+declare function CorePipeline({ model, label, endpoint, stageField, stages, titleField }: CorePipelineProps): react.JSX.Element;
+
+interface CoreIntegrationProps {
+    label?: string;
+}
+/**
+ * Painel de integrações: lista o que o back declarou em /core/integrations e
+ * permite reprocessar via action RESTful (POST /integrations/actions/process-active).
+ */
+declare function CoreIntegration({ label }: CoreIntegrationProps): react.JSX.Element;
+
+interface CoreCurrencyProps {
+    /** model das moedas. Default: "Moeda". */
+    model?: string;
+    label?: string;
+    endpoint?: string;
+    columns?: OonColumnDef[];
+}
+/**
+ * Multi-moedas (módulo de domínio, Seção 4.6/2.11). Lista as moedas e expõe a
+ * ação RESTful de atualizar cotações (POST /<endpoint>/actions/update-rates).
+ */
+declare function CoreCurrency({ model, label, endpoint, columns }: CoreCurrencyProps): react.JSX.Element;
+
+interface CoreAssistantProps {
+    /** code do assistente registrado no back (ex.: "servicos-tomados.revisao"). */
+    assistantCode: string;
+    label?: string;
+    /** entidade de contexto (apenas tipo + id; nada sensível). */
+    entity?: {
+        type: string;
+        id: string;
+    };
+    /** base de assistentes; default usa o mesmo client REST do Core. */
+    endpoint?: string;
+}
+/**
+ * Assistente IA do Core (Seção 2.12 / 6.2). Envia ao back apenas
+ * assistantCode + entity + message — NUNCA chave de IA, modelo ou prompt.
+ * O back resolve modelo, prompt, chave e políticas.
+ */
+declare function CoreAssistant({ assistantCode, label, entity, endpoint }: CoreAssistantProps): react.JSX.Element;
+
+interface CoreDashboardProps {
+    label?: string;
+    widgets?: DashboardWidgetDef[];
+}
+/**
+ * Dashboard do Core: renderiza widgets registrados (count/sum por model ou
+ * render custom). Cache, loading e erro ficam no Core; a Central só declara.
+ */
+declare function CoreDashboard({ label, widgets }: CoreDashboardProps): react.JSX.Element;
+
+interface AuthContextValue {
+    user: OonUser | null;
+    roles: string[];
+    status: "loading" | "authenticated" | "unauthenticated";
+    isAuthenticated: boolean;
+    hasPermission: (permission?: string | string[]) => boolean;
+    logout: () => void;
+}
+declare function useOonAuth(): AuthContextValue;
+
+/**
+ * Esconde a UI quando o usuário não tem a permissão. NÃO é segurança real
+ * (Seção 6.2, item 3) — o back é a autoridade. Serve apenas para não exibir
+ * ações/menus que o usuário não pode usar.
+ */
+declare function PermissionGate({ permission, fallback, children, }: {
+    permission?: string | string[];
+    fallback?: ReactNode;
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * SDK do contrato /core/* (introspecção dirigida por metadata). É o que
+ * permite o modo "dynamic" das coleções: o front monta grid/form/rotas a
+ * partir do que o back descreve, sem código de UI por entidade.
+ */
+interface CoreClient {
+    metadata(): Promise<CoreMetadata>;
+    models(): Promise<ModelSummary[]>;
+    model(name: string): Promise<ModelSummary>;
+    permissions(): Promise<Array<{
+        resource: string;
+        action: string;
+        roles: string[];
+    }>>;
+    menus(): Promise<CoreMetadata["menus"]>;
+}
+
+/**
+ * SDK por recurso (Seção 2.5). Espelha o CRUD gerado pelo back em `basePath`:
+ *   GET /            -> list (paginado)
+ *   GET /:id         -> get
+ *   POST /           -> create
+ *   PUT /:id         -> update
+ *   PATCH /:id       -> patch
+ *   DELETE /:id      -> delete
+ *   POST /import     -> importMany
+ *   GET /export      -> exportAll
+ *
+ * O back devolve registro único na chave do singular (`{ [singular]: {...} }`);
+ * `unwrap` extrai o primeiro valor não-meta para o consumidor não precisar
+ * conhecer o singular.
+ */
+interface ResourceClient<T = Record<string, unknown>> {
+    list(params?: ListParams): Promise<PaginatedResult<T>>;
+    get(id: string): Promise<T>;
+    create(body: Partial<T>, audit?: AuditContext): Promise<T>;
+    update(id: string, body: Partial<T>, audit?: AuditContext): Promise<T>;
+    patch(id: string, body: Partial<T>, audit?: AuditContext): Promise<T>;
+    delete(id: string, audit?: AuditContext): Promise<T>;
+    importMany(rows: unknown[], audit?: AuditContext): Promise<{
+        inserted?: number;
+        [k: string]: unknown;
+    }>;
+    exportAll(params?: ListParams): Promise<T[]>;
+}
+
+interface ApiContextValue {
+    http: AxiosInstance;
+    core: CoreClient;
+    resource: <T = Record<string, unknown>>(basePath: string) => ResourceClient<T>;
+}
+declare function useOonApi(): ApiContextValue;
+/** Cliente de um recurso, memoizado pelo basePath. */
+declare function useOonResource<T = Record<string, unknown>>(basePath: string): ResourceClient<T>;
+/** Metadata completa do back (cache de 5 min). */
+declare function useCoreMetadata(): _tanstack_react_query.UseQueryResult<NoInfer<CoreMetadata>, Error>;
+/** Descrição de uma model específica — base do modo "dynamic". */
+declare function useModelSchema(name: string): _tanstack_react_query.UseQueryResult<NoInfer<ModelSummary>, Error>;
+
+export { type CentralUiManifest, type CollectionMode, type CollectionViewDef, CoreAssistant, CoreCollection, CoreCurrency, CoreDashboard, CoreDocument, CoreIntegration, type CoreMetadata, CorePipeline, type DashboardViewDef, type DashboardWidgetDef, type DocumentViewDef, type FieldKind, type FieldMeta, type ListParams, type ManifestRuntime, type ModelSummary, type OonApiConfig, type OonAppConfig, type OonAuthConfig, type OonColumnDef, type OonCoreFrontConfig, type OonError, type OonFormFieldDef, type OonMenuItem, type OonModule, type OonRoute, type OonSecurityConfig, type OonUiManifest, type OonUser, type OonViewDefinition, type PaginatedResult, type Pagination, PermissionGate, type PipelineViewDef, defineCollectionView, defineDashboard, defineDocumentView, defineOonModule, definePipelineView, manifestToConfig, oonCoreFront, start, startFromManifest, useCoreMetadata, useModelSchema, useOonApi, useOonAuth, useOonResource };