@microteia/console 2.7.0

package/lib/console/deployFunctions.js

@@ -0,0 +1,204 @@
+import { stripVTControlCharacters } from 'node:util';
+import { capture, sleep } from '../shared/run.js';
+import { blank, failure, info, pending, success } from '../shared/ui.js';
+import { FIREBASE_BIN } from './firebaseCli.js';
+const NOTICES = [
+    {
+        title: /DEPRECATION NOTICE/,
+        body: /functions[.:]config|Runtime Config|params package|config-env/,
+        summary: 'this project still holds legacy functions:config values. They keep working, but Firebase'
+            + ' shuts Runtime Config down in March 2027 and deploys that read it stop working then.'
+            + ' "firebase functions:config:get" lists what is there.',
+    },
+];
+export const stripNotices = (text) => {
+    const lines = text.split('\n');
+    const kept = [];
+    const summaries = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const notice = NOTICES.find((candidate) => candidate.title.test(lines[index]));
+        if (notice === undefined) {
+            kept.push(lines[index]);
+            continue;
+        }
+        summaries.push(notice.summary);
+        index += 1;
+        while (index < lines.length && (lines[index].trim() === '' || notice.body.test(lines[index]))) {
+            index += 1;
+        }
+        index -= 1;
+    }
+    return { text: kept.join('\n'), summaries };
+};
+/**
+ * A linha que EXPLICA a falha, tirada da saída do `firebase`.
+ *
+ * Existe porque imprimir só `fail  [13/23] auditNestedEntityChange` não deixa nada a fazer para quem
+ * está instalando: se a segunda passada resolver, o motivo é descartado e nunca chega a ser visto; se
+ * não resolver, ele só aparece no fim, depois de mais dez minutos de deploy. O motivo tem de sair no
+ * momento da falha.
+ *
+ * A escolha é por QUANTO a linha informa, e não por onde ela está. Nem a primeira nem a última
+ * servem: uma falha real imprime três coisas parecidas em sequência — quem falhou
+ * (`failed to create function <nome>`), por que falhou (`HTTP Error: 400, Invalid trigger`) e o
+ * epílogo (`There was an error deploying functions`), e a ordem entre as duas primeiras varia. Por
+ * posição, sempre se perde uma das duas: pela última vinha o epílogo, pela primeira viria o nome de
+ * quem falhou — que o `fail` da linha de cima já disse.
+ */
+const REASON_LIMIT = 240;
+/** Carrega a CAUSA: é ela que diz algo que o resto da saída não diz. */
+const CAUSE = /(^|\s)(Error:|HTTP Error|functions\[|✖)/;
+/** Só nomeia quem falhou. Vale como motivo apenas quando a causa não foi impressa. */
+const SUBJECT = /failed to (create|update|delete)/;
+/** O epílogo do `firebase`: verdadeiro em toda falha e específico em nenhuma. */
+const EPILOGUE = /^Error: There was an error deploying functions/;
+export const failureReason = (output) => {
+    const lines = stripVTControlCharacters(output)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '');
+    const chosen = lines.find((line) => CAUSE.test(line) && !EPILOGUE.test(line))
+        ?? lines.find((line) => SUBJECT.test(line))
+        ?? lines.find((line) => EPILOGUE.test(line))
+        ?? lines[lines.length - 1]
+        ?? 'no output from firebase';
+    return chosen.length > REASON_LIMIT ? `${chosen.slice(0, REASON_LIMIT - 1)}…` : chosen;
+};
+const TERMINAL_FAILURES = [
+    {
+        match: /Aborting because deletion cannot proceed in non-interactive mode/,
+        hint: [
+            'The project holds a copy of this function that the source no longer declares — almost always',
+            'a leftover in a region the package moved away from. The Firebase CLI will not deploy over it',
+            'and cannot ask for permission here, so it refuses. Delete the old copy:',
+            '  microteia deploy --prune',
+        ],
+    },
+    {
+        match: /does not have a default and cannot be answered in non-interactive mode/,
+        hint: [
+            'The Firebase CLI needed an answer and this deploy has no terminal to ask it. Run the same',
+            'deploy by hand once, from the installation directory, answer the question, and then run',
+            '"microteia deploy" again.',
+        ],
+    },
+];
+export const terminalFailure = (output) => {
+    const clean = stripVTControlCharacters(output);
+    return TERMINAL_FAILURES.find((candidate) => candidate.match.test(clean));
+};
+/**
+ * O deploy é UMA A UMA, e não `--only functions` de uma vez, porque em lote ele estoura a quota de
+ * CPU do projeto — o motivo pelo qual `scripts/deploy-functions-individually.cjs` existe deste lado.
+ * O cliente bate exatamente na mesma parede, com a diferença de que ele não tem o script.
+ *
+ * A segunda passada não é teimosia: numa instalação nova as identidades de serviço do Pub/Sub e do
+ * Eventarc são criadas DURANTE o primeiro deploy e não propagam a tempo, então toda function de
+ * gatilho falha enquanto as callables sobem normalmente. Repetir resolve, e sem isso a primeira
+ * instalação parece quebrada quando está apenas incompleta.
+ */
+const deployOne = async (name, options) => {
+    const args = ['deploy', '--only', `functions:${name}`, '--project', options.projectId];
+    if (options.force)
+        args.push('--force');
+    const startedAt = Date.now();
+    const result = await capture(FIREBASE_BIN, args, { cwd: options.cwd });
+    const cleaned = stripNotices(`${result.stdout}${result.stderr}`);
+    return {
+        ok: result.code === 0,
+        output: cleaned.text.trim(),
+        notices: cleaned.summaries,
+        seconds: Math.round((Date.now() - startedAt) / 1000),
+    };
+};
+export const deployFunctionsOneByOne = async (names, options) => {
+    const deployed = [];
+    const failed = [];
+    const notices = new Set();
+    let remaining = names;
+    for (let pass = 1; pass <= 2 && remaining.length > 0; pass += 1) {
+        if (pass === 2) {
+            info(`\n  Retrying ${remaining.length} function(s). On a new project the Pub/Sub and Eventarc`);
+            info('  service identities are created during the first deploy and do not propagate in time.');
+        }
+        else if (options.force) {
+            // Só na PRIMEIRA instalação, que é o que `force` significa: é ali que o Firebase provisiona build
+            // e Artifact Registry, e a primeira function leva vários minutos. Dizer isso ANTES é o que separa
+            // "demorado" de "travado" para quem está olhando. Num `provision` de projeto já montado a dica
+            // seria falsa, e por isso ela não aparece lá.
+            info(`  the first of the ${remaining.length} takes the longest — on a new project Firebase sets`);
+            info('  up the build infrastructure before it can deploy anything.');
+        }
+        const retryable = [];
+        for (let index = 0; index < remaining.length; index += 1) {
+            const name = remaining[index];
+            const label = `[${index + 1}/${remaining.length}] ${name}`;
+            pending(label);
+            const { ok, output, notices: given, seconds } = await deployOne(name, options);
+            for (const notice of given)
+                notices.add(notice);
+            if (ok) {
+                success(`${label} (${seconds}s)`);
+                deployed.push(name);
+            }
+            else {
+                const terminal = terminalFailure(output);
+                const reason = failureReason(output);
+                failure(`${label} (failed after ${seconds}s)`);
+                // O motivo AGORA, não só no relatório final: numa instalação nova as functions de gatilho
+                // falham na primeira passada por propagação de identidade de serviço, a segunda resolve, e sem
+                // esta linha quem instala vê um "fail" que nunca é explicado.
+                info(`        ${reason}`);
+                if (terminal === undefined && pass === 1) {
+                    info('        retrying at the end of this pass');
+                    retryable.push(name);
+                }
+                else {
+                    if (terminal !== undefined)
+                        info('        repeating this does not change the answer');
+                    failed.push({
+                        name,
+                        output,
+                        reason,
+                        terminal: terminal !== undefined,
+                        hint: terminal?.hint ?? [],
+                    });
+                }
+            }
+            if (index < remaining.length - 1 && options.delaySeconds > 0) {
+                await sleep(options.delaySeconds);
+            }
+        }
+        remaining = retryable;
+    }
+    return { deployed, failed, notices: [...notices] };
+};
+/**
+ * O relatório do que não subiu, no fim do comando.
+ *
+ * Mora aqui, e não em cada comando, porque `deploy` e `provision` imprimiam o mesmo bloco escrito
+ * duas vezes — e a cauda de 12 linhas dos dois mostrava o rodapé do aviso de descontinuação, não o
+ * erro. A dica sai UMA vez por motivo distinto: oito functions barradas pela mesma região antiga são
+ * um problema, não oito.
+ */
+const TAIL_LINES = 12;
+export const reportFailures = (failures) => {
+    const hints = new Set();
+    for (const entry of failures) {
+        failure(entry.name);
+        info(entry.output.split('\n').slice(-TAIL_LINES).map((line) => `      ${line}`).join('\n'));
+        if (entry.hint.length > 0)
+            hints.add(entry.hint.join('\n'));
+    }
+    for (const hint of hints) {
+        blank();
+        for (const line of hint.split('\n'))
+            info(`  ${line}`);
+    }
+};
+export const reportNotices = (notices) => {
+    for (const notice of notices) {
+        blank();
+        info(`  Note: ${notice}`);
+    }
+};

package/lib/console/environment.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Um Environment é UMA instalação da Microteia associada a UM projeto Firebase. Nada além disso por
+ * enquanto: organização, staging e promoção entre ambientes são conceitos que ainda não existem, e
+ * inventá-los agora seria decidir sem saber.
+ */
+export interface Environment {
+    project: {
+        name: string;
+    };
+    environment: {
+        id: string;
+        name: string;
+    };
+    firebase: {
+        projectId: string | null;
+        region: string;
+    };
+    /**
+     * `version` é o kernel EM VIGOR nesta instalação — quem o grava é o `unpack`, que é o comando que o
+     * põe no lugar. `deployed` é o que já foi publicado no projeto, gravado pelo `deploy`.
+     *
+     * São dois porque a separação entre `unpack` e `deploy` é o contrato: existe um intervalo legítimo em
+     * que o pacote está no lugar e não foi publicado. Um campo só mentia numa das duas pontas — e mentia
+     * na que se olha, porque o `MICROTEIA.md` reescrito pelo `unpack` já anunciava a versão nova enquanto
+     * o `microteia.yaml` ao lado dele seguia na anterior.
+     */
+    kernel: {
+        version: string | null;
+        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.
+     *
+     * 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.
+     */
+    backend: {
+        functions: string | null;
+        /**
+         * Uma impressão digital por parâmetro de backend já aplicado (`NOME:digest`), para o
+         * provisionamento reconhecer o valor que foi preenchido ou trocado DEPOIS do deploy — ver
+         * `backendParameters.ts`. Sem isso, a function deployada continua com o valor anterior e nenhum
+         * comando repara nisso.
+         */
+        parameters: string | null;
+        /**
+         * Os índices compostos declarados por causa de uma extensão — ver `backendIndexes.ts`. Fica na
+         * RAIZ porque tem de sobreviver ao `unpack`, que apaga `.microteia/install/` inteiro e devolve o
+         * `firestore.indexes.json` do pacote, que é só a baseline.
+         */
+        indexes: string | null;
+    };
+}
+export declare const ENVIRONMENT_FILE = "microteia.yaml";
+export declare const parseEnvironment: (source: string) => Environment;
+export declare const serializeEnvironment: (environment: Environment) => string;
+export declare const readEnvironment: (path: string) => Promise<Environment>;
+export declare const writeEnvironment: (path: string, environment: Environment) => Promise<void>;
+export declare const slug: (value: string) => string;

package/lib/console/environment.js

@@ -0,0 +1,151 @@
+import { readFile, writeFile } from 'node:fs/promises';
+export const ENVIRONMENT_FILE = 'microteia.yaml';
+/**
+ * O YAML aqui é um SUBCONJUNTO deliberado: mapas de dois níveis com valores escalares, que é a forma
+ * exata deste arquivo. Não há biblioteca de YAML no repositório, e trazer uma para ler quatro seções
+ * seria pagar uma dependência pela generalidade que não vamos usar. O que o leitor não entende ele
+ * REJEITA com o número da linha, em vez de adivinhar.
+ */
+const unquote = (raw) => {
+    const value = raw.trim();
+    if (value === '' || value === 'null' || value === '~')
+        return null;
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+    return value;
+};
+const needsQuotes = (value) => value === ''
+    || /^[-?:,[\]{}#&*!|>'"%@`]/.test(value)
+    || value.includes(': ')
+    || value.includes(' #')
+    || /^(true|false|null|yes|no|on|off)$/i.test(value)
+    || /^-?\d+(\.\d+)?$/.test(value)
+    || value.trim() !== value;
+const quote = (value) => {
+    if (value === null)
+        return 'null';
+    if (!needsQuotes(value))
+        return value;
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+};
+export const parseEnvironment = (source) => {
+    const sections = new Map();
+    let current = null;
+    const lines = source.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        // O comentário pode estar INDENTADO: o arquivo que este módulo gera tem um dentro da seção
+        // `firebase`, e olhar só a coluna zero faria o leitor rejeitar o que ele mesmo escreveu.
+        const withoutComment = line.trim().startsWith('#') ? '' : line;
+        if (withoutComment.trim() === '')
+            continue;
+        const topLevel = withoutComment.match(/^([A-Za-z][A-Za-z0-9_]*):\s*$/);
+        if (topLevel !== null) {
+            current = new Map();
+            sections.set(topLevel[1], current);
+            continue;
+        }
+        const entry = withoutComment.match(/^ {2}([A-Za-z][A-Za-z0-9_]*):\s*(.*)$/);
+        if (entry !== null) {
+            if (current === null) {
+                throw new Error(`${ENVIRONMENT_FILE} line ${index + 1}: entry outside of any section.`);
+            }
+            current.set(entry[1], unquote(entry[2]));
+            continue;
+        }
+        throw new Error(`${ENVIRONMENT_FILE} line ${index + 1}: unsupported syntax: ${line.trim()}`);
+    }
+    const required = (section, key) => {
+        const value = sections.get(section)?.get(key);
+        if (value === undefined || value === null || value === '') {
+            throw new Error(`${ENVIRONMENT_FILE} is missing ${section}.${key}.`);
+        }
+        return value;
+    };
+    const optional = (section, key) => sections.get(section)?.get(key) ?? null;
+    return {
+        project: { name: required('project', 'name') },
+        environment: {
+            id: required('environment', 'id'),
+            name: required('environment', 'name'),
+        },
+        firebase: {
+            projectId: optional('firebase', 'projectId'),
+            region: required('firebase', 'region'),
+        },
+        kernel: {
+            version: optional('kernel', 'version'),
+            deployed: optional('kernel', 'deployed'),
+        },
+        backend: {
+            functions: optional('backend', 'functions'),
+            parameters: optional('backend', 'parameters'),
+            indexes: optional('backend', 'indexes'),
+        },
+    };
+};
+export const serializeEnvironment = (environment) => `# Microteia installation.
+#
+# Created by "microteia init" and completed by "microteia connect" and "microteia deploy".
+# It describes ONE installation bound to ONE Firebase project. It holds no credentials and is safe
+# to keep next to your own Cloud Functions — but it is specific to this installation, so it does not
+# belong in a shared repository.
+
+project:
+  name: ${quote(environment.project.name)}
+
+environment:
+  id: ${quote(environment.environment.id)}
+  name: ${quote(environment.environment.name)}
+
+firebase:
+  projectId: ${quote(environment.firebase.projectId)}
+  # The region the kernel is compiled for. Cloud Functions are pinned to it, and Firestore must be
+  # in the same region or its triggers will never fire. Changing it here does not move anything.
+  region: ${quote(environment.firebase.region)}
+
+kernel:
+  # The version in place in this installation, written by "microteia unpack".
+  version: ${quote(environment.kernel.version)}
+  # The version already published to the Firebase project, written by "microteia deploy". It trails
+  # the one above between taking a package and publishing it, which is what those two commands are
+  # separate for.
+  deployed: ${quote(environment.kernel.deployed)}
+
+backend:
+  # Cloud Functions deployed because an installed extension asked for them. Managed by
+  # "microteia provision" — editing it by hand only makes the next run deploy or keep the wrong set.
+  functions: ${quote(environment.backend.functions)}
+  # A fingerprint of each backend setting already applied from .env.<projectId> (next to this file).
+  # It is how "microteia provision" notices a setting filled in after the deploy and redeploys the
+  # functions that carry it. It holds no value, only a salted digest of each one — editing it by hand only makes
+  # the next run redeploy, or skip, the wrong set.
+  parameters: ${quote(environment.backend.parameters)}
+  # Composite indexes declared because an installed extension asked for them. It has to live here,
+  # and not only in the unpacked package, because "microteia unpack" replaces that whole directory
+  # and the package carries only the kernel's own indexes. Without it, a kernel upgrade made
+  # "firebase deploy" offer to delete the indexes of every extension. Managed by
+  # "microteia provision".
+  indexes: ${quote(environment.backend.indexes)}
+`;
+export const readEnvironment = async (path) => {
+    try {
+        return parseEnvironment(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`No ${ENVIRONMENT_FILE} here. Run "microteia init" first.`, { cause: error });
+        }
+        throw error;
+    }
+};
+export const writeEnvironment = async (path, environment) => {
+    await writeFile(path, serializeEnvironment(environment));
+};
+export const slug = (value) => value
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');

package/lib/console/firebaseCli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tudo aqui passa pelo `firebase` oficial. O Console não implementa autenticação própria e nunca vê
+ * credencial do cliente: quem está logado é quem rodou `firebase login`, e o projeto é dele.
+ */
+export declare const FIREBASE_BIN = "firebase";
+export interface WebAppSummary {
+    appId: string;
+    displayName: string;
+}
+export declare const parseJson: (raw: string) => unknown;
+export declare const assertFirebaseCli: () => Promise<string>;
+export declare const assertLoggedIn: () => Promise<void>;
+export declare const listWebApps: (projectId: string) => Promise<WebAppSummary[]>;
+export declare const createWebApp: (projectId: string, displayName: string) => Promise<string>;
+export declare const webAppSdkConfig: (projectId: string, appId: string) => Promise<Record<string, string>>;

package/lib/console/firebaseCli.js

@@ -0,0 +1,90 @@
+import { capture, captureOrThrow } from '../shared/run.js';
+/**
+ * Tudo aqui passa pelo `firebase` oficial. O Console não implementa autenticação própria e nunca vê
+ * credencial do cliente: quem está logado é quem rodou `firebase login`, e o projeto é dele.
+ */
+export const FIREBASE_BIN = 'firebase';
+export const parseJson = (raw) => {
+    // O `firebase --json` às vezes imprime aviso antes do JSON; o objeto começa na primeira chave.
+    const start = raw.indexOf('{');
+    if (start === -1)
+        throw new Error(`Expected JSON from the Firebase CLI, got:\n${raw.trim()}`);
+    return JSON.parse(raw.slice(start));
+};
+/**
+ * Procura recursivamente o objeto que contém a configuração do SDK. O `apps:sdkconfig` já mudou o
+ * formato de saída entre versões do `firebase`, e casar a forma exata quebraria a cada atualização
+ * do CLI do cliente — que não é uma versão que possamos fixar.
+ */
+const findSdkConfig = (value) => {
+    if (value === null || typeof value !== 'object')
+        return null;
+    if (!Array.isArray(value)) {
+        const record = value;
+        if (typeof record.apiKey === 'string' && typeof record.projectId === 'string') {
+            const config = {};
+            for (const [key, entry] of Object.entries(record)) {
+                if (typeof entry === 'string')
+                    config[key] = entry;
+            }
+            return config;
+        }
+    }
+    for (const entry of Array.isArray(value) ? value : Object.values(value)) {
+        const found = findSdkConfig(entry);
+        if (found !== null)
+            return found;
+    }
+    return null;
+};
+export const assertFirebaseCli = async () => {
+    const result = await capture(FIREBASE_BIN, ['--version']);
+    if (result.code !== 0) {
+        throw new Error('The Firebase CLI is required and was not found.\n'
+            + 'Install it with: npm install -g firebase-tools');
+    }
+    return result.stdout.trim().split('\n')[0];
+};
+export const assertLoggedIn = async () => {
+    const result = await capture(FIREBASE_BIN, ['login:list']);
+    const output = `${result.stdout}${result.stderr}`;
+    if (result.code !== 0 || /no authorized accounts/i.test(output)) {
+        throw new Error('You are not signed in to Firebase. Run: firebase login');
+    }
+};
+export const listWebApps = async (projectId) => {
+    const result = await capture(FIREBASE_BIN, ['apps:list', 'WEB', '--project', projectId, '--json']);
+    if (result.code !== 0) {
+        throw new Error(`Cannot reach Firebase project "${projectId}".\n`
+            + 'Check that the project id is correct and that the signed-in account has access to it.\n'
+            + `${result.stderr.trim()}`);
+    }
+    const parsed = parseJson(result.stdout);
+    const apps = Array.isArray(parsed.result) ? parsed.result : [];
+    return apps
+        .filter((app) => app !== null && typeof app === 'object')
+        .map((app) => ({
+        appId: String(app.appId ?? ''),
+        displayName: String(app.displayName ?? ''),
+    }))
+        .filter((app) => app.appId !== '');
+};
+export const createWebApp = async (projectId, displayName) => {
+    const stdout = await captureOrThrow(FIREBASE_BIN, ['apps:create', 'WEB', displayName, '--project', projectId, '--json']);
+    const config = findSdkConfig(parseJson(stdout));
+    if (config !== null && config.appId !== undefined)
+        return config.appId;
+    const parsed = parseJson(stdout);
+    const appId = parsed.result?.appId;
+    if (typeof appId !== 'string')
+        throw new Error('Firebase did not return an app id for the new web app.');
+    return appId;
+};
+export const webAppSdkConfig = async (projectId, appId) => {
+    const stdout = await captureOrThrow(FIREBASE_BIN, ['apps:sdkconfig', 'WEB', appId, '--project', projectId, '--json']);
+    const config = findSdkConfig(parseJson(stdout));
+    if (config === null) {
+        throw new Error(`Could not read the web SDK configuration for app ${appId}.`);
+    }
+    return config;
+};

package/lib/console/firestoreRest.d.ts

@@ -0,0 +1,39 @@
+export interface FirestoreDocument {
+    name: string;
+    fields: Record<string, unknown>;
+}
+export declare const accessToken: () => Promise<string>;
+/** Um valor tipado da REST virando valor de JavaScript. Timestamp vira string ISO, que é o que basta. */
+export declare const decodeValue: (value: unknown) => unknown;
+export declare const decodeFields: (fields: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Os documentos de uma coleção, seguindo a paginação até o fim.
+ *
+ * Sem máscara de campo, e de propósito: mascarar um caminho aninhado (`package.manifest`) funciona até
+ * uma versão da API discordar da forma, e o sintoma seria uma extensão sumindo do provisionamento sem
+ * erro. Documento de extensão é grande, mas são poucos por escritório, e isto roda uma vez por comando.
+ */
+export declare const listDocuments: (projectId: string, path: string) => Promise<FirestoreDocument[]>;
+export declare const documentId: (document: FirestoreDocument) => string;
+/** Um valor com o tipo que a REST espera, montado por quem sabe o que o campo é. */
+export type FirestoreTypedValue = {
+    stringValue: string;
+} | {
+    timestampValue: string;
+};
+export declare const asString: (value: string) => FirestoreTypedValue;
+/**
+ * Data como DATA, e não como texto que se parece com uma.
+ *
+ * O tipo do valor gravado é escolhido aqui e lido do outro lado do produto, meses depois, por quem não
+ * viu esta linha. Gravar uma data como `stringValue` custou um botão que não funcionava: a tela lia o
+ * texto, exibia certo, e só falhava ao gravar de volta. O `timestampValue` fecha essa porta — e é
+ * também o que permite ordenar e comparar o campo no banco. A REST exige RFC 3339 em UTC, que é
+ * exatamente o que `toISOString` devolve.
+ */
+export declare const asTimestamp: (value: Date) => FirestoreTypedValue;
+/**
+ * Grava UM campo de mapa, com `updateMask` — o resto do documento não é tocado. É o que permite o
+ * 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>;