@lineai/bluebeam-api/AI-GUIDE.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 SDK - AI Developer Guide

This guide is specifically written for AI code assistants and developers to understand the complete functionality available in the `@lineai/bluebeam-api` SDK.

## 🚨 IMPORTANT: Don't Reimplement - Use the SDK!

This SDK already implements ALL the functionality you need. Before writing custom code, check this guide to see if it's already available.

## Quick Start for AI Agents

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

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

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

## Environment Variables (Recommended Approach)

Set these environment variables instead of hardcoding credentials:

```bash
BLUEBEAM_CLIENT_ID=your-client-id
BLUEBEAM_CLIENT_SECRET=your-client-secret
BLUEBEAM_ACCESS_TOKEN=your-access-token
BLUEBEAM_REDIRECT_URI=http://localhost:3000/callback
BLUEBEAM_SCOPE=full_prime offline_access
```

## Complete API Reference

### 🔐 Authentication (OAuth 2.0)

The SDK handles ALL OAuth complexity automatically:

```typescript
// Create OAuth client for authorization flow
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);

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

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

// Refresh expired tokens
const newTokens = await auth.refreshAccessToken();

// Check token status
const isExpired = auth.isTokenExpired();
const currentToken = auth.getAccessToken();

// Clear tokens
auth.clearTokens();
```

### 📁 Sessions Management (Complete Coverage)

```typescript
// Get all sessions with pagination
const sessions = await client.sessions.getAllSessions({
  limit: 50,
  offset: 0,
  orderby: 'Created', // 'Created', 'Name', 'Status'
  reverse: true
});

// Create 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 specific session
const session = await client.sessions.getSession('session-id');

// Update session
const updatedSession = await client.sessions.updateSession('session-id', {
  Name: 'Updated Session Name',
  Status: 'Completed'
});

// Delete session
await client.sessions.deleteSession('session-id');
```

### 📊 Session Activities

```typescript
// Get session activities
const activities = await client.sessions.getSessionActivities('session-id', {
  limit: 20,
  offset: 0,
  reverse: true
});

// Create session activity
const activity = await client.sessions.createSessionActivity('session-id', {
  Message: 'Session activity message',
  Type: 'Comment' // Activity type
});

// Get specific activity
const activity = await client.sessions.getSessionActivity('session-id', 'activity-id');
```

### 📄 File Management

```typescript
// Get session files
const files = await client.sessions.getSessionFiles('session-id', {
  limit: 50,
  offset: 0
});

// Create/upload file
const file = await client.sessions.createSessionFile('session-id', {
  Name: 'document.pdf',
  Size: 1024000,
  // Additional file properties
});

// Delete file
await client.sessions.deleteSessionFile('session-id', 'file-id');

// Confirm file upload
await client.sessions.confirmFileUpload('session-id', 'file-id');

// Get file snapshots
const snapshots = await client.sessions.getFileSnapshots('session-id', 'file-id');
```

### 👥 User Management

```typescript
// Invite user to session
await client.sessions.inviteUser('session-id', {
  Email: 'user@example.com',
  Role: 'Participant' // Role type
});

// Add user to session
await client.sessions.addUserToSession('session-id', {
  UserId: 'user-id',
  Role: 'Participant'
});
```

### 📝 Markups (V2 API)

```typescript
// Get markups for a file
const markups = await client.markups.getMarkups('session-id', 123);

// Get valid markup statuses
const statuses = await client.markups.getValidStatuses('session-id', 123);

// Update markup status
await client.markups.updateMarkupStatus('session-id', 123, 'markup-id', {
  Status: 'Approved',
  Comment: 'Looks good!'
});
```

### 🔄 Token Management (Automatic)

The SDK automatically handles token management:

```typescript
// Update access token (creates new client instance)
const newClient = client.updateAccessToken('new-access-token');

// Token refresh is handled automatically in OAuth client
// No need to manually manage token expiration
```

## Complete Type Definitions

All API responses are fully typed:

```typescript
import type {
  // Session types
  SessionDto,
  CreateSessionRequest,
  UpdateSessionRequest,
  GetSessionsRequest,
  GetSessionsResponse,
  
  // Activity types
  SessionActivityDto,
  CreateSessionActivityRequest,
  GetSessionActivitiesRequest,
  GetSessionActivitiesResponse,
  
  // File types
  SessionFileDto,
  CreateSessionFileRequest,
  GetSessionFilesRequest,
  GetSessionFilesResponse,
  
  // Markup types
  MarkupDto,
  MarkupStatusDto,
  UpdateMarkupStatusRequest,
  
  // Auth types
  TokenResponse,
  AuthCodeResponse,
  TokenRequest,
  OAuthConfig,
  
  // Error types
  ApiError
} from '@lineai/bluebeam-api';
```

## Error Handling Patterns

```typescript
try {
  const sessions = await client.sessions.getAllSessions();
} catch (error) {
  if (error && typeof error === 'object' && 'status' in error) {
    const apiError = error as ApiError;
    
    switch (apiError.status) {
      case 401:
        console.log('Token expired or invalid');
        // Refresh token or re-authenticate
        break;
      case 403:
        console.log('Insufficient permissions');
        break;
      case 404:
        console.log('Resource not found');
        break;
      default:
        console.log(`API Error: ${apiError.status} - ${apiError.error}`);
    }
  }
}
```

## Common Usage Patterns

### 1. Session Analysis
```typescript
// Get all sessions and analyze them
const sessions = await client.sessions.getAllSessions();
const activeSessions = sessions.Sessions.filter(s => s.Status === 'Active');
const completedSessions = sessions.Sessions.filter(s => s.Status === 'Completed');

console.log(`Active: ${activeSessions.length}, Completed: ${completedSessions.length}`);
```

### 2. File Processing
```typescript
// Process all files in a session
const files = await client.sessions.getSessionFiles('session-id');
for (const file of files.Files) {
  const markups = await client.markups.getMarkups('session-id', file.Id);
  console.log(`File ${file.Name} has ${markups.length} markups`);
}
```

### 3. Activity Monitoring
```typescript
// Monitor recent activities
const activities = await client.sessions.getSessionActivities('session-id', {
  limit: 10,
  reverse: true
});

const recentActivity = activities.SessionActivities[0];
if (recentActivity) {
  console.log(`Latest: ${recentActivity.Message} at ${recentActivity.Created}`);
}
```

## API Endpoints Reference

### Base URLs
- **V1 API**: `https://studioapi.bluebeam.com/PublicAPI/v1/`
- **V2 API**: `https://api.bluebeam.com/publicapi/v2/`
- **OAuth**: `https://api.bluebeam.com/`

### Authentication Headers
All requests include:
```
Authorization: Bearer {access_token}
Content-Type: application/json
```

OAuth token requests use:
```
Content-Type: application/x-www-form-urlencoded
```

## Deployment Configuration

### Production Setup
```typescript
// Set environment variables in production
process.env.BLUEBEAM_CLIENT_ID = 'prod-client-id';
process.env.BLUEBEAM_CLIENT_SECRET = 'prod-client-secret';
process.env.BLUEBEAM_ACCESS_TOKEN = 'user-access-token';

// Client automatically loads from environment
const client = await createBluebeamClient();
```

### Development Setup
```typescript
// Use .env file for development
const client = await createBluebeamClient({
  client_id: process.env.BLUEBEAM_CLIENT_ID,
  client_secret: process.env.BLUEBEAM_CLIENT_SECRET,
  access_token: process.env.BLUEBEAM_ACCESS_TOKEN,
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'full_prime offline_access'
});
```

## Testing

The SDK includes comprehensive tests. Run with:
```bash
yarn test:unit
```

Set test environment variables:
```bash
BLUEBEAM_CLIENT_ID=test-client-id
BLUEBEAM_CLIENT_SECRET=test-client-secret
BLUEBEAM_ACCESS_TOKEN=test-access-token
```

## Key Benefits for AI Agents

1. **No OAuth Complexity**: SDK handles all OAuth flows
2. **Automatic Token Management**: No need to manually track expiration
3. **Complete Type Safety**: All responses are typed
4. **Error Handling**: Structured error responses
5. **Environment Variables**: Easy deployment configuration
6. **Comprehensive Coverage**: All documented endpoints implemented
7. **Pagination Support**: Built-in pagination handling
8. **Real-world Examples**: Practical usage patterns included

## ⚠️ Don't Reimplement These Features

The SDK already provides:
- ✅ OAuth 2.0 authorization code flow
- ✅ OAuth 2.0 implicit flow  
- ✅ Token refresh and management
- ✅ All Sessions API endpoints
- ✅ All Markups API endpoints
- ✅ File upload and management
- ✅ User invitation and management
- ✅ Activity tracking
- ✅ Error handling and retry logic
- ✅ Type definitions for all responses
- ✅ Pagination support
- ✅ Environment variable configuration

Use the SDK instead of writing custom HTTP clients or authentication logic!