@izak0s/spacebring-api 1.1.0 → 1.2.0

package/README.md

@@ -85,6 +85,8 @@ Values are passed through exactly as the API sends them — no runtime conversio
 
 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
@@ -105,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

@@ -52,7 +52,7 @@ function createClient(clientOptions) {
     const {
       baseUrl: localBaseUrl,
       fetch = baseFetch,
-      Request = CustomRequest,
+      Request: Request2 = CustomRequest,
       headers,
       params = {},
       parseAs = "json",
@@ -104,7 +104,7 @@ function createClient(clientOptions) {
     };
     let id;
     let options;
-    let request = new Request(
+    let request = new Request2(
       createFinalURL(schemaPath, { baseUrl: finalBaseUrl, params, querySerializer, pathSerializer }),
       requestInit
     );
@@ -134,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;
@@ -1722,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
@@ -1738,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 }));
     }
   };
 }
@@ -2089,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");