@bundleup/sdk 0.0.18 → 0.2.0

package/README.md

@@ -3,21 +3,45 @@
 [![npm version](https://img.shields.io/npm/v/@bundleup/sdk.svg)](https://www.npmjs.com/package/@bundleup/sdk)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-Official JavaScript/TypeScript SDK for the [BundleUp](https://bundleup.io) API. Connect to 100+ integrations with a single, unified API.
+Official JavaScript/TypeScript SDK for the [BundleUp](https://bundleup.io) API. Connect to 100+ integrations with a single, unified API. Build once, integrate everywhere.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Core Concepts](#core-concepts)
+- [API Reference](#api-reference)
+  - [Connections](#connections)
+  - [Integrations](#integrations)
+  - [Webhooks](#webhooks)
+  - [Proxy API](#proxy-api)
+  - [Unify API](#unify-api)
+- [Error Handling](#error-handling)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
 
 ## Installation
 
+Install the SDK using your preferred package manager:
+
+**npm:**
+
 ```bash
 npm install @bundleup/sdk
 ```
 
-Or with yarn:
+**yarn:**
 
 ```bash
 yarn add @bundleup/sdk
 ```
 
-Or with pnpm:
+**pnpm:**
 
 ```bash
 pnpm add @bundleup/sdk
@@ -25,34 +49,76 @@ pnpm add @bundleup/sdk
 
 ## Requirements
 
-- Node.js 16 or higher
-- TypeScript 5.0+ (for TypeScript projects)
+- **Node.js**: 16.0.0 or higher
+- **TypeScript**: 5.0+ (for TypeScript projects)
+- **Fetch API**: Native fetch support (Node.js 18+) or polyfill for older versions
+
+### Node.js Compatibility
+
+For Node.js versions below 18, you'll need to install a fetch polyfill:
+
+```bash
+npm install node-fetch
+```
+
+Then import it before using the SDK:
+
+```javascript
+import fetch from 'node-fetch';
+globalThis.fetch = fetch;
+```
 
 ## Features
 
-- **TypeScript First** - Built with TypeScript, includes full type definitions
-- **Modern JavaScript** - ESM and CommonJS support for maximum compatibility
-- **Promise-based API** - Uses native fetch for all HTTP requests
-- **Comprehensive Coverage** - Full support for Connections, Integrations, Webhooks, Proxy, and Unify APIs
-- **Lightweight** - Zero dependencies beyond native fetch API
+- 🚀 **TypeScript First** - Built with TypeScript, includes comprehensive type definitions
+- 📦 **Modern JavaScript** - ESM and CommonJS support for maximum compatibility
+- ⚡ **Promise-based API** - Async/await support using native fetch
+- 🔌 **100+ Integrations** - Connect to Slack, GitHub, Jira, Linear, and many more
+- 🎯 **Unified API** - Consistent interface across all integrations via Unify API
+- 🔑 **Proxy API** - Direct access to underlying integration APIs
+- 🪶 **Lightweight** - Zero dependencies beyond native fetch API
+- 🛡️ **Error Handling** - Comprehensive error messages and validation
+- 📚 **Well Documented** - Extensive documentation and examples
 
 ## Quick Start
 
+Get started with BundleUp in just a few lines of code:
+
 ```javascript
 import { BundleUp } from '@bundleup/sdk';
 
-// Initialize the client with your API key
+// Initialize the client
 const client = new BundleUp(process.env.BUNDLEUP_API_KEY);
 
-// List all connections
+// List all active connections
 const connections = await client.connections.list();
-console.log(connections);
+console.log(`You have ${connections.length} active connections`);
+
+// Use the Proxy API to make requests to integrated services
+const proxy = client.proxy('conn_123');
+const response = await proxy.get('/api/users');
+const users = await response.json();
+console.log('Users:', users);
+
+// Use the Unify API for standardized data across integrations
+const unify = client.unify('conn_456');
+const channels = await unify.chat.channels({ limit: 10 });
+console.log('Chat channels:', channels.data);
 ```
 
 ## Authentication
 
 The BundleUp SDK uses API keys for authentication. You can obtain your API key from the [BundleUp Dashboard](https://app.bundleup.io).
 
+### Getting Your API Key
+
+1. Sign in to your [BundleUp Dashboard](https://app.bundleup.io)
+2. Navigate to **API Keys**
+3. Click **Create API Key**
+4. Copy your API key and store it securely
+
+### Initializing the SDK
+
 ```javascript
 import { BundleUp } from '@bundleup/sdk';
 
@@ -63,273 +129,957 @@ const client = new BundleUp('your_api_key_here');
 const client = new BundleUp(process.env.BUNDLEUP_API_KEY);
 ```
 
-**Security Best Practice:** Never commit your API keys to version control. Use environment variables or a secure credential management system.
+### Security Best Practices
+
+- ✅ **DO** store API keys in environment variables
+- ✅ **DO** use a secrets management service in production
+- ✅ **DO** rotate API keys regularly
+- ❌ **DON'T** commit API keys to version control
+- ❌ **DON'T** hardcode API keys in your source code
+- ❌ **DON'T** share API keys in public channels
+
+**Example `.env` file:**
+
+```bash
+BUNDLEUP_API_KEY=bu_live_1234567890abcdefghijklmnopqrstuvwxyz
+```
+
+**Loading environment variables:**
+
+```javascript
+import 'dotenv/config'; // For Node.js projects
+import { BundleUp } from '@bundleup/sdk';
+
+const client = new BundleUp(process.env.BUNDLEUP_API_KEY);
+```
+
+## Core Concepts
 
-## Usage
+### Platform API
+
+The **Platform API** provides access to core BundleUp features like managing connections and integrations. Use this API to list, retrieve, and delete connections, as well as discover available integrations.
+
+### Proxy API
+
+The **Proxy API** allows you to make direct HTTP requests to the underlying integration's API through BundleUp. This is useful when you need access to integration-specific features not covered by the Unify API.
+
+### Unify API
+
+The **Unify API** provides a standardized, normalized interface across different integrations. For example, you can fetch chat channels from Slack, Discord, or Microsoft Teams using the same API call.
+
+## API Reference
 
 ### Connections
 
-Manage your integration connections:
+Manage your integration connections.
+
+#### List Connections
+
+Retrieve a list of all connections in your account.
 
 ```javascript
-// List all connections
 const connections = await client.connections.list();
+```
 
-// List with query parameters
-const connections = await client.connections.list({ status: 'active', limit: '10' });
+**With query parameters:**
 
-// Retrieve a specific connection
-const connection = await client.connections.retrieve('conn_123');
+```javascript
+const connections = await client.connections.list({
+  integration_id: 'int_slack',
+  limit: 50,
+  offset: 0,
+  external_id: 'user_123',
+});
+```
+
+**Query Parameters:**
+
+- `integration_id` (string): Filter by integration ID
+- `integration_identifier` (string): Filter by integration identifier (e.g., 'slack', 'github')
+- `external_id` (string): Filter by external user/account ID
+- `limit` (number): Maximum number of results (default: 50, max: 100)
+- `offset` (number): Number of results to skip for pagination
 
-// Delete a connection
-await client.connections.del('conn_123');
+**Response:**
+
+```typescript
+[
+  {
+    id: 'conn_123abc',
+    externalId: 'user_456',
+    integrationId: 'int_slack',
+    isValid: true,
+    createdAt: '2024-01-15T10:30:00Z',
+    updatedAt: '2024-01-20T14:22:00Z',
+    refreshedAt: '2024-01-20T14:22:00Z',
+    expiresAt: '2024-04-20T14:22:00Z',
+  },
+  // ... more connections
+];
 ```
 
+#### Retrieve a Connection
+
+Get details of a specific connection by ID.
+
+```javascript
+const connection = await client.connections.retrieve('conn_123abc');
+```
+
+**Response:**
+
+```typescript
+{
+  id: 'conn_123abc',
+  externalId: 'user_456',
+  integrationId: 'int_slack',
+  isValid: true,
+  createdAt: '2024-01-15T10:30:00Z',
+  updatedAt: '2024-01-20T14:22:00Z',
+  refreshedAt: '2024-01-20T14:22:00Z',
+  expiresAt: '2024-04-20T14:22:00Z'
+}
+```
+
+#### Delete a Connection
+
+Remove a connection from your account.
+
+```javascript
+await client.connections.del('conn_123abc');
+```
+
+**Note:** Deleting a connection will revoke access to the integration and cannot be undone.
+
 ### Integrations
 
-Work with available integrations:
+Discover and work with available integrations.
+
+#### List Integrations
+
+Get a list of all available integrations.
 
 ```javascript
-// List all integrations
 const integrations = await client.integrations.list();
+```
+
+**With query parameters:**
+
+```javascript
+const integrations = await client.integrations.list({
+  status: 'active',
+  limit: 100,
+  offset: 0,
+});
+```
+
+**Query Parameters:**
+
+- `status` (string): Filter by status ('active', 'inactive', 'beta')
+- `limit` (number): Maximum number of results
+- `offset` (number): Number of results to skip for pagination
+
+**Response:**
+
+```typescript
+[
+  {
+    id: 'int_slack',
+    identifier: 'slack',
+    name: 'Slack',
+    category: 'chat',
+    createdAt: '2023-01-01T00:00:00Z',
+    updatedAt: '2024-01-15T10:00:00Z',
+  },
+  // ... more integrations
+];
+```
+
+#### Retrieve an Integration
 
-// Retrieve a specific integration
-const integration = await client.integrations.retrieve('int_123');
+Get details of a specific integration.
+
+```javascript
+const integration = await client.integrations.retrieve('int_slack');
+```
+
+**Response:**
+
+```typescript
+{
+  id: 'int_slack',
+  identifier: 'slack',
+  name: 'Slack',
+  category: 'chat',
+  createdAt: '2023-01-01T00:00:00Z',
+  updatedAt: '2024-01-15T10:00:00Z'
+}
 ```
 
 ### Webhooks
 
-Manage webhook subscriptions:
+Manage webhook subscriptions for real-time event notifications.
+
+#### List Webhooks
+
+Get all registered webhooks.
 
 ```javascript
-// List all webhooks
 const webhooks = await client.webhooks.list();
+```
+
+**With pagination:**
+
+```javascript
+const webhooks = await client.webhooks.list({
+  limit: 50,
+  offset: 0,
+});
+```
+
+**Response:**
+
+```typescript
+[
+  {
+    id: 'webhook_123',
+    name: 'My Webhook',
+    url: 'https://example.com/webhook',
+    events: {
+      'connection.created': true,
+      'connection.deleted': true,
+    },
+    createdAt: '2024-01-15T10:30:00Z',
+    updatedAt: '2024-01-20T14:22:00Z',
+    lastTriggeredAt: '2024-01-20T14:22:00Z',
+  },
+];
+```
+
+#### Create a Webhook
 
-// Create a webhook
+Register a new webhook endpoint.
+
+```javascript
 const webhook = await client.webhooks.create({
+  name: 'Connection Events Webhook',
   url: 'https://example.com/webhook',
   events: {
     'connection.created': true,
-    'connection.deleted': true
-  }
+    'connection.deleted': true,
+    'connection.updated': true,
+  },
 });
+```
+
+**Webhook Events:**
+
+- `connection.created` - Triggered when a new connection is established
+- `connection.deleted` - Triggered when a connection is removed
+- `connection.updated` - Triggered when a connection is modified
+
+**Request Body:**
+
+```typescript
+{
+  name: string;           // Friendly name for the webhook
+  url: string;            // Your webhook endpoint URL
+  events: {               // Events to subscribe to
+    [eventName: string]: boolean;
+  };
+}
+```
+
+**Response:**
+
+```typescript
+{
+  id: 'webhook_123',
+  name: 'Connection Events Webhook',
+  url: 'https://example.com/webhook',
+  events: {
+    'connection.created': true,
+    'connection.deleted': true,
+    'connection.updated': true
+  },
+  createdAt: '2024-01-15T10:30:00Z',
+  updatedAt: '2024-01-15T10:30:00Z'
+}
+```
+
+#### Retrieve a Webhook
+
+Get details of a specific webhook.
 
-// Retrieve a webhook
+```javascript
 const webhook = await client.webhooks.retrieve('webhook_123');
+```
+
+#### Update a Webhook
 
-// Update a webhook
+Modify an existing webhook.
+
+```javascript
 const updated = await client.webhooks.update('webhook_123', {
-  url: 'https://example.com/new-webhook'
+  name: 'Updated Webhook Name',
+  url: 'https://example.com/new-webhook',
+  events: {
+    'connection.created': true,
+    'connection.deleted': false,
+  },
 });
+```
+
+#### Delete a Webhook
 
-// Delete a webhook
+Remove a webhook subscription.
+
+```javascript
 await client.webhooks.del('webhook_123');
 ```
 
+#### Webhook Payload Example
+
+When an event occurs, BundleUp sends a POST request to your webhook URL with the following payload:
+
+```json
+{
+  "id": "evt_1234567890",
+  "type": "connection.created",
+  "created_at": "2024-01-15T10:30:00Z",
+  "data": {
+    "id": "conn_123abc",
+    "external_id": "user_456",
+    "integration_id": "int_slack",
+    "is_valid": true,
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+#### Webhook Security
+
+To verify webhook signatures:
+
+```javascript
+import crypto from 'crypto';
+
+function verifyWebhookSignature(payload, signature, secret) {
+  const hmac = crypto.createHmac('sha256', secret);
+  hmac.update(payload);
+  const digest = hmac.digest('hex');
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
+}
+
+// In your webhook handler
+app.post('/webhook', (req, res) => {
+  const signature = req.headers['x-bundleup-signature'];
+  const payload = JSON.stringify(req.body);
+
+  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  // Process the webhook
+  console.log('Webhook received:', req.body);
+  res.status(200).send('OK');
+});
+```
+
 ### Proxy API
 
-Make direct calls to the underlying integration APIs:
+Make direct HTTP requests to integration APIs through BundleUp.
+
+#### Creating a Proxy Instance
 
 ```javascript
-// Create a proxy instance
-const proxy = client.proxy('conn_123');
+const proxy = client.proxy('conn_123abc');
+```
+
+#### GET Request
 
-// Make GET request
-const users = await proxy.get('/api/users');
-const data = await users.json();
+```javascript
+const response = await proxy.get('/api/users');
+const data = await response.json();
+console.log(data);
+```
+
+**With custom headers:**
+
+```javascript
+const response = await proxy.get('/api/users', {
+  'X-Custom-Header': 'value',
+  Accept: 'application/json',
+});
+```
+
+#### POST Request
+
+```javascript
+const response = await proxy.post(
+  '/api/users',
+  JSON.stringify({
+    name: 'John Doe',
+    email: 'john@example.com',
+    role: 'developer',
+  }),
+);
 
-// Make POST request
-const response = await proxy.post('/api/users', JSON.stringify({
-  name: 'John Doe',
-  email: 'john@example.com'
-}));
 const newUser = await response.json();
+console.log('Created user:', newUser);
+```
+
+**With custom headers:**
 
-// Make PUT request
-const response = await proxy.put('/api/users/123', JSON.stringify({
-  name: 'Jane Doe'
-}));
+```javascript
+const response = await proxy.post('/api/users', JSON.stringify({ name: 'John Doe' }), {
+  'Content-Type': 'application/json',
+  'X-API-Version': '2.0',
+});
+```
 
-// Make PATCH request
-const response = await proxy.patch('/api/users/123', JSON.stringify({
-  email: 'jane@example.com'
-}));
+#### PUT Request
 
-// Make DELETE request
-await proxy.delete('/api/users/123');
+```javascript
+const response = await proxy.put(
+  '/api/users/123',
+  JSON.stringify({
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  }),
+);
+
+const updatedUser = await response.json();
 ```
 
-### Unify API
+#### PATCH Request
 
-Access unified, normalized data across different integrations.
+```javascript
+const response = await proxy.patch(
+  '/api/users/123',
+  JSON.stringify({
+    email: 'newemail@example.com',
+  }),
+);
+
+const partiallyUpdated = await response.json();
+```
 
-#### Chat (Slack, Discord, Microsoft Teams, etc.)
+#### DELETE Request
 
 ```javascript
-// Get unified API instance for a connection
-const unify = client.unify('conn_123');
+const response = await proxy.delete('/api/users/123');
 
-// List channels
-const channels = await unify.chat.channels({ limit: 100 });
+if (response.ok) {
+  console.log('User deleted successfully');
+}
+```
 
-// List channels with pagination
-const channels = await unify.chat.channels({
-  limit: 50,
-  after: 'cursor_token'
-});
+#### Working with Different Content Types
 
-// Include raw response from the integration
-const channels = await unify.chat.channels({
-  limit: 100,
-  includeRaw: true
+**Sending form data:**
+
+```javascript
+const formData = new URLSearchParams();
+formData.append('name', 'John Doe');
+formData.append('email', 'john@example.com');
+
+const response = await proxy.post('/api/users', formData.toString(), {
+  'Content-Type': 'application/x-www-form-urlencoded',
 });
 ```
 
-#### Git (GitHub, GitLab, Bitbucket, etc.)
+**Uploading files:**
 
 ```javascript
-const unify = client.unify('conn_123');
+import FormData from 'form-data';
+import fs from 'fs';
 
-// List repositories
-const repos = await unify.git.repos({ limit: 50 });
+const form = new FormData();
+form.append('file', fs.createReadStream('document.pdf'));
+form.append('title', 'My Document');
 
-// List pull requests for a repository
-const pulls = await unify.git.pulls({
-  repoName: 'owner/repo',
-  limit: 20
-});
+const response = await proxy.post('/api/documents', form, form.getHeaders());
+```
+
+#### Handling Binary Data
+
+```javascript
+const response = await proxy.get('/api/files/download/123');
+const buffer = await response.arrayBuffer();
+fs.writeFileSync('downloaded-file.pdf', Buffer.from(buffer));
+```
+
+### Unify API
+
+Access unified, normalized data across different integrations with a consistent interface.
+
+#### Creating a Unify Instance
+
+```javascript
+const unify = client.unify('conn_123abc');
+```
+
+#### Chat API
+
+The Chat API provides a unified interface for chat platforms like Slack, Discord, and Microsoft Teams.
 
-// List tags for a repository
-const tags = await unify.git.tags({ repoName: 'owner/repo' });
+##### List Channels
 
-// List releases for a repository
-const releases = await unify.git.releases({
-  repoName: 'owner/repo',
-  limit: 10
+Retrieve a list of channels from the connected chat platform.
+
+```javascript
+const result = await unify.chat.channels({
+  limit: 100,
+  after: null,
+  include_raw: false,
 });
 
-// Include raw response
-const repos = await unify.git.repos({ includeRaw: true });
+console.log('Channels:', result.data);
+console.log('Next cursor:', result.metadata.next);
 ```
 
-#### Project Management (Jira, Linear, Asana, etc.)
+**Parameters:**
+
+- `limit` (number, optional): Maximum number of channels to return (default: 100, max: 1000)
+- `after` (string, optional): Pagination cursor from previous response
+- `include_raw` (boolean, optional): Include raw API response from the integration (default: false)
+
+**Response:**
+
+```typescript
+{
+  data: [
+    {
+      id: 'C1234567890',
+      name: 'general'
+    },
+    {
+      id: 'C0987654321',
+      name: 'engineering'
+    }
+  ],
+  metadata: {
+    next: 'cursor_abc123'  // Use this for pagination
+  },
+  _raw?: {  // Only present if include_raw: true
+    // Original response from the integration API
+  }
+}
+```
+
+**Pagination example:**
 
 ```javascript
-// Get issues
-const issues = await client.unify('conn_123').pm.issues({ limit: 100 });
+let allChannels = [];
+let cursor = null;
+
+do {
+  const result = await unify.chat.channels({
+    limit: 100,
+    after: cursor,
+  });
+
+  allChannels = [...allChannels, ...result.data];
+  cursor = result.metadata.next;
+} while (cursor);
+
+console.log(`Fetched ${allChannels.length} total channels`);
+```
+
+#### Git API
 
-// List with pagination
-const issues = await client.unify('conn_123').pm.issues({
+The Git API provides a unified interface for version control platforms like GitHub, GitLab, and Bitbucket.
+
+##### List Repositories
+
+```javascript
+const result = await unify.git.repos({
   limit: 50,
-  after: 'cursor_token'
+  after: null,
+  include_raw: false,
 });
 
-// Include raw response
-const issues = await client.unify('conn_123').pm.issues({
-  includeRaw: true
-});
+console.log('Repositories:', result.data);
 ```
 
-## Error Handling
+**Response:**
 
-The SDK throws standard JavaScript errors. You can catch and handle them as needed:
+```typescript
+{
+  data: [
+    {
+      id: '123456',
+      name: 'my-awesome-project',
+      full_name: 'organization/my-awesome-project',
+      description: 'An awesome project',
+      url: 'https://github.com/organization/my-awesome-project',
+      created_at: '2023-01-15T10:30:00Z',
+      updated_at: '2024-01-20T14:22:00Z',
+      pushed_at: '2024-01-20T14:22:00Z'
+    }
+  ],
+  metadata: {
+    next: 'cursor_xyz789'
+  }
+}
+```
+
+##### List Pull Requests
 
 ```javascript
-try {
-  const client = new BundleUp('your-api-key');
-  const connections = await client.connections.list();
-} catch (error) {
-  if (error.message.includes('401')) {
-    console.error('Authentication failed: Invalid API key');
-  } else if (error.message.includes('404')) {
-    console.error('Resource not found');
-  } else if (error.message.includes('429')) {
-    console.error('Rate limit exceeded');
-  } else {
-    console.error('API error:', error.message);
+const result = await unify.git.pulls('organization/repo-name', {
+  limit: 20,
+  after: null,
+  include_raw: false,
+});
+
+console.log('Pull Requests:', result.data);
+```
+
+**Parameters:**
+
+- `repoName` (string, required): Repository name in the format 'owner/repo'
+- `limit` (number, optional): Maximum number of PRs to return
+- `after` (string, optional): Pagination cursor
+- `include_raw` (boolean, optional): Include raw API response
+
+**Response:**
+
+```typescript
+{
+  data: [
+    {
+      id: '12345',
+      number: 42,
+      title: 'Add new feature',
+      description: 'This PR adds an awesome new feature',
+      draft: false,
+      state: 'open',
+      url: 'https://github.com/org/repo/pull/42',
+      user: 'john-doe',
+      created_at: '2024-01-15T10:30:00Z',
+      updated_at: '2024-01-20T14:22:00Z',
+      merged_at: null
+    }
+  ],
+  metadata: {
+    next: null
   }
 }
 ```
 
-## Advanced Usage
+##### List Tags
+
+```javascript
+const result = await unify.git.tags('organization/repo-name', {
+  limit: 50,
+});
+
+console.log('Tags:', result.data);
+```
+
+**Response:**
 
-### Query Parameters
+```typescript
+{
+  data: [
+    {
+      name: 'v1.0.0',
+      commit_sha: 'abc123def456'
+    },
+    {
+      name: 'v0.9.0',
+      commit_sha: 'def456ghi789'
+    }
+  ],
+  metadata: {
+    next: null
+  }
+}
+```
 
-The `list()` method supports query parameters:
+##### List Releases
 
 ```javascript
-// List with filters
-const connections = await client.connections.list({
-  status: 'active',
-  limit: '50',
-  page: '1'
+const result = await unify.git.releases('organization/repo-name', {
+  limit: 10,
 });
+
+console.log('Releases:', result.data);
 ```
 
-### Custom Headers
+**Response:**
 
-When using the Proxy API, you can pass custom headers:
+```typescript
+{
+  data: [
+    {
+      id: '54321',
+      name: 'Version 1.0.0',
+      tag_name: 'v1.0.0',
+      description: 'Initial release with all the features',
+      prerelease: false,
+      url: 'https://github.com/org/repo/releases/tag/v1.0.0',
+      created_at: '2024-01-15T10:30:00Z',
+      released_at: '2024-01-15T10:30:00Z'
+    }
+  ],
+  metadata: {
+    next: null
+  }
+}
+```
+
+#### Project Management API
+
+The PM API provides a unified interface for project management platforms like Jira, Linear, and Asana.
+
+##### List Issues
 
 ```javascript
-const proxy = client.proxy('conn_123');
-const response = await proxy.get('/api/users', {}, {
-  'X-Custom-Header': 'value'
+const result = await unify.pm.issues({
+  limit: 100,
+  after: null,
+  include_raw: false,
 });
-```
 
-### TypeScript Support
+console.log('Issues:', result.data);
+```
 
-The SDK is written in TypeScript and includes comprehensive type definitions:
+**Response:**
 
 ```typescript
-import { BundleUp } from '@bundleup/sdk';
+{
+  data: [
+    {
+      id: 'PROJ-123',
+      url: 'https://jira.example.com/browse/PROJ-123',
+      title: 'Fix login bug',
+      status: 'in_progress',
+      description: 'Users are unable to log in',
+      created_at: '2024-01-15T10:30:00Z',
+      updated_at: '2024-01-20T14:22:00Z'
+    }
+  ],
+  metadata: {
+    next: 'cursor_def456'
+  }
+}
+```
 
-const client = new BundleUp(process.env.BUNDLEUP_API_KEY!);
+**Filtering and sorting:**
 
-// Types are inferred automatically
-const connections = await client.connections.list();
-const webhook = await client.webhooks.create({
-  url: 'https://example.com/webhook',
-  events: {
-    'connection.created': true
-  }
-});
+```javascript
+const openIssues = result.data.filter(issue => issue.status === 'open');
+const sortedByDate = result.data.sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
+```
+
+## Error Handling
+
+The SDK throws standard JavaScript errors with descriptive messages. Always wrap SDK calls in try-catch blocks for proper error handling.
+
+```javascript
+try {
+  const connections = await client.connections.list();
+} catch (error) {
+  console.error('Failed to fetch connections:', error.message);
+}
 ```
 
+### Getting Help
+
+If you're still experiencing issues:
+
+1. Check the [BundleUp Documentation](https://docs.bundleup.io)
+2. Search [GitHub Issues](https://github.com/bundleup/javascript/issues)
+3. Join our [Community Discord](https://discord.gg/bundleup)
+4. Contact [support@bundleup.io](mailto:support@bundleup.io)
+
+When reporting issues, please include:
+
+- SDK version (`@bundleup/sdk` version from package.json)
+- Node.js version (`node --version`)
+- Minimal code to reproduce the issue
+- Full error message and stack trace
+
 ## Development
 
-After cloning the repository, install dependencies:
+### Setting Up Development Environment
 
 ```bash
+# Clone the repository
+git clone https://github.com/bundleup/javascript.git
+cd javascript/packages/sdk
+
+# Install dependencies
 npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode for development
+npm run dev
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Main entry point
+├── proxy.ts              # Proxy API implementation
+├── unify.ts              # Unify API implementation
+├── utils.ts              # Utility functions
+├── resources/
+│   ├── base.ts          # Base resource class
+│   ├── connection.ts    # Connections API
+│   ├── integration.ts   # Integrations API
+│   └── webhooks.ts      # Webhooks API
+├── unify/
+│   ├── base.ts          # Base Unify class
+│   ├── chat.ts          # Chat Unify API
+│   ├── git.ts           # Git Unify API
+│   └── pm.ts            # PM Unify API
+└── __tests__/           # Test files
 ```
 
-Build the package:
+### Running Tests
 
 ```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm test -- --watch
+
+# Run specific test file
+npm test -- proxy.test.ts
+
+# Run with coverage
+npm test -- --coverage
+```
+
+### Building
+
+```bash
+# Build for production
 npm run build
+
+# Clean build artifacts
+npm run clean
+
+# Build and watch for changes
+npm run dev
 ```
 
-Run tests:
+### Linting
 
 ```bash
-npm test
+# Run ESLint
+npm run lint
+
+# Fix linting issues
+npm run lint -- --fix
 ```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/bundleup/javascript.
+We welcome contributions to the BundleUp JavaScript SDK! Here's how you can help:
+
+### Reporting Bugs
+
+1. Check if the bug has already been reported in [GitHub Issues](https://github.com/bundleup/javascript/issues)
+2. If not, create a new issue with:
+   - Clear title and description
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - SDK version and environment details
+
+### Suggesting Features
+
+1. Open a new issue with the "feature request" label
+2. Describe the feature and its use case
+3. Explain why this feature would be useful
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a new branch: `git checkout -b feature/my-new-feature`
+3. Make your changes
+4. Write or update tests
+5. Ensure all tests pass: `npm test`
+6. Commit your changes: `git commit -am 'Add new feature'`
+7. Push to the branch: `git push origin feature/my-new-feature`
+8. Submit a pull request
+
+### Development Guidelines
+
+- Follow the existing code style
+- Add tests for new features
+- Update documentation for API changes
+- Keep commits focused and atomic
+- Write clear commit messages
 
 ## License
 
 This package is available as open source under the terms of the [ISC License](https://opensource.org/licenses/ISC).
 
+```
+Copyright (c) 2024 BundleUp
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
 ## Support
 
-- Documentation: [https://docs.bundleup.io](https://docs.bundleup.io)
-- Email: [support@bundleup.io](mailto:support@bundleup.io)
-- GitHub Issues: [https://github.com/bundleup/javascript/issues](https://github.com/bundleup/javascript/issues)
+Need help? We're here for you!
+
+### Documentation
+
+- **Official Docs**: [https://docs.bundleup.io](https://docs.bundleup.io)
+- **API Reference**: [https://docs.bundleup.io/api](https://docs.bundleup.io/api)
+- **SDK Guides**: [https://docs.bundleup.io/sdk/javascript](https://docs.bundleup.io/sdk/javascript)
+
+### Community
+
+- **Discord**: [https://discord.gg/bundleup](https://discord.gg/bundleup)
+- **GitHub Discussions**: [https://github.com/bundleup/javascript/discussions](https://github.com/bundleup/javascript/discussions)
+- **Stack Overflow**: Tag your questions with `bundleup`
+
+### Direct Support
+
+- **Email**: [support@bundleup.io](mailto:support@bundleup.io)
+- **GitHub Issues**: [https://github.com/bundleup/javascript/issues](https://github.com/bundleup/javascript/issues)
+- **Twitter**: [@bundleup_io](https://twitter.com/bundleup_io)
+
+### Enterprise Support
+
+For enterprise customers, we offer:
+
+- Priority support with SLA
+- Dedicated support channel
+- Architecture consultation
+- Custom integration assistance
+
+Contact [enterprise@bundleup.io](mailto:enterprise@bundleup.io) for more information.
 
 ## Code of Conduct
 
 Everyone interacting in the BundleUp project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bundleup/javascript/blob/main/CODE_OF_CONDUCT).
+
+---
+
+Made with ❤️ by the [BundleUp](https://bundleup.io) team