@revinel/sdk

Zero dependencies; runs in any JS runtime with fetch (browser, Node, edge, workers).

Install

npm install @revinel/sdk

Usage

import { createRevinelClient } from "@revinel/sdk"

const revinel = createRevinelClient({
  workspaceId: "your-workspace-id",
  // apiUrl defaults to the Revinel production API
})

// Fetch the single ad currently serving for a placement.
const ad = await revinel.getAd({ weight: { gte: 2.5 } })

// Fetch several ads for a grid (rotation-aware; pass excludeIds to dedupe).
const ads = await revinel.getAds({ count: 5, excludeIds: ad ? [ad.id] : [] })

// Record events.
if (ad) {
  await revinel.recordImpression(ad.id)
  await revinel.recordClick(ad.id)
}

getAd resolves to RevinelAd | null; getAds to RevinelAd[] (empty when nothing is eligible; the SDK never throws on “no ads”).

Typed creative (`meta`)

ad.meta is keyed by each custom field’s stable machine slug (set when the publisher creates the field, e.g. bannerImage for a “Banner image” field). Pass your own interface for typesafe access:

interface AdMeta {
  tagline?: string
  description?: string
  bannerImage?: string
  ctaLabel?: string
}

const ad = await revinel.getAd<AdMeta>({ weight: { gte: 2.5 } })
ad?.meta.bannerImage // string | undefined, fully typed, no casting

Renaming a field’s display label never changes its slug, so your code keeps working.

Next.js / caching

Ad fetches default to next: { revalidate: 60 }, so App Router pages that call getAd/getAds stay statically renderable while the ad still refreshes every minute. (Revinel’s API edge-caches responses for ~5s anyway, so per-request rotation was always approximate.) Non-Next runtimes ignore the next key: server fetches (Node/edge) stay uncached, while browsers honor the response Cache-Control (max-age=5) and may reuse an identical request for up to ~5s, the same window the API’s edge cache already imposes. Opt out for true per-request rotation (on an already-dynamic Next page, or anywhere else):

const ad = await revinel.getAd({ request: { cache: "no-store" } })

Any explicit cache or next.revalidate you pass replaces the default entirely.

In Next.js server components, don’t wrap getAd in a try/catch that swallows every error. Errors carrying a digest property (e.g. DYNAMIC_SERVER_USAGE) are Next.js control flow, so rethrow them:

try {
  ad = await revinel.getAd()
} catch (error) {
  if (error && typeof error === "object" && "digest" in error) throw error
  ad = null // your actual fallback
}

Errors

Non-2xx responses throw RevinelApiError ({ status, body }). The body is the Revinel API error envelope:

{ "defined": false, "code": "NOT_FOUND", "status": 404, "message": "Workspace not found." }

Input-validation failures use HTTP 422 with code: "INPUT_VALIDATION_FAILED" and a data.fieldErrors / data.formErrors map. For React bindings see @revinel/react.

Revinel API

Guides

SDKs

API endpoints

Install

Usage

Typed creative (`meta`)

Next.js / caching

Errors

​Install

​Usage

​Typed creative (meta)

​Next.js / caching

​Errors

Install

Usage

Typed creative (`meta`)

Next.js / caching

Errors