@onlineapps/storage-core

Core MinIO storage operations for OA Drive - shared by business and infrastructure services.

Purpose

This package provides basic storage operations without business-specific features (caching, shared URLs, logging). It is used by:

• Business services via @onlineapps/conn-base-storage (which adds business features)
• Infrastructure services via @onlineapps/infrastructure-tools (which re-exports this package)

Installation

npm install @onlineapps/storage-core

Quick Start

const { StorageCore } = require('@onlineapps/storage-core');

const storage = new StorageCore({
  // FAIL-FAST: topology must be explicit (no defaults for hosts/credentials)
  endPoint: process.env.MINIO_ENDPOINT,
  port: parseInt(process.env.MINIO_PORT, 10),
  accessKey: process.env.MINIO_ACCESS_KEY,
  secretKey: process.env.MINIO_SECRET_KEY
});

await storage.initialize();

// Upload
await storage.putObject('bucket', 'path/to/file', buffer, {
  'Content-Type': 'application/json'
});

// Download
const buffer = await storage.getObject('bucket', 'path/to/file');

// Fingerprint
const fingerprint = storage.calculateFingerprint(buffer);

API

Constructor

const storage = new StorageCore(config);

Config options:

• endPoint - MinIO server endpoint (required, env: MINIO_ENDPOINT)
• port - MinIO server port (required, env: MINIO_PORT)
• useSSL - Use SSL/TLS (default: false)
• accessKey - Access key (required, env: MINIO_ACCESS_KEY)
• secretKey - Secret key (required, env: MINIO_SECRET_KEY)

Core Methods

initialize()

Initialize storage client (currently a no-op, kept for API consistency).

bucketExists(bucket)

Check if bucket exists.

ensureBucket(bucket, region?)

Ensure bucket exists, create if it doesn't.

putObject(bucket, path, data, metadata?)

Upload object to storage.

getObject(bucket, path)

Download object from storage.

objectExists(bucket, path)

Check if object exists.

statObject(bucket, path)

Get object metadata.

deleteObject(bucket, path)

Delete object from storage.

calculateFingerprint(content)

Generate SHA256 fingerprint for content (string, Buffer, or Object).

verifyFingerprint(bucket, path, expectedFingerprint)

Download object and verify its fingerprint matches expected value.

getContentType(filename)

Get MIME type from filename extension.

getPresignedUrl(bucket, path, expiry?)

Generate presigned URL for object access.

listByPrefix(bucket, prefix?, recursive?)

List objects by prefix.

Architecture

storage-core (this package)
    ↓
conn-base-storage (business services)
    + business features (caching, shared URLs, logging)

storage-core (this package)
    ↓
infrastructure-tools (infrastructure services)
    + re-export for infra services

Error Messages

All errors follow the format: [StorageCore] Problem - Expected/Fix

Example:

[StorageCore] putObject: bucket name is required
[StorageCore] Fingerprint mismatch: expected abc123, got def456

Dependencies

• minio - MinIO client library

No other external dependencies - minimal footprint.

License

ISC