ExuluStorage - IMP Docs

ExuluStorage is a class that wraps the platform’s S3-compatible object storage. It uses the same configuration as the IMP server’s Uppy-based upload pipeline, so files written through ExuluStorage are accessible from the same bucket the platform uses for attachments and knowledge items. You do not instantiate ExuluStorage directly — you receive an instance through the utils.storage object passed to ExuluContext processors and chunker operations.

Constructor

new ExuluStorage({ config: ExuluConfig })

config

ExuluConfig

required

The application config object from ExuluApp. Passed automatically by the platform to processor and chunker callbacks.

API surface

getPresignedUrl

storage.getPresignedUrl(key: string): Promise<string>

Returns a presigned GET URL for a stored object. The key must be in the format <bucket>/<object-path>.

key

string

required

S3 key in <bucket>/<object-path> format (e.g. "uploads/documents/report.pdf"). Throws when the bucket or key portion is empty.

return

Promise<string>

A time-limited presigned URL the caller can use to download the object directly from S3.

uploadFile

storage.uploadFile(
  file: Buffer | Uint8Array,
  fileName: string,
  type: string,
  user?: number,
  metadata?: Record<string, string>,
  customBucket?: string,
): Promise<string>

Uploads a file to S3 and returns the stored object key.

file

Buffer | Uint8Array

required

The file content to upload.

fileName

string

required

The target file name (used to derive the object key in the bucket).

type

string

required

MIME type (e.g. "application/pdf", "image/png"). Stored as the object’s Content-Type.

user

number

Numeric user ID. Stored as metadata on the S3 object when provided.

metadata

Record<string, string>

Additional key-value metadata stored on the S3 object.

customBucket

string

Override the default bucket. When omitted the platform’s configured default bucket is used.

return

Promise<string>

The S3 object key under which the file was stored.

Example

Inside a custom ExuluContext processor:

import type { ExuluContextProcessor } from "@exulu/backend";

const myProcessor: ExuluContextProcessor = {
  name: "pdf-text-extractor",
  description: "Reads a PDF from storage and extracts its text.",
  config: { trigger: "onInsert" },
  execute: async ({ item, utils }) => {
    // Download the source PDF
    const pdfUrl = await utils.storage.getPresignedUrl(item.source_key);

    const response = await fetch(pdfUrl);
    const buffer = Buffer.from(await response.arrayBuffer());

    // ... extract text from buffer ...
    const text = "extracted text";

    // Upload the result
    const resultKey = await utils.storage.uploadFile(
      Buffer.from(text),
      `${item.id}-extracted.txt`,
      "text/plain",
    );

    return { ...item, content: text, result_key: resultKey };
  },
};

Notes

ExuluStorage is exposed through utils.storage inside context processors and chunker operations — you do not need to import or instantiate it directly.
The getPresignedUrl key parsing expects exactly one / separating the bucket from the object path. Multi-level paths (bucket/folder/file.pdf) are handled correctly.

ExuluContext — configuration: how to add a processor to a context.
Self-hosting / S3 storage: configure the S3-compatible storage backend.

​Constructor

​API surface

​getPresignedUrl

​uploadFile

​Example

​Notes

​Related

Constructor

API surface

getPresignedUrl

uploadFile

Example

Notes

Related