@neetru/sdk 2.3.6 → 3.0.1

package/dist/{types-sGGN1vkg.d.cts → types-Lfd3LiAF.d.cts}

@@ -1,5 +1,4 @@
 import { c as DbCollectionRef$1, S as SyncState, U as Unsubscribe, C as ConflictRecord, R as RealtimeTransport } from './collection-ref-DqAAhuhX.cjs';
-import { DbQuery, DeltaFrame } from '@neetru/realtime-protocol';
 import { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import { NeetruError } from './errors.cjs';
 
@@ -104,6 +103,11 @@ interface ProductNotification {
     dismissedAt?: string;
 }
 interface SendNotificationInput {
+    /**
+     * **3.0 (breaking):** productId é obrigatório (Core valida via Zod). Default
+     * resolve do `config.productId`; lança `validation_failed` se ausente.
+     */
+    productId?: string;
     userId: string;
     kind: string;
     title: string;
@@ -118,6 +122,11 @@ interface SendNotificationInput {
     fingerprint?: string;
 }
 interface ListNotificationsOptions {
+    /**
+     * **3.0 (breaking):** productId é obrigatório no Core. Default resolve do
+     * `config.productId`.
+     */
+    productId?: string;
     /** Inclui notificações dismissed (default false). */
     includeDismissed?: boolean;
     /** Filtro por unread. */
@@ -125,17 +134,21 @@ interface ListNotificationsOptions {
     /** Máx itens (default 50, máx 200). */
     limit?: number;
 }
+/** 3.0: scope option pra markRead/dismiss (productId obrigatório no Core). */
+interface NotificationScopeOptions {
+    productId?: string;
+}
 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<{
+    markRead(id: string, options?: NotificationScopeOptions): Promise<{
         ok: true;
     }>;
     /** Descarta. */
-    dismiss(id: string): Promise<{
+    dismiss(id: string, options?: NotificationScopeOptions): Promise<{
         ok: true;
     }>;
 }
@@ -145,10 +158,10 @@ declare class MockNotifications implements NotificationsNamespace {
     private nextId;
     send(input: SendNotificationInput): Promise<ProductNotification>;
     list(userId: string, options?: ListNotificationsOptions): Promise<ProductNotification[]>;
-    markRead(id: string): Promise<{
+    markRead(id: string, _options?: NotificationScopeOptions): Promise<{
         ok: true;
     }>;
-    dismiss(id: string): Promise<{
+    dismiss(id: string, _options?: NotificationScopeOptions): Promise<{
         ok: true;
     }>;
 }
@@ -169,6 +182,12 @@ interface WebhookEndpoint {
     createdAt: string;
 }
 interface RegisterWebhookInput {
+    /**
+     * **3.0 (breaking):** `productId` é obrigatório no body. Se ausente,
+     * SDK tenta resolver do `config.productId` (default no `createNeetruClient`);
+     * lança `validation_failed` se ambos faltarem.
+     */
+    productId?: string;
     url: string;
     events: WebhookEvent[];
     /**
@@ -184,53 +203,67 @@ interface WebhookTestResult {
     durationMs?: number;
     error?: string;
 }
+/**
+ * 3.0: opções de scoping — todos os verbos exigem `productId` (default do
+ * `config.productId` se ausente).
+ */
+interface WebhookScopeOptions {
+    productId?: string;
+}
 interface WebhooksNamespace {
     /** Registra um novo endpoint. */
     register(input: RegisterWebhookInput): Promise<WebhookEndpoint>;
     /** Lista endpoints registrados pelo produto. */
-    list(): Promise<WebhookEndpoint[]>;
+    list(options?: WebhookScopeOptions): Promise<WebhookEndpoint[]>;
     /** Remove um endpoint. */
-    unregister(id: string): Promise<{
+    unregister(id: string, options?: WebhookScopeOptions): Promise<{
         ok: true;
     }>;
     /** Dispara evento de teste pra validar conectividade. */
-    test(id: string): Promise<WebhookTestResult>;
+    test(id: string, options?: WebhookScopeOptions): Promise<WebhookTestResult>;
 }
 /**
  * Verifica assinatura HMAC SHA-256 de payload de webhook recebido pelo
- * produto consumer. Constant-time compare pra resistir a timing attack.
+ * produto consumer. **3.0**: Universal (browser/Node/Edge) via WebCrypto.subtle.
  *
- * @param payload Corpo cru da request (string ou Buffer). NÃO use o objeto
+ * Constant-time compare via byte-level XOR accumulator (não usa
+ * `timingSafeEqual` do Node porque WebCrypto não tem equivalente direto).
+ *
+ * @param payload Corpo cru da request (string ou Uint8Array). 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.
+ * @returns Promise<boolean> — 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'));
+ * // Next.js Route Handler (Edge ou Node runtime — funciona em ambos)
+ * export async function POST(req: Request) {
+ *   const raw = await req.text();
+ *   const sig = req.headers.get('X-Neetru-Signature');
+ *   const ok = await verifyWebhookSignature(raw, sig, process.env.NEETRU_WEBHOOK_SECRET!);
+ *   if (!ok) return new Response('unauthorized', { status: 401 });
+ *   const event = JSON.parse(raw);
  *   // ... handle event
- *   res.json({ ok: true });
- * });
+ *   return Response.json({ ok: true });
+ * }
  * ```
+ *
+ * @throws NeetruError('runtime_unsupported') se runtime não expõe WebCrypto.
+ *   Não retorna `false` silencioso — caller precisa distinguir "assinatura
+ *   inválida" (return false) de "ambiente não suporta" (throw).
  */
-declare function verifyWebhookSignature(payload: string | Uint8Array, signature: string | null | undefined, secret: string): boolean;
+declare function verifyWebhookSignature(payload: string | Uint8Array, signature: string | null | undefined, secret: string): Promise<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<{
+    list(_options?: WebhookScopeOptions): Promise<WebhookEndpoint[]>;
+    unregister(id: string, _options?: WebhookScopeOptions): Promise<{
         ok: true;
     }>;
-    test(id: string): Promise<WebhookTestResult>;
+    test(id: string, _options?: WebhookScopeOptions): Promise<WebhookTestResult>;
 }
 
 /**
@@ -290,29 +323,25 @@ declare class NeetruDbError extends NeetruError {
     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.
- */
-
+declare const DELTA_OPS: readonly ["delta", "resync", "stale", "error", "pong", "drain"];
+type DeltaOp = (typeof DELTA_OPS)[number];
+interface DbQuery {
+    filter?: Record<string, unknown>;
+    limit?: number;
+    orderBy?: string;
+    orderDir?: 'asc' | 'desc';
+}
+interface DbChange {
+    type: string;
+    documentId: string;
+    data?: Record<string, unknown>;
+}
+interface DeltaFrame {
+    op: DeltaOp;
+    subscriptionId: string;
+    changes?: DbChange[];
+    reason?: string;
+}
 type InboundFrame = DeltaFrame;
 type RealtimeQuery = DbQuery;
 /**
@@ -560,7 +589,7 @@ interface SqlOptions {
  * - 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`):
+ * Protocolo de frames (contrato inlined em `./types.ts` — MASTER-CRIT-038):
  *   ENVIA  → `subscribe` | `unsubscribe` | `ping`
  *   RECEBE ← `delta` | `resync` | `stale` | `error` | `pong` | `drain`
  *
@@ -1043,6 +1072,14 @@ interface NeetruClientConfig {
      * Valores: `'rest'` | `'firestore'` | `'nosql-vm'`.
      */
     db?: NeetruDbOptions;
+    /**
+     * 3.0 — hosts adicionais permitidos para `baseUrl`. Por default, SDK aceita
+     * `*.neetru.com` HTTPS + localhost. Para apontar pra staging/proxy custom em
+     * `https://meu-proxy.empresa.com`, adicione `['empresa.com']`.
+     *
+     * Bypass total: `NEETRU_ALLOW_INSECURE_BASEURL=1` no env.
+     */
+    allowedHosts?: string[];
 }
 /**
  * Status do produto no catálogo público.
@@ -1299,41 +1336,41 @@ interface VerifyTokenOptions {
      */
     jwksCacheTtlMs?: number;
 }
+/**
+ * 3.0 BREAKING: `UsageEventInput` mantido só como tipo para tests/legacy
+ * imports — não é mais retorno de método. `usage.track`/`usage.getQuota`
+ * **REMOVIDOS** em 3.0. Use `usage.report(resource, qty, options)`.
+ */
 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;
 }
+/**
+ * 3.0 BREAKING: `UsageQuota` mantido só para compat de imports. Não é mais
+ * retorno de método ativo. `usage.report()` devolve `{value, limit, remaining}`
+ * inline; `usage.check()` devolve detalhes do entitlement.
+ */
 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;
 }
+/**
+ * 3.0 — superfície limpa: `report` (POST metered) + `check` (GET entitlement).
+ *
+ * Métodos removidos vs 2.x:
+ *   - `track(event, props)` — vaporware contra Core. Use `report()`.
+ *   - `getQuota(metric)` — endpoint nunca existiu. `report()` devolve quota.
+ */
 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.
+     * Reporta consumo metered. Incrementa `usage_counters` no Core atomicamente.
+     * Idempotency-Key gerado por chamada (defesa anti-dup em retry transient).
      *
-     * 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.
+     * `productId`/`tenantId` lidos do contexto do client se ausentes nas options.
      */
     report(resource: string, qty?: number, options?: {
         productId?: string;
@@ -1347,8 +1384,9 @@ interface UsageNamespace {
         status?: string;
     }>;
     /**
-     * v0.3 — Verifica entitlement de um resource/feature. Wrapper em
-     * GET /sdk/v1/entitlements. Em dev consulta MockEntitlements + MockUsage.
+     * Verifica entitlement de um resource/feature. GET cacheável (HTTP 60s).
+     * Resposta inclui `allowed`, `reason`, `remaining`, `limit`, `planId`,
+     * `planFeatures` e `behavior` ('readonly' quando limit_exceeded).
      */
     check(resource: string, options?: {
         productId?: string;
@@ -1360,6 +1398,7 @@ interface UsageNamespace {
         limit?: number;
         planId?: string | null;
         planFeatures?: string[];
+        behavior?: 'readonly' | null;
     }>;
 }
 /**
@@ -1427,12 +1466,29 @@ interface CreateTicketInput {
     message: string;
     severity?: SupportSeverity;
     productSlug?: string;
+    /**
+     * **L-05 fix (Opus review 2026-05-27):** metadata opcional (Core já aceita
+     * via `metadata: z.record(...)` no Zod). Útil pra anexar contexto como
+     * `{ orderId, userAgent, route, sessionId }` sem inflar subject/message.
+     *
+     * Chaves limitadas a 64 chars; valores primitive (string/number/boolean/null).
+     */
+    metadata?: Record<string, string | number | boolean | null>;
 }
 interface SupportNamespace {
-    /** Cria um novo ticket. Mock em dev, POST `/api/v1/products/{slug}/tickets` em prod. */
+    /**
+     * Cria um novo ticket. **3.0**: POST `/api/sdk/v1/support/tickets`
+     * (canonical, requer `productId` no body — default `config.productId`).
+     * Mock em dev.
+     */
     createTicket(input: CreateTicketInput): Promise<SupportTicket>;
-    /** Lista meus tickets abertos. */
-    listMyTickets(): Promise<SupportTicket[]>;
+    /**
+     * Lista meus tickets abertos. **3.0**: GET `/api/sdk/v1/support/tickets?productId=...`
+     * (canonical). `options.productSlug` override do `config.productId` default.
+     */
+    listMyTickets(options?: {
+        productSlug?: string;
+    }): Promise<SupportTicket[]>;
 }
 /**
  * Modo do SDK. `dev` ativa mocks automáticos (úteis pra testes e
@@ -1459,4 +1515,4 @@ interface CatalogListOptions {
     includeDrafts?: boolean;
 }
 
-export { type VerifyTokenOptions as $, type AuthNamespace as A, type ProductNotificationSeverity as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type EntitlementCheck as E, type ProductPlan as F, type ProductStatus as G, type ResolvedConfig as H, type SignInOptions as I, type SqlOptions as J, type SupportNamespace as K, type ListNotificationsOptions as L, MockCheckout as M, type NeetruClient as N, type SupportSeverity as O, type Product as P, type SupportStatus as Q, type RegisterWebhookInput as R, type SendNotificationInput as S, type SupportTicket as T, type TelemetryEventAck as U, type TelemetryEventInput as V, type TelemetryLogAck as W, type TelemetryLogInput as X, type UsageEventInput as Y, type UsageNamespace as Z, type UsageQuota as _, type AuthStateListener as a, type WebhookEndpoint as a0, type WebhookEvent as a1, type WebhookTestResult as a2, type WebhooksNamespace as a3, createCheckoutNamespace as a4, createNeetruDb as a5, createNotificationsNamespace as a6, createRestSyncTransport as a7, createWebhooksNamespace as a8, getWebSocketRealtimeClient as a9, verifyWebhookSignature as aa, 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 NeetruDbTransport as u, type NeetruEnv as v, type NeetruSqlClient as w, type NeetruUser as x, type NotificationsNamespace as y, type ProductNotification as z };
+export { type UsageQuota as $, type AuthNamespace as A, type ProductNotification as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type EntitlementCheck as E, type ProductNotificationSeverity as F, type ProductPlan as G, type ProductStatus as H, type ResolvedConfig as I, type SignInOptions as J, type SqlOptions as K, type ListNotificationsOptions as L, MockCheckout as M, type NeetruClient as N, type SupportNamespace as O, type Product as P, type SupportSeverity as Q, type RegisterWebhookInput as R, type SendNotificationInput as S, type SupportStatus as T, type SupportTicket as U, type TelemetryEventAck as V, type TelemetryEventInput as W, type TelemetryLogAck as X, type TelemetryLogInput as Y, type UsageEventInput as Z, type UsageNamespace as _, type AuthStateListener as a, type VerifyTokenOptions as a0, type WebhookEndpoint as a1, type WebhookEvent as a2, type WebhookScopeOptions as a3, type WebhookTestResult as a4, type WebhooksNamespace as a5, createCheckoutNamespace as a6, createNeetruDb as a7, createNotificationsNamespace as a8, createRestSyncTransport as a9, createWebhooksNamespace as aa, getWebSocketRealtimeClient as ab, verifyWebhookSignature as ac, 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 NeetruDbTransport as u, type NeetruEnv as v, type NeetruSqlClient as w, type NeetruUser as x, type NotificationScopeOptions as y, type NotificationsNamespace as z };

package/dist/usage.cjs

@@ -15,8 +15,22 @@ var NeetruError = class _NeetruError extends Error {
   }
 };
 
+// src/idempotency.ts
+function generateIdempotencyKey() {
+  const cryptoObj = typeof globalThis !== "undefined" && "crypto" in globalThis ? globalThis.crypto : void 0;
+  if (cryptoObj && typeof cryptoObj.randomUUID === "function") {
+    return cryptoObj.randomUUID();
+  }
+  throw new NeetruError(
+    "runtime_unsupported",
+    "crypto.randomUUID not available in this runtime. SDK 3.0 requires Node \u226520 or modern browser/Edge."
+  );
+}
+
 // src/http.ts
-var DEFAULT_RETRIES = 2;
+var DEFAULT_RETRIES_READ = 2;
+var DEFAULT_RETRIES_WRITE = 0;
+var READ_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
 var RETRYABLE_CODES = /* @__PURE__ */ new Set([
   "rate_limited",
   "server_error",
@@ -74,7 +88,8 @@ async function safeJson(res) {
 async function httpRequest(config, opts) {
   const method = opts.method ?? "GET";
   const url = buildUrl(config.baseUrl, opts.path, opts.query);
-  const maxRetries = opts.retries ?? DEFAULT_RETRIES;
+  const defaultRetries = READ_METHODS.has(method) ? DEFAULT_RETRIES_READ : DEFAULT_RETRIES_WRITE;
+  const maxRetries = opts.retries ?? defaultRetries;
   const headers = {
     accept: "application/json",
     ...opts.headers
@@ -88,6 +103,10 @@ async function httpRequest(config, opts) {
     }
     headers.authorization = `Bearer ${config.apiKey}`;
   }
+  if (opts.idempotencyKey) {
+    const key = typeof opts.idempotencyKey === "string" ? opts.idempotencyKey : generateIdempotencyKey();
+    headers["idempotency-key"] = key;
+  }
   const bodyString = opts.body !== void 0 && method !== "GET" && method !== "DELETE" ? JSON.stringify(opts.body) : void 0;
   if (bodyString !== void 0) {
     headers["content-type"] = "application/json";
@@ -140,66 +159,31 @@ async function httpRequest(config, opts) {
   throw lastError ?? new NeetruError("unknown", "unexpected httpRequest exit");
 }
 
-// src/usage.ts
-function toQuota(metric, raw) {
-  if (!raw || typeof raw !== "object") {
-    throw new NeetruError("invalid_response", "Quota response is not an object");
-  }
-  const r = raw;
-  if (typeof r.used !== "number" || typeof r.limit !== "number") {
-    throw new NeetruError("invalid_response", "Quota response missing used/limit numbers");
+// src/validators.ts
+var SDK_ID_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+function assertValidSdkId(field, value) {
+  if (typeof value !== "string" || !SDK_ID_RE.test(value)) {
+    throw new NeetruError(
+      "validation_failed",
+      `${field} must match ${SDK_ID_RE.source} (lowercase alphanumeric, _, -; first char must be alphanumeric; max 63 chars)`
+    );
   }
-  return {
-    metric: typeof r.metric === "string" ? r.metric : metric,
-    used: r.used,
-    limit: r.limit,
-    resetsAt: typeof r.resetsAt === "string" ? r.resetsAt : void 0,
-    plan: typeof r.plan === "string" ? r.plan : void 0
-  };
 }
+
+// src/usage.ts
 function createUsageNamespace(config) {
   return {
     /**
-     * Persiste um evento de usage. Em dev (mocks ativos via factory) só loga.
-     * Em workspace/prod chama POST /sdk/v1/usage/record.
-     */
-    async track(event, properties) {
-      if (!event || typeof event !== "string") {
-        throw new NeetruError("validation_failed", "event name is required");
-      }
-      if (event.length > 128) {
-        throw new NeetruError("validation_failed", "event name max 128 chars");
-      }
-      const body = { event };
-      if (properties && typeof properties === "object") body.properties = properties;
-      const raw = await httpRequest(config, {
-        method: "POST",
-        path: "/sdk/v1/usage/record",
-        body,
-        requireAuth: true
-      });
-      if (!raw || raw.ok !== true) {
-        throw new NeetruError("invalid_response", "Usage record response missing ok");
-      }
-      return { ok: true };
-    },
-    /**
-     * Lê quota atual de uma métrica. Cacheável (caller decide), SDK não cacheia.
-     */
-    async getQuota(metric) {
-      if (!metric || typeof metric !== "string") {
-        throw new NeetruError("validation_failed", "metric is required");
-      }
-      const raw = await httpRequest(config, {
-        method: "GET",
-        path: "/sdk/v1/usage/quota",
-        query: { metric },
-        requireAuth: true
-      });
-      return toQuota(metric, raw);
-    },
-    /**
-     * v0.3 — Reporta consumo metered. Hit no endpoint canônico Sprint 7.
+     * Reporta consumo metered de um resource. Hit no endpoint canônico
+     * `POST /api/sdk/v1/usage/record`. Idempotency-Key gerado por chamada;
+     * Core dedup serverside TTL 24h.
+     *
+     * @example
+     * ```ts
+     * await client.usage.report('api_call', 1);
+     * // ou explicit:
+     * await client.usage.report('api_call', 5, { productId: 'gestovendas', tenantId: 't-acme' });
+     * ```
      */
     async report(resource, qty = 1, options) {
       if (!resource || typeof resource !== "string") {
@@ -222,11 +206,14 @@ function createUsageNamespace(config) {
           "tenantId required (pass to options or set on createNeetruClient)"
         );
       }
+      assertValidSdkId("productId", productId);
+      assertValidSdkId("tenantId", tenantId);
       const raw = await httpRequest(config, {
         method: "POST",
-        path: "/sdk/v1/usage/record",
+        path: "/api/sdk/v1/usage/record",
         body: { productId, tenantId, resource, qty: Math.floor(qty) },
-        requireAuth: true
+        requireAuth: true,
+        idempotencyKey: true
       });
       if (!raw || raw.ok !== true) {
         throw new NeetruError("invalid_response", "usage.report response missing ok");
@@ -241,7 +228,10 @@ function createUsageNamespace(config) {
       };
     },
     /**
-     * v0.3 — Verifica entitlement de um resource via GET /sdk/v1/entitlements.
+     * Verifica entitlement de um resource via `GET /api/sdk/v1/entitlements`.
+     * Resposta inclui `allowed`, `reason` ('granted' | 'not_subscribed' |
+     * 'subscription_inactive' | 'feature_not_in_plan' | 'limit_exceeded'),
+     * `remaining`, `limit`, `planId`, `planFeatures`.
      */
     async check(resource, options) {
       if (!resource || typeof resource !== "string") {
@@ -252,25 +242,29 @@ function createUsageNamespace(config) {
       if (!productId || !tenantId) {
         throw new NeetruError(
           "validation_failed",
-          "productId and tenantId required"
+          "productId and tenantId required (pass to options or set on createNeetruClient)"
         );
       }
+      assertValidSdkId("productId", productId);
+      assertValidSdkId("tenantId", tenantId);
       const raw = await httpRequest(config, {
         method: "GET",
-        path: "/sdk/v1/entitlements",
+        path: "/api/sdk/v1/entitlements",
         query: { productId, tenantId, feature: resource },
         requireAuth: true
       });
       if (!raw || typeof raw.allowed !== "boolean") {
         throw new NeetruError("invalid_response", "usage.check response missing allowed");
       }
+      const behavior = raw.behavior ?? (raw.reason === "limit_exceeded" ? "readonly" : null);
       return {
         allowed: raw.allowed,
         reason: raw.reason,
         remaining: raw.remaining,
         limit: raw.limit,
         planId: raw.planId,
-        planFeatures: raw.planFeatures
+        planFeatures: raw.planFeatures,
+        behavior
       };
     }
   };