@neetru/sdk 1.1.1 → 2.1.0

package/dist/types-Kmt4y1FQ.d.cts

@@ -0,0 +1,1364 @@
+import { c as DbCollectionRef$1, S as SyncState, U as Unsubscribe, C as ConflictRecord, R as RealtimeTransport } from './collection-ref-BBvTTXoG.cjs';
+import { DbQuery, DeltaFrame } from '@neetru/realtime-protocol';
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { NeetruError } from './errors.cjs';
+
+/** Tipo do tenant alvo da subscription (PF=uid, PJ=orgId). */
+type CheckoutTenantType = 'pf' | 'pj';
+/** Status do `checkout_intents/{intentId}` no Core. */
+type CheckoutIntentStatus = 'pending' | 'kyc_in_progress' | 'stripe_redirected' | 'completed' | 'expired' | 'cancelled';
+interface CheckoutStartInput {
+    /** Slug do produto no catálogo (ex: `neetru-pulse`). */
+    productId: string;
+    /** Slug do plano no catálogo do produto (ex: `pro_monthly`). */
+    planId: string;
+    /** Pra onde o produto SaaS quer voltar pós-checkout. https obrigatório (ou http://localhost em dev). */
+    callbackUrl: string;
+    /** Override pra checkout em nome de uma org. Default: PF do uid logado. */
+    tenantType?: CheckoutTenantType;
+    /** Quando `tenantType='pj'`, id da org. Ignorado quando PF. */
+    tenantId?: string;
+    /**
+     * Em browsers, default `true` — SDK faz `window.location.href = redirectUrl`.
+     * Passe `false` se quiser controlar o redirect manualmente.
+     */
+    autoRedirect?: boolean;
+}
+interface CheckoutStartResult {
+    intentId: string;
+    redirectUrl: string;
+    status: CheckoutIntentStatus;
+    expiresAt: string;
+    /** True se KYC ainda precisa ser coletado no portal. UI pode mostrar hint. */
+    requiresKyc: boolean;
+}
+interface CheckoutIntentInfo {
+    intentId: string;
+    uid: string;
+    targetTenantId: string;
+    targetTenantType: CheckoutTenantType;
+    productId: string;
+    planId: string;
+    callbackUrl: string;
+    status: CheckoutIntentStatus;
+    /** Stripe Checkout Session id quando avançou pra `stripe_redirected`. */
+    stripeSessionId?: string | null;
+    expiresAt: string;
+    /** True se já passou `expiresAt` mas Core ainda não marcou expired. */
+    isStale?: boolean;
+}
+interface CheckoutNamespace {
+    /**
+     * Inicia checkout. Em browser, redireciona automaticamente pro portal.
+     * Em Node/SSR, retorna o resultado sem efeitos colaterais — caller decide
+     * o que fazer com `redirectUrl`.
+     *
+     * Dev mode (`NEETRU_ENV=dev`): retorna URL fake `https://localhost:9003/portal/checkout/mock-XXXX`.
+     */
+    start(input: CheckoutStartInput): Promise<CheckoutStartResult>;
+    /** Lê estado atual do intent (Core). */
+    get(intentId: string): Promise<CheckoutIntentInfo>;
+    /** Cancela um intent que ainda não virou `stripe_redirected`. */
+    cancel(intentId: string): Promise<{
+        ok: true;
+        alreadyCancelled: boolean;
+    }>;
+}
+/**
+ * Mock dev — retorna URL fake `https://localhost:9003/portal/checkout/mock-XXXX`
+ * sem tocar no Core. Útil pra dev externo SaaS testar UI/redirect sem precisar
+ * de Bearer token Neetru.
+ *
+ * Dev mode persiste intents em mapa in-memory pro `get`/`cancel` retornarem
+ * resultado consistente.
+ */
+declare class MockCheckout implements CheckoutNamespace {
+    private readonly intents;
+    start(input: CheckoutStartInput): Promise<CheckoutStartResult>;
+    get(intentId: string): Promise<CheckoutIntentInfo>;
+    cancel(intentId: string): Promise<{
+        ok: true;
+        alreadyCancelled: boolean;
+    }>;
+}
+declare function createCheckoutNamespace(config: ResolvedConfig): CheckoutNamespace;
+
+type ProductNotificationSeverity = 'info' | 'success' | 'warning' | 'error';
+interface ProductNotification {
+    id: string;
+    /** UID do usuário final (do produto, não staff Neetru). */
+    userId: string;
+    /** Identificador semântico do evento (ex: `order.received`). */
+    kind: string;
+    severity: ProductNotificationSeverity;
+    title: string;
+    body?: string;
+    /** Link opcional pra ação. */
+    link?: string;
+    /** Metadata livre (serializável). */
+    metadata?: Record<string, string | number | boolean | null>;
+    createdAt: string;
+    /** ISO quando user marcou lida. */
+    readAt?: string;
+    /** ISO quando user descartou. */
+    dismissedAt?: string;
+}
+interface SendNotificationInput {
+    userId: string;
+    kind: string;
+    title: string;
+    severity?: ProductNotificationSeverity;
+    body?: string;
+    link?: string;
+    metadata?: Record<string, string | number | boolean | null>;
+    /**
+     * Dedup — se já existir notificação com mesmo fingerprint dentro de 24h,
+     * NÃO cria duplicata. Útil pra evitar spam quando webhook reentrega.
+     */
+    fingerprint?: string;
+}
+interface ListNotificationsOptions {
+    /** Inclui notificações dismissed (default false). */
+    includeDismissed?: boolean;
+    /** Filtro por unread. */
+    onlyUnread?: boolean;
+    /** Máx itens (default 50, máx 200). */
+    limit?: number;
+}
+interface NotificationsNamespace {
+    /** Produto envia uma notificação pra um usuário do produto. */
+    send(input: SendNotificationInput): Promise<ProductNotification>;
+    /** Lista notificações de um usuário. */
+    list(userId: string, options?: ListNotificationsOptions): Promise<ProductNotification[]>;
+    /** Marca como lida. */
+    markRead(id: string): Promise<{
+        ok: true;
+    }>;
+    /** Descarta. */
+    dismiss(id: string): Promise<{
+        ok: true;
+    }>;
+}
+declare function createNotificationsNamespace(config: ResolvedConfig): NotificationsNamespace;
+declare class MockNotifications implements NotificationsNamespace {
+    private notifications;
+    private nextId;
+    send(input: SendNotificationInput): Promise<ProductNotification>;
+    list(userId: string, options?: ListNotificationsOptions): Promise<ProductNotification[]>;
+    markRead(id: string): Promise<{
+        ok: true;
+    }>;
+    dismiss(id: string): Promise<{
+        ok: true;
+    }>;
+}
+
+/** Eventos Neetru que produtos podem assinar. Lista expansível por minor bump. */
+type WebhookEvent = 'subscription.activated' | 'subscription.cancelled' | 'subscription.payment_failed' | 'subscription.trial_ending' | 'usage.quota_exceeded' | 'account.suspended' | 'account.reactivated' | 'support.ticket_replied';
+interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: WebhookEvent[];
+    /** Quando true, `X-Neetru-Signature` é enviado em cada dispatch. */
+    hasSecret: boolean;
+    status: 'active' | 'degraded' | 'disabled';
+    /** ISO timestamp do último dispatch bem-sucedido. */
+    lastDeliveryAt?: string;
+    /** Quantos dispatches falharam consecutivos (resetado em sucesso). */
+    consecutiveFailures?: number;
+    createdAt: string;
+}
+interface RegisterWebhookInput {
+    url: string;
+    events: WebhookEvent[];
+    /**
+     * Secret pra HMAC SHA-256 (mín 16 chars). Recomendado.
+     * Quando ausente, dispatches vão sem assinatura — produto deve ter
+     * IP allowlist ou outra defesa.
+     */
+    secret?: string;
+}
+interface WebhookTestResult {
+    ok: boolean;
+    statusCode?: number;
+    durationMs?: number;
+    error?: string;
+}
+interface WebhooksNamespace {
+    /** Registra um novo endpoint. */
+    register(input: RegisterWebhookInput): Promise<WebhookEndpoint>;
+    /** Lista endpoints registrados pelo produto. */
+    list(): Promise<WebhookEndpoint[]>;
+    /** Remove um endpoint. */
+    unregister(id: string): Promise<{
+        ok: true;
+    }>;
+    /** Dispara evento de teste pra validar conectividade. */
+    test(id: string): Promise<WebhookTestResult>;
+}
+/**
+ * Verifica assinatura HMAC SHA-256 de payload de webhook recebido pelo
+ * produto consumer. Constant-time compare pra resistir a timing attack.
+ *
+ * @param payload Corpo cru da request (string ou Buffer). NÃO use o objeto
+ *                parseado — JSON.stringify pode diferir do que foi assinado.
+ * @param signature Header `X-Neetru-Signature` recebido (formato `sha256=<hex>`).
+ * @param secret Secret registrado em `webhooks.register({ secret })`.
+ * @returns true se assinatura confere, false caso contrário.
+ *
+ * @example
+ * ```ts
+ * // Express handler
+ * app.post('/webhooks/neetru', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const sig = req.header('X-Neetru-Signature');
+ *   if (!verifyWebhookSignature(req.body, sig, process.env.WEBHOOK_SECRET!)) {
+ *     return res.status(401).end();
+ *   }
+ *   const event = JSON.parse(req.body.toString('utf8'));
+ *   // ... handle event
+ *   res.json({ ok: true });
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string | Uint8Array, signature: string | null | undefined, secret: string): boolean;
+declare function createWebhooksNamespace(config: ResolvedConfig): WebhooksNamespace;
+declare class MockWebhooks implements WebhooksNamespace {
+    private endpoints;
+    private nextId;
+    register(input: RegisterWebhookInput): Promise<WebhookEndpoint>;
+    list(): Promise<WebhookEndpoint[]>;
+    unregister(id: string): Promise<{
+        ok: true;
+    }>;
+    test(id: string): Promise<WebhookTestResult>;
+}
+
+/**
+ * NeetruDbError — classe de erro especializada para o módulo `db`.
+ *
+ * Conforma com 02-sdk.md §3.5: `NeetruDbError extends NeetruError`,
+ * campo `code` fechado em `NeetruDbErrorCode`, campo `retryable` booleano,
+ * campo `dbId` opaco para correlação.
+ *
+ * Herda de `NeetruError` para que um `catch (e) { if (e instanceof NeetruError) }`
+ * genérico continue pegando erros de DB. Quem quer granularidade usa
+ * `instanceof NeetruDbError` e o `code` fechado.
+ */
+
+/**
+ * Códigos de erro específicos do módulo `db`.
+ *
+ * - `db_unavailable`        — lifecycle: provisionando / falhou / arquivado.
+ *                             NÃO significa "sem rede" — offline é transparente.
+ * - `db_not_found`          — documento/coleção não encontrado no servidor.
+ * - `db_conflict`           — conflito de escrita detectado.
+ * - `db_quota_exceeded`     — quota de escrita/leitura excedida no banco.
+ * - `db_permission_denied`  — sem permissão para a operação.
+ * - `db_invalid_query`      — query inválida (campo, operador, tipo).
+ * - `db_timeout`            — operação excedeu o timeout.
+ * - `offline_quota_exceeded`— IndexedDB cheio; a escrita não pode ser enfileirada.
+ * - `offline_unavailable`   — IndexedDB indisponível; SDK degrado para cache RAM.
+ */
+type NeetruDbErrorCode = 'db_unavailable' | 'db_not_found' | 'db_conflict' | 'db_quota_exceeded' | 'db_permission_denied' | 'db_invalid_query' | 'db_timeout' | 'offline_quota_exceeded' | 'offline_unavailable';
+/**
+ * Erro tipado do módulo `db` — estende `NeetruError` para compatibilidade.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.db.collection('orders').add({ ... });
+ * } catch (e) {
+ *   if (e instanceof NeetruDbError && e.code === 'offline_quota_exceeded') {
+ *     // IndexedDB cheio — notificar usuário
+ *   }
+ * }
+ * ```
+ */
+declare class NeetruDbError extends NeetruError {
+    /** Código de erro fechado — específico de DB. */
+    readonly code: NeetruDbErrorCode;
+    /**
+     * `true` para erros transientes que o produto pode tentar novamente.
+     * São retryable: `db_unavailable`, `db_conflict`, `db_timeout`.
+     */
+    readonly retryable: boolean;
+    /**
+     * ID opaco do banco lógico — só para correlação com logs do Core.
+     * Nunca deve ser exibido ao usuário final.
+     */
+    readonly dbId?: string;
+    constructor(code: NeetruDbErrorCode, message: string, dbId?: string);
+}
+
+/**
+ * Tipos internos do NeetruRealtimeClient.
+ *
+ * Os tipos de wire protocol (frames, ops, query descriptor, change) sao
+ * importados de `@neetru/realtime-protocol` — fonte unica de verdade
+ * compartilhada com o gateway (@neetru/realtime-transport e
+ * @neetru/realtime-changestream). Isso garante que cliente e gateway
+ * NUNCA derivem silenciosamente.
+ *
+ * Este arquivo define apenas os tipos internos ao cliente:
+ *   - ConnectionState / ConnectionStateListener : estado observavel da conexao
+ *   - WebSocketLike / WebSocketFactory          : injecao de dependencia pra testes
+ *   - RealtimeTicket / TicketProvider           : autenticacao realtime
+ *   - RealtimeClientOptions                     : configuracao do cliente
+ *   - SubscriptionCallback / SubscriptionEntry  : estado interno de subscriptions
+ *
+ * Re-exports de conveniencia:
+ *   - RealtimeQuery (alias de DbQuery)
+ *   - OutboundFrame (alias de SubscribeFrame)
+ *   - InboundFrame  (alias de DeltaFrame)
+ *   Os aliases preservam a API publica do cliente sem expor os nomes do gateway.
+ */
+
+type InboundFrame = DeltaFrame;
+type RealtimeQuery = DbQuery;
+/**
+ * Estado observavel da conexao WebSocket.
+ *
+ * - 'connecting'    : tentando (re)conectar — socket em aberto ou backoff ativo.
+ * - 'connected'     : WebSocket aberto e pronto para enviar/receber.
+ * - 'disconnected'  : sem conexao ativa, sem tentativa pendente.
+ * - 'draining'      : gateway enviou drain; aguardando reconexao com backoff.
+ */
+type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'draining';
+/** Listener de mudanca de estado da conexao. */
+type ConnectionStateListener = (state: ConnectionState) => void;
+/**
+ * Callback entregue a cada `subscribe()`.
+ * Recebe o frame inbound (delta/resync/stale/error) ja roteado para esta
+ * subscription especifica.
+ */
+type SubscriptionCallback = (frame: InboundFrame) => void;
+/**
+ * Subconjunto do WebSocket nativo necessario para o NeetruRealtimeClient.
+ * Injetavel em testes via FakeWebSocket.
+ *
+ * Cobre o que usamos: envio de mensagem, leitura de estado e event handlers.
+ * Nao inclui streams, arraybuffer ou blob — o protocolo so usa JSON text.
+ */
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+}
+/** Factory que cria instancias de WebSocketLike. Injetavel nos testes. */
+type WebSocketFactory = (url: string) => WebSocketLike;
+/**
+ * Ticket obtido de `POST /api/sdk/v1/db/realtime/ticket` pelo Core.
+ *
+ * O `token` e embedding em `query.filter._ticket` de cada frame `subscribe`
+ * enviado ao gateway, que o valida via
+ * `POST /api/sdk/v1/db/realtime/validate`.
+ *
+ * TTL tipico: 60s. Single-use-ish (o gateway valida na primeira mensagem).
+ */
+interface RealtimeTicket {
+    /** ID do ticket (opaco, para correlacao no lado do servidor). */
+    ticketId: string;
+    /** Token curto que o gateway extrai e valida. */
+    token: string;
+    /** ISO timestamp de expiracao. */
+    expiresAt: string;
+    /** TTL em milissegundos (atalho — igual a `expiresAt - now`). */
+    ttlMs: number;
+}
+/**
+ * Provedor de ticket injetavel.
+ *
+ * - Producao: implementacao padrao que chama
+ *   `POST /api/sdk/v1/db/realtime/ticket` via camada HTTP do SDK.
+ * - Testes: stub que retorna um ticket fixo (ou rejeita para simular falha).
+ *
+ * Deve retornar um ticket fresco a cada chamada — tickets tem TTL 60s e
+ * sao single-use-ish (um por conexao WS).
+ */
+type TicketProvider = () => Promise<RealtimeTicket>;
+/** Configuracao do NeetruRealtimeClient. */
+interface RealtimeClientOptions {
+    /**
+     * URL do gateway `neetru-realtime`.
+     * Ex.: `wss://realtime.neetru.com/ws`
+     */
+    gatewayUrl: string;
+    /**
+     * Provedor de ticket de autenticacao realtime injetavel.
+     *
+     * - Chamado antes de CADA abertura de WebSocket (primeira conexao e
+     *   reconexoes). Se falhar, a conexao e abortada e o backoff se aplica.
+     * - Producao: implementacao padrao usa `POST /api/sdk/v1/db/realtime/ticket`
+     *   via HTTP do SDK (requer `apiKey` configurado).
+     * - Testes: stub determinístico (nao precisa de Core rodando).
+     *
+     * OBRIGATORIO: o cliente nao abre WebSocket sem ticket valido.
+     */
+    ticketProvider: TicketProvider;
+    /**
+     * ID opaco do banco logico (BL-8 fix).
+     *
+     * Embutido em `query.filter._dbId` de cada frame `subscribe` enviado ao
+     * gateway. O gateway (`@neetru/realtime-changestream._extractDbId`) exige
+     * este campo para rotear a subscription ao banco correto — a ausencia causa
+     * rejeicao silenciosa.
+     *
+     * Opcional para compatibilidade reversa; ausente → nenhum `_dbId` no frame.
+     */
+    dbId?: string;
+    /**
+     * Factory de WebSocket injetavel.
+     * Default: `(url) => new WebSocket(url)`.
+     * Injetar em testes para evitar rede real.
+     */
+    webSocketFactory?: WebSocketFactory;
+    /**
+     * Injecao de `setTimeout`/`clearTimeout` para testes de backoff sem relogio
+     * real (fake timers). Default: `globalThis.setTimeout/clearTimeout`.
+     */
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
+    /**
+     * Delay base do backoff exponencial em ms. Default: 1000.
+     * O delay efetivo no attempt N e: `min(baseMs * 2^N, maxMs) * jitter`.
+     */
+    backoffBaseMs?: number;
+    /**
+     * Delay maximo do backoff em ms. Default: 30_000.
+     */
+    backoffMaxMs?: number;
+    /**
+     * Intervalo de heartbeat ping/pong em ms. Default: 25_000.
+     * Usar 0 para desabilitar (util em testes).
+     */
+    heartbeatIntervalMs?: number;
+}
+
+/**
+ * Tipos do Mundo SQL — `client.db.sql()`.
+ *
+ * Alinhado com 02-sdk.md §3.3 e 00-RELATORIO-CENTRAL.md §6.1 (peça 7+8 —
+ * `NeetruLeaseIssuer` + `SqlLeaseManager`).
+ *
+ * REGRA DURA: `DbSqlLease` nunca é logado, nunca é persistido, nunca é exposto
+ * ao produto. Vive só na RAM do processo.
+ */
+
+/**
+ * Lease SQL de curta duração emitido pelo Core via `POST /api/sdk/v1/db/lease`.
+ *
+ * Alinhado com `DbSqlLease` do Core (`src/lib/db/lease/types.ts`).
+ *
+ * - `port` sempre 5433 — o lease aponta pro PgBouncer, nunca à porta crua.
+ * - `credentialVersion` — bump indica rotação; o `SqlLeaseManager` reabre
+ *   o pool ao detectar versão diferente.
+ * - `expiresAt` — ISO string; o SDK renova aos ~80% do TTL (12 min em TTL=15 min).
+ */
+interface DbSqlLease {
+    leaseId: string;
+    host: string;
+    port: 5433;
+    dbName: string;
+    user: string;
+    /** Plaintext — trafega só sobre HTTPS, NUNCA logado/persistido. */
+    password: string;
+    /** CA do servidor para TLS — null até mTLS do Core (TODO P0-3). */
+    sslca: string | null;
+    /** Cert de cliente — null até mTLS do Core. */
+    clientCert: string | null;
+    /** Chave de cliente — null até mTLS do Core. */
+    clientKey: string | null;
+    /**
+     * Versão da credencial no Secret Manager. Bump = rotação de senha.
+     * O manager fecha o pool antigo e abre um novo quando esta versão muda.
+     */
+    credentialVersion: number;
+    /** Expiração ISO — SDK renova ~2 min antes. */
+    expiresAt: string;
+}
+/**
+ * Handle SQL retornado por `client.db.sql(schema)`.
+ *
+ * Superfície pública exata de 02-sdk.md §3.3.
+ *
+ * @template TSchema — schema Drizzle do produto (`pgTable(...)`)
+ */
+interface NeetruSqlClient<TSchema extends Record<string, unknown>> {
+    /** Handle Drizzle tipado pelo schema. */
+    readonly orm: NodePgDatabase<TSchema>;
+    /**
+     * Transação ACID real com rollback automático em exceção.
+     *
+     * @param fn — callback que recebe o handle Drizzle transacional.
+     * @param opts — `isolationLevel` opcional.
+     */
+    transaction<T>(fn: (tx: NodePgDatabase<TSchema>) => Promise<T>, opts?: {
+        isolationLevel?: 'read committed' | 'repeatable read' | 'serializable';
+    }): Promise<T>;
+    /** Drena o pool — chamar no shutdown do produto. */
+    close(): Promise<void>;
+}
+/**
+ * Opções do segundo argumento de `client.db.sql(schema, options?)`.
+ *
+ * Contrato C-H (00-RELATORIO-CENTRAL.md §3.8):
+ *   `client.db.sql(schema, { database? })` — quando `database` é fornecido,
+ *   identifica o banco SQL alvo entre N bancos do produto. Quando ausente,
+ *   resolve para o banco padrão (comportamento v1.x preservado).
+ */
+interface SqlOptions {
+    /**
+     * ID opaco do banco SQL — emitido pelo Core em `POST /api/sdk/v1/db`.
+     *
+     * Necessário quando o produto registrou mais de um banco SQL (ex.: `caixa`
+     * + `analytics`). O valor flui para o lease request e o Core emite um
+     * `DbSqlLease` escopado a esse banco.
+     *
+     * Quando omitido, o Core resolve o banco padrão do produto (geralmente o
+     * único registrado, ou o banco homônimo do produto).
+     */
+    database?: string;
+}
+
+/**
+ * NeetruRealtimeClient — cliente WebSocket multiplexado do gateway (M3).
+ *
+ * Componente #18 do relatório central do Conselho Neetru Core DB.
+ * Par cliente do serviço `neetru-realtime` (componente #19,
+ * `@neetru/realtime-transport`).
+ *
+ * Responsabilidades:
+ * - Manter EXATAMENTE UMA conexão WebSocket ao gateway.
+ * - Multiplexar N subscriptions independentes sobre ela.
+ * - Reconectar com backoff exponencial + jitter em caso de queda.
+ * - Em reconexão, reenviar todos os frames `subscribe` ativos.
+ * - Responder / enviar heartbeat ping/pong por protocolo.
+ * - Rotear frames inbound para o callback correto por `subscriptionId`.
+ * - Emitir mudanças de `ConnectionState` para observadores externos.
+ *
+ * Protocolo de frames (contrato compartilhado via `@neetru/realtime-protocol`):
+ *   ENVIA  → `subscribe` | `unsubscribe` | `ping`
+ *   RECEBE ← `delta` | `resync` | `stale` | `error` | `pong` | `drain`
+ *
+ * Deps: ZERO externas. Apenas WebSocket nativo (injetável).
+ *
+ * Nota: a integração de `NeetruRealtimeClient` na superfície pública
+ * `client.db` é um follow-up deliberado — ver seção de pendências no
+ * relatório de entrega.
+ */
+
+/**
+ * Cliente WebSocket multiplexado do gateway `neetru-realtime`.
+ *
+ * @example
+ * ```ts
+ * const rt = new NeetruRealtimeClient({
+ *   gatewayUrl: 'wss://realtime.neetru.com/ws',
+ * });
+ *
+ * const subId = rt.subscribe('orders', { filter: { status: 'open' } }, (frame) => {
+ *   if (frame.op === 'delta') applyChanges(frame.changes);
+ *   if (frame.op === 'resync') fullReload();
+ * });
+ *
+ * rt.onConnectionState((state) => console.log('connection:', state));
+ *
+ * // Para parar:
+ * rt.unsubscribe(subId);
+ * rt.close();
+ * ```
+ */
+declare class NeetruRealtimeClient {
+    private readonly _gatewayUrl;
+    private readonly _wsFactory;
+    private readonly _setTimeout;
+    private readonly _clearTimeout;
+    private readonly _backoffBaseMs;
+    private readonly _backoffMaxMs;
+    private readonly _heartbeatIntervalMs;
+    private readonly _ticketProvider;
+    /** ID do banco lógico (BL-8) — embutido em query.filter._dbId de cada subscribe. */
+    private readonly _dbId;
+    /** Ticket atual — obtido antes de cada abertura de WS e embutido nos frames. */
+    private _currentTicket;
+    /** Subscriptions ativas: id → entry */
+    private _subscriptions;
+    /** Listeners do estado da conexão. */
+    private _stateListeners;
+    /** Estado atual da conexão. */
+    private _connectionState;
+    /** Socket atual (pode ser null entre tentativas). */
+    private _ws;
+    /** Número da tentativa de reconexão corrente (reseta após conexão bem-sucedida). */
+    private _reconnectAttempt;
+    /** Handle do timer de backoff pendente. */
+    private _reconnectTimer;
+    /** Handle do timer de heartbeat. */
+    private _heartbeatTimer;
+    /** Indica que o cliente foi encerrado via `close()`. Não reconecta mais. */
+    private _closed;
+    /**
+     * Frames de subscribe que precisam ser enviados mas a socket ainda não
+     * está aberta (estado CONNECTING). Drenados no onopen.
+     */
+    private _pendingFrames;
+    constructor(options: RealtimeClientOptions);
+    /**
+     * Registra uma subscription em `collection` com `query` opcional.
+     *
+     * Envia um frame `subscribe` ao gateway (ou enfileira se o socket ainda
+     * não está aberto). O `callback` é invocado com cada frame `delta`,
+     * `resync`, `stale` ou `error` roteado para esta subscription.
+     *
+     * @returns O `subscriptionId` opaco — usar para cancelar via `unsubscribe()`.
+     */
+    subscribe(collection: string, query: RealtimeQuery, callback: SubscriptionCallback): string;
+    /**
+     * Cancela uma subscription.
+     *
+     * Envia um frame `unsubscribe` ao gateway e remove o listener local.
+     * Frames subsequentes com este `subscriptionId` são silenciosamente descartados.
+     */
+    unsubscribe(subscriptionId: string): void;
+    /**
+     * Registra um listener de mudanças no estado da conexão.
+     *
+     * O listener é invocado imediatamente com o estado atual e depois a cada
+     * transição. Retorna uma função `unsubscribe`.
+     */
+    onConnectionState(listener: ConnectionStateListener): () => void;
+    /**
+     * Encerra o cliente definitivamente.
+     *
+     * Fecha o socket ativo, cancela timers pendentes e marca o cliente como
+     * encerrado (sem mais reconexões).
+     */
+    close(): void;
+    /**
+     * Busca um ticket de autenticação e, em seguida, cria um novo WebSocket e
+     * instala os handlers de evento.
+     *
+     * A busca de ticket é obrigatória antes de abrir qualquer WS (primeira
+     * conexão e reconexões). Se a busca falhar, a conexão é abortada com
+     * estado `'connecting'` e o backoff reconectará em seguida.
+     *
+     * Fail-closed: o WebSocket NUNCA é aberto sem um ticket válido.
+     */
+    private _connect;
+    /** Implementação assíncrona de _connect — busca ticket e abre WS. */
+    private _connectWithTicket;
+    private _handleOpen;
+    private _handleMessage;
+    private _handleClose;
+    private _handleError;
+    private _handleDrain;
+    private _routeToSubscription;
+    /**
+     * Reenvía frames `subscribe` para todas as subscriptions ativas.
+     * Chamado no `onopen` de reconexões para restaurar o estado remoto.
+     *
+     * Durante a PRIMEIRA conexão: _pendingFrames já foi drenado com os
+     * subscribes iniciais acima. ResubscribeAll envia novamente — como a
+     * lista de subscriptions foi populada pelos `subscribe()` calls anteriores
+     * ao open, e os frames drenados também os incluem, teríamos duplicatas.
+     *
+     * Solução: resubscribeAll só é invocado após drenar _pendingFrames, e
+     * como o gateway é idempotente para o mesmo subscriptionId (segundo o
+     * design do componente #19), a duplicata é inócua. Em reconexões, onde
+     * _pendingFrames está vazio, os frames são os únicos enviados.
+     *
+     * Para o caso do primeiro open com subscribes anteriores ao open, os
+     * frames já foram drenados de _pendingFrames — não chamamos resubscribeAll
+     * se era a primeira conexão (_reconnectAttempt era 0 antes de resetar).
+     * Rastreamos isso com _hasConnectedOnce.
+     */
+    private _hasConnectedOnce;
+    private _resubscribeAll;
+    /**
+     * Constrói o descriptor `query` para um frame `subscribe`, embutindo o
+     * `token` do ticket corrente em `query.filter._ticket` e o `_dbId` do
+     * banco lógico em `query.filter._dbId` (BL-8 fix).
+     *
+     * O gateway extrai `filter._ticket` do primeiro frame `subscribe` e valida
+     * contra `POST /api/sdk/v1/db/realtime/validate`. `filter._dbId` é exigido
+     * pelo `@neetru/realtime-changestream._extractDbId` para rotear a
+     * subscription ao banco correto — sem ele a subscription é rejeitada.
+     *
+     * Retorna `undefined` se a query seria vazia E não há ticket (estado
+     * transitório antes do primeiro ticket — não deve ocorrer normalmente pois
+     * `_connect` só abre o WS após obter o ticket).
+     */
+    private _buildSubscribeQuery;
+    /** Agenda uma tentativa de reconexão com backoff exponencial + jitter. */
+    private _scheduleReconnect;
+    /**
+     * Calcula o delay de backoff para o attempt N.
+     *
+     * Fórmula: `min(baseMs * 2^N, maxMs) * jitter`
+     * onde `jitter ∈ [JITTER_MIN, JITTER_MAX]` (±50%).
+     */
+    private _computeBackoffDelay;
+    private _cancelReconnectTimer;
+    /** Agenda o próximo ping. Não-operacional se heartbeatIntervalMs === 0. */
+    private _scheduleHeartbeat;
+    private _cancelHeartbeatTimer;
+    private _sendPing;
+    /**
+     * Envia o frame imediatamente se o socket está aberto; caso contrário,
+     * enfileira em `_pendingFrames` para envio no próximo `onopen`.
+     */
+    private _sendOrBuffer;
+    /** Serializa e envia o frame imediatamente via WebSocket. */
+    private _sendNow;
+    private _setState;
+    /** Remove todos os handlers de um WebSocket (evita disparo após close()). */
+    private _detachHandlers;
+}
+
+/**
+ * Engine do banco lógico — determina o transporte de realtime.
+ *
+ * - `'firestore'` — Firestore Web SDK como transporte (memoryLocalCache).
+ * - `'nosql-vm'`  — WebSocket via gateway `neetru-realtime`.
+ * - `'rest'`      — REST puro (default MVP; sem realtime nativo).
+ *
+ * O produto NUNCA vê a diferença de transporte — o comportamento offline
+ * é idêntico nos dois engines de Documentos (02-sdk.md §3.7).
+ */
+type NeetruDbEngine = 'firestore' | 'nosql-vm' | 'rest';
+/**
+ * Opções de configuração do banco lógico.
+ *
+ * Normalmente geradas pelo scaffold `neetru db init` em `db/client.ts`.
+ * Em testes, injetar diretamente.
+ */
+interface NeetruDbOptions {
+    /**
+     * ID opaco do banco lógico — emitido pelo Core em `POST /api/sdk/v1/db`.
+     * Necessário para o lease SQL e para scoping das coleções.
+     */
+    dbId?: string;
+    /**
+     * Engine do banco lógico — determina o transporte de realtime.
+     * Default: `'rest'` (MVP — funciona para todos os engines SQL e Documentos).
+     */
+    engine?: NeetruDbEngine;
+    /**
+     * Opções do transporte Firestore (somente quando `engine === 'firestore'`).
+     * O `firestore` handle (inicializado com `memoryLocalCache`) é injetado aqui.
+     *
+     * Injeção explícita — o SDK não importa `firebase/firestore` diretamente
+     * para não poluir o bundle de quem não usa este engine.
+     */
+    firestoreTransport?: RealtimeTransport;
+    /**
+     * Opções do transporte WebSocket (somente quando `engine === 'nosql-vm'`).
+     * URL do gateway `neetru-realtime`.
+     */
+    realtimeGatewayUrl?: string;
+    /**
+     * Coleções declaradas pelo produto — necessário para pullChanges/fullResync
+     * com os transportes Firestore e nosql-vm.
+     *
+     * Default: `[]` (o SyncEngine sincroniza coleções conforme são acessadas).
+     */
+    collections?: string[];
+    /**
+     * Nome do banco IndexedDB. Convenção: `neetru-db__{productSlug}__{dbId}__{env}`.
+     * Gerado automaticamente se ausente.
+     */
+    dbName?: string;
+    /**
+     * `true` = sem contenção multi-aba (sempre líder).
+     * Padrão em SSR/testes; em produção usa Web Locks.
+     */
+    singleTab?: boolean;
+    /**
+     * Transporte de sync customizado (injetado em testes).
+     * Se presente, sobrepõe a detecção por `engine`.
+     */
+    _transport?: RealtimeTransport;
+    /**
+     * Factory de WebSocket injetável (somente quando `engine === 'nosql-vm'`).
+     * Default: `(url) => new WebSocket(url)`.
+     * Injetar em testes para evitar rede real.
+     */
+    _wsFactory?: WebSocketFactory;
+}
+/**
+ * Superfície pública do namespace `client.db` — alinhada com 02-sdk.md §3.1.
+ *
+ * ```ts
+ * const client = createNeetruClient({ ... });
+ *
+ * // Mundo Documentos (offline-first):
+ * const orders = client.db.collection<Order>('orders');
+ * await orders.add({ ... });
+ * orders.onSnapshot(query, snap => renderOrders(snap.docs));
+ *
+ * // Mundo SQL (lease + pg.Pool + Drizzle):
+ * const sql = await client.db.sql(schema);
+ * const rows = await sql.orm.select().from(schema.orders);
+ *
+ * // Camada offline:
+ * const state = client.db.syncState;
+ * client.db.onSyncStateChanged(s => console.log(s.pendingWrites));
+ * await client.db.flush(); // força sync
+ * ```
+ */
+interface NeetruDb {
+    /**
+     * Retorna uma `DbCollectionRef` para a coleção `name`.
+     *
+     * Offline-first: reads vêm do cache local; writes são aplicados
+     * otimisticamente e enfileirados para sync. Engine-aware: o transporte
+     * realtime é selecionado automaticamente pelo `engine` configurado.
+     */
+    collection<T = Record<string, unknown>>(name: string): DbCollectionRef$1<T>;
+    /**
+     * Abre o handle SQL: busca o lease no Core, abre o `pg.Pool`, cria o
+     * handle Drizzle tipado pelo `schema`. Operação async, 1x no startup.
+     *
+     * Em `NEETRU_ENV=dev`, retorna um `MockSqlClient` que não abre socket.
+     *
+     * @param schema   — Schema Drizzle do produto (`pgTable(...)` em `db/schema.ts`).
+     * @param options  — Opções opcionais (contrato C-H).
+     *   `options.database` desambigua quando o produto tem N>1 bancos SQL.
+     *   Quando omitido, o Core resolve o banco padrão/homônimo do produto.
+     *
+     * @example
+     * ```ts
+     * import * as schema from './db/schema';
+     * // banco padrão (único ou homônimo):
+     * export const db = await client.db.sql(schema);
+     * // banco específico entre N bancos SQL:
+     * export const analytics = await client.db.sql(schema, { database: 'analytics' });
+     * ```
+     */
+    sql<TSchema extends Record<string, unknown>>(schema: TSchema, options?: SqlOptions): Promise<NeetruSqlClient<TSchema>>;
+    /** Estado atual de sincronização da camada offline. */
+    readonly syncState: SyncState;
+    /**
+     * Subscreve a mudanças de `SyncState`.
+     * Retorna função de unsubscribe.
+     */
+    onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;
+    /**
+     * Força flush da fila de mutações pendentes.
+     * Útil antes de um `beforeunload` ou shutdown do produto.
+     */
+    flush(): Promise<void>;
+    /**
+     * Limpa o cache local (IndexedDB) — operação destrutiva.
+     * Use com cuidado: dados não sincronizados serão perdidos.
+     */
+    clearCache(): Promise<void>;
+    /**
+     * Retorna os registros de conflito LWW pendentes de entrega.
+     * Permite ao produto inspecionar escritas perdidas.
+     */
+    getConflicts(): Promise<ConflictRecord[]>;
+}
+/**
+ * Transporte REST puro — usa os endpoints `/api/sdk/v1/datastore/*` do Core.
+ *
+ * BL-2 fix: `pushMutations` agora chama o Core de verdade via `httpRequest`.
+ * Sem `config`, lança `NeetruDbError('db_unavailable')` — NUNCA retorna
+ * `confirmed` para uma escrita que não foi enviada.
+ *
+ * - `pushMutations`  → POST/PATCH/PUT/DELETE `/api/sdk/v1/datastore/{coll}/{id}`
+ * - `pullChanges`    → GET `/api/sdk/v1/datastore/{coll}` (best-effort por coleção)
+ * - `fullResync`     → GET por coleção (lista completa)
+ *
+ * Exportado para testes.
+ */
+declare function createRestSyncTransport(config?: ResolvedConfig): RealtimeTransport;
+/**
+ * Retorna o `NeetruRealtimeClient` para uso em `subscribeRealtime` fora do
+ * `SyncTransport` (extensão nosql-vm — não faz parte do contrato base).
+ *
+ * H-10 fix: agora aceita um `dbId` opcional que é passado para o cliente
+ * (BL-8 — o cliente embute `_dbId` nos frames de subscribe).
+ *
+ * @param gatewayUrl      URL do gateway WebSocket.
+ * @param ticketProvider  Provedor de ticket obrigatório.
+ * @param dbId            ID do banco lógico (BL-8).
+ * @param wsFactory       Factory de WebSocket injetável (testes).
+ */
+declare function getWebSocketRealtimeClient(gatewayUrl: string, ticketProvider: TicketProvider, dbId?: string, wsFactory?: WebSocketFactory): NeetruRealtimeClient;
+/**
+ * Cria o namespace `client.db` completo.
+ *
+ * **Factory única** — `createNeetruDb` é a única factory pública.
+ * O split sync/async é um detalhe de implementação interno: o `NeetruDb`
+ * retornado inicializa a camada offline (IndexedDB) de forma lazy na
+ * primeira operação real, portanto:
+ *
+ * - Pode ser chamado de contextos síncronos (como `createNeetruClient`).
+ * - Pode ser chamado com `await` quando se deseja garantir que o store
+ *   esteja aquecido antes da primeira op (equivalente a chamar `flush()`).
+ * - `client.db.flush()` garante que o IndexedDB está aberto.
+ *
+ * @param config   — config resolvida do cliente (apiKey, baseUrl, env, etc.)
+ * @param dbOpts   — opções do banco lógico (engine, dbId, collections, etc.)
+ *
+ * @example
+ * ```ts
+ * // Uso síncrono (dentro de createNeetruClient):
+ * const db = createNeetruDb(resolved, config.db);
+ *
+ * // Uso com await (quando se quer garantir warmup):
+ * const db = await createNeetruDb(resolved, config.db);
+ * await db.flush(); // opcional — já está aquecido
+ *
+ * // O produto usa:
+ * const orders = db.collection<Order>('orders');
+ * const sqlDb  = await db.sql(schema);
+ * ```
+ */
+declare function createNeetruDb(config: ResolvedConfig, dbOpts?: NeetruDbOptions): NeetruDb;
+
+/**
+ * Tipos públicos do SDK Neetru.
+ *
+ * Vendor-neutral: nada aqui referencia `firebase/*`, `stripe`, ou qualquer
+ * provider interno. Caller só vê superfície neutra (Product, Entitlement, ...).
+ */
+/** Default base URL pra API pública Neetru. */
+declare const DEFAULT_BASE_URL = "https://api.neetru.com";
+/**
+ * Configuração passada pra `createNeetruClient`.
+ */
+interface NeetruClientConfig {
+    /**
+     * Bearer token Neetru (formato `nrt_<keyId>_<secret>`). Opcional —
+     * se ausente, o SDK tenta `process.env.NEETRU_API_KEY` em Node.
+     *
+     * Endpoints públicos (catalog) funcionam sem apiKey. Endpoints autenticados
+     * (entitlements, telemetry) lançam `missing_api_key` se ausente.
+     */
+    apiKey?: string;
+    /**
+     * URL base da API Neetru. Default: `https://api.neetru.com`.
+     * Útil em testes apontando pra staging ou mock server.
+     */
+    baseUrl?: string;
+    /**
+     * Implementação de fetch customizada. Default: `globalThis.fetch`.
+     * Necessário em runtimes que não exponham fetch global por default.
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Modo de runtime. `dev` ativa mocks (auth retorna user fixture, usage só
+     * loga, support retorna lista fake). `workspace` e `prod` chamam HTTP real.
+     *
+     * Default: lê `process.env.NEETRU_ENV` (Node) ou `globalThis.NEETRU_ENV`
+     * (browser); fallback `prod`.
+     */
+    env?: 'dev' | 'workspace' | 'prod';
+    /**
+     * Override de mocks — útil em tests do consumer pra injetar fixtures
+     * determinísticos (sem depender de NEETRU_ENV=dev).
+     */
+    mocks?: {
+        auth?: AuthNamespace;
+        usage?: UsageNamespace;
+        support?: SupportNamespace;
+        entitlements?: NeetruClient['entitlements'];
+        /** v2.0: aceita NeetruDb (inclui MockDb). DbNamespace legado não é mais aceito. */
+        db?: NeetruDb;
+        webhooks?: WebhooksNamespace;
+        notifications?: NotificationsNamespace;
+    };
+    /**
+     * v0.3 — productId default usado por `usage.report()` / `usage.check()` /
+     * `db.collection()` quando não passado explicitamente nas options.
+     */
+    productId?: string;
+    /**
+     * v0.3 — tenantId default usado por `usage.report()` / `usage.check()` /
+     * `db.collection()` quando não passado explicitamente nas options.
+     */
+    tenantId?: string;
+    /**
+     * v2.0 — Configuração do banco lógico: engine, dbId, coleções, transport.
+     * Gerado pelo scaffold `neetru db init`. Opcional — padrão é engine='rest'.
+     */
+    db?: NeetruDbOptions;
+}
+/**
+ * Status do produto no catálogo público.
+ */
+type ProductStatus = 'live' | 'soon' | 'beta';
+/**
+ * Produto SaaS publicado pelo Neetru Core.
+ *
+ * Schema neutro — alinhado com `public_products/{slug}` no backend mas
+ * nunca expõe campos internos (Firestore Timestamps, draft state, etc).
+ */
+interface Product {
+    /** Identificador estável do produto, ex: `neetru-pulse`. */
+    slug: string;
+    /** Nome de exibição, ex: `Neetru Pulse`. */
+    name: string;
+    /** Subtítulo curto, ex: `Gestão de operações`. */
+    tagline?: string;
+    /** Descrição longa em prosa. */
+    description?: string;
+    /** Status público do produto. */
+    status?: ProductStatus;
+    /** Hint de ícone (catálogo de keys interno do Core). */
+    iconKey?: string;
+    /** Link override do CTA principal (default: página do produto). */
+    ctaHref?: string;
+    /** Label override do CTA. */
+    ctaLabel?: string;
+    /** Lista opcional de planos cobrados. Pode ser preenchida v0.2+. */
+    plans?: ProductPlan[];
+}
+/** Plano cobrado de um produto (placeholder v0.1 — schema final v0.2). */
+interface ProductPlan {
+    id: string;
+    name: string;
+    /** Preço mensal em centavos (BRL). Pode ser undefined em planos custom. */
+    amountCents?: number;
+    features?: string[];
+}
+/**
+ * Resposta do `client.catalog.list()`.
+ */
+interface CatalogListResponse {
+    products: Product[];
+    fetchedAt: string;
+}
+/**
+ * Resposta do `client.entitlements.check(productSlug, feature)`.
+ *
+ * `allowed` é o sinal forte; `reason` ajuda a debugar (não exibir pro user
+ * final).
+ */
+interface EntitlementCheck {
+    allowed: boolean;
+    productSlug: string;
+    feature: string;
+    /** Reason code estável: `granted` | `not_subscribed` | `feature_not_in_plan` | `expired`. */
+    reason?: string;
+}
+/**
+ * Payload pra `client.telemetry.event()`.
+ */
+interface TelemetryEventInput {
+    /** Nome do evento, ex: `dashboard_opened`, `report_exported`. */
+    name: string;
+    /** Atributos adicionais (chave → valor primitivo). */
+    properties?: Record<string, string | number | boolean | null>;
+    /** Timestamp ISO opcional; default = server time. */
+    timestamp?: string;
+}
+/**
+ * Confirmação de aceitação do evento de telemetria.
+ */
+interface TelemetryEventAck {
+    ok: true;
+    /** ID gerado pelo backend pra evento (`usage_events/{id}`). */
+    eventId: string;
+}
+type TelemetryLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+interface TelemetryLogInput {
+    level: TelemetryLogLevel;
+    message: string;
+    metadata?: Record<string, unknown>;
+    /** Override correlationId (default: lê dos headers/env automaticamente). */
+    correlationId?: string;
+    /** Slug do produto referenciado. Backend infere do escopo do token se ausente. */
+    productSlug?: string;
+}
+interface TelemetryLogAck {
+    ok: true;
+    /** ID do log gravado (`logs/{productId}/{yyyymmdd}/{logId}`) — opcional em mocks. */
+    logId?: string;
+    /** Indicador de modo (mock vs http). */
+    mode: 'mock' | 'http';
+}
+/**
+ * Handle imutável retornado por `createNeetruClient`. Carrega namespaces
+ * `auth`, `catalog`, `entitlements`, `telemetry`, `usage`, `support`.
+ *
+ * Cada namespace é exposto como objeto chamável — espelha API Firebase
+ * (`auth`, `firestore`) ou Stripe (`paymentIntents`, `customers`).
+ */
+interface NeetruClient {
+    /** Configuração resolvida (apiKey, baseUrl, fetch). Read-only. */
+    readonly config: ResolvedConfig;
+    /** Namespace auth (v0.2 — OIDC + mocks dev). */
+    readonly auth: AuthNamespace;
+    /** Namespace catálogo público de produtos. */
+    readonly catalog: {
+        /** Lista produtos publicados. */
+        list(opts?: CatalogListOptions): Promise<CatalogListResponse>;
+        /** Busca produto único por slug. */
+        get(slug: string): Promise<Product>;
+    };
+    /** Namespace entitlements (v1.2: cache LRU 60s TTL). */
+    readonly entitlements: {
+        /**
+         * Verifica se o portador da apiKey pode usar `feature` do produto `slug`.
+         * Cacheado 60s. `{ cacheBust: true }` força ida ao servidor.
+         */
+        check(productSlug: string, feature: string, opts?: {
+            cacheBust?: boolean;
+        }): Promise<boolean>;
+        /** Variante que retorna o objeto completo com `reason`. */
+        checkDetailed(productSlug: string, feature: string, opts?: {
+            cacheBust?: boolean;
+        }): Promise<EntitlementCheck>;
+    };
+    /** Namespace telemetria (v1.2: track fire-and-forget + flush). */
+    readonly telemetry: {
+        /** Persiste um evento single-shot. await retorna { ok, eventId }. */
+        event(input: TelemetryEventInput): Promise<TelemetryEventAck>;
+        /** Fire-and-forget: enqueue + flush 500ms debounce. Sem retorno. */
+        track(input: TelemetryEventInput): void;
+        /** Força flush da queue do track() (chamar antes de unload). */
+        flush(): Promise<void>;
+        /**
+         * Registra um log estruturado per-product (Sprint 6).
+         *
+         * - Em `NEETRU_ENV=dev`: apenas console.{level} (sem network).
+         * - Em `workspace`/`prod`: POST `/api/sdk/v1/telemetry/log` com Bearer + correlationId.
+         */
+        log(input: TelemetryLogInput): Promise<TelemetryLogAck>;
+    };
+    /** Namespace usage (v0.2 — track + quota; v0.3 — report + check). */
+    readonly usage: UsageNamespace;
+    /** Namespace support (v0.2 — tickets). */
+    readonly support: SupportNamespace;
+    /**
+     * Namespace db (v2.0 — Mundo Documentos offline-first + Mundo SQL).
+     *
+     * Breaking change v2.0: `client.db` agora é `NeetruDb` em vez de `DbNamespace`.
+     *   - `db.collection(name)` → `DbCollectionRef` (offline-first, com `onSnapshot`,
+     *     `batch`, `doc(id)`, `onDoc`; `list()` retorna `DbListResult` com cursor).
+     *   - `db.sql(schema)` → `Promise<NeetruSqlClient>` (Mundo SQL).
+     *   - `db.syncState` / `db.flush()` / `db.clearCache()` (camada offline).
+     *
+     * O antigo `DbNamespace` (list retornava `T[]`) foi removido em v2.0.
+     */
+    readonly db: NeetruDb;
+    /** Namespace checkout (v1.1 — start/get/cancel intent + auto-redirect). */
+    readonly checkout: CheckoutNamespace;
+    /** Namespace webhooks (v1.2 — register/list/unregister/test). */
+    readonly webhooks: WebhooksNamespace;
+    /** Namespace notifications (v1.2 — send/list/markRead/dismiss). */
+    readonly notifications: NotificationsNamespace;
+}
+/**
+ * User retornado pelo OIDC ID token. Schema neutro — não vaza Firebase
+ * decoded token shape. Subset estável do RFC 7519 + custom claims Neetru.
+ */
+interface NeetruUser {
+    /** Subject — uid estável. */
+    uid: string;
+    email: string;
+    emailVerified?: boolean;
+    displayName?: string;
+    photoURL?: string;
+    /** Custom claim Neetru — true quando staff. */
+    isStaff?: boolean;
+    /** Custom claim Neetru — true quando customer enrolled. */
+    isCustomer?: boolean;
+    /** Tenant assigned (multi-tenant deployments). */
+    tenantId?: string;
+    /** Outros claims OIDC (aud, iss, iat, exp). */
+    [extra: string]: unknown;
+}
+interface SignInOptions {
+    /** OIDC redirect_uri override. Default = window.location origin. */
+    redirectUri?: string;
+    /** OIDC scope. Default `openid profile email`. */
+    scope?: string;
+    /** Onde mandar após login completo. Default = window.location.href. */
+    postLoginRedirect?: string;
+}
+type AuthStateListener = (user: NeetruUser | null) => void;
+interface AuthNamespace {
+    /**
+     * Inicia fluxo de login OIDC. Em dev (`NEETRU_ENV=dev`) retorna mock user
+     * direto sem redirect. Em prod redireciona pro authorize endpoint.
+     */
+    signIn(options?: SignInOptions): Promise<NeetruUser | void>;
+    /** Limpa session local + revoga refresh token no servidor. */
+    signOut(): Promise<void>;
+    /** Retorna o user atual (do id_token cached) ou `null` se não logado. */
+    getUser(): NeetruUser | null;
+    /**
+     * Subscreve a mudanças de estado de auth. Listener é invocado imediatamente
+     * com user atual. Retorna função de unsubscribe.
+     */
+    onAuthStateChanged(listener: AuthStateListener): () => void;
+}
+interface UsageEventInput {
+    /** Nome do evento, ex: `report_generated`, `api_call`. */
+    event: string;
+    /** Atributos do evento. Valores primitivos serializáveis. */
+    properties?: Record<string, string | number | boolean | null>;
+    /** Quantidade — default 1 (1 evento). Útil pra batch. */
+    quantity?: number;
+}
+interface UsageQuota {
+    metric: string;
+    /** Quantidade já consumida no período. */
+    used: number;
+    /** Limite total. -1 = unlimited. */
+    limit: number;
+    /** ISO timestamp do reset (próximo período). */
+    resetsAt?: string;
+    /** Plano que define o limite. */
+    plan?: string;
+}
+interface UsageNamespace {
+    /** Persiste um evento de uso. Mock em dev, POST `/sdk/v1/usage/record` em prod. */
+    track(event: string, props?: UsageEventInput['properties']): Promise<{
+        ok: true;
+    }>;
+    /** Lê quota atual de uma métrica. Mock em dev, GET `/sdk/v1/usage/quota` em prod. */
+    getQuota(metric: string): Promise<UsageQuota>;
+    /**
+     * v0.3 — Reporta consumo de um resource metered (POST /sdk/v1/usage/record
+     * com `{productId, tenantId, resource, qty}`). Em dev acumula no mock.
+     *
+     * Diferente de `track()`: usa o endpoint canônico Sprint 7 que incrementa
+     * `usage_counters/{tenantId}_{productId}_{resource}_{yyyymm}` atomicamente.
+     *
+     * `productId`/`tenantId` são lidos do contexto resolvido do client se
+     * ausentes nas options.
+     */
+    report(resource: string, qty?: number, options?: {
+        productId?: string;
+        tenantId?: string;
+    }): Promise<{
+        ok: true;
+        counterId?: string;
+        value?: number;
+        limit?: number;
+        remaining?: number;
+        status?: string;
+    }>;
+    /**
+     * v0.3 — Verifica entitlement de um resource/feature. Wrapper em
+     * GET /sdk/v1/entitlements. Em dev consulta MockEntitlements + MockUsage.
+     */
+    check(resource: string, options?: {
+        productId?: string;
+        tenantId?: string;
+    }): Promise<{
+        allowed: boolean;
+        reason?: string;
+        remaining?: number;
+        limit?: number;
+        planId?: string | null;
+        planFeatures?: string[];
+    }>;
+}
+/**
+ * Namespace `db` (v0.3) — wrapper minimalista para CRUD em coleções tenant-scoped
+ * via Core REST. Em dev retorna fixtures in-memory por collection.
+ *
+ * O Core injeta automaticamente o tenantId no path do Firestore:
+ * `tenant_{tid}_{name}/{docId}`.
+ */
+/** Filtro `where` simples — alinhado com endpoint REST `field:op:value`. */
+interface DbWhereFilter {
+    field: string;
+    op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in';
+    value: string | number | boolean | null | Array<string | number | boolean>;
+}
+interface DbListOptions {
+    limit?: number;
+    /** Lista de filtros — máximo 5 (alinhado ao backend). */
+    where?: DbWhereFilter[];
+}
+interface DbCollectionRef {
+    /** Lista documentos com filtros opcionais. */
+    list<T = Record<string, unknown>>(opts?: DbListOptions): Promise<T[]>;
+    /** Lê um documento por id. Retorna `null` se não existe. */
+    get<T = Record<string, unknown>>(id: string): Promise<T | null>;
+    /** Cria/upsert um documento com id explícito. */
+    set(id: string, data: Record<string, unknown>): Promise<{
+        ok: true;
+    }>;
+    /**
+     * v0.3.1 — Adiciona doc com id auto-gerado pelo backend. Retorna `{id}` do
+     * doc criado. Diferente de `set(id, data)` que requer caller fornecer id.
+     */
+    add(data: Record<string, unknown>): Promise<{
+        ok: true;
+        id: string;
+    }>;
+    /** Atualiza doc com merge — só campos passados em `data`. */
+    update(id: string, data: Record<string, unknown>): Promise<{
+        ok: true;
+    }>;
+    /** Deleta um documento. */
+    remove(id: string): Promise<{
+        ok: true;
+    }>;
+}
+interface DbNamespace {
+    collection(name: string): DbCollectionRef;
+}
+type SupportSeverity = 'low' | 'normal' | 'high' | 'urgent';
+type SupportStatus = 'open' | 'pending' | 'resolved' | 'closed';
+interface SupportTicket {
+    id: string;
+    subject: string;
+    message: string;
+    severity: SupportSeverity;
+    status: SupportStatus;
+    createdAt: string;
+    updatedAt?: string;
+    /** Slug do produto referenciado. */
+    productSlug?: string;
+}
+interface CreateTicketInput {
+    subject: string;
+    message: string;
+    severity?: SupportSeverity;
+    productSlug?: string;
+}
+interface SupportNamespace {
+    /** Cria um novo ticket. Mock em dev, POST `/api/v1/products/{slug}/tickets` em prod. */
+    createTicket(input: CreateTicketInput): Promise<SupportTicket>;
+    /** Lista meus tickets abertos. */
+    listMyTickets(): Promise<SupportTicket[]>;
+}
+/**
+ * Modo do SDK. `dev` ativa mocks automáticos (úteis pra testes e
+ * desenvolvimento sem precisar de backend rodando).
+ */
+type NeetruEnv = 'dev' | 'workspace' | 'prod';
+/**
+ * Configuração resolvida (defaults aplicados, fetch garantido).
+ */
+interface ResolvedConfig {
+    readonly apiKey?: string;
+    readonly baseUrl: string;
+    readonly fetch: typeof globalThis.fetch;
+    /** Resolved env — `dev` | `workspace` | `prod`. Default `prod`. */
+    readonly env: NeetruEnv;
+    /** Default productId (v0.3). */
+    readonly productId?: string;
+    /** Default tenantId (v0.3). */
+    readonly tenantId?: string;
+}
+/** Opções pra `catalog.list()`. */
+interface CatalogListOptions {
+    /** Inclui rascunhos (apenas com Bearer staff). Default false. */
+    includeDrafts?: boolean;
+}
+
+export { type WebhookEvent as $, type AuthNamespace as A, type ProductPlan as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type EntitlementCheck as E, type ProductStatus as F, type ResolvedConfig as G, type SignInOptions as H, type SqlOptions as I, type SupportNamespace as J, type SupportSeverity as K, type ListNotificationsOptions as L, MockCheckout as M, type NeetruClient as N, type SupportStatus as O, type Product as P, type SupportTicket as Q, type RegisterWebhookInput as R, type SendNotificationInput as S, type TelemetryEventAck as T, type TelemetryEventInput as U, type TelemetryLogAck as V, type TelemetryLogInput as W, type UsageEventInput as X, type UsageNamespace as Y, type UsageQuota as Z, type WebhookEndpoint as _, type AuthStateListener as a, type WebhookTestResult as a0, type WebhooksNamespace as a1, createCheckoutNamespace as a2, createNeetruDb as a3, createNotificationsNamespace as a4, createRestSyncTransport as a5, createWebhooksNamespace as a6, getWebSocketRealtimeClient as a7, verifyWebhookSignature as a8, type CatalogListResponse as b, type CheckoutIntentInfo as c, type CheckoutIntentStatus as d, type CheckoutNamespace as e, type CheckoutStartInput as f, type CheckoutStartResult as g, type CheckoutTenantType as h, type CreateTicketInput as i, type DbNamespace as j, type DbSqlLease as k, type DbWhereFilter as l, MockNotifications as m, MockWebhooks as n, type NeetruClientConfig as o, type NeetruDb as p, type NeetruDbEngine as q, NeetruDbError as r, type NeetruDbErrorCode as s, type NeetruDbOptions as t, type NeetruEnv as u, type NeetruSqlClient as v, type NeetruUser as w, type NotificationsNamespace as x, type ProductNotification as y, type ProductNotificationSeverity as z };