Models، generations، files، credits، webhooks، اور SSE streaming سمیت Chat کے لیے Public API v1 call کرنے کے لیے Rivya TypeScript SDK beta استعمال کریں۔

Rivya server-side Public API integrations کے لیے TypeScript SDK beta فراہم کرتا ہے۔

SDK Rivya Public API v1 کے اوپر ایک thin client ہے۔ Lower-level contract OpenAPI and Schema Contract ہی رہتا ہے، اور SDK methods کو اس schema کے ساتھ aligned رہنا چاہیے۔

Status

Package فی الحال اس repository کے اندر private beta کے طور پر maintain ہوتا ہے۔ Package name، metadata، changelog، اور release process explicitly approve ہونے تک یہ npm پر publish نہیں ہوتا۔

SDK یہ support کرتا ہے:

model listing
asynchronous generation create اور retrieve
Files API upload اور retrieve
credit balance retrieval
webhook endpoint management، test deliveries، event listing، delivery listing، اور secret rotation
webhook signature verification
non-streaming اور streaming Chat completions، plus API-created chat sessions

Chat streaming اس private beta میں server-side SSE parsing کے ذریعے available ہے۔ Secret API keys اپنے server پر رکھیں۔

اس repo میں install

SDK beta میں ہو تو local package source استعمال کریں:

pnpm --dir packages/rivya-sdk typecheck

Application code کو secret API key server پر رکھنی چاہیے:

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

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

Secret API keys کو browser bundles، localStorage، analytics events، screenshots، یا shared tickets میں نہ رکھیں۔

Models list کریں

models.list public ہے اور API key require نہیں کرتا:

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

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

Generation create کریں

Asynchronous image، video، یا audio generation کے لیے generations.create استعمال کریں:

const generation = await rivya.generations.create(
  {
    model: "z-image",
    prompt: "soft studio background پر clean editorial product image",
    client_request_id: "order-123-preview"
  },
  {
    idempotencyKey: "order-123-preview"
  }
);

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

پھر generations.retrieve سے poll کریں:

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

Production write requests کے لیے Idempotency-Key استعمال کریں۔ SDK اسے idempotencyKey کے طور پر expose کرتا ہے۔

Files upload کریں

Reference images، videos، یا audio کے لیے files.upload استعمال کریں:

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);

Uploaded metadata دوبارہ read کرنے کے لیے files.retrieve استعمال کریں:

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

Generation میں file استعمال کرتے وقت returned public fields کو params.referenceMediaItems کے ذریعے pass کریں:

await rivya.generations.create({
  model: "nano-banana-2",
  prompt: "اس product photo کو clean editorial catalog page کے لیے restyle کریں",
  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
      }
    ]
  }
});

Credits check کریں

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

Webhooks manage کریں

Webhook endpoint create کریں:

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 صرف create یا rotate calls کے بعد return ہوتا ہے۔ اسے اپنے server پر store کریں۔

دیگر webhook helpers:

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 });

Webhook payloads پر trust کرنے سے پہلے delivery signatures verify کریں:

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");
}

SDK helper وہی HMAC-SHA256 contract استعمال کرتا ہے جو API Webhooks میں documented ہے۔

Chat

ایک non-streaming Chat API turn کے لیے chat.completions.create استعمال کریں:

const completion = await rivya.chat.completions.create(
  {
    model: "gpt-5-2-chat",
    message: "نئی product image campaign کے لیے مختصر launch plan لکھیں",
    client_request_id: "chat-001"
  },
  {
    idempotencyKey: "chat-001"
  }
);

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

Returned session_id سے continue کریں:

await rivya.chat.completions.create({
  model: "gpt-5-2-chat",
  session_id: completion.session_id,
  message: "اب اسے 5-step execution checklist میں بدلیں۔"
});

API-created sessions read کریں:

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

Server-Sent Events کو async iterator کے طور پر consume کرنے کے لیے chat.completions.stream استعمال کریں:

const stream = await rivya.chat.completions.stream(
  {
    model: "gpt-5-2-chat",
    message: "نئی product image campaign کے لیے مختصر launch plan لکھیں",
    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 صرف display کے لیے ہے۔ Committed result message.completed کے بعد available ہوتا ہے، اور بعد میں chat.sessions.retrieve سے read کیا جا سکتا ہے۔

Errors

Non-2xx Public API responses کے لیے SDK RivyaAPIError throw کرتا ہے:

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 میں HTTP status، public error code، message، available ہو تو request id، اور safe response-header subset شامل ہوتا ہے۔

Validation

Change کو complete سمجھنے سے پہلے SDK checks run کریں:

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

pnpm sdk:check میں static contract check اور no-network runtime check شامل ہیں، جو error parsing، safe error headers، idempotency headers، Bearer auth، public model listing، Chat streaming SSE parsing، Chat streaming error events، اور webhook signature verification cover کرتے ہیں۔

Rivya TypeScript SDK

فہرست