Client SDK

The Client SDK provides a streamlined way to connect your application with Buildel. It simplifies authentication, websocket connections, and workflow execution. The SDK is designed to facilitate real-time interactions and structured event handling.

Installation

Begin by installing the necessary Buildel packages using npm. This initial step equips you with the tools required for seamless integration with our API.

npm

npm install @buildel/buildel @buildel/buildel-auth

yarn

yarn add @buildel/buildel @buildel/buildel-auth

pnpm

pnpm install @buildel/buildel @buildel/buildel-auth

Server side configuration

To authenticate with our API via the SDK, it’s essential to secure your socket connection at the backend. Our @buildel/buildel-auth package simplifies this process.

Set up an HTTP endpoint on your server and use the API key to hash your socket connection.

Next.js

index.tsx

import { BuildelAuth } from "@buildel/buildel-auth";

export async function POST(request: Request) {
  const { socket_id: socketId, channel_name: channelName } = await request.json();

  const buildelAuth = new BuildelAuth(process.env.BUILDEL_API_KEY);

  const authData = buildelAuth.generateAuth(socketId, channelName);

  return NextResponse.json(authData);
}

Remix

index.tsx

import { BuildelAuth } from "@buildel/buildel-auth"

export async function action({ request }: ActionFunctionArgs) {
  const body = await request.formData();
  const socketId = body.get("socketId") as string;
  const channelName = body.get("channelName") as string;

  const buildelAuth = new BuildelAuth(process.env.BUILDEL_API_KEY);

  const authData = buildelAuth.generateAuth(socketId, channelName);

  return json({ authData });
}

Initialize client SDK

Initiate the client SDK with your organization's identifier to validate your credentials. This establishes your organization's identity within the SDK's scope.

Behind the scenes, the SDK will query an endpoint at the specified address (step 2) to retrieve the hashed credentials required for a secure websocket connection.

index.tsx

import { BuildelSocket } from "@buildel/buildel";

// 2 is an identifier of your organization
const buildel = new BuildelSocket(2, { authUrl: '/your-api/auth-endpoint' });

Connect websockets

Establish a connection to our websocket server to engage in real-time bidirectional communication. This connection is vital for real-time messaging and data interchange.

index.tsx

await buildel.connect();

Initialize run instance

Initialize a run instance with your workflow ID to manage events for specific blocks, handle errors, and perform other workflow operations.

index.tsx

// 591 is an identifier of your workflow

const run = buildel.run(591, {
  onBlockOutput: ( blockId: string, outputName: string, payload: unknown) => {
    console.log(`Output from block ${blockId}, output ${outputName}:`, payload);
  },
  onBlockStatusChange: (blockId: string, isWorking: boolean) => {
    console.log(`Block ${blockId} is ${isWorking ? "working" : "stopped"}`);
  },
  onStatusChange: (status: BuildelRunStatus) => {
    console.log(`Status changed: ${status}`);
  },
  onBlockError: (blockId: string, errors: string[]) => {
    console.log(`Block ${blockId} errors: ${errors}`);
  }
})

Send data to channel

After starting your run instance, send data payloads to a specified block in your channel. This action triggers the processing within your run.

index.tsx

await run.start()
run.push("your_block_name:input", 'sample payload');

Close connection

When your interactions with the API conclude, ensure you properly close the socket connection. This step is critical for releasing resources and securely disconnecting from the server.

index.tsx

await buildel.disconnect();