Node.js API Client

The Buzzy API Node.js client provides a convenient way to interact with the Buzzy REST API from Node.js applications. This client handles authentication, request formatting, and response parsing, making it easier to use the API.

Installation

npm install buzzy-api-nodejs

Usage

import { 
  login, 
  insertMicroAppRow, 
  getMicroAppData 
} from 'buzzy-api-nodejs';

// Example: Login and get auth credentials
async function example() {
  const auth = await login({
    url: 'https://your-buzzy-instance.com',
    email: '[email protected]',
    password: 'password'
  });
  
  // Use auth credentials for other API calls
  const { token, userId } = auth;
  
  // Example: Get data from a MicroApp
  const rows = await getMicroAppData({
    microAppID: 'microAppID',
    authToken: token,
    userId: userId,
    url: 'https://your-buzzy-instance.com'
  });
  
  console.log(rows);
}

Comprehensive Examples: For detailed examples showing how to perform the same operations using the Node.js client, REST API, and BuzzyFrameAPI, see Common API Examples.

API Reference

login

login({ url, email, password })

Logs in a user and retrieves authentication token and user ID.

Parameters:

• url (string): The base URL of your Buzzy instance

• email (string): The user's email

• password (string): The user's password

Returns:

• Promise resolving to { token, userId }

logout

logout({ authToken, userId, url })

Logs out a user by removing their authentication token.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID

• url (string): Buzzy instance URL

Returns:

• Promise resolving to logout response

Example:

const result = await logout({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com'
});

getUserID

getUserID({ authToken, userId, url, email })

Finds a user ID based on an email address.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• email (string): The email to look up

Returns:

• Promise resolving to an object containing the user ID

insertMicroAppRow

insertMicroAppRow({
  microAppID,
  authToken,
  userId,
  url,
  rowData,
  embeddingRowID,
  viewers,
  userID
})

Inserts a new row into a specified MicroApp.

Parameters:

• microAppID (string): The ID of the MicroApp

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• rowData (object): The data to insert

• embeddingRowID (string, optional): The ID of the embedding row

• viewers (array, optional): Array of user IDs who can view this row

• userID (string, optional): The ID of the creator

Returns:

• Promise resolving to an object containing the inserted row ID

getMicroAppData

getMicroAppData({
  microAppID,
  authToken,
  userId,
  url,
  optSearchFilters,
  searchFilter,
  optViewFilters,
  optIsVectorSearch,
  optVectorSearchString,
  optLimit
})

Retrieves data from a specified MicroApp.

Parameters:

• microAppID (string): The ID of the MicroApp

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• optSearchFilters (object, optional): Optional search filters

• searchFilter (object, optional): Primary search filter

• optViewFilters (object, optional): Optional view filters for filtering results, including geo/spatial queries using sortValGeometry (see geo/spatial query examples)

• optIsVectorSearch (boolean, optional): Whether to use vector search

• optVectorSearchString (string, optional): Vector search string

• optLimit (number, optional): Number of results to return

Returns:

• Promise resolving to an array of rows

getMicroAppDataRow

getMicroAppDataRow({ rowID, authToken, userId, url })

Retrieves a specific row from a MicroApp.

Parameters:

• rowID (string): The ID of the row

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

Returns:

• Promise resolving to the row data

removeMicroAppRow

removeMicroAppRow(rowID, authToken, userId, url)

Removes a specific row from a MicroApp.

Parameters:

• rowID (string): The ID of the row to remove

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

Returns:

• Promise resolving to the operation result

updateMicroAppDataRow

updateMicroAppDataRow({
  rowID,
  authToken,
  userId,
  url,
  rowData,
  creatorID
})

Updates a specific row in a MicroApp.

Parameters:

• rowID (string): The ID of the row to update

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• rowData (object): The new data for the row

• creatorID (string, optional): The ID of the creator

Returns:

• Promise resolving to a boolean indicating success

insertOrganization

insertOrganization({ authToken, userId, url, organizationInfo })

Creates a new organization.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• organizationInfo (object): Information about the organization

Returns:

• Promise resolving to the operation result

insertTeam

insertTeam({ authToken, userId, url, teamInfo, adminID })

Creates a new team within an organization.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamInfo (object): Information about the team

• adminID (string, optional): The ID of the admin user

Returns:

• Promise resolving to the operation result

insertTeamMembers

insertTeamMembers({
  authToken,
  userId,
  url,
  teamIDs,
  emails,
  userIDs,
  targetInitialApp,
  targetInitialScreen,
  targetRoute
})

Adds members to teams.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamIDs (array): Array of team IDs

• emails (array, optional): Array of user emails

• userIDs (array, optional): Array of user IDs

• targetInitialApp (string, optional): Initial app for new users

• targetInitialScreen (string, optional): Initial screen for new users

• targetRoute (string, optional): Route for new users

Returns:

• Promise resolving to the operation result

Advanced Team Management

enforceTeamMembership

enforceTeamMembership({ authToken, userId, url, userID, email, teamIDs })

Enforces team membership for a user by adding/removing them from specified teams.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID making the request

• url (string): Buzzy instance URL

• userID (string): User ID to manage (optional if email provided)

• email (string): Email to manage (optional if userID provided)

• teamIDs (array): Array of team IDs to enforce membership for

Returns:

• Promise resolving to enforcement response

Example:

const result = await enforceTeamMembership({
  authToken: 'your-auth-token',
  userId: 'admin-user-id',
  url: 'https://your-buzzy-instance.com',
  email: '[email protected]',
  teamIDs: ['team-id-1', 'team-id-2']
});

getTeamMembers

getTeamMembers({ authToken, userId, url, teamIDs })

Gets team members for specified teams.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID

• url (string): Buzzy instance URL

• teamIDs (array): Array of team IDs to get members for

Returns:

• Promise resolving to team members response with array of user IDs

Example:

const result = await getTeamMembers({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  teamIDs: ['team-id-1', 'team-id-2']
});

AI-Powered App Creation

createAppWithPrompt

createAppWithPrompt({ url, apiKey, userEmail, appPrompt, attachments })

Creates an app using AI prompt.

Parameters:

• url (string): Buzzy instance URL

• apiKey (string): API key for authentication

• userEmail (string): User's email

• appPrompt (string): AI prompt for app creation

• attachments (array, optional): Optional attachments array

Returns:

• Promise resolving to app creation response with buzzID

Example:

const result = await createAppWithPrompt({
  url: 'https://your-buzzy-instance.com',
  apiKey: 'your-api-key',
  userEmail: '[email protected]',
  appPrompt: 'Create a task management app with user assignments',
  attachments: []
});

Organization Management

readOrganization

readOrganization({ authToken, userId, url, organizationID })

Retrieves information about a specific organization.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• organizationID (string): The ID of the organization to read

Returns:

• Promise resolving to the organization data

Example:

const organization = await readOrganization({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  organizationID: 'org-id-123'
});

updateOrganization

updateOrganization({ authToken, userId, url, organizationID, organizationInfo })

Updates an existing organization's information.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• organizationID (string): The ID of the organization to update

• organizationInfo (object): Updated organization information

Returns:

• Promise resolving to the update result

Example:

const result = await updateOrganization({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  organizationID: 'org-id-123',
  organizationInfo: {
    name: 'Updated Organization Name',
    description: 'Updated description'
  }
});

deleteOrganization

deleteOrganization({ authToken, userId, url, organizationID })

Deletes an organization.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• organizationID (string): The ID of the organization to delete

Returns:

• Promise resolving to the deletion result

Example:

const result = await deleteOrganization({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  organizationID: 'org-id-123'
});

Team Management

readTeam

readTeam({ authToken, userId, url, teamID })

Retrieves information about a specific team.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamID (string): The ID of the team to read

Returns:

• Promise resolving to the team data

Example:

const team = await readTeam({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  teamID: 'team-id-123'
});

updateTeam

updateTeam({ authToken, userId, url, teamID, teamInfo })

Updates an existing team's information.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamID (string): The ID of the team to update

• teamInfo (object): Updated team information

Returns:

• Promise resolving to the update result

Example:

const result = await updateTeam({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  teamID: 'team-id-123',
  teamInfo: {
    name: 'Updated Team Name',
    description: 'Updated team description'
  }
});

deleteTeam

deleteTeam({ authToken, userId, url, teamID })

Deletes a team.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamID (string): The ID of the team to delete

Returns:

• Promise resolving to the deletion result

Example:

const result = await deleteTeam({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  teamID: 'team-id-123'
});

readTeamMember

readTeamMember({ authToken, userId, url, teamID, userID })

Retrieves information about a specific team member.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamID (string): The ID of the team

• userID (string): The ID of the team member

Returns:

• Promise resolving to the team member data

Example:

const member = await readTeamMember({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  teamID: 'team-id-123',
  userID: 'member-user-id'
});

updateTeamMember

updateTeamMember({ authToken, userId, url, teamID, userID, role })

Updates a team member's role or information.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamID (string): The ID of the team

• userID (string): The ID of the team member to update

• role (string): The new role for the team member ('admin' or 'member')

Returns:

• Promise resolving to the update result

Example:

const result = await updateTeamMember({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  teamID: 'team-id-123',
  userID: 'member-user-id',
  role: 'admin'
});

deleteTeamMember

deleteTeamMember({ authToken, userId, url, teamID, userID })

Removes a member from a team.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamID (string): The ID of the team

• userID (string): The ID of the team member to remove

Returns:

• Promise resolving to the deletion result

Example:

const result = await deleteTeamMember({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  teamID: 'team-id-123',
  userID: 'member-user-id'
});

enforceTeamMembership

enforceTeamMembership({ authToken, userId, url, email, teamIDs })

Enforces team membership for a user by adding them to specified teams.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• email (string): Email of the user to add to teams

• teamIDs (array): Array of team IDs to add the user to

Returns:

• Promise resolving to the enforcement result

Example:

const result = await enforceTeamMembership({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  email: '[email protected]',
  teamIDs: ['team-id-1', 'team-id-2']
});

getTeamMembers

getTeamMembers({ authToken, userId, url, teamIDs })

Retrieves all members for specified teams.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• teamIDs (array): Array of team IDs to get members for

Returns:

• Promise resolving to an array of team members

Example:

const members = await getTeamMembers({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  teamIDs: ['team-id-1', 'team-id-2']
});

MicroAppChild Operations

MicroAppChild operations allow you to manage file attachments and child items within MicroApp data structures. These operations are essential for handling file uploads, attachments, and hierarchical data relationships.

createMicroAppChild

createMicroAppChild({
  authToken,
  userId,
  url,
  microAppResourceID,
  appID,
  fieldID,
  content
})

Creates a new MicroAppChild entry, typically used for file attachments or child data items.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• microAppResourceID (string): ID of the MicroApp resource

• appID (string): ID of the parent app item

• fieldID (string): ID of the parent field

• content (object): Content data for the child item

Returns:

• Promise resolving to an object containing the created child ID

Example:

const result = await createMicroAppChild({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  microAppResourceID: 'microapp-resource-id',
  appID: 'parent-app-id',
  fieldID: 'attachment-field-id',
  content: {
    filename: 'document.pdf',
    filesize: 1024000,
    contentType: 'application/pdf'
  }
});
console.log('Created child ID:', result.childID);

getChildItemsByField

getChildItemsByField({
  authToken,
  userId,
  url,
  appID,
  fieldID
})

Retrieves all MicroAppChild items for a specific parent app item and field.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• appID (string): ID of the parent app item

• fieldID (string): ID of the parent field

Returns:

• Promise resolving to an array of child items

Example:

const childItems = await getChildItemsByField({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  appID: 'parent-app-id',
  fieldID: 'attachment-field-id'
});
console.log('Found', childItems.length, 'child items');

readMicroAppChild

readMicroAppChild({
  authToken,
  userId,
  url,
  childID
})

Reads a specific MicroAppChild item by its ID.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• childID (string): ID of the child item to read

Returns:

• Promise resolving to the child item data

Example:

const childItem = await readMicroAppChild({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  childID: 'child-item-id'
});
console.log('Child item:', childItem);

updateMicroAppChild

updateMicroAppChild({
  authToken,
  userId,
  url,
  childID,
  content
})

Updates the content of an existing MicroAppChild item.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• childID (string): ID of the child item to update

• content (object): New content data for the child item

Returns:

• Promise resolving to the update result

Example:

const result = await updateMicroAppChild({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  childID: 'child-item-id',
  content: {
    filename: 'updated-document.pdf',
    description: 'Updated file description'
  }
});

removeMicroAppChild

removeMicroAppChild({
  authToken,
  userId,
  url,
  childID
})

Deletes a MicroAppChild item.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• childID (string): ID of the child item to delete

Returns:

• Promise resolving to the deletion result

Example:

const result = await removeMicroAppChild({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  childID: 'child-item-id'
});

AI-Powered App Creation

createAppWithPrompt

createAppWithPrompt({ authToken, userId, url, prompt, organizationID })

Creates a new app using AI based on a natural language prompt.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID of the requesting user

• url (string): The base URL of your Buzzy instance

• prompt (string): Natural language description of the app to create

• organizationID (string): ID of the organization to create the app in

Returns:

• Promise resolving to the created app information

Example:

const result = await createAppWithPrompt({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  prompt: 'Create a task management app with user assignments and due dates',
  organizationID: 'org-id-123'
});
console.log('Created app:', result.appID);

S3 File Operations

copyS3File

copyS3File({ authToken, userId, url, sourceResourceID, destinationResourceID, fileKey, newFileKey })

Copies a file between S3 locations.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID

• url (string): Buzzy instance URL

• sourceResourceID (string): Source resource ID

• destinationResourceID (string): Destination resource ID

• fileKey (string): File key to copy

• newFileKey (string, optional): Optional new file key

Returns:

• Promise resolving to copy response with signed URL

Example:

const result = await copyS3File({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  sourceResourceID: 'source-resource-id',
  destinationResourceID: 'dest-resource-id',
  fileKey: 'path/to/file.pdf'
});

uploadFileToS3

uploadFileToS3({ authToken, userId, url, resourceID, fieldID, fileUrl, filename })

Uploads a file to S3 from a URL.

Parameters:

• authToken (string): Authentication token

• userId (string): User ID

• url (string): Buzzy instance URL

• resourceID (string): Resource ID

• fieldID (string): Field ID

• fileUrl (string): URL of file to upload

• filename (string): Filename for the upload

Returns:

• Promise resolving to upload response with URL

Example:

const result = await uploadFileToS3({
  authToken: 'your-auth-token',
  userId: 'user-id',
  url: 'https://your-buzzy-instance.com',
  resourceID: 'resource-id',
  fieldID: 'field-id',
  fileUrl: 'https://example.com/document.pdf',
  filename: 'document.pdf'
});

Comprehensive Examples

File Attachment Workflow

Here's a complete example showing how to create, manage, and delete file attachments using MicroAppChild operations:

import { 
  login, 
  createMicroAppChild, 
  getChildItemsByField, 
  updateMicroAppChild, 
  removeMicroAppChild,
  uploadFileToS3 
} from 'buzzy-api-nodejs';

async function fileAttachmentWorkflow() {
  // Login and get credentials
  const auth = await login({
    url: 'https://your-buzzy-instance.com',
    email: '[email protected]',
    password: 'password'
  });
  
  const { token, userId } = auth;
  const baseParams = {
    authToken: token,
    userId: userId,
    url: 'https://your-buzzy-instance.com'
  };
  
  try {
    // 1. Upload a file to S3
    const uploadResult = await uploadFileToS3({
      ...baseParams,
      resourceID: 'resource-id',
      fieldID: 'attachment-field-id',
      fileUrl: 'https://example.com/document.pdf',
      filename: 'important-document.pdf'
    });
    
    // 2. Create a MicroAppChild entry for the uploaded file
    const childResult = await createMicroAppChild({
      ...baseParams,
      microAppResourceID: 'microapp-resource-id',
      appID: 'parent-app-id',
      fieldID: 'attachment-field-id',
      content: {
        filename: 'important-document.pdf',
        fileUrl: uploadResult.url,
        filesize: 1024000,
        contentType: 'application/pdf'
      }
    });
    
    console.log('Created attachment:', childResult.childID);
    
    // 3. List all attachments for this field
    const attachments = await getChildItemsByField({
      ...baseParams,
      appID: 'parent-app-id',
      fieldID: 'attachment-field-id'
    });
    
    console.log('Total attachments:', attachments.length);
    
    // 4. Update attachment metadata
    await updateMicroAppChild({
      ...baseParams,
      childID: childResult.childID,
      content: {
        filename: 'important-document.pdf',
        description: 'Updated: Critical business document',
        tags: ['important', 'business']
      }
    });
    
    // 5. Clean up - remove attachment if needed
    // await removeMicroAppChild({
    //   ...baseParams,
    //   childID: childResult.childID
    // });
    
  } catch (error) {
    console.error('File attachment workflow error:', error);
  }
}

Organization and Team Management Lifecycle

import { 
  login,
  insertOrganization,
  readOrganization,
  updateOrganization,
  insertTeam,
  readTeam,
  updateTeam,
  insertTeamMembers,
  enforceTeamMembership,
  getTeamMembers
} from 'buzzy-api-nodejs';

async function organizationManagementWorkflow() {
  const auth = await login({
    url: 'https://your-buzzy-instance.com',
    email: '[email protected]',
    password: 'password'
  });
  
  const { token, userId } = auth;
  const baseParams = {
    authToken: token,
    userId: userId,
    url: 'https://your-buzzy-instance.com'
  };
  
  try {
    // 1. Create organization
    const orgResult = await insertOrganization({
      ...baseParams,
      organizationInfo: {
        name: 'Acme Corporation',
        description: 'Leading provider of innovative solutions'
      }
    });
    
    const organizationID = orgResult.organizationID;
    console.log('Created organization:', organizationID);
    
    // 2. Read organization details
    const orgDetails = await readOrganization({
      ...baseParams,
      organizationID
    });
    
    // 3. Update organization
    await updateOrganization({
      ...baseParams,
      organizationID,
      organizationInfo: {
        name: 'Acme Corporation Ltd',
        description: 'Leading provider of innovative business solutions'
      }
    });
    
    // 4. Create team within organization
    const teamResult = await insertTeam({
      ...baseParams,
      teamInfo: {
        organizationID,
        name: 'Development Team',
        description: 'Software development team'
      },
      adminID: userId
    });
    
    const teamID = teamResult.teamID;
    console.log('Created team:', teamID);
    
    // 5. Add team members
    await insertTeamMembers({
      ...baseParams,
      teamIDs: [teamID],
      emails: ['[email protected]', '[email protected]'],
      targetInitialApp: 'welcome-app-id'
    });
    
    // 6. Get team members
    const members = await getTeamMembers({
      ...baseParams,
      teamIDs: [teamID]
    });
    
    console.log('Team members:', members);
    
    // 7. Enforce team membership (add/remove users as needed)
    await enforceTeamMembership({
      ...baseParams,
      email: '[email protected]',
      teamIDs: [teamID]
    });
    
  } catch (error) {
    console.error('Organization management workflow error:', error);
  }
}