@settlemint/sdk-minio/dist/minio.d.ts

MinIO integration module for SettleMint SDK, providing S3-compatible object storage capabilities

/* SettleMint MinIO SDK - Object Storage */
import { Client, Client as Client$1, ItemBucketMetadata } from "minio";
import { z } from "zod";
import { Buffer } from "node:buffer";

//#region src/helpers/client-options.schema.d.ts
/**
 * Schema for validating server client options for the MinIO client.
 */
declare const ServerClientOptionsSchema: z.ZodObject<{
  instance: z.ZodString;
  accessKey: z.ZodString;
  secretKey: z.ZodString;
}, z.core.$strip>;
/**
 * Type definition for server client options derived from the ServerClientOptionsSchema.
 */
type ServerClientOptions = z.infer<typeof ServerClientOptionsSchema>;
//#endregion
//#region src/helpers/schema.d.ts
/**
 * 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>;
}, z.core.$strip>;
/**
 * Type representing file metadata after validation.
 */
interface FileMetadata {
  /**
   * The unique identifier for the file.
   */
  id: string;
  /**
   * The name of the file.
   */
  name: string;
  /**
   * The content type of the file.
   */
  contentType: string;
  /**
   * The size of the file in bytes.
   */
  size: number;
  /**
   * The date and time the file was uploaded.
   */
  uploadedAt: string;
  /**
   * The ETag of the file.
   */
  etag: string;
  /**
   * The URL of the file.
   */
  url?: string;
}
/**
 * Default bucket name to use for file storage when none is specified.
 */
declare const DEFAULT_BUCKET = "uploads";
//#endregion
//#region src/helpers/functions.d.ts
/**
 * 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$1, prefix?: string, bucket?: string): Promise<FileMetadata[]>;
/**
 * Gets a single file by its object name
 *
 * @param client - The MinIO client to use
 * @param fileId - The file identifier/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 getFileById(client: Client$1, fileId: string, bucket?: string): Promise<FileMetadata>;
/**
 * Deletes a file from storage
 *
 * @param client - The MinIO client to use
 * @param fileId - The file identifier/path
 * @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$1, 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$1, 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$1, buffer: Buffer, objectName: string, contentType: string, bucket?: string): Promise<FileMetadata>;
//#endregion
//#region src/minio.d.ts
/**
 * Creates a MinIO client for server-side use with authentication.
 *
 * @param options - The server client options for configuring the MinIO client
 * @returns An object containing the initialized MinIO client
 * @throws Will throw an error if not called on the server or if the options fail validation
 *
 * @example
 * import { createServerMinioClient } 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!
 * });
 * client.listBuckets();
 */
declare function createServerMinioClient(options: ServerClientOptions): {
  client: Client$1;
};
//#endregion
export { type Client, DEFAULT_BUCKET, type FileMetadata, type ItemBucketMetadata, createPresignedUploadUrl, createServerMinioClient, deleteFile, getFileById, getFilesList, uploadFile };
//# sourceMappingURL=minio.d.ts.map