Skip to main content

Storage

The Fynd Boltic SDK exposes account storage through client.storage: list objects under a prefix, upload files, create folders, change public/private access, and download file contents. Configuration matches other SDK services (region, environment, and so on).

import { createClient } from "@boltic/sdk";

const client = createClient("your-api-key");

// All storage operations
const storage = client.storage;

What you can do​

  • List — Browse files and folders under a basePath prefix; each row is normalized to a fixed set of fields (see List).
  • Upload — Send a Blob + filename; control visibility with public and expire_in (see Upload).
  • Create folder — Create an empty prefix path (see Create folder).
  • Delete — Remove an object by full path (see Delete file).
  • Access — makePublic / makePrivate with a compact summary response (see Public & private).
  • Download — Read full file bytes for a path (see Download file).

Core functions​

FunctionDescription
list(params?)List objects under an optional folder prefix
upload(params)Upload a file (Blob + options)
createFolder(params)Create a folder path
deleteFile(params)Delete by full object path
makePublic(filePath)Make object publicly readable
makePrivate(filePath)Make object private
downloadFile(params)Download bytes for an object

Client configuration​

Pass options as the second argument to createClient so storage calls hit the correct environment:

OptionTypeDescription
region'asia-south1' or 'us-central1'Regional host (default asia-south1)
environment'local', 'sit', 'uat', or 'prod'Deployment environment
debugbooleanVerbose request logging
const client = createClient(process.env.BOLTIC_API_KEY!, {
    region: "asia-south1",
    environment: "prod",
    debug: false,
});

Response shape​

Every method returns either success data or a BolticErrorResponse. Prefer the type guard isErrorResponse from @boltic/sdk:

import { createClient, isErrorResponse } from "@boltic/sdk";

const result = await client.storage.list({ basePath: "app/" });

if (isErrorResponse(result)) {
    console.error(result.error.message);
    return;
}

const rows = result.files?.data ?? [];

You can also check "error" in result && result.error if you avoid the helper.

Success and error types (conceptual)​

// Success — shape depends on the method (list, upload, etc.)
// Error
interface BolticErrorResponse {
    error: {
        code: string;
        message: string;
        meta?: string[];
    };
}

Quick example​

import { createClient, isErrorResponse } from "@boltic/sdk";

const client = createClient("your-api-key");

const listed = await client.storage.list({ basePath: "" });
if (!isErrorResponse(listed)) {
    console.log(listed.files?.data?.length ?? 0, "items");
}

End-to-end pattern​

Typical flow: ensure a prefix exists → upload → list → optionally download or change access.

import { createClient, isErrorResponse } from "@boltic/sdk";

const client = createClient("your-api-key");
const prefix = "my-app/invoices/";

// 1) Folder (optional if uploads create prefixes automatically)
const folder = await client.storage.createFolder({ folder_path: prefix.replace(/\/$/, "") });
if (isErrorResponse(folder)) throw new Error(folder.error.message);

// 2) Upload
const blob = new Blob([JSON.stringify({ ok: true })], { type: "application/json" });
const up = await client.storage.upload({
    file: blob,
    filename: `invoice-${Date.now()}.json`,
    filepath: prefix,
});
if (isErrorResponse(up)) throw new Error(up.error.message);
const objectPath = up.path;

// 3) List
const listed = await client.storage.list({ basePath: prefix });
if (isErrorResponse(listed)) throw new Error(listed.error.message);

// 4) Download (use full path from upload or list `fullPath`)
const dl = await client.storage.downloadFile({ file_name: objectPath });
if (isErrorResponse(dl)) throw new Error(dl.error.message);
const bytes = dl.bytes;

Paths: rules of thumb​

  • basePath for list — folder prefix, often trailing slash (e.g. "exports/").
  • filepath for upload — prefix under which the file is stored; combine with filename for the logical object.
  • path / fullPath from responses — use these for deleteFile({ filename }), downloadFile({ file_name }), makePublic / makePrivate — must match the full object path in storage.

For builders and AI assistants​

Use this checklist when implementing or generating code:

  1. Import — createClient from @boltic/sdk; use isErrorResponse after every storage call unless you wrap errors elsewhere.
  2. List — Pass basePath to scope listing; read result.files?.data and use fullPath, isDirectory, size, updatedAt as needed.
  3. Upload — Provide file (Blob) and filename or file_name (logical name). Set public / expire_in for visibility; read path and optional temporary_sharable_link / public_url.
  4. Delete / download / access — Always use the full storage path for that object (same as list fullPath or upload path).
  5. Download — Pass file_name with the full path. If you already know the size from a previous list, pass sizeBytes so the client does not need to resolve it.
  6. makePublic / makePrivate — Returns ObjectAccessSummary: message, name, size, updated, public.

Use only the client.storage methods documented in this section.