@hazeloft/ai

Client oficial pentru Hazeloft AI Gateway. Zero dependențe, funcționează în Node 18+, edge runtimes (Cloudflare Workers, Vercel Edge, Deno) și — cu grijă — în browser. Folosește contul tău Hazeloft prin cheia hzx_.

Instalare

npm i @hazeloft/ai
# sau: bun add @hazeloft/ai / pnpm add @hazeloft/ai

De unde iau cheia

1. Cont pe hazeloft.com, plan Pro sau mai mare.
2. Dashboard → Integrations → AI Gateway → Activate.
3. Generează o cheie hzx_… (afișată o singură dată) și pune-o în mediu:

HAZELOFT_API_KEY=hzx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Cheia hzx_ e un secret de facturare — cine o are îți consumă cota. Folosește-o doar server-side (backend, edge function, route handler). În browser SDK-ul aruncă eroare intenționat; vezi dangerouslyAllowBrowser.

Utilizare

import { Hazeloft } from "@hazeloft/ai";

const hz = new Hazeloft(); // citește HAZELOFT_API_KEY

// Răspuns complet
const res = await hz.chat({
  messages: [{ role: "user", content: "Scrie un haiku despre mare." }],
});
console.log(res.content, res.usage);

// Streaming
for await (const delta of hz.stream({
  messages: [{ role: "user", content: "Numără până la 5." }],
})) {
  process.stdout.write(delta);
}

// Modelele disponibile pe contul tău
console.log(await hz.models());

Modelul e opțional — dacă îl omiți, gateway-ul folosește modelul implicit al contului. Pasează model ca să-l alegi explicit (hz.models() îți dă lista).

Configurare

new Hazeloft({
  apiKey: "hzx_…",          // implicit: HAZELOFT_API_KEY
  baseURL: "https://…/v1",  // implicit: HAZELOFT_BASE_URL sau gateway.hazeloft.com
  headers: { "x-app": "…" },// headere suplimentare
  fetch: customFetch,        // fetch propriu (runtime fără fetch global / teste)
  dangerouslyAllowBrowser: false,
});

Erori

Toate moștenesc din HazeloftError (status, code, type, requestId):

| Clasă | Când | | --- | --- | | HazeloftAuthError | cheie invalidă / integrare inactivă / plan insuficient (401/403) | | HazeloftBadRequestError | payload greșit, model inexistent, prea mare (400/413) | | HazeloftRateLimitError | rate sau cotă depășită (429); .isQuota distinge cota lunară | | HazeloftServerError | eroare gateway/upstream (5xx) | | HazeloftConnectionError | rețeaua a picat înainte de răspuns | | HazeloftConfigError | configurare invalidă (cheie lipsă, browser) |

import { HazeloftRateLimitError } from "@hazeloft/ai";

try {
  await hz.chat({ messages });
} catch (err) {
  if (err instanceof HazeloftRateLimitError && err.isQuota) {
    // cota lunară epuizată
  }
}

Licență

MIT © Hazeloft Enterprise S.R.L