> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nexspace365.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Install and use the NexSpace TypeScript SDK

# TypeScript SDK

## Installation

```bash theme={null}
npm install @nexspace/sdk
```

## Quick Start

```typescript theme={null}
import { NexSpace } from '@nexspace/sdk';

const client = new NexSpace({
  apiKey: process.env.NEXSPACE_API_KEY!,
});

// List facilities
const facilities = await client.facilities.list();

// Search staff
const staff = await client.staff.search({
  query: 'Jane',
  specialty: 'RN',
  facilityId: 12,
});

// Get shift details
const shift = await client.shifts.get(456);
```

## Configuration

```typescript theme={null}
const client = new NexSpace({
  apiKey: 'nex_live_...',
  baseUrl: 'https://api.nexspace365.com',  // default
  version: '2026-05-10',                // pin API version
  maxRetries: 3,                        // default
  timeout: 30_000,                      // 30s default
});
```

## Resources

### Facilities

```typescript theme={null}
const facilities = await client.facilities.list();
const facility = await client.facilities.get(12);
```

### Staff

```typescript theme={null}
const results = await client.staff.search({ query: 'Smith', limit: 10 });
const member = await client.staff.get(789);
```

### Shifts

```typescript theme={null}
const shifts = await client.shifts.list({ facilityId: 12, status: 'open' });
const assigned = await client.shifts.assign(456, { staffIds: [789] });
```

### API Keys

```typescript theme={null}
const keys = await client.apiKeys.list();
const newKey = await client.apiKeys.create({
  name: 'CI Pipeline',
  scopes: ['shifts:read', 'staff:read'],
});
```

### Credentials

```typescript theme={null}
const expiring = await client.credentials.listExpiring({ daysAhead: 30 });
```

## Error Handling

```typescript theme={null}
import { NexSpaceError } from '@nexspace/sdk';

try {
  await client.shifts.assign(456, { staffIds: [789] });
} catch (err) {
  if (err instanceof NexSpaceError) {
    console.error(err.code);       // 'FORBIDDEN'
    console.error(err.suggestion); // 'Rotate your API key to include...'
    console.error(err.retryable);  // false
  }
}
```

## Idempotency

Mutation methods automatically generate idempotency keys. Override with:

```typescript theme={null}
await client.shifts.assign(456, { staffIds: [789] }, {
  idempotencyKey: 'my-custom-key-123',
});
```