Quickstart

Welcome to Lume—the easiest way to automate your data transformations. Lume uses AI to infer how your source data maps to a target schema, generating code so you don’t have to. This guide will help you get started quickly using our TypeScript SDK.

Installing the Lume SDK

npm install @lume-ai/typescript-sdk

Initialize the SDK

import { Lume } from "@lume-ai/typescript-sdk";

const lume = new Lume("YOUR_API_KEY_HERE");

1. Create & Run a Flow

We are ingesting data from an API and want to normalize each record to our own internal schema. The data in question contains information about our users. The API gives us the following source data:

data.json

[
    {
        "name": "Barry Devlin",
        "nickname": "Baz",
        "years_old": 42
    },
    {
        "name": "Paul Murphy",
        "nickname": "Polly",
        "years_old": 37
    }
]

You want these fields to match your internal schema, which might look like this:

schema.json

{
    "type": "object"
    "properties": {
        "first_name": {
            "description": "The first name of the user.",
            "type": "string"
        },
        "last_name": {
            "description": "The last name of the user.",
            "type": "string"
        },
        "age": {
            "description": "The age of the user in years.",
            "type": "integer"
        }
    },
    "required": [
        "first_name",
        "last_name",
        "age",
    ]
}

All we need to do is create a flow with our target schema and run it with our source data to retrieve the transformed data:

// 1) Create a flow with the target schema
// 2) Immediately run source data through it
// 3) Wait for completion so we can fetch the results in one call
const flow = await lume.flowService.createAndRunFlow(
  {
    name: "my_flow",
    description: "Process customer data",
    target_schema: schema,
    tags: ["customers"]
  },
  {
    source_data: data
  },
  true // Wait for run to finish before returning
);

// When finished, we can fetch the results from the latest run:
const page = await flow.getLatestRunResults();
console.log("Newest run output:", page?.items);

And just like that, Lume completely automates the mapping process! Our mapped data will look like this:

[
    {
        "first_name": "Barry",
        "last_name": "Devlin",
        "age": 42
    },
    {
        "first_name": "Paul",
        "last_name": "Murphy",
        "age": 37
    }
]

That’s it! You didn’t need to write any mapping code. Lume does it all automatically. Of course, you can edit the mapper in the Lume app, and reuse the same flow for future data.

Mapping Data on an Existing Flow

Suppose you already created a Flow and just want to feed new data through it, to leverage the same mapping logic. You can do so with the process method:

const flowId = "existing-flow-id";
const existingFlow = await lume.flowService.getFlow(flowId);

// Supply new data; process internally creates and finishes a run, and returns paginated mapped output.
const resultsPage = await existingFlow.process(
  [
    { first_name: "Jane", last_name: "Smith", year_of_birth: 1985 },
    { first_name: "John", last_name: "Doe", year_of_birth: 1990 }
  ]
);

console.log("Mapped data:", resultsPage.items);

Managing Runs Manually

If you want more control over Run creation, especially for parallel tasks or large transformations, you can manage the runs yourself:

// 1. Create a run but do not wait.
const flow = await lume.flowService.getFlow("my-long-flow-id");
const run = await flow.createRun({ source_data: data }, false);

// 2. Poll or wait for it to finish.
await run.waitForCompletion();  // blocks until Succeeded, Failed, or Crashed

// 3. Check the run status and get the results.
if (run.status === "SUCCEEDED") {
  // Page size is limited to 100 items per request
  const page = await flow.getRunResults(run, 1, 50);
  console.log("Manual run output:", page.items);
} else {
  console.error("Run ended with status:", run.status);
}

// paginate through the results as needed

This approach is useful if you have advanced scheduling or concurrency requirements and prefer to manually handle the timing or error checks.

Next steps

As our data transformation needs grow, we will begin creating more flows. Start with Managing Flows and read the rest of our guides to learn more!

See the Typescript Library Overview and the NPM package for more advanced operations.

That’s everything you need for a blazing-fast start with Lume. If you run into any issues or want to share your feedback, reach out to our team. Happy mapping!