@cresium/cleric-utils

Shared utilities for Cresium services.

Installation

yarn add @cresium/cleric-utils
# or
npm install @cresium/cleric-utils

Available Utilities

| Utility | Description | | ------- | ----------- | | S3Manager | AWS S3 operations (upload, retrieve, presigned URLs) |

S3Manager

Full-featured S3 client with typed retrieval and multiple upload methods.

Setup

import { S3Manager } from "@cresium/cleric-utils";

const s3Manager = new S3Manager({
  region: "us-east-1",
  bucketName: "my-bucket",
});

Methods

retrieve<T>(key) - Get typed JSON from S3

interface MyData {
  transactions: Transaction[];
}

const data = await s3Manager.retrieve<MyData>("path/to/file.json");
// data is typed as MyData

upload(key, buffer, contentType?) - Upload a buffer

await s3Manager.upload("documents/file.pdf", pdfBuffer, "application/pdf");
await s3Manager.upload("images/photo.jpg", imageBuffer, "image/jpeg");

uploadFile(file, key, location) - Upload with location prefix

// Returns "images/photo.jpg"
const path = await s3Manager.uploadFile(
  { buffer: fileBuffer, mimetype: "image/jpeg" },
  "photo.jpg",
  "images"
);

uploadJson(data, key, location?) - Upload JSON data

// Without location prefix
await s3Manager.uploadJson({ foo: "bar" }, "data.json");

// With location prefix (returns "documents/data.json")
await s3Manager.uploadJson({ foo: "bar" }, "data.json", "documents");

generatePresignedUrl(key, filename?, expiresIn?) - Presigned URL from key

const url = await s3Manager.generatePresignedUrl(
  "documents/file.pdf",
  "download.pdf",  // optional download filename
  3600             // optional expiry in seconds (default: 3600)
);

generatePresignedUrlFromUrl(url, filename?) - Presigned URL from S3 URL

const presignedUrl = await s3Manager.generatePresignedUrlFromUrl(
  "https://bucket.s3.amazonaws.com/path/to/file.pdf",
  "download.pdf"
);

// Returns original URL if it's not from the configured bucket

Types

S3ManagerConfig

interface S3ManagerConfig {
  region: string;
  bucketName: string;
}

S3File

Compatible with Multer file uploads.

interface S3File {
  buffer: Buffer;
  mimetype: string;
}

Publishing

Quick Release

cd /path/to/cleric/packages/utils

# 1. Build and verify
yarn build
yarn typecheck

# 2. Bump version
npm version patch   # 0.2.0 -> 0.2.1 (bug fixes)
npm version minor   # 0.2.0 -> 0.3.0 (new features)
npm version major   # 0.2.0 -> 1.0.0 (breaking changes)

# 3. Publish
npm publish

# 4. Push tags to git
git push && git push --tags

Pre-publish Checklist

# Verify what will be published
npm pack --dry-run

# Should show:
# - dist/
# - README.md
# - package.json

License

MIT