npm package: @scalepad/sdk-core
Description: Thin typed ScalePad Core API helper package used by the ScalePad CLI.
Latest version: 0.1.3

# @scalepad/sdk-core

Thin typed client for selected ScalePad Core API routes used by the ScalePad CLI.

`@scalepad/cli` is the primary supported developer interface right now. Use this package when you need a lightweight programmatic helper for a subset of Core API workflows.

## Install

```bash
npm install @scalepad/sdk-core
```

## Usage

```ts
import { createCoreClient } from "@scalepad/sdk-core";

const client = createCoreClient({
  apiKey: process.env.SCALEPAD_API_KEY!,
  validateResponses: true
});

const clients = await client.listClients({ pageSize: 10 });
console.log(clients.data);
```

## API

The package exports a generated client plus a small convenience wrapper.

Wrapper helpers:

- `createCoreClient(config)`
- `ScalepadCoreClient`
- `listClients(query)`
- `getClient(id)`
- `listIntegrationConfigurations()`
- `listHardwareAssets(query)`
- `listTickets(query)`
- `paginateClientPages(query)`
- `paginateClients(query)`
- `collectAllClients(query)`
- `paginateHardwareAssetPages(query)`
- `paginateHardwareAssets(query)`
- `collectAllHardwareAssets(query)`
- `paginateTicketPages(query)`
- `paginateTickets(query)`
- `collectAllTickets(query)`

Generated and schema exports:

- `GeneratedCoreClient`
- `coreOperations`
- `ScalepadApiError`
- `paths`

## Client configuration

```ts
type CoreClientConfig = {
  apiKey: string;
  baseUrl?: string;
  fetchImpl?: typeof fetch;
  userAgent?: string;
  timeoutMs?: number;
  maxRetries?: number;
  retry?: Partial<RetryConfig>;
  validateResponses?: boolean;
};
```

- `apiKey` is required and is sent as `x-api-key`
- `baseUrl` defaults to `https://api.scalepad.com`
- `fetchImpl` lets you inject a custom fetch implementation
- `userAgent` defaults to `@scalepad/cli`
- `timeoutMs` defaults to `30000`
- `maxRetries` is kept for backward compatibility and overrides `retry.maxRetries` when set
- `retry.retryOn429` and `retry.retryOn5xx` control safe-method retries
- `retry.retryUnsafeMethods` defaults to `false`
- `validateResponses` enables basic runtime envelope validation for wrapper methods

## List queries

List endpoints accept this shared shape:

```ts
type ListQuery = {
  cursor?: string;
  pageSize?: number;
  filters?: Record<string, string>;
  sort?: string;
};
```

Filters are translated to `filter[field]=expression` query parameters, and `pageSize` is translated to `page_size`.

## Pagination helpers

Wrapper list methods still support manual cursor pagination through `ListQuery`, and the package now also exports helper iterators:

```ts
for await (const clientRecord of client.paginateClients({ pageSize: 100 })) {
  console.log(clientRecord.id);
}

const allTickets = await client.collectAllTickets({ pageSize: 200 });
```

## Error handling

Failed requests throw richer typed errors:

- `ScalepadApiError` for general API failures
- `AuthenticationError`
- `AuthorizationError`
- `RateLimitError`
- `ServerError`
- `TimeoutError`
- `NetworkError`
- `ResponseValidationError`

## Development

This package is generated from the checked-in OpenAPI spec in the monorepo root. To refresh or rebuild it:

```bash
pnpm fetch:specs
pnpm generate:sdk
pnpm --filter @scalepad/sdk-core build
```