@forge/teamwork-graph v0.1.4

Forge Graph Client

A client for interacting with the Forge Graph API.

Installation

npm install @forge/teamwork-graph

Usage Examples

Document Entity

import { graph } from '@forge/teamwork-graph';
import type { EntityPayload, DocumentCategory } from '@forge/teamwork-graph';


const documentPayload: EntityPayload = {
  // Required base fields
  schemaVersion: '1.0',
  id: 'doc-123',
  updateSequenceNumber: Date.now(),
  displayName: 'Project Requirements Doc',
  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: [
    {
      accountId: 'acc-123',
      email: 'owner@example.com'
    }
  ],

  // Document preview
  thumbnail: {
    externalUrl: 'https://example.com/thumbnail.png'
  },

  // Hierarchical relationships
  parentKey: {
    type: 'atlassian:document',
    value: {
      entityId: 'parent-folder-id'
    }
  },
  containerKey: {
    type: 'atlassian:space',
    value: {
      entityId: 'space-123'
    }
  },

  // Access control
  permissions: {
    accessControls: [
      {
        principals: [
          { type: 'USER', id: 'user-123' },
          { type: 'GROUP', id: 'group-456' },
          { type: 'EVERYONE' }
        ]
      }
    ],
    smartLinkViewedBy: [
      {
        principalUser: {
          type: 'USER',
          id: 'user-789'
        }
      }
    ]
  },

  // Relationships
  associations: {
    set: [
      {
        associationType: 'issueIdOrKeys',
        values: ['PROJ-123', 'PROJ-456']
      }
    ]
  },

  // Document-specific attributes
  'atlassian:document': {
    type: {
      category: 'document',
      mimeType: 'text/plain',
      iconUrl: 'https://example.com/icon.png',
      fileExtension: 'txt'
    },
    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' }
    ]
  }
};

// Send the document to the API - now with context parameter
// context will be provided by the framework
await graph.setEntity(context, documentPayload);

Delete Operations

// Delete an entity - now with context parameter
await graph.deleteEntity(context, 'entity-123');

// Delete a user - now with context parameter
await graph.deleteUser(context, 'user-123');

// Delete a group - now with context parameter
await graph.deleteGroup(context, 'group-123');

Fetch External Data

// 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' }
  ]
});

// Define the result handler
const handleResult = (data) => {
  console.log('Fetched data:', data);
  // Process the data as needed
};

// Fetch and process the data
await graph.fetchExternalData(context, requestConfig, handleResult);

Transform Data

// 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
  }));
};

// Transform the data
const transformedData = await graph.transformData(context, rawData, transformToEntities);

Error Handling

The client throws ForgeGraphAPIError for API errors. Error types include:

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);
  }
}

Available Types

import type {
  // Entity-related
  EntityPayload,
  DocumentAttributes,
  DocumentCategory,
  DocumentType,
  DocumentContent,
  ExportLink,

  // User and Group
  UserObject,
  GroupPayload,

  // Common types
  Permissions,
  AccessControl,
  Principal,
  Thumbnail,
  
  // Relationships
  ParentKeyObject,
  ContainerKeyObject,
  Associations,
  AssociationObject,
  
  // Operations
  RequestConfig
} from '@forge/teamwork-graph';