@settlemint/sdk-minio 2.1.4 → 2.1.5-pr3ad019ac

package/dist/minio.d.cts

@@ -1,19 +1,19 @@
-import { Client } from 'minio';
+import { Client, ItemBucketMetadata } from 'minio';
+export { Client, ItemBucketMetadata } from 'minio';
 import { z } from 'zod';
+import { Buffer } from 'node:buffer';
 
 /**
- * Schema for validating server client options for the Portal client.
- * Extends the ClientOptionsSchema with additional server-specific fields.
+ * Schema for validating server client options for the MinIO client.
  */
-declare const ServerClientOptionsSchema: z.ZodObject<z.objectUtil.extendShape<{
+declare const ServerClientOptionsSchema: z.ZodObject<{
     /** The URL of the MinIO instance to connect to */
     instance: z.ZodString;
-}, {
     /** The MinIO access key used to authenticate with the MinIO server */
     accessKey: z.ZodString;
     /** The MinIO secret key used to authenticate with the MinIO server */
     secretKey: z.ZodString;
-}>, "strip", z.ZodTypeAny, {
+}, "strip", z.ZodTypeAny, {
     instance: string;
     accessKey: string;
     secretKey: string;
@@ -27,6 +27,328 @@ declare const ServerClientOptionsSchema: z.ZodObject<z.objectUtil.extendShape<{
  */
 type ServerClientOptions = z.infer<typeof ServerClientOptionsSchema>;
 
+/**
+ * Base interface for all MinIO operations
+ *
+ * @template T The return type of the operation
+ */
+interface MinioOperation<T> {
+    execute: (client: Client) => Promise<T>;
+}
+/**
+ * Creates an operation to list objects in a bucket
+ *
+ * @param bucket - The bucket name to list objects from
+ * @param prefix - Optional prefix to filter objects (like a folder path)
+ * @returns A MinioOperation that lists objects when executed
+ * @throws Will throw an error if the operation fails
+ *
+ * @example
+ * import { createListObjectsOperation, executeMinioOperation } from "@settlemint/sdk-minio";
+ *
+ * const listOperation = createListObjectsOperation("my-bucket", "folder/");
+ * const objects = await executeMinioOperation(client, listOperation);
+ */
+declare function createListObjectsOperation(bucket: string, prefix?: string): MinioOperation<Array<{
+    name: string;
+    prefix?: string;
+    size: number;
+    etag: string;
+    lastModified: Date;
+}>>;
+/**
+ * Creates an operation to get an object's metadata
+ *
+ * @param bucket - The bucket name containing the object
+ * @param objectName - The object name/path
+ * @returns A MinioOperation that gets object stats when executed
+ * @throws Will throw an error if the operation fails
+ *
+ * @example
+ * import { createStatObjectOperation, executeMinioOperation } from "@settlemint/sdk-minio";
+ *
+ * const statOperation = createStatObjectOperation("my-bucket", "folder/file.txt");
+ * const stats = await executeMinioOperation(client, statOperation);
+ */
+declare function createStatObjectOperation(bucket: string, objectName: string): MinioOperation<{
+    size: number;
+    etag: string;
+    metaData: Record<string, string>;
+    lastModified: Date;
+}>;
+/**
+ * Creates an operation to upload a buffer to MinIO
+ *
+ * @param bucket - The bucket name to upload to
+ * @param objectName - The object name/path to create
+ * @param buffer - The buffer containing the file data
+ * @param metadata - Optional metadata to attach to the object
+ * @returns A MinioOperation that uploads the buffer when executed
+ * @throws Will throw an error if the operation fails
+ *
+ * @example
+ * import { createUploadOperation, executeMinioOperation } from "@settlemint/sdk-minio";
+ *
+ * const buffer = Buffer.from("file content");
+ * const uploadOperation = createUploadOperation("my-bucket", "folder/file.txt", buffer, { "content-type": "text/plain" });
+ * const result = await executeMinioOperation(client, uploadOperation);
+ */
+declare function createUploadOperation(bucket: string, objectName: string, buffer: Buffer, metadata?: ItemBucketMetadata): MinioOperation<{
+    etag: string;
+}>;
+/**
+ * Creates an operation to delete an object from MinIO
+ *
+ * @param bucket - The bucket name containing the object
+ * @param objectName - The object name/path to delete
+ * @returns A MinioOperation that deletes the object when executed
+ * @throws Will throw an error if the operation fails
+ *
+ * @example
+ * import { createDeleteOperation, executeMinioOperation } from "@settlemint/sdk-minio";
+ *
+ * const deleteOperation = createDeleteOperation("my-bucket", "folder/file.txt");
+ * await executeMinioOperation(client, deleteOperation);
+ */
+declare function createDeleteOperation(bucket: string, objectName: string): MinioOperation<void>;
+/**
+ * Creates an operation to generate a presigned URL for an object
+ *
+ * @param bucket - The bucket name containing the object
+ * @param objectName - The object name/path
+ * @param expirySeconds - How long the URL should be valid for in seconds
+ * @returns A MinioOperation that creates a presigned URL when executed
+ * @throws Will throw an error if the operation fails
+ *
+ * @example
+ * import { createPresignedUrlOperation, executeMinioOperation } from "@settlemint/sdk-minio";
+ *
+ * const urlOperation = createPresignedUrlOperation("my-bucket", "folder/file.txt", 3600);
+ * const url = await executeMinioOperation(client, urlOperation);
+ */
+declare function createPresignedUrlOperation(bucket: string, objectName: string, expirySeconds: number): MinioOperation<string>;
+/**
+ * Creates an operation to generate a presigned PUT URL for direct uploads
+ *
+ * @param bucket - The bucket name to upload to
+ * @param objectName - The object name/path to create
+ * @param expirySeconds - How long the URL should be valid for in seconds
+ * @returns A MinioOperation that creates a presigned PUT URL when executed
+ * @throws Will throw an error if the operation fails
+ *
+ * @example
+ * import { createPresignedPutOperation, executeMinioOperation } from "@settlemint/sdk-minio";
+ *
+ * const putUrlOperation = createPresignedPutOperation("my-bucket", "folder/file.txt", 3600);
+ * const url = await executeMinioOperation(client, putUrlOperation);
+ */
+declare function createPresignedPutOperation(bucket: string, objectName: string, expirySeconds: number): MinioOperation<string>;
+/**
+ * Creates a simplified upload function bound to a specific client
+ *
+ * @param client - The MinIO client to use for uploads
+ * @returns A function that uploads buffers to MinIO
+ * @throws Will throw an error if the operation fails
+ *
+ * @example
+ * import { createSimpleUploadOperation, getMinioClient } from "@settlemint/sdk-minio";
+ *
+ * const client = await getMinioClient();
+ * const uploadFn = createSimpleUploadOperation(client);
+ * const result = await uploadFn(buffer, "my-bucket", "folder/file.txt", { "content-type": "text/plain" });
+ */
+declare function createSimpleUploadOperation(client: Client): (buffer: Buffer, bucket: string, objectName: string, metadata?: ItemBucketMetadata) => Promise<{
+    etag: string;
+}>;
+
+/**
+ * Helper type to extract the inferred type from a Zod schema.
+ *
+ * @template T - The Zod schema type
+ */
+type Static<T extends z.ZodType> = z.infer<T>;
+/**
+ * Schema for file metadata stored in MinIO.
+ * Defines the structure and validation rules for file information.
+ */
+declare const FileMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    contentType: z.ZodString;
+    size: z.ZodNumber;
+    uploadedAt: z.ZodString;
+    etag: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    contentType: string;
+    size: number;
+    uploadedAt: string;
+    etag: string;
+    url?: string | undefined;
+}, {
+    id: string;
+    name: string;
+    contentType: string;
+    size: number;
+    uploadedAt: string;
+    etag: string;
+    url?: string | undefined;
+}>;
+/**
+ * Type representing file metadata after validation.
+ */
+type FileMetadata = Static<typeof FileMetadataSchema>;
+/**
+ * Default bucket name to use for file storage when none is specified.
+ */
+declare const DEFAULT_BUCKET = "uploads";
+
+/**
+ * Gets a list of files with optional prefix filter
+ *
+ * @param client - The MinIO client to use
+ * @param prefix - Optional prefix to filter files (like a folder path)
+ * @param bucket - Optional bucket name (defaults to DEFAULT_BUCKET)
+ * @returns Array of file metadata objects
+ * @throws Will throw an error if the operation fails or client initialization fails
+ *
+ * @example
+ * import { createServerMinioClient, getFilesList } from "@settlemint/sdk-minio";
+ *
+ * const { client } = createServerMinioClient({
+ *   instance: process.env.SETTLEMINT_MINIO_ENDPOINT!,
+ *   accessKey: process.env.SETTLEMINT_MINIO_ACCESS_KEY!,
+ *   secretKey: process.env.SETTLEMINT_MINIO_SECRET_KEY!
+ * });
+ *
+ * const files = await getFilesList(client, "documents/");
+ */
+declare function getFilesList(client: Client, prefix?: string, bucket?: string): Promise<FileMetadata[]>;
+/**
+ * Gets a single file by its object name
+ *
+ * @param client - The MinIO client to use
+ * @param objectName - The object name/path
+ * @param bucket - Optional bucket name (defaults to DEFAULT_BUCKET)
+ * @returns File metadata with presigned URL
+ * @throws Will throw an error if the file doesn't exist or client initialization fails
+ *
+ * @example
+ * import { createServerMinioClient, getFileByObjectName } from "@settlemint/sdk-minio";
+ *
+ * const { client } = createServerMinioClient({
+ *   instance: process.env.SETTLEMINT_MINIO_ENDPOINT!,
+ *   accessKey: process.env.SETTLEMINT_MINIO_ACCESS_KEY!,
+ *   secretKey: process.env.SETTLEMINT_MINIO_SECRET_KEY!
+ * });
+ *
+ * const file = await getFileByObjectName(client, "documents/report.pdf");
+ */
+declare function getFileByObjectName(client: Client, objectName: string, bucket?: string): Promise<FileMetadata>;
+/**
+ * Deletes a file from storage
+ *
+ * @param client - The MinIO client to use
+ * @param fileId - The file identifier/path to delete
+ * @param bucket - Optional bucket name (defaults to DEFAULT_BUCKET)
+ * @returns Success status
+ * @throws Will throw an error if deletion fails or client initialization fails
+ *
+ * @example
+ * import { createServerMinioClient, deleteFile } from "@settlemint/sdk-minio";
+ *
+ * const { client } = createServerMinioClient({
+ *   instance: process.env.SETTLEMINT_MINIO_ENDPOINT!,
+ *   accessKey: process.env.SETTLEMINT_MINIO_ACCESS_KEY!,
+ *   secretKey: process.env.SETTLEMINT_MINIO_SECRET_KEY!
+ * });
+ *
+ * await deleteFile(client, "documents/report.pdf");
+ */
+declare function deleteFile(client: Client, fileId: string, bucket?: string): Promise<boolean>;
+/**
+ * Creates a presigned upload URL for direct browser uploads
+ *
+ * @param client - The MinIO client to use
+ * @param fileName - The file name to use
+ * @param path - Optional path/folder
+ * @param bucket - Optional bucket name (defaults to DEFAULT_BUCKET)
+ * @param expirySeconds - How long the URL should be valid for
+ * @returns Presigned URL for PUT operation
+ * @throws Will throw an error if URL creation fails or client initialization fails
+ *
+ * @example
+ * import { createServerMinioClient, createPresignedUploadUrl } from "@settlemint/sdk-minio";
+ *
+ * const { client } = createServerMinioClient({
+ *   instance: process.env.SETTLEMINT_MINIO_ENDPOINT!,
+ *   accessKey: process.env.SETTLEMINT_MINIO_ACCESS_KEY!,
+ *   secretKey: process.env.SETTLEMINT_MINIO_SECRET_KEY!
+ * });
+ *
+ * // Generate the presigned URL on the server
+ * const url = await createPresignedUploadUrl(client, "report.pdf", "documents/");
+ *
+ * // Send the URL to the client/browser via HTTP response
+ * return Response.json({ uploadUrl: url });
+ *
+ * // Then in the browser:
+ * const response = await fetch('/api/get-upload-url');
+ * const { uploadUrl } = await response.json();
+ * await fetch(uploadUrl, {
+ *  method: 'PUT',
+ *  headers: { 'Content-Type': 'application/pdf' },
+ *  body: pdfFile
+ * });
+ */
+declare function createPresignedUploadUrl(client: Client, fileName: string, path?: string, bucket?: string, expirySeconds?: number): Promise<string>;
+/**
+ * Uploads a buffer directly to storage
+ *
+ * @param client - The MinIO client to use
+ * @param buffer - The buffer to upload
+ * @param objectName - The full object name/path
+ * @param contentType - The content type of the file
+ * @param bucket - Optional bucket name (defaults to DEFAULT_BUCKET)
+ * @returns The uploaded file metadata
+ * @throws Will throw an error if upload fails or client initialization fails
+ *
+ * @example
+ * import { createServerMinioClient, uploadBuffer } from "@settlemint/sdk-minio";
+ *
+ * const { client } = createServerMinioClient({
+ *   instance: process.env.SETTLEMINT_MINIO_ENDPOINT!,
+ *   accessKey: process.env.SETTLEMINT_MINIO_ACCESS_KEY!,
+ *   secretKey: process.env.SETTLEMINT_MINIO_SECRET_KEY!
+ * });
+ *
+ * const buffer = Buffer.from("Hello, world!");
+ * const uploadedFile = await uploadFile(client, buffer, "documents/hello.txt", "text/plain");
+ */
+declare function uploadFile(client: Client, buffer: Buffer, objectName: string, contentType: string, bucket?: string): Promise<FileMetadata>;
+
+/**
+ * Executes a MinIO operation using the provided client
+ *
+ * @param client - MinIO client to use
+ * @param operation - The operation to execute
+ * @returns The result of the operation execution
+ * @throws Will throw an error if the operation fails
+ *
+ * @example
+ * import { createServerMinioClient, createListObjectsOperation, executeMinioOperation } from "@settlemint/sdk-minio";
+ * const { client } = createServerMinioClient({
+ *   instance: process.env.SETTLEMINT_MINIO_ENDPOINT!,
+ *   accessKey: process.env.SETTLEMINT_MINIO_ACCESS_KEY!,
+ *   secretKey: process.env.SETTLEMINT_MINIO_SECRET_KEY!
+ * });
+ * const listOperation = createListObjectsOperation("my-bucket", "prefix/");
+ * const result = await executeMinioOperation(client, listOperation);
+ */
+declare function executeMinioOperation<T>(client: Client, operation: MinioOperation<T>): Promise<T>;
+
 /**
  * Creates a MinIO client for server-side use with authentication.
  *
@@ -48,4 +370,4 @@ declare function createServerMinioClient(options: ServerClientOptions): {
     client: Client;
 };
 
-export { createServerMinioClient };
+export { DEFAULT_BUCKET, type FileMetadata, type MinioOperation, createDeleteOperation, createListObjectsOperation, createPresignedPutOperation, createPresignedUploadUrl, createPresignedUrlOperation, createServerMinioClient, createSimpleUploadOperation, createStatObjectOperation, createUploadOperation, deleteFile, executeMinioOperation, getFileByObjectName, getFilesList, uploadFile };