buildx-connect/README.md

Official JavaScript/TypeScript SDK for Buildx low-code platform

# Buildx Connect SDK

Official JavaScript/TypeScript SDK for the Buildx low-code platform. Easily integrate Buildx APIs into your Node.js or browser applications with a modular, Firebase-like API.

## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [API Overview](#api-overview)
  - [Authentication](#authentication)
  - [Projects](#projects)
  - [Collections](#collections)
  - [Storage](#storage)
  - [Flows](#flows)
  - [Templates](#templates)
- [TypeScript Support](#typescript-support)
- [Error Handling](#error-handling)
- [License](#license)

---

## Installation

```bash
yarn add buildx-connect
# or
npm install buildx-connect
```

## Quick Start

```typescript
import { Buildx } from 'buildx-connect';

const buildx = new Buildx({
  apiEndpoint: 'https://api.buildx.com',
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
});

// Authenticate
const user = await buildx.auth().login({ username: 'user', password: 'pass' });

// List projects
const projects = await buildx.projects().list();

// Query documents (uses project ID from config)
const docs = await buildx.collections().query('collectionId', { limit: 10 });
```

## Configuration

The SDK is initialized with a configuration object:

```typescript
const buildx = new Buildx({
  apiEndpoint: 'https://api.buildx.com',
  apiKey: 'your-api-key',
  projectId: 'your-project-id',        // Used as default for all operations
  organizationId?: 'your-org-id',      // Optional, for organization-level operations
});
```

You can update the configuration at runtime:

```typescript
buildx.updateConfig({ apiKey: 'new-api-key' });
```

## API Overview

The SDK is organized into modular services, similar to Firebase. All methods use the project ID from your config by default, but you can override it by passing a `projectId` parameter:

```typescript
buildx.auth()        // Authentication
buildx.projects()    // Project management
buildx.collections() // Data collections
buildx.storage()     // File storage
buildx.flows()       // Workflow automation
buildx.templates()   // Template rendering
```

### Authentication

```typescript
// Login (uses project ID from config)
await buildx.auth().login({ username, password });

// Signup (uses project ID from config)
await buildx.auth().signup({ username, password });

// Get current user (uses project ID from config)
await buildx.auth().getCurrentUser();

// Override project ID for specific operation
await buildx.auth().login({ username, password }, 'different-project-id');
```

#### Token Management

The SDK automatically stores authentication tokens when you login, signup, or verify OTP. You can also manually manage tokens:

```typescript
// Check if user is authenticated
const isAuth = buildx.auth().isAuthenticated();

// Get current access token
const token = buildx.auth().getAccessToken();

// Get current refresh token
const refreshToken = buildx.auth().getRefreshToken();

// Manually set tokens
buildx.auth().setAccessToken('your-access-token');
buildx.auth().setRefreshToken('your-refresh-token');

// Clear all stored tokens (logout)
buildx.auth().clearTokens();

// Refresh authentication token
await buildx.auth().refreshToken();
```

### Projects

```typescript
// List all projects
await buildx.projects().list();

// Get project by ID
await buildx.projects().get('project-id');

// Create a new project
await buildx.projects().create({ name: 'My Project' });
```

### Collections

```typescript
// List collections (uses project ID from config)
await buildx.collections().list();

// Query documents (uses project ID from config)
await buildx.collections().query('collectionId', { filter: { status: 'active' } });

// Create document (uses project ID from config)
await buildx.collections().createDocument('collectionId', { field: 'value' });

// Override project ID for specific operation
await buildx.collections().query('collectionId', { limit: 10 }, 'different-project-id');
```

### Storage

```typescript
// Upload a file (uses project ID from config)
await buildx.storage().upload(file, 'uploads/');

// List files (uses project ID from config)
await buildx.storage().list('uploads/');

// Delete a file (uses project ID from config)
await buildx.storage().deleteFile('uploads/file.txt');
```

### Flows

```typescript
// Get flow types
await buildx.flows().getTypes();

// Run a flow (uses project ID from config)
await buildx.flows().run('flow-id', { args: { foo: 'bar' } });
```

### Templates

```typescript
// Preview a template (uses project ID from config)
await buildx.templates().preview(template, data);

// Render a template (uses project ID from config)
await buildx.templates().render('template-id', data);

// Generate PDF (uses project ID from config)
await buildx.templates().generatePDF('template-id', data);
```

## TypeScript Support

This SDK is written in TypeScript and ships with full type definitions for all APIs and data models.

## Error Handling

All methods return either the expected result or an `ErrorResponse` object:

```typescript
interface ErrorResponse {
  error: string;
  message: string;
  statusCode: number;
  success: false;
}
```

Check for errors in your code:

```typescript
const result = await buildx.projects().get('project-id');
if ('error' in result) {
  // handle error
  console.error(result.message);
}
```