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

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

Basic Usage

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: '[email protected]',
  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

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 - Comprehensive guide specifically for AI code assistants
• Complete API Reference - Full API documentation with examples
• Testing Guide - How to test the SDK functionality

Migration & Updates

• Migration Guide - 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:

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:

// 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:

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:

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