create-ginko 0.4.0 → 0.5.0

package/templates/docs/content/docs/11.error-codes.md

@@ -0,0 +1,35 @@
+---
+title: Error codes
+description: Every code of OrbitError, its HTTP status, whether the client retries it, and what to do.
+---
+
+Every error the client throws is an `OrbitError` with these properties:
+
+| Property | Type | What it is |
+|---|---|---|
+| `code` | `string` | One of the codes below. |
+| `status` | `number \| null` | The HTTP status, or `null` when there was no answer. |
+| `message` | `string` | A sentence in English that says what went wrong. |
+| `requestId` | `string \| null` | The id of the request in Orbit’s logs, for support. |
+| `details` | `{ field: string; message: string }[]` | The wrong fields, for `validation_failed` only; else empty. |
+| `retryAfter` | `number \| null` | Seconds to wait, for `rate_limited` only. |
+
+## Codes
+
+| Code | HTTP | Retried | Meaning and what to do |
+|---|---|---|---|
+| `missing_api_key` | – | no | No key was passed and `ORBIT_API_KEY` is not set. Set it. |
+| `invalid_request` | 400 | no | The request is malformed. Check the method’s parameters. |
+| `invalid_cursor` | 400 | no | The cursor is older than 24 hours or belongs to other filters. Start the list again. |
+| `unauthorized` | 401 | no | The key is wrong or was deleted. |
+| `forbidden` | 403 | no | The key may not do this, for example a test key on live data. |
+| `not_found` | 404 | no | No monitor, incident or check with this id. |
+| `conflict` | 409 | no | The request clashes with the current state, for example a second monitor for the same address. |
+| `validation_failed` | 422 | no | A value is not allowed. `details` names each field. |
+| `rate_limited` | 429 | yes | More than 600 requests in a minute. The client waits `retryAfter` seconds. |
+| `server_error` | 500–504 | yes | A problem on Orbit’s side. If it lasts, check the status page. |
+| `timeout` | – | yes | No answer within `timeout`. |
+| `connection_failed` | – | yes | No connection to the API, for example a DNS or network failure. |
+| `invalid_signature` | – | no | `webhooks.verify()`: the signature does not match or the webhook is older than five minutes. |
+
+“Retried” means the client sends the request again by itself, up to `maxRetries` times, before it throws. See [Errors and retries]($docs.errors-and-retries).

package/templates/docs/content/docs/2.getting-started.de.md

@@ -0,0 +1,57 @@
+---
+title: Schnellstart
+slug: schnellstart
+description: Orbit SDK installieren, den API-Schlüssel setzen und den ersten Monitor anlegen.
+---
+
+:::steps
+### Paket installieren
+
+::code-group
+```bash [npm]
+npm install @orbit-example/sdk
+```
+```bash [pnpm]
+pnpm add @orbit-example/sdk
+```
+::
+
+### API-Schlüssel setzen
+
+Lege im Orbit-Dashboard unter **Settings > API keys** einen Schlüssel an und trage ihn in die Umgebung deines Servers ein. Zum lokalen Arbeiten reicht eine `.env`-Datei; halte sie aus Git heraus.
+
+```bash [.env]
+ORBIT_API_KEY=orb_test_4f9a2c7e1b
+```
+
+Ein Schlüssel, der mit `orb_test_` beginnt, wirkt nur auf Testdaten. So kannst du alles ausprobieren, ohne echte Monitore anzulegen.
+
+### Erste Anfrage senden
+
+```ts [check-shop.ts]
+import { Orbit } from '@orbit-example/sdk'
+
+const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY })
+
+const monitor = await orbit.monitors.create({
+  name: 'Shop-Kasse',
+  url: 'https://shop.example.com/checkout',
+})
+
+console.log(monitor.id, monitor.status) // mon_8f2k1x pending
+```
+
+Starte es mit `node --env-file=.env check-shop.ts`. Node.js 22.18 und neuer führen TypeScript-Dateien direkt aus.
+:::
+
+## Was passiert ist
+
+1. `new Orbit()` legt einen Client an. Er hält deinen Schlüssel, die Adresse der API und die Einstellungen für Wiederholungen; leg ihn einmal an und nutze ihn überall. Alle Optionen stehen unter [Client-Optionen]($docs.client).
+2. `orbit.monitors.create()` sendet eine Anfrage an die API und gibt den neuen Monitor zurück. Orbit prüft die Adresse einmal pro Minute aus der Region `eu-central`, bis du das änderst.
+3. Der Status ist `pending`, bis die erste Prüfung gelaufen ist, meist innerhalb einer Minute. Danach ist er `up` oder `down`.
+
+## Wie es weitergeht
+
+- Das Ergebnis jeder Prüfung und jeden Vorfall lesen: [Vorfälle und Prüfungen]($docs.incidents-and-checks).
+- Eine Nachricht bekommen, wenn der Shop ausfällt: [Webhooks]($docs.webhooks).
+- Eine fehlgeschlagene Anfrage behandeln: [Fehler und Wiederholungen]($docs.errors-and-retries).

package/templates/docs/content/docs/2.getting-started.md

@@ -0,0 +1,56 @@
+---
+title: Getting started
+description: Install Orbit SDK, set your API key and create your first monitor.
+---
+
+:::steps
+### Install the package
+
+::code-group
+```bash [npm]
+npm install @orbit-example/sdk
+```
+```bash [pnpm]
+pnpm add @orbit-example/sdk
+```
+::
+
+### Set your API key
+
+Create a key in the Orbit dashboard under **Settings > API keys** and put it in the environment of your server. For local work, a `.env` file is fine; keep it out of Git.
+
+```bash [.env]
+ORBIT_API_KEY=orb_test_4f9a2c7e1b
+```
+
+A key that starts with `orb_test_` works on test data only, so you can try everything without real monitors.
+
+### Send your first request
+
+```ts [check-shop.ts]
+import { Orbit } from '@orbit-example/sdk'
+
+const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY })
+
+const monitor = await orbit.monitors.create({
+  name: 'Shop checkout',
+  url: 'https://shop.example.com/checkout',
+})
+
+console.log(monitor.id, monitor.status) // mon_8f2k1x pending
+```
+
+Run it with `node --env-file=.env check-shop.ts`. Node.js 22.18 and newer run TypeScript files directly.
+:::
+
+## What happened
+
+1. `new Orbit()` creates a client. It holds your key, the address of the API and the retry settings; create it once and use it everywhere. All options are in [Client options]($docs.client).
+2. `orbit.monitors.create()` sends one request to the API and returns the new monitor. Orbit checks the address once a minute from the region `eu-central` until you change that.
+3. The status is `pending` until the first check has run, usually within a minute. After that it is `up` or `down`.
+
+## Next steps
+
+- Read the result of each check and every incident: [Incidents and checks]($docs.incidents-and-checks).
+- Get a message when the shop goes down: [Webhooks]($docs.webhooks).
+- Handle a request that fails: [Errors and retries]($docs.errors-and-retries).

package/templates/docs/content/docs/3.authentication.de.md

@@ -0,0 +1,55 @@
+---
+title: Authentifizierung
+slug: authentifizierung
+description: Einen API-Schlüssel anlegen, dem Client übergeben, geheim halten und ohne Ausfall austauschen.
+section: Anleitungen
+---
+
+Jede Anfrage an die Orbit API trägt einen API-Schlüssel. Der Client sendet ihn im `Authorization`-Header; du übergibst ihn nur einmal.
+
+## Schlüssel anlegen
+
+Öffne im Orbit-Dashboard **Settings > API keys** und wähle **Create key**. Orbit zeigt den Schlüssel genau einmal. Kopiere ihn in die Umgebung deines Servers oder in deinen Geheimnisspeicher.
+
+Es gibt zwei Arten von Schlüsseln:
+
+| Präfix | Wirkt auf | Nutze ihn für |
+|---|---|---|
+| `orb_live_` | deine echten Monitore und Vorfälle | den Betrieb |
+| `orb_test_` | eigene Testdaten | Entwicklung, CI, Ausprobieren |
+
+Testmonitore werden wie echte geprüft, ihre Prüfungen und Vorfälle bleiben aber in den Testdaten. Webhooks für Testdaten verschickt Orbit wie echte.
+
+## Schlüssel an den Client geben
+
+Übergibst du keinen Schlüssel, liest der Client `ORBIT_API_KEY` aus der Umgebung:
+
+```ts
+import { Orbit } from '@orbit-example/sdk'
+
+const orbit = new Orbit() // liest process.env.ORBIT_API_KEY
+```
+
+Übergib `apiKey`, wenn der Schlüssel von woanders kommt, etwa aus einem Geheimnisspeicher:
+
+```ts
+const orbit = new Orbit({ apiKey: await secrets.get('orbit-api-key') })
+```
+
+Ohne Schlüssel wirft `new Orbit()` sofort einen `OrbitError` mit dem Code `missing_api_key`, nicht erst bei der ersten Anfrage.
+
+## Schlüssel geheim halten
+
+- Nutze den Schlüssel nur in Servercode. In einer Nuxt- oder Next.js-App heißt das: in einer Server-Route oder einem Modul nur für den Server, nie in einer Komponente.
+- Halte ihn aus Git heraus: Trag `.env` in `.gitignore` ein.
+- Gib jeder App einen eigenen Schlüssel. Dann kannst du einen austauschen, ohne die anderen anzufassen.
+
+::callout{type="warning" title="Ein Schlüssel im Browser ist öffentlich"}
+Alles, was der Browser lädt, kann jeder lesen. Ist ein Schlüssel in Client-Code oder in einem öffentlichen Repository gelandet, lösch ihn sofort im Dashboard und leg einen neuen an.
+::
+
+## Schlüssel ohne Ausfall austauschen
+
+1. Leg im Dashboard einen zweiten Schlüssel an. Beide Schlüssel gelten gleichzeitig.
+2. Veröffentliche deine App mit dem neuen Schlüssel.
+3. Lösch den alten Schlüssel. Anfragen damit scheitern jetzt mit `unauthorized` (HTTP 401).

package/templates/docs/content/docs/3.authentication.md

@@ -0,0 +1,54 @@
+---
+title: Authentication
+description: Create an API key, give it to the client, keep it secret and replace it without downtime.
+section: Guides
+---
+
+Every request to the Orbit API carries an API key. The client sends it in the `Authorization` header; you only pass it once.
+
+## Create a key
+
+In the Orbit dashboard, open **Settings > API keys** and choose **Create key**. Orbit shows the key once. Copy it into the environment of your server or into your secret store.
+
+There are two kinds of keys:
+
+| Prefix | Works on | Use it for |
+|---|---|---|
+| `orb_live_` | your real monitors and incidents | production |
+| `orb_test_` | a separate set of test data | development, CI, trying things out |
+
+Test monitors are checked like real ones, but their checks and incidents stay in the test data. Webhooks for test data are sent like real ones.
+
+## Give the key to the client
+
+The client reads `ORBIT_API_KEY` from the environment when you pass no key:
+
+```ts
+import { Orbit } from '@orbit-example/sdk'
+
+const orbit = new Orbit() // reads process.env.ORBIT_API_KEY
+```
+
+Pass `apiKey` when the key comes from somewhere else, for example a secret store:
+
+```ts
+const orbit = new Orbit({ apiKey: await secrets.get('orbit-api-key') })
+```
+
+Without a key, `new Orbit()` throws an `OrbitError` with the code `missing_api_key` at once, not at the first request.
+
+## Keep the key secret
+
+- Use the key in server code only. In a Nuxt or Next.js app that means a server route or a server-only module, never a component.
+- Keep it out of Git: put `.env` in `.gitignore`.
+- Give each app its own key, so you can replace one without touching the others.
+
+::callout{type="warning" title="A key in the browser is a public key"}
+Anything the browser loads, anyone can read. If a key ended up in client code or in a public repository, delete it in the dashboard at once and create a new one.
+::
+
+## Replace a key without downtime
+
+1. Create a second key in the dashboard. Both keys work at the same time.
+2. Deploy your app with the new key.
+3. Delete the old key. Requests with it now fail with `unauthorized` (HTTP 401).

package/templates/docs/content/docs/4.pagination.de.md

@@ -0,0 +1,45 @@
+---
+title: Paginierung
+slug: paginierung
+description: Eine Seite einer Liste lesen oder mit for await jeden Eintrag. Cursor, Seitengröße und Filter.
+---
+
+Listen wie Monitore, Vorfälle und Prüfungen können lang sein, deshalb liefert die API sie in Seiten. Jede `list()`-Methode gibt dir einen `PageRequest`: Wartest du mit `await` darauf, bekommst du eine Seite; gehst du mit einer Schleife darüber, liest du jeden Eintrag.
+
+## Jeder Eintrag: for await
+
+```ts
+for await (const incident of orbit.incidents.list({ status: 'open' })) {
+  console.log(incident.id, incident.cause)
+}
+```
+
+Der Client holt die nächste Seite erst, wenn die Schleife sie braucht. Verlässt du die Schleife mit `break`, lädt er keine weitere Seite.
+
+## Eine Seite
+
+```ts
+const page = await orbit.monitors.list({ limit: 50 })
+
+page.data        // Monitor[], höchstens 50
+page.hasMore     // true, wenn es eine nächste Seite gibt
+page.nextCursor  // String für `cursor`, oder null auf der letzten Seite
+```
+
+Für eine Liste mit „Weiter“-Knopf merkst du dir `nextCursor` und gibst ihn bei der nächsten Anfrage mit:
+
+```ts
+const next = await orbit.monitors.list({ limit: 50, cursor: page.nextCursor })
+```
+
+## Seitengröße
+
+`limit` ist standardmäßig 20 und höchstens 100. Größere Seiten bedeuten weniger Anfragen, und das hilft beim Ratenlimit von 600 Anfragen pro Minute.
+
+## Reihenfolge und Filter
+
+Jede Liste ist nach dem Anlagedatum sortiert, die neuesten zuerst. Filter stehen neben `limit` und `cursor`, zum Beispiel `status` bei Monitoren und Vorfällen oder `monitorId` und `since` bei Prüfungen. Behalte für alle Seiten einer Liste dieselben Filter: Ein Cursor gehört zu den Filtern, mit denen er entstanden ist. Die Parameter jeder Liste stehen in der Referenz: [Monitore]($docs.monitors), [Vorfälle und Prüfungen]($docs.incidents-and-checks).
+
+::callout{type="note" title="Cursor laufen ab"}
+Ein Cursor gilt 24 Stunden. Danach scheitert die Anfrage mit `invalid_cursor` (HTTP 400); beginne die Liste dann ohne Cursor neu.
+::

package/templates/docs/content/docs/4.pagination.md

@@ -0,0 +1,44 @@
+---
+title: Pagination
+description: Read one page of a list, or every entry with for await. Cursors, page sizes and filters.
+---
+
+Lists such as monitors, incidents and checks can be long, so the API returns them in pages. Each `list()` method gives you a `PageRequest`: await it for one page, or loop over it to read every entry.
+
+## Every entry: for await
+
+```ts
+for await (const incident of orbit.incidents.list({ status: 'open' })) {
+  console.log(incident.id, incident.cause)
+}
+```
+
+The client asks for the next page only when the loop needs it. Leave the loop with `break` and no further page is loaded.
+
+## One page
+
+```ts
+const page = await orbit.monitors.list({ limit: 50 })
+
+page.data        // Monitor[], at most 50
+page.hasMore     // true when there is a next page
+page.nextCursor  // string to pass as `cursor`, or null on the last page
+```
+
+To show a list with a “Next” button, keep `nextCursor` and pass it with the next request:
+
+```ts
+const next = await orbit.monitors.list({ limit: 50, cursor: page.nextCursor })
+```
+
+## Page size
+
+`limit` is 20 by default and at most 100. A larger page means fewer requests, which helps with the rate limit of 600 requests per minute.
+
+## Order and filters
+
+Every list is ordered newest first by its creation date. Filters go next to `limit` and `cursor`, for example `status` for monitors and incidents, or `monitorId` and `since` for checks. Keep the same filters for every page of one list: a cursor belongs to the filters it was made with. The parameters of each list are in the reference: [Monitors]($docs.monitors), [Incidents and checks]($docs.incidents-and-checks).
+
+::callout{type="note" title="Cursors expire"}
+A cursor works for 24 hours. After that, the request fails with `invalid_cursor` (HTTP 400); start the list again without a cursor.
+::

package/templates/docs/content/docs/5.errors-and-retries.de.md

@@ -0,0 +1,69 @@
+---
+title: Fehler und Wiederholungen
+slug: fehler-und-wiederholungen
+description: Was der Client selbst wiederholt, was als OrbitError bei deinem Code ankommt und wie du jeden Fall behandelst.
+---
+
+Eine Anfrage kann aus zwei Arten von Gründen scheitern: an etwas Vorübergehendem, etwa einer abgebrochenen Verbindung oder einem ausgelasteten Server, oder an der Anfrage selbst, etwa einem falschen Schlüssel oder einem unbekannten Monitor. Die erste Art wiederholt der Client, die zweite wirft er.
+
+## Was wiederholt wird
+
+| Grund | Code | Wiederholt |
+|---|---|---|
+| Keine Verbindung, oder sie ist abgebrochen | `connection_failed` | ja |
+| Keine Antwort innerhalb der Wartezeit | `timeout` | ja |
+| Zu viele Anfragen (HTTP 429) | `rate_limited` | ja, nach der Zeit, die die API nennt |
+| Serverfehler (HTTP 500, 502, 503, 504) | `server_error` | ja |
+| Jeder andere Fehler (HTTP 4xx) | siehe [Fehlercodes]($docs.error-codes) | nein |
+
+Standardmäßig versucht der Client eine Anfrage bis zu dreimal: den ersten Versuch und zwei Wiederholungen, nach etwa 0,5 und 1 Sekunde (mit etwas Zufall, damit nicht viele Clients im selben Moment wiederholen). Ändern lässt sich das mit `maxRetries`:
+
+```ts
+const orbit = new Orbit({ maxRetries: 5 }) // bis zu 6 Versuche
+const strict = new Orbit({ maxRetries: 0 }) // nie wiederholen
+```
+
+Das Anlegen lässt sich gefahrlos wiederholen: Der Client sendet bei jedem `create()` einen `Idempotency-Key`-Header. So legt die API nur einen Monitor an, auch wenn eine Wiederholung auf eine verlorene Antwort folgt.
+
+## Einen Fehler behandeln
+
+Jeder Fehler, den der Client wirft, ist ein `OrbitError`. Sein `code` sagt, was passiert ist; `status` ist der HTTP-Status oder `null`, wenn keine Antwort kam.
+
+```ts
+import { Orbit, OrbitError } from '@orbit-example/sdk'
+
+try {
+  await orbit.monitors.pause('mon_8f2k1x')
+} catch (error) {
+  if (!(error instanceof OrbitError)) throw error
+  if (error.code === 'not_found') {
+    console.warn('Diesen Monitor gibt es nicht mehr.')
+  } else {
+    console.error(error.code, error.message, error.requestId)
+    throw error
+  }
+}
+```
+
+`requestId` benennt die Anfrage in den Protokollen von Orbit. Gib sie an, wenn du dem Orbit-Support schreibst.
+
+## Ungültige Werte
+
+Lehnt die API die gesendeten Werte ab, ist der Code `validation_failed`, und `details` nennt jedes Feld:
+
+```ts
+error.details // [{ field: 'interval', message: 'Must be 30, 60, 300 or 900.' }]
+```
+
+Die Meldungen der API sind immer auf Englisch.
+
+## Wartezeit
+
+Eine Anfrage wartet standardmäßig 30 Sekunden auf eine Antwort. Setze `timeout` (in Millisekunden) am Client oder für eine einzelne Anfrage:
+
+```ts
+const orbit = new Orbit({ timeout: 10_000 })
+await orbit.checks.list({ monitorId: 'mon_8f2k1x' }, { timeout: 60_000 })
+```
+
+Alle Codes mit ihrem HTTP-Status stehen unter [Fehlercodes]($docs.error-codes).

package/templates/docs/content/docs/5.errors-and-retries.md

@@ -0,0 +1,66 @@
+---
+title: Errors and retries
+description: What the client retries for you, what reaches your code as an OrbitError, and how to handle each case.
+---
+
+A request can fail for two kinds of reasons: something temporary, such as a lost connection or a busy server, or something about the request itself, such as a wrong key or an unknown monitor. The client retries the first kind and throws the second.
+
+## What is retried
+
+| Reason | Code | Retried |
+|---|---|---|
+| No connection, or the connection broke | `connection_failed` | yes |
+| No answer within the timeout | `timeout` | yes |
+| Too many requests (HTTP 429) | `rate_limited` | yes, after the time the API asks for |
+| Server error (HTTP 500, 502, 503, 504) | `server_error` | yes |
+| Any other error (HTTP 4xx) | see [Error codes]($docs.error-codes) | no |
+
+By default the client tries a request up to three times in all: the first attempt and two retries, after about 0.5 and 1 second (a little random time is added, so many clients do not retry at the same moment). Change it with `maxRetries`:
+
+```ts
+const orbit = new Orbit({ maxRetries: 5 }) // up to 6 attempts
+const strict = new Orbit({ maxRetries: 0 }) // never retry
+```
+
+Creating something is safe to retry: the client sends an `Idempotency-Key` header with every `create()`, so the API makes one monitor even when a retry follows an answer that got lost.
+
+## Handle an error
+
+Every error the client throws is an `OrbitError`. Its `code` says what happened; `status` is the HTTP status, or `null` when there was no answer.
+
+```ts
+import { Orbit, OrbitError } from '@orbit-example/sdk'
+
+try {
+  await orbit.monitors.pause('mon_8f2k1x')
+} catch (error) {
+  if (!(error instanceof OrbitError)) throw error
+  if (error.code === 'not_found') {
+    console.warn('That monitor was deleted.')
+  } else {
+    console.error(error.code, error.message, error.requestId)
+    throw error
+  }
+}
+```
+
+`requestId` names the request in Orbit’s logs. Include it when you write to Orbit support.
+
+## Validation errors
+
+When the API refuses the values you sent, the code is `validation_failed` and `details` lists each field:
+
+```ts
+error.details // [{ field: 'interval', message: 'Must be 30, 60, 300 or 900.' }]
+```
+
+## Timeouts
+
+A request waits 30 seconds for an answer by default. Set `timeout` (in milliseconds) on the client, or for one request:
+
+```ts
+const orbit = new Orbit({ timeout: 10_000 })
+await orbit.checks.list({ monitorId: 'mon_8f2k1x' }, { timeout: 60_000 })
+```
+
+Every code and its HTTP status are listed in [Error codes]($docs.error-codes).

package/templates/docs/content/docs/6.webhooks.de.md

@@ -0,0 +1,53 @@
+---
+title: Webhooks
+slug: webhooks
+description: Eine HTTP-Anfrage bekommen, wenn ein Monitor ausfällt oder wieder antwortet, und prüfen, dass Orbit sie geschickt hat.
+---
+
+Ein Webhook ist eine Anfrage, die Orbit an deinen Server schickt, wenn etwas passiert. So musst du die API nicht jede Minute fragen. Nutze ihn, um in einen Chat zu schreiben, die Bereitschaft zu alarmieren oder auf deiner Statusseite einen Hinweis zu zeigen.
+
+## Ereignisse
+
+| Ereignis | Kommt, wenn |
+|---|---|
+| `incident.opened` | ein Monitor zwei Prüfungen hintereinander nicht besteht und Orbit einen Vorfall eröffnet |
+| `incident.resolved` | der Monitor wieder antwortet oder jemand den Vorfall als behoben markiert |
+| `monitor.paused` | ein Monitor pausiert wird |
+| `monitor.resumed` | ein pausierter Monitor wieder startet |
+
+## Endpunkt hinzufügen
+
+Öffne im Orbit-Dashboard **Settings > Webhooks**, wähle **Add endpoint**, trag die Adresse deines Servers ein und wähle die Ereignisse. Orbit zeigt ein Signaturgeheimnis, das mit `whsec_` beginnt. Bewahre es wie einen API-Schlüssel auf, zum Beispiel als `ORBIT_WEBHOOK_SECRET`.
+
+## Signatur prüfen
+
+Jeder kann eine Anfrage an deinen Endpunkt schicken. Jeder Webhook von Orbit trägt einen `orbit-signature`-Header, der mit deinem Signaturgeheimnis entstanden ist; `orbit.webhooks.verify()` prüft ihn und gibt das Ereignis zurück. Übergib den Body genau so, wie er ankam, als Text und nicht als geparstes JSON.
+
+```ts [server/api/orbit-webhook.post.ts]
+import { Orbit, OrbitError } from '@orbit-example/sdk'
+
+const orbit = new Orbit()
+
+export default defineEventHandler(async (event) => {
+  const body = await readRawBody(event, 'utf8')
+  const signature = getHeader(event, 'orbit-signature')
+  try {
+    const hook = orbit.webhooks.verify(body ?? '', signature ?? '', process.env.ORBIT_WEBHOOK_SECRET!)
+    if (hook.type === 'incident.opened') await notifyTeam(hook.data.monitorId, hook.data.cause)
+    return { ok: true }
+  } catch (error) {
+    if (error instanceof OrbitError && error.code === 'invalid_signature') throw createError({ statusCode: 400 })
+    throw error
+  }
+})
+```
+
+`verify()` lehnt außerdem Webhooks ab, die älter als fünf Minuten sind. So lässt sich eine mitgeschnittene Anfrage nicht später noch einmal senden.
+
+## Schnell antworten
+
+Antworte innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Bekommt Orbit einen anderen Status oder keine Antwort, sendet es den Webhook erneut: nach 1 Minute, 10 Minuten, 1 Stunde und 6 Stunden, danach nicht mehr. Dasselbe Ereignis kann also mehr als einmal ankommen; `hook.id` ist jedes Mal gleich, überspring also eine id, die du schon kennst.
+
+## Ausprobieren
+
+Im Dashboard schickt **Send test event** ein `incident.opened`-Ereignis für einen Testmonitor an deinen Endpunkt. Um einen Server auf deinem eigenen Rechner zu erreichen, nutze einen Tunnel wie `cloudflared` oder `ngrok`.

package/templates/docs/content/docs/6.webhooks.md

@@ -0,0 +1,52 @@
+---
+title: Webhooks
+description: Receive an HTTP request when a monitor goes down or comes back, and check that Orbit sent it.
+---
+
+A webhook is a request Orbit sends to your server when something happens, so you do not have to ask the API every minute. Use it to post to a chat, page the person on call, or show a notice on your status page.
+
+## Events
+
+| Event | Sent when |
+|---|---|
+| `incident.opened` | a monitor fails two checks in a row and Orbit opens an incident |
+| `incident.resolved` | the monitor answers again, or someone resolves the incident |
+| `monitor.paused` | a monitor is paused |
+| `monitor.resumed` | a paused monitor is resumed |
+
+## Add an endpoint
+
+In the Orbit dashboard, open **Settings > Webhooks**, choose **Add endpoint**, enter the address of your server and pick the events. Orbit shows a signing secret that starts with `whsec_`. Store it like an API key, for example as `ORBIT_WEBHOOK_SECRET`.
+
+## Check the signature
+
+Anyone can send a request to your endpoint. Each webhook from Orbit carries an `orbit-signature` header made with your signing secret; `orbit.webhooks.verify()` checks it and returns the event. Pass the body exactly as it arrived, as text, not parsed JSON.
+
+```ts [server/api/orbit-webhook.post.ts]
+import { Orbit, OrbitError } from '@orbit-example/sdk'
+
+const orbit = new Orbit()
+
+export default defineEventHandler(async (event) => {
+  const body = await readRawBody(event, 'utf8')
+  const signature = getHeader(event, 'orbit-signature')
+  try {
+    const hook = orbit.webhooks.verify(body ?? '', signature ?? '', process.env.ORBIT_WEBHOOK_SECRET!)
+    if (hook.type === 'incident.opened') await notifyTeam(hook.data.monitorId, hook.data.cause)
+    return { ok: true }
+  } catch (error) {
+    if (error instanceof OrbitError && error.code === 'invalid_signature') throw createError({ statusCode: 400 })
+    throw error
+  }
+})
+```
+
+`verify()` also refuses a webhook older than five minutes, so a recorded request cannot be sent again later.
+
+## Answer quickly
+
+Answer with any 2xx status within 10 seconds. Orbit sends a webhook again when it gets another status or no answer: after 1 minute, 10 minutes, 1 hour and 6 hours, then it gives up. The same event can therefore arrive more than once; `hook.id` is the same each time, so skip an id you have seen.
+
+## Try it
+
+In the dashboard, **Send test event** sends an `incident.opened` event for a test monitor to your endpoint. To reach a server on your own computer, use a tunnel such as `cloudflared` or `ngrok`.

package/templates/docs/content/docs/7.upgrading-to-v2.md

@@ -0,0 +1,73 @@
+---
+title: Upgrading to 2.0
+description: What changed from Orbit SDK 1.x to 2.0 and how to update your code, step by step.
+---
+
+Version 2.0 has a new package name, one client object instead of separate functions, cursors instead of page numbers and one error class. Most apps need about half an hour to update. This page is in English only.
+
+## 1. Change the package
+
+The package moved from `orbit-sdk` to `@orbit-example/sdk`:
+
+```bash
+npm uninstall orbit-sdk
+npm install @orbit-example/sdk
+```
+
+2.0 needs Node.js 22 or newer and ES modules. Replace `require()` with `import`.
+
+## 2. Create one client
+
+```ts
+// 1.x
+import { OrbitClient } from 'orbit-sdk'
+const client = new OrbitClient('orb_live_…')
+
+// 2.0
+import { Orbit } from '@orbit-example/sdk'
+const orbit = new Orbit({ apiKey: 'orb_live_…' })
+```
+
+## 3. Rename the methods
+
+| 1.x | 2.0 |
+|---|---|
+| `client.listMonitors()` | `orbit.monitors.list()` |
+| `client.getMonitor(id)` | `orbit.monitors.get(id)` |
+| `client.addMonitor(url, name)` | `orbit.monitors.create({ url, name })` |
+| `client.removeMonitor(id)` | `orbit.monitors.delete(id)` |
+| `client.listIncidents(monitorId)` | `orbit.incidents.list({ monitorId })` |
+| `client.closeIncident(id, { note })` | `orbit.incidents.resolve(id, { note })` |
+| `verifyWebhook(body, signature, secret)` | `orbit.webhooks.verify(body, signature, secret)` |
+
+## 4. Replace page numbers with cursors
+
+1.x took `page` and `perPage`. 2.0 takes `limit` and `cursor`, and `for await` reads every page:
+
+```ts
+// 1.x
+for (let page = 1; ; page++) {
+  const monitors = await client.listMonitors({ page, perPage: 100 })
+  if (!monitors.length) break
+  // …
+}
+
+// 2.0
+for await (const monitor of orbit.monitors.list({ limit: 100 })) {
+  // …
+}
+```
+
+See [Pagination]($docs.pagination).
+
+## 5. Catch one error class
+
+1.x threw `OrbitHttpError`, `OrbitTimeoutError` and `OrbitAuthError`. 2.0 throws `OrbitError` and puts the reason in `code`:
+
+| 1.x | 2.0 |
+|---|---|
+| `OrbitAuthError` | `OrbitError` with `code` `unauthorized` or `forbidden` |
+| `OrbitTimeoutError` | `OrbitError` with `code` `timeout` |
+| `OrbitHttpError` with `status` 404 | `OrbitError` with `code` `not_found` |
+
+1.x did not retry; 2.0 retries temporary errors twice by default. If your code retried by itself, remove that loop or set `maxRetries: 0`. See [Errors and retries]($docs.errors-and-retries).