@settlemint/sdk-minio 2.1.4 → 2.1.5-pr594fad44

package/README.md

@@ -29,7 +29,18 @@
 - [About](#about)
 - [API Reference](#api-reference)
   - [Functions](#functions)
+    - [createPresignedUploadUrl()](#createpresigneduploadurl)
     - [createServerMinioClient()](#createserverminioclient)
+    - [deleteFile()](#deletefile)
+    - [getFileById()](#getfilebyid)
+    - [getFilesList()](#getfileslist)
+    - [uploadFile()](#uploadfile)
+  - [Type Aliases](#type-aliases)
+    - [FileMetadata](#filemetadata)
+    - [Static\<T\>](#statict)
+  - [Variables](#variables)
+    - [DEFAULT\_BUCKET](#default_bucket)
+    - [FileMetadataSchema](#filemetadataschema)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -43,11 +54,68 @@ For detailed information about using MinIO with the SettleMint platform, check o
 
 ### Functions
 
+#### createPresignedUploadUrl()
+
+> **createPresignedUploadUrl**(`client`, `fileName`, `path`, `bucket`, `expirySeconds`): `Promise`\<`string`\>
+
+Defined in: [sdk/minio/src/helpers/functions.ts:242](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/functions.ts#L242)
+
+Creates a presigned upload URL for direct browser uploads
+
+##### Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `client` | `Client` | `undefined` | The MinIO client to use |
+| `fileName` | `string` | `undefined` | The file name to use |
+| `path` | `string` | `""` | Optional path/folder |
+| `bucket` | `string` | `DEFAULT_BUCKET` | Optional bucket name (defaults to DEFAULT_BUCKET) |
+| `expirySeconds` | `number` | `3600` | How long the URL should be valid for |
+
+##### Returns
+
+`Promise`\<`string`\>
+
+Presigned URL for PUT operation
+
+##### Throws
+
+Will throw an error if URL creation fails or client initialization fails
+
+##### Example
+
+```ts
+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
+});
+```
+
+***
+
 #### createServerMinioClient()
 
 > **createServerMinioClient**(`options`): `object`
 
-Defined in: [sdk/minio/src/minio.ts:23](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/minio.ts#L23)
+Defined in: [sdk/minio/src/minio.ts:23](https://github.com/settlemint/sdk/blob/v2.1.5/sdk/minio/src/minio.ts#L23)
 
 Creates a MinIO client for server-side use with authentication.
 
@@ -68,7 +136,7 @@ An object containing the initialized MinIO client
 
 | Name | Type | Defined in |
 | ------ | ------ | ------ |
-| `client` | `Client` | [sdk/minio/src/minio.ts:23](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/minio.ts#L23) |
+| `client` | `Client` | [sdk/minio/src/minio.ts:23](https://github.com/settlemint/sdk/blob/v2.1.5/sdk/minio/src/minio.ts#L23) |
 
 ##### Throws
 
@@ -87,6 +155,224 @@ const { client } = createServerMinioClient({
 client.listBuckets();
 ```
 
+***
+
+#### deleteFile()
+
+> **deleteFile**(`client`, `fileId`, `bucket`): `Promise`\<`boolean`\>
+
+Defined in: [sdk/minio/src/helpers/functions.ts:195](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/functions.ts#L195)
+
+Deletes a file from storage
+
+##### Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `client` | `Client` | `undefined` | The MinIO client to use |
+| `fileId` | `string` | `undefined` | The file identifier/path |
+| `bucket` | `string` | `DEFAULT_BUCKET` | Optional bucket name (defaults to DEFAULT_BUCKET) |
+
+##### Returns
+
+`Promise`\<`boolean`\>
+
+Success status
+
+##### Throws
+
+Will throw an error if deletion fails or client initialization fails
+
+##### Example
+
+```ts
+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");
+```
+
+***
+
+#### getFileById()
+
+> **getFileById**(`client`, `fileId`, `bucket`): `Promise`\<\{ `contentType`: `string`; `etag`: `string`; `id`: `string`; `name`: `string`; `size`: `number`; `uploadedAt`: `string`; `url?`: `string`; \}\>
+
+Defined in: [sdk/minio/src/helpers/functions.ts:122](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/functions.ts#L122)
+
+Gets a single file by its object name
+
+##### Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `client` | `Client` | `undefined` | The MinIO client to use |
+| `fileId` | `string` | `undefined` | The file identifier/path |
+| `bucket` | `string` | `DEFAULT_BUCKET` | Optional bucket name (defaults to DEFAULT_BUCKET) |
+
+##### Returns
+
+`Promise`\<\{ `contentType`: `string`; `etag`: `string`; `id`: `string`; `name`: `string`; `size`: `number`; `uploadedAt`: `string`; `url?`: `string`; \}\>
+
+File metadata with presigned URL
+
+##### Throws
+
+Will throw an error if the file doesn't exist or client initialization fails
+
+##### Example
+
+```ts
+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");
+```
+
+***
+
+#### getFilesList()
+
+> **getFilesList**(`client`, `prefix`, `bucket`): `Promise`\<`object`[]\>
+
+Defined in: [sdk/minio/src/helpers/functions.ts:61](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/functions.ts#L61)
+
+Gets a list of files with optional prefix filter
+
+##### Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `client` | `Client` | `undefined` | The MinIO client to use |
+| `prefix` | `string` | `""` | Optional prefix to filter files (like a folder path) |
+| `bucket` | `string` | `DEFAULT_BUCKET` | Optional bucket name (defaults to DEFAULT_BUCKET) |
+
+##### Returns
+
+`Promise`\<`object`[]\>
+
+Array of file metadata objects
+
+##### Throws
+
+Will throw an error if the operation fails or client initialization fails
+
+##### Example
+
+```ts
+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/");
+```
+
+***
+
+#### uploadFile()
+
+> **uploadFile**(`client`, `buffer`, `objectName`, `contentType`, `bucket`): `Promise`\<\{ `contentType`: `string`; `etag`: `string`; `id`: `string`; `name`: `string`; `size`: `number`; `uploadedAt`: `string`; `url?`: `string`; \}\>
+
+Defined in: [sdk/minio/src/helpers/functions.ts:292](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/functions.ts#L292)
+
+Uploads a buffer directly to storage
+
+##### Parameters
+
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `client` | `Client` | `undefined` | The MinIO client to use |
+| `buffer` | `Buffer` | `undefined` | The buffer to upload |
+| `objectName` | `string` | `undefined` | The full object name/path |
+| `contentType` | `string` | `undefined` | The content type of the file |
+| `bucket` | `string` | `DEFAULT_BUCKET` | Optional bucket name (defaults to DEFAULT_BUCKET) |
+
+##### Returns
+
+`Promise`\<\{ `contentType`: `string`; `etag`: `string`; `id`: `string`; `name`: `string`; `size`: `number`; `uploadedAt`: `string`; `url?`: `string`; \}\>
+
+The uploaded file metadata
+
+##### Throws
+
+Will throw an error if upload fails or client initialization fails
+
+##### Example
+
+```ts
+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");
+```
+
+### Type Aliases
+
+#### FileMetadata
+
+> **FileMetadata** = [`Static`](#static)\<*typeof* [`FileMetadataSchema`](#filemetadataschema)\>
+
+Defined in: [sdk/minio/src/helpers/schema.ts:29](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/schema.ts#L29)
+
+Type representing file metadata after validation.
+
+***
+
+#### Static\<T\>
+
+> **Static**\<`T`\> = [`Static`](#static)\<`T`\>
+
+Defined in: [sdk/minio/src/helpers/schema.ts:8](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/schema.ts#L8)
+
+Helper type to extract the inferred type from a Zod schema.
+
+##### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` *extends* `z.ZodType` | The Zod schema type |
+
+### Variables
+
+#### DEFAULT\_BUCKET
+
+> `const` **DEFAULT\_BUCKET**: `"uploads"` = `"uploads"`
+
+Defined in: [sdk/minio/src/helpers/schema.ts:34](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/schema.ts#L34)
+
+Default bucket name to use for file storage when none is specified.
+
+***
+
+#### FileMetadataSchema
+
+> `const` **FileMetadataSchema**: `ZodObject`\<\{ `contentType`: `ZodString`; `etag`: `ZodString`; `id`: `ZodString`; `name`: `ZodString`; `size`: `ZodNumber`; `uploadedAt`: `ZodString`; `url`: `ZodOptional`\<`ZodString`\>; \}, `"strip"`, `ZodTypeAny`, \{ `contentType`: `string`; `etag`: `string`; `id`: `string`; `name`: `string`; `size`: `number`; `uploadedAt`: `string`; `url?`: `string`; \}, \{ `contentType`: `string`; `etag`: `string`; `id`: `string`; `name`: `string`; `size`: `number`; `uploadedAt`: `string`; `url?`: `string`; \}\>
+
+Defined in: [sdk/minio/src/helpers/schema.ts:16](https://github.com/settlemint/sdk/blob/v2.1.4/sdk/minio/src/helpers/schema.ts#L16)
+
+Schema for file metadata stored in MinIO.
+Defines the structure and validation rules for file information.
+
 ## Contributing
 
 We welcome contributions from the community! Please check out our [Contributing](https://github.com/settlemint/sdk/blob/main/.github/CONTRIBUTING.md) guide to learn how you can help improve the SettleMint SDK through bug reports, feature requests, documentation updates, or code contributions.

package/dist/minio.cjs

@@ -20,31 +20,263 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/minio.ts
 var minio_exports = {};
 __export(minio_exports, {
-  createServerMinioClient: () => createServerMinioClient
+  DEFAULT_BUCKET: () => DEFAULT_BUCKET,
+  createPresignedUploadUrl: () => createPresignedUploadUrl,
+  createServerMinioClient: () => createServerMinioClient,
+  deleteFile: () => deleteFile,
+  getFileById: () => getFileById,
+  getFilesList: () => getFilesList,
+  uploadFile: () => uploadFile
 });
 module.exports = __toCommonJS(minio_exports);
-var import_runtime = require("@settlemint/sdk-utils/runtime");
-var import_validation2 = require("@settlemint/sdk-utils/validation");
+var import_runtime3 = require("@settlemint/sdk-utils/runtime");
+var import_validation3 = require("@settlemint/sdk-utils/validation");
 var import_minio = require("minio");
 
 // src/helpers/client-options.schema.ts
 var import_validation = require("@settlemint/sdk-utils/validation");
 var import_zod = require("zod");
-var ClientOptionsSchema = import_zod.z.object({
+var ServerClientOptionsSchema = import_zod.z.object({
   /** The URL of the MinIO instance to connect to */
-  instance: import_validation.UrlSchema
-});
-var ServerClientOptionsSchema = ClientOptionsSchema.extend({
+  instance: import_validation.UrlSchema,
   /** The MinIO access key used to authenticate with the MinIO server */
   accessKey: import_zod.z.string(),
   /** The MinIO secret key used to authenticate with the MinIO server */
   secretKey: import_zod.z.string()
 });
 
+// src/helpers/functions.ts
+var import_runtime2 = require("@settlemint/sdk-utils/runtime");
+var import_validation2 = require("@settlemint/sdk-utils/validation");
+
+// src/helpers/executor.ts
+var import_runtime = require("@settlemint/sdk-utils/runtime");
+async function executeMinioOperation(client, operation) {
+  (0, import_runtime.ensureServer)();
+  return operation.execute(client);
+}
+
+// src/helpers/operations.ts
+function createListObjectsOperation(bucket, prefix = "") {
+  return {
+    execute: async (client) => {
+      const objectsStream = client.listObjects(bucket, prefix, true);
+      const objects = [];
+      return new Promise((resolve, reject) => {
+        objectsStream.on("data", (obj) => {
+          if (obj.name && typeof obj.size === "number" && obj.etag && obj.lastModified) {
+            objects.push({
+              name: obj.name,
+              prefix: obj.prefix,
+              size: obj.size,
+              etag: obj.etag,
+              lastModified: obj.lastModified
+            });
+          }
+        });
+        objectsStream.on("error", (err) => {
+          reject(err);
+        });
+        objectsStream.on("end", () => {
+          resolve(objects);
+        });
+      });
+    }
+  };
+}
+function createStatObjectOperation(bucket, objectName) {
+  return {
+    execute: async (client) => {
+      return client.statObject(bucket, objectName);
+    }
+  };
+}
+function createDeleteOperation(bucket, objectName) {
+  return {
+    execute: async (client) => {
+      return client.removeObject(bucket, objectName);
+    }
+  };
+}
+function createPresignedUrlOperation(bucket, objectName, expirySeconds) {
+  return {
+    execute: async (client) => {
+      return client.presignedGetObject(bucket, objectName, expirySeconds);
+    }
+  };
+}
+function createPresignedPutOperation(bucket, objectName, expirySeconds) {
+  return {
+    execute: async (client) => {
+      return client.presignedPutObject(bucket, objectName, expirySeconds);
+    }
+  };
+}
+function createSimpleUploadOperation(client) {
+  return async (buffer, bucket, objectName, metadata) => {
+    return client.putObject(bucket, objectName, buffer, void 0, metadata);
+  };
+}
+
+// src/helpers/schema.ts
+var import_zod2 = require("zod");
+var FileMetadataSchema = import_zod2.z.object({
+  id: import_zod2.z.string(),
+  name: import_zod2.z.string(),
+  contentType: import_zod2.z.string(),
+  size: import_zod2.z.number(),
+  uploadedAt: import_zod2.z.string().datetime(),
+  etag: import_zod2.z.string(),
+  url: import_zod2.z.string().url().optional()
+});
+var DEFAULT_BUCKET = "uploads";
+
+// src/helpers/functions.ts
+function normalizePath(path, fileName) {
+  if (path.length > 1e3) {
+    throw new Error("Path is too long");
+  }
+  const cleanPath = path.replace(/\/+$/, "");
+  if (!cleanPath) {
+    return fileName;
+  }
+  return `${cleanPath}/${fileName}`;
+}
+async function getFilesList(client, prefix = "", bucket = DEFAULT_BUCKET) {
+  (0, import_runtime2.ensureServer)();
+  console.log(`Listing files with prefix: "${prefix}" in bucket: "${bucket}"`);
+  try {
+    const listOperation = createListObjectsOperation(bucket, prefix);
+    const objects = await executeMinioOperation(client, listOperation);
+    console.log(`Found ${objects.length} files in MinIO`);
+    const fileObjects = await Promise.all(
+      objects.map(async (obj) => {
+        const presignedUrlOperation = createPresignedUrlOperation(
+          bucket,
+          obj.name,
+          3600
+          // 1 hour expiry
+        );
+        const url = await executeMinioOperation(client, presignedUrlOperation);
+        return {
+          id: obj.name,
+          name: obj.name.split("/").pop() || obj.name,
+          contentType: "application/octet-stream",
+          // Default type
+          size: obj.size,
+          uploadedAt: obj.lastModified.toISOString(),
+          etag: obj.etag,
+          url
+        };
+      })
+    );
+    return (0, import_validation2.validate)(FileMetadataSchema.array(), fileObjects);
+  } catch (error) {
+    console.error("Failed to list files:", error);
+    throw new Error(`Failed to list files: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function getFileById(client, fileId, bucket = DEFAULT_BUCKET) {
+  (0, import_runtime2.ensureServer)();
+  console.log(`Getting file details for: ${fileId} in bucket: ${bucket}`);
+  try {
+    const statOperation = createStatObjectOperation(bucket, fileId);
+    const statResult = await executeMinioOperation(client, statOperation);
+    const presignedUrlOperation = createPresignedUrlOperation(
+      bucket,
+      fileId,
+      3600
+      // 1 hour expiry
+    );
+    const url = await executeMinioOperation(client, presignedUrlOperation);
+    let size = 0;
+    if (statResult.metaData["content-length"]) {
+      const parsedSize = Number.parseInt(statResult.metaData["content-length"], 10);
+      if (!Number.isNaN(parsedSize)) {
+        size = parsedSize;
+      }
+    } else if (typeof statResult.size === "number" && !Number.isNaN(statResult.size)) {
+      size = statResult.size;
+    }
+    const fileMetadata = {
+      id: fileId,
+      name: fileId.split("/").pop() || fileId,
+      contentType: statResult.metaData["content-type"] || "application/octet-stream",
+      size,
+      uploadedAt: statResult.lastModified.toISOString(),
+      etag: statResult.etag,
+      url
+    };
+    return (0, import_validation2.validate)(FileMetadataSchema, fileMetadata);
+  } catch (error) {
+    console.error(`Failed to get file ${fileId}:`, error);
+    throw new Error(`Failed to get file ${fileId}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function deleteFile(client, fileId, bucket = DEFAULT_BUCKET) {
+  (0, import_runtime2.ensureServer)();
+  try {
+    const deleteOperation = createDeleteOperation(bucket, fileId);
+    await executeMinioOperation(client, deleteOperation);
+    return true;
+  } catch (error) {
+    console.error(`Failed to delete file ${fileId}:`, error);
+    throw new Error(`Failed to delete file ${fileId}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function createPresignedUploadUrl(client, fileName, path = "", bucket = DEFAULT_BUCKET, expirySeconds = 3600) {
+  (0, import_runtime2.ensureServer)();
+  try {
+    const safeFileName = fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
+    const objectName = normalizePath(path, safeFileName);
+    const presignedPutOperation = createPresignedPutOperation(bucket, objectName, expirySeconds);
+    const url = await executeMinioOperation(client, presignedPutOperation);
+    if (!url) {
+      throw new Error("Failed to generate presigned upload URL");
+    }
+    return url;
+  } catch (error) {
+    console.error("Failed to create presigned upload URL:", error);
+    throw new Error(`Failed to create presigned upload URL: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function uploadFile(client, buffer, objectName, contentType, bucket = DEFAULT_BUCKET) {
+  (0, import_runtime2.ensureServer)();
+  try {
+    const metadata = {
+      "content-type": contentType,
+      "upload-time": (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const simpleUploadFn = createSimpleUploadOperation(client);
+    const result = await simpleUploadFn(buffer, bucket, objectName, metadata);
+    const presignedUrlOperation = createPresignedUrlOperation(
+      bucket,
+      objectName,
+      3600
+      // 1 hour expiry
+    );
+    const url = await executeMinioOperation(client, presignedUrlOperation);
+    const fileName = objectName.split("/").pop() || objectName;
+    const fileMetadata = {
+      id: objectName,
+      name: fileName,
+      contentType,
+      size: buffer.length,
+      uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      etag: result.etag,
+      url
+    };
+    return (0, import_validation2.validate)(FileMetadataSchema, fileMetadata);
+  } catch (error) {
+    console.error("Failed to upload file:", error);
+    throw new Error(`Failed to upload file: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 // src/minio.ts
 function createServerMinioClient(options) {
-  (0, import_runtime.ensureServer)();
-  const validatedOptions = (0, import_validation2.validate)(ServerClientOptionsSchema, options);
+  (0, import_runtime3.ensureServer)();
+  const validatedOptions = (0, import_validation3.validate)(ServerClientOptionsSchema, options);
   const url = new URL(validatedOptions.instance);
   return {
     client: new import_minio.Client({
@@ -59,6 +291,12 @@ function createServerMinioClient(options) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createServerMinioClient
+  DEFAULT_BUCKET,
+  createPresignedUploadUrl,
+  createServerMinioClient,
+  deleteFile,
+  getFileById,
+  getFilesList,
+  uploadFile
 });
 //# sourceMappingURL=minio.cjs.map