@legalize-dev/sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -9,6 +9,27 @@ and this project adheres to [Semantic Versioning][semver].
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-06-17
+
+### Added
+
+- `requestRaw(method, path, options?)` on `Legalize` — the low-level
+  escape hatch for content negotiation. It fetches any endpoint in a
+  non-JSON wire format and returns a `RawResponse` (`.statusCode`,
+  `.content` as raw bytes, `.text`, `.contentType`, `.headers`) without
+  JSON-decoding. `options.format` controls the `Accept` header:
+  `"xml"` (the default) sends `application/xml`, `"json"` sends
+  `application/json`, and any other value is used verbatim as the media
+  type. Same retry policy, `lastResponse` population, and typed error
+  hierarchy as `request`.
+- `RawResponse` type, exported from the package, with a `.json()`
+  convenience parser. The SDK ships no XML parser and keeps zero runtime
+  dependencies — parse `.text`/`.content` with your own library.
+- `RequestRawOptions` type and the `formatToAccept` helper are exported.
+
+The typed resource methods still return JSON-parsed models; XML is opt-in
+per call via `requestRaw`. See the "Response formats" API docs.
+
 ## [0.1.0] — 2026-04-20
 
 ### Added

package/README.md

@@ -65,6 +65,31 @@ const past = await client.laws.atCommit("es", "ley_organica_3_2018", oldest);
 console.log(past.content_md); // Markdown at that revision
 ```
 
+### XML (and other raw formats)
+
+The typed methods always return JSON-parsed models. When your app speaks
+XML, use `requestRaw` to fetch any endpoint in another wire format via
+content negotiation — it sets `Accept` and hands you the body untouched:
+
+```ts
+const res = await client.requestRaw("GET", "/api/v1/es/laws/BOE-A-1978-31229");
+res.contentType;     // "application/xml; charset=utf-8"
+const xmlText = res.text;   // the raw XML string
+res.content;         // the raw bytes (Uint8Array)
+
+// format: "json" or any explicit media type works the same way:
+const data = (
+  await client.requestRaw("GET", "/api/v1/countries", { format: "json" })
+).json();
+```
+
+`requestRaw` defaults to `format: "xml"`. The SDK has **zero runtime
+dependencies and ships no XML parser** — parse `res.text` (or
+`res.content`) with your own library (`fast-xml-parser`,
+`@xmldom/xmldom`, …). Errors raise the same typed exceptions as the JSON
+methods (the error body is in the negotiated format). See the
+[Response formats](https://legalize.dev/docs/formats) docs.
+
 ### Abort + timeout
 
 Every method accepts a standard `AbortSignal`:

package/dist/index.cjs

@@ -744,7 +744,7 @@ var Webhooks = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 
 // src/client.ts
 function defaultUserAgent() {
@@ -755,6 +755,22 @@ function stripTrailingSlashes(s) {
   while (end > 0 && s.charCodeAt(end - 1) === 47) end--;
   return s.slice(0, end);
 }
+var FORMAT_ALIASES = {
+  xml: "application/xml",
+  json: "application/json"
+};
+function formatToAccept(format) {
+  const key = (format ?? "").trim().toLowerCase();
+  if (!key) return "application/xml";
+  return FORMAT_ALIASES[key] ?? format;
+}
+function headersToRecord(headers) {
+  const out = {};
+  headers.forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}
 var Legalize = class {
   countries;
   jurisdictions;
@@ -801,19 +817,100 @@ var Legalize = class {
    */
   async request(method, path, options = {}) {
     const upperMethod = method.toUpperCase();
-    const url = this.buildUrl(path, options.params);
     const headers = { ...this._headers };
     if (options.extraHeaders) Object.assign(headers, options.extraHeaders);
     if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
     const hasJson = options.json !== void 0;
     if (hasJson) headers["Content-Type"] = "application/json";
+    const response = await this.sendWithRetry(upperMethod, path, headers, options, hasJson);
+    this._lastResponse = response;
+    if (response.status === 204) return null;
+    const text = await response.text();
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new APIError({
+        message: "Server returned non-JSON body",
+        statusCode: response.status,
+        body: text,
+        response,
+        cause: err
+      });
+    }
+  }
+  /**
+   * Execute a request and return the raw, non-JSON-decoded body.
+   *
+   * The escape hatch for content negotiation: the typed resource methods
+   * always return JSON models, but `requestRaw` lets you fetch any
+   * endpoint in another wire format. `format` controls the `Accept`
+   * header — `"xml"` (the default) requests `application/xml`, `"json"`
+   * requests `application/json`, and any other value is sent verbatim as
+   * the media type.
+   *
+   * The SDK has zero runtime deps and ships no XML parser — parse the
+   * returned `.text` (or `.content`) with your own library.
+   *
+   * Example:
+   *
+   *   const res = await client.requestRaw("GET", "/api/v1/es/laws/BOE-A-1978-31229");
+   *   res.contentType; // "application/xml; charset=utf-8"
+   *   const xmlText = res.text; // already application/xml
+   *
+   * Throws the same APIError subclasses as {@link request} on a non-2xx
+   * response; the error body is in whatever format you negotiated.
+   */
+  async requestRaw(method, path, options = {}) {
+    const upperMethod = method.toUpperCase();
+    const headers = { ...this._headers };
+    headers["Accept"] = formatToAccept(options.format);
+    if (options.extraHeaders) Object.assign(headers, options.extraHeaders);
+    if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+    const response = await this.sendWithRetry(upperMethod, path, headers, options, false);
+    this._lastResponse = response;
+    return rawFromResponse(response);
+  }
+  /** Release any resources held by the client. Kept for API symmetry. */
+  async close() {
+  }
+  /** TS 5.2+ `using` / `await using` support. */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  // ---- internals --------------------------------------------------------
+  buildUrl(path, params) {
+    let base;
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+      base = path;
+    } else {
+      const p = path.startsWith("/") ? path : `/${path}`;
+      base = this._baseUrl + p;
+    }
+    if (!params) return base;
+    const query = buildQueryString(params);
+    if (!query) return base;
+    return base.includes("?") ? `${base}&${query}` : `${base}?${query}`;
+  }
+  /**
+   * Run the retry loop and return the raw 2xx `Response`.
+   *
+   * Shared by {@link request} (which then JSON-parses) and
+   * {@link requestRaw} (which builds a `RawResponse`). Applies the retry
+   * policy on transport errors and retryable statuses, populates
+   * `lastResponse` on the failing response before raising, and throws the
+   * typed `APIError` hierarchy on a final non-2xx. The returned response
+   * body is left unread for the caller to consume.
+   */
+  async sendWithRetry(method, path, headers, options, hasJson) {
+    const url = this.buildUrl(path, options.params);
     let attempt = 0;
     while (true) {
       let response;
       try {
-        response = await this.sendOnce(url, upperMethod, headers, options, hasJson);
+        response = await this.sendOnce(url, method, headers, options, hasJson);
       } catch (err) {
-        const shouldRetry2 = this._retry.shouldRetry(attempt, { method: upperMethod });
+        const shouldRetry2 = this._retry.shouldRetry(attempt, { method });
         if (!shouldRetry2) {
           throw wrapTransportError(err);
         }
@@ -823,25 +920,11 @@ var Legalize = class {
         continue;
       }
       if (response.status >= 200 && response.status < 300) {
-        this._lastResponse = response;
-        if (response.status === 204) return null;
-        const text = await response.text();
-        if (!text) return null;
-        try {
-          return JSON.parse(text);
-        } catch (err) {
-          throw new APIError({
-            message: "Server returned non-JSON body",
-            statusCode: response.status,
-            body: text,
-            response,
-            cause: err
-          });
-        }
+        return response;
       }
       const shouldRetry = this._retry.shouldRetry(attempt, {
         status: response.status,
-        method: upperMethod
+        method
       });
       if (!shouldRetry) {
         this._lastResponse = response;
@@ -857,27 +940,6 @@ var Legalize = class {
       attempt += 1;
     }
   }
-  /** Release any resources held by the client. Kept for API symmetry. */
-  async close() {
-  }
-  /** TS 5.2+ `using` / `await using` support. */
-  async [Symbol.asyncDispose]() {
-    await this.close();
-  }
-  // ---- internals --------------------------------------------------------
-  buildUrl(path, params) {
-    let base;
-    if (path.startsWith("http://") || path.startsWith("https://")) {
-      base = path;
-    } else {
-      const p = path.startsWith("/") ? path : `/${path}`;
-      base = this._baseUrl + p;
-    }
-    if (!params) return base;
-    const query = buildQueryString(params);
-    if (!query) return base;
-    return base.includes("?") ? `${base}&${query}` : `${base}?${query}`;
-  }
   async sendOnce(url, method, headers, options, hasJson) {
     const controller = new AbortController();
     const timeoutMs = this._timeout;
@@ -955,6 +1017,21 @@ async function errorFromResponse(response) {
   }
   return APIError.fromResponse(response, text, data);
 }
+async function rawFromResponse(response) {
+  const buffer = await response.arrayBuffer();
+  const content = new Uint8Array(buffer);
+  const text = new TextDecoder().decode(content);
+  return {
+    statusCode: response.status,
+    content,
+    text,
+    contentType: response.headers.get("content-type") ?? "",
+    headers: headersToRecord(response.headers),
+    json() {
+      return JSON.parse(text);
+    }
+  };
+}
 function wrapTransportError(err) {
   if (err instanceof Error) {
     const isAbort = err.name === "AbortError" || err.code === "ABORT_ERR";
@@ -1120,6 +1197,7 @@ exports.WebhookVerificationError = WebhookVerificationError;
 exports.Webhooks = Webhooks;
 exports.buildQueryString = buildQueryString;
 exports.defaultUserAgent = defaultUserAgent;
+exports.formatToAccept = formatToAccept;
 exports.parseRetryAfter = parseRetryAfter;
 exports.resolveApiKey = resolveApiKey;
 exports.resolveApiVersion = resolveApiVersion;