Files

A file source reads a vendor's spreadsheet or export: CSV (and tab-separated text), XLSX, XLS, JSON or XML. The file can reach FurniOps three ways:

Whichever way it comes, a file goes through the same run, and its columns are read through the source's mapping. Set config.format when the content does not tell the format apart (a .txt that is really CSV). A file larger than FurniOps' snapshot limit fails as too_large. A column of shipping boxes has a format of its own, described in Cartons.

From a URLCopy Anchor Link

// A vendor's price list at a URL, read every 6 hours.
const pricelist = await furniops.sources.create({
  name: "Acme price list",
  kind: "file",
  config: { url: "https://vendor.example/feeds/pricelist.csv", format: "csv", role: "supplier" },
  schedule: { interval_minutes: 360 },
  licence_basis: "vendor_agreement",
});
console.log(pricelist.id, pricelist.status); // "src_…", "active"

FurniOps fetches only public http and https addresses: a URL that points at a private or local network is refused, the run fails as fetch_refused, and the source is blocked until the URL changes.

Upload a fileCopy Anchor Link

Uploading takes three calls, and the file itself never passes through the API:

// A file you have, for a `file` source without a URL.
const bytes = await readFile("pricelist.xlsx");
const upload = await furniops.sources.createUpload("src_034XqBaL2mRLTZPXyRbaUc", {
  filename: "pricelist.xlsx",
  content_type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  bytes: bytes.byteLength,
});
// PUT the bytes to the presigned URL, with exactly the headers given, within 15 minutes.
const target = upload.target;
if (target === null) throw new Error("no upload target");
const put = await fetch(target.url, {
  method: target.method,
  headers: target.headers,
  body: bytes,
});
if (!put.ok) throw new Error(`upload failed: ${put.status}`);
// Then complete it: FurniOps checks the bytes arrived and queues a run that reads them.
const reading = await furniops.uploads.complete(upload.id);
console.log(reading.id, reading.status); // "run_…", "queued"

• An upload is pending until completed, then completed with its run. One never completed in time becomes expired.
• Only file sources take uploads; other kinds answer 422, as does a file larger than the snapshot limit.
• Missing or different bytes answer 422 on completion. An expired or already completed upload, a source with a run under way, or a paused or disabled source answer 409.
• The bytes are checked again when captured: the declared type is not trusted on its own.

The dashboard's Uploads page is not available yet; upload through the API or the SDK.

Receive files by emailCopy Anchor Link

Vendors who send price lists by email can send them straight to the source. Set config.inbound with the senders allowed:

{
  "config": {
    "format": "xlsx",
    "inbound": { "senders": ["[email protected]", "@vendor.example"] }
  }
}

The source then gets its own address, inbound_address. The part before the @ is a random 26-character token, unique to the source and kept for its life unless you rotate it: give the address only to the vendor.

FurniOps takes an email only when all of these hold:

1. The sender is authenticated. The message passed DMARC, or carries a DKIM signature aligned with the From domain, as the mail provider reports. FurniOps never trusts the From header alone.
2. The sender is allowed. The From address is on the source's list, as a whole address or as @domain for anyone at that domain. Up to 50 entries, each listed once.
3. The source is active (or degraded).
4. It has an attachment in the source's format (any supported format when config.format is unset).

Each attachment that qualifies starts its own run; the message body and inline parts are ignored. A source runs one run at a time, so a second attachment waits for the first run to end.

The inbox logCopy Anchor Link

GET /v1/sources/{id}/inbound-messages lists what arrived, newest first: the sender, when it was received, what FurniOps did, and the run each attachment started.

Each attachment shows started (with its run), skipped (not in the source's format) or failed (it could not be fetched or stored). Reasons are FurniOps' own words: nothing the sender wrote is echoed back.

A leaked addressCopy Anchor Link

POST /v1/sources/{id}/inbound-address/rotate gives the source a new address at once; mail to the old one is refused from then on. Send the new one to your vendor.