Files

Sarah's spring campaign has a brief — a PDF from the agency. It belongs with the campaign record, it mustn't be reachable by guessing a URL, and it shouldn't crawl through our API server on its way to storage.

Files is the environment's file catalog: each file is a row in the same database as your custom data, and an object in storage under a prefix that is yours alone. Uploads go straight to storage through a short-lived URL; downloads come back through an expiring URL; every upload is virus-scanned before anyone can read it.

Three steps, or one

const brief = await hb.files.upload(pdfBytes, {
  name: "spring-brief.pdf",
  contentType: "application/pdf",
  metadata: { kind: "brief" },
});
// brief.status === "ready", brief.scan_status === "pending"

POST /api/modules/files/uploads        { "name", "content_type", "size", "metadata"? }
  → 201 { "data": { "id", ... }, "upload": { "url", "method": "PUT", "headers", "expires_at" } }

PUT  <upload.url>              the bytes, with the headers given (no API key)

POST /api/modules/files/{id}/complete  → 200, verifies the object's size against what you declared

const scanned = await hb.files.waitUntilScanned(brief.id);
// scan_status: "clean" | "infected" | "failed"

await hb.data.collections.create({
  slug: "campaigns",
  fields: [
    { name: "name",  type: "string", required: true },
    { name: "brief", type: "file", on_delete: "restrict" },   // or "set_null" (default)
  ],
});

await campaigns.create({ name: "Spring refresh", brief: brief.id });

const { url, expires_at } = await hb.files.url(brief.id, { expiresIn: 300 });

await hb.files.delete(brief.id);   // gone from lists and URLs; the object is kept
await hb.files.restore(brief.id);  // within 30 days

Attach it to a module record

Custom data fields are for your own collections; for records a module owns — a client, say — attach the file to the record in the location that holds it:

const link = await hb.files.attach(brief.id, {
  targetType: "clients",
  targetId: client.id,
  locationId: location.id,
  label: "contract",
});

const docs = await hb.files.list({ attached_to: `clients:${client.id}`, location_id: location.id });
// each file carries its `attachment` (label, when)

await hb.files.detach(brief.id, link.id);   // the file stays in the catalog

The key must reach the location and the record must exist there; attaching the same file twice returns the existing link. Links survive a soft delete of the file and go with it when it's purged. Today clients is the attachable record type; modules opt in as they are released.

Keys and scopes

files.read lists, reads and mints download URLs; files.upload announces, completes and edits metadata; files.delete deletes and restores. See Who can do what.

Limits

Per plan: the largest single upload (files.max_upload_bytes, 25 MB on sandbox, 250 MB on production) and total storage (1 GB / 50 GB), both checked when an upload is announced. Metadata is at most 4 KB.

Events

file.ready, file.infected, file.deleted, file.restored — see Getting told when things happen.