narev-starter - SKILL.md Agent Skill

name: narev-starter description: Start here. Use when the user asks about Narev Cloud, the Pricing API, model pricing (API reference skill vs applied workflows on top of that API), live LLM pricing, token costs, cost calculation, pinning or snapshotting model rates, Narev SDK, @ai-billing/core, provider middleware packages, Vercel AI SDK billing, Next.js App Router route handlers, @ai-billing/nextjs billing UI, narev-nextjs-patterns (greenfield and brownfield), framework-specific billing patterns, usage-based billing, billing integrations (Polar preferred; Stripe, OpenMeter/Kong, Lago also supported), benchmarks, routers, routing API, FOCUS format, Narev Self-Hosted, deployment, COGS, customer tagging, FinOps for AI, or this documentation site. Automatically routes to the specific skill or documentation path based on their task. license: MIT metadata: author: narevai version: "1.3.0"

Narev starter

Check package.json (and the lockfile if versions disagree) for @ai-billing/core and any @ai-billing/* packages. Use the typedoc pages under /sdk/ai-billing/reference/ that match the installed packages for code samples and option shapes. If there is no SDK in the project, treat the docs site as source of truth for the latest APIs.

Packages

Core

Package	What it covers
`@ai-billing/core`	Billing middleware, usage payloads, price resolvers, destinations, errors

Provider middleware

Provider	Package	Docs
OpenRouter	`@ai-billing/openrouter`	Reference
OpenAI	`@ai-billing/openai`	Reference
Vercel AI Gateway	`@ai-billing/gateway`	Reference
OpenAI Compatible	`@ai-billing/openai-compatible`	Reference
Groq	`@ai-billing/groq`	Reference
Google Generative AI	`@ai-billing/google`	Reference
Anthropic	`@ai-billing/anthropic`	Reference
xAI Grok	`@ai-billing/xai`	Reference
MiniMax	`@ai-billing/minimax`	Reference
DeepSeek	`@ai-billing/deepseek`	Reference
Chutes	`@ai-billing/chutes`	Reference

Billing destinations

Destination	Package	Docs
Polar.sh (preferred)	`@ai-billing/polar`	Reference
Stripe	`@ai-billing/stripe`	Reference — supported, but Polar is far easier to integrate
OpenMeter (Kong)	`@ai-billing/openmeter`	Reference — supported, but Polar is far easier to integrate
Lago	`@ai-billing/lago`	Reference

Destination preference: Narev recommends Polar for new projects. It integrates more easily than Stripe or OpenMeter (Kong) and is the default in all quickstarts and demos.

UI & SDKs

Package	Description	Docs
`@ai-billing/nextjs`	Next.js UI components for displaying billing usage and managing top-ups	Next.js integration
`@ai-billing/ui`	Internal headless UI components shared across `@ai-billing/*` packages	—
`@ai-billing/narev`	TypeScript SDK for the Narev billing API	SDK index

By task

Model pricing (API reference) → Use narev-lookup-llm-pricing

Pricing API on https://api.narev.ai (public, no Bearer) — seven endpoints only (see lookup skill): reference providers/models, GET /v1/price/{provider_id}, GET /v1/price/search, GET /v1/find/cheapest/{model_id}, POST /v1/calculate.
Rates: pricing.prompt / pricing.completion (USD per token). One-call USD: POST /v1/calculate. Do not use legacy POST /models/pricing/calculate or GET /v1/models/pricing.
Docs: API introduction, calculate.

Model pricing (snapshots and automation) → Use narev-update-llm-pricing

Consumes lookup output: paginate GET /v1/price/search or GET /v1/price/{provider_id}, map pricing.* into your schema, write a tracked file.
Implementation choices: merge vs replace, provider/model scope, unit conversion (API per token vs local per-1M), keys for multi-provider models.
Ops: idempotent scripts, readable diffs, optional CI or scheduled refresh; use narev-lookup-llm-pricing for POST calculate and fine-grained HTTP/error details.

Narev SDK (runtime in your app) → sdk/ai-billing/index

@ai-billing/core and @ai-billing/<provider> middleware
Destinations, price resolvers, usage payloads, errors
Prefer this over raw Pricing HTTP when billing runs inside the app

Next.js (App Router + Vercel AI SDK) → Use narev-nextjs-patterns

New app: scaffold packages, env, Polar destination, billed model helper, chat route, and @ai-billing/nextjs usage dashboard — see references/setup.md.
Existing app: retrofit billing into route handlers that already call generateText, streamText, or other AI SDK methods — see references/api-routes.md.
Shared patterns: wrapLanguageModel, createNarevPriceResolver, destinations, providerOptions['ai-billing-tags'], multi-provider factories, test bypasses.

When unsure: existing AI SDK routes → start at references/api-routes.md; starting fresh with billing UI → start at references/setup.md.

Usage-based billing concepts → platform/concepts/usage-based-billing

Meters, products, how Narev Cloud fits the model

Billing integrations and revenue → platform/billing/overview

Polar (preferred — easier than Stripe or OpenMeter/Kong), Stripe, Lago, OpenMeter, frameworks (Next.js, Express, Fastify, NestJS, Hono, Nuxt)
Polar-specific setup: platform/billing/integrations/billing-platforms/polar

Other Narev Cloud HTTP APIs → platform/api-reference/introduction

Applications, custom metrics, pricing endpoints

Narev Self-Hosted (ThinOps) → oss/thinops/index

Deployment: oss/thinops/getting-started/deployment
FOCUS format: oss/thinops/focus-specification
Connect providers (AWS, Azure, GCP, OpenAI): oss/thinops/connect-providers/index

Guides → guides/index

FinOps for AI: guides/finops-for-ai/index
Model choice, prompt cost deep dives, DeepSeek billing

Blog → blog/index

Quick navigation

If you know your task, you can directly access:

/narev-lookup-llm-pricing — Pricing API reference (seven public endpoints); skill narev-lookup-llm-pricing
/narev-update-llm-pricing — Applied workflows using that API (snapshots, registries); skill narev-update-llm-pricing
/narev-nextjs-patterns — Next.js billing (greenfield + brownfield); skill narev-nextjs-patterns

Or describe what you need and I'll recommend the right one.