@dimah-s3/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamidreza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @dimah-s3/server
+
+Presigned S3 handlers with HTTP `handler`, direct `api`, and an optional `plugins` array.
+
+Full documentation: [dimah-s3.dev](https://dimah-s3.dev/docs/server)
+
+## Install
+
+```bash
+pnpm add @dimah-s3/server @aws-sdk/client-s3
+```
+
+## Minimal setup
+
+```ts
+import { dimahS3 } from "@dimah-s3/server";
+import { s3Client, defaultBucket } from "@/lib/s3-client";
+
+export const s3 = dimahS3({
+  s3: s3Client,
+  defaultBucket,
+  upload: { enabled: true },
+  download: { enabled: false },
+  delete: { enabled: false },
+  multipart: { enabled: false },
+});
+```
+
+```ts
+import { toNextJsHandler } from "@dimah-s3/server/next";
+import { s3 } from "@/lib/s3";
+
+export const { GET, POST, DELETE } = toNextJsHandler(s3);
+```
+
+Server-side (no HTTP):
+
+```ts
+await s3.api.download(key, { headers: await headers() });
+```
+
+Optional persistence: add `db()` from [`@dimah-s3/db`](../db) to `plugins`.
+
+## License
+
+MIT

package/dist/adapters/next.d.ts

@@ -0,0 +1,18 @@
+import type { DimahS3 } from "../dimah-s3";
+/**
+ * Adapt a {@link DimahS3} instance to Next.js App Router route handlers.
+ *
+ * @example
+ * ```ts
+ * import { toNextJsHandler } from "@dimah-s3/server/next";
+ * import { s3 } from "@/lib/s3";
+ *
+ * export const { GET, POST, DELETE } = toNextJsHandler(s3);
+ * ```
+ */
+export declare function toNextJsHandler(s3: Pick<DimahS3<Record<string, unknown>>, "handler">): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+    DELETE: (request: Request) => Promise<Response>;
+};
+//# sourceMappingURL=next.d.ts.map

package/dist/adapters/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../../src/adapters/next.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC;IAGnD,GAAG;IACH,IAAI;IACJ,MAAM;EAET"}

package/dist/adapters/next.js

@@ -0,0 +1,12 @@
+// src/adapters/next.ts
+function toNextJsHandler(s3) {
+  return {
+    GET: s3.handler,
+    POST: s3.handler,
+    DELETE: s3.handler
+  };
+}
+
+export { toNextJsHandler };
+//# sourceMappingURL=next.js.map
+//# sourceMappingURL=next.js.map

package/dist/adapters/next.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/next.ts"],"names":[],"mappings":";AAaO,SAAS,gBACd,EAAA,EACA;AACA,EAAA,OAAO;AAAA,IACL,KAAK,EAAA,CAAG,OAAA;AAAA,IACR,MAAM,EAAA,CAAG,OAAA;AAAA,IACT,QAAQ,EAAA,CAAG;AAAA,GACb;AACF","file":"next.js","sourcesContent":["import type { DimahS3 } from \"../dimah-s3\";\n\n/**\n * Adapt a {@link DimahS3} instance to Next.js App Router route handlers.\n *\n * @example\n * ```ts\n * import { toNextJsHandler } from \"@dimah-s3/server/next\";\n * import { s3 } from \"@/lib/s3\";\n *\n * export const { GET, POST, DELETE } = toNextJsHandler(s3);\n * ```\n */\nexport function toNextJsHandler(\n  s3: Pick<DimahS3<Record<string, unknown>>, \"handler\">,\n) {\n  return {\n    GET: s3.handler,\n    POST: s3.handler,\n    DELETE: s3.handler,\n  };\n}\n"]}

package/dist/adapters/node.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { DimahS3 } from "../dimah-s3";
+/**
+ * Adapt a {@link DimahS3} instance to Node.js `http` / Express-style handlers.
+ *
+ * @example
+ * ```ts
+ * import { createServer } from "node:http";
+ * import { toNodeHandler } from "@dimah-s3/server/node";
+ * import { s3 } from "./s3";
+ *
+ * createServer(toNodeHandler(s3)).listen(3000);
+ * ```
+ */
+export declare function toNodeHandler(s3: Pick<DimahS3<Record<string, unknown>>, "handler">): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//# sourceMappingURL=node.d.ts.map

package/dist/adapters/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/adapters/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAuD3C;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,SAAS,CAAC,SAElC,eAAe,OAAO,cAAc,KAAG,OAAO,CAAC,IAAI,CAAC,CAqBxE"}

package/dist/adapters/node.js

@@ -0,0 +1,116 @@
+import { DimahS3Error, S3_ERROR_CODES } from '@dimah-s3/core';
+
+// src/errors.ts
+var errors = {
+  notFound: () => new DimahS3Error("Not Found", 404, { code: S3_ERROR_CODES.NOT_FOUND }),
+  invalidJson: () => new DimahS3Error("Invalid JSON payload", 400, {
+    code: S3_ERROR_CODES.INVALID_JSON
+  }),
+  forbidden: () => new DimahS3Error("Forbidden", 403, { code: S3_ERROR_CODES.FORBIDDEN }),
+  internalError: () => new DimahS3Error("Internal server error", 500, {
+    code: S3_ERROR_CODES.INTERNAL_ERROR
+  }),
+  objectNotFound: () => new DimahS3Error("Object not found", 404, {
+    code: S3_ERROR_CODES.OBJECT_NOT_FOUND
+  }),
+  s3NetworkError: (code) => new DimahS3Error(
+    `S3 endpoint unreachable (${code}): check your endpoint URL and network connectivity`,
+    502,
+    { code: S3_ERROR_CODES.S3_NETWORK_ERROR, params: { code } }
+  ),
+  fieldRequired: (name) => new DimahS3Error(`${name} is required`, 400, {
+    code: S3_ERROR_CODES.FIELD_REQUIRED,
+    params: { name }
+  }),
+  /** Missing `key` on query-string routes (download / delete / list-parts). */
+  keyRequired: () => new DimahS3Error("key query parameter is required", 400, {
+    code: S3_ERROR_CODES.KEY_REQUIRED
+  }),
+  uploadIdRequired: () => new DimahS3Error("uploadId is required", 400, {
+    code: S3_ERROR_CODES.UPLOAD_ID_REQUIRED
+  }),
+  partNumberInvalid: () => new DimahS3Error("partNumber must be a positive integer", 400, {
+    code: S3_ERROR_CODES.PART_NUMBER_INVALID
+  }),
+  partsRequired: () => new DimahS3Error("At least one valid part is required", 400, {
+    code: S3_ERROR_CODES.PARTS_REQUIRED
+  }),
+  fileSizeRequiredUpload: () => new DimahS3Error(
+    "fileSize is required when upload.requireFileSize is enabled",
+    400,
+    { code: S3_ERROR_CODES.FILE_SIZE_REQUIRED_UPLOAD }
+  ),
+  fileSizeRequiredMultipart: () => new DimahS3Error(
+    "fileSize is required when multipart.requireFileSize is enabled",
+    400,
+    { code: S3_ERROR_CODES.FILE_SIZE_REQUIRED_MULTIPART }
+  )
+};
+
+// src/adapters/node.ts
+function collectBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+function toWebRequest(req, body) {
+  const host = req.headers.host ?? "localhost";
+  const protocol = req.socket.encrypted === true ? "https" : "http";
+  const url = new URL(req.url ?? "/", `${protocol}://${host}`);
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) headers.append(key, v);
+    } else {
+      headers.set(key, value);
+    }
+  }
+  const method = (req.method ?? "GET").toUpperCase();
+  const init = { method, headers };
+  if (method !== "GET" && method !== "HEAD") {
+    init.body = new Uint8Array(body);
+    init.duplex = "half";
+  }
+  return new Request(url, init);
+}
+async function writeWebResponse(res, response) {
+  res.statusCode = response.status;
+  response.headers.forEach((value, key) => {
+    res.setHeader(key, value);
+  });
+  const buffer = Buffer.from(await response.arrayBuffer());
+  res.end(buffer);
+}
+function toNodeHandler(s3) {
+  return async (req, res) => {
+    try {
+      const body = await collectBody(req);
+      const request = toWebRequest(req, body);
+      const response = await s3.handler(request);
+      await writeWebResponse(res, response);
+    } catch (err) {
+      console.error("[S3 API]", err);
+      if (!res.headersSent) {
+        const fallback = errors.internalError();
+        res.statusCode = fallback.status;
+        res.setHeader("Content-Type", "application/json");
+        res.end(
+          JSON.stringify({
+            message: fallback.message,
+            code: fallback.code
+          })
+        );
+      }
+    }
+  };
+}
+
+export { toNodeHandler };
+//# sourceMappingURL=node.js.map
+//# sourceMappingURL=node.js.map

package/dist/adapters/node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/adapters/node.ts"],"names":[],"mappings":"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","file":"node.js","sourcesContent":["import { DimahS3Error, S3_ERROR_CODES, type S3ErrorCode } from \"@dimah-s3/core\";\n\nexport { DimahS3Error };\n\n/** English API errors with stable codes for client-side localization. */\nexport const errors = {\n  notFound: () =>\n    new DimahS3Error(\"Not Found\", 404, { code: S3_ERROR_CODES.NOT_FOUND }),\n\n  invalidJson: () =>\n    new DimahS3Error(\"Invalid JSON payload\", 400, {\n      code: S3_ERROR_CODES.INVALID_JSON,\n    }),\n\n  forbidden: () =>\n    new DimahS3Error(\"Forbidden\", 403, { code: S3_ERROR_CODES.FORBIDDEN }),\n\n  internalError: () =>\n    new DimahS3Error(\"Internal server error\", 500, {\n      code: S3_ERROR_CODES.INTERNAL_ERROR,\n    }),\n\n  objectNotFound: () =>\n    new DimahS3Error(\"Object not found\", 404, {\n      code: S3_ERROR_CODES.OBJECT_NOT_FOUND,\n    }),\n\n  s3NetworkError: (code: string) =>\n    new DimahS3Error(\n      `S3 endpoint unreachable (${code}): check your endpoint URL and network connectivity`,\n      502,\n      { code: S3_ERROR_CODES.S3_NETWORK_ERROR, params: { code } },\n    ),\n\n  fieldRequired: (name: string) =>\n    new DimahS3Error(`${name} is required`, 400, {\n      code: S3_ERROR_CODES.FIELD_REQUIRED,\n      params: { name },\n    }),\n\n  /** Missing `key` on query-string routes (download / delete / list-parts). */\n  keyRequired: () =>\n    new DimahS3Error(\"key query parameter is required\", 400, {\n      code: S3_ERROR_CODES.KEY_REQUIRED,\n    }),\n\n  uploadIdRequired: () =>\n    new DimahS3Error(\"uploadId is required\", 400, {\n      code: S3_ERROR_CODES.UPLOAD_ID_REQUIRED,\n    }),\n\n  partNumberInvalid: () =>\n    new DimahS3Error(\"partNumber must be a positive integer\", 400, {\n      code: S3_ERROR_CODES.PART_NUMBER_INVALID,\n    }),\n\n  partsRequired: () =>\n    new DimahS3Error(\"At least one valid part is required\", 400, {\n      code: S3_ERROR_CODES.PARTS_REQUIRED,\n    }),\n\n  fileSizeRequiredUpload: () =>\n    new DimahS3Error(\n      \"fileSize is required when upload.requireFileSize is enabled\",\n      400,\n      { code: S3_ERROR_CODES.FILE_SIZE_REQUIRED_UPLOAD },\n    ),\n\n  fileSizeRequiredMultipart: () =>\n    new DimahS3Error(\n      \"fileSize is required when multipart.requireFileSize is enabled\",\n      400,\n      { code: S3_ERROR_CODES.FILE_SIZE_REQUIRED_MULTIPART },\n    ),\n} as const;\n\nexport type ServerErrors = typeof errors;\n\n/** Trim and require a non-empty string; throws {@link errors.fieldRequired}. */\nexport function requireString(value: unknown, name: string): string {\n  const trimmed = typeof value === \"string\" ? value.trim() : \"\";\n  if (!trimmed) throw errors.fieldRequired(name);\n  return trimmed;\n}\n\nfunction statusOf(err: unknown, fallback: number): number {\n  return typeof (err as { status?: unknown })?.status === \"number\"\n    ? (err as { status: number }).status\n    : fallback;\n}\n\n/**\n * Convert hook/S3 throws into {@link DimahS3Error}.\n *\n * - Existing {@link DimahS3Error} instances are preserved (including subclasses).\n * - Plain `Error`s keep their message; `code` is only applied when provided\n *   (omit it so clients show the custom English message instead of a mapped\n *   library string).\n */\nexport function toDimahS3Error(\n  err: unknown,\n  fallbackMessage: string,\n  fallbackStatus = 403,\n  options?: { code?: S3ErrorCode | string },\n): DimahS3Error {\n  if (err instanceof DimahS3Error) return err;\n\n  const message =\n    err instanceof Error && err.message.trim() ? err.message : fallbackMessage;\n  const status = statusOf(err, fallbackStatus);\n\n  return new DimahS3Error(message, status, {\n    cause: err instanceof Error ? err : undefined,\n    ...(options?.code !== undefined ? { code: options.code } : {}),\n  });\n}\n","import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport type { DimahS3 } from \"../dimah-s3\";\nimport { errors } from \"../errors\";\n\nfunction collectBody(req: IncomingMessage): Promise<Buffer> {\n  return new Promise((resolve, reject) => {\n    const chunks: Buffer[] = [];\n    req.on(\"data\", (chunk: Buffer | string) => {\n      chunks.push(typeof chunk === \"string\" ? Buffer.from(chunk) : chunk);\n    });\n    req.on(\"end\", () => resolve(Buffer.concat(chunks)));\n    req.on(\"error\", reject);\n  });\n}\n\nfunction toWebRequest(req: IncomingMessage, body: Buffer): Request {\n  const host = req.headers.host ?? \"localhost\";\n  const protocol =\n    (req.socket as { encrypted?: boolean }).encrypted === true\n      ? \"https\"\n      : \"http\";\n  const url = new URL(req.url ?? \"/\", `${protocol}://${host}`);\n\n  const headers = new Headers();\n  for (const [key, value] of Object.entries(req.headers)) {\n    if (value == null) continue;\n    if (Array.isArray(value)) {\n      for (const v of value) headers.append(key, v);\n    } else {\n      headers.set(key, value);\n    }\n  }\n\n  const method = (req.method ?? \"GET\").toUpperCase();\n  const init: RequestInit = { method, headers };\n  if (method !== \"GET\" && method !== \"HEAD\") {\n    init.body = new Uint8Array(body);\n    // @ts-expect-error Node fetch duplex for streaming bodies\n    init.duplex = \"half\";\n  }\n\n  return new Request(url, init);\n}\n\nasync function writeWebResponse(\n  res: ServerResponse,\n  response: Response,\n): Promise<void> {\n  res.statusCode = response.status;\n  response.headers.forEach((value, key) => {\n    res.setHeader(key, value);\n  });\n  const buffer = Buffer.from(await response.arrayBuffer());\n  res.end(buffer);\n}\n\n/**\n * Adapt a {@link DimahS3} instance to Node.js `http` / Express-style handlers.\n *\n * @example\n * ```ts\n * import { createServer } from \"node:http\";\n * import { toNodeHandler } from \"@dimah-s3/server/node\";\n * import { s3 } from \"./s3\";\n *\n * createServer(toNodeHandler(s3)).listen(3000);\n * ```\n */\nexport function toNodeHandler(\n  s3: Pick<DimahS3<Record<string, unknown>>, \"handler\">,\n) {\n  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {\n    try {\n      const body = await collectBody(req);\n      const request = toWebRequest(req, body);\n      const response = await s3.handler(request);\n      await writeWebResponse(res, response);\n    } catch (err) {\n      console.error(\"[S3 API]\", err);\n      if (!res.headersSent) {\n        const fallback = errors.internalError();\n        res.statusCode = fallback.status;\n        res.setHeader(\"Content-Type\", \"application/json\");\n        res.end(\n          JSON.stringify({\n            message: fallback.message,\n            code: fallback.code,\n          }),\n        );\n      }\n    }\n  };\n}\n"]}

package/dist/api.d.ts

@@ -0,0 +1,5 @@
+import type { S3Api } from "@dimah-s3/core";
+import type { DimahS3Config } from "./types";
+/** Direct `S3Api` backed by the same procedures as the HTTP handler. */
+export declare function createServerApi(config: DimahS3Config): S3Api;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAkB7C,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,KAAK,CAqF5D"}

package/dist/dimah-s3.d.ts

@@ -0,0 +1,36 @@
+import type { S3Api } from "@dimah-s3/core";
+import { type DimahS3Plugin, type PluginContextMap } from "./plugin";
+import type { DimahS3Config } from "./types";
+export type DimahS3<C extends Record<string, unknown> = Record<string, unknown>> = {
+    /** Framework-agnostic HTTP handler (`Request` → `Response`). */
+    handler: (request: Request) => Promise<Response>;
+    /** Same `S3Api` as the browser client — call from Server Actions / RSC without HTTP. */
+    api: S3Api;
+    /** Plugin contexts keyed by plugin id. */
+    context: C;
+    /** Lookup a registered plugin by id. */
+    getPlugin: (id: string) => DimahS3Plugin | undefined;
+} & C;
+/**
+ * Create a dimah-s3 server instance.
+ *
+ * Plugin contexts are available on `s3.context[id]` and flattened onto the
+ * instance itself (`s3.db` when the `db` plugin is registered, etc.).
+ *
+ * @example
+ * ```ts
+ * export const s3 = dimahS3({
+ *   s3: s3Client,
+ *   defaultBucket: "my-bucket",
+ *   upload: { enabled: true },
+ * });
+ *
+ * export const { GET, POST, DELETE } = toNextJsHandler(s3);
+ *
+ * await s3.api.download(key, { headers: await headers() });
+ * ```
+ */
+export declare function dimahS3<const P extends readonly DimahS3Plugin[] = []>(config: DimahS3Config & {
+    plugins?: P;
+}): DimahS3<PluginContextMap<P>>;
+//# sourceMappingURL=dimah-s3.d.ts.map

package/dist/dimah-s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dimah-s3.d.ts","sourceRoot":"","sources":["../src/dimah-s3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,MAAM,OAAO,CACjB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzD;IACF,gEAAgE;IAChE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjD,wFAAwF;IACxF,GAAG,EAAE,KAAK,CAAC;IACX,0CAA0C;IAC1C,OAAO,EAAE,CAAC,CAAC;IACX,wCAAwC;IACxC,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;CACtD,GAAG,CAAC,CAAC;AAEN;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,aAAa,EAAE,GAAG,EAAE,EACnE,MAAM,EAAE,aAAa,GAAG;IAAE,OAAO,CAAC,EAAE,CAAC,CAAA;CAAE,GACtC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAgB9B"}

package/dist/errors.d.ts

@@ -0,0 +1,34 @@
+import { DimahS3Error, type S3ErrorCode } from "@dimah-s3/core";
+export { DimahS3Error };
+/** English API errors with stable codes for client-side localization. */
+export declare const errors: {
+    readonly notFound: () => DimahS3Error;
+    readonly invalidJson: () => DimahS3Error;
+    readonly forbidden: () => DimahS3Error;
+    readonly internalError: () => DimahS3Error;
+    readonly objectNotFound: () => DimahS3Error;
+    readonly s3NetworkError: (code: string) => DimahS3Error;
+    readonly fieldRequired: (name: string) => DimahS3Error;
+    /** Missing `key` on query-string routes (download / delete / list-parts). */
+    readonly keyRequired: () => DimahS3Error;
+    readonly uploadIdRequired: () => DimahS3Error;
+    readonly partNumberInvalid: () => DimahS3Error;
+    readonly partsRequired: () => DimahS3Error;
+    readonly fileSizeRequiredUpload: () => DimahS3Error;
+    readonly fileSizeRequiredMultipart: () => DimahS3Error;
+};
+export type ServerErrors = typeof errors;
+/** Trim and require a non-empty string; throws {@link errors.fieldRequired}. */
+export declare function requireString(value: unknown, name: string): string;
+/**
+ * Convert hook/S3 throws into {@link DimahS3Error}.
+ *
+ * - Existing {@link DimahS3Error} instances are preserved (including subclasses).
+ * - Plain `Error`s keep their message; `code` is only applied when provided
+ *   (omit it so clients show the custom English message instead of a mapped
+ *   library string).
+ */
+export declare function toDimahS3Error(err: unknown, fallbackMessage: string, fallbackStatus?: number, options?: {
+    code?: S3ErrorCode | string;
+}): DimahS3Error;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAkB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,yEAAyE;AACzE,eAAO,MAAM,MAAM;aACjB,QAAQ;aAGR,WAAW;aAKX,SAAS;aAGT,aAAa;aAKb,cAAc;aAKd,cAAc,SAAS,MAAM;aAO7B,aAAa,SAAS,MAAM;IAM5B,6EAA6E;aAC7E,WAAW;aAKX,gBAAgB;aAKhB,iBAAiB;aAKjB,aAAa;aAKb,sBAAsB;aAOtB,yBAAyB;CAMjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,OAAO,MAAM,CAAC;AAEzC,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlE;AAQD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,MAAM,EACvB,cAAc,SAAM,EACpB,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;CAAE,GACxC,YAAY,CAWd"}

package/dist/handler.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedPluginEndpoint } from "./plugin/types";
+import type { DimahS3Config } from "./types";
+/** Framework-agnostic HTTP router (`Request` → `Response`). */
+export declare function createHandler(config: DimahS3Config, basePath?: string, pluginEndpoints?: ResolvedPluginEndpoint[]): (request: Request) => Promise<Response>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAsE7C,+DAA+D;AAC/D,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,QAAQ,GAAE,MAAyB,EACnC,eAAe,GAAE,sBAAsB,EAAO,2CAyC/C"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,3 @@
+export { isAwsNotFound } from "./is-aws-not-found";
+export { resolveObjectAcl } from "./resolve-object-acl";
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/helpers/is-aws-not-found.d.ts

@@ -0,0 +1,3 @@
+/** True when an AWS SDK throw means the object (or key) does not exist. */
+export declare function isAwsNotFound(err: unknown): boolean;
+//# sourceMappingURL=is-aws-not-found.d.ts.map

package/dist/helpers/is-aws-not-found.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-aws-not-found.d.ts","sourceRoot":"","sources":["../../src/helpers/is-aws-not-found.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAanD"}

package/dist/helpers/is-aws-not-found.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=is-aws-not-found.test.d.ts.map

package/dist/helpers/is-aws-not-found.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-aws-not-found.test.d.ts","sourceRoot":"","sources":["../../src/helpers/is-aws-not-found.test.ts"],"names":[],"mappings":""}

package/dist/helpers/resolve-object-acl.d.ts

@@ -0,0 +1,10 @@
+import { type S3Client } from "@aws-sdk/client-s3";
+/**
+ * Determines the ACL of an S3 object by querying `GetObjectAcl`.
+ *
+ * Returns `"public-read"` when the `AllUsers` grantee has `READ` or
+ * `FULL_CONTROL` permission, `"private"` when ACL is resolvable but not public,
+ * and `undefined` when ACL cannot be resolved (e.g. unsupported providers).
+ */
+export declare function resolveObjectAcl(s3: S3Client, bucket: string, key: string, timeoutMs?: number): Promise<"public-read" | "private" | undefined>;
+//# sourceMappingURL=resolve-object-acl.d.ts.map

package/dist/helpers/resolve-object-acl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-object-acl.d.ts","sourceRoot":"","sources":["../../src/helpers/resolve-object-acl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAIxE;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,MAAsC,GAChD,OAAO,CAAC,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC,CAoBhD"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { dimahS3 } from "./dimah-s3";
+export type { DimahS3 } from "./dimah-s3";
+export { DimahS3Error, errors } from "./errors";
+export type { ServerErrors } from "./errors";
+export { resolveObjectAcl } from "./helpers/resolve-object-acl";
+export { applyPlugins, chainHooks, createEndpoint, definePlugin, FEATURE_HOOK_KEYS, RESERVED_PLUGIN_IDS, } from "./plugin";
+export type { AppliedPlugins, DimahS3Plugin, DimahS3PluginHooks, FeatureName, PluginContextMap, PluginEndpoint, PluginEndpointContext, PluginInitEnv, ReservedPluginId, ResolvedPluginEndpoint, } from "./plugin";
+export type { DimahS3Config, UploadConfig, DownloadConfig, DeleteConfig, MultipartConfig, GuardContext, UploadPresignGuardContext, UploadOnPresignedContext, UploadConfirmGuardContext, UploadOnConfirmedContext, UploadOnUploadConfirmedContext, DownloadPresignGuardContext, DownloadOnPresignedContext, DeleteGuardContext, DeleteOnDeletedContext, MultipartUploadContext, MultipartInitGuardContext, MultipartGuardContext, MultipartPartGuardContext, MultipartCompleteGuardContext, MultipartAbortGuardContext, MultipartListGuardContext, MultipartOnInitContext, MultipartOnCompleteContext, MultipartOnAbortContext, MultipartOnListContext, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,EACL,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,8BAA8B,EAC9B,2BAA2B,EAC3B,0BAA0B,EAC1B,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,EACzB,6BAA6B,EAC7B,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,SAAS,CAAC"}