@izak0s/spacebring-api 1.0.0 → 1.2.0

package/README.md

@@ -46,26 +46,38 @@ const sb = new Spacebring({
   // fetch: customFetch,                     // inject your own fetch (tests, proxies)
 });
 
-// Single-property envelopes are unwrapped: entities and plain arrays come back directly
-const invoice = await sb.billing.invoices.get(invoiceId);
-const locations = await sb.locations.list();
-await sb.visitors.visits.checkIn({ locationRef, visitRef });
-
-// Paginated lists return the page envelope, so nextPageToken stays available
-const { benefits, nextPageToken } = await sb.benefits.list({ locationRef });
+async function main() {
+  // Single-property envelopes are unwrapped: entities and plain arrays come back directly
+  const invoice = await sb.billing.invoices.get(invoiceId);
+  const locations = await sb.locations.list();
+  await sb.visitors.visits.checkIn({ locationRef, visitRef });
+
+  // Paginated lists return the page envelope, so nextPageToken stays available
+  const { benefits, nextPageToken } = await sb.benefits.list({ locationRef });
+
+  // ...or let iterate() walk nextPageToken for you; breaking early stops fetching
+  for await (const booking of sb.resources.bookings.iterate({ locationRef })) {
+    console.log(booking.id);
+  }
 
-// ...or let iterate() walk nextPageToken for you; breaking early stops fetching
-for await (const booking of sb.resources.bookings.iterate({ locationRef })) {
-  console.log(booking.id);
+  // Endpoints returning multiple payloads keep the envelope
+  const { invoice: paid, payment } = await sb.billing.invoices.pay(invoiceId, {
+    paymentMethod: { type: "stripe" },
+  });
 }
 
-// Endpoints returning multiple payloads keep the envelope
-const { invoice: paid, payment } = await sb.billing.invoices.pay(invoiceId, {
-  paymentMethod: { type: "stripe" },
-});
+main().catch(console.error);
 ```
 
-TypeScript helpers are exported too: `SpacebringConfig`, `SpacebringResources`, and the raw spec types `paths` / `components` / `operations` (e.g. `components["schemas"]["invoice"]`).
+Entity types are exported by name — `import type { Booking, Invoice, Membership } from "@izak0s/spacebring-api"` — matching what the methods return (`get`/`create`/`update` resolve to the entity, `iterate()` yields it). Lower-level helpers too: `SpacebringConfig`, `SpacebringResources`, and the raw spec types `paths` / `components` / `operations`.
+
+### Data formats
+
+Values are passed through exactly as the API sends them — no runtime conversion:
+
+- **Dates** (`createDate`, `startDate`, …) are ISO 8601 strings — wrap in `new Date(booking.startDate)` when you need a `Date`.
+- **Money** (`amount`, `price`, …) arrives as decimal floats. Fine for display; for accounting arithmetic convert to integer cents first to avoid floating-point drift.
+- **IDs** (`id`, `*Ref`) are UUID strings.
 
 ---
 
@@ -73,6 +85,8 @@ TypeScript helpers are exported too: `SpacebringConfig`, `SpacebringResources`,
 
 HTTP Basic with your **Client ID** and **Client Secret** from **Spacebring → [Network] → Network Settings → Developers**. The client builds the `Authorization: Basic …` header for you. The API's OAuth2 flow is not currently supported.
 
+For development without touching live data, Spacebring offers a [test environment](https://www.spacebring.com/docs/administration/test-environment) (Network settings → Billing add-on) with free sandbox API credentials that work with this client unchanged.
+
 ---
 
 ## Error handling
@@ -93,6 +107,10 @@ try {
 
 Malformed successes are covered too: a 2xx with an empty or incomplete body throws a `SpacebringError` (never a bare `TypeError`), and `iterate()` throws instead of looping forever if the API repeats a page token.
 
+### Rate limits
+
+The API allows **10 requests per second**. Rate-limited requests (429) are retried automatically — up to 3 times, honoring `Retry-After` or backing off exponentially — so `iterate()` survives the limit out of the box. Tune or disable via `maxRetries` in the config (`maxRetries: 0` turns it off); a 429 that persists past the retries is thrown as a normal `SpacebringError`.
+
 ---
 
 ## Escape hatch

package/dist/index.cjs

@@ -40,24 +40,27 @@ function createClient(clientOptions) {
     fetch: baseFetch = globalThis.fetch,
     querySerializer: globalQuerySerializer,
     bodySerializer: globalBodySerializer,
+    pathSerializer: globalPathSerializer,
     headers: baseHeaders,
     requestInitExt = void 0,
     ...baseOptions
   } = { ...clientOptions };
   requestInitExt = supportsRequestInitExt() ? requestInitExt : void 0;
   baseUrl = removeTrailingSlash(baseUrl);
-  const middlewares = [];
+  const globalMiddlewares = [];
   async function coreFetch(schemaPath, fetchOptions) {
     const {
       baseUrl: localBaseUrl,
       fetch = baseFetch,
-      Request = CustomRequest,
+      Request: Request2 = CustomRequest,
       headers,
       params = {},
       parseAs = "json",
       querySerializer: requestQuerySerializer,
       bodySerializer = globalBodySerializer ?? defaultBodySerializer,
+      pathSerializer: requestPathSerializer,
       body,
+      middleware: requestMiddlewares = [],
       ...init
     } = fetchOptions || {};
     let finalBaseUrl = baseUrl;
@@ -71,6 +74,7 @@ function createClient(clientOptions) {
         ...requestQuerySerializer
       });
     }
+    const pathSerializer = requestPathSerializer || globalPathSerializer || defaultPathSerializer;
     const serializedBody = body === void 0 ? void 0 : bodySerializer(
       body,
       // Note: we declare mergeHeaders() both here and below because it’s a bit of a chicken-or-egg situation:
@@ -90,6 +94,7 @@ function createClient(clientOptions) {
       headers,
       params.header
     );
+    const finalMiddlewares = [...globalMiddlewares, ...requestMiddlewares];
     const requestInit = {
       redirect: "follow",
       ...baseOptions,
@@ -99,8 +104,8 @@ function createClient(clientOptions) {
     };
     let id;
     let options;
-    let request = new Request(
-      createFinalURL(schemaPath, { baseUrl: finalBaseUrl, params, querySerializer }),
+    let request = new Request2(
+      createFinalURL(schemaPath, { baseUrl: finalBaseUrl, params, querySerializer, pathSerializer }),
       requestInit
     );
     let response;
@@ -109,16 +114,17 @@ function createClient(clientOptions) {
         request[key] = init[key];
       }
     }
-    if (middlewares.length) {
+    if (finalMiddlewares.length) {
       id = randomID();
       options = Object.freeze({
         baseUrl: finalBaseUrl,
         fetch,
         parseAs,
         querySerializer,
-        bodySerializer
+        bodySerializer,
+        pathSerializer
       });
-      for (const m of middlewares) {
+      for (const m of finalMiddlewares) {
         if (m && typeof m === "object" && typeof m.onRequest === "function") {
           const result = await m.onRequest({
             request,
@@ -128,7 +134,7 @@ function createClient(clientOptions) {
             id
           });
           if (result) {
-            if (result instanceof Request) {
+            if (result instanceof Request2) {
               request = result;
             } else if (result instanceof Response) {
               response = result;
@@ -145,9 +151,9 @@ function createClient(clientOptions) {
         response = await fetch(request, requestInitExt);
       } catch (error2) {
         let errorAfterMiddleware = error2;
-        if (middlewares.length) {
-          for (let i = middlewares.length - 1; i >= 0; i--) {
-            const m = middlewares[i];
+        if (finalMiddlewares.length) {
+          for (let i = finalMiddlewares.length - 1; i >= 0; i--) {
+            const m = finalMiddlewares[i];
             if (m && typeof m === "object" && typeof m.onError === "function") {
               const result = await m.onError({
                 request,
@@ -176,9 +182,9 @@ function createClient(clientOptions) {
           throw errorAfterMiddleware;
         }
       }
-      if (middlewares.length) {
-        for (let i = middlewares.length - 1; i >= 0; i--) {
-          const m = middlewares[i];
+      if (finalMiddlewares.length) {
+        for (let i = finalMiddlewares.length - 1; i >= 0; i--) {
+          const m = finalMiddlewares[i];
           if (m && typeof m === "object" && typeof m.onResponse === "function") {
             const result = await m.onResponse({
               request,
@@ -198,14 +204,22 @@ function createClient(clientOptions) {
         }
       }
     }
-    if (response.status === 204 || request.method === "HEAD" || response.headers.get("Content-Length") === "0") {
+    const contentLength = response.headers.get("Content-Length");
+    if (response.status === 204 || request.method === "HEAD" || contentLength === "0" && !response.headers.get("Transfer-Encoding")?.includes("chunked")) {
       return response.ok ? { data: void 0, response } : { error: void 0, response };
     }
     if (response.ok) {
-      if (parseAs === "stream") {
-        return { data: response.body, response };
-      }
-      return { data: await response[parseAs](), response };
+      const getResponseData = async () => {
+        if (parseAs === "stream") {
+          return response.body;
+        }
+        if (parseAs === "json" && !contentLength) {
+          const raw = await response.text();
+          return raw ? JSON.parse(raw) : void 0;
+        }
+        return await response[parseAs]();
+      };
+      return { data: await getResponseData(), response };
     }
     let error = await response.text();
     try {
@@ -259,15 +273,15 @@ function createClient(clientOptions) {
         if (typeof m !== "object" || !("onRequest" in m || "onResponse" in m || "onError" in m)) {
           throw new Error("Middleware must be an object with one of `onRequest()`, `onResponse() or `onError()`");
         }
-        middlewares.push(m);
+        globalMiddlewares.push(m);
       }
     },
     /** Unregister middleware */
     eject(...middleware) {
       for (const m of middleware) {
-        const i = middlewares.indexOf(m);
+        const i = globalMiddlewares.indexOf(m);
         if (i !== -1) {
-          middlewares.splice(i, 1);
+          globalMiddlewares.splice(i, 1);
         }
       }
     }
@@ -448,7 +462,7 @@ function defaultBodySerializer(body, headers) {
 function createFinalURL(pathname, options) {
   let finalURL = `${options.baseUrl}${pathname}`;
   if (options.params?.path) {
-    finalURL = defaultPathSerializer(finalURL, options.params.path);
+    finalURL = options.pathSerializer(finalURL, options.params.path);
   }
   let search = options.querySerializer(options.params.query ?? {});
   if (search.startsWith("?")) {
@@ -1708,8 +1722,8 @@ function createSubscriptions(client, defaults) {
      *
      * Retrieve a certain subscription.
      */
-    async get(id) {
-      return unwrapProp(await client.GET("/subscriptions/v1/{id}", { params: { path: { id } } }), "subscription");
+    async get(subscriptionId) {
+      return unwrapProp(await client.GET("/subscriptions/v1/{subscriptionId}", { params: { path: { subscriptionId } } }), "subscription");
     },
     /**
      * Create a subscription
@@ -1724,28 +1738,28 @@ function createSubscriptions(client, defaults) {
      *
      * Update a certain subscription.
      */
-    async update(id, body) {
-      return unwrap(await client.PATCH("/subscriptions/v1/{id}", { params: { path: { id } }, body }));
+    async update(subscriptionId, body) {
+      return unwrap(await client.PATCH("/subscriptions/v1/{subscriptionId}", { params: { path: { subscriptionId } }, body }));
     },
     /**
      * Delete a subscription
      *
      * Delete a certain subscription.
      */
-    async delete(id) {
-      return unwrap(await client.DELETE("/subscriptions/v1/{id}", { params: { path: { id } } }));
+    async delete(subscriptionId) {
+      return unwrap(await client.DELETE("/subscriptions/v1/{subscriptionId}", { params: { path: { subscriptionId } } }));
     },
     /** Create a subscription item */
-    async createItem(id, body) {
-      return unwrapProp(await client.POST("/subscriptions/v1/{id}/items", { params: { path: { id } }, body }), "subscription");
+    async createItem(subscriptionId, body) {
+      return unwrapProp(await client.POST("/subscriptions/v1/{subscriptionId}/items", { params: { path: { subscriptionId } }, body }), "subscription");
     },
     /** Delete a subscription item */
-    async deleteItem(id, itemId) {
-      return unwrap(await client.DELETE("/subscriptions/v1/{id}/items/{itemId}", { params: { path: { id, itemId } } }));
+    async deleteItem(subscriptionId, itemId) {
+      return unwrap(await client.DELETE("/subscriptions/v1/{subscriptionId}/items/{itemId}", { params: { path: { subscriptionId, itemId } } }));
     },
     /** Update a subscription item */
-    async updateItem(id, itemId, body) {
-      return unwrap(await client.PATCH("/subscriptions/v1/{id}/items/{itemId}", { params: { path: { id, itemId } }, body }));
+    async updateItem(subscriptionId, itemId, body) {
+      return unwrap(await client.PATCH("/subscriptions/v1/{subscriptionId}/items/{itemId}", { params: { path: { subscriptionId, itemId } }, body }));
     }
   };
 }
@@ -2075,11 +2089,25 @@ var Spacebring = class {
     this.raw = createClient({
       baseUrl: config.baseUrl ?? "https://api.spacebring.com",
       headers,
-      fetch: config.fetch
+      fetch: withRetry(config.fetch ?? globalThis.fetch, config.maxRetries ?? 3)
     });
     Object.assign(this, createResources2(this.raw, { networkId: config.networkId }));
   }
 };
+function withRetry(fetchImpl, maxRetries) {
+  if (maxRetries <= 0) return fetchImpl;
+  return async (input, init) => {
+    const request = input instanceof Request && init === void 0 ? input : new Request(input, init);
+    for (let attempt = 0; ; attempt += 1) {
+      const response = await fetchImpl(request.clone());
+      if (response.status !== 429 || attempt >= maxRetries) return response;
+      const retryAfterHeader = response.headers.get("retry-after");
+      const retryAfter = retryAfterHeader === null ? Number.NaN : Number(retryAfterHeader);
+      const delayMs = Number.isFinite(retryAfter) && retryAfter >= 0 ? Math.min(retryAfter * 1e3, 6e4) : Math.min(250 * 2 ** attempt + Math.random() * 100, 5e3);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  };
+}
 function toBase64(value) {
   if (typeof Buffer !== "undefined") {
     return Buffer.from(value, "utf8").toString("base64");