@edgestore/server 0.1.5-alpha.4 → 0.1.5-alpha.5

package/src/adapters/shared.ts

@@ -82,7 +82,10 @@ export async function requestUpload<TCtx>(params: {
   const ctx = await getContext(ctxToken);
   const bucket = router.buckets[bucketName];
   if (!bucket) {
-    throw new Error(`Bucket ${bucketName} not found`);
+    throw new EdgeStoreError({
+      message: `Bucket ${bucketName} not found`,
+      code: 'BAD_REQUEST',
+    });
   }
   if (bucket._def.beforeUpload) {
     const canUpload = await bucket._def.beforeUpload?.({
@@ -98,15 +101,22 @@ export async function requestUpload<TCtx>(params: {
       },
     });
     if (!canUpload) {
-      throw new Error('Upload not allowed');
+      throw new EdgeStoreError({
+        message: 'Upload not allowed for the current context',
+        code: 'UPLOAD_NOT_ALLOWED',
+      });
     }
   }
 
   if (bucket._def.type === 'IMAGE') {
     if (!IMAGE_MIME_TYPES.includes(fileInfo.type)) {
       throw new EdgeStoreError({
-        code: 'BAD_REQUEST',
+        code: 'MIME_TYPE_NOT_ALLOWED',
         message: 'Only images are allowed in this bucket',
+        details: {
+          allowedMimeTypes: IMAGE_MIME_TYPES,
+          mimeType: fileInfo.type,
+        },
       });
     }
   }
@@ -114,8 +124,12 @@ export async function requestUpload<TCtx>(params: {
   if (bucket._def.bucketConfig?.maxSize) {
     if (fileInfo.size > bucket._def.bucketConfig.maxSize) {
       throw new EdgeStoreError({
-        code: 'BAD_REQUEST',
+        code: 'FILE_TOO_LARGE',
         message: `File size is too big. Max size is ${bucket._def.bucketConfig.maxSize}`,
+        details: {
+          maxFileSize: bucket._def.bucketConfig.maxSize,
+          fileSize: fileInfo.size,
+        },
       });
     }
   }
@@ -137,10 +151,14 @@ export async function requestUpload<TCtx>(params: {
     }
     if (!accepted) {
       throw new EdgeStoreError({
-        code: 'BAD_REQUEST',
+        code: 'MIME_TYPE_NOT_ALLOWED',
         message: `"${
           fileInfo.type
         }" is not allowed. Accepted types are ${JSON.stringify(accept)}`,
+        details: {
+          allowedMimeTypes: accept,
+          mimeType: fileInfo.type,
+        },
       });
     }
   }
@@ -190,7 +208,6 @@ export async function requestUploadParts<TCtx>(params: {
 }) {
   const {
     provider,
-    router,
     ctxToken,
     body: { multipart, path },
   } = params;
@@ -201,10 +218,6 @@ export async function requestUploadParts<TCtx>(params: {
     });
   }
   await getContext(ctxToken); // just to check if the token is valid
-  const bucket = router.buckets[multipart.uploadId];
-  if (!bucket) {
-    throw new Error(`Bucket ${multipart.uploadId} not found`);
-  }
   return await provider.requestUploadParts({
     multipart,
     path,
@@ -242,7 +255,10 @@ export async function completeMultipartUpload<TCtx>(params: {
   await getContext(ctxToken); // just to check if the token is valid
   const bucket = router.buckets[bucketName];
   if (!bucket) {
-    throw new Error(`Bucket ${bucketName} not found`);
+    throw new EdgeStoreError({
+      message: `Bucket ${bucketName} not found`,
+      code: 'BAD_REQUEST',
+    });
   }
   return await provider.completeMultipartUpload({
     uploadId,
@@ -278,7 +294,10 @@ export async function confirmUpload<TCtx>(params: {
   await getContext(ctxToken); // just to check if the token is valid
   const bucket = router.buckets[bucketName];
   if (!bucket) {
-    throw new Error(`Bucket ${bucketName} not found`);
+    throw new EdgeStoreError({
+      message: `Bucket ${bucketName} not found`,
+      code: 'BAD_REQUEST',
+    });
   }
 
   return await provider.confirmUpload({
@@ -314,13 +333,18 @@ export async function deleteFile<TCtx>(params: {
   const ctx = await getContext(ctxToken);
   const bucket = router.buckets[bucketName];
   if (!bucket) {
-    throw new Error(`Bucket ${bucketName} not found`);
+    throw new EdgeStoreError({
+      message: `Bucket ${bucketName} not found`,
+      code: 'BAD_REQUEST',
+    });
   }
 
   if (!bucket._def.beforeDelete) {
-    throw new Error(
-      'You need to define beforeDelete if you want to delete files directly from the frontend.',
-    );
+    throw new EdgeStoreError({
+      message:
+        'You need to define beforeDelete if you want to delete files directly from the frontend.',
+      code: 'SERVER_ERROR',
+    });
   }
 
   const fileInfo = await provider.getFile({
@@ -332,7 +356,10 @@ export async function deleteFile<TCtx>(params: {
     fileInfo,
   });
   if (!canDelete) {
-    throw new Error('Delete not allowed');
+    throw new EdgeStoreError({
+      message: 'Delete not allowed for the current context',
+      code: 'DELETE_NOT_ALLOWED',
+    });
   }
   return await provider.deleteFile({
     bucket,
@@ -344,9 +371,10 @@ async function encryptJWT(ctx: any) {
   const secret =
     process.env.EDGE_STORE_JWT_SECRET ?? process.env.EDGE_STORE_SECRET_KEY;
   if (!secret) {
-    throw new Error(
-      'EDGE_STORE_JWT_SECRET or EDGE_STORE_SECRET_KEY is not defined',
-    );
+    throw new EdgeStoreError({
+      message: 'EDGE_STORE_JWT_SECRET or EDGE_STORE_SECRET_KEY is not defined',
+      code: 'SERVER_ERROR',
+    });
   }
   const encryptionSecret = await getDerivedEncryptionKey(secret);
   return await new EncryptJWT(ctx)
@@ -361,9 +389,10 @@ async function decryptJWT(token: string) {
   const secret =
     process.env.EDGE_STORE_JWT_SECRET ?? process.env.EDGE_STORE_SECRET_KEY;
   if (!secret) {
-    throw new Error(
-      'EDGE_STORE_JWT_SECRET or EDGE_STORE_SECRET_KEY is not set',
-    );
+    throw new EdgeStoreError({
+      message: 'EDGE_STORE_JWT_SECRET or EDGE_STORE_SECRET_KEY is not defined',
+      code: 'SERVER_ERROR',
+    });
   }
   const encryptionSecret = await getDerivedEncryptionKey(secret);
   const { payload } = await jwtDecrypt(token, encryptionSecret, {
@@ -395,7 +424,10 @@ export function buildPath(params: {
   const path = pathParams.map((param) => {
     const paramEntries = Object.entries(param);
     if (paramEntries[0] === undefined) {
-      throw new Error('Missing path param');
+      throw new EdgeStoreError({
+        message: `Empty path param found in: ${JSON.stringify(pathParams)}`,
+        code: 'SERVER_ERROR',
+      });
     }
     const [key, value] = paramEntries[0];
     // this is a string like: "ctx.xxx" or "input.yyy.zzz"
@@ -403,7 +435,10 @@ export function buildPath(params: {
       .split('.')
       .reduce((acc2: any, key: string) => {
         if (acc2[key] === undefined) {
-          throw new Error(`Missing key ${key} in ${JSON.stringify(acc2)}`);
+          throw new EdgeStoreError({
+            message: `Missing key ${key} in ${JSON.stringify(acc2)}`,
+            code: 'BAD_REQUEST',
+          });
         }
         return acc2[key];
       }, params.pathAttrs as any) as string;
@@ -427,10 +462,7 @@ export function parsePath(path: { key: string; value: string }[]) {
   };
 }
 
-async function getContext(token?: string) {
-  if (!token) {
-    throw new Error('No token');
-  }
+async function getContext(token: string) {
   return await decryptJWT(token);
 }
 

package/src/core/client/index.ts

@@ -50,6 +50,26 @@ export type UploadOptions = {
 };
 
 export type UploadFileRequest<TBucket extends AnyBuilder> = {
+  /**
+   * Can be a string or a blob.
+   *
+   * If it's a string, it will be converted to a blob with the type `text/plain`.
+   *
+   * @example
+   * ```ts
+   * // string
+   * content: "some text"
+   * ```
+   *
+   * @example
+   * ```ts
+   * // blob
+   * content: {
+   *   blob: new Blob([text], { type: "text/csv" }),
+   *   extension: "csv",
+   * }
+   * ```
+   */
   content:
     | string
     | {
@@ -125,15 +145,50 @@ type EdgeStoreClient<TRouter extends AnyRouter> = {
     getFile: (params: {
       url: string;
     }) => Promise<GetFileRes<TRouter['buckets'][K]>>;
+
+    /**
+     * Use this function to upload a file to the bucket directly from your backend.
+     *
+     * @example
+     * ```ts
+     * // simple example
+     * await backendClient.myBucket.upload({
+     *   content: "some text",
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // complete example
+     * await backendClient.myBucket.upload({
+     *   content: {
+     *     blob: new Blob([text], { type: "text/csv" }),
+     *     extension: "csv",
+     *   },
+     *   options: {
+     *     temporary: true,
+     *     replaceTargetUrl: replaceUrl,
+     *     manualFileName: "test.csv",
+     *   },
+     *   ctx: {
+     *     userId: "123",
+     *     userRole: "admin",
+     *   },
+     *   input: {
+     *     type: "post",
+     *   },
+     * });
+     * ```
+     */
     upload: (
       params: UploadFileRequest<TRouter['buckets'][K]>,
     ) => Promise<Prettify<UploadFileRes<TRouter['buckets'][K]>>>;
     /**
-     * Confirm a temporary file upload.
+     * Confirm a temporary file upload directly from your backend.
      */
     confirmUpload: (params: { url: string }) => Promise<{ success: boolean }>;
     /**
-     * Programmatically delete a file.
+     * Programmatically delete a file directly from your backend.
      */
     deleteFile: (params: { url: string }) => Promise<{
       success: boolean;

package/src/core/index.ts

@@ -7,5 +7,11 @@ export type {
   InferBucketPathObject,
   InferMetadataObject,
 } from './internals/bucketBuilder';
+export type {
+  EdgeStoreErrorCodeKey,
+  EdgeStoreErrorDetails,
+  EdgeStoreJsonResponse,
+} from '../libs/errors/EdgeStoreError';
+export { EdgeStoreApiClientError } from '../libs/errors/EdgeStoreApiClientError';
 
 export type AnyRouter = EdgeStoreRouter<any>;

package/src/core/sdk/index.ts

@@ -1,5 +1,6 @@
 import { type AnyRouter } from '..';
 import EdgeStoreCredentialsError from '../../libs/errors/EdgeStoreCredentialsError';
+import EdgeStoreError from '../../libs/errors/EdgeStoreError';
 import { type AnyContext, type AnyMetadata } from '../internals/bucketBuilder';
 
 const API_ENDPOINT =
@@ -93,7 +94,12 @@ export const edgeStoreRawSdk = {
           path: bucket._def.path.map((p: { [key: string]: () => string }) => {
             const paramEntries = Object.entries(p);
             if (paramEntries[0] === undefined) {
-              throw new Error('Missing path param');
+              throw new EdgeStoreError({
+                message: `Empty path param found in: ${JSON.stringify(
+                  bucket._def.path,
+                )}`,
+                code: 'SERVER_ERROR',
+              });
             }
             const [key, value] = paramEntries[0];
             return {

package/src/libs/errors/EdgeStoreApiClientError.ts

@@ -0,0 +1,14 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+
+import { type EdgeStoreJsonResponse } from './EdgeStoreError';
+
+export class EdgeStoreApiClientError extends Error {
+  public readonly data: EdgeStoreJsonResponse;
+
+  constructor(opts: { response: EdgeStoreJsonResponse }) {
+    super(opts.response.message);
+    this.name = 'EdgeStoreApiClientError';
+
+    this.data = opts.response;
+  }
+}

package/src/libs/errors/EdgeStoreError.ts

@@ -1,24 +1,93 @@
+import { type Simplify } from '../../types';
+
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
 export const EDGE_STORE_ERROR_CODES = {
   BAD_REQUEST: 400,
+  FILE_TOO_LARGE: 400,
+  MIME_TYPE_NOT_ALLOWED: 400,
   UNAUTHORIZED: 401,
+  UPLOAD_NOT_ALLOWED: 403,
+  DELETE_NOT_ALLOWED: 403,
+  CREATE_CONTEXT_ERROR: 500,
+  SERVER_ERROR: 500,
 } as const;
 
 export type EdgeStoreErrorCodeKey = keyof typeof EDGE_STORE_ERROR_CODES;
 
-class EdgeStoreError extends Error {
+export type EdgeStoreErrorDetails<TCode extends EdgeStoreErrorCodeKey> =
+  TCode extends 'FILE_TOO_LARGE'
+    ? {
+        maxFileSize: number;
+        fileSize: number;
+      }
+    : TCode extends 'MIME_TYPE_NOT_ALLOWED'
+    ? {
+        allowedMimeTypes: string[];
+        mimeType: string;
+      }
+    : never;
+
+export type EdgeStoreJsonResponse = Simplify<
+  | {
+      message: string;
+      code: 'FILE_TOO_LARGE';
+      details: EdgeStoreErrorDetails<'FILE_TOO_LARGE'>;
+    }
+  | {
+      message: string;
+      code: 'MIME_TYPE_NOT_ALLOWED';
+      details: EdgeStoreErrorDetails<'MIME_TYPE_NOT_ALLOWED'>;
+    }
+  | {
+      message: string;
+      code: Exclude<
+        EdgeStoreErrorCodeKey,
+        'FILE_TOO_LARGE' | 'MIME_TYPE_NOT_ALLOWED'
+      >;
+    }
+>;
+
+class EdgeStoreError<TCode extends EdgeStoreErrorCodeKey> extends Error {
   public readonly cause?: Error;
-  public readonly code: EdgeStoreErrorCodeKey;
+  public readonly code: TCode;
+  public readonly level: 'error' | 'warn';
+  public readonly details: EdgeStoreErrorDetails<TCode>;
 
-  constructor(opts: {
-    message: string;
-    code: EdgeStoreErrorCodeKey;
-    cause?: Error;
-  }) {
+  constructor(
+    opts: {
+      message: string;
+      code: TCode;
+      cause?: Error;
+    } & (EdgeStoreErrorDetails<TCode> extends undefined
+      ? object
+      : {
+          details: EdgeStoreErrorDetails<TCode>;
+        }),
+  ) {
     super(opts.message);
     this.name = 'EdgeStoreError';
 
     this.code = opts.code;
     this.cause = opts.cause;
+    this.level = EDGE_STORE_ERROR_CODES[opts.code] >= 500 ? 'error' : 'warn';
+    this.details = 'details' in opts ? opts.details : undefined!;
+  }
+
+  formattedMessage(): string {
+    return `EdgeStore${this.level === 'error' ? 'Error' : 'Info'}: ${
+      this.message
+    }${this.details ? `\n    Details: ${JSON.stringify(this.details)}` : ''}${
+      this.cause ? `\n    Caused by: ${this.cause.message}` : ''
+    }`;
+  }
+
+  formattedJson(): EdgeStoreJsonResponse {
+    return {
+      message:
+        this.code === 'SERVER_ERROR' ? 'Internal server error' : this.message,
+      code: this.code,
+      details: this.details as any,
+    } satisfies EdgeStoreJsonResponse;
   }
 }
 

package/src/libs/logger.ts

@@ -0,0 +1,44 @@
+/* eslint-disable no-console */
+
+const logLevel = ['debug', 'info', 'warn', 'error', 'none'] as const;
+
+export type LogLevel = typeof logLevel[number];
+
+class Logger {
+  private logLevel: LogLevel;
+
+  constructor(logLevel?: LogLevel) {
+    this.logLevel =
+      logLevel ?? process.env.NODE_ENV === 'production' ? 'error' : 'info';
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return logLevel.indexOf(level) >= logLevel.indexOf(this.logLevel);
+  }
+
+  debug(message?: any, ...optionalParams: any[]): void {
+    if (this.shouldLog('debug')) {
+      console.debug(message, ...optionalParams);
+    }
+  }
+
+  info(message?: any, ...optionalParams: any[]): void {
+    if (this.shouldLog('info')) {
+      console.info(message, ...optionalParams);
+    }
+  }
+
+  warn(message?: any, ...optionalParams: any[]): void {
+    if (this.shouldLog('warn')) {
+      console.warn(message, ...optionalParams);
+    }
+  }
+
+  error(message?: any, ...optionalParams: any[]): void {
+    if (this.shouldLog('error')) {
+      console.error(message, ...optionalParams);
+    }
+  }
+}
+
+export default Logger;

package/src/providers/edgestore/index.ts

@@ -1,5 +1,6 @@
 import { initEdgeStoreSdk } from '../../core/sdk';
 import EdgeStoreCredentialsError from '../../libs/errors/EdgeStoreCredentialsError';
+import EdgeStoreError from '../../libs/errors/EdgeStoreError';
 import { type Provider, type RequestUploadRes } from '../types';
 
 const DEFAULT_BASE_URL = 'https://files.edgestore.dev';
@@ -111,7 +112,10 @@ export function EdgeStoreProvider(
             thumbnailUrl: res.thumbnailUrl,
           };
         } else {
-          throw new Error('Could not get upload url');
+          throw new EdgeStoreError({
+            message: 'Could not get upload url',
+            code: 'SERVER_ERROR',
+          });
         }
       }
       const res = await edgeStoreSdk.requestUpload({
@@ -126,7 +130,10 @@ export function EdgeStoreProvider(
           thumbnailUrl: res.thumbnailUrl,
         };
       }
-      throw new Error('Could not get upload url');
+      throw new EdgeStoreError({
+        message: 'Could not get upload url',
+        code: 'SERVER_ERROR',
+      });
     },
     requestUploadParts: async ({ multipart, path }) => {
       const res = await edgeStoreSdk.requestUploadParts({