@microteia/console 2.10.0 → 2.18.0

package/lib/console/environment.d.ts

@@ -29,13 +29,14 @@ export interface Environment {
         deployed: string | null;
     };
     /**
-     * Quais Cloud Functions de EXTENSÃO já foram deployadas neste projeto. Fica aqui, e não no banco,
-     * porque é estado da instalação e não do escritório — e é o que permite ao `provision` deployar só o
-     * delta e reconhecer o que ficou órfão depois de uma desinstalação.
+     * Quais Cloud Functions de EXTENSÃO já foram deployadas neste projeto, e de QUEM. Fica aqui, e não no
+     * banco, porque é estado da instalação e não do escritório — e é o que permite ao `provision`
+     * deployar só o delta e reconhecer o que ficou órfão depois de uma desinstalação.
      *
-     * Uma lista num escalar separado por vírgula porque o leitor de YAML daqui entende mapas de dois
-     * níveis e escalares, e trazer sequências para guardar meia dúzia de nomes seria pagar caro pela
-     * generalidade.
+     * `nome@pluginId` separado por vírgula — ver `appliedFunctions.ts`, que o lê e o escreve. O escalar é
+     * porque o leitor de YAML daqui entende mapas de dois níveis e escalares, e trazer sequências para
+     * guardar meia dúzia de pares seria pagar caro pela generalidade. Uma entrada sem `@` é o que uma
+     * instalação anterior ao dono gravou, e continua valendo.
      */
     backend: {
         functions: string | null;

package/lib/console/firestoreRest.d.ts

@@ -20,8 +20,26 @@ export type FirestoreTypedValue = {
     stringValue: string;
 } | {
     timestampValue: string;
+} | {
+    integerValue: string;
+} | {
+    arrayValue: {
+        values: FirestoreTypedValue[];
+    };
+} | {
+    mapValue: {
+        fields: Record<string, FirestoreTypedValue>;
+    };
 };
 export declare const asString: (value: string) => FirestoreTypedValue;
+/**
+ * Inteiro como INTEIRO. A REST o transporta em string — é assim que ela representa um int64 sem perder
+ * precisão em JSON —, mas o campo gravado é numérico, e é isso que faz o outro lado do produto poder
+ * compará-lo em vez de tentar convertê-lo.
+ */
+export declare const asInteger: (value: number) => FirestoreTypedValue;
+export declare const asArray: (values: FirestoreTypedValue[]) => FirestoreTypedValue;
+export declare const asMap: (fields: Record<string, FirestoreTypedValue>) => FirestoreTypedValue;
 /**
  * Data como DATA, e não como texto que se parece com uma.
  *
@@ -37,3 +55,12 @@ export declare const asTimestamp: (value: Date) => FirestoreTypedValue;
  * Console carimbar o estado sem conhecer (nem arriscar reescrever) o pacote inteiro que vive ao lado.
  */
 export declare const patchMapField: (projectId: string, path: string, field: string, entries: Record<string, FirestoreTypedValue>) => Promise<void>;
+/**
+ * Grava um documento inteiro, com `updateMask` listando cada campo escrito.
+ *
+ * A máscara é explícita e não omitida de propósito: sem ela o comportamento de um PATCH depende de o
+ * documento existir, e o que se quer aqui é convergência — o que é escrito passa a valer, e nada de uma
+ * execução anterior sobra. Como todos os campos são escritos a cada vez, a máscara completa é também o
+ * que apaga o que deixou de ser verdade.
+ */
+export declare const patchFields: (projectId: string, path: string, fields: Record<string, FirestoreTypedValue>) => Promise<void>;

package/lib/console/firestoreRest.js

@@ -108,6 +108,14 @@ export const listDocuments = async (projectId, path) => {
 };
 export const documentId = (document) => document.name.slice(document.name.lastIndexOf('/') + 1);
 export const asString = (value) => ({ stringValue: value });
+/**
+ * Inteiro como INTEIRO. A REST o transporta em string — é assim que ela representa um int64 sem perder
+ * precisão em JSON —, mas o campo gravado é numérico, e é isso que faz o outro lado do produto poder
+ * compará-lo em vez de tentar convertê-lo.
+ */
+export const asInteger = (value) => ({ integerValue: String(value) });
+export const asArray = (values) => ({ arrayValue: { values } });
+export const asMap = (fields) => ({ mapValue: { fields } });
 /**
  * Data como DATA, e não como texto que se parece com uma.
  *
@@ -129,3 +137,18 @@ export const patchMapField = async (projectId, path, field, entries) => {
         body: { fields: { [field]: { mapValue: { fields: entries } } } },
     });
 };
+/**
+ * Grava um documento inteiro, com `updateMask` listando cada campo escrito.
+ *
+ * A máscara é explícita e não omitida de propósito: sem ela o comportamento de um PATCH depende de o
+ * documento existir, e o que se quer aqui é convergência — o que é escrito passa a valer, e nada de uma
+ * execução anterior sobra. Como todos os campos são escritos a cada vez, a máscara completa é também o
+ * que apaga o que deixou de ser verdade.
+ */
+export const patchFields = async (projectId, path, fields) => {
+    await request(projectId, path, {
+        method: 'PATCH',
+        query: { 'updateMask.fieldPaths': Object.keys(fields) },
+        body: { fields },
+    });
+};

package/lib/console/functionGate.d.ts

@@ -0,0 +1,198 @@
+/**
+ * O portão de instalação, conferido na FONTE.
+ *
+ * `forInstalledExtension` é a metade da retirada que age no instante certo: a Cloud Function é do
+ * PROJETO e a instalação da extensão é do ESCRITÓRIO, então um `onDocumentWritten('tenants/{tenantId}/…')`
+ * declarado por uma extensão dispara para TODOS os escritórios do projeto — os que nunca a instalaram, e
+ * o que a desinstalou enquanto outro a mantém. Nesse último caso `--prune` não pode ajudar: a function
+ * tem de continuar no ar, porque alguém ainda precisa dela.
+ *
+ * Só que nada cobrava o portão. O `create function` o escrevia no molde, e era só isso: nenhuma
+ * verificação do empacotamento, do deploy ou do provisionamento olhava a fonte. Um gatilho sem portão
+ * passava por tudo e ia para o ar — e o sintoma dele é o pior que existe, porque não é uma falha: é
+ * código de uma extensão que ninguém tem mais rodando sobre os dados de quem nunca a pediu, sem erro em
+ * lugar nenhum.
+ *
+ * É recusa e não aviso pelo mesmo motivo do nome de function repetido (`functionProblems`): o defeito é
+ * invisível depois de instalado, e um aviso na saída de um deploy é lido uma vez.
+ *
+ * A análise é por texto, no idioma dos outros leitores de fonte do Console (`callableFunctionNames`,
+ * `declaredParametersIn`). Ela erra para o lado ALTO — o que ela não entende ela recusa —, e é por isso
+ * que o portão declarado num identificador ao lado é reconhecido: recusar código correto é o que ensina
+ * a desligar a verificação.
+ */
+/**
+ * Os construtores de gatilho de Firestore.
+ *
+ * São os únicos eventos cujo caminho carrega `{tenantId}`, e portanto os únicos para os quais o portão
+ * existe. Um `onSchedule` ou um `onMessagePublished` não tem escritório de onde perguntar — envolvê-los
+ * no portão os deixaria permanentemente inertes, porque ele falha FECHADO. Eles ficam de fora desta
+ * verificação de propósito: exigir deles um portão que não funciona seria trocar um defeito por outro.
+ */
+export declare const TENANT_TRIGGER_CONSTRUCTORS: string[];
+/**
+ * Os construtores cujo evento NÃO carrega escritório no caminho.
+ *
+ * Para eles as duas saídas do autor eram erradas, e é isso que faz deles uma recusa e não um aviso: sem
+ * portão a function age sobre o projeto inteiro; COM portão ela nunca roda — nem enquanto a extensão está
+ * instalada —, porque `forInstalledExtension` falha FECHADO e nunca acha o `{tenantId}` que não existe.
+ * Um autor que seguisse a orientação genérica "envolva o handler no portão" produzia uma function que
+ * passava no deploy, não acusava nada e nunca fazia nada.
+ *
+ * A resposta é o laço por escritório (`forEachInstalledOffice`), e é por existir uma resposta que a
+ * recusa é honesta.
+ *
+ * A lista é EXPLÍCITA, e não "tudo o que não é gatilho de documento": o que não se conhece não se recusa.
+ * O RTDB fica de fora de propósito — o caminho dele TEM parâmetros, então um `{tenantId}` ali é possível
+ * —, e a plataforma não usa RTDB em lugar nenhum.
+ */
+export declare const UNSCOPED_TRIGGER_CONSTRUCTORS: string[];
+/**
+ * A fonte sem comentário nenhum, com as strings intactas.
+ *
+ * O JSDoc que o molde escreve CITA `forInstalledExtension` — é ali que ele explica o portão. Sem esta
+ * limpeza, um gatilho que perdesse a chamada e mantivesse o comentário passaria na verificação, o que é
+ * o caso exato que ela existe para pegar.
+ */
+export declare const withoutComments: (source: string) => string;
+export interface TriggerDeclaration {
+    /** O nome declarado — é por ele que se sabe se o `index.ts` o exporta. */
+    name: string;
+    /** O construtor usado. Aparece na mensagem: é ele que explica por que o portão é devido. */
+    trigger: string;
+    /** O id que `forInstalledExtension` recebeu, ou `null` quando o portão não está lá. */
+    gatedFor: string | null;
+    /** Todos os ids que as guardas daquele gatilho recebem — a comum guarda mais de um. */
+    guards: string[];
+}
+/** Os gatilhos de Firestore declarados numa fonte, com o estado do portão de cada um. */
+export declare const triggerDeclarations: (rawSource: string) => TriggerDeclaration[];
+/**
+ * As functions sem escritório no evento, e o id que o laço por escritório recebeu no ARQUIVO.
+ *
+ * O alcance é o arquivo, e não os parênteses da chamada — a diferença é deliberada. O portão de um
+ * gatilho de documento embrulha AQUELE handler, então ele tem de estar ali; o laço, ao contrário, roda
+ * DENTRO do handler e pode estar algumas chamadas abaixo, num `syncOffice(tenantId)` que o próprio autor
+ * escreveu. Exigi-lo nos parênteses recusaria código correto, e a verificação que erra assim é a que
+ * ensina a próxima pessoa a desligá-la.
+ *
+ * O preço é conhecido: dois agendados no mesmo arquivo, um com laço e outro sem, passam os dois. É menos
+ * grave que o inverso, e está dito.
+ */
+export declare const unscopedDeclarations: (rawSource: string) => TriggerDeclaration[];
+/**
+ * As callables declaradas, e o id que a guarda delas recebeu no ARQUIVO.
+ *
+ * O alcance é o arquivo pela mesma razão do laço por escritório: a guarda roda DENTRO do handler (ela
+ * precisa do `request`), e o guia manda o autor manter o handler fino, com a decisão num arquivo ao
+ * lado. Exigi-la nos parênteses recusaria justamente o código que o guia pede.
+ */
+export declare const callableDeclarations: (rawSource: string) => TriggerDeclaration[];
+/**
+ * O que uma origem de functions precisa ter para ser conferida. É a forma de `FunctionSource`, declarada
+ * aqui em vez de importada: assim este módulo se testa sozinho, sem montar diretório nenhum.
+ */
+export interface GateSubject {
+    label: string;
+    /** `functions/` é comum a várias extensões, e não tem uma instalação de onde perguntar. */
+    shared: boolean;
+    exported: string[];
+    triggers: TriggerDeclaration[];
+    /** As functions cujo evento não carrega escritório: o agendado, a fila, o HTTP, o Storage. */
+    unscoped: TriggerDeclaration[];
+    /** Quem cada function comum declara servir. Vazio numa origem de extensão. */
+    serves: Record<string, string[]>;
+    /** As callables declaradas, com o estado da guarda de cada uma. */
+    callableGuards: TriggerDeclaration[];
+}
+/**
+ * Gatilho de extensão sem portão.
+ *
+ * `functions/` fica de fora porque ali a pergunta não tem resposta: a function é comum a várias
+ * extensões, nenhuma a reivindica, e não há um id para o portão receber. É lacuna conhecida e tem
+ * endereço próprio — enquanto ela não fechar, exigir aqui um portão impossível seria recusar a única
+ * forma que a plataforma oferece para uma function compartilhada.
+ */
+export declare const ungatedTriggerProblems: (subjects: GateSubject[]) => string[];
+/**
+ * Function de extensão cujo evento não tem escritório, e que não passa pelo laço.
+ *
+ * A recusa vem acompanhada do substituto porque sem ele ela seria só uma porta fechada: o laço por
+ * escritório (`forEachInstalledOffice`) existe justamente para este caso, e é ele que a mensagem nomeia.
+ *
+ * `functions/` fica de fora pelo mesmo motivo de sempre: a comum não tem um id de extensão para dar ao
+ * laço. Quem responde por ela é a declaração de quem ela serve.
+ */
+export declare const unscopedTriggerProblems: (subjects: GateSubject[]) => string[];
+/**
+ * Gatilho de uma function COMUM que declara quem serve, e não guarda ninguém.
+ *
+ * A comum ficava fora desta cobrança porque não havia id para dar à guarda: nenhuma extensão pode
+ * reivindicá-la. `microteia.serves` resolve exatamente isso — a partir dela existem ids, e a partir dos
+ * ids a cobrança passa a ser possível. Um gatilho comum sem guarda dispara para todo escritório do
+ * projeto, e é o mesmo defeito do gatilho de extensão sem portão, com um alcance maior.
+ *
+ * A comum SEM declaração continua de fora, e é deliberado: cobrar dela uma guarda sem ter ids a oferecer
+ * seria fechar a porta sem abrir nenhuma. O que ela recebe é o relato do provisionamento.
+ *
+ * A segunda recusa é a guarda que nomeia extensão que a function não declara servir: as duas listas
+ * respondem à mesma pergunta em dois lugares, e divergirem faz uma delas mentir — a `serves` decide a
+ * retirada, a guarda decide a execução, e a function passaria a agir onde não pode ser retirada.
+ */
+export declare const unguardedSharedProblems: (subjects: GateSubject[]) => string[];
+/**
+ * Callable de extensão sem a guarda de instalação.
+ *
+ * "Uma callable órfã é inerte" era verdade de INTERFACE, e não de segurança — e era a frase que o guia
+ * dizia. O deploy concede a `allUsers` o papel `roles/run.invoker` em cada callable; o que sobra depois é
+ * a validação do token do Firebase. Então a tela ir embora com a extensão não fecha nada: o endpoint
+ * segue no ar aceitando o token de QUALQUER usuário do projeto, de qualquer escritório, tendo ou não a
+ * extensão.
+ *
+ * E o escritório chega no PAYLOAD, porque `useCallable` manda só o que a tela passou. Sem a guarda, um
+ * usuário do escritório A chama a function apontando para o B — e o molde gerado conferia apenas se
+ * havia `request.auth`.
+ *
+ * A comum fica de fora: `requireInstalledExtension` pede UM id, e a comum serve vários. É lacuna
+ * conhecida e está registrada — a guarda "alguma das que eu sirvo" existe para gatilho, não para
+ * callable.
+ */
+export declare const unguardedCallableProblems: (subjects: GateSubject[]) => string[];
+export interface MisgatedTrigger {
+    /** A origem, como as mensagens a citam. */
+    label: string;
+    name: string;
+    /** O id que a guarda recebeu. */
+    gatedFor: string;
+    /** O id da extensão que reivindica a function. */
+    owner: string;
+    /** Qual guarda recebeu o id errado — é ela que o autor tem de corrigir. */
+    via: string;
+}
+/**
+ * Portão aberto para o id ERRADO.
+ *
+ * É o defeito do copiar-e-colar entre extensões, e o sintoma dele é o oposto do gatilho sem portão: a
+ * function sobe, o gatilho dispara, e o handler nunca roda em escritório nenhum. Nada falha — a extensão
+ * apenas não faz o que promete, e a causa está numa string.
+ *
+ * Devolve os casos, e não as frases, porque quem chama precisa dos dois: a mensagem para relatar e o id
+ * da extensão para pendurar. Deduzir o id de volta a partir do texto é o que faz um relatório recusar a
+ * extensão errada quando o nome de uma aparece dentro da mensagem de outra.
+ *
+ * Só se pergunta quando o nome tem UM reivindicante: com dois, `functionClaimProblems` já recusou antes,
+ * e apontar um deles como o dono certo seria inventar uma resposta.
+ */
+export declare const misgatedTriggers: (subjects: GateSubject[], claimants: Map<string, string>) => MisgatedTrigger[];
+/** Como uma guarda de id errado aparece num relatório. */
+export declare const describeMisgated: (entry: MisgatedTrigger) => string;
+/**
+ * Quem reivindica cada nome, quando é um só. Duas extensões pedindo o mesmo nome é problema de outra
+ * verificação, e o nome sai daqui em vez de receber um dono escolhido a esmo.
+ */
+export declare const singleClaimants: (claims: {
+    pluginId: string;
+    backend: {
+        functions?: string[];
+    };
+}[]) => Map<string, string>;