Storage

Upload, retrieve, and delete files and images from the browser

The storage module uploads files and images to managed cloud storage and returns proxy URLs, plus reads and deletes existing files. Uploads are sent as multipart/form-data — pass a browser File (e.g. from an <input type="file">) or a Blob. There is no Uint8Array + mimeType path; the browser supplies the content type.

Uploads are attributed to the logged-in user automatically (from the token) — there is no userId param. A user may delete files they own; reads are project-scoped.

---

uploadFile

Uploads a generic file (PDF, video, document, …) without server-side processing.

const input = document.querySelector('input[type="file"]');
const file = input.files[0];

const uploaded = await sublay.storage.uploadFile({
  file,
  filename: "report.pdf",
  pathParts: ["documents", "reports"],
  entityId: "ent_xyz789",
});
// uploaded.publicPath → proxy URL

file · Blob | File · required

The file to upload, as a browser File or Blob.

pathParts · string[] · required

Storage path segments. The file is stored under the joined path with a UUID sub-folder appended, e.g. ["documents", "reports"] → documents/reports/<uuid>/<filename>.

filename · string

Filename for the multipart part. Defaults to the File.name, or "upload".

position · number

Display order when a record has multiple attachments.

metadata · object

Custom key-value data stored alongside the file record.

entityId · string

Associates the file with an entity for cascade deletion. Only one of entityId / commentId / spaceId may be set.

commentId · string

Associates the file with a comment for cascade deletion.

spaceId · string

Associates the file with a space.

Returns — Promise<UploadFileResponse>:

{
  fileId: string;
  type: string;
  relativePath: string;
  publicPath: string; // proxy URL
  size: number;
  mimeType: string;
  createdAt: string;
}

---

uploadImage

Uploads an image, processes it server-side, and stores the original plus all requested variants. The imageOptions object is a discriminated union on mode — the other fields depend on the mode you pick.

const input = document.querySelector('input[type="file"]');
const file = input.files[0];

const uploaded = await sublay.storage.uploadImage({
  file,
  filename: "avatar.png",
  imageOptions: {
    mode: "exact-dimensions",
    dimensions: {
      thumbnail: { width: 64, height: 64 },
      card: { width: 400, height: 300 },
    },
    format: "webp",
    quality: 85,
  },
  pathParts: ["avatars"],
});
// uploaded.variants → { thumbnail: {...}, card: {...} }

file · Blob | File · required

The image to upload, as a browser File or Blob. Must be a format the server can process.

imageOptions · ImageOptions · required

Image-processing configuration — a discriminated union on mode. The supported modes and their required fields:

mode	Required fields	Notes
exact-dimensions	dimensions ({ [variant]: { width, height } })	Fixed-size crops.
aspect-ratio-width-based	aspectRatio, widths ({ [variant]: number })	Heights computed from the ratio.
aspect-ratio-height-based	aspectRatio, heights ({ [variant]: number })	Widths computed from the ratio.
original-aspect	sizes ({ [variant]: number })	Preserves source ratio; fit limited to inside/outside.
multi-aspect-ratio	aspectRatios ({ width, height }[]), sizes	1–10 aspect ratios.

All modes also accept optional quality (1–100), format (webp | jpeg | png | original), stripExif (boolean), and fit (cover | contain | inside | outside). Dimension/size values are 50–10000.

filename · string

Filename for the multipart part. Defaults to the File.name, or "upload".

pathParts · string[]

Storage path segments. Defaults to ["images", "<fileId>"].

entityId · string

Associates the image with an entity. Only one of entityId / commentId / spaceId / eventId may be set.

commentId · string

Associates the image with a comment.

spaceId · string

Associates the image with a space.

eventId · string

Associates the image with an event. Most apps attach event images inline via sublay.events.createEvent/updateEvent (cover / gallery); use this only to attach an image to an existing event out-of-band.

Returns — Promise<UploadImageResponse>:

{
  fileId: string;
  type: "image";
  originalPath: string;
  originalSize: number;
  originalWidth: number;
  originalHeight: number;
  variants: Record<string, UploadedImageVariant>; // { path, width, height, size, format, publicPath }
  format: string;
  quality: number;
  createdAt: string;
}

---

getFile

Fetches a file’s metadata and proxy URLs by ID. For images, an image extension (variants, processing details) is included. Reads are project-scoped.

const file = await sublay.storage.getFile({ fileId: "fil_abc123" });

fileId · string · required

The ID of the file to retrieve.

Returns — Promise<GetFileResponse> — a flat projection carrying fileId, type, originalPath, originalSize, originalMimeType, position, metadata, createdAt/updatedAt, the optional association ids (userId, entityId, commentId, spaceId), and — for images — an image object with variants, processingStatus, format, quality, and exifStripped.

---

deleteFile

Deletes a file record and removes all associated storage objects (for images, every generated variant too).

await sublay.storage.deleteFile({ fileId: "fil_abc123" });

fileId · string · required

The ID of the file to delete.

Returns — Promise<void>

The call only succeeds when the logged-in user owns the file; otherwise it returns 403.