Skip to content

javascript.md

Latest commit

 

History

History
304 lines (229 loc) · 7.33 KB

javascript.md

File metadata and controls

304 lines (229 loc) · 7.33 KB

Use the JavaScript SDK

Manage Ascend workspaces, deployments, flows, and flow runs from JavaScript/TypeScript.

Install

npm add ascend-tools

Upgrade to the latest version:

npm update ascend-tools

CLI

The npm package includes the full ascend-tools CLI:

npx ascend-tools workspace list
npx ascend-tools flow run "My Flow" --workspace "My Workspace"
npx ascend-tools otto tui

Or install globally:

npm install -g ascend-tools
ascend-tools workspace list

See CLI guide for all commands.

Authenticate

From instance config (recommended)

import { Client } from "ascend-tools";

const client = new Client();                            // uses default instance from ~/.ascend-tools/config.toml
const client = new Client(null, null, null, "staging"); // uses a named instance

Set up instances with the CLI: ascend-tools instance add (see CLI guide).

From environment variables

const client = new Client(); // reads ASCEND_SERVICE_ACCOUNT_ID, etc. from env

See Quickstart for the full service account creation walkthrough.

With explicit credentials

const client = new Client(
  "asc-sa-...",                      // serviceAccountId
  "...",                              // serviceAccountKey
  "https://api.instance.ascend.io",   // instanceApiUrl
);

Resolution order: explicit args > instance config > env vars.

Environments and projects

List environments

const environments = await client.listEnvironments();

Get an environment by title

const env = await client.getEnvironment("Production");

List projects

const projects = await client.listProjects();

Get a project by title

const project = await client.getProject("My Project");

List profiles

const profiles = await client.listProfiles("My Workspace");
const profiles = await client.listProfiles(null, "My Deployment");
const profiles = await client.listProfiles(null, null, null, "My Project", "main");

Manage workspaces and deployments

Workspaces

await client.listWorkspaces();
await client.listWorkspaces(null, null, "Production");
await client.getWorkspace("My Workspace");
await client.pauseWorkspace("My Workspace");
await client.resumeWorkspace("My Workspace");
await client.deleteWorkspace("My Workspace");

Create a workspace

const ws = await client.createWorkspace(
  "My Workspace",   // title
  "Production",     // environment
  "My Project",     // project
  "default",        // profile
  "main",           // gitBranch
);

Update a workspace

const ws = await client.updateWorkspace(
  "My Workspace",   // title
  null,              // uuid
  "New Title",       // newTitle
  "feature/abc",     // gitBranch
);

Deployments

await client.listDeployments();
await client.getDeployment("My Deployment");
await client.pauseDeploymentAutomations("My Deployment");
await client.resumeDeploymentAutomations("My Deployment");
await client.deleteDeployment("My Deployment");

Create a deployment

const dep = await client.createDeployment(
  "My Deployment",   // title
  "Production",      // environment
  "My Project",      // project
  "default",         // profile
  "main",            // gitBranch
);

Update a deployment

const dep = await client.updateDeployment(
  "My Deployment",   // title
  null,              // uuid
  null,              // newTitle
  null,              // gitBranch
  null,              // gitBranchBase
  null,              // profile
  null,              // size
  null,              // storageSize
  true,              // enableAutomations
);

Manage flows

List flows

const flows = await client.listFlows("My Workspace");
const flows = await client.listFlows(null, "My Deployment");

Run a flow

const result = await client.runFlow("sales", "My Workspace");

Resume a paused workspace before running:

const result = await client.runFlow(
  "sales",           // flow
  "My Workspace",    // workspace
  null,              // deployment
  null,              // uuid
  null,              // spec
  true,              // resume
);

Pass a spec object for advanced options:

const result = await client.runFlow(
  "sales",           // flow
  "My Workspace",    // workspace
  null,              // deployment
  null,              // uuid
  { full_refresh: true },  // spec
);

Flow run spec options

Field Type Description
full_refresh bool Drop all internal data and recompute from scratch. Destructive.
components list Run only these components (by name). Omit to run all.
component_categories list Run only components in these categories.
parameters object Custom parameters passed to the flow.
run_tests bool Run tests after processing data. Defaults to true.
store_test_results bool Store test results.
halt_flow_on_error bool Stop the flow on error.
disable_optimizers bool Disable optimizers.
update_materialization_type bool Update component materialization types. May drop data.
deep_data_pruning bool Full table scan for Smart Table data maintenance.
backfill_missing_statistics bool Backfill statistics for data blocks without them.
disable_incremental_metadata_collection bool Disable incremental read/transform metadata collection.
runner_overrides object Runner config overrides (e.g., {"size": "Medium"}).

Monitor flow runs

List flow runs

const result = await client.listFlowRuns("My Workspace");
const runs = result.items;         // array
const truncated = result.truncated; // bool

Filter by status, flow name, time range, or paginate:

await client.listFlowRuns("My Workspace", null, null, "running");
await client.listFlowRuns(null, "My Deployment", null, null, "sales", null, null, null, 10);
await client.listFlowRuns("My Workspace", null, null, null, null, "2025-01-01T00:00:00Z");

Get a flow run

const run = await client.getFlowRun("fr-...", "My Workspace");

Otto (AI assistant)

// List providers and models
const providers = await client.listOttoProviders();

// Chat
const response = await client.otto("What flows are running?");
const response = await client.otto("Describe the sales flow", "My Workspace");

Streaming

const response = await client.ottoStreaming(
  "Describe the sales flow",
  (err, delta) => {
    if (err) console.error(err);
    else process.stdout.write(delta);
  },
  "My Workspace",
);

Return types

  • All methods are async (return Promises)
  • All methods return plain objects or arrays
  • TypeScript type definitions are included (index.d.cts)

Error handling

The SDK throws errors for:

  • Missing configuration (environment variables not set)
  • Authentication failures (invalid or expired key)
  • HTTP errors (API returns non-2xx status)
  • State errors (paused, starting, error state)
try {
  await client.runFlow("sales", "My Workspace");
} catch (e) {
  console.error(`Error: ${e.message}`);
}