@legalize-dev/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -704,6 +704,47 @@ interface RequestOptions {
      */
     idempotencyKey?: string;
 }
+interface RequestRawOptions extends Omit<RequestOptions, "json"> {
+    /**
+     * The wire format to negotiate via the `Accept` header. `"xml"` (the
+     * default) requests `application/xml`, `"json"` requests
+     * `application/json`, and any other value is sent verbatim as the
+     * media type (so `format: "text/xml"` works too). Empty falls back to
+     * XML.
+     */
+    format?: string;
+}
+/**
+ * A raw, non-JSON-decoded API response.
+ *
+ * Returned by {@link Legalize.requestRaw} for content negotiation — when
+ * you want the body in a specific wire format (e.g. XML) instead of the
+ * typed JSON model the resource methods return. The SDK has zero runtime
+ * dependencies and ships no XML parser: parse `.text` (or `.content`)
+ * with your own library (e.g. `fast-xml-parser`, `@xmldom/xmldom`).
+ */
+interface RawResponse {
+    /** HTTP status of the response. */
+    statusCode: number;
+    /** Raw response body as bytes. */
+    content: Uint8Array;
+    /** The body decoded to a string (server charset, default UTF-8). */
+    text: string;
+    /** The `Content-Type` header value (e.g. `application/xml; charset=utf-8`). */
+    contentType: string;
+    /** The response headers as a plain, lower-cased mapping. */
+    headers: Record<string, string>;
+    /** Parse the body as JSON (handy when `format: "json"`). */
+    json(): unknown;
+}
+/**
+ * Map a `format` shorthand to an Accept media type.
+ *
+ * `"xml"` → `application/xml`, `"json"` → `application/json`. Any other
+ * value is treated as an explicit media type and sent as-is (so
+ * `format: "text/xml"` works too). Empty falls back to XML.
+ */
+declare function formatToAccept(format: string | undefined): string;
 /**
  * Synchronous-API, promise-based client for the Legalize API.
  *
@@ -746,11 +787,45 @@ declare class Legalize {
      * failure.
      */
     request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * 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.
+     */
+    requestRaw(method: string, path: string, options?: RequestRawOptions): Promise<RawResponse>;
     /** Release any resources held by the client. Kept for API symmetry. */
     close(): Promise<void>;
     /** TS 5.2+ `using` / `await using` support. */
     [Symbol.asyncDispose](): Promise<void>;
     private buildUrl;
+    /**
+     * 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.
+     */
+    private sendWithRetry;
     private sendOnce;
 }
 /**
@@ -1007,6 +1082,6 @@ declare class Webhook {
  * output without extra wiring, so we duplicate the literal here. The test
  * suite asserts they match so drift is caught immediately.
  */
-declare const SDK_VERSION = "0.1.0";
+declare const SDK_VERSION = "0.2.0";
 
-export { APIConnectionError, APIError, type APIErrorOptions, APITimeoutError, type ApiValidationError, AuthenticationError, type Commit, type CommitsResponse, Countries, type CountryInfo, DEFAULT_API_VERSION, DEFAULT_BACKOFF_FACTOR, DEFAULT_BASE_URL, DEFAULT_INITIAL_DELAY, DEFAULT_MAX_DELAY, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_TOLERANCE_SECONDS, type FetchImpl, ForbiddenError, type HTTPValidationError, IDEMPOTENT_METHODS, InvalidRequestError, type JurisdictionInfo, Jurisdictions, KEY_PREFIX, type LawAtCommitResponse, type LawDetail, type LawFilterOptions, type LawIterOptions, type LawListOptions, type LawMeta, type LawSearchOptions, type LawSearchResult, type LawSort, LawTypes, Laws, Legalize, LegalizeError, type LegalizeOptions, NotFoundError, OffsetIterator, PAGE_MAX, PageIterator, type PaginatedLaws, RETRY_STATUSES, RateLimitError, type Reform, type ReformIterOptions, type ReformListOptions, Reforms, type ReformsResponse, type RequestOptions, RetryPolicy, type RetryPolicyOptions, SDK_VERSION, ServerError, ServiceUnavailableError, Stats, type StatsOptions, type StatsResponse, ValidationError, Webhook, type WebhookCreateOptions, type WebhookDeliveriesOptions, type WebhookDeliveriesPage, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEndpoint, type WebhookEndpointCreate, type WebhookEndpointUpdate, type WebhookEvent, type WebhookUpdateOptions, WebhookVerificationError, type WebhookVerificationReason, type WebhookVerifyOptions, Webhooks, buildQueryString, defaultUserAgent, parseRetryAfter, resolveApiKey, resolveApiVersion, resolveBaseUrl, sleep };
+export { APIConnectionError, APIError, type APIErrorOptions, APITimeoutError, type ApiValidationError, AuthenticationError, type Commit, type CommitsResponse, Countries, type CountryInfo, DEFAULT_API_VERSION, DEFAULT_BACKOFF_FACTOR, DEFAULT_BASE_URL, DEFAULT_INITIAL_DELAY, DEFAULT_MAX_DELAY, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_TOLERANCE_SECONDS, type FetchImpl, ForbiddenError, type HTTPValidationError, IDEMPOTENT_METHODS, InvalidRequestError, type JurisdictionInfo, Jurisdictions, KEY_PREFIX, type LawAtCommitResponse, type LawDetail, type LawFilterOptions, type LawIterOptions, type LawListOptions, type LawMeta, type LawSearchOptions, type LawSearchResult, type LawSort, LawTypes, Laws, Legalize, LegalizeError, type LegalizeOptions, NotFoundError, OffsetIterator, PAGE_MAX, PageIterator, type PaginatedLaws, RETRY_STATUSES, RateLimitError, type RawResponse, type Reform, type ReformIterOptions, type ReformListOptions, Reforms, type ReformsResponse, type RequestOptions, type RequestRawOptions, RetryPolicy, type RetryPolicyOptions, SDK_VERSION, ServerError, ServiceUnavailableError, Stats, type StatsOptions, type StatsResponse, ValidationError, Webhook, type WebhookCreateOptions, type WebhookDeliveriesOptions, type WebhookDeliveriesPage, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEndpoint, type WebhookEndpointCreate, type WebhookEndpointUpdate, type WebhookEvent, type WebhookUpdateOptions, WebhookVerificationError, type WebhookVerificationReason, type WebhookVerifyOptions, Webhooks, buildQueryString, defaultUserAgent, formatToAccept, parseRetryAfter, resolveApiKey, resolveApiVersion, resolveBaseUrl, sleep };

package/dist/index.js

@@ -722,7 +722,7 @@ var Webhooks = class {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 
 // src/client.ts
 function defaultUserAgent() {
@@ -733,6 +733,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;
@@ -779,19 +795,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);
         }
@@ -801,25 +898,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;
@@ -835,27 +918,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;
@@ -933,6 +995,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";
@@ -1058,6 +1135,6 @@ function webhookEventFromPayload(payload) {
   };
 }
 
-export { APIConnectionError, APIError, APITimeoutError, AuthenticationError, Countries, DEFAULT_API_VERSION, DEFAULT_BACKOFF_FACTOR, DEFAULT_BASE_URL, DEFAULT_INITIAL_DELAY, DEFAULT_MAX_DELAY, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_TOLERANCE_SECONDS, ForbiddenError, IDEMPOTENT_METHODS, InvalidRequestError, Jurisdictions, KEY_PREFIX, LawTypes, Laws, Legalize, LegalizeError, NotFoundError, OffsetIterator, PAGE_MAX, PageIterator, RETRY_STATUSES, RateLimitError, Reforms, RetryPolicy, SDK_VERSION, ServerError, ServiceUnavailableError, Stats, ValidationError, Webhook, WebhookVerificationError, Webhooks, buildQueryString, defaultUserAgent, parseRetryAfter, resolveApiKey, resolveApiVersion, resolveBaseUrl, sleep };
+export { APIConnectionError, APIError, APITimeoutError, AuthenticationError, Countries, DEFAULT_API_VERSION, DEFAULT_BACKOFF_FACTOR, DEFAULT_BASE_URL, DEFAULT_INITIAL_DELAY, DEFAULT_MAX_DELAY, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, DEFAULT_TOLERANCE_SECONDS, ForbiddenError, IDEMPOTENT_METHODS, InvalidRequestError, Jurisdictions, KEY_PREFIX, LawTypes, Laws, Legalize, LegalizeError, NotFoundError, OffsetIterator, PAGE_MAX, PageIterator, RETRY_STATUSES, RateLimitError, Reforms, RetryPolicy, SDK_VERSION, ServerError, ServiceUnavailableError, Stats, ValidationError, Webhook, WebhookVerificationError, Webhooks, buildQueryString, defaultUserAgent, formatToAccept, parseRetryAfter, resolveApiKey, resolveApiVersion, resolveBaseUrl, sleep };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map