Membrane

https://docs.integration.app/docs/
Admin
Membrane is an AI-powered integration layer that enables products to connect with external apps and...
Tokens:82,761
Snippets:492
Trust Score:7.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install React Package

Source: https://docs.integration.app/docs/react

Installs the @membranehq/react NPM package using npm. This is the first step to begin building your integration UI with React.

```shell
npm install @membranehq/react
```

--------------------------------

### Install KEDA using Helm

Source: https://docs.integration.app/docs/helm

Adds the KEDA Helm repository, updates repositories, creates a keda namespace, and installs KEDA for autoscaling features.

```shell
helm repo add kedacore https://kedacore.github.io/charts
helm repo update
kubectl create namespace keda
helm install keda kedacore/keda --namespace keda
```

--------------------------------

### Open Pre-built Connection UI with Membrane SDK

Source: https://docs.integration.app/docs/getting-started

Opens a pre-built user interface for managing connections to external applications. This is the simplest way to start interacting with external apps on behalf of a customer. No specific dependencies are mentioned other than the Membrane SDK itself.

```javascript
integrationApp.open()
```

--------------------------------

### Install Prometheus Stack using Helm

Source: https://docs.integration.app/docs/helm

Adds the Prometheus community Helm repository, updates repositories, creates a monitoring namespace, and installs the kube-prometheus-stack.

```shell
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
kubectl create namespace monitoring
helm install prometheus-stack prometheus-community/kube-prometheus-stack --namespace monitoring
```

--------------------------------

### Webhook Types and Payload Examples

Source: https://docs.integration.app/docs/system-webhooks

Details the different types of system webhooks supported and provides example payloads for each event.

```APIDOC
## Webhook Types

Membrane supports the following webhook types:

### User Invited to Organization (`user-invited-to-org`)
Triggered when a user is invited to join an organization workspace.

**Payload Example:**
```json
{
  "type": "user-invited-to-org",
  "invitationUrl": "https://console.yourdomain.com/org-invitations/12345",
  "issuer": {
    "name": "John Admin",
    "email": "admin@company.com"
  },
  "user": {
    "email": "newuser@company.com"
  },
  "org": {
    "id": "org123",
    "name": "My Organization",
    "trialEndDate": "2025-05-16"
  }
}
```

### Organization Access Requested (`org-access-requested`)
Triggered when a user requests access to an organization based on their email domain.

**Payload Example:**
```json
{
  "type": "org-access-requested",
  "user": {
    "id": "user123",
    "email": "employee@company.com",
    "name": "Jane Employee"
  },
  "orgAdmins": [
    {
      "email": "admin@company.com",
      "orgs": [
        {
          "id": "org123",
          "name": "My Organization"
        }
      ]
    }
  ]
}
```

### Organization Created (`org-created`)
Triggered when a new organization is created on the platform.

**Payload Example:**
```json
{
  "type": "org-created",
  "name": "New Organization",
  "workspaceName": "Main Workspace",
  "orgId": "org456",
  "org": {
    "id": "org456",
    "name": "New Organization",
    "domains": ["company.com"],
    "trialEndDate": "2025-05-23"
  },
  "user": {
    "name": "Creator User",
    "email": "creator@company.com"
  }
}
```
```

--------------------------------

### Testing Webhooks

Source: https://docs.integration.app/docs/system-webhooks

Recommends tools and provides an example for testing webhook integrations.

```APIDOC
## Testing Webhooks

For development and testing purposes, you can use tools like:
  * **ngrok** : To expose local development servers
  * **webhook.site** : To inspect webhook payloads
  * **Postman** : To simulate webhook endpoints

Example ngrok setup:
```bash
# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the generated HTTPS URL in webhook configuration
```
```

--------------------------------

### JavaScript API Request Examples

Source: https://docs.integration.app/docs/javascript

Provides practical examples of using the API client to perform common HTTP requests: GET with query parameters, POST with data, PUT for updates, and DELETE.

```javascript
// GET request with query parameters
const response = await apiClient.get('/items', {
  page: 1,
  limit: 10
})

// POST request with data
const newItem = await apiClient.post('/items', {
  name: 'New Item',
  description: 'Description'
})

// PUT request to update
await apiClient.put('/items/123', {
  name: 'Updated Item'
})

// DELETE request
await apiClient.delete('/items/123')

```

--------------------------------

### ngrok Setup for Local Testing

Source: https://docs.integration.app/docs/system-webhooks

Bash commands to install and set up ngrok for exposing a local development server to the internet, which is useful for testing webhooks. After installation, ngrok http is used to tunnel traffic to a specified port (e.g., 3000).

```Bash
# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the generated HTTPS URL in webhook configuration
```

--------------------------------

### Example Action

Source: https://docs.integration.app/docs/actions

Provides an example of an action definition, including its name, key, input schema, type, and configuration.

```APIDOC
## Example Action

```yaml
name: Create Task
key: create-task
inputSchema:
  type: object
  properties:
    title: 
      type: string
    description:
      type: string
type: create-data-record
config:
  dataSource:
    collectionKey: issues
  fieldMapping:
    defaultValue:
      summary:
        $var: $.input.title
      description:
        $var: $.input.description
```
```

--------------------------------

### Integration App Helm Chart Values (YAML)

Source: https://docs.integration.app/docs/helm

Example configuration for the Integration App Helm chart's values.yaml file. It includes settings for service accounts, environment variables, and Auth0 integration.

```yaml
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:role/<YOUR_ROLE_NAME>

config:
  NODE_ENV: production
  MONGO_URI: MONGO_URI
  REDIS_URI: REDIS_URI
  # URI where `api` service will be available
  API_URI: API_URI
  # URI where `ui` service will be available
  UI_URI: UI_URI
  # URI where `console` service will be available
  CONSOLE_URI: CONSOLE_URI
  # Bucket for storing custom connectors
  CONNECTORS_S3_BUCKET: CONNECTORS_S3_BUCKET
  # Bucket for storing temporary files (like logs)
  TMP_S3_BUCKET: TMP_S3_BUCKET
  # Buckets for storing static files that should be available in user's browser (like images)
  STATIC_S3_BUCKET: STATIC_S3_BUCKET
  # Base URI where files stored in STATIC_S3_BUCKET will be available
  BASE_STATIC_URI: BASE_STATIC_URI
  # Auth0 Settings
  AUTH0_DOMAIN: AUTH0_DOMAIN
  AUTH0_CLIENT_ID: AUTH0_CLIENT_ID
  AUTH0_CLIENT_SECRET: AUTH0_CLIENT_SECRET
  # Secret key used for signing JWT tokens
  SECRET: SECRET
  # Secret key used for encrypting data at rest
  ENCRYPTION_SECRET: ENCRYPTION_SECRET
```

--------------------------------

### Generate JWT Token in Go

Source: https://docs.integration.app/docs/getting-started

Generates a JWT authentication token using the `github.com/dgrijalva/jwt-go` library. It includes customer ID, name, issuer, and expiration time. Ensure the library is imported correctly.

```go
import (
    "time"
    "github.com/dgrijalva/jwt-go"
)

var WORKSPACE_KEY = "f88f52bc-57a9-47e3-93b3-843fa0dd5708"
var WORKSPACE_SECRET = "2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66"

var SigningKey = []byte(WORKSPACE_SECRET)


claims := jwt.MapClaims{
    // Identifier of your customer (user, team, or organization).
    "id" : "{CUSTOMER_ID}",
    // Human-readable customer name.
    "name": "{CUSTOMER_NAME}",
    // To prevent token from being used for too long
    "exp": time.Now().Add(time.Hour * 24).Unix(),
    "iss": WORKSPACE_KEY,
    }

token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
tokenString, err := token.SignedString(SigningKey)
```

--------------------------------

### Install Membrane CLI

Source: https://docs.integration.app/docs/initial-context-for-ai

This command installs the Membrane CLI, which is necessary for configuring MCP tools when Membrane is not automatically available.

```shell
membrane
```

--------------------------------

### Setup or Refresh Data Source Instance

Source: https://docs.integration.app/docs/data-source-instances

Sets up or refreshes a Data Source Instance.

```APIDOC
## POST /connection/{connection_key}/dataSource/{data_source_key}/setup

### Description
Sets up or refreshes a Data Source Instance.

### Method
POST

### Endpoint
`/connection/{connection_key}/dataSource/{data_source_key}/setup`

### Request Example
```javascript
await integrationApp.connection('hubspot').dataSource('{DATA_SOURCE_KEY}').setup()
```
```

--------------------------------

### Search Data Record Configuration Example (YAML)

Source: https://docs.integration.app/docs/search-data-record

Provides a YAML configuration example for the 'search-data-record' function, demonstrating how to set up a data source, field mapping, and query parameters for searching tasks.

```yaml
name: Search Tasks
key: search-tasks
type: search-data-record
config:
  dataSource:
    collectionKey: tasks
  fieldMapping:
    importValue:
      title:
        $var: $.summary
  # Required: search query
  query:
    $var: $.input.searchText
  cursor:
    $var: $.input.pageToken

```

--------------------------------

### Install JavaScript SDK via NPM

Source: https://docs.integration.app/docs/javascript-sdk

Installs the @membranehq/sdk package using npm. This is the recommended method for most Node.js or front-end projects.

```bash
npm install @membranehq/sdk
```

--------------------------------

### Deploy Integration App Helm Chart

Source: https://docs.integration.app/docs/helm

Installs the Integration App Helm chart into the specified Kubernetes namespace. Creates the namespace if it doesn't exist.

```shell
helm install integration-app ./path-to-this-folder --namespace <your-namespace> --create-namespace
```

--------------------------------

### Setup Flow Instance

Source: https://docs.integration.app/docs/flow-instances

Re-fetches all dependencies (data sources, schemas, etc.) and recalculates dynamic fields for a given flow instance.

```APIDOC
## POST /websites/integration_app/connections/{connectionKey}/flows/{flowKey}/setup

### Description
Sets up or refreshes a flow instance, re-fetching dependencies and recalculating dynamic fields.

### Method
POST

### Endpoint
/websites/integration_app/connections/{connectionKey}/flows/{flowKey}/setup

### Parameters
#### Path Parameters
- **connectionKey** (string) - Required - The key of the connection.
- **flowKey** (string) - Required - The key of the flow.

### Request Example
```javascript
await integrationApp.connection('hubspot').flow('{FLOW_KEY}').setup()
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the setup.

#### Response Example
```json
{
  "message": "Flow instance setup initiated."
}
```
```

--------------------------------

### List Method Drilldown JavaScript Example

Source: https://docs.integration.app/docs/data-collection-methods

Provides a JavaScript example for using drilldowns with the 'list' method, demonstrating fetching files from multiple folders by first retrieving folders and then making subsequent requests for files within each folder.

```JavaScript
// Example: Fetching files from folders
module.exports = async ({ filter, cursor, parameters }) => {
  if (!cursor && filter?.parentFolderId === "root") {
    // First, get all folders
    const folders = await makeApiRequest({
      method: "GET",
      path: "/api/folders",
      credentials,
    })

    // Return folders with drilldowns for their files
    return {
      records: folders.data,
      drilldowns: folders.data.map((folder) => ({
        parameters: { recursive: true },
        filter: {
          type: "file",
          parentFolderId: folder.id,
        },
      })),
    }
  }

  // Regular file listing
  const response = await makeApiRequest({
    method: "GET",
    path: "/api/files",
    query: { folderId: filter?.parentFolderId },
    credentials,
  })

  return {
    records: response.data,
  }
}

```

--------------------------------

### Connector Specification Example (YAML)

Source: https://docs.integration.app/docs/connectors

An example of a Connector Specification file (`spec.yml`) which defines a connector's metadata, parameters schema, and authentication configuration.

```yaml
name: Connector Name
logoUri: https://static.integration.app/connectors/connector-key/logo.png>
key: connector-key
parametersSchema:
  type: object
  properties:
	  parameter:
			type: string
appUuid: 877b0ad6-66b1-4d61-82f9-7e4d62acea69
apiDocsUri: https://api.example.com/docs
auth:
  # Authentication configuration

```

--------------------------------

### Setup Flow Instance

Source: https://docs.integration.app/docs/flow-instances

Re-fetches dependencies and recalculates dynamic fields for a Flow Instance. This ensures the instance is up-to-date with external data sources and schemas.

```javascript
await integrationApp
  .connection('hubspot')
  .flow('{FLOW_KEY}')
  .setup()
```

--------------------------------

### User Invited to Organization Payload Example

Source: https://docs.integration.app/docs/system-webhooks

Example JSON payload for the 'user-invited-to-org' webhook event, which is triggered when a user is invited to an organization workspace. It includes details about the invitation URL, issuer, user, and organization.

```JSON
{
  "type": "user-invited-to-org",
  "invitationUrl": "https://console.yourdomain.com/org-invitations/12345",
  "issuer": {
    "name": "John Admin",
    "email": "admin@company.com"
  },
  "user": {
    "email": "newuser@company.com"
  },
  "org": {
    "id": "org123",
    "name": "My Organization",
    "trialEndDate": "2025-05-16"
  }
}
```

--------------------------------

### GraphQL API Mapping Example

Source: https://docs.integration.app/docs/graphql-api-mapping

An example of a YAML file (`list.graphql.yml`) demonstrating how to define a GraphQL query, map variables, and specify response mapping.

```APIDOC
## GraphQL API Mapping

This documentation outlines the structure and usage of YAML files for mapping functions to GraphQL API endpoints.

### Method
This mapping is typically used with POST requests to a GraphQL endpoint, although the specific HTTP method depends on the GraphQL client implementation.

### Endpoint
The endpoint will be the URL of your GraphQL API.

### Request Body
The request body is defined by the `query` and `variables` fields in the YAML file.

```yaml
# list.graphql.yml
query: |
  query GetContacts($limit: Int, $cursor: String, $email: String) {
    contacts(first: $limit, after: $cursor, where: { email: $email }) {
      edges {
        node {
          id
          firstName
          lastName
          email
          phone
          createdAt
          updatedAt
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
variables:
  limit: 100
  cursor:
    $var: $.cursor
  email:
    $var: $.filter.email
responseMapping:
  records: 
    $var: response.data.contacts.edges[*].node
  cursor:
    $cond:
      - $var: response.data.contacts.pageInfo.hasNextPage
      - $var: response.data.contacts.pageInfo.endCursor
      - null
```

### Request Example
This is an illustrative example of how the YAML configuration might be used. The actual request sent to the GraphQL endpoint would be constructed based on this mapping.

```json
{
  "query": "query GetContacts($limit: Int, $cursor: String, $email: String) { contacts(first: $limit, after: $cursor, where: { email: $email }) { edges { node { id firstName lastName email phone createdAt updatedAt } } pageInfo { hasNextPage endCursor } } }",
  "variables": {
    "limit": 100,
    "cursor": "some_cursor_value",
    "email": "test@example.com"
  }
}
```

### Response
#### Success Response (200)

The response structure is determined by the `responseMapping` in the YAML file. It transforms the raw GraphQL response into a more usable format.

- **records** (array) - A list of contact records.
- **cursor** (string|null) - The cursor for pagination, or null if there is no next page.

#### Response Example

```json
{
  "records": [
    {
      "id": "contact-1",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "123-456-7890",
      "createdAt": "2023-01-01T10:00:00Z",
      "updatedAt": "2023-01-01T10:00:00Z"
    }
  ],
  "cursor": "next_cursor_value"
}
```

### YAML Specification

The GraphQL mapping specification includes:
* `query` – The GraphQL query or mutation string.
* `variables` – Variables mapping for the GraphQL query.
* `responseMapping` – Mapping to transform the GraphQL response.

### Available Variables

*   **function-specific input variables**: Described in each function's documentation.
*   **`credentials`**: Contains credentials from the current connection.
*   **`parameters`**: For data collection functions, contains combined function-level and collection-level parameters.
*   **`response`**: Available in `responseMapping`, with fields `data`, `errors`, and `extensions`.
```

--------------------------------

### Match Data Record Configuration Example

Source: https://docs.integration.app/docs/match-data-record

An example of how to configure the 'match-data-record' function type in YAML. This specific example demonstrates finding a contact by their email address, specifying the data source, lookup query, and field mapping for the imported value.

```yaml
name: Find Contact by Email
key: find-contact-by-email
inputSchema:
  type: object
  properties:
    email:
      type: string
type: match-data-record
config:
  dataSource:
    collectionKey: contacts
  lookup:
    query:
      email:
        $var: $.input.email
  fieldMapping:
    importValue:
      name:
        $var: $.fullName
      email:
        $var: $.primaryEmail
```

--------------------------------

### REST API Mapping Configuration Example (YAML)

Source: https://docs.integration.app/docs/rest-api-mapping

An example of a .rest.yml file used for REST API mapping. It defines the path, HTTP method, request mapping (query parameters), and response mapping for a GET request to retrieve contacts.

```yaml
# list.rest.yml
path: /contacts
method: GET
requestMapping:
  query:
    limit: 100
    offset: { $var: $.cursor }
    email: { $var: $.filter.email }
    first_name: { $var: $.filter.firstName }
    include_archived: { $var: $.parameters.includeArchived }
responseMapping:
  records: { $var: response.data.contacts }
  cursor: |
    {
      $cond: [
        { $var: response.data.hasMore },
        { $string: { $sum: [{ $number: { $var: $.cursor } }, 100] } },
        null
      ]
    }
```

--------------------------------

### List Method Configuration

Source: https://docs.integration.app/docs/data-collection-methods

Configuration example for the list method, specifying filterable fields and parameter schema.

```APIDOC
## List Method Configuration

### Description
Configuration for the list method, defining fields that can be used for filtering and the schema for additional parameters.

### Method
`list`

### Endpoint
N/A (Configuration)

### Parameters
#### Query Parameters
- `filterFields` (array): Fields that can be used for filtering of the results.
- `parametersSchema` (DataSchema): Schema for the additional parameters. Example:
```yaml
type: object
properties:
  includeArchived:
    type: boolean
    default: false
```
```

--------------------------------

### Setup or Refresh Data Source

Source: https://docs.integration.app/docs/data-source-instances

Sets up or refreshes a Data Source Instance. This operation is useful for ensuring the data source configuration is up-to-date or for re-initializing its state.

```javascript
await integrationApp
  .connection('hubspot')
  .dataSource('{DATA_SOURCE_KEY}')
  .setup()
```

--------------------------------

### Callback on Success

Source: https://docs.integration.app/docs/connection-ui-without-the-front-end-sdk

Example of a GET request to the redirect URI upon a successful connection. It includes the `connectionId` as a query parameter, which your backend can use to identify the established connection.

```http
GET https://your-backend.com/integration/callback?connectionId=abc123
```

--------------------------------

### Example Usage of Record From Fields

Source: https://docs.integration.app/docs/data-collection-record-from-fields

This example demonstrates the input and output of the `recordFromFields` method. It shows a sample input `fields` object and the resulting structured record object that includes the ID, original fields, computed name, URL, and raw metadata.

```javascript
// Input fields:
{
  "id": "123",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

// recordFromFields returns:
{
  "id": "123",
  "fields": {
    "id": "123",
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "name": "John Doe",
  "url": "https://app.example.com/contacts/123",
  "raw": {
    "source": "api",
    "version": "2.0"
  }
}
```

--------------------------------

### List Method Configuration (YAML)

Source: https://docs.integration.app/docs/data-collection-list

Configuration example for the 'list' method in YAML format, specifying filterable fields and request parameters schema.

```yaml
# spec.yml
name: Collection Name
methods:
  list:
    filterFields:
      - email
      - firstName
      - lastName
    parametersSchema:
      type: object
      properties:
        includeArchived:
          type: boolean
          default: false

```

--------------------------------

### Webhook Configuration Requirements

Source: https://docs.integration.app/docs/system-webhooks

Outlines the essential requirements and constraints for configuring system webhooks.

```APIDOC
## Webhook Configuration Requirements

  * **Admin Access** : Only platform administrators can create, modify, or delete webhooks
  * **Unique Types** : Only one webhook can be configured per event type
  * **HTTPS Required** : Webhook URLs should use HTTPS for security
  * **Response Timeout** : Webhook requests have a 30-second timeout
  * **Retry Policy** : Failed webhooks are not automatically retried
```

--------------------------------

### List Method Drilldowns

Source: https://docs.integration.app/docs/data-collection-methods

Explanation and examples of using drilldowns with the list method for fetching related data.

```APIDOC
## List Method Drilldowns

### Description
The `list` method supports drilldowns, enabling the fetching of nested or related data in conjunction with the primary list query. This is demonstrated with an example of fetching files from multiple folders.

### Method
`list` (with drilldowns)

### Endpoint
N/A (Conceptual, depends on drilldown implementation)

### Parameters for Drilldown Structure
- `parameters` (object): Parameters for the drilldown request (e.g., `{ recursive: true }`).
- `filter` (object): Filter criteria for the drilldown request (e.g., `{ type: 'file', parentFolderId: '123' }`).

### Drilldown Structure Example
```json
{
  "drilldowns": [
    {
      "parameters": { "recursive": true },
      "filter": {
        "type": "file",
        "parentFolderId": "123"
      }
    }
  ]
}
```

### JavaScript Implementation Example (Conceptual)
```javascript
// Example: Fetching files from folders
module.exports = async ({ filter, cursor, parameters, credentials, makeApiRequest }) => {
  if (!cursor && filter?.parentFolderId === "root") {
    // First, get all folders
    const folders = await makeApiRequest({
      method: "GET",
      path: "/api/folders",
      credentials,
    });

    // Return folders with drilldowns for their files
    return {
      records: folders.data,
      drilldowns: folders.data.map((folder) => ({
        parameters: { recursive: true },
        filter: {
          type: "file",
          parentFolderId: folder.id,
        },
      })),
    };
  }

  // Regular file listing
  const response = await makeApiRequest({
    method: "GET",
    path: "/api/files",
    query: { folderId: filter?.parentFolderId },
    credentials,
  });

  return {
    records: response.data,
  };
}
```
```

--------------------------------

### UDM Collection Mapping Example (YAML)

Source: https://docs.integration.app/docs/universal-data-models

An example demonstrating how to define Universal Data Model (UDM) collection mappings in a `udm.yml` file. This includes mapping fields from a collection to UDM fields using formulas and vice-versa.

```yaml
contacts:
  collectionMappings:
    - key: contacts
      fieldsFromCollection:
        id:
          $var: $.id
        fullName:
          $concat:
            values:
              - $var: $.firstName
              - $var: $.lastName
            delimiter: ' '
        firstName:
          $var: $.firstName
        lastName:
          $var: $.lastName
      fieldsToCollection:
        id:
          $var: $.id
        firstName:
          $var: $.firstName
        lastName:
          $var: $.lastName
```

--------------------------------

### GraphQL API Mapping Example

Source: https://docs.integration.app/docs/graphql-api-mapping

An example of a GraphQL API mapping configuration file (`.graphql.yml`). It defines a GraphQL query to fetch contacts, maps variables for the query, and specifies how to transform the response.

```yaml
# list.graphql.yml
query: |
  query GetContacts($limit: Int, $cursor: String, $email: String) {
    contacts(first: $limit, after: $cursor, where: { email: $email }) {
      edges {
        node {
          id
          firstName
          lastName
          email
          phone
          createdAt
          updatedAt
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
variables:
  limit: 100
  cursor:
    $var: $.cursor
  email:
    $var: $.filter.email
responseMapping:
  records:
    $var: response.data.contacts.edges[*].node
  cursor:
    $cond:
      - $var: response.data.contacts.pageInfo.hasNextPage
      - $var: response.data.contacts.pageInfo.endCursor
      - null

```

--------------------------------

### JavaScript Implementation for API Client

Source: https://docs.integration.app/docs/make-api-client

Use JavaScript or TypeScript for more complex API client configurations, allowing custom logic for request setup.

```APIDOC
## Configure API Client with JavaScript

### Description
This section outlines how to configure your API client using JavaScript or TypeScript. This method is suitable for complex scenarios where custom logic is needed to construct the REST API client instance, including setting the base URL, headers, and other request-specific details.

### Method
N/A (Configuration via JavaScript file)

### Endpoint
N/A (Configuration via JavaScript file)

### Parameters
#### JavaScript Export Function:
- The exported default function should accept an object with `credentials` as a property.
- It should return an object representing the `RestApiClient` instance with properties like `baseUrl` and `headers`.

### Request Example (JavaScript File)
```javascript
// File: auth/make-api-client.js
exports.makeApiClient = function({ credentials }) {
  return {
    baseUrl: 'https://api.example.com',
    headers: {
      'Authorization': `Bearer ${credentials.access_token}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
  };
};
```

### Request Example (spec.yml Configuration)
```yaml
auth:
  # ...other auth settings
  makeApiClient:
    implementationType: javascript
```

### Response
N/A (Configuration step, no direct response)

### Response Example
N/A
```

--------------------------------

### Flow Input Example (JSON)

Source: https://docs.integration.app/docs/flows

Illustrates the structure of input data for a node within a flow, including original flow input and outputs from previous nodes.

```json
{
  "...original flow input": "",
  "<previus-node-key>": "<previous node output>",
  "<another-previous-node-key>": "<another previous node output>"
}
```

--------------------------------

### Full Scan Configuration Example (YAML)

Source: https://docs.integration.app/docs/data-collection-events-full-scan

An example YAML configuration for a 'full-scan' implementation type in a collection's specification. It demonstrates how to define events for created, updated, and deleted records, including ignoring specific fields for update comparisons.

```yaml
# spec.yml
name: Collection Name
events:
  created:
    implementationType: full-scan
  updated:
    implementationType: full-scan
    ignoredFields:
      - lastViewedAt
      - downloadUrl
      - temporaryToken
  deleted:
    implementationType: full-scan

```

--------------------------------

### Initialize IntegrationAppProvider with Static Token

Source: https://docs.integration.app/docs/react

Wraps a part of your React application with IntegrationAppProvider, providing a static authentication token. This sets up the necessary context for integration-related components.

```jsx
import { IntegrationAppProvider } from '@membranehq/react'

export function MyApp() {
  return (
    <IntegrationAppProvider token='{TOKEN}'>
      <MyComponent />
    </IntegrationAppProvider>
  )
}
```

--------------------------------

### JavaScript API Request with Options Example

Source: https://docs.integration.app/docs/javascript

Demonstrates how to use the `options` parameter with API client methods, such as setting custom headers for JSON responses or specifying a stream response type for file downloads.

```javascript
// Get JSON response (default)
const jsonResponse = await apiClient.get('/items', {}, {
  headers: {
    'Accept': 'application/json'
  }
})

// Download file as stream
const fileResponse = await apiClient.get('/files/123', {}, {
  responseType: 'stream',
  returnFullResponse: true
})

```

--------------------------------

### Generate JWT Token in Python

Source: https://docs.integration.app/docs/getting-started

Generates a JWT authentication token using the PyJWT library. It includes customer ID, name, issuer, and expiration time. Ensure the PyJWT library is installed (`pip install PyJWT`).

```python
import jwt
import datetime

WORKSPACE_KEY = "f88f52bc-57a9-47e3-93b3-843fa0dd5708"
WORKSPACE_SECRET = "2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66"

encoded_jwt = jwt.encode(
    {
      # ID of your customer in your system.
      # It will be used to identify customer in Integration.app
      "id": "{CUSTOMER_ID}",
      # Human-readable name (it will simplify troubleshooting)
      "name": "{CUSTOMER_NAME}",
      "iss": WORKSPACE_KEY,
      # Any customer fields you want to attach to your user.
      "fields": {
        "field1": "<field value>"
      },
      "exp": datetime.datetime.now() + datetime.timedelta(seconds=1440)
    }, WORKSPACE_SECRET, algorithm="HS256")
```

--------------------------------

### Download Documentation with curl

Source: https://docs.integration.app/docs/initial-context-for-ai

This snippet shows how to use the `curl` command to download web pages, specifically for reading Membrane integration documentation.

```shell
curl https://docs.integration.app/llms.txt
```

--------------------------------

### Login to Helm Registry

Source: https://docs.integration.app/docs/helm

Logs into the Helm registry using provided username and password. This is the first step to access Membrane artifacts.

```shell
helm registry login harbor.integration.app \
  --username <helm-username> \
  --password <helm-password>
```

--------------------------------

### Webhook Configuration Example (YAML)

Source: https://docs.integration.app/docs/data-collection-events-webhook

This YAML configuration shows how to define webhook implementations for 'created', 'updated', and 'deleted' events in a collection.

```yaml
# spec.yml
name: Collection Name
events:
  created:
    implementationType: webhook
  updated:
    implementationType: webhook
  deleted:
    implementationType: webhook

```

--------------------------------

### GET /contacts

Source: https://docs.integration.app/docs/rest-api-mapping

Example of mapping a GET request to the /contacts endpoint, including query parameter mapping and response transformation.

```APIDOC
## GET /contacts

### Description
This endpoint retrieves a list of contacts with options for filtering and pagination.

### Method
GET

### Endpoint
/contacts

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of contacts to return.
- **offset** (integer) - Optional - The number of contacts to skip for pagination. Mapped from $.cursor.
- **email** (string) - Optional - Filters contacts by email address. Mapped from $.filter.email.
- **first_name** (string) - Optional - Filters contacts by first name. Mapped from $.filter.firstName.
- **include_archived** (boolean) - Optional - Whether to include archived contacts. Mapped from $.parameters.includeArchived.

### Request Example
```json
{
  "cursor": "",
  "filter": {
    "email": "test@example.com",
    "firstName": "John"
  },
  "parameters": {
    "includeArchived": true
  }
}
```

### Response
#### Success Response (200)
- **records** (array) - A list of contact objects. Mapped from response.data.contacts.
- **cursor** (string) - The cursor for the next page of results. Mapped using a conditional logic based on `response.data.hasMore`.

#### Response Example
```json
{
  "data": {
    "contacts": [
      {
        "id": "1",
        "firstName": "John",
        "email": "john@example.com"
      }
    ],
    "hasMore": true
  },
  "headers": {},
  "statusCode": 200
}
```
```

--------------------------------

### Webhook Management API Endpoints

Source: https://docs.integration.app/docs/system-webhooks

Provides a list of API endpoints for managing system webhooks.

```APIDOC
## Managing Webhooks

### API Endpoints:
  * `GET /webhooks` - List all webhooks
  * `POST /webhooks` - Create a new webhook
  * `GET /webhooks/:type` - Get webhook by type
  * `PATCH /webhooks/:type` - Update webhook
  * `DELETE /webhooks/:type` - Delete webhook

> **Note** : All webhook management operations require admin authentication via Auth0 JWT tokens.
```

--------------------------------

### Pull Integration App Helm Chart

Source: https://docs.integration.app/docs/helm

Pulls and unpacks the Integration.app Helm chart from the OCI registry. Requires specifying the desired chart version.

```shell
# See Versions section at the bottom of this page for available versions
helm pull oci://harbor.integration.app/helm/integration-app --version <version> --untar
```

--------------------------------

### Drilldown Structure Example (JSON)

Source: https://docs.integration.app/docs/data-collection-list

JSON structure illustrating how to define drilldowns for fetching related data, including parameters and filters for sub-requests.

```json
{
  "drilldowns": [
    {
      "parameters": { "recursive": true },
      "filter": {
        "type": "file",
        "parentFolderId": "123"
      }
    }
  ]
}

```

--------------------------------

### Membrane Configuration File

Source: https://docs.integration.app/docs/development-environment

Example of the `membrane.config.yml` file used to link a local development environment to a remote Membrane workspace. It includes workspace credentials and API URI.

```yaml
workspaceKey: <workspace-key>
workspaceSecret: <workspace-secret>
apiUri: <your base API url - if self-hosted>
testCustomerId: <your customer id for testing>
```

--------------------------------

### Organization Created Payload Example

Source: https://docs.integration.app/docs/system-webhooks

Example JSON payload for the 'org-created' webhook event, which fires when a new organization is created on the platform. It includes the organization's name, workspace name, ID, and creator's information.

```JSON
{
  "type": "org-created",
  "name": "New Organization",
  "workspaceName": "Main Workspace",
  "orgId": "org456",
  "org": {
    "id": "org456",
    "name": "New Organization",
    "domains": ["company.com"],
    "trialEndDate": "2025-05-23"
  },
  "user": {
    "name": "Creator User",
    "email": "creator@company.com"
  }
}
```

--------------------------------

### Organization Access Requested Payload Example

Source: https://docs.integration.app/docs/system-webhooks

Example JSON payload for the 'org-access-requested' webhook event, triggered when a user requests access to an organization based on their email domain. It contains user information and details about organization administrators.

```JSON
{
  "type": "org-access-requested",
  "user": {
    "id": "user123",
    "email": "employee@company.com",
    "name": "Jane Employee"
  },
  "orgAdmins": [
    {
      "email": "admin@company.com",
      "orgs": [
        {
          "id": "org123",
          "name": "My Organization"
        }
      ]
    }
  ]
}
```

--------------------------------

### Using Actions

Source: https://docs.integration.app/docs/actions

Explains how to run an action by providing input that matches its schema and the expected output.

```APIDOC
## Using Actions

To run an action, you need to provide an input that matches its `inputSchema`. As a result, you will get an output that matches its `outputSchema`.

All action runs are recorded as Action Run Logs.

See full API reference here: Actions API Reference.
```

--------------------------------

### JavaScript: Get Credentials from Connection Parameters

Source: https://docs.integration.app/docs/authentication-functions

This JavaScript function, getCredentialsFromConnectionParameters, takes connection parameters and uses them to make a POST request to an API to obtain an access token. It expects an 'email' and 'password' within connectionParameters and returns the 'accessToken'. Ensure axios is installed as a dependency.

```javascript
import axios from 'axios'

export default async function getCredentialsFromConnectionParameters({
  connectionParameters,
}) {
  const { email, password } = connectionParameters
  const res = await axios.post('https://api.example.com/v1/get-token', {
    email,
    password,
  })
  const accessToken = res.data?.access_token

  if (!accessToken) {
    throw new Error('Failed to get access token')
  }

  return { accessToken }
}
```

--------------------------------

### Upgrade Integration App Helm Chart

Source: https://docs.integration.app/docs/helm

Upgrades an existing installation of the Integration App Helm chart in the specified Kubernetes namespace.

```shell
helm upgrade integration-app ./path-to-this-folder --namespace <your-namespace>
```

--------------------------------

### Running a Tool/Action (JavaScript)

Source: https://docs.integration.app/docs/using-tools-from-external-apps

This JavaScript snippet shows how to execute a specific tool or action. It uses the integrationApp SDK to connect to a service (e.g., 'hubspot'), select an action by its key, and run it with provided input.

```javascript
await integrationApp
  .connection('hubspot')
  .action('{ACTION_KEY}')
  .run('{INPUT}')

```

--------------------------------

### Callback on Error

Source: https://docs.integration.app/docs/connection-ui-without-the-front-end-sdk

Example of a GET request to the redirect URI when an error occurs during the connection process. It includes an `error` message and `errorData` (JSON-encoded) as query parameters for debugging and handling the failure.

```http
GET https://your-backend.com/integration/callback?error=OAuth+failed&errorData=%7B...%7D
```

--------------------------------

### List Data Records Configuration Example - YAML

Source: https://docs.integration.app/docs/list-data-records

This YAML configuration demonstrates how to set up the 'list-data-records' function for listing tasks. It specifies the data source, field mappings for importing data, and optional filtering and pagination parameters.

```yaml
name: List Tasks
key: list-tasks
type: list-data-records
config:
  dataSource:
    collectionKey: tasks
  fieldMapping:
    importValue:
      title:
        $var: $.summary
      createdAt:
        $var: $.created
  # Optional: filtering and pagination
  filter:
    status: open
  unifiedFilter:
    assigneeId:
      $var: $.input.userId
  cursor:
    $var: $.input.cursor
```

--------------------------------

### YAML API Client Configuration

Source: https://docs.integration.app/docs/make-api-client

Configure your API client using a YAML mapping file for base URI and default headers. This is the recommended approach for most API clients.

```YAML
# File: auth/make-api-client.map.yml
baseUri: https://api.example.com
headers:
  Authorization:
    $concat:
        - "Bearer "
        - $var: credentials.access_token

```

```YAML
auth:
  # ...other auth settings
  makeApiClient:
    implementationType: mapping

```

--------------------------------

### Generate JWT Token in PHP

Source: https://docs.integration.app/docs/getting-started

Generates a JWT authentication token using the Firebase JWT library. It includes customer ID, name, issuer, and expiration time. Ensure the Firebase JWT library is included in your project.

```php
use FirebaseJWTJWT;

// Your workspace key and secret.
// You can find them on the Settings page.
$secret = '2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66';
$key = 'f88f52bc-57a9-47e3-93b3-843fa0dd5708';

$payload = [
    'id' => "{CUSTOMER_ID}",  // ID of your customer in your system. It will be used to identify customer in Integration.app
    'name' => "{CUSTOMER_NAME}", // Human-readable customer name (it will simplify troubleshooting)
    'iss' => $key,
    'exp' => time() + 60 * 60 * 24 * 60, // To prevent token from being used for too long
];
$token = JWT::encode($payload, $secret, 'HS256');
```

--------------------------------

### Node.js Webhook Signature Verification

Source: https://docs.integration.app/docs/system-webhooks

Example Node.js function to verify the HMAC-SHA256 signature of incoming webhook payloads. It requires the payload, the signature from the header, and the webhook secret. The function updates the HMAC with the stringified payload and compares it to the provided signature.

```JavaScript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === expectedSignature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const isValid = verifyWebhook(req.body, signature, 'your-webhook-secret');

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook payload
  res.status(200).send('OK');
});
```

--------------------------------

### Generate JWT Authentication Token in JavaScript

Source: https://docs.integration.app/docs/getting-started

This JavaScript snippet demonstrates how to generate a JWT (JSON Web Token) for authenticating with Membrane. It requires your workspace key and secret, customer information, and specifies token options like expiration and signing algorithm. The generated token is used to authorize interactions with Membrane's API.

```javascript
import jwt from "jsonwebtoken"
// Your workspace key and secret.
// You can find them on the Settings page.
const WORKSPACE_KEY = "<WORKSPACE_KEY>"
const WORKSPACE_SECRET = "<WORKSPACE_SECRET>"

const tokenData = {
  // Identifier of your customer (user, team, or organization).
  id: "{CUSTOMER_ID}",
  // Human-readable customer name.
  name: "{CUSTOMER_NAME}",
  // (optional) Any user fields you want to attach to your customer.
  fields: {
    userField: "<user field value>",
  },
}

const options = {
  issuer: WORKSPACE_KEY,
  // To prevent token from being used for too long
  expiresIn: 7200,
  // HS256 signing algorithm is used by default,
  // but we recommend to go with more secure option like HS512.
  algorithm: "HS512",
}

const token = jwt.sign(tokenData, WORKSPACE_SECRET, options)

```
Tokens:
Raw