@edgestore/server 0.1.5-alpha.0 → 0.1.5-alpha.10

package/src/core/client/index.ts

@@ -1,5 +1,8 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import { type z, type ZodNever } from 'zod';
 import { type AnyRouter, type Comparison } from '..';
-import { type Simplify } from '../../types';
+import { buildPath, parsePath } from '../../adapters/shared';
+import { type Prettify, type Simplify } from '../../types';
 import {
   type AnyBuilder,
   type InferBucketPathKeys,
@@ -16,6 +19,104 @@ export type GetFileRes<TBucket extends AnyBuilder> = {
   path: InferBucketPathObject<TBucket>;
 };
 
+export type UploadOptions = {
+  /**
+   * e.g. 'my-file-name.jpg'
+   *
+   * By default, a unique file name will be generated for each upload.
+   * If you want to use a custom file name, you can use this option.
+   * If you use the same file name for multiple uploads, the previous file will be overwritten.
+   * But it might take some time for the CDN cache to be cleared.
+   * So maybe you will keep seeing the old file for a while.
+   *
+   * If you want to replace an existing file immediately leave the `manualFileName` option empty and use the `replaceTargetUrl` option.
+   */
+  manualFileName?: string;
+  /**
+   * Use this to replace an existing file.
+   * It will automatically delete the existing file when the upload is complete.
+   */
+  replaceTargetUrl?: string;
+  /**
+   * If true, the file needs to be confirmed by using the `confirmUpload` function.
+   * If the file is not confirmed within 24 hours, it will be deleted.
+   *
+   * This is useful for pages where the file is uploaded as soon as it is selected,
+   * but the user can leave the page without submitting the form.
+   *
+   * This avoids unnecessary zombie files in the bucket.
+   */
+  temporary?: boolean;
+};
+
+type TextContent = string;
+type BlobContent = {
+  blob: Blob;
+  extension: string;
+};
+type UrlContent = {
+  url: string;
+  extension: string;
+};
+
+// type guard for `content`
+function isTextContent(
+  content: TextContent | BlobContent | UrlContent,
+): content is TextContent {
+  return typeof content === 'string';
+}
+
+function isBlobContent(
+  content: TextContent | BlobContent | UrlContent,
+): content is BlobContent {
+  return typeof content !== 'string' && 'blob' in content;
+}
+
+export type UploadFileRequest<TBucket extends AnyBuilder> = {
+  /**
+   * Can be a string, a blob or an url.
+   *
+   * If it's a string, it will be converted to a blob with the type `text/plain`.
+   *
+   * @example
+   * // string
+   * content: "some text"
+   *
+   * @example
+   * // blob
+   * content: {
+   *   blob: new Blob([text], { type: "text/csv" }),
+   *   extension: "csv",
+   * }
+   *
+   * @example
+   * // url
+   * content: {
+   *   url: "https://example.com/my-file.csv",
+   *   extension: "csv",
+   * }
+   */
+  content: TextContent | BlobContent | UrlContent;
+  options?: UploadOptions;
+} & (TBucket['$config']['ctx'] extends Record<string, never>
+  ? {}
+  : {
+      ctx: TBucket['$config']['ctx'];
+    }) &
+  (TBucket['_def']['input'] extends ZodNever
+    ? {}
+    : {
+        input: z.infer<TBucket['_def']['input']>;
+      });
+
+export type UploadFileRes<TBucket extends AnyBuilder> = {
+  url: string;
+  size: number;
+  metadata: InferMetadataObject<TBucket>;
+  path: InferBucketPathObject<TBucket>;
+  pathOrder: (keyof InferBucketPathObject<TBucket>)[];
+};
+
 type Filter<TBucket extends AnyBuilder> = {
   AND?: Filter<TBucket>[];
   OR?: Filter<TBucket>[];
@@ -65,24 +166,50 @@ type EdgeStoreClient<TRouter extends AnyRouter> = {
     getFile: (params: {
       url: string;
     }) => Promise<GetFileRes<TRouter['buckets'][K]>>;
-    // TODO: replace with `upload`
-    // requestUpload: (params: {
-    //   file: File;
-    //   path: {
-    //     [TKey in InferBucketPathKeys<TRouter['buckets'][K]>]: string;
-    //   };
-    //   metadata: InferMetadataObject<TRouter['buckets'][K]>;
-    //   replaceTargetUrl?: string;
-    // }) => Promise<{
-    //   uploadUrl: string;
-    //   accessUrl: string;
-    // }>;
+
     /**
-     * Confirm a temporary file upload.
+     * 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 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;
@@ -95,7 +222,7 @@ type EdgeStoreClient<TRouter extends AnyRouter> = {
      */
     listFiles: (
       params?: ListFilesRequest<TRouter['buckets'][K]>,
-    ) => Promise<ListFilesResponse<TRouter['buckets'][K]>>;
+    ) => Promise<Prettify<ListFilesResponse<TRouter['buckets'][K]>>>;
   };
 };
 
@@ -124,6 +251,91 @@ export function initEdgeStoreClient<TRouter extends AnyRouter>(config: {
         throw new Error(`Bucket ${bucketName} not found`);
       }
       const client: EdgeStoreClient<TRouter>[string] = {
+        async upload(params) {
+          const content = params.content;
+          const ctx = 'ctx' in params ? params.ctx : {};
+          const input = 'input' in params ? params.input : {};
+
+          const { blob, extension } = await (async () => {
+            if (isTextContent(content)) {
+              return {
+                blob: new Blob([content], { type: 'text/plain' }),
+                extension: 'txt',
+              };
+            } else if (isBlobContent(content)) {
+              return {
+                blob: content.blob,
+                extension: content.extension,
+              };
+            } else {
+              return {
+                blob: await getBlobFromUrl(content.url),
+                extension: content.extension,
+              };
+            }
+          })();
+
+          const path = buildPath({
+            bucket,
+            pathAttrs: {
+              ctx,
+              input,
+            },
+            fileInfo: {
+              type: blob.type,
+              size: blob.size,
+              extension,
+              temporary: false,
+              fileName: params.options?.manualFileName,
+              replaceTargetUrl: params.options?.replaceTargetUrl,
+            },
+          });
+          const metadata = await bucket._def.metadata({
+            ctx,
+            input,
+          });
+
+          const requestUploadRes = await sdk.requestUpload({
+            bucketName,
+            bucketType: bucket._def.type,
+            fileInfo: {
+              fileName: params.options?.manualFileName,
+              replaceTargetUrl: params.options?.replaceTargetUrl,
+              type: blob.type,
+              size: blob.size,
+              extension,
+              isPublic: bucket._def.accessControl === undefined,
+              temporary: params.options?.temporary ?? false,
+              path,
+              metadata,
+            },
+          });
+
+          const { signedUrl, multipart } = requestUploadRes;
+
+          if (multipart) {
+            // TODO
+            throw new Error('Multipart upload not implemented');
+          } else if (signedUrl) {
+            await fetch(signedUrl, {
+              method: 'PUT',
+              body: blob,
+            });
+          } else {
+            throw new Error('Missing signedUrl');
+          }
+          const { parsedPath, pathOrder } = parsePath(path);
+          return {
+            url: requestUploadRes.accessUrl,
+            size: blob.size,
+            metadata,
+            path: parsedPath,
+            pathOrder,
+          } satisfies UploadFileRes<typeof bucket> as UploadFileRes<
+            TRouter['buckets'][string]
+          >;
+        },
+
         async getFile(params) {
           const res = await sdk.getFile(params);
           return {
@@ -136,41 +348,6 @@ export function initEdgeStoreClient<TRouter extends AnyRouter>(config: {
             TRouter['buckets'][string]
           >;
         },
-        // TODO: Replace with `upload`
-        // async requestUpload(params) {
-        //   const { file, path, metadata, replaceTargetUrl } = params;
-        //   const fileExtension = file.name.includes('.')
-        //     ? file.name.split('.').pop()
-        //     : undefined;
-        //   if (!fileExtension) {
-        //     throw new Error('Missing file extension');
-        //   }
-        //   const parsedPath = Object.keys(bucket._def.path).map((key) => {
-        //     const value = path[key as keyof typeof path];
-        //     if (value === undefined) {
-        //       throw new Error(`Missing path param ${key}`);
-        //     }
-        //     return {
-        //       key,
-        //       value,
-        //     };
-        //   });
-
-        //   const fileInfo = {
-        //     size: file.size,
-        //     extension: fileExtension,
-        //     isPublic: bucket._def.accessControl === undefined,
-        //     path: parsedPath,
-        //     metadata,
-        //     replaceTargetUrl,
-        //   };
-
-        //   return await sdk.requestUpload({
-        //     bucketName,
-        //     bucketType: bucket._def.type,
-        //     fileInfo,
-        //   });
-        // },
 
         async confirmUpload(params) {
           return await sdk.confirmUpload(params);
@@ -232,6 +409,11 @@ function getUrl(url: string, baseUrl?: string) {
   return url;
 }
 
+async function getBlobFromUrl(url: string) {
+  const res = await fetch(url);
+  return await res.blob();
+}
+
 export type InferClientResponse<TRouter extends AnyRouter> = {
   [TBucketName in keyof TRouter['buckets']]: {
     [TClienFn in keyof EdgeStoreClient<TRouter>[TBucketName]]: Simplify<

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/EdgeStoreCredentialsError.ts

@@ -1,6 +1,5 @@
 const DEFAULT_MESSAGE = `Missing EDGE_STORE_ACCESS_KEY or EDGE_STORE_SECRET_KEY. 
-This can happen if you are trying to use the vanilla client in your frontend.
-The vanilla client should only be used in the backend.`;
+This can happen if you are trying to import something related to the backend of Edge Store in a client component.`;
 
 class EdgeStoreCredentialsError extends Error {
   constructor(message = DEFAULT_MESSAGE) {

package/src/libs/errors/EdgeStoreError.ts

@@ -1,24 +1,91 @@
+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 `${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('[EdgeStoreDebug]', message, ...optionalParams);
+    }
+  }
+
+  info(message?: any, ...optionalParams: any[]): void {
+    if (this.shouldLog('info')) {
+      console.info('[EdgeStoreInfo]', message, ...optionalParams);
+    }
+  }
+
+  warn(message?: any, ...optionalParams: any[]): void {
+    if (this.shouldLog('warn')) {
+      console.warn('[EdgeStoreWarn]', message, ...optionalParams);
+    }
+  }
+
+  error(message?: any, ...optionalParams: any[]): void {
+    if (this.shouldLog('error')) {
+      console.error('[EdgeStoreError]', message, ...optionalParams);
+    }
+  }
+}
+
+export default Logger;

package/src/providers/aws/index.ts

@@ -107,7 +107,7 @@ export function AWSProvider(options?: AWSProviderOptions): Provider {
       const extension = fileInfo.extension
         ? `.${fileInfo.extension.replace('.', '')}`
         : '';
-      const fileName = `${nameId}${extension}`;
+      const fileName = fileInfo.fileName ?? `${nameId}${extension}`;
       const filePath = fileInfo.path.reduce((acc, item) => {
         return `${acc}/${item.value}`;
       }, '');

package/src/providers/azure/index.ts

@@ -0,0 +1,89 @@
+import { BlobServiceClient } from '@azure/storage-blob';
+import { v4 as uuidv4 } from 'uuid';
+import { type Provider } from '../types';
+
+export type AzureProviderOptions = {
+  /**
+   * The storage account name for Azure Blob Storage
+   * Can also be set via the `ES_AZURE_ACCOUNT_NAME` environment variable.
+   */
+  storageAccountName?: string;
+  /**
+   * SAS token for Azure Blob Storage
+   * Can also be set via the `ES_AZURE_SAS_TOKEN` environment variable.
+   */
+  sasToken?: string;
+  /**
+   * Azure Blob Storage container name
+   * Can also be set via the `ES_AZURE_CONTAINER_NAME` environment variable.
+   */
+  containerName?: string;
+};
+
+export function AzureProvider(options?: AzureProviderOptions): Provider {
+  const {
+    storageAccountName = process.env.ES_AZURE_ACCOUNT_NAME,
+    sasToken = process.env.ES_AZURE_SAS_TOKEN,
+    containerName = process.env.ES_AZURE_CONTAINER_NAME,
+  } = options ?? {};
+
+  const baseUrl = `https://${storageAccountName}.blob.core.windows.net`;
+  const blobServiceClient = new BlobServiceClient(`${baseUrl}?${sasToken}`);
+  const containerClient = blobServiceClient.getContainerClient(
+    containerName ?? '',
+  );
+
+  return {
+    async init() {
+      return {};
+    },
+    getBaseUrl() {
+      return baseUrl;
+    },
+    async getFile({ url }) {
+      const blobClient = containerClient.getBlobClient(url);
+
+      const { contentLength, lastModified } = await blobClient.getProperties();
+
+      return {
+        url: url,
+        metadata: {},
+        path: {},
+        size: contentLength ?? 0,
+        uploadedAt: lastModified ?? new Date(),
+      };
+    },
+    async requestUpload({ fileInfo }) {
+      const nameId = uuidv4();
+      const extension = fileInfo.extension
+        ? `.${fileInfo.extension.replace('.', '')}`
+        : '';
+      const fileName = fileInfo.fileName ?? `${nameId}${extension}`;
+
+      const blobClient = containerClient.getBlobClient(fileName);
+
+      const url = blobClient.url;
+
+      return {
+        uploadUrl: url,
+        accessUrl: url,
+      };
+    },
+    async requestUploadParts() {
+      throw new Error('Not implemented');
+    },
+    async completeMultipartUpload() {
+      throw new Error('Not implemented');
+    },
+    async confirmUpload() {
+      throw new Error('Not implemented');
+    },
+    async deleteFile({ url }) {
+      const blobClient = containerClient.getBlobClient(url);
+      await blobClient.delete();
+      return {
+        success: true,
+      };
+    },
+  };
+}

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({

package/src/providers/types.ts

@@ -41,6 +41,7 @@ export type RequestUploadParams = {
     size: number;
     extension: string;
     isPublic: boolean;
+    fileName?: string;
     path: {
       key: string;
       value: string;

package/src/types.ts

@@ -61,6 +61,14 @@ export type Simplify<TType> = TType extends any[] | Date
   ? TType
   : { [K in keyof TType]: TType[K] };
 
+/**
+ * @internal
+ */
+export type Prettify<TType> = {
+  [K in keyof TType]: TType[K];
+  // eslint-disable-next-line @typescript-eslint/ban-types
+} & {};
+
 /**
  * @public
  */