TypeScript SDK

​

Install

npm install @vaquill-ai/sdk

​

Quickstart

import { Vaquill } from "@vaquill-ai/sdk";

const client = new Vaquill(); // reads VAQUILL_API_KEY (must start with vq_key_)

const res = await client.statutes.search({ query: "assault with a deadly weapon", state: "tx" });
console.log(res.results?.length, res.creditsConsumed);

const { data, meta } = await client.statutes.getSection("USC_T42_C21_S1983").withResponse();
console.log(meta.requestId, meta.creditsConsumed, meta.rateLimit.remainingDay);

const result = await client.statutes.resolve({ cite: "42 U.S.C. 1983" });
if (result.resolved && result.section) {
  const body = await client.statutes.getSectionBody(result.section.actId);
  console.log(body.plain);
}

​

Client options

• apiKey defaults to VAQUILL_API_KEY. Keys that do not start with vq_key_ are rejected.
• baseURL defaults to VAQUILL_BASE_URL, then https://api.vaquill.ai.
• timeout is per attempt, in milliseconds (default 60000). maxRetries defaults to 2.
• fetch injects a custom implementation, for a proxy or a test double.
• maxCredits is the spend guard, described below. client.creditsSpent shows the running total.
• logger is where log lines go: any subset of debug, info, warn and error, defaulting to console. logLevel is the minimum level, default warn. debug logs each request and response, info adds retries, and warn reports deprecated endpoints once per method and path. The API key is always redacted.
• client.withOptions({ ... }) returns a derived client that shares the key and the spend counter.
• Every method takes { timeout, maxRetries, headers, signal, idempotencyKey } as its last argument.

​

Namespaces

​

Which calls cost credits

​

Spend guard

const client = new Vaquill({ maxCredits: 500 });
console.log(client.creditsSpent);

​

Error handling

import {
  Vaquill,
  InsufficientCreditsError,
  RateLimitError,
  APIStatusError,
} from "@vaquill-ai/sdk";

const client = new Vaquill();

try {
  await client.statutes.resolve({ cite: "42 U.S.C. 1983" });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // 402. Never retried. Top up, then call again.
    console.error("out of credits", err.status, err.requestId);
  } else if (err instanceof RateLimitError) {
    console.error("rate limited, retry after", err.retryAfterSeconds);
  } else if (err instanceof APIStatusError) {
    console.error(err.status, err.requestId, err.code, err.body);
  } else {
    throw err;
  }
}

​

Retries and idempotency

• Retried: 408, 429 and 5xx, plus 409 only for idempotency_in_progress. Connection errors and timeouts are retried when it is safe.
• Backoff is 0.5 s doubling to an 8 s cap, scaled down by 0 to 25 percent jitter. retry-after-ms wins over Retry-After (seconds or date), which wins over the body’s retryAfterSeconds. A wait above 120 s is not retried.
• Never retried: insufficient_credits (402), daily_cap_exceeded, any 4xx other than the above, and anything the server marks retryable: false.
• Each charged call gets one generated Idempotency-Key, reused on every retry of that call. When the server honours the key, a retry cannot charge twice. Pass idempotencyKey: "..." to choose your own.
• With idempotencyKey: false a charged call is not retried after a timeout, connection error or 5xx, because it could charge twice. A 429 rate_limited is still retried, since it is refused before any work.
• Free POSTs without a key (watches.create, watches.test) follow the same rule, so a retry cannot create a second watch.

​

Pagination

for await (const s of client.statutes.searchAll({ query: "negligence" }, { maxPages: 3, maxItems: 50 })) {
  console.log(s);
}

​

Batch helpers

• options takes the usual request options plus chunkSize. A value above the cap is clamped to it, so the helper never sends a request the server would refuse.
• The spend guard is checked before each chunk, and exact repeats in the input are sent once.
• An empty input sends nothing.
• All three are charged.

​

Raw responses

const { data, meta } = await client.statutes.getSection("USC_T42_C21_S1983").withResponse();
console.log(meta.requestId, meta.creditsConsumed, meta.rateLimit.remainingDay);

​

Alerts and webhook verification

const created = await client.watches.create({
  corpusType: "state",
  state: "wa",
  channel: "webhook",
  webhookUrl: "https://example.com/hooks/law-changes",
});
console.log(created.data.id);

import { webhooks } from "@vaquill-ai/sdk";

const event = await webhooks.unwrap(rawBody, request.headers, process.env.WEBHOOK_SECRET!);