npm package: @packagecat/packagecat-js
Description: Package Cat JavaScript SDK
Author: Jeremiah Muela
Latest version: 0.5.0

# Packagecat JS SDK

A lightweight JavaScript SDK for interacting with the **Packagecat** API.  
Packagecat helps developers manage developer keys, tokens, client APIs, and carrier bundles easily and securely.

## Installation

Install via npm:

```bash
npm install @packagecat/packagecat-js
```

Or using yarn:

```bash
yarn add @packagecat/packagecat-js
```

## Usage

First, initialize a Packagecat instance with your API URL and (optionally) access token and clientToken:

```javascript
import { Packagecat } from '@packagecat/packagecat-js';

const packagecat = new Packagecat({
  url: 'https://api.packagecat.com',
  token: 'your-access-token',
  clientToken: 'your-client-specific-token',
});
```

You can update tokens later dynamically:

```javascript
packagecat.setToken('new-token'); // Update auth token
packagecat.setToken('new-client-specific-token', true); // Update client specific auth token
```

## API Overview

Packagecat organizes functionality into two main areas: `developer` and `carrier`.

### Developer APIs

#### Users

| Method                                  | Description                           |
|:----------------------------------------|:--------------------------------------|
| `developer.createUser(user)`            | Create a developer user               |
| `developer.getUsers()`                  | Retrieve developer users              |

#### Keys & Tokens

| Method                                  | Description                           |
|:----------------------------------------|:--------------------------------------|
| `developer.createClientSecret(key)`     | Create client key secret              |
| `developer.createDeveloperKey(payload)` | Add developer keys                    |
| `developer.createToken(tokenProps)`     | Set or exchange for a developer token |
| `developer.deleteApiKey(keyId)`         | Delete a developer key by ID          |
| `developer.getKeys()`                   | Retrieve all developer keys           |
| `developer.updateApiKey(key, payload)`  | Update name or enabled                |

### Carrier APIs

| Method | Description                                                 |
|:-------|:------------------------------------------------------------|
| `carrier.createAccountBundle(bundle)` | Add a carrier account bundle                                |
| `carrier.deleteAccountBundle(id)` | Delete a carrier account bundle by ID                       |
| `carrier.getAccountBundles()` | Retrieve all carrier account bundles                        |
| `carrier.patchAccountBundle(id)` | Patch an account bundle by overwriting its carrier accounts |
| `carrier.updateAccountBundle(bundle)` | Update an existing carrier account bundle                   |

#### Rates

| Example | Description |
|:--------|:------------|
| `carrier.getRates(rateRequests, { carrier: 'ups' })` | Retrieve abbreviated rates from a specific carrier |
| `carrier.getRates(rateRequests, { short: false })` | Retrieve full rate response object |
| `carrier.getRates(rateRequests)` | Retrieve abbreviated rates (default behavior) |

### Location APIs

| Method                                 | Description                                 |
|:---------------------------------------|:--------------------------------------------|
| `location.createLocation(payload)`     | Add a new location                          |
| `location.getLocations(params?)`       | Retrieve locations with optional pagination |
| `location.getLocationById(id)`         | Retrieve location by ID                     |
| `location.deleteLocationById(id)`      | Delete a specific location by ID            |
| `location.patchLocation(location, id)` | Patches a specific location by ID           |
| `location.updateLocation(location, id)` | Updates a specific location by ID           |

### Shipment APIs

| Method | Description |
|:-------|:------------|
| `shipment.create(payload)` | Create a shipment |
| `shipment.label(shipmentId)` | Generate a shipping label |
| `shipment.cancel(shipmentId)` | Cancel a shipment |
| `shipment.get(shipmentId)` | Retrieve a shipment by ID |

### Event APIs

| Method | Description |
|:-------|:------------|
| `event.get(options?)` | Fetch developer events with optional filters |

## Notes

- `token` is used for administrative API access.
- `clientToken` is used for client-specific API access via `/api/{apiVersion}`.
- You can choose to operate on either depending on your access model.

## License

MIT