naystack 1.5.9 → 1.5.10

package/dist/env.d.mts

@@ -1,24 +1,85 @@
+/**
+ * Enum of all environment variable keys used by the naystack stack.
+ * Use with {@link getEnv} or {@link getEnvValue} to read these variables.
+ *
+ * @category Environment
+ */
 declare enum EnvVariable {
+    /** GraphQL endpoint URL (client-side, e.g. `/api/graphql`). */
     NEXT_PUBLIC_GRAPHQL_ENDPOINT = "NEXT_PUBLIC_GRAPHQL_ENDPOINT",
+    /** Email auth endpoint URL (client-side, e.g. `/api/email`). */
     NEXT_PUBLIC_EMAIL_AUTH_ENDPOINT = "NEXT_PUBLIC_EMAIL_AUTH_ENDPOINT",
+    /** Google OAuth endpoint URL (client-side, e.g. `/api/google`). */
     NEXT_PUBLIC_GOOGLE_AUTH_ENDPOINT = "NEXT_PUBLIC_GOOGLE_AUTH_ENDPOINT",
+    /** Instagram OAuth endpoint URL (client-side, e.g. `/api/instagram`). */
     NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT = "NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT",
+    /** File upload endpoint URL (client-side, e.g. `/api/file`). */
     NEXT_PUBLIC_FILE_ENDPOINT = "NEXT_PUBLIC_FILE_ENDPOINT",
+    /** Base URL of the app (e.g. `https://yourapp.com`). Used for SEO and Apple Web App metadata. */
     NEXT_PUBLIC_BASE_URL = "NEXT_PUBLIC_BASE_URL",
+    /** Secret key for signing JWT refresh tokens. */
     REFRESH_KEY = "REFRESH_KEY",
+    /** Secret key for signing JWT access tokens. */
     SIGNING_KEY = "SIGNING_KEY",
+    /** Instagram app client secret (from Meta Developer Portal). */
     INSTAGRAM_CLIENT_SECRET = "INSTAGRAM_CLIENT_SECRET",
+    /** Instagram app client id (from Meta Developer Portal). */
     INSTAGRAM_CLIENT_ID = "INSTAGRAM_CLIENT_ID",
+    /** Google OAuth client secret (from Google Cloud Console). */
     GOOGLE_CLIENT_SECRET = "GOOGLE_CLIENT_SECRET",
+    /** Google OAuth client id (from Google Cloud Console). */
     GOOGLE_CLIENT_ID = "GOOGLE_CLIENT_ID",
+    /** Cloudflare Turnstile secret key (optional — enables captcha on auth routes). */
     TURNSTILE_KEY = "TURNSTILE_KEY",
+    /** AWS access key id for S3. */
     AWS_ACCESS_KEY_ID = "AWS_ACCESS_KEY_ID",
+    /** AWS secret access key for S3. */
     AWS_ACCESS_KEY_SECRET = "AWS_ACCESS_KEY_SECRET",
+    /** AWS region for S3 (e.g. `us-east-1`). */
     AWS_REGION = "AWS_REGION",
+    /** AWS S3 bucket name. */
     AWS_BUCKET = "AWS_BUCKET",
+    /** Node environment (`development`, `production`, etc.). Used for Apollo landing page and introspection. */
     NODE_ENV = "NODE_ENV"
 }
+/**
+ * Reads an environment variable by key. Does **not** throw if the value is missing.
+ *
+ * @param key - One of the {@link EnvVariable} enum values.
+ * @returns The value of the env var, or `undefined` if unset.
+ *
+ * @example
+ * ```ts
+ * import { getEnvValue, EnvVariable } from "naystack/env";
+ *
+ * const region = getEnvValue(EnvVariable.AWS_REGION); // "us-east-1" or undefined
+ * ```
+ *
+ * @category Environment
+ */
 declare const getEnvValue: (key: EnvVariable) => string | undefined;
+/**
+ * Reads an environment variable and **throws** if it's missing (unless `skipCheck` is `true`).
+ * Use this for required configuration values.
+ *
+ * @param key - One of the {@link EnvVariable} enum values.
+ * @param skipCheck - If `true`, the function does **not** throw when the value is missing and returns `string | undefined`.
+ *   Useful for optional vars (e.g. `getEnv(EnvVariable.TURNSTILE_KEY, true)`).
+ * @returns The env value. When `skipCheck` is `true`, the type is `string | undefined`; otherwise `string` (throws before returning if missing).
+ *
+ * @example
+ * ```ts
+ * import { getEnv, EnvVariable } from "naystack/env";
+ *
+ * // Required — throws if missing:
+ * const signingKey = getEnv(EnvVariable.SIGNING_KEY);
+ *
+ * // Optional — returns undefined if missing:
+ * const turnstile = getEnv(EnvVariable.TURNSTILE_KEY, true);
+ * ```
+ *
+ * @category Environment
+ */
 declare function getEnv<T extends boolean = false>(key: EnvVariable, skipCheck?: T): T extends true ? string | undefined : string;
 
 export { EnvVariable, getEnv, getEnvValue };

package/dist/env.d.ts

@@ -1,24 +1,85 @@
+/**
+ * Enum of all environment variable keys used by the naystack stack.
+ * Use with {@link getEnv} or {@link getEnvValue} to read these variables.
+ *
+ * @category Environment
+ */
 declare enum EnvVariable {
+    /** GraphQL endpoint URL (client-side, e.g. `/api/graphql`). */
     NEXT_PUBLIC_GRAPHQL_ENDPOINT = "NEXT_PUBLIC_GRAPHQL_ENDPOINT",
+    /** Email auth endpoint URL (client-side, e.g. `/api/email`). */
     NEXT_PUBLIC_EMAIL_AUTH_ENDPOINT = "NEXT_PUBLIC_EMAIL_AUTH_ENDPOINT",
+    /** Google OAuth endpoint URL (client-side, e.g. `/api/google`). */
     NEXT_PUBLIC_GOOGLE_AUTH_ENDPOINT = "NEXT_PUBLIC_GOOGLE_AUTH_ENDPOINT",
+    /** Instagram OAuth endpoint URL (client-side, e.g. `/api/instagram`). */
     NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT = "NEXT_PUBLIC_INSTAGRAM_AUTH_ENDPOINT",
+    /** File upload endpoint URL (client-side, e.g. `/api/file`). */
     NEXT_PUBLIC_FILE_ENDPOINT = "NEXT_PUBLIC_FILE_ENDPOINT",
+    /** Base URL of the app (e.g. `https://yourapp.com`). Used for SEO and Apple Web App metadata. */
     NEXT_PUBLIC_BASE_URL = "NEXT_PUBLIC_BASE_URL",
+    /** Secret key for signing JWT refresh tokens. */
     REFRESH_KEY = "REFRESH_KEY",
+    /** Secret key for signing JWT access tokens. */
     SIGNING_KEY = "SIGNING_KEY",
+    /** Instagram app client secret (from Meta Developer Portal). */
     INSTAGRAM_CLIENT_SECRET = "INSTAGRAM_CLIENT_SECRET",
+    /** Instagram app client id (from Meta Developer Portal). */
     INSTAGRAM_CLIENT_ID = "INSTAGRAM_CLIENT_ID",
+    /** Google OAuth client secret (from Google Cloud Console). */
     GOOGLE_CLIENT_SECRET = "GOOGLE_CLIENT_SECRET",
+    /** Google OAuth client id (from Google Cloud Console). */
     GOOGLE_CLIENT_ID = "GOOGLE_CLIENT_ID",
+    /** Cloudflare Turnstile secret key (optional — enables captcha on auth routes). */
     TURNSTILE_KEY = "TURNSTILE_KEY",
+    /** AWS access key id for S3. */
     AWS_ACCESS_KEY_ID = "AWS_ACCESS_KEY_ID",
+    /** AWS secret access key for S3. */
     AWS_ACCESS_KEY_SECRET = "AWS_ACCESS_KEY_SECRET",
+    /** AWS region for S3 (e.g. `us-east-1`). */
     AWS_REGION = "AWS_REGION",
+    /** AWS S3 bucket name. */
     AWS_BUCKET = "AWS_BUCKET",
+    /** Node environment (`development`, `production`, etc.). Used for Apollo landing page and introspection. */
     NODE_ENV = "NODE_ENV"
 }
+/**
+ * Reads an environment variable by key. Does **not** throw if the value is missing.
+ *
+ * @param key - One of the {@link EnvVariable} enum values.
+ * @returns The value of the env var, or `undefined` if unset.
+ *
+ * @example
+ * ```ts
+ * import { getEnvValue, EnvVariable } from "naystack/env";
+ *
+ * const region = getEnvValue(EnvVariable.AWS_REGION); // "us-east-1" or undefined
+ * ```
+ *
+ * @category Environment
+ */
 declare const getEnvValue: (key: EnvVariable) => string | undefined;
+/**
+ * Reads an environment variable and **throws** if it's missing (unless `skipCheck` is `true`).
+ * Use this for required configuration values.
+ *
+ * @param key - One of the {@link EnvVariable} enum values.
+ * @param skipCheck - If `true`, the function does **not** throw when the value is missing and returns `string | undefined`.
+ *   Useful for optional vars (e.g. `getEnv(EnvVariable.TURNSTILE_KEY, true)`).
+ * @returns The env value. When `skipCheck` is `true`, the type is `string | undefined`; otherwise `string` (throws before returning if missing).
+ *
+ * @example
+ * ```ts
+ * import { getEnv, EnvVariable } from "naystack/env";
+ *
+ * // Required — throws if missing:
+ * const signingKey = getEnv(EnvVariable.SIGNING_KEY);
+ *
+ * // Optional — returns undefined if missing:
+ * const turnstile = getEnv(EnvVariable.TURNSTILE_KEY, true);
+ * ```
+ *
+ * @category Environment
+ */
 declare function getEnv<T extends boolean = false>(key: EnvVariable, skipCheck?: T): T extends true ? string | undefined : string;
 
 export { EnvVariable, getEnv, getEnvValue };

package/dist/file/client.d.mts

@@ -1,7 +1,59 @@
+/**
+ * Returns a function that uploads a file to your file upload endpoint with the current auth token.
+ * Must be used inside a tree that provides the token (i.e. inside `AuthWrapper`).
+ *
+ * The endpoint is read from `NEXT_PUBLIC_FILE_ENDPOINT` env var. The file is sent as multipart form data
+ * along with a `type` string and optional JSON `data` for metadata.
+ *
+ * @returns A function `(file, type, data?) => Promise<FileUploadResponseType | null>`.
+ *   - `file` — `File` or `Blob` to upload.
+ *   - `type` — String category (e.g. `"avatar"`, `"DealDocument"`); sent as form field `type`.
+ *   - `data` — Optional JSON-serializable object for metadata; sent as form field `data`.
+ *   Resolves to the JSON response `{ url, onUploadResponse }` or `null`.
+ *
+ * @example
+ * ```tsx
+ * import { useFileUpload } from "naystack/file/client";
+ *
+ * function FileUploader({ dealId }: { dealId: number }) {
+ *   const uploadFile = useFileUpload();
+ *   const [uploading, setUploading] = useState(false);
+ *
+ *   const handleUpload = async (file: File) => {
+ *     setUploading(true);
+ *     try {
+ *       const result = await uploadFile(file, "DealDocument", {
+ *         dealId,
+ *         fileName: file.name,
+ *         category: "Contract",
+ *       });
+ *       if (result?.url) {
+ *         console.log("Uploaded:", result.url);
+ *         router.refresh();
+ *       }
+ *     } finally {
+ *       setUploading(false);
+ *     }
+ *   };
+ *
+ *   return <input type="file" onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])} />;
+ * }
+ * ```
+ *
+ * @category File
+ */
 declare const useFileUpload: () => (file: File | Blob, type: string, data?: object) => Promise<FileUploadResponseType>;
+/**
+ * Shape of the JSON response from the file upload PUT endpoint.
+ *
+ * @property url - The public S3 URL of the uploaded file.
+ * @property onUploadResponse - The return value from the `onUpload` callback in `setupFileUpload`.
+ *
+ * @category File
+ */
 interface FileUploadResponseType {
     url?: string;
     onUploadResponse?: object;
 }
 
-export { useFileUpload };
+export { type FileUploadResponseType, useFileUpload };

package/dist/file/client.d.ts

@@ -1,7 +1,59 @@
+/**
+ * Returns a function that uploads a file to your file upload endpoint with the current auth token.
+ * Must be used inside a tree that provides the token (i.e. inside `AuthWrapper`).
+ *
+ * The endpoint is read from `NEXT_PUBLIC_FILE_ENDPOINT` env var. The file is sent as multipart form data
+ * along with a `type` string and optional JSON `data` for metadata.
+ *
+ * @returns A function `(file, type, data?) => Promise<FileUploadResponseType | null>`.
+ *   - `file` — `File` or `Blob` to upload.
+ *   - `type` — String category (e.g. `"avatar"`, `"DealDocument"`); sent as form field `type`.
+ *   - `data` — Optional JSON-serializable object for metadata; sent as form field `data`.
+ *   Resolves to the JSON response `{ url, onUploadResponse }` or `null`.
+ *
+ * @example
+ * ```tsx
+ * import { useFileUpload } from "naystack/file/client";
+ *
+ * function FileUploader({ dealId }: { dealId: number }) {
+ *   const uploadFile = useFileUpload();
+ *   const [uploading, setUploading] = useState(false);
+ *
+ *   const handleUpload = async (file: File) => {
+ *     setUploading(true);
+ *     try {
+ *       const result = await uploadFile(file, "DealDocument", {
+ *         dealId,
+ *         fileName: file.name,
+ *         category: "Contract",
+ *       });
+ *       if (result?.url) {
+ *         console.log("Uploaded:", result.url);
+ *         router.refresh();
+ *       }
+ *     } finally {
+ *       setUploading(false);
+ *     }
+ *   };
+ *
+ *   return <input type="file" onChange={(e) => e.target.files?.[0] && handleUpload(e.target.files[0])} />;
+ * }
+ * ```
+ *
+ * @category File
+ */
 declare const useFileUpload: () => (file: File | Blob, type: string, data?: object) => Promise<FileUploadResponseType>;
+/**
+ * Shape of the JSON response from the file upload PUT endpoint.
+ *
+ * @property url - The public S3 URL of the uploaded file.
+ * @property onUploadResponse - The return value from the `onUpload` callback in `setupFileUpload`.
+ *
+ * @category File
+ */
 interface FileUploadResponseType {
     url?: string;
     onUploadResponse?: object;
 }
 
-export { useFileUpload };
+export { type FileUploadResponseType, useFileUpload };

package/dist/file/index.cjs.js

@@ -30,7 +30,6 @@ var import_uuid = require("uuid");
 
 // src/auth/email/utils.ts
 var import_jsonwebtoken2 = require("jsonwebtoken");
-var import_headers2 = require("next/headers");
 
 // src/auth/email/token.ts
 var import_bcryptjs = require("bcryptjs");

package/dist/file/index.esm.js

@@ -4,7 +4,6 @@ import { v4 } from "uuid";
 
 // src/auth/email/utils.ts
 import { verify as verify2 } from "jsonwebtoken";
-import { cookies as cookies2 } from "next/headers";
 
 // src/auth/email/token.ts
 import { compare } from "bcryptjs";

package/dist/file/put.cjs.js

@@ -28,7 +28,6 @@ var import_uuid = require("uuid");
 
 // src/auth/email/utils.ts
 var import_jsonwebtoken2 = require("jsonwebtoken");
-var import_headers2 = require("next/headers");
 
 // src/auth/email/token.ts
 var import_bcryptjs = require("bcryptjs");

package/dist/file/put.d.mts

@@ -2,6 +2,17 @@ import { S3Client } from '@aws-sdk/client-s3';
 import { NextRequest, NextResponse } from 'next/server';
 import { SetupFileUploadOptions } from './setup.mjs';
 
+/**
+ * Returns the PUT route handler for file upload.
+ *
+ * Requires authentication (Bearer token, not refresh cookie).
+ * Expects multipart form data with fields: `file` (File), `type` (string), and optional `data` (JSON string).
+ *
+ * @param options - `SetupFileUploadOptions` (getKey, onUpload).
+ * @param client - S3 client instance.
+ * @returns Async Next.js route handler for PUT requests.
+ * @category File
+ */
 declare const getFileUploadPutRoute: (options: SetupFileUploadOptions, client: S3Client) => (req: NextRequest) => Promise<NextResponse<{
     error: string;
 }> | NextResponse<{

package/dist/file/put.d.ts

@@ -2,6 +2,17 @@ import { S3Client } from '@aws-sdk/client-s3';
 import { NextRequest, NextResponse } from 'next/server';
 import { SetupFileUploadOptions } from './setup.js';
 
+/**
+ * Returns the PUT route handler for file upload.
+ *
+ * Requires authentication (Bearer token, not refresh cookie).
+ * Expects multipart form data with fields: `file` (File), `type` (string), and optional `data` (JSON string).
+ *
+ * @param options - `SetupFileUploadOptions` (getKey, onUpload).
+ * @param client - S3 client instance.
+ * @returns Async Next.js route handler for PUT requests.
+ * @category File
+ */
 declare const getFileUploadPutRoute: (options: SetupFileUploadOptions, client: S3Client) => (req: NextRequest) => Promise<NextResponse<{
     error: string;
 }> | NextResponse<{

package/dist/file/put.esm.js

@@ -4,7 +4,6 @@ import { v4 } from "uuid";
 
 // src/auth/email/utils.ts
 import { verify as verify2 } from "jsonwebtoken";
-import { cookies as cookies2 } from "next/headers";
 
 // src/auth/email/token.ts
 import { compare } from "bcryptjs";

package/dist/file/setup.cjs.js

@@ -30,7 +30,6 @@ var import_uuid = require("uuid");
 
 // src/auth/email/utils.ts
 var import_jsonwebtoken2 = require("jsonwebtoken");
-var import_headers2 = require("next/headers");
 
 // src/auth/email/token.ts
 var import_bcryptjs = require("bcryptjs");

package/dist/file/setup.d.mts

@@ -1,5 +1,14 @@
 import * as next_server from 'next/server';
 
+/**
+ * Options for setting up file upload via {@link setupFileUpload}.
+ *
+ * @property getKey - Optional. Given `{ type, userId, data }`, returns the S3 object key for the upload. If omitted, a UUID is generated.
+ * @property onUpload - **Required.** Called after each successful upload with `{ url, type, userId, data }`.
+ *   The return value is included in the API response as `onUploadResponse` (e.g. save metadata to your database and return it).
+ *
+ * @category File
+ */
 interface SetupFileUploadOptions {
     getKey?: (data: {
         type: string;
@@ -13,6 +22,45 @@ interface SetupFileUploadOptions {
         data: object;
     }) => Promise<object>;
 }
+/**
+ * Configures file upload for S3. Returns a `PUT` route handler (for the client to upload files) and server-side helpers.
+ *
+ * Mount the `PUT` handler on your file upload API route (e.g. `app/api/(rest)/file/route.ts`).
+ * The client can then use `useFileUpload()` from `naystack/file/client` to upload files with the auth token.
+ *
+ * AWS credentials are read from env vars: `AWS_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_SECRET`, `AWS_REGION`, `AWS_BUCKET`.
+ *
+ * @param options - Configuration. See {@link SetupFileUploadOptions}.
+ * @returns Object with:
+ *   - `PUT` — Next.js route handler for file uploads (auth required, multipart form).
+ *   - `uploadFile(keys, { url?, blob? })` — Server-side: upload a file from URL or Blob to S3.
+ *   - `deleteFile(url)` — Server-side: delete a file by its S3 URL.
+ *   - `getUploadURL(keys)` — Server-side: get a presigned PUT URL (5-minute expiry).
+ *   - `getDownloadURL(keys)` — Get the public download URL for a key.
+ *
+ * @example
+ * ```ts
+ * // app/api/(rest)/file/route.ts
+ * import { setupFileUpload } from "naystack/file";
+ *
+ * export const { PUT } = setupFileUpload({
+ *   onUpload: async ({ url, type, userId, data }) => {
+ *     if (type === "DealDocument" && url) {
+ *       const payload = data as { dealId: number; fileName: string };
+ *       const [row] = await db.insert(DocumentsTable).values({
+ *         dealId: payload.dealId, fileURL: url, fileName: payload.fileName,
+ *       }).returning();
+ *       return row ?? {};
+ *     }
+ *     return {};
+ *   },
+ *   // Optional: customize the S3 key (defaults to UUID)
+ *   getKey: async ({ type, userId }) => `${type}/${userId}/${crypto.randomUUID()}`,
+ * });
+ * ```
+ *
+ * @category File
+ */
 declare function setupFileUpload(options: SetupFileUploadOptions): {
     PUT: (req: next_server.NextRequest) => Promise<next_server.NextResponse<{
         error: string;

package/dist/file/setup.d.ts

@@ -1,5 +1,14 @@
 import * as next_server from 'next/server';
 
+/**
+ * Options for setting up file upload via {@link setupFileUpload}.
+ *
+ * @property getKey - Optional. Given `{ type, userId, data }`, returns the S3 object key for the upload. If omitted, a UUID is generated.
+ * @property onUpload - **Required.** Called after each successful upload with `{ url, type, userId, data }`.
+ *   The return value is included in the API response as `onUploadResponse` (e.g. save metadata to your database and return it).
+ *
+ * @category File
+ */
 interface SetupFileUploadOptions {
     getKey?: (data: {
         type: string;
@@ -13,6 +22,45 @@ interface SetupFileUploadOptions {
         data: object;
     }) => Promise<object>;
 }
+/**
+ * Configures file upload for S3. Returns a `PUT` route handler (for the client to upload files) and server-side helpers.
+ *
+ * Mount the `PUT` handler on your file upload API route (e.g. `app/api/(rest)/file/route.ts`).
+ * The client can then use `useFileUpload()` from `naystack/file/client` to upload files with the auth token.
+ *
+ * AWS credentials are read from env vars: `AWS_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_SECRET`, `AWS_REGION`, `AWS_BUCKET`.
+ *
+ * @param options - Configuration. See {@link SetupFileUploadOptions}.
+ * @returns Object with:
+ *   - `PUT` — Next.js route handler for file uploads (auth required, multipart form).
+ *   - `uploadFile(keys, { url?, blob? })` — Server-side: upload a file from URL or Blob to S3.
+ *   - `deleteFile(url)` — Server-side: delete a file by its S3 URL.
+ *   - `getUploadURL(keys)` — Server-side: get a presigned PUT URL (5-minute expiry).
+ *   - `getDownloadURL(keys)` — Get the public download URL for a key.
+ *
+ * @example
+ * ```ts
+ * // app/api/(rest)/file/route.ts
+ * import { setupFileUpload } from "naystack/file";
+ *
+ * export const { PUT } = setupFileUpload({
+ *   onUpload: async ({ url, type, userId, data }) => {
+ *     if (type === "DealDocument" && url) {
+ *       const payload = data as { dealId: number; fileName: string };
+ *       const [row] = await db.insert(DocumentsTable).values({
+ *         dealId: payload.dealId, fileURL: url, fileName: payload.fileName,
+ *       }).returning();
+ *       return row ?? {};
+ *     }
+ *     return {};
+ *   },
+ *   // Optional: customize the S3 key (defaults to UUID)
+ *   getKey: async ({ type, userId }) => `${type}/${userId}/${crypto.randomUUID()}`,
+ * });
+ * ```
+ *
+ * @category File
+ */
 declare function setupFileUpload(options: SetupFileUploadOptions): {
     PUT: (req: next_server.NextRequest) => Promise<next_server.NextResponse<{
         error: string;

package/dist/file/setup.esm.js

@@ -4,7 +4,6 @@ import { v4 } from "uuid";
 
 // src/auth/email/utils.ts
 import { verify as verify2 } from "jsonwebtoken";
-import { cookies as cookies2 } from "next/headers";
 
 // src/auth/email/token.ts
 import { compare } from "bcryptjs";

package/dist/file/utils.d.mts

@@ -1,14 +1,55 @@
 import * as _aws_sdk_client_s3 from '@aws-sdk/client-s3';
 import { S3Client } from '@aws-sdk/client-s3';
 
+/**
+ * Creates an S3 client using env credentials (`AWS_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_SECRET`, `AWS_REGION`).
+ * @returns Configured `S3Client` instance.
+ * @category File
+ */
 declare const getS3Client: () => S3Client;
+/**
+ * Returns a function that generates a presigned PUT URL for uploading to the given S3 key(s).
+ * The presigned URL expires after 5 minutes.
+ *
+ * @param client - S3 client instance.
+ * @returns `(keys: string | string[]) => Promise<string>` — the presigned upload URL.
+ * @category File
+ */
 declare const getUploadURL: (client: S3Client) => (keys: string | string[]) => Promise<string>;
+/**
+ * Builds the public download URL for one or more keys in the configured S3 bucket.
+ *
+ * @param keys - S3 key or key path segments (array joined by `/`).
+ * @returns Full HTTPS URL for the object.
+ * @category File
+ */
 declare const getDownloadURL: (keys: string | string[]) => string;
+/**
+ * Returns a function that uploads a file (by URL or Blob) to the given S3 key(s).
+ *
+ * @param client - S3 client instance.
+ * @returns `(keys, { url?, blob? }) => Promise<string | null>` — the download URL on success, or `null` if no input.
+ * @category File
+ */
 declare const uploadFile: (client: S3Client) => (keys: string | string[], { url, blob, }: {
     blob?: Blob;
     url?: string;
 }) => Promise<string | null>;
+/**
+ * Returns a function that deletes an S3 object by its full URL.
+ *
+ * @param client - S3 client instance.
+ * @returns `(url: string) => Promise<boolean>` — `true` if deleted successfully, `false` otherwise.
+ * @category File
+ */
 declare const deleteFile: (client: S3Client) => (url: string) => Promise<boolean>;
+/**
+ * Returns a function that uploads a Blob/File to S3 at the given key.
+ *
+ * @param client - S3 client instance.
+ * @returns `(file: File | Blob, key: string) => Promise<PutObjectCommandOutput>`.
+ * @category File
+ */
 declare const uploadBlob: (client: S3Client) => (file: File | Blob, key: string) => Promise<_aws_sdk_client_s3.PutObjectCommandOutput>;
 
 export { deleteFile, getDownloadURL, getS3Client, getUploadURL, uploadBlob, uploadFile };

package/dist/file/utils.d.ts

@@ -1,14 +1,55 @@
 import * as _aws_sdk_client_s3 from '@aws-sdk/client-s3';
 import { S3Client } from '@aws-sdk/client-s3';
 
+/**
+ * Creates an S3 client using env credentials (`AWS_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_SECRET`, `AWS_REGION`).
+ * @returns Configured `S3Client` instance.
+ * @category File
+ */
 declare const getS3Client: () => S3Client;
+/**
+ * Returns a function that generates a presigned PUT URL for uploading to the given S3 key(s).
+ * The presigned URL expires after 5 minutes.
+ *
+ * @param client - S3 client instance.
+ * @returns `(keys: string | string[]) => Promise<string>` — the presigned upload URL.
+ * @category File
+ */
 declare const getUploadURL: (client: S3Client) => (keys: string | string[]) => Promise<string>;
+/**
+ * Builds the public download URL for one or more keys in the configured S3 bucket.
+ *
+ * @param keys - S3 key or key path segments (array joined by `/`).
+ * @returns Full HTTPS URL for the object.
+ * @category File
+ */
 declare const getDownloadURL: (keys: string | string[]) => string;
+/**
+ * Returns a function that uploads a file (by URL or Blob) to the given S3 key(s).
+ *
+ * @param client - S3 client instance.
+ * @returns `(keys, { url?, blob? }) => Promise<string | null>` — the download URL on success, or `null` if no input.
+ * @category File
+ */
 declare const uploadFile: (client: S3Client) => (keys: string | string[], { url, blob, }: {
     blob?: Blob;
     url?: string;
 }) => Promise<string | null>;
+/**
+ * Returns a function that deletes an S3 object by its full URL.
+ *
+ * @param client - S3 client instance.
+ * @returns `(url: string) => Promise<boolean>` — `true` if deleted successfully, `false` otherwise.
+ * @category File
+ */
 declare const deleteFile: (client: S3Client) => (url: string) => Promise<boolean>;
+/**
+ * Returns a function that uploads a Blob/File to S3 at the given key.
+ *
+ * @param client - S3 client instance.
+ * @returns `(file: File | Blob, key: string) => Promise<PutObjectCommandOutput>`.
+ * @category File
+ */
 declare const uploadBlob: (client: S3Client) => (file: File | Blob, key: string) => Promise<_aws_sdk_client_s3.PutObjectCommandOutput>;
 
 export { deleteFile, getDownloadURL, getS3Client, getUploadURL, uploadBlob, uploadFile };