@adveron/sdk

TypeScript client for the Adveron public API — the tenant /v1 surface, generated from the API's own OpenAPI document. Runs in Node (18+) and the browser; the transport is fetch.

The client is generated, not hand-written. Every operation, every request shape, and every response type comes from the same registered operations the server dispatches, so the client cannot describe a surface the API does not serve.

Install

pnpm add @adveron/sdk

Authentication

Every call authenticates with a workspace API key as a bearer token. Configure the shared client once:

import { client } from "@adveron/sdk";

client.setConfig({
  baseUrl: "https://api.adveron.com",
  auth: () => process.env.ADVERON_API_KEY!,
});

Or build an isolated client (useful when one process serves several workspaces):

import { createClient, createConfig } from "@adveron/sdk";

const adveron = createClient(
  createConfig({ baseUrl: "https://api.adveron.com", auth: () => apiKey })
);

Every operation accepts a client option, so a per-request client needs no global state.

Responses

Operations return { data, error } — never a throw on an HTTP status. A successful body is { data, meta }, where meta always carries the request_id that also rides the X-Request-Id response header.

Failures carry the house envelope, { error: { code, message, request_id, details? } }. isAdveronError narrows it:

import { brandGet, isAdveronError } from "@adveron/sdk";

const { data, error } = await brandGet({ path: { id: brandId } });
if (isAdveronError(error)) {
  // error.error.code is one of the stable machine codes — e.g.
  // "resource_not_activated", "insufficient_credits", "rate_limited"
  console.error(error.error.code, error.error.request_id);
}

Quote request_id in a support request: it joins our logs, traces, and the credit ledger.

One example per group

Brands — search first; every other brand operation takes an id, not a name.

import { brandSearch, brandGet } from "@adveron/sdk";

const { data: found } = await brandSearch({ query: { q: "nike", limit: 5 } });
const { data: brand } = await brandGet({
  path: { id: found!.data.items[0].id },
});

Categories

import { categoryList } from "@adveron/sdk";

const { data } = await categoryList();
// data.data.items[0].subcategories — the launched children under each category

Audiences

import { audienceGet } from "@adveron/sdk";

const { data } = await audienceGet({ path: { id: "AUD123" } });

Balance & usage

import { balanceGet, usageSummary } from "@adveron/sdk";

const { data: balance } = await balanceGet();
const { data: usage } = await usageSummary({
  query: { group_by: "WORKSPACE" },
});

Metering headers

Successful responses carry X-Credits-Charged / X-Credits-Reason and the organization's purchased throughput as RateLimit-*. Reads answer Cache-Control: no-store. Send an Idempotency-Key header to make a call safe to retry — recommended on metered GETs, where an auto-retried read would otherwise double-charge.

Reference

The full operation reference, with request and response shapes for every /v1 endpoint, is the API's own interactive documentation at https://api.adveron.com/v1/docs — the same OpenAPI document this client is generated from.