feat(items): add server field and improve item management

refactor(ai): enhance item structure generation with schema validation
feat(ai): add token usage tracking and cost calculation
fix(ui): improve item card number formatting with locale support
docs(items): add documentation for item value separation
test(items): add tests for value field validation

lib/ai/token-pricing.ts

@@ -0,0 +1,61 @@
+/**
+ * Utilitário de preços de tokens do Gemini e cálculo de custo por requisição
+ * Baseado em preços públicos aproximados para o modelo `gemini-2.5-flash`.
+ * Valores podem variar; mantenha sob revisão se houver mudança na tabela oficial.
+ */
+
+export interface UsageMetadata {
+  promptTokenCount?: number;
+  candidatesTokenCount?: number;
+  totalTokenCount?: number;
+}
+
+export interface TokenCostBreakdown {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  inputUsd: number;
+  outputUsd: number;
+  totalUsd: number;
+}
+
+type PricingTable = {
+  [model: string]: {
+    inputPerMillionTextImageVideo: number; // USD por 1M tokens de entrada (text/image/video)
+    outputPerMillion: number; // USD por 1M tokens de saída
+  };
+};
+
+// Tabela simplificada; ajuste se usar outros modelos no futuro
+export const TOKEN_PRICING: PricingTable = {
+  "gemini-2.5-flash": {
+    inputPerMillionTextImageVideo: 0.15, // USD
+    outputPerMillion: 1.25, // USD
+  },
+};
+
+/**
+ * Calcula custo em USD baseado em usageMetadata retornado pela API Gemini.
+ */
+export function calculateTokenCost(
+  model: keyof typeof TOKEN_PRICING,
+  usage: UsageMetadata | null | undefined,
+): TokenCostBreakdown {
+  const pricing = TOKEN_PRICING[model] ?? TOKEN_PRICING["gemini-2.5-flash"];
+  const inputTokens = Math.max(0, Number(usage?.promptTokenCount || 0));
+  const outputTokens = Math.max(0, Number(usage?.candidatesTokenCount || 0));
+  const totalTokens = Math.max(0, Number(usage?.totalTokenCount || inputTokens + outputTokens));
+
+  const inputUsd = (inputTokens / 1_000_000) * pricing.inputPerMillionTextImageVideo;
+  const outputUsd = (outputTokens / 1_000_000) * pricing.outputPerMillion;
+  const totalUsd = inputUsd + outputUsd;
+
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    inputUsd,
+    outputUsd,
+    totalUsd,
+  };
+}