@lineai/bluebeam-api/README.md

Your unofficial library for Bluebeam API for human and AI developers. Provides TypeScript support, entity classes, and developer-friendly features. Perfect for AI coders, construction professionals, and document management tasks. Includes comprehensive JS

# bluebeam-api

Your unofficial library for bluebeam optimized and documented for human and AI developer use

## Features

- **TypeScript Support**: Full type definitions for all API responses and requests
- **OAuth 2.0 Authentication**: Complete implementation of Authorization Code and Implicit flows
- **Sessions Management**: Full coverage of Bluebeam Studio Sessions API
- **Markups Support**: V2 API support for markup operations and status management
- **Functional Programming**: Immutable data structures and functional patterns
- **Developer-Friendly**: Comprehensive JSDoc, helper constants, and real-world examples

## Quick Start

### Installation

```bash
npm install @lineai/bluebeam-api
# or
yarn add @lineai/bluebeam-api
```

### Basic Usage

```typescript
import { createBluebeamClient } from '@lineai/bluebeam-api';

// Method 1: Load from environment variables (recommended)
const client = await createBluebeamClient();

// Method 2: Pass configuration directly
const client = await createBluebeamClient({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'full_prime offline_access',
  access_token: 'your-access-token'
});

// Get all sessions with pagination
const sessions = await client.sessions.getAllSessions({ limit: 10 });

// Create a new session
const newSession = await client.sessions.createSession({
  Name: 'My Session',
  Notification: true,
  OwnerEmailOrId: 'user@example.com',
  Restricted: false,
  SessionEndDate: '2024-12-31T23:59:59Z',
  Status: 'Active'
});

// Get session files and markups
const files = await client.sessions.getSessionFiles(newSession.Id);
if (files.Files.length > 0) {
  const markups = await client.markups.getMarkups(newSession.Id, files.Files[0].Id);
}
```

### Authentication

```typescript
import { createOAuthClient, createHttpClient } from '@lineai/bluebeam-api';

const httpClient = createHttpClient({ client_id: 'your-client-id' });
const auth = createOAuthClient({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'full_prime offline_access'
}, httpClient);

// Create authorization URL
const authUrl = auth.createAuthorizationUrl('random-state-string');

// Exchange code for token
const tokens = await auth.exchangeCodeForToken('authorization-code');

// Refresh token
const newTokens = await auth.refreshAccessToken();
```

## API Coverage

### Sessions API (V1)
- ✅ Get all sessions
- ✅ Create session
- ✅ Get session by ID
- ✅ Update session
- ✅ Delete session
- ✅ Session activities (get, create, get by ID)
- ✅ File management (get, create, delete, confirm upload, snapshots)
- ✅ User management (invite, add users)

### Markups API (V2)
- ✅ Get markups for session file
- ✅ Get valid statuses for markups
- ✅ Update markup status

### Authentication
- ✅ OAuth 2.0 Authorization Code flow
- ✅ OAuth 2.0 Implicit flow
- ✅ Token refresh
- ✅ Token management

## Documentation

### For AI Developers
- **[AI Developer Guide](./AI-GUIDE.md)** - Comprehensive guide specifically for AI code assistants
- **[Complete API Reference](./API.md)** - Full API documentation with examples
- **[Testing Guide](./TESTING.md)** - How to test the SDK functionality

### Migration & Updates
- **[Migration Guide](./MIGRATION.md)** - Upgrade instructions for breaking changes and new features

### Key Features for AI Agents
- **No Reimplementation Needed**: All Bluebeam API functionality is already implemented
- **Environment Variable Support**: Easy deployment with `BLUEBEAM_*` environment variables
- **Automatic Token Management**: OAuth tokens are handled automatically
- **Complete Type Safety**: All API responses are fully typed
- **Error Handling**: Structured error responses with proper status codes

## TypeScript Support

Full TypeScript definitions are included:

```typescript
import type { 
  SessionDto, 
  CreateSessionRequest, 
  MarkupDto,
  TokenResponse 
} from '@lineai/bluebeam-api';
```

## Common Issues

### 415 "Media Type Not Supported" Error
This was fixed in v0.0.2. The SDK now properly sends OAuth requests with `application/x-www-form-urlencoded` content type.

### Token Management
The SDK automatically handles token refresh when requests fail with 401:

```typescript
// Automatic token refresh is enabled by default
const client = await createBluebeamClient({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  tokenStorage: myTokenStorage, // Optional: provide custom token storage
});

// SDK automatically refreshes and retries on 401
const sessions = await client.sessions.getAllSessions();
```

To disable automatic refresh for custom handling:

```typescript
const client = await createBluebeamClient({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  autoRefresh: false, // Disable automatic refresh
});
```

### Environment Variables Not Loading
Make sure your environment variables are set correctly:

```bash
# Check if variables are set
echo $BLUEBEAM_CLIENT_ID
echo $BLUEBEAM_CLIENT_SECRET
echo $BLUEBEAM_ACCESS_TOKEN
```