@edgestore/shared 0.7.0 → 1.0.0-next.0

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@edgestore/shared",
-  "version": "0.7.0",
+  "version": "1.0.0-next.0",
   "description": "Upload files with ease from React/Next.js",
   "homepage": "https://edgestore.dev",
   "license": "MIT",
   "sideEffects": false,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/edgestorejs/edgestore.git",
@@ -15,7 +19,6 @@
   },
   "author": "Ravi <me@ravi.com>",
   "main": "dist/index.js",
-  "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "keywords": [
     "react",
@@ -31,8 +34,8 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
       "default": "./dist/index.js"
     }
   },
@@ -57,16 +60,19 @@
   },
   "devDependencies": {
     "@types/node": "25.0.3",
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
-    "typescript": "5.9.3",
-    "zod": "3.25.42"
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "tsx": "4.23.1",
+    "typescript": "6.0.3",
+    "zod": "3.25.76"
   },
   "gitHead": "a223c4cb8df50e6b64f9db5dc2daf93848748da9",
   "scripts": {
     "build": "rollup --config rollup.config.ts --configPlugin rollup-plugin-swc3",
     "dev": "pnpm build --watch",
     "codegen:entrypoints": "tsx entrypoints.script.ts",
-    "lint": "eslint --cache --ext \".js,.ts,.tsx\" --ignore-path ../../.gitignore --report-unused-disable-directives src"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint --cache --report-unused-disable-directives src"
   }
 }

package/src/errors/EdgeStoreError.ts

@@ -1,6 +1,5 @@
 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,
@@ -21,11 +20,11 @@ export type EdgeStoreErrorDetails<TCode extends EdgeStoreErrorCodeKey> =
         fileSize: number;
       }
     : TCode extends 'MIME_TYPE_NOT_ALLOWED'
-    ? {
-        allowedMimeTypes: string[];
-        mimeType: string;
-      }
-    : never;
+      ? {
+          allowedMimeTypes: string[];
+          mimeType: string;
+        }
+      : never;
 
 export type EdgeStoreJsonResponse = Simplify<
   | {
@@ -84,7 +83,7 @@ export class EdgeStoreError<TCode extends EdgeStoreErrorCodeKey> extends Error {
       message:
         this.code === 'SERVER_ERROR' ? 'Internal server error' : this.message,
       code: this.code,
-      details: this.details as any,
-    } satisfies EdgeStoreJsonResponse;
+      details: this.details,
+    } as EdgeStoreJsonResponse;
   }
 }

package/src/internals/bucketBuilder.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { EdgeStoreError } from '../errors';
 import { type KeysOfUnion, type MaybePromise, type Simplify } from '../types';
 import { createPathParamProxy } from './createPathParamProxy';
 
@@ -36,6 +37,11 @@ export type InferBucketPathObject<TBucket extends Builder<any, AnyDef>> =
         [TKey in InferBucketPathKeys<TBucket>]: string;
       };
 
+export type InferBucketPathOrder<TBucket extends Builder<any, AnyDef>> =
+  InferBucketPathKeys<TBucket> extends never
+    ? []
+    : InferBucketPathKeys<TBucket>[];
+
 export type InferBucketPathObjectFromDef<TDef extends AnyDef> =
   InferBucketPathKeysFromDef<TDef> extends never
     ? Record<string, never>
@@ -53,7 +59,11 @@ type InferMetadataObjectFromDef<TDef extends AnyDef> =
     ? Awaited<ReturnType<TDef['metadata']>>
     : Record<string, never>;
 
-export type AnyContext = Record<string, string | undefined | null>;
+export type AnyContextValue = string | undefined | null | AnyContext;
+
+export interface AnyContext {
+  [key: string]: AnyContextValue;
+}
 
 export type AnyInput = z.AnyZodObject | z.ZodNever;
 
@@ -77,9 +87,7 @@ type Conditions<TPath extends AnyPath> = {
 export type AccessControlSchema<TCtx, TDef extends AnyDef> = Merge<
   {
     [TKey in keyof TCtx]?:
-      | string
-      | PathParam<TDef['path']>
-      | Conditions<TDef['path']>;
+      string | PathParam<TDef['path']> | Conditions<TDef['path']>;
   },
   {
     OR?: AccessControlSchema<TCtx, TDef>[];
@@ -88,6 +96,14 @@ export type AccessControlSchema<TCtx, TDef extends AnyDef> = Merge<
   }
 >;
 
+export type AccessControl<TCtx, TDef extends AnyDef> =
+  'private' | AccessControlSchema<TCtx, TDef>;
+
+export type AutoSignedUrlsConfig = {
+  expiresIn?: number;
+  includeThumbnails?: boolean;
+};
+
 type BucketConfig = {
   /**
    * Maximum size for a single file in bytes
@@ -107,19 +123,17 @@ type BucketConfig = {
   accept?: string[];
 };
 
-type FileInfo = {
-  size: number;
-  type: string;
-  extension: string;
-  fileName?: string;
-  replaceTargetUrl?: string;
-  temporary: boolean;
-};
-
 type BeforeUploadFn<TCtx, TDef extends AnyDef> = (params: {
   ctx: TCtx;
   input: z.infer<TDef['input']>;
-  fileInfo: FileInfo;
+  fileInfo: {
+    size: number;
+    type: string;
+    extension: string;
+    fileName?: string;
+    replaceTargetUrl?: string;
+    temporary: boolean;
+  };
 }) => MaybePromise<boolean>;
 
 type BeforeDeleteFn<TCtx, TDef extends AnyDef> = (params: {
@@ -155,7 +169,8 @@ type Def<
   path: TPath;
   metadata: TMetadata;
   bucketConfig?: BucketConfig;
-  accessControl?: AccessControlSchema<any, any>;
+  accessControl?: AccessControl<any, any>;
+  autoSignedUrls?: AutoSignedUrlsConfig;
   beforeUpload?: BeforeUploadFn<any, any>;
   beforeDelete?: BeforeDeleteFn<any, any>;
 };
@@ -187,6 +202,7 @@ type Builder<TCtx, TDef extends AnyDef> = {
       metadata: TDef['metadata'];
       bucketConfig: TDef['bucketConfig'];
       accessControl: TDef['accessControl'];
+      autoSignedUrls: TDef['autoSignedUrls'];
       beforeUpload: TDef['beforeUpload'];
       beforeDelete: TDef['beforeDelete'];
     }
@@ -217,6 +233,7 @@ type Builder<TCtx, TDef extends AnyDef> = {
       metadata: TDef['metadata'];
       bucketConfig: TDef['bucketConfig'];
       accessControl: TDef['accessControl'];
+      autoSignedUrls: TDef['autoSignedUrls'];
       beforeUpload: TDef['beforeUpload'];
       beforeDelete: TDef['beforeDelete'];
     }
@@ -237,6 +254,7 @@ type Builder<TCtx, TDef extends AnyDef> = {
       metadata: MetadataFn<any, any, TMetadata>;
       bucketConfig: TDef['bucketConfig'];
       accessControl: TDef['accessControl'];
+      autoSignedUrls: TDef['autoSignedUrls'];
       beforeUpload: TDef['beforeUpload'];
       beforeDelete: TDef['beforeDelete'];
     }
@@ -247,7 +265,26 @@ type Builder<TCtx, TDef extends AnyDef> = {
    * This means that images will only be accessible from within your app.
    * And only if it passes the check set in this function.
    */
-  accessControl(accessControl: AccessControlSchema<TCtx, TDef>): Builder<
+  accessControl(accessControl: AccessControl<TCtx, TDef>): Builder<
+    TCtx,
+    {
+      type: TDef['type'];
+      input: TDef['input'];
+      path: TDef['path'];
+      metadata: TDef['metadata'];
+      bucketConfig: TDef['bucketConfig'];
+      accessControl: AccessControl<any, any>;
+      autoSignedUrls: TDef['autoSignedUrls'];
+      beforeUpload: TDef['beforeUpload'];
+      beforeDelete: TDef['beforeDelete'];
+    }
+  >;
+  /**
+   * Automatically return temporary signed read URLs after uploads.
+   *
+   * This requires explicit non-public access control.
+   */
+  autoSignedUrls(config?: AutoSignedUrlsConfig): Builder<
     TCtx,
     {
       type: TDef['type'];
@@ -255,7 +292,8 @@ type Builder<TCtx, TDef extends AnyDef> = {
       path: TDef['path'];
       metadata: TDef['metadata'];
       bucketConfig: TDef['bucketConfig'];
-      accessControl: AccessControlSchema<any, any>;
+      accessControl: TDef['accessControl'];
+      autoSignedUrls: AutoSignedUrlsConfig;
       beforeUpload: TDef['beforeUpload'];
       beforeDelete: TDef['beforeDelete'];
     }
@@ -274,6 +312,7 @@ type Builder<TCtx, TDef extends AnyDef> = {
       metadata: TDef['metadata'];
       bucketConfig: TDef['bucketConfig'];
       accessControl: TDef['accessControl'];
+      autoSignedUrls: TDef['autoSignedUrls'];
       beforeUpload: BeforeUploadFn<any, any>;
       beforeDelete: TDef['beforeDelete'];
     }
@@ -292,6 +331,7 @@ type Builder<TCtx, TDef extends AnyDef> = {
       metadata: TDef['metadata'];
       bucketConfig: TDef['bucketConfig'];
       accessControl: TDef['accessControl'];
+      autoSignedUrls: TDef['autoSignedUrls'];
       beforeUpload: TDef['beforeUpload'];
       beforeDelete: BeforeDeleteFn<any, any>;
     }
@@ -330,7 +370,8 @@ function createBuilder<
     path: TPath;
     metadata: TMetadata;
     bucketConfig?: BucketConfig;
-    accessControl?: AccessControlSchema<any, any>;
+    accessControl?: AccessControl<any, any>;
+    autoSignedUrls?: AutoSignedUrlsConfig;
     beforeUpload?: BeforeUploadFn<any, any>;
     beforeDelete?: BeforeDeleteFn<any, any>;
   }
@@ -355,11 +396,31 @@ function createBuilder<
       }) as any;
     },
     path(pathResolver) {
-      // TODO: Should throw a runtime error in the following cases:
-      // 1. in case of multiple keys in one object
-      // 2. in case of duplicate keys
       const pathParamProxy = createPathParamProxy();
       const params = pathResolver(pathParamProxy);
+      const pathKeys = new Set<string>();
+      for (const param of params) {
+        const entries = Object.entries(param);
+        if (entries.length !== 1) {
+          const foundKeys = entries.map(([key]) => key);
+          throw new EdgeStoreError({
+            message: `Path params must have exactly one key. Found keys: ${
+              foundKeys.length > 0 ? foundKeys.join(', ') : '(none)'
+            }`,
+            code: 'SERVER_ERROR',
+          });
+        }
+        const key = entries[0]?.[0];
+        if (key !== undefined && pathKeys.has(key)) {
+          throw new EdgeStoreError({
+            message: `Duplicate path param found: ${key}`,
+            code: 'SERVER_ERROR',
+          });
+        }
+        if (key !== undefined) {
+          pathKeys.add(key);
+        }
+      }
       return createNewBuilder(_def, {
         path: params,
       }) as any;
@@ -370,10 +431,36 @@ function createBuilder<
       }) as any;
     },
     accessControl(accessControl) {
+      if (
+        typeof accessControl === 'object' &&
+        Object.keys(accessControl).length === 0
+      ) {
+        throw new EdgeStoreError({
+          message:
+            'Empty accessControl objects are not allowed. Use accessControl("private") for signed-URL-only private files.',
+          code: 'SERVER_ERROR',
+        });
+      }
       return createNewBuilder(_def, {
         accessControl: accessControl,
       }) as any;
     },
+    autoSignedUrls(config) {
+      if (_def.accessControl === undefined) {
+        throw new EdgeStoreError({
+          message:
+            'autoSignedUrls requires a non-public bucket. Add accessControl("private") or an access-control schema first.',
+          code: 'SERVER_ERROR',
+        });
+      }
+      return createNewBuilder(_def, {
+        autoSignedUrls: {
+          expiresIn: config?.expiresIn,
+          includeThumbnails:
+            config?.includeThumbnails ?? (_def.type === 'IMAGE' ? true : false),
+        },
+      }) as any;
+    },
     beforeUpload(beforeUpload) {
       return createNewBuilder(_def, {
         beforeUpload,
@@ -397,7 +484,13 @@ class EdgeStoreBuilder<TCtx = Record<string, never>> {
   }
 }
 
-export type EdgeStoreRouter<TCtx> = {
+export type EdgeStoreRouter<
+  TCtx,
+  TBuckets extends Record<string, Builder<TCtx, AnyDef>> = Record<
+    string,
+    Builder<TCtx, AnyDef>
+  >,
+> = {
   /**
    * Only used for types
    * @internal
@@ -405,10 +498,10 @@ export type EdgeStoreRouter<TCtx> = {
   $config: {
     ctx: TCtx;
   };
-  buckets: Record<string, Builder<TCtx, AnyDef>>;
+  buckets: TBuckets;
 };
 
-export type AnyRouter = EdgeStoreRouter<any>;
+export type AnyRouter = EdgeStoreRouter<any, Record<string, AnyBuilder>>;
 
 function createRouterFactory<TCtx>() {
   return function createRouterInner<
@@ -419,7 +512,7 @@ function createRouterFactory<TCtx>() {
         ctx: undefined as TCtx,
       },
       buckets,
-    } satisfies EdgeStoreRouter<TCtx>;
+    } satisfies EdgeStoreRouter<TCtx, TBuckets>;
   };
 }
 

package/src/internals/providerTypes.ts

@@ -50,6 +50,10 @@ export type RequestUploadParams = {
     replaceTargetUrl?: string;
     temporary: boolean;
   };
+  autoSignedUrls?: {
+    expiresIn?: number;
+    includeThumbnails?: boolean;
+  };
 };
 
 export type RequestUploadPartsParams = {
@@ -88,6 +92,10 @@ export type RequestUploadRes =
       uploadUrl: string;
       accessUrl: string;
       thumbnailUrl?: string | null;
+      accessSignedUrl?: string;
+      accessSignedThumbnailUrl?: string | null;
+      accessSignedUrlExpiresAt?: Date | string;
+      accessSignedUrlExpiresIn?: number;
     }
   | {
       multipart: {
@@ -102,8 +110,28 @@ export type RequestUploadRes =
       };
       accessUrl: string;
       thumbnailUrl?: string | null;
+      accessSignedUrl?: string;
+      accessSignedThumbnailUrl?: string | null;
+      accessSignedUrlExpiresAt?: Date | string;
+      accessSignedUrlExpiresIn?: number;
     };
 
+export type GetSignedUrlsParams = {
+  bucketName: string;
+  urls: string[];
+  expiresIn?: number;
+  includeThumbnails?: boolean;
+};
+
+export type GetSignedUrlRes = {
+  url: string;
+  signedUrl: string;
+  expiresAt: Date;
+  expiresIn: number;
+  thumbnailUrl?: string | null;
+  signedThumbnailUrl?: string | null;
+};
+
 export type ConfirmUpload = {
   bucket: AnyBuilder;
   url: string;
@@ -133,6 +161,9 @@ export type Provider = {
   requestUploadParts: (
     params: RequestUploadPartsParams,
   ) => MaybePromise<RequestUploadPartsRes>;
+  getSignedUrls?: (
+    params: GetSignedUrlsParams,
+  ) => MaybePromise<GetSignedUrlRes[]>;
   completeMultipartUpload: (
     params: CompleteMultipartUploadParams,
   ) => MaybePromise<CompleteMultipartUploadRes>;

package/src/internals/sharedFuncTypes.ts

@@ -11,6 +11,7 @@ export type SharedInitRes = {
   token: string | undefined;
   baseUrl: string;
   providerName: string;
+  requiresFileAccessCookie: boolean;
 };
 export type SharedRequestUploadRes = Simplify<
   RequestUploadRes & {

package/src/internals/types.ts

@@ -1,3 +1,18 @@
+import { type MaybePromise } from '../types';
+
+export type ClientUploadTransform = (params: {
+  file: File;
+  extension: string;
+  signal?: AbortSignal;
+}) => MaybePromise<
+  | File
+  | Blob
+  | {
+      file: File | Blob;
+      extension: string;
+    }
+>;
+
 export type UploadOptions = {
   /**
    * e.g. 'my-file-name.jpg'
@@ -26,4 +41,12 @@ export type UploadOptions = {
    * This avoids unnecessary zombie files in the bucket.
    */
   temporary?: boolean;
+  /**
+   * Transform the file before it is validated and uploaded.
+   *
+   * This can be used to compress images, convert formats, encrypt files, etc.
+   * The transformed file's size, MIME type, and extension will be used for the
+   * upload request.
+   */
+  transform?: ClientUploadTransform;
 };

package/src/types.ts

@@ -21,8 +21,8 @@ export type FlatOverwrite<TType, TWith> = InferOptional<
     [TKey in keyof TType | keyof TWith]: TKey extends keyof TWith
       ? TWith[TKey]
       : TKey extends keyof TType
-      ? TType[TKey]
-      : never;
+        ? TType[TKey]
+        : never;
   },
   UndefinedKeys<TType> | UndefinedKeys<TWith>
 >;
@@ -49,9 +49,8 @@ export type Maybe<TType> = TType | null | undefined;
 /**
  * @internal
  */
-export type ThenArg<TType> = TType extends PromiseLike<infer U>
-  ? ThenArg<U>
-  : TType;
+export type ThenArg<TType> =
+  TType extends PromiseLike<infer U> ? ThenArg<U> : TType;
 
 /**
  * @internal
@@ -66,7 +65,6 @@ export type Simplify<TType> = TType extends any[] | Date
  */
 export type Prettify<TType> = {
   [K in keyof TType]: TType[K];
-  // eslint-disable-next-line @typescript-eslint/ban-types
 } & {};
 
 /**

package/dist/errors/EdgeStoreError.mjs

@@ -1,49 +0,0 @@
-function _define_property(obj, key, value) {
-    if (key in obj) {
-        Object.defineProperty(obj, key, {
-            value: value,
-            enumerable: true,
-            configurable: true,
-            writable: true
-        });
-    } else {
-        obj[key] = value;
-    }
-    return obj;
-}
-/* eslint-disable @typescript-eslint/no-non-null-assertion */ 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
-};
-class EdgeStoreError extends Error {
-    formattedMessage() {
-        return `${this.message}${this.details ? `\n    Details: ${JSON.stringify(this.details)}` : ''}${this.cause ? `\n    Caused by: ${this.cause.message}` : ''}`;
-    }
-    formattedJson() {
-        return {
-            message: this.code === 'SERVER_ERROR' ? 'Internal server error' : this.message,
-            code: this.code,
-            details: this.details
-        };
-    }
-    constructor(opts){
-        super(opts.message);
-        _define_property(this, "cause", void 0);
-        _define_property(this, "code", void 0);
-        _define_property(this, "level", void 0);
-        _define_property(this, "details", void 0);
-        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;
-    }
-}
-
-export { EDGE_STORE_ERROR_CODES, EdgeStoreError };

package/dist/errors/index.mjs

@@ -1,23 +0,0 @@
-function _define_property(obj, key, value) {
-    if (key in obj) {
-        Object.defineProperty(obj, key, {
-            value: value,
-            enumerable: true,
-            configurable: true,
-            writable: true
-        });
-    } else {
-        obj[key] = value;
-    }
-    return obj;
-}
-class EdgeStoreApiClientError extends Error {
-    constructor(opts){
-        super(opts.response.message);
-        _define_property(this, "data", void 0);
-        this.name = 'EdgeStoreApiClientError';
-        this.data = opts.response;
-    }
-}
-
-export { EdgeStoreApiClientError };

package/dist/index.mjs

@@ -1,3 +0,0 @@
-export { EdgeStoreApiClientError } from './errors/index.mjs';
-export { initEdgeStore } from './internals/bucketBuilder.mjs';
-export { EDGE_STORE_ERROR_CODES, EdgeStoreError } from './errors/EdgeStoreError.mjs';