# 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.

Use the REST API docs as the canonical source for shared row semantics:

* [Row Metadata and Relationships](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/row-metadata-and-relationships)
* [microappdata](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata)
* [microappdata/row](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row)
* [insertmicroapprows](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/insertmicroapprows)

This page focuses on wrapper ergonomics and method mappings rather than redefining metadata or payload semantics.

## Installation

```bash
npm install buzzy-api-nodejs
```

{% hint style="info" %}
**Using AWS Lambda?** If you're running this client inside AWS Lambda, your function can't use extra npm packages unless they are bundled with the function deployment or provided via an [AWS Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-layers.html). Refer to the AWS documentation for the full process.

One common approach is to package shared dependencies into a layer:

```bash
mkdir -p nodejs
npm install --prefix nodejs buzzy-api-nodejs axios
zip -r buzzy-node-deps-layer.zip nodejs
# Publish the zip as a Lambda Layer, then attach that layer to your function
```

Keep your layer up to date whenever you upgrade `buzzy-api-nodejs` or any other npm packages so your functions run on the latest supported and most secure package versions.
{% endhint %}

## Usage

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

// Example: Login and get auth credentials
async function example() {
  const auth = await login({
    url: 'https://your-buzzy-instance.com',
    email: 'user@example.com',
    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);
}
```

{% hint style="info" %}
**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](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/common-api-examples).
{% endhint %}

## API Reference

### login

```javascript
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

```javascript
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:**

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

### sendNotification

```javascript
sendNotification({ authToken, userId, url, appID, email, message, badgeCount, channel })
```

Sends a notification to a user by email with optional badge and channel controls.

**Parameters:**

* `authToken` (string): Authentication token
* `userId` (string): User ID of the requesting user
* `url` (string): The base URL of your Buzzy instance
* `appID` (string): App ID the requesting user can edit
* `email` (string): Recipient email address
* `message` (string, optional): Visible notification message
* `badgeCount` (number, optional): Absolute badge value to send
* `channel` (string, optional): `push`, `inApp`, or omit for default behavior

The authenticated user must be able to edit the target app. This method uses the same permission checks as the REST endpoint and is not an API-key-only operation.

When `channel: 'push'` is used without a `message`, Buzzy sends a badge-only push update. It does not show a visible notification message and only updates the app badge number on the user's Apple device.

**Returns:**

* Promise resolving to the notification response

Typical response:

```javascript
{
  ok: true,
  appID: 'your-app-id',
  email: 'user@example.com',
  channel: 'push',
  hasMessage: false,
  badgeCount: 7,
  notificationCount: 0,
  pushCount: 1
}
```

**Visible notification example:**

```javascript
const result = await sendNotification({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  appID: 'your-app-id',
  email: 'user@example.com',
  message: 'Hello from Buzzy'
});
```

**Badge-only app push example:**

```javascript
const result = await sendNotification({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  appID: 'your-app-id',
  email: 'user@example.com',
  badgeCount: 7,
  channel: 'push'
});
```

**In-app only example:**

```javascript
const result = await sendNotification({
  authToken,
  userId,
  url: 'https://your-buzzy-instance.com',
  appID: 'your-app-id',
  email: 'user@example.com',
  message: 'Check the app inbox',
  channel: 'inApp'
});
```

### getUserID

```javascript
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

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

Inserts a new row into a specified MicroApp.

This method wraps [insertmicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/insertmicroapprow). Use the REST page for canonical `rowData`, linked-table, and `embeddingRowID` semantics.

**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

This wrapper currently exposes only `embeddingRowID`, `viewers`, and `userID` from the fuller REST insert contract. If you need REST-only options such as `teamViewers` or `ignoreActionRules`, call the REST endpoint directly.

**Returns:**

* Promise resolving to an object containing the inserted row ID

### insertMicroAppRowsBatch

```javascript
insertMicroAppRowsBatch({
  microAppID,
  authToken,
  userId,
  url,
  rows,
  embeddingRowID,
  viewers,
  userID
})
```

Inserts multiple rows into a specified MicroApp in one request.

This method wraps [insertmicroapprows](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/insertmicroapprows). Use the REST page for canonical batch payload semantics, per-row `embeddingRowID` overrides, and partial-success response details.

**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
* `rows` (array): Array of row objects keyed by field label
* `embeddingRowID` (string, optional): Default parent row ID for the batch
* `viewers` (array, optional): Array of user IDs who can view inserted rows
* `userID` (string, optional): Creator override for inserted rows

**Returns:**

* Promise resolving to `{ inserted, rowIDs, errors? }`

### getMicroAppData

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

Retrieves data from a specified MicroApp.

This method wraps [microappdata](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata). Use the REST page for the canonical definition of filtering, sorting, pagination, metadata fields, and `embeddingRowID` child-row queries.

**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](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microappdata#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

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

Retrieves a specific row from a MicroApp.

This method wraps [microappdata/row](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row). Use the REST docs for the canonical row response shape and metadata meanings.

**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

```javascript
removeMicroAppRow({ rowID, authToken, userId, url, ignoreActionRules })
```

Removes a specific row from a MicroApp.

This method wraps [removemicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/removemicroapprow).

**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
* `ignoreActionRules` (boolean, optional): Passed by the wrapper, but the current REST route does not use it

**Returns:**

* Promise resolving to the operation result

### updateMicroAppDataRow

```javascript
updateMicroAppDataRow({
  rowID,
  authToken,
  userId,
  url,
  rowData,
  userID
})
```

Updates a specific row in a MicroApp.

This method wraps [updatemicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/updatemicroapprow). Use the REST page for canonical linked-table update semantics.

**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
* `userID` (string, optional): Creator override

This wrapper currently exposes only `userID` from the fuller REST update contract. If you need REST-only options such as `embeddingRowID` or `ignoreActionRules`, call the REST endpoint directly.

**Returns:**

* Promise resolving to a boolean indicating success

### insertOrganization

```javascript
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

```javascript
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

```javascript
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

```javascript
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:**

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

### getTeamMembers

```javascript
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:**

```javascript
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

```javascript
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:**

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

## Organization Management

### readOrganization

```javascript
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:**

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

### updateOrganization

```javascript
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:**

```javascript
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

```javascript
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:**

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

## Team Management

### readTeam

```javascript
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:**

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

### updateTeam

```javascript
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:**

```javascript
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

```javascript
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:**

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

### readTeamMember

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

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

### getTeamMembers

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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

```javascript
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:**

```javascript
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:

```javascript
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: 'user@example.com',
    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

```javascript
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: 'admin@example.com',
    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: ['dev1@example.com', 'dev2@example.com'],
      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: 'newdev@example.com',
      teamIDs: [teamID]
    });
    
  } catch (error) {
    console.error('Organization management workflow error:', error);
  }
}
```