npm package: @lassare/sdk
Description: TypeScript/JavaScript SDK for the Lassare Gateway
Author: Lassare
Latest version: 0.3.0

# Lassare TypeScript/JavaScript SDK

A TypeScript/JavaScript client library for the Lassare Gateway.

**The SDK is designed to BLOCK agent execution until a human decision is made.**
This is the core purpose of Lassare - forcing agents to stop and wait for approval.

## Installation

```bash
npm install @lassare/sdk
```

## Quick Start

```typescript
import { LassareClient, RequestStatus } from '@lassare/sdk';

// Initialize client with API key
const client = new LassareClient({
  apiKey: 'lsk_prod_xxx...',
});

// Connect to WebSocket
await client.connect();

// This call BLOCKS until a human approves, rejects, or the request expires
const decision = await client.pauseForHuman({
  projectId: 'proj_abc123',
  policyId: 'pol_xyz789',
  payload: { amount: 50000, destination: 'new_account' },
  title: 'Approve large transaction',
  description: 'User requested withdrawal of $50,000 to new account',
});

// Code only reaches here AFTER human decision
if (decision.status === RequestStatus.APPROVED) {
  console.log(`Approved by ${decision.decidedBy}`);
  await executeTransaction();
} else if (decision.status === RequestStatus.REJECTED) {
  console.log(`Rejected: ${decision.comment}`);
  await cancelTransaction();
} else { // EXPIRED
  console.log('Request expired without decision');
  await handleTimeout();
}

await client.disconnect();
```

## Blocking Behavior

The `pauseForHuman()` method **blocks** via WebSocket until a decision is made. This ensures your agent cannot proceed without human approval.

### With Timeout

```typescript
import { DecisionTimeoutError } from '@lassare/sdk';

try {
  // Block for max 5 minutes (300000 ms)
  const decision = await client.pauseForHuman(request, 300000);
} catch (error) {
  if (error instanceof DecisionTimeoutError) {
    console.log('No decision in time');
  }
}
```

### Non-Blocking

For cases where you need to create a request and return immediately:

```typescript
// Creates request and returns immediately (does not wait for decision)
const response = await client.createApprovalRequest({
  projectId: 'proj_abc123',
  policyId: 'pol_xyz789',
  payload: { amount: 50000 },
  title: 'Approve transaction',
});
console.log(`Created request: ${response.requestId}`);
// Check status later with getRequestStatus() or use callbacks
```

## Policy-Based Routing

Use `policyId` to route approval requests through policies configured in the Lassare Portal:

```typescript
const decision = await client.pauseForHuman({
  projectId: 'proj_abc123',
  policyId: 'pol_default',  // Configured in Portal
  payload: { amount: 50000, customerId: 'cust_123' },
  title: 'High-value transaction',
});
```

Policies define:
- Which approvers receive notifications
- Notification channels (email, Slack, Microsoft Teams, webhooks)
- Urgency levels and escalation rules

## API Reference

### LassareClient

#### Constructor

```typescript
new LassareClient({
  apiKey: 'lsk_prod_xxx...',
  wsUrl: 'wss://ws.lassare.com',  // optional, defaults to production
})
```

#### Methods

- `pauseForHuman(request, timeoutMs?)` - **BLOCKS** until decision
- `createApprovalRequest(request, timeoutMs?)` - Creates request, returns immediately
- `getRequestStatus(requestId)` - Get current status of a request
- `cancelRequest(requestId)` - Cancel a pending request
- `connect()` / `disconnect()` - Connection management

### Types

- `PauseRequest` - Request with `projectId`, `policyId`, `payload`, `title`, etc.
- `DecisionResponse` - Response with `status`, `decidedBy`, `comment`, `requestId`
- `RequestStatus` - Enum: `PENDING`, `APPROVED`, `REJECTED`, `EXPIRED`
- `Urgency` - Enum: `CRITICAL`, `STANDARD`, `EXTENDED`

## Documentation

For full documentation, visit [https://docs.lassare.com/sdks/javascript](https://docs.lassare.com/sdks/javascript)

## License

MIT