Foloseste beta-ul Rivya TypeScript SDK pentru a apela Public API v1 pentru modele, generari, fisiere, credite, webhookuri si Chat, inclusiv streaming SSE.

Rivya ofera un beta TypeScript SDK pentru integrari Public API server-side.

SDK-ul este un client subtire peste Rivya Public API v1. Contractul de nivel inferior ramane Contract OpenAPI si schema, iar metodele SDK trebuie sa ramana aliniate cu acea schema.

Status

Pachetul este mentinut in prezent in acest repository ca beta privata. Nu este publicat pe npm pana cand numele pachetului, metadata, changelogul si procesul de release nu sunt aprobate explicit.

SDK-ul accepta:

listarea modelelor
crearea si recuperarea generarilor asincrone
incarcare si recuperare prin Files API
recuperarea soldului de credite
gestionarea endpointurilor webhook, livrari de test, listarea evenimentelor, listarea livrarilor si rotatia secretului
verificarea semnaturilor webhook
completari Chat non-streaming si streaming, plus sesiuni de chat create prin API

Streamingul Chat este disponibil in acest beta privat prin parsare SSE server-side. Pastreaza cheile API secrete pe server.

Instalare in acest repo

Foloseste sursa locala a pachetului cat timp SDK-ul este in beta:

pnpm --dir packages/rivya-sdk typecheck

Codul aplicatiei ar trebui sa pastreze cheia API secreta pe server:

import { RivyaClient } from "@rivya/sdk";

const rivya = new RivyaClient({
  apiKey: process.env.RIVYA_API_KEY
});

Nu pune chei API secrete in bundle-uri de browser, localStorage, evenimente de analytics, capturi de ecran sau tickete partajate.

Listeaza modelele

models.list este public si nu necesita o cheie API:

const models = await rivya.models.list();

for (const model of models.data) {
  console.log(model.id, model.api_status, model.supported_api_inputs);
}

Creeaza o generare

Foloseste generations.create pentru generare asincrona de imagine, video sau audio:

const generation = await rivya.generations.create(
  {
    model: "z-image",
    prompt: "O imagine editoriala curata de produs pe un fundal moale de studio",
    client_request_id: "order-123-preview"
  },
  {
    idempotencyKey: "order-123-preview"
  }
);

console.log(generation.id, generation.status);

Apoi interogheaza cu generations.retrieve:

const current = await rivya.generations.retrieve(generation.id);
console.log(current.status, current.result?.primary_url);

Foloseste Idempotency-Key pentru cereri de scriere in productie. SDK-ul expune acest lucru ca idempotencyKey.

Incarca fisiere

Foloseste files.upload pentru imagini, video sau audio de referinta:

import { readFile } from "node:fs/promises";

const file = new Blob([await readFile("./reference.png")], {
  type: "image/png"
});

const uploaded = await rivya.files.upload({
  file,
  filename: "reference.png",
  kind: "image",
  model: "nano-banana-2",
  client_request_id: "asset-123"
});

console.log(uploaded.id, uploaded.url);

Foloseste files.retrieve pentru a citi din nou metadata incarcata:

const sameFile = await rivya.files.retrieve(uploaded.id);
console.log(sameFile.mime_type, sameFile.duration_token);

Cand folosesti un fisier intr-o generare, trimite campurile publice returnate prin params.referenceMediaItems:

await rivya.generations.create({
  model: "nano-banana-2",
  prompt: "Restilizeaza aceasta fotografie de produs pentru o pagina de catalog editorial curata",
  params: {
    referenceMediaItems: [
      {
        url: uploaded.url,
        kind: uploaded.kind,
        name: uploaded.file_name,
        mimeType: uploaded.mime_type,
        durationSeconds: uploaded.duration_seconds ?? undefined,
        durationToken: uploaded.duration_token ?? undefined
      }
    ]
  }
});

Verifica creditele

const credits = await rivya.credits.retrieve();
console.log(credits.current_credits);

Gestioneaza webhookuri

Creeaza un endpoint webhook:

const endpoint = await rivya.webhooks.create({
  name: "Production webhook",
  url: "https://example.com/rivya/webhook",
  event_types: ["generation.succeeded", "generation.failed"]
});

console.log(endpoint.id, endpoint.signing_secret);

signing_secret este returnat doar dupa apeluri de creare sau rotatie. Stocheaza-l pe serverul tau.

Alte helper-e webhook:

await rivya.webhooks.list();
await rivya.webhooks.retrieve(endpoint.id);
await rivya.webhooks.update(endpoint.id, { status: "disabled" });
await rivya.webhooks.test(endpoint.id);
await rivya.webhooks.rotateSecret(endpoint.id);
await rivya.webhooks.deliveries.list(endpoint.id, { limit: 20 });
await rivya.webhookEvents.list({ limit: 20 });

Verifica semnaturile livrarilor inainte sa ai incredere in payloadurile webhook:

import { verifyRivyaWebhookSignature } from "@rivya/sdk";

const ok = await verifyRivyaWebhookSignature({
  rawBody,
  timestamp: request.headers.get("rivya-webhook-timestamp") || "",
  signatureHeader: request.headers.get("rivya-webhook-signature") || "",
  signingSecret: process.env.RIVYA_WEBHOOK_SIGNING_SECRET || ""
});

if (!ok) {
  throw new Error("Invalid Rivya webhook signature");
}

Helperul SDK foloseste acelasi contract HMAC-SHA256 documentat in API Webhooks.

Chat

Foloseste chat.completions.create pentru o tura Chat API non-streaming:

const completion = await rivya.chat.completions.create(
  {
    model: "gpt-5-2-chat",
    message: "Scrie un plan concis de lansare pentru o campanie noua de imagini de produs",
    client_request_id: "chat-001"
  },
  {
    idempotencyKey: "chat-001"
  }
);

console.log(completion.session_id, completion.message.content);

Continua cu session_id returnat:

await rivya.chat.completions.create({
  model: "gpt-5-2-chat",
  session_id: completion.session_id,
  message: "Acum transforma asta intr-un checklist de executie in 5 pasi."
});

Citeste sesiunile create prin API:

await rivya.chat.sessions.list({ limit: 20 });
await rivya.chat.sessions.retrieve(completion.session_id);

Foloseste chat.completions.stream pentru a consuma Server-Sent Events ca async iterator:

const stream = await rivya.chat.completions.stream(
  {
    model: "gpt-5-2-chat",
    message: "Scrie un plan concis de lansare pentru o campanie noua de imagini de produs",
    client_request_id: "chat-stream-001"
  },
  {
    idempotencyKey: "chat-stream-001"
  }
);

for await (const event of stream) {
  if (event.event === "message.delta") {
    process.stdout.write(event.data.delta);
  }

  if (event.event === "message.completed") {
    console.log(event.data.message.id);
  }
}

message.delta este doar pentru afisare. Rezultatul confirmat este disponibil dupa message.completed si poate fi citit mai tarziu cu chat.sessions.retrieve.

Erori

SDK-ul arunca RivyaAPIError pentru raspunsuri Public API non-2xx:

import { RivyaAPIError } from "@rivya/sdk";

try {
  await rivya.generations.retrieve("task_missing");
} catch (error) {
  if (error instanceof RivyaAPIError) {
    console.log(error.status, error.code, error.requestId);
  }
}

RivyaAPIError include statusul HTTP, codul public de eroare, mesajul, request id cand este disponibil si un subset sigur de headere de raspuns.

Validare

Ruleaza verificarile SDK inainte sa tratezi o schimbare ca finalizata:

pnpm sdk:check
pnpm --dir packages/rivya-sdk typecheck
pnpm content:api-docs

pnpm sdk:check include o verificare statica de contract si o verificare runtime fara retea pentru parsarea erorilor, headere sigure de eroare, headere de idempotenta, auth Bearer, listarea publica a modelelor, parsarea SSE pentru streaming Chat, evenimentele de eroare in streaming Chat si verificarea semnaturilor webhook.

Rivya TypeScript SDK