# @shumoku/plugin-sdk

Canonical: https://docs.shumoku.dev/ja/library/packages/plugin-sdk
Language: ja

libs/@shumoku/plugin-sdk/README.md

# @shumoku/plugin-sdk

Shared runtime helpers for data-source plugins.

日本語版はまだありません。英語の原文を表示しています。

Node-runtime SDK for [Shumoku](https://github.com/konoe-akitoshi/shumoku) data-source plugins. Provides an HTTP client (with auth strategies and self-signed-TLS support) and a pagination helper.

This is **layer 2** of the shared plugin toolkit: it needs Node (fetch dispatcher / TLS control), so it lives outside the browser-safe [`@shumoku/core`](https://docs.shumoku.dev/ja/library/packages/core). Pure, runtime-agnostic helpers (severity mapping, Alertmanager parsing, `flattenObject`, `stampObserved`, `validateAgainstSchema`) stay in core’s plugin kit.

## Install

```
npm install @shumoku/plugin-sdk
```

## Quick start

```
import { HttpClient, paginate } from '@shumoku/plugin-sdk'

const client = new HttpClient({
  baseUrl: 'https://netbox.example.com',
  auth: { type: 'token', token: process.env.NETBOX_TOKEN ?? '' }, // NetBox's scheme is `Token`
  insecure: false, // set true only for trusted self-signed upstreams
})

// Single request — returns a standard Response
const res = await client.request('/api/dcim/sites/', { query: { limit: 50 } })
const { results } = await res.json()

// Follow `next` links to the end
const devices = await paginate('/api/dcim/devices/?limit=100', async (path) => {
  const r = await client.request(path)
  const body = await r.json()
  return { items: body.results, next: body.next }
})
```

## API

*   **`HttpClient`** — `new HttpClient(options)` with `request(path, opts?) → Promise<Response>`. Options: `baseUrl`, `auth`, `timeoutMs` (default 10000), `insecure`, `defaultHeaders`, `debug`, `fetchImpl`. Request options: `method`, `query`, `headers`, `body` (non-string is JSON-encoded), `timeoutMs`, `signal`.
*   **`AuthStrategy`** — `{ type: 'none' }`, `{ type: 'bearer', token }`, `{ type: 'token', token, scheme? }`, `{ type: 'basic', username, password }`.
*   **`HttpError`** — thrown on non-2xx; carries `status`, `url`, `bodyText`.
*   **`paginate(firstPath, fetchPage, options?)`** — walks `next` cursors, accumulating `items`. `options.maxPages` defaults to 1000 (`onTruncated` fires if hit).

See [Plugin Authoring](https://docs.shumoku.dev/ja/developers/plugin-authoring) and the bundled plugins in [`libs/plugins`](https://github.com/konoe-akitoshi/shumoku/blob/73ebc72ba0bc0d1caf74e1ed34c89a6debcb0e6a/libs/plugins) for real usage.

## License

AGPL-3.0-only. For commercial licensing, contact [contact@shumoku.dev](mailto:contact@shumoku.dev).