Reading and Writing Data Using the Pipefy API

Hey there, fellow JavaScript devs! Ready to dive into the world of Pipefy API integration? Let's get our hands dirty with some data syncing magic for user-facing integrations. Buckle up!

Setting Up the Pipefy API Client

First things first, let's get that API client up and running. It's as easy as pie:

npm install pipefy-api-client

Now, let's configure our client:

import { PipefyClient } from 'pipefy-api-client';

const client = new PipefyClient({
  apiKey: 'your-api-key-here'
});

Pro tip: Keep that API key safe! Use environment variables or a secure key management system.

Reading Data from Pipefy

Time to fetch some data! Let's grab some cards from a pipe:

async function getCards(pipeId) {
  const query = `
    {
      pipe(id: ${pipeId}) {
        cards {
          edges {
            node {
              id
              title
              fields {
                name
                value
              }
            }
          }
        }
      }
    }
  `;
  
  const response = await client.query(query);
  return response.data.pipe.cards.edges.map(edge => edge.node);
}

Easy peasy, right? Now you've got your cards, complete with all their juicy field data.

Writing Data to Pipefy

Creating and updating cards is where the real fun begins. Check this out:

async function createCard(pipeId, cardData) {
  const mutation = `
    mutation {
      createCard(input: {
        pipe_id: ${pipeId}
        title: "${cardData.title}"
        fields_attributes: [
          { field_id: "field_id_1", value: "${cardData.field1}" },
          { field_id: "field_id_2", value: "${cardData.field2}" }
        ]
      }) {
        card {
          id
        }
      }
    }
  `;
  
  const response = await client.query(mutation);
  return response.data.createCard.card.id;
}

Boom! New card created. Updating is just as straightforward – swap out createCard for updateCard and you're golden.

Implementing Real-time Data Sync

Real-time sync? We've got you covered. Set up a webhook to catch those Pipefy changes:

import express from 'express';

const app = express();

app.post('/webhook', express.json(), (req, res) => {
  const { action, card } = req.body;
  
  if (action === 'card.create' || action === 'card.update') {
    // Sync the card data to your system
    syncCard(card);
  }
  
  res.sendStatus(200);
});

function syncCard(card) {
  // Your sync logic here
  console.log(`Syncing card ${card.id}`);
}

app.listen(3000, () => console.log('Webhook server running'));

Now you're catching those changes like a pro!

Error Handling and Rate Limiting

Don't let those pesky errors catch you off guard. Wrap your API calls in some error handling goodness:

async function safeApiCall(apiFunction) {
  try {
    return await apiFunction();
  } catch (error) {
    if (error.response && error.response.status === 429) {
      // Handle rate limiting
      console.log('Rate limited. Retrying in 60 seconds...');
      await new Promise(resolve => setTimeout(resolve, 60000));
      return safeApiCall(apiFunction);
    }
    throw error;
  }
}

Use this wrapper around your API calls to handle rate limits like a champ.

Optimizing Performance

Want to speed things up? Batch those requests, baby!

async function batchUpdateCards(cards) {
  const mutations = cards.map(card => `
    updateCard${card.id}: updateCard(input: {
      id: ${card.id}
      title: "${card.title}"
    }) {
      card { id }
    }
  `).join('\n');

  const query = `mutation { ${mutations} }`;
  return await client.query(query);
}

Now you're updating multiple cards in one go. Efficiency at its finest!

Security Considerations

Remember, with great power comes great responsibility. Always validate and sanitize your data:

function sanitizeInput(input) {
  return input.replace(/[<>&'"]/g, char => {
    switch (char) {
      case '<': return '&lt;';
      case '>': return '&gt;';
      case '&': return '&amp;';
      case "'": return '&#39;';
      case '"': return '&quot;';
    }
  });
}

Use this before sending any user input to Pipefy. Better safe than sorry!

Testing and Debugging

Last but not least, always test your integrations. Here's a quick unit test to get you started:

import { jest } from '@jest/globals';
import { PipefyClient } from 'pipefy-api-client';

jest.mock('pipefy-api-client');

test('getCards fetches cards correctly', async () => {
  const mockQuery = jest.fn().mockResolvedValue({
    data: {
      pipe: {
        cards: {
          edges: [
            { node: { id: '1', title: 'Test Card' } }
          ]
        }
      }
    }
  });

  PipefyClient.mockImplementation(() => ({
    query: mockQuery
  }));

  const cards = await getCards(123);

  expect(mockQuery).toHaveBeenCalled();
  expect(cards).toHaveLength(1);
  expect(cards[0].title).toBe('Test Card');
});

And there you have it! You're now equipped to build some killer Pipefy integrations. Remember, practice makes perfect, so get out there and start coding. Happy integrating!