@izak0s/spacebring-api 1.8.0 → 1.10.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/izak0s/spacebring-api/actions/workflows/ci.yml/badge.svg)](https://github.com/izak0s/spacebring-api/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/%40izak0s%2Fspacebring-api)](https://www.npmjs.com/package/@izak0s/spacebring-api)
+[![docs](https://img.shields.io/badge/docs-API%20reference-blue)](https://izak0s.github.io/spacebring-api/)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 A fully-typed TypeScript client for the [Spacebring](https://www.spacebring.com) coworking space management API, auto-generated from the official OpenAPI spec.
@@ -10,6 +11,8 @@ A fully-typed TypeScript client for the [Spacebring](https://www.spacebring.com)
 
 ---
 
+📖 **[Full API reference](https://izak0s.github.io/spacebring-api/)** — every resource, method, and type, generated from the source.
+
 ## Features
 
 - **<!-- coverage -->162 operations across 20 resource groups<!-- /coverage -->** — the full Spacebring API surface
@@ -38,40 +41,46 @@ No runtime dependencies — HTTP uses the built-in `fetch`.
 ## Quick Start
 
 ```ts
-import { Spacebring } from "@izak0s/spacebring-api";
+import { Spacebring, SpacebringError } from "@izak0s/spacebring-api";
 
 const sb = new Spacebring({
   clientId: process.env.SPACEBRING_CLIENT_ID!,
   clientSecret: process.env.SPACEBRING_CLIENT_SECRET!,
-  networkId: "your-network-id", // optional, sent as spacebring-network-id header
-  // baseUrl: "https://api.spacebring.com",  // default
-  // fetch: customFetch,                     // inject your own fetch (tests, proxies)
+  networkId: process.env.SPACEBRING_NETWORK_ID, // optional — sent as the spacebring-network-id header
 });
 
-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 });
+// Single-property envelopes are unwrapped — list() gives you Location[] directly.
+const locations = await sb.locations.list();
+const locationRef = locations[0].id;
 
-  // Paginated lists return the page envelope, so nextPageToken stays available
-  const { benefits, nextPageToken } = await sb.benefits.list({ locationRef });
+// 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 hand it to iterate(), which follows nextPageToken across pages.
+// Break out early and it simply stops fetching — no wasted requests.
+for await (const booking of sb.resources.bookings.iterate({ locationRef })) {
+  console.log(`${booking.startDate} → ${booking.endDate}`);
+}
 
-  // Endpoints returning multiple payloads keep the envelope
-  const { invoice: paid, payment } = await sb.billing.invoices.pay(invoiceId, {
-    paymentMethod: { type: "stripe" },
-  });
+// Non-2xx responses throw a typed SpacebringError.
+try {
+  await sb.billing.invoices.get("does-not-exist");
+} catch (error) {
+  if (error instanceof SpacebringError) {
+    console.error(`${error.status} on ${error.operation}: ${error.body?.message}`);
+  }
 }
+```
+
+Writes read the same, and endpoints that return more than one payload keep the envelope intact:
 
-main().catch(console.error);
+```ts
+const { invoice, payment } = await sb.billing.invoices.pay(invoiceId, {
+  paymentMethod: { type: "stripe" },
+});
 ```
 
-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). Query parameters get named interfaces too (`GetBookingsQuery`, `GetInvoicesQuery`), with per-field docs from the spec and enum filters as literal unions. Lower-level helpers too: `SpacebringConfig`, `SpacebringResources`, and the raw spec types `paths` / `components` / `operations`.
+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). Query parameters get named interfaces too (`GetBookingsQuery`, `GetInvoicesQuery`), with per-field docs from the spec and enum filters as literal unions, and request bodies get named types (`CreateBookingBody`, `UpdateInvoiceBody`). Lower-level helpers too: `SpacebringConfig`, `SpacebringResources`, and the raw spec types `paths` / `components` / `operations`.
 
 ### Data formats
 
@@ -87,6 +96,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.
 
+Because those credentials ride on every request, the client rejects a non-`https` `baseUrl` at construction — `http` is allowed only for loopback hosts (local proxies or mock servers). The default `baseUrl` is `https://api.spacebring.com`.
+
 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.
 
 ---

package/dist/index.cjs

@@ -2107,6 +2107,8 @@ var Spacebring = class {
   /** Typed openapi-fetch client — escape hatch for endpoints or options the facade does not cover. */
   raw;
   constructor(config) {
+    const baseUrl = config.baseUrl ?? "https://api.spacebring.com";
+    assertSecureBaseUrl(baseUrl);
     const headers = {
       Authorization: `Basic ${toBase64(`${config.clientId}:${config.clientSecret}`)}`
     };
@@ -2114,7 +2116,7 @@ var Spacebring = class {
       headers["spacebring-network-id"] = config.networkId;
     }
     this.raw = createClient({
-      baseUrl: config.baseUrl ?? "https://api.spacebring.com",
+      baseUrl,
       headers,
       fetch: withRetry(config.fetch ?? globalThis.fetch, config.maxRetries ?? 3, config.timeoutMs)
     });
@@ -2183,6 +2185,20 @@ function sleep(ms, signal) {
     signal.addEventListener("abort", onAbort, { once: true });
   });
 }
+function assertSecureBaseUrl(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error(`Spacebring baseUrl is not a valid URL: ${baseUrl}`);
+  }
+  if (url.protocol === "https:") return;
+  const isLoopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+  if (url.protocol === "http:" && isLoopback) return;
+  throw new Error(
+    `Spacebring baseUrl must use https (got "${url.protocol}//"): Basic-auth credentials would otherwise be sent in cleartext. Use https, or http only for a loopback host.`
+  );
+}
 function toBase64(value) {
   if (typeof Buffer !== "undefined") {
     return Buffer.from(value, "utf8").toString("base64");