Skip to main content

Interfaces

tip

We highly recommend getting familiar with Client SDK API before start

Installation​

Begin by installing the necessary Buildel packages using package manager of your choice.

This initial step equips you with the tools required for seamless integration with our API.

~ terminal
npm install @buildel/buildel @buildel/buildel-auth

Server-side configuration​

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);
}

Initialize client SDK​

BuildelSocket.tsx
export const BuildelProvider = ({ children }: PropsWithChildren) => {
  useEffect(() => {
      async function connect() {
          const organizationId = 27;
          const authUrl = "/buildel/auth";
          const buildel = new BuildelSocket(organizationId, { authUrl });
      }
  }, [])
}

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.

BuildelSocket.tsx
export const BuildelProvider = ({ children }: PropsWithChildren) => {
    const [buildel, setBuildel] = useState<BuildelSocket | null>(null);

    useEffect(() => {
        const connect = async () => {
            const organizationId = 27;
            const authUrl = "/buildel/auth";
            const buildel = new BuildelSocket(organizationId, { authUrl });

            await buildel.connect();

            setBuildel(buildel);
        }

        connect();

        return () => {
            if (!buildel) return;
            buildel!.disconnect().then(() => {
              console.log("Disconnected from Buildel");
            });
        };
    }, [])
}

Initialize run instance​

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

BuildelSocket.tsx
interface UsePipelineRunProps {
    onBlockOutput?: (
        blockId: string,
        outputName: string,
        payload: unknown
    ) => void;
    onBlockStatusChange?: (blockId: string, isWorking: boolean) => void;
    workflowId: number;
}

export const usePipelineRun = ({ workflowId, onBlockOutput, onBlockStatusChange }: UsePipelineRunProps) => {
    const { buildel } = useBuildelSocket();
    const runRef = useRef<BuildelRun>();

    useEffect(() => {
        if (!buildel) return;

        const run = buildel.run(workflowId, {
            onBlockOutput: (
                blockId: string,
                outputName: string,
                payload: unknown
            ) => {
                onBlockOutput?.(blockId, outputName, payload);
            },
            onBlockStatusChange: (blockId: string, isWorking: boolean) => {
                onBlockStatusChange?.(blockId, isWorking);
            },
            onStatusChange: (status: BuildelRunStatus) => {
                setStatus(status);
            },
            onBlockError: (blockId: string, errors: string[]) => {
                console.log(`Block ${blockId} errors: ${errors}`);
            },
        });

        runRef.current = run;
    }, [buildel]);
}

export function useBuildelSocket() {
  const context = useContext(BuildelContext);

  if (!context) {
    throw new Error("useBuildelSocket must be used within a BuildelProvider");
  }

  return context;
}

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.

BuildelSocket.tsx
await run.start();
run.push('topic:input', 'sample payload')

Options​

topic: string​

This is a combination of blockName and fieldName separated by a colon. In this example: text_input_1:input, text_input_1 refers to name of block you want to send payload to and input is name of field within this block.

payload: any​

Payload can be anything from string to complex object or even array of object. You name it.

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.

BuildelSocket.tsx
useEffect(() => {
  // ...
  return () => {
      await buildel.disconnect();
  }
})