@forge/teamwork-graph 2.0.0 → 2.1.0-next.0-experimental-ab129b0

package/README.md

@@ -1,6 +1,6 @@
-# Forge Graph Client
+# Forge Teamwork Graph SDK
 
-A client for interacting with the Forge Graph API.
+A TypeScript SDK for interacting with the Forge Teamwork Graph API, providing a clean interface for managing objects, users, groups, and data operations.
 
 ## Installation
 
@@ -8,243 +8,358 @@ A client for interacting with the Forge Graph API.
 npm install @forge/teamwork-graph
 ```
 
-## Usage Examples
-
-### Document Entity
+## Quick Start
 
 ```typescript
 import { graph } from '@forge/teamwork-graph';
-import type { EntityPayload, DocumentCategory } from '@forge/teamwork-graph';
-
+import type { DocumentObject } from '@forge/teamwork-graph';
 
-const documentPayload: EntityPayload = {
-  // Required base fields
+// Create a document object
+const document: DocumentObject = {
   schemaVersion: '1.0',
   id: 'doc-123',
   updateSequenceNumber: Date.now(),
-  displayName: 'Project Requirements Doc',
+  displayName: 'Project Requirements',
   url: 'https://example.com/docs/requirements',
-  
-  // Optional base fields
   description: 'Project requirements and specifications',
   createdAt: new Date().toISOString(),
-  createdBy: {
-    accountId: 'acc-123',
-    email: 'creator@example.com'
-  },
   lastUpdatedAt: new Date().toISOString(),
-  lastUpdatedBy: {
-    accountId: 'acc-456',
-    email: 'updater@example.com'
-  },
-
-  // Document ownership
-  owners: [
+  permissions: [
     {
-      accountId: 'acc-123',
-      email: 'owner@example.com'
+      accessControls: [
+        {
+          principals: [
+            {
+              { type: 'USER', id: 'user-123' }
+            }
+          ]
+        }
+      ]
     }
   ],
+  'atlassian:document': {
+    type: {
+      category: 'document',
+      mimeType: 'text/plain'
+    },
+    content: {
+      mimeType: 'text/plain',
+      text: 'Document content...'
+    }
+  }
+};
 
-  // Document preview
-  thumbnail: {
-    externalUrl: 'https://example.com/thumbnail.png'
-  },
+const result = await graph.setObjects({ objects: [document] });
 
-  // Hierarchical relationships
-  parentKey: {
-    type: 'atlassian:document',
-    value: {
-      entityId: 'parent-folder-id'
-    }
-  },
-  containerKey: {
-    type: 'atlassian:space',
-    value: {
-      entityId: 'space-123'
-    }
-  },
+if (result.success) {
+  console.log('Document created successfully:', result.results);
+} else {
+  console.error('Failed to create document:', result.error);
+  // Access the original error for debugging
+  console.error('Original error:', result.originalError);
+}
+```
 
-  // Access control
-  permissions: {
-    accessControls: [
-      {
-        principals: [
-          { type: 'USER', id: 'user-123' },
-          { type: 'GROUP', id: 'group-456' },
-          { type: 'EVERYONE' }
-        ]
-      }
-    ],
-    smartLinkViewedBy: [
-      {
-        principalUser: {
-          type: 'USER',
-          id: 'user-789'
-        }
-      }
-    ]
-  },
+## Core Operations
 
-  // Relationships
-  associations: {
-    set: [
-      {
-        associationType: 'issueIdOrKeys',
-        values: ['PROJ-123', 'PROJ-456']
-      }
-    ]
-  },
+### Object Management
+
+```typescript
+import { graph } from '@forge/teamwork-graph';
+import type { DocumentObject } from '@forge/teamwork-graph';
 
-  // Document-specific attributes
+// Bulk create/update objects
+const document: DocumentObject = {
+  schemaVersion: '1.0',
+  id: 'doc-123',
+  updateSequenceNumber: Date.now(),
+  displayName: 'Project Requirements',
+  url: 'https://example.com/docs/requirements',
+  createdAt: new Date().toISOString(),
+  lastUpdatedAt: new Date().toISOString(),
+  permissions: [
+    {
+      accessControls: [
+        {
+          principals: [
+            {
+              { type: 'USER', id: 'user-123' }
+            }
+          ]
+        }
+      ]
+    }
+  ],
   'atlassian:document': {
     type: {
       category: 'document',
-      mimeType: 'text/plain',
-      iconUrl: 'https://example.com/icon.png',
-      fileExtension: 'txt'
+      mimeType: 'text/plain'
     },
     content: {
       mimeType: 'text/plain',
-      text: 'Document content...',
-      // binary: 'base64EncodedContent...' // Alternative to text
-    },
-    byteSize: 1234,
-    exportLinks: [
-      {
-        mimeType: 'application/pdf',
-        url: 'https://example.com/export/pdf'
-      }
-    ],
-    collaborators: [
-      { email: 'collaborator1@example.com' },
-      { email: 'collaborator2@example.com' }
-    ]
+      text: 'Document content...'
+    }
   }
 };
 
-// Send the document to the API - now with context parameter
-// context will be provided by the framework
-await graph.setEntity(context, documentPayload);
+const bulkResult = await graph.setObjects({
+  objects: [document]
+});
+
+// Get object by external ID
+const objectResult = await graph.getObjectByExternalId({
+  objectType: 'atlassian:document',
+  externalId: 'doc-123'
+});
+
+if (objectResult.success) {
+  console.log('Object found:', objectResult.object);
+} else {
+  console.error('Object not found:', objectResult.error);
+}
+
+// Delete objects by external IDs
+const deleteResult = await graph.deleteObjectsByExternalId({
+  objectType: 'atlassian:document',
+  externalIds: ['doc-123', 'doc-456']
+});
+
+// Delete objects by properties
+const deleteByPropsResult = await graph.deleteObjectsByProperties({
+  environment: 'staging',
+  status: 'completed'
+});
 ```
 
-### Delete Operations
+### User Management
 
 ```typescript
+import { graph } from '@forge/teamwork-graph';
+
+// Bulk create/update users
+const usersResult = await graph.setUsers({
+  users: [
+    {
+      externalId: 'user-123',
+      displayName: 'John Doe',
+      userName: 'johndoe',
+      name: {
+        formatted: 'John Doe',
+        familyName: 'Doe',
+        givenName: 'John'
+      },
+      emails: [
+        { value: 'john@example.com', primary: true }
+      ]
+    }
+  ]
+});
 
-// Delete an entity - now with context parameter
-await graph.deleteEntity(context, 'entity-123');
+// Get user by external ID
+const userResult = await graph.getUserByExternalId({
+  externalId: 'user-123'
+});
 
-// Delete a user - now with context parameter
-await graph.deleteUser(context, 'user-123');
+// Delete users by external IDs
+const deleteUsersResult = await graph.deleteUsersByExternalId({
+  externalIds: ['user-123', 'user-456']
+});
 
-// Delete a group - now with context parameter
-await graph.deleteGroup(context, 'group-123');
+// Map users to Atlassian accounts
+const mapResult = await graph.mapUsers({
+  directMappings: [
+    {
+      externalId: 'user-123',
+      updateSequenceNumber: Date.now(),
+      updatedAt: Date.now(),
+      accountId: 'acc-123'
+    }
+  ]
+});
 ```
 
-### Fetch External Data
+### Group Management
 
 ```typescript
+import { graph } from '@forge/teamwork-graph';
 
-// Define the request configuration
-const requestConfig = () => ({
-  path: '/api/v1/tasks',
-  method: 'GET',
-  remoteKey: 'jira',
-  url: 'https://your-instance.atlassian.net',
-  headers: [
-    { 'Authorization': 'Bearer your-token' }
+// Bulk create/update groups
+const groupsResult = await graph.setGroups({
+  groups: [
+    {
+      externalId: 'group-123',
+      displayName: 'Developers',
+      description: 'Development team'
+    }
   ]
 });
 
-// Define the result handler
-const handleResult = (data) => {
-  console.log('Fetched data:', data);
-  // Process the data as needed
-};
+// Get group by external ID
+const groupResult = await graph.getGroupByExternalId({
+  externalId: 'group-123'
+});
 
-// Fetch and process the data
-await graph.fetchExternalData(context, requestConfig, handleResult);
+// Delete groups by external IDs
+const deleteGroupsResult = await graph.deleteGroupsByExternalId({
+  externalIds: ['group-123', 'group-456']
+});
 ```
 
-### Transform Data
+### Data Operations
 
 ```typescript
+import { graph } from '@forge/teamwork-graph';
 
-// Define the raw data
-const rawData = {
-  issues: [
-    { key: 'PROJ-123', summary: 'Fix bug', assignee: { key: 'user1' } },
-    { key: 'PROJ-456', summary: 'Add feature', assignee: { key: 'user2' } }
-  ]
-};
-
-// Define the transform function
-const transformToEntities = (data) => {
-  return data.issues.map(issue => ({
-    id: issue.key,
-    displayName: issue.summary,
-    type: 'issue',
-    assignee: issue.assignee.key
-  }));
-};
+// Fetch external data
+const fetchResult = await graph.fetchData({
+  requestConfig: {
+    url: 'https://api.example.com/data',
+    method: 'GET',
+    headers: { 'Authorization': 'Bearer token' }
+  },
+  onResult: (data) => {
+    console.log('Data received:', data);
+    return data;
+  }
+});
 
-// Transform the data
-const transformedData = await graph.transformData(context, rawData, transformToEntities);
+// Transform data
+const transformResult = await graph.transformData({
+  data: { items: [{ id: 1, name: 'Item 1' }] },
+  transformMethod: (data) => {
+    return data.items.map(item => ({
+      id: `doc-${item.id}`,
+      displayName: item.name,
+      // Additional object properties would be added here
+    }));
+  }
+});
 ```
 
 ## Error Handling
 
-The client throws `ForgeGraphAPIError` for API errors. Error types include:
+The SDK provides comprehensive error handling with consistent error responses and access to original error objects for debugging.
+
+### Error Response Structure
+
+All operations return a response with this structure:
 
 ```typescript
-import { errorCodes } from '@forge/teamwork-graph';
-
-// Available error codes
-errorCodes.INVALID_REQUEST_BODY   // 400 Bad Request
-errorCodes.INSUFFICIENT_SCOPE     // 403 Forbidden
-errorCodes.TOO_MANY_REQUESTS      // 429 Rate Limit
-errorCodes.UNKNOWN_ERROR          // Other errors
-
-try {
-  const context = { id: 'operation-123', cloudId: 'cloud-123' };
-  await graph.setEntity(context, /* ... */);
-} catch (error) {
-  if (error instanceof ForgeGraphAPIError) {
-    console.error(error.code, error.message);
+interface BaseResponse {
+  success: boolean;
+  error?: string;
+  originalError?: unknown;
+}
+```
+
+### Error Types
+
+The SDK uses specific error classes for different types of failures:
+
+```typescript
+// Note: Error classes are not exported from the main package
+// They are used internally by the SDK for error handling
+
+// The SDK handles errors internally and returns them in the response
+// You can access error information through the response object:
+
+const result = await graph.setObjects({ objects: [] });
+
+if (!result.success) {
+  console.error('Operation failed:', result.error);
+  
+  // Access original error for debugging
+  if (result.originalError) {
+    console.error('Original error:', result.originalError);
   }
 }
 ```
 
-## Available Types
+### Error Handling Examples
+
+```typescript
+// Handle object operations
+const result = await graph.getObjectByExternalId({
+  objectType: 'atlassian:document',
+  externalId: 'nonexistent'
+});
+
+if (!result.success) {
+  console.error('Operation failed:', result.error);
+  
+  // Access original error for debugging
+if (result.originalError) {
+  console.error('Original error details:', result.originalError);
+}
+}
+
+// Handle validation errors (these are returned in the response)
+const result = await graph.setObjects({
+  objects: [] // Empty array will return error in response
+});
+
+if (!result.success) {
+  console.error('Validation failed:', result.error);
+}
+```
+
+## TypeScript Support
+
+The SDK is fully typed with comprehensive TypeScript definitions:
 
 ```typescript
 import type {
-  // Entity-related
-  EntityPayload,
-  DocumentAttributes,
-  DocumentCategory,
-  DocumentType,
-  DocumentContent,
-  ExportLink,
-
-  // User and Group
-  UserObject,
+  // Object types
+  Object,
+  DocumentObject,
+  SetObjectsRequest,
+  BulkObjectResponse,
+  GetObjectByExternalIdRequest,
+  GetObjectByExternalIdResponse,
+  
+  // User types
+  User,
+  UserPayload,
+  BulkUsersRequest,
+  BulkUsersResponse,
+  GetUserByExternalIdRequest,
+  GetUserByExternalIdResponse,
+  MapUsersRequest,
+  MapUsersResponse,
+  
+  // Group types
+  Group,
   GroupPayload,
-
-  // Common types
-  Permissions,
-  AccessControl,
-  Principal,
-  Thumbnail,
+  BulkGroupsRequest,
+  BulkGroupsResponse,
+  GetGroupByExternalIdRequest,
+  GetGroupByExternalIdResponse,
   
-  // Relationships
-  ParentKeyObject,
-  ContainerKeyObject,
-  Associations,
-  AssociationObject,
+  // Data operation types
+  FetchDataRequest,
+  FetchDataResponse,
+  TransformDataRequest,
+  TransformDataResponse,
   
-  // Operations
-  RequestConfig
+  // Common types
+  DeleteObjectsByExternalIdRequest,
+  DeleteObjectsByExternalIdResponse,
+  DeleteObjectsByPropertiesRequest,
+  DeleteObjectsByPropertiesResponse,
+  DeleteUsersByExternalIdRequest,
+  DeleteUsersByExternalIdResponse,
+  DeleteGroupsByExternalIdRequest,
+  DeleteGroupsByExternalIdResponse
 } from '@forge/teamwork-graph';
 ```
+
+## Configuration
+
+The SDK automatically handles authentication and configuration through the Forge platform. No additional setup is required.
+
+## Best Practices
+
+1. **Always check success flag**: Verify `result.success` before accessing response data
+2. **Handle errors gracefully**: Use the `error` field for user-facing messages and `originalError` for debugging
+3. **Validate input**: The SDK will throw validation errors for invalid input, so handle them appropriately
+5. **Monitor rate limits**: The SDK handles rate limiting automatically, but monitor for `429` errors