Lume AI TypeScript SDK

The official TypeScript SDK for Lume AI's data transformation platform.

Features

• 🚀 Create and manage data transformation flows
• 🔄 Transform data using AI-powered mapping
• ✨ Real-time validation and error handling
• 📊 Rich schema support

Status

The Lume Typescript SDK is currently in beta. Please reach out to support if you have any questions, encounter any bugs, or have any feature requests.

Installation

npm install @lume-ai/typescript-sdk

yarn add @lume-ai/typescript-sdk

pnpm add @lume-ai/typescript-sdk

Quickstart

Initialize the SDK

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

const lume = new Lume("your-api-key");

Create a Flow and Run

// Define your target schema
const targetSchema = {
  type: "object",
  properties: {
    full_name: { type: "string", description: "Full name of the person" },
    age: { type: "integer", description: "Age of the person" },
  },
  required: ["full_name", "age"],
};
const lume = new Lume(apiKey);

// Create and run a new flow. Return only when the flow is complete.
const flow = await lume.flowService.createAndRunFlow(
  {
    name: "my_flow",
    description: "Process customer data",
    target_schema: schema,
    tags: ["customers"],
  },
  {
    source_data: myData,
  },
  true
);

// Process more data with existing flow
const flowId = "existing-flow-id";
const existingFlow = await lume.flowService.getFlow(flowId);
const results = await existingFlow.process(newData);

// use mapped data results page

Example of fetching results with pagination

Note: While the SDK provides paginated access to results, we recommend processing data page by page for large datasets. The following example shows how you could fetch all results:

// Helper function - not part of the SDK
async function getAllResults(flow) {
  const pageSize = 50;
  let currentPage = 1;
  let allResults = [];

  while (true) {
    const paginatedResults = await flow.getLatestRunResults(
      currentPage,
      pageSize
    );

    if (!paginatedResults?.items || paginatedResults.items.length === 0) {
      break; // No more results to fetch
    }

    allResults = [...allResults, ...paginatedResults.items];

    // If we have total pages info and we've reached the last page, stop
    if (paginatedResults.pages && currentPage >= paginatedResults.pages) {
      break;
    }

    currentPage++;
  }

  return allResults;
}

// Usage
const flow = await lume.flowService.getFlow(flowId);
const allResults = await getAllResults(flow);
console.log(`Retrieved ${allResults.length} total items`);

Monitor Run Status

The Run class provides methods to track transformation progress and access results:

// Get latest run status
await run.get();
console.log(run.status); // 'SUCCEEDED', 'FAILED', etc.

// Access run metadata
console.log(run.metadata);

// Get transformation output with pagination
const output = await run.getSchemaTransformerOutput(1, 50);
if (output) {
  console.log("Transformed items:", output.mapped_data.items);
  console.log("Total items:", output.mapped_data.total);
  console.log("Validation errors:", output.errors);
}

Monitoring Flow Status

You can monitor the status of flows and runs:

// Create a flow and wait for completion
const flow = await lume.flowService.createFlow({
  name: "my_flow",
  description: "Process customer data",
  target_schema: schema,
  tags: ["production"],
});

// Monitor run status
const run = await flow.createRun({ source_data: data });
while (run.status === "RUNNING" || run.status === "PENDING") {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  await run.get();
}

if (run.status === "SUCCEEDED") {
  const results = await run.getSchemaTransformerOutput();
  console.log("Transformation complete:", results);
} else {
  console.log("Run failed:", run.status);
}

Validation Handling

You can track which fields were flagged for validation errors:

try {
  const flow = await lume.flowService.createFlow({
    // ... flow configuration ...
  });

  const run = await flow.createRun({ source_data: data });
  const output = await run.getSchemaTransformerOutput();

  if (output?.errors) {
    // Handle different types of validation errors
    if ("global_errors" in output.errors) {
      // Handle global validation errors
      const globalErrors = output.errors.global_errors;
      console.log("Global validation errors:", globalErrors);
    }

    if ("record_errors" in output.errors) {
      // Handle record-specific errors
      const recordErrors = output.errors.record_errors;
      for (const [recordIndex, errors] of Object.entries(recordErrors)) {
        console.log(`Errors in record ${recordIndex}:`, errors);
      }
    }

    // Handle field-specific validation errors
    for (const [field, fieldErrors] of Object.entries(output.errors)) {
      if (field !== "global_errors" && field !== "record_errors") {
        console.log(`Validation errors for ${field}:`, fieldErrors);
      }
    }
  }

  // Handle records that couldn't be processed
  if (output?.no_data_idxs?.length) {
    console.log("Records that could not be processed:", output.no_data_idxs);
  }
} catch (error) {
  if ((error as HTTPExceptionError).code === 401) {
    console.log("Authentication failed - check your API key");
  } else if ((error as HTTPExceptionError).code === 429) {
    console.log("Rate limit exceeded - please try again later");
  } else if ((error as HTTPExceptionError).code === 400) {
    console.log("Invalid request:", (error as HTTPExceptionError).message);
  } else {
    console.log("Unexpected error:", error);
  }
}

Documentation

See the full documentation.

Issues / Questions

Please reach out to support if you encounter any bugs, have any questions, or have any feature requests.