Skip to main content

Node SDK

The official TypeScript SDK for FluidGrids provides programmatic access to workflows, runs, nodes, credentials, and more.

Install​

@fluidgrids/sdk is not published to npm yet. Until it is, build it from source and reference the build from your project:

git clone https://github.com/algoshred/fluidgrids-sdk-node.git
cd fluidgrids-sdk-node
bun install
bun run build          # emits dist/

# in your project
npm install ../fluidgrids-sdk-node      # or: bun add ../fluidgrids-sdk-node

Once published, the install becomes npm install @fluidgrids/sdk.

Environment selection​

The SDK endpoint defaults to production. Pass the appropriate endpoint in createClient:

EnvironmentEndpoint
prod (default)https://graphqlworkspaces.burdenoff.com/workspaces/graphql
alphahttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql
localhttp://localhost:4003/workspaces/graphql

The endpoint comes from the baseUrl argument to createClient, or from the FLUIDGRIDS_ENDPOINT / FLUIDGRIDS_WORKSPACE_ENDPOINT environment variables (the BURDENOFF_ENDPOINT / BURDENOFF_WORKSPACE_ENDPOINT aliases also work). BURDENOFF_ENV is read only by the browser and VS Code extensions, not by this SDK.

Quick start​

import { createClient } from "@fluidgrids/sdk";

const client = createClient({
  baseUrl: "https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
  token: "your-jwt-token",
});

// List workflows
const workflows = await client.workflows.list();
console.log(workflows.items);

// Trigger a workflow
const result = await client.workflows.triggerByKey("my-workflow", undefined, {
  inputData: { name: "John" },
});
console.log("Run started:", result.runId);

Authentication​

const client = createClient({
  baseUrl: "https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
  token: "your-jwt-token",
});

API Key​

const client = createClient({
  baseUrl: "https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
  apiKey: "your-api-key",
});

Username & Password​

const client = createClient({
  baseUrl: "https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
});

const { user, tokens } = await client.signIn("username", "password");

Dynamic Token Update​

client.setToken("new-token");
client.setApiKey("new-api-key");
client.clearAuth();

Resources​

Workflows​

const workflows = await client.workflows.list({
  limit: 10,
  status: "published",
});
const workflow = await client.workflows.getById("workflow-id");
const workflowByKey = await client.workflows.getByKey("my-workflow", "v1.0.0");
const newWorkflow = await client.workflows.create({
  name: "My Workflow",
  description: "A test workflow",
  tags: ["test"],
});
await client.workflows.update("workflow-id", {
  description: "Updated description",
});
await client.workflows.delete("workflow-id");
const result = await client.workflows.triggerById("workflow-id", {
  inputData: { key: "value" },
  async: true,
});
await client.workflows.publish("workflow-id", "Release notes");
const copy = await client.workflows.duplicate(
  "workflow-id",
  "Copy of Workflow",
);

Runs​

const runs = await client.runs.list({
  workflowKey: "my-workflow",
  status: "completed",
  limit: 20,
});
const run = await client.runs.get("run-id");
const logs = await client.runs.getLogs("run-id", { level: "error" });
await client.runs.cancel("run-id");
await client.runs.pause("run-id");
await client.runs.resume("run-id");
await client.runs.retry("run-id");
const completedRun = await client.runs.waitForCompletion("run-id", {
  pollInterval: 1000,
  timeout: 60000,
});

Nodes​

const nodes = await client.nodes.list({ category: "Integrations" });
const node = await client.nodes.get("node-id");
const categories = await client.nodes.listCategories();
const results = await client.nodes.search("http");

Credentials​

const credentials = await client.credentials.list();
const credential = await client.credentials.get("credential-id");
const types = await client.credentials.listTypes();
const newCredential = await client.credentials.create({
  name: "My API Key",
  type: "api_key",
  data: { apiKey: "secret" },
});
await client.credentials.update("credential-id", { name: "Updated Name" });
const result = await client.credentials.test("credential-id");
await client.credentials.delete("credential-id");

Webhooks​

const webhooks = await client.webhooks.list({ workflowId: "workflow-id" });
const webhook = await client.webhooks.create({
  name: "My Webhook",
  workflowId: "workflow-id",
  method: "POST",
});
await client.webhooks.activate("webhook-id");
await client.webhooks.deactivate("webhook-id");
await client.webhooks.delete("webhook-id");

Scheduled Jobs​

const jobs = await client.scheduledJobs.list();
const job = await client.scheduledJobs.create({
  name: "Daily Report",
  workflowId: "workflow-id",
  cronExpression: "0 9 * * *",
  timezone: "America/New_York",
});
await client.scheduledJobs.pause("job-id");
await client.scheduledJobs.resume("job-id");
await client.scheduledJobs.delete("job-id");

Dashboard​

const stats = await client.dashboard.getStats("7d");
const last24h = await client.dashboard.getLast24Hours();
const last7d = await client.dashboard.getLast7Days();
const last30d = await client.dashboard.getLast30Days();
const results = await client.search.query("email notification");
const workflows = await client.search.searchWorkflows("email");
const nodes = await client.search.searchNodes("http");

Raw GraphQL​

const result = await client.query<{ myQuery: MyType }>(
  `query MyQuery($id: ID!) { myQuery(id: $id) { id name } }`,
  { id: "123" },
);

const result = await client.mutate<{ myMutation: MyType }>(
  `mutation MyMutation($input: MyInput!) { myMutation(input: $input) { id } }`,
  { input: { name: "test" } },
);

Error Handling​

try {
  await client.workflows.getById("non-existent");
} catch (error) {
  if (error instanceof Error) {
    console.error("Error:", error.message);
  }
}

Development​

git clone https://github.com/algoshred/fluidgrids-sdk-node.git
cd fluidgrids-sdk-node
bun install
bun run dev          # Watch mode
bun run build        # Production build
bun run test         # Run tests
bun run sanity       # All checks (format, lint, type-check, test, build)

Source​

  • Repository: github.com/algoshred/fluidgrids-sdk-node
  • Package: @fluidgrids/sdk on npm

Next steps​