the-real-snipeit-mcp 0.1.5

package/.env.example

@@ -0,0 +1,8 @@
+# Required: Snipe-IT Personal API Token (JWT). Get from Snipe-IT > User > Manage API Keys.
+SNIPEIT_API_TOKEN=
+
+# Optional overrides
+SNIPEIT_API_BASE=https://snipe-it.example.com/api/v1
+SNIPEIT_CONFIRM_WRITES=false
+SNIPEIT_TIMEOUT_MS=30000
+SNIPEIT_LOG_LEVEL=info

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## 0.1.5 — 2026-05-25
+
+- Public release preparation: neutralized example domain in defaults (`https://snipe-it.example.com/api/v1`, RFC 2606 reserved).
+- `package.json` polished for npm publish: `author`, `repository`, `homepage`, `bugs`, `keywords`, `publishConfig.access: public`.
+- First npm release (`the-real-snipeit-mcp@0.1.5`).
+- Repo switched from private to public.
+
+## 0.1.4 — 2026-05-25
+
+- Docs: README extended with full tool reference (39 hand-wrappers in tables, plus workflow recipes).
+- Docs: new `ARCHITECTURE.md` (layer diagram, data flow, codegen pipeline, file map).
+- Docs: new `CONTRIBUTING.md` (workflows for adding tools/resources/prompts, codegen regeneration, release process).
+- Docs: JSDoc annotations on all exported functions across `client/`, `codegen/`, `tools/`, `config`, `logger`, `server`.
+- Docs: expanded inline code-comment block at the Snipe-IT status-envelope check.
+
+## 0.1.3 — 2026-05-25
+
+- Test coverage: `callWrite` preview full-URL path, raw_request preview full-URL path, summary auto-pagination.
+- `schemaToZod`: recursively flatten nested `allOf` via `$ref`.
+- `snipeit_raw_request` preview now shows full URL (consistency with `callWrite`).
+
+## 0.1.2 — 2026-05-25
+
+- Extract shared `callJson`/`callWrite` helpers, remove duplication across 9 wrapper modules.
+- `runGuarded` preview now shows full URL instead of bare path.
+- `schemaToZod`: resolve `$ref` inside `allOf` parts before merging (was silent no-op).
+- Drop unnecessary intermediate cast in `codegen/generate.ts`.
+- Parallelize `snipeit://hardware/summary` per-label and per-category fan-out (was sequential).
+- Auto-paginate status-labels and categories in summary instead of hardcoded `limit: 200`.
+- `callList` preserves server-reported `total` when `all: true`.
+
+## 0.1.1 — 2026-05-25
+
+- feat(resources): `snipeit://hardware/summary` now includes `by_category` breakdown (spec §10).
+- fix(resources): `snipeit://hardware/summary` wrapped in outer try/catch — network errors return `{error}` JSON instead of crashing.
+- feat(tools): all 11 list tools now accept `all?: boolean` to auto-paginate up to 10,000 rows (spec §7); uses existing `autoPaginate` helper.
+- refactor(client): fix readonly mutation bug — 429 retry-after now constructs a new `SnipeitApiError` instead of casting and mutating the `readonly details` field.
+- test(client): new coverage for timeout/AbortError path (`statusCode: 0`).
+- test(logger): new coverage for `"api_token":"…"` redaction pattern.
+
+## 0.1.0 — 2026-05-25
+
+- Initial release.
+- Hand-wrappers for hardware (13), users (5), licenses (3), accessories (3), consumables (2), components (3), locations (2), status-labels (2), maintenances (2), bulk-checkout (1), identity (1).
+- Auto-generated tools for all paths in the Snipe-IT OpenAPI 3.1 spec (~145 tools).
+- `snipeit_raw_request` escape hatch.
+- Resources: `snipeit://me`, `snipeit://settings`, `snipeit://hardware/summary`.
+- Prompts: inventory-audit, user-onboarding, license-health.
+- MCPB bundle.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Guttmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# the-real-snipeit-mcp
+
+MCP server for the [Snipe-IT](https://snipeitapp.com) REST API. 100 % endpoint coverage (read + write), hand-written wrappers for common workflows, codegen from the official OpenAPI 3.1 spec, stdio transport.
+
+**Three tool layers:**
+- **39 hand-wrappers** (`snipeit_*`) — friendlier UX for common workflows
+- **~145 auto-generated tools** (`snipeit_gen_*`) — 100 % endpoint coverage
+- **`snipeit_raw_request`** — escape hatch for any method/path
+
+Plus **3 resources**, **3 prompts**, and an MCPB bundle for one-click Claude Desktop install.
+
+---
+
+## Quick start
+
+```bash
+npm install
+cp .env.example .env
+# edit .env: set SNIPEIT_API_TOKEN
+npm run build
+npm start
+```
+
+Verify the connection with the MCP Inspector:
+```bash
+npm run inspector
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `SNIPEIT_API_TOKEN` | (required) | Snipe-IT Personal API Token (JWT) |
+| `SNIPEIT_API_BASE` | `https://snipe-it.example.com/api/v1` | API base URL |
+| `SNIPEIT_CONFIRM_WRITES` | `false` | If true, destructive tools require `confirm: "YES"` |
+| `SNIPEIT_TIMEOUT_MS` | `30000` | Per-request timeout |
+| `SNIPEIT_LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
+
+## Claude Desktop config
+
+```json
+{
+  "mcpServers": {
+    "snipeit": {
+      "command": "node",
+      "args": [
+        "--env-file=/absolute/path/to/the-real-snipeit-mcp/.env",
+        "/absolute/path/to/the-real-snipeit-mcp/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+Or install via the MCPB bundle: `npm run build:mcpb` → install the `.mcpb` file in Claude Desktop.
+
+---
+
+## Tool reference
+
+### Hand-wrappers (39 tools)
+
+#### Identity (1)
+
+| Tool | Endpoint | Annotations |
+|---|---|---|
+| `snipeit_me` | `GET /users/me` | readOnly |
+
+#### Hardware / Assets (13)
+
+| Tool | Endpoint | Annotations |
+|---|---|---|
+| `snipeit_list_hardware` | `GET /hardware` (paginated, common filters) | readOnly |
+| `snipeit_search_hardware` | `GET /hardware?search={query}` (convenience) | readOnly |
+| `snipeit_get_hardware_by_id` | `GET /hardware/{id}` | readOnly |
+| `snipeit_get_hardware_by_tag` | `GET /hardware/bytag/{tag}` | readOnly |
+| `snipeit_get_hardware_by_serial` | `GET /hardware/byserial/{serial}` | readOnly |
+| `snipeit_create_hardware` | `POST /hardware` | writeOnce |
+| `snipeit_update_hardware` | `PATCH /hardware/{id}` | writeIdempotent |
+| `snipeit_delete_hardware` | `DELETE /hardware/{id}` | writeIdempotent |
+| `snipeit_checkout_hardware` | `POST /hardware/{id}/checkout` (user/location/asset) | writeOnce |
+| `snipeit_checkin_hardware` | `POST /hardware/{id}/checkin` | writeOnce |
+| `snipeit_audit_hardware` | `POST /hardware/audit` | writeOnce |
+| `snipeit_list_audit_due` | `GET /hardware/audit/due` | readOnly |
+| `snipeit_list_audit_overdue` | `GET /hardware/audit/overdue` | readOnly |
+
+#### Users (5)
+
+| Tool | Endpoint | Annotations |
+|---|---|---|
+| `snipeit_list_users` | `GET /users` | readOnly |
+| `snipeit_get_user` | `GET /users/{id}` | readOnly |
+| `snipeit_get_user_assets` | `GET /users/{id}/assets` | readOnly |
+| `snipeit_get_user_accessories` | `GET /users/{id}/accessories` | readOnly |
+| `snipeit_get_user_licenses` | `GET /users/{id}/licenses` | readOnly |
+
+#### Licenses (3)
+
+| Tool | Endpoint | Annotations |
+|---|---|---|
+| `snipeit_list_licenses` | `GET /licenses` | readOnly |
+| `snipeit_get_license_seats` | `GET /licenses/{id}/seats` | readOnly |
+| `snipeit_checkout_license_seat` | `PUT /licenses/{license_id}/seats/{seat_id}` | writeIdempotent |
+
+#### Accessories / Consumables / Components (8)
+
+| Tool | Endpoint | Annotations |
+|---|---|---|
+| `snipeit_list_accessories` | `GET /accessories` | readOnly |
+| `snipeit_checkout_accessory` | `POST /accessories/{id}/checkout` | writeOnce |
+| `snipeit_checkin_accessory` | `POST /accessories/{id}/checkin` (pivot-id) | writeOnce |
+| `snipeit_list_consumables` | `GET /consumables` | readOnly |
+| `snipeit_checkout_consumable` | `POST /consumables/{id}/checkout` | writeOnce |
+| `snipeit_list_components` | `GET /components` | readOnly |
+| `snipeit_checkout_component` | `POST /components/{id}/checkout` (to asset) | writeOnce |
+| `snipeit_checkin_component` | `POST /components/{id}/checkin` (pivot-id) | writeOnce |
+
+#### Locations / Status-Labels / Maintenances (6)
+
+| Tool | Endpoint | Annotations |
+|---|---|---|
+| `snipeit_list_locations` | `GET /locations` | readOnly |
+| `snipeit_get_location` | `GET /locations/{id}` | readOnly |
+| `snipeit_list_statuslabels` | `GET /statuslabels` | readOnly |
+| `snipeit_get_statuslabel_assets` | `GET /statuslabels/{id}/assetlist` | readOnly |
+| `snipeit_list_maintenances` | `GET /maintenances` | readOnly |
+| `snipeit_create_maintenance` | `POST /maintenances` | writeOnce |
+
+#### Bulk & Escape (2)
+
+| Tool | Behavior | Annotations |
+|---|---|---|
+| `snipeit_bulk_checkout` | Serially checks out N assets, returns per-item success/error summary | writeOnce |
+| `snipeit_raw_request` | Any method/path against `SNIPEIT_API_BASE` — escape hatch | writeOnce (writeIdempotent for GET) |
+
+**List tools** (`snipeit_list_*`) accept `limit?`, `offset?`, and `all?: boolean`. With `all: true`, the tool auto-paginates up to 10 000 rows.
+
+### Auto-generated tools (`snipeit_gen_*`)
+
+All 77 paths × every method in the Snipe-IT OpenAPI 3.1 spec are exposed as `snipeit_gen_<snake_operation_id>` — roughly 145 tools. Use these when the hand-wrapper layer doesn't cover what you need. Read tools have `readOnlyHint: true`; writes have `destructiveHint: true`. Regenerate with `npm run codegen` after `npm run refresh-spec`.
+
+### `snipeit_raw_request`
+
+Escape hatch for anything else:
+```ts
+{ method: "PATCH", path: "/locations/4", body: { name: "HQ" } }
+```
+GET requests bypass the destructive-write guard; other methods honor `SNIPEIT_CONFIRM_WRITES`.
+
+---
+
+## Resources
+
+| URI | Description |
+|---|---|
+| `snipeit://me` | Current authenticated user (`GET /users/me`) |
+| `snipeit://settings` | Server settings (`GET /settings`) |
+| `snipeit://hardware/summary` | `{total, by_status_label, by_category}` — aggregated counts |
+
+## Prompts
+
+| Prompt | Args | Purpose |
+|---|---|---|
+| `snipeit-inventory-audit` | – | Lists overdue/due audits + unassigned assets, then summarizes |
+| `snipeit-user-onboarding` | `user_id`, optional `kit` | Suggests a checkout sequence for a new user |
+| `snipeit-license-health` | – | Seat usage + licenses expiring within 90 days |
+
+---
+
+## Workflows / Recipes
+
+### Onboard a new user with a laptop
+
+1. Confirm the user: `snipeit_get_user(id: 42)`
+2. Find an available laptop: `snipeit_list_hardware(category_id: 3, status_id: 5)` (ready-to-deploy)
+3. Checkout: `snipeit_checkout_hardware(id: 100, checkout_to_type: "user", assigned_user: 42, note: "Onboarding 2026-05-25")`
+
+### Bulk-checkout a kit to one user
+
+```json
+{
+  "items": [
+    { "asset_id": 100, "checkout_to_type": "user", "assigned_user": 42 },
+    { "asset_id": 101, "checkout_to_type": "user", "assigned_user": 42 },
+    { "asset_id": 102, "checkout_to_type": "user", "assigned_user": 42 }
+  ]
+}
+```
+Continues on per-item errors. Returns `{summary: {total, ok, errors}, results: [...]}`.
+
+### Audit overdue cleanup
+
+1. `snipeit_list_audit_overdue(all: true)` — full list, auto-paginated
+2. For each: `snipeit_audit_hardware(asset_tag: "...", location_id: 1, next_audit_date: "2027-05-25")`
+
+### Find an asset by tag or serial
+
+- By asset tag: `snipeit_get_hardware_by_tag(tag: "A-42")` (handles URL encoding)
+- By serial: `snipeit_get_hardware_by_serial(serial: "SN12345")`
+
+### Discover what an LLM can do
+
+Browse the MCP Inspector:
+```bash
+npm run build && npm run inspector
+```
+
+---
+
+## Write safety
+
+By default, destructive tools execute directly. Set `SNIPEIT_CONFIRM_WRITES=true` and any write tool returns a **redacted preview** instead — re-invoke with `confirm: "YES"` to actually execute. Preview includes the full URL (`apiBase + path`) and a redacted body (password/secret/token/api_key fields replaced with `(redacted)`).
+
+## Snipe-IT API quirk
+
+Snipe-IT often returns **HTTP 200** with `{"status":"error","messages":…}` for validation errors. This server detects that envelope and surfaces the messages as a tool error (with `isError: true`), so callers never accidentally treat a Snipe-IT error as success. Successful envelopes (`{"status":"success","payload":…}`) are unwrapped automatically so tool data is the inner `payload`, not the outer wrapper.
+
+---
+
+## Develop
+
+```bash
+npm run dev               # tsx watch
+npm test                  # unit + integration if env present
+npm run test:unit         # unit only (CI-safe)
+npm run test:integration  # live; requires SNIPEIT_API_TOKEN in .env
+npm run lint
+npm run typecheck
+npm run codegen           # regenerate src/tools/generated from vendor/snipe-it-rest-api.json
+npm run refresh-spec      # pull latest OpenAPI spec from snipe-it.readme.io
+npm run inspector         # MCP Inspector
+npm run build:mcpb        # build .mcpb installable bundle
+```
+
+See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the layer diagram and data flow. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for adding hand-wrappers, regenerating the codegen layer, and debugging.
+
+## Security
+
+- API token is read from `SNIPEIT_API_TOKEN` env only. Never hard-coded. `.env` is git-ignored.
+- The logger redacts known secret patterns (Bearer tokens, JWTs, `api_token` fields, `Authorization` header) before any output.
+- All MCP stdio output goes to `stderr` only — `stdout` is reserved for the protocol.
+- **If your token has ever been pasted into a chat or commit, rotate it.**
+
+## License
+
+MIT.

package/dist/client/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Error types and message formatting for Snipe-IT API failures.
+ *
+ * `SnipeitApiError` is thrown by `SnipeitClient` for any failure mode —
+ * non-2xx HTTP, the `{"status":"error"}` envelope on HTTP 200, timeouts (statusCode 0),
+ * and unrecoverable network errors. `formatMessages` converts Snipe-IT's
+ * variable-shape `messages` field into a single readable string.
+ *
+ * @module
+ */
+export interface SnipeitErrorPayload {
+    statusCode: number;
+    message: string;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * Custom error thrown by `SnipeitClient` for all API failures.
+ * Use `instanceof SnipeitApiError` to distinguish from generic Errors.
+ *
+ * - `statusCode === 0` means timeout or unrecoverable network error.
+ * - `statusCode === 200` with this error means a Snipe-IT envelope-level error.
+ * - `details` preserves the original `messages` field for programmatic inspection.
+ */
+export declare class SnipeitApiError extends Error {
+    readonly statusCode: number;
+    readonly code: string | undefined;
+    readonly details: unknown;
+    constructor(p: SnipeitErrorPayload);
+}
+/**
+ * Format Snipe-IT's `messages` field (which can be a string, field→string map,
+ * field→string-array map, or arbitrary JSON) into a single readable line.
+ *
+ * @example
+ * formatMessages("Asset created.") // → "Asset created."
+ * formatMessages({ name: ["required"], asset_tag: ["unique"] })
+ *   // → "asset_tag: unique; name: required"
+ * formatMessages({ name: "required" }) // → "name: required"
+ */
+export declare function formatMessages(messages: unknown): string;
+/**
+ * Build a `SnipeitApiError` from an HTTP error response body.
+ *
+ * Tries to JSON-parse the body and extract `messages` or `message`; falls back to
+ * `HTTP <status>: <body-snippet>` if neither yields a usable message.
+ */
+export declare function parseApiError(body: string, status: number): SnipeitApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/client/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,CAAC,EAAE,mBAAmB;CAOnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAmBxD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAkB3E"}

package/dist/client/errors.js

@@ -0,0 +1,83 @@
+/**
+ * Custom error thrown by `SnipeitClient` for all API failures.
+ * Use `instanceof SnipeitApiError` to distinguish from generic Errors.
+ *
+ * - `statusCode === 0` means timeout or unrecoverable network error.
+ * - `statusCode === 200` with this error means a Snipe-IT envelope-level error.
+ * - `details` preserves the original `messages` field for programmatic inspection.
+ */
+export class SnipeitApiError extends Error {
+    statusCode;
+    code;
+    details;
+    constructor(p) {
+        super(`[${p.statusCode}] ${p.message}`);
+        this.name = "SnipeitApiError";
+        this.statusCode = p.statusCode;
+        this.code = p.code;
+        this.details = p.details;
+    }
+}
+/**
+ * Format Snipe-IT's `messages` field (which can be a string, field→string map,
+ * field→string-array map, or arbitrary JSON) into a single readable line.
+ *
+ * @example
+ * formatMessages("Asset created.") // → "Asset created."
+ * formatMessages({ name: ["required"], asset_tag: ["unique"] })
+ *   // → "asset_tag: unique; name: required"
+ * formatMessages({ name: "required" }) // → "name: required"
+ */
+export function formatMessages(messages) {
+    if (messages === null || messages === undefined)
+        return "";
+    if (typeof messages === "string")
+        return messages;
+    if (typeof messages === "object" && !Array.isArray(messages)) {
+        const obj = messages;
+        const parts = [];
+        for (const key of Object.keys(obj).sort()) {
+            const val = obj[key];
+            if (Array.isArray(val))
+                parts.push(`${key}: ${val.join(", ")}`);
+            else if (typeof val === "string")
+                parts.push(`${key}: ${val}`);
+            else
+                parts.push(`${key}: ${JSON.stringify(val)}`);
+        }
+        return parts.join("; ");
+    }
+    try {
+        return JSON.stringify(messages).slice(0, 500);
+    }
+    catch {
+        return String(messages).slice(0, 500);
+    }
+}
+/**
+ * Build a `SnipeitApiError` from an HTTP error response body.
+ *
+ * Tries to JSON-parse the body and extract `messages` or `message`; falls back to
+ * `HTTP <status>: <body-snippet>` if neither yields a usable message.
+ */
+export function parseApiError(body, status) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            const msg = parsed.messages !== undefined
+                ? formatMessages(parsed.messages)
+                : (typeof parsed.message === "string" ? parsed.message : "");
+            if (msg) {
+                return new SnipeitApiError({ statusCode: status, message: msg, details: parsed.messages });
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return new SnipeitApiError({
+        statusCode: status,
+        message: `HTTP ${status}${body ? `: ${body.slice(0, 200)}` : ""}`,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/client/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"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"}

package/dist/client/pagination.d.ts

@@ -0,0 +1,42 @@
+export interface PaginationHint {
+    total: number;
+    returned: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextOffset: number;
+}
+/**
+ * Detect a Snipe-IT list envelope (`{total, rows}`) and compute a pagination hint
+ * describing how to fetch the next page. Returns `null` if the body isn't a list envelope.
+ *
+ * @param body - The (already-unwrapped) response payload.
+ * @param req - The `{limit, offset}` actually used for this request.
+ */
+export declare function parsePaginationHint(body: unknown, req: {
+    limit: number;
+    offset: number;
+}): PaginationHint | null;
+export interface AutoPaginateOptions {
+    startOffset?: number;
+    pageLimit?: number;
+    maxRows?: number;
+}
+/**
+ * Walk all pages of a list endpoint, calling `fetcher` repeatedly with increasing
+ * `offset` until either the server reports no more rows or `maxRows` is reached.
+ *
+ * @param fetcher - Async function that fetches a single page given `{limit, offset}`.
+ * @param opts.startOffset - Offset to start from (default 0).
+ * @param opts.pageLimit - Rows per page (default 200, capped at 500 by Snipe-IT).
+ * @param opts.maxRows - Hard cap on total rows (default 10 000) to prevent runaway loops.
+ * @returns The merged row array.
+ */
+export declare function autoPaginate<T>(fetcher: (opts: {
+    limit: number;
+    offset: number;
+}) => Promise<{
+    total: number;
+    rows: T[];
+}>, opts?: AutoPaginateOptions): Promise<T[]>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/client/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/client/pagination.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAaD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC,cAAc,GAAG,IAAI,CAYvB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,EAAE,CAAA;CAAE,CAAC,EAC3F,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,CAAC,EAAE,CAAC,CAcd"}

package/dist/client/pagination.js

@@ -0,0 +1,66 @@
+/**
+ * Pagination utilities for Snipe-IT list endpoints.
+ *
+ * Snipe-IT lists return `{total, rows}` with `limit`/`offset` query parameters.
+ * {@link parsePaginationHint} extracts a hint describing the current page; callers
+ * can chain pages manually using `nextOffset`. {@link autoPaginate} provides the
+ * walk-all-pages variant with a safety cap.
+ *
+ * @module
+ */
+import { PAGINATION } from "../constants.js";
+function isEnvelope(x) {
+    if (x === null || typeof x !== "object" || Array.isArray(x))
+        return false;
+    const r = x;
+    return typeof r.total === "number" && Array.isArray(r.rows);
+}
+/**
+ * Detect a Snipe-IT list envelope (`{total, rows}`) and compute a pagination hint
+ * describing how to fetch the next page. Returns `null` if the body isn't a list envelope.
+ *
+ * @param body - The (already-unwrapped) response payload.
+ * @param req - The `{limit, offset}` actually used for this request.
+ */
+export function parsePaginationHint(body, req) {
+    if (!isEnvelope(body))
+        return null;
+    const returned = body.rows.length;
+    const next = req.offset + returned;
+    return {
+        total: body.total,
+        returned,
+        offset: req.offset,
+        limit: req.limit,
+        hasMore: next < body.total,
+        nextOffset: next,
+    };
+}
+/**
+ * Walk all pages of a list endpoint, calling `fetcher` repeatedly with increasing
+ * `offset` until either the server reports no more rows or `maxRows` is reached.
+ *
+ * @param fetcher - Async function that fetches a single page given `{limit, offset}`.
+ * @param opts.startOffset - Offset to start from (default 0).
+ * @param opts.pageLimit - Rows per page (default 200, capped at 500 by Snipe-IT).
+ * @param opts.maxRows - Hard cap on total rows (default 10 000) to prevent runaway loops.
+ * @returns The merged row array.
+ */
+export async function autoPaginate(fetcher, opts = {}) {
+    const pageLimit = Math.min(opts.pageLimit ?? PAGINATION.AUTO_PAGINATE_PAGE_SIZE, PAGINATION.MAX_LIMIT);
+    const maxRows = opts.maxRows ?? PAGINATION.AUTO_PAGINATE_MAX_ROWS;
+    let offset = opts.startOffset ?? 0;
+    const out = [];
+    while (out.length < maxRows) {
+        const page = await fetcher({ limit: pageLimit, offset });
+        out.push(...page.rows);
+        const fetched = page.rows.length;
+        if (fetched === 0)
+            break;
+        offset += fetched;
+        if (offset >= page.total)
+            break;
+    }
+    return out.slice(0, maxRows);
+}
+//# sourceMappingURL=pagination.js.map

package/dist/client/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/client/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAgB7C,SAAS,UAAU,CAAC,CAAU;IAC5B,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1E,MAAM,CAAC,GAAG,CAA4B,CAAC;IACvC,OAAO,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAa,EACb,GAAsC;IAEtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAClC,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,GAAG,QAAQ,CAAC;IACnC,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ;QACR,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC,KAAK;QAC1B,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC;AAQD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAA2F,EAC3F,OAA4B,EAAE;IAE9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,UAAU,CAAC,uBAAuB,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IACvG,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,UAAU,CAAC,sBAAsB,CAAC;IAClE,IAAI,MAAM,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;IACnC,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,OAAO,GAAG,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QACzD,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QACjC,IAAI,OAAO,KAAK,CAAC;YAAE,MAAM;QACzB,MAAM,IAAI,OAAO,CAAC;QAClB,IAAI,MAAM,IAAI,IAAI,CAAC,KAAK;YAAE,MAAM;IAClC,CAAC;IACD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/client/retry.d.ts

@@ -0,0 +1,34 @@
+export interface RetryOptions {
+    maxAttempts: number;
+    sleep?: (ms: number) => Promise<void>;
+    idempotent?: boolean;
+}
+/** Return the backoff (ms) for the given attempt index, capped at the last schedule entry. */
+export declare function computeBackoff(attempt: number): number;
+/**
+ * Parse a `Retry-After` HTTP header into milliseconds.
+ *
+ * Accepts both numeric seconds (`"5"`) and HTTP-date (`"Wed, 21 Oct 2026 07:28:00 GMT"`).
+ * Returns `null` for missing/garbage input. Capped at 60s to prevent unbounded waits.
+ */
+export declare function parseRetryAfter(header: string | undefined | null): number | null;
+/**
+ * Decide whether a given error is worth retrying.
+ *
+ * @param err - Caught error from a failed `fetch` call or `SnipeitClient.request`.
+ * @param opts.idempotent - If true, 5xx are retried; otherwise 5xx are not retried.
+ */
+export declare function isRetriable(err: unknown, opts?: {
+    idempotent?: boolean;
+}): boolean;
+/**
+ * Run `fn` with bounded retries. Re-throws the last error if `maxAttempts` is exhausted
+ * or the error is not retriable. Honors `Retry-After` for 429 errors.
+ *
+ * @param fn - The async operation to retry.
+ * @param opts.maxAttempts - Maximum number of attempts (including the first).
+ * @param opts.idempotent - When true, 5xx errors are retried; otherwise only 429 and network errors.
+ * @param opts.sleep - Override the default sleep implementation (used in tests to avoid real delays).
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/client/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/client/retry.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,8FAA8F;AAC9F,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAItD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAahF;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAUtF;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBvF"}