npm package: @25madisonhealth/careslate-scheduler
Description: The official TypeScript SDK for interacting with the CareSlate Scheduler API. Provides convenient methods for accessing all API endpoints with TypeScript typings.
Author: David Cabal & Ryan Frost
Latest version: 0.1.3

# CareSlate Scheduler SDK

The official TypeScript SDK for interacting with the CareSlate Scheduler API.

This SDK provides convenient methods for accessing all API endpoints, along with TypeScript typings for requests and responses, and utility functions for common tasks.

## Installation

You can install the SDK using npm, pnpm, or yarn:

**npm:**

```bash
npm install @25madisonhealth/careslate-scheduler
```

**pnpm:**

```bash
pnpm add @25madisonhealth/careslate-scheduler
```

**yarn:**

```bash
yarn add @25madisonhealth/careslate-scheduler
```

## Getting Started

### Initialization

First, import and instantiate the `CareSlateApiClient`, providing your API key. You can also optionally provide a custom `baseUrl` if you need to target a non-production environment (e.g., for local development or a staging server).

```typescript
import { CareSlateApiClient } from '@25madisonhealth/careslate-scheduler';

const client = new CareSlateApiClient({
  apiKey: 'YOUR_API_KEY_HERE', // Replace with your actual API key
  // baseUrl: 'http://localhost:3001' // Optional: For local development
});
```

The client will automatically determine the correct base URL based on the `process.env.ENVIRONMENT` variable if `baseUrl` is not explicitly provided:

- `local`: `http://localhost:3001`
- `dev`: `https://dev-303703761.us-central1.run.app`
- `prod` (or any other value/undefined): `https://prod-303703761.us-central1.run.app`

### Making API Calls

The SDK methods are organized by resource. For example, to get account details:

```typescript
import { CareSlateApiClient, Account, CareSlateApiError } from '@25madisonhealth/careslate-scheduler';

const client = new CareSlateApiClient({ apiKey: 'YOUR_API_KEY_HERE' });

async function main() {
  try {
    const myAccount: Account = await client.account.getAccount();
    console.log('My Account:', myAccount);

    // Example: Adding a user
    const newUser = await client.user.addUser({ name: 'Jane Doe' });
    console.log('New User:', newUser);
  } catch (error) {
    if (error instanceof CareSlateApiError) {
      console.error('API Error:', error.message, 'Status:', error.status, 'Data:', error.data);
    } else {
      console.error('Generic Error:', error);
    }
  }
}

main();
```

### Using Utilities

The SDK also exports utility functions. For example, `convertToLocalTime`:

```typescript
import { convertToLocalTime } from '@25madisonhealth/careslate-scheduler';

// Assuming you have an array of availability data from an API call
// This data structure should match what convertToLocalTime expects
const availabilityDataFromApi = [
  // ... your data from an endpoint like client.availability.getAllAvailability() ...
  // Example:
  // {
  //   userId: 'user123',
  //   availability: [
  //     {
  //       start: '2024-07-15T09:00:00.000Z', // UTC time from server
  //       end: '2024-07-15T17:00:00.000Z',   // UTC time from server
  //       timeZone: 'America/New_York',   // Original timezone
  //       offset: -240                    // Original offset in minutes for that specific time
  //     }
  //   ]
  // }
];

const localAvailability = convertToLocalTime(availabilityDataFromApi);
console.log('Availability in local time:', localAvailability);
```

**Note**: The `convertToLocalTime` function expects the input items to have `timeZone` and an `offset` (or `originalItemOffset`) property to correctly perform the "sticky" time conversion. Ensure your API responses used with this utility provide these fields.

## API Documentation

For detailed information on all available SDK methods, parameters, and types, please refer to our [TypeDoc API Documentation](https://25mh.github.io/careslate/).

## License

This SDK is MIT licensed.