node-legal-docs-client

A client for the Case Law Explorer API, for TypeScript on a server.

npm install node-legal-docs-client

Server-side only

This holds an API key. Do not import it into browser code.

A key given to a page is readable by anyone who opens developer tools — and, worse, usable by them to make whatever calls they like against your quota. Hiding it behind a bundler does not help: import.meta.env.VITE_* is replaced with the literal value at build time, so the key ends up compiled into the JavaScript you ship.

Browser code should call your server. Your server calls this.

browser ──▶ your server ──▶ Case Law Explorer API
             (holds the key)

If you only need the shapes — to build a query in a form, or render a document — import legal-docs-types instead. It has no client and cannot make a request, so it is safe anywhere.

Use

import { createLegalDocsClient } from "node-legal-docs-client";

const client = createLegalDocsClient({
  apiKey: process.env.CITATIONS_API_KEY,
});

const results = await client.fetchRechtspraak({
  degreesSource: 1,
  degreesTarget: 1,
  keywords: ["huurrecht"],
});

In a Nuxt or Next server route

// server/api/legal-docs/search.post.ts
import { createLegalDocsClient } from "node-legal-docs-client";

const client = createLegalDocsClient({ apiKey: process.env.CITATIONS_API_KEY });

export default defineEventHandler(async (event) => {
  const query = await readBody(event);
  return query.dataset === "ECHR"
    ? client.fetchEchr(query.params)
    : client.fetchRechtspraak(query.params);
});

What it supports

| Method | Endpoint | |---|---| | fetchRechtspraak(query, computeStatistics?) | POST /rechtspraak | | fetchEchr(query, computeStatistics?) | POST /echr | | computeStatistics(docs) | POST /statistics | | getRechtspraakFullText(eclis) | POST /rechtspraak/text | | getEchrFullText(eclis, language?) | POST /echr/text | | fetchLaws(query) | GET /links/laws?q= |

setApiKey(key) and setHeaders(headers) change them after construction.

Errors

Failures throw ApiError, carrying the HTTP status and the response body.

import { ApiError } from "node-legal-docs-client";

try {
  await client.fetchRechtspraak(query);
} catch (err) {
  if (err instanceof ApiError && err.isAuthFailure) {
    // Your key, not their query. Do not show this to the person searching.
  } else if (err instanceof ApiError && err.status === 400) {
    // Their query. err.body says which filter was wrong.
  }
}

status is undefined when nothing answered at all — a timeout, a refused connection — so an absent status is never mistaken for the API's verdict.

Getting a token

https://api.caselawexplorer.tech/login.html?next=/account.html

Types

Every request and response shape comes from legal-docs-types, and is re-exported here so a server needs only this package in its dependencies. Browser code should depend on legal-docs-types directly and never on this.

The Go equivalent is go-legal-docs-client, which carries its own types: nothing in Go needs the shapes without the client, so there is no reason to split them there.

Development

npm install
npm link ../legal-docs-types   # to work against unreleased changes to the types
npm run build