Use the Flowcore TypeScript SDK

@flowcore/sdk provides a typed command interface for Flowcore v2 services. It supports Node.js and Deno and covers platform resources, ingestion, event queries, IAM, credentials, secrets, Data Pathways, and additional service domains.

Use the SDK when your TypeScript application needs direct control over a Flowcore operation. Use @flowcore/pathways when you want event contracts, handlers, and processing runtime behavior built around the same application builder.

Install the SDK

npm install @flowcore/sdk

Import from the public package entry point:

import {
  FlowcoreClient,
  DataCoreFetchCommand,
} from "@flowcore/sdk"

Do not import internal source paths. Public command exports can evolve while internal directory structure is not an application contract.

Pin the package through your lockfile and review release notes before upgrades. Flowcore v2 command coverage and service behavior continue to replace older GraphQL surfaces.

Create an API-key client

Most current REST operations support application API keys when IAM grants the required action:

import { FlowcoreClient } from "@flowcore/sdk"
 
const client = new FlowcoreClient({
  apiKey: process.env.FLOWCORE_API_KEY!,
})

Create one key per service and environment. Keep it on the server, store it in a secret manager, and avoid logging the value or embedding it in a browser bundle.

An API key is not automatically authorized for every tenant resource. The associated roles, policies, and bindings determine what the command may do.

Create a bearer-token client

Some administrative, GraphQL-backed, and AI Agent Coordinator operations require an OAuth bearer token:

const userClient = new FlowcoreClient({
  getBearerToken: async () => {
    return getCurrentFlowcoreAccessToken()
  },
})

The callback lets the client obtain a current token instead of retaining one hard-coded value indefinitely.

Use bearer authentication for user-scoped tools and operations that explicitly require it. Do not substitute a service API key when the command only allows bearer mode, and do not copy a user's token into a background service.

Choose authentication per command family

The SDK command defines its allowed authentication modes.

Typical patterns are:

• GraphQL compatibility commands: bearer token
• AI Agent Coordinator and its streaming operations: bearer token
• Most current REST resource commands: API key when permitted
• Ingestion: API key, with the SDK handling ingestion-specific authorization behavior
• Data Pathway control-plane administration: often bearer token
• Data Pathway worker operations: API key

When one command succeeds and another returns 401 or 403, compare their authentication and IAM requirements before changing credentials.

Understand the command model

Every operation is represented by a typed Command<Input, Output>.

A command owns:

• Allowed authentication modes
• Service base URL
• HTTP method and path
• Request headers and body
• Response parsing
• Domain output type
• Command-specific failure behavior

Execute it through a client:

const dataCore = await client.execute(
  new DataCoreFetchCommand({
    tenant: "acme-production",
    dataCore: "commerce",
  }),
)

The input is checked by TypeScript, and the result has the command's output type. The client adds authentication, executes the request, applies retry behavior, and returns the parsed output.

Let commands select service endpoints

Flowcore v2 is composed of domain-specific services. The command knows which service it targets.

For example:

• GraphQL commands use the GraphQL service and bearer authentication.
• Ingestion commands use the webhook ingestion service.
• Data-core, IAM, event-query, and Data Pathway commands use their corresponding service hosts.

Prefer official commands over manually concatenating internal URLs. The SDK keeps endpoint, authentication, path, and response behavior together.

For a dedicated installation, use the package and environment configuration recommended by its platform operator.

Configure retries

The client defaults to a 250 ms delay and three attempts. Configure the behavior when your operation needs a different policy:

const client = new FlowcoreClient({
  apiKey: process.env.FLOWCORE_API_KEY!,
  retry: {
    delay: 500,
    maxRetries: 5,
  },
})

Disable SDK retries when the caller owns the complete retry strategy:

const client = new FlowcoreClient({
  apiKey: process.env.FLOWCORE_API_KEY!,
  retry: null,
})

Retries are not automatically safe for every business workflow. A request can succeed remotely while the response is lost.

For create or ingestion operations, design idempotency at the domain boundary. Do not assume a timeout means nothing changed.

Add application-level timeouts

Retries control repeated attempts; they do not replace an overall deadline.

A user-facing request should have a bounded total duration. A background provisioning job can tolerate a longer window but still needs cancellation and visibility.

Wrap critical operations with the application's timeout and circuit-breaker policy. Avoid stacking many retry layers whose combined delay exceeds the caller's deadline.

Handle SDK error types

The SDK exposes two important error categories:

• ClientError represents transport or HTTP failures and includes status and response details.
• CommandError represents domain-specific command logic failures.

A general handling pattern is:

try {
  return await client.execute(command)
} catch (error) {
  if (error instanceof ClientError) {
    logger.error("Flowcore request failed", {
      status: error.status,
      operation: command.constructor.name,
    })
    throw mapFlowcoreHttpError(error)
  }
 
  if (error instanceof CommandError) {
    logger.error("Flowcore command failed", {
      operation: command.constructor.name,
      message: error.message,
    })
    throw error
  }
 
  throw error
}

Use the actual exported error fields from the installed SDK version. Keep logs focused on operation, status, resource identity, and correlation details rather than credentials or full sensitive responses.

Classify failures before retrying

Treat most client errors by category:

• 400 or 422: invalid input or contract; correct the request
• 401: missing, expired, or unsupported authentication
• 403: authenticated identity lacks permission
• 404: wrong resource, tenant scope, or endpoint
• 409: lifecycle or state conflict
• 429: throttling; retry according to server guidance and idempotency
• 5xx: service failure; bounded retry may be appropriate
• Network timeout: outcome can be uncertain; retry only with safe operation identity

A 403 does not become valid after immediate retry. A 422 does not need exponential backoff. Classifying errors prevents retry storms and makes alerts actionable.

Reuse clients appropriately

Create a client per authentication and environment configuration, then reuse it for related calls. Avoid constructing a new client and reading secrets for every loop iteration.

Do not share one mutable global client across tenants if its token callback or endpoint configuration can change unexpectedly. Make environment and identity explicit at the dependency boundary.

Keep SDK calls on trusted servers

The SDK can technically run in several JavaScript environments, but privileged Flowcore operations should execute in trusted backend code.

A browser application must not receive a platform API key. Place resource management, event queries with sensitive-data access, and pathway administration behind an authenticated application API that applies user authorization.

Test command wrappers

Wrap SDK commands in small domain services rather than spreading them through route handlers:

export class CommerceFlowcore {
  constructor(private readonly client: FlowcoreClient) {}
 
  async fetchDataCore() {
    return this.client.execute(
      new DataCoreFetchCommand({
        tenant: "acme-production",
        dataCore: "commerce",
      }),
    )
  }
}

This gives tests one boundary for command construction, error mapping, retry expectations, and audit logging.

Continue with Use SDK command families for resource, ingestion, query, and Data Pathway examples.