@edgestore/shared 1.0.0-next.0 → 1.0.0-next.2

package/src/internals/providerTypes.ts

@@ -1,33 +1,24 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import { type MaybePromise } from '../types';
 import {
-  type AnyBuilder,
+  type AnyContext,
   type AnyMetadata,
   type EdgeStoreRouter,
 } from './bucketBuilder';
 
-export type InitParams = {
-  ctx: any;
-  router: EdgeStoreRouter<any>;
+export type InitParams<TCtx extends AnyContext = AnyContext> = {
+  ctx: TCtx;
+  router: EdgeStoreRouter<TCtx>;
 };
 
-export type InitRes = {
-  token?: string;
-};
-
-export type GetFileParams = {
-  url: string;
+export type ClientInit = {
+  path: string;
+  headers?: Record<string, string>;
 };
 
-export type GetFileRes = {
-  url: string;
-  size: number;
-  uploadedAt: Date;
-  path: {
-    [key: string]: string;
-  };
-  metadata: {
-    [key: string]: string;
-  };
+export type InitRes = {
+  token?: string;
+  clientInit?: ClientInit;
 };
 
 export type RequestUploadParams = {
@@ -38,6 +29,7 @@ export type RequestUploadParams = {
   bucketName: string;
   bucketType: string;
   fileInfo: {
+    type?: string;
     size: number;
     extension: string;
     isPublic: boolean;
@@ -56,6 +48,160 @@ export type RequestUploadParams = {
   };
 };
 
+export type ProviderFilterValue =
+  | string
+  | Partial<{
+      eq: string;
+      neq: string;
+      gt: string;
+      gte: string;
+      lt: string;
+      lte: string;
+      startsWith: string;
+      endsWith: string;
+      between: [string, string];
+    }>;
+
+export type ListFilesFilter = {
+  AND?: ListFilesFilter[];
+  OR?: ListFilesFilter[];
+  uploadedAt?: ProviderFilterValue;
+  path?: Record<string, ProviderFilterValue>;
+  metadata?: Record<string, ProviderFilterValue>;
+};
+
+export type FileReference = { id: string } | { key: string } | { url: string };
+
+export type ProviderFile = {
+  id: string;
+  url: string;
+  key: string;
+  thumbnailUrl: string | null;
+  thumbnailKey: string | null;
+  bucketId: string;
+  bucketName: string;
+  projectId: string;
+  accountId: string;
+  name: string;
+  path: Record<string, string>;
+  metadata: Record<string, string>;
+  sizeBytes: number;
+  mimeType: string | null;
+  state: 'requested' | 'uploaded' | 'deleted' | 'replace_requested';
+  temporary: boolean;
+  uploadedAt: Date;
+  updatedAt: Date;
+};
+
+export type BackendFile = {
+  url: string;
+  sizeBytes: number;
+  /** Router-derived path values, when this operation retrieves them. */
+  path?: Record<string, string>;
+  /** Router-derived metadata values, when this operation retrieves them. */
+  metadata?: Record<string, string>;
+  uploadedAt: Date | string;
+  updatedAt: Date | string;
+};
+
+export type ProviderFileMutationResult<
+  TErrorCode extends string =
+    | 'FILE_NOT_CONFIRMABLE'
+    | 'FILE_NOT_DELETABLE'
+    | 'FILE_NOT_RESTORABLE'
+    | 'INVALID_FILE_REF',
+> = {
+  results: (
+    | { success: true }
+    | {
+        success: false;
+        error: {
+          code: TErrorCode;
+          message: string;
+        };
+      }
+  )[];
+};
+
+export type BackendUploadParams = {
+  bucketName: string;
+  bucketType: string;
+  fileInfo: RequestUploadParams['fileInfo'];
+  autoSignedUrls?: RequestUploadParams['autoSignedUrls'];
+  source: Blob;
+  signal?: AbortSignal;
+  onProgress?: (progress: {
+    transferredBytes: number;
+    totalBytes: number;
+    percentage: number;
+    phase: 'preparing' | 'uploading' | 'processing';
+  }) => void;
+};
+
+export type BackendUploadResult<TFile extends BackendFile = ProviderFile> = {
+  file: TFile;
+  signedReadUrl?: {
+    signedUrl: string;
+    signedThumbnailUrl?: string | null;
+    expiresAt: Date | string;
+    expiresIn: number;
+  };
+};
+
+export type BackendUploadOperation<TFile extends BackendFile = ProviderFile> = (
+  params: BackendUploadParams,
+) => MaybePromise<BackendUploadResult<TFile>>;
+
+export type BackendGetFileOperation<
+  TFile extends BackendFile = ProviderFile,
+  TFileReference = FileReference,
+> = (params: {
+  bucketName: string;
+  file: TFileReference;
+}) => MaybePromise<TFile>;
+
+export type BackendListFilesResult<
+  TFile extends BackendFile = ProviderFile,
+  TCursor = string,
+> = {
+  items: TFile[];
+  limit: number;
+  nextCursor: TCursor | null;
+  hasMore: boolean;
+};
+
+export type BackendListFilesOperation<
+  TFile extends BackendFile = ProviderFile,
+  TCursor = string,
+> = (params: {
+  bucketName: string;
+  filter?: ListFilesFilter;
+  cursor?: TCursor;
+  limit?: number;
+}) => MaybePromise<BackendListFilesResult<TFile, TCursor>>;
+
+export type BackendFileMutationOperation<
+  TFileReference = FileReference,
+  TErrorCode extends string =
+    | 'FILE_NOT_CONFIRMABLE'
+    | 'FILE_NOT_DELETABLE'
+    | 'FILE_NOT_RESTORABLE'
+    | 'INVALID_FILE_REF',
+> = (params: {
+  bucketName: string;
+  files: TFileReference[];
+}) => MaybePromise<ProviderFileMutationResult<TErrorCode>>;
+
+export type BackendGetSignedUrlsOperation<
+  TFileReference = FileReference,
+  TResult extends GetSignedUrlRes = GetSignedUrlRes,
+> = (params: {
+  bucketName: string;
+  files: TFileReference[];
+  expiresIn?: number;
+  includeThumbnails?: boolean;
+}) => MaybePromise<TResult[]>;
+
 export type RequestUploadPartsParams = {
   multipart: {
     uploadId: string;
@@ -83,46 +229,35 @@ export type CompleteMultipartUploadParams = {
   }[];
 };
 
-export type CompleteMultipartUploadRes = {
-  success: boolean;
+type RequestUploadAccess = {
+  accessUrl: string;
+  thumbnailUrl?: string | null;
+  accessSignedUrl?: string;
+  accessSignedThumbnailUrl?: string | null;
+  accessSignedUrlExpiresAt?: Date | string;
+  accessSignedUrlExpiresIn?: number;
 };
 
-export type RequestUploadRes =
-  | {
+export type SinglePartRequestUploadRes = RequestUploadAccess & {
+  uploadUrl: string;
+};
+
+export type MultipartRequestUploadRes = RequestUploadAccess & {
+  multipart: {
+    key: string;
+    uploadId: string;
+    partSize: number;
+    totalParts: number;
+    parts: {
+      partNumber: number;
       uploadUrl: string;
-      accessUrl: string;
-      thumbnailUrl?: string | null;
-      accessSignedUrl?: string;
-      accessSignedThumbnailUrl?: string | null;
-      accessSignedUrlExpiresAt?: Date | string;
-      accessSignedUrlExpiresIn?: number;
-    }
-  | {
-      multipart: {
-        key: string;
-        uploadId: string;
-        partSize: number;
-        totalParts: number;
-        parts: {
-          partNumber: number;
-          uploadUrl: string;
-        }[];
-      };
-      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 RequestUploadRes =
+  SinglePartRequestUploadRes | MultipartRequestUploadRes;
+
 export type GetSignedUrlRes = {
   url: string;
   signedUrl: string;
@@ -132,41 +267,113 @@ export type GetSignedUrlRes = {
   signedThumbnailUrl?: string | null;
 };
 
-export type ConfirmUpload = {
-  bucket: AnyBuilder;
-  url: string;
+export type ProviderReferenceDefinition<
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
+> = {
+  schema: TSchema;
+  fromUrl: (url: string) => MaybePromise<unknown>;
 };
 
-export type ConfirmUploadRes = {
-  success: boolean;
+type ProviderUploadBase<
+  TUpload extends BackendUploadOperation<BackendFile> | undefined =
+    BackendUploadOperation<BackendFile> | undefined,
+> = {
+  upload?: TUpload;
 };
 
-export type DeleteFileParams = {
-  bucket: AnyBuilder;
-  url: string;
+export type ProviderMultipartUploads = {
+  requestParts: (
+    params: RequestUploadPartsParams,
+  ) => MaybePromise<RequestUploadPartsRes>;
+  complete: (params: CompleteMultipartUploadParams) => MaybePromise<void>;
 };
 
-export type DeleteFileRes = {
-  success: boolean;
+export type ProviderUploads<
+  TUpload extends BackendUploadOperation<BackendFile> | undefined =
+    BackendUploadOperation<BackendFile> | undefined,
+> =
+  | (ProviderUploadBase<TUpload> & {
+      request: (
+        params: RequestUploadParams,
+      ) => MaybePromise<SinglePartRequestUploadRes>;
+      multipart?: never;
+    })
+  | (ProviderUploadBase<TUpload> & {
+      request: (params: RequestUploadParams) => MaybePromise<RequestUploadRes>;
+      multipart: ProviderMultipartUploads;
+    });
+
+export type ProviderFiles<
+  TFileReference = FileReference,
+  TCursor = string,
+  TGet extends BackendGetFileOperation<BackendFile, TFileReference> =
+    BackendGetFileOperation<BackendFile, TFileReference>,
+  TList extends BackendListFilesOperation<BackendFile, TCursor> | undefined =
+    BackendListFilesOperation<BackendFile, TCursor> | undefined,
+  TConfirm extends
+    BackendFileMutationOperation<TFileReference, string> | undefined =
+    BackendFileMutationOperation<TFileReference, string> | undefined,
+  TDelete extends
+    BackendFileMutationOperation<TFileReference, string> | undefined =
+    BackendFileMutationOperation<TFileReference, string> | undefined,
+  TRestore extends
+    BackendFileMutationOperation<TFileReference, string> | undefined =
+    BackendFileMutationOperation<TFileReference, string> | undefined,
+  TGetSignedUrls extends
+    BackendGetSignedUrlsOperation<TFileReference> | undefined =
+    BackendGetSignedUrlsOperation<TFileReference> | undefined,
+> = {
+  cursorSchema?: StandardSchemaV1<unknown, TCursor>;
+  get: TGet;
+  list?: TList;
+  confirm?: TConfirm;
+  delete?: TDelete;
+  restore?: TRestore;
+  getSignedUrls?: TGetSignedUrls;
 };
 
-export type Provider = {
+export type EdgeStoreProvider<
+  TReferenceSchema extends StandardSchemaV1 = StandardSchemaV1<
+    unknown,
+    FileReference
+  >,
+  TCursor = string,
+  TUploads extends ProviderUploads = ProviderUploads,
+  TFiles extends ProviderFiles<
+    StandardSchemaV1.InferOutput<TReferenceSchema>,
+    TCursor
+  > = ProviderFiles<StandardSchemaV1.InferOutput<TReferenceSchema>, TCursor>,
+> = {
   name: string;
-  init: (params: InitParams) => MaybePromise<InitRes>;
-  getBaseUrl: () => MaybePromise<string>;
-  getFile: (params: GetFileParams) => MaybePromise<GetFileRes>;
-  requestUpload: (
-    params: RequestUploadParams,
-  ) => MaybePromise<RequestUploadRes>;
-  requestUploadParts: (
-    params: RequestUploadPartsParams,
-  ) => MaybePromise<RequestUploadPartsRes>;
-  getSignedUrls?: (
-    params: GetSignedUrlsParams,
-  ) => MaybePromise<GetSignedUrlRes[]>;
-  completeMultipartUpload: (
-    params: CompleteMultipartUploadParams,
-  ) => MaybePromise<CompleteMultipartUploadRes>;
-  confirmUpload: (params: ConfirmUpload) => MaybePromise<ConfirmUploadRes>;
-  deleteFile: (params: DeleteFileParams) => MaybePromise<DeleteFileRes>;
+  baseUrl: string | (() => MaybePromise<string>);
+  init: <TCtx extends AnyContext>(
+    params: InitParams<TCtx>,
+  ) => MaybePromise<InitRes>;
+  reference: ProviderReferenceDefinition<TReferenceSchema>;
+  uploads: TUploads;
+  files: TFiles;
+};
+
+export type AnyEdgeStoreProvider = EdgeStoreProvider<
+  StandardSchemaV1<any, any>,
+  any,
+  ProviderUploads,
+  ProviderFiles<any, any>
+>;
+
+export type DefaultEdgeStoreProvider = EdgeStoreProvider<
+  StandardSchemaV1<unknown, FileReference>,
+  string
+> & {
+  uploads: ProviderUploads<BackendUploadOperation> & {
+    upload: BackendUploadOperation;
+  };
+  files: ProviderFiles<FileReference, string> & {
+    get: BackendGetFileOperation;
+    list: BackendListFilesOperation;
+    confirm: BackendFileMutationOperation;
+    delete: BackendFileMutationOperation;
+    restore: BackendFileMutationOperation;
+    getSignedUrls: BackendGetSignedUrlsOperation;
+  };
 };

package/src/internals/schema.ts

@@ -0,0 +1,88 @@
+import { type StandardSchemaV1 } from '@standard-schema/spec';
+import { EdgeStoreError } from '../errors';
+
+export type AnySchema = StandardSchemaV1<any, Record<string, unknown>>;
+
+/** @internal */
+export type AnyInput = AnySchema | undefined;
+
+export type InferSchemaInput<TSchema extends AnyInput> =
+  TSchema extends StandardSchemaV1
+    ? StandardSchemaV1.InferInput<TSchema>
+    : never;
+
+export type InferSchemaOutput<TSchema extends AnyInput> =
+  TSchema extends StandardSchemaV1
+    ? StandardSchemaV1.InferOutput<TSchema>
+    : never;
+
+function formatIssue(issue: StandardSchemaV1.Issue): string {
+  const path = issue.path
+    ?.map((segment) =>
+      typeof segment === 'object' ? String(segment.key) : String(segment),
+    )
+    .join('.');
+
+  return path ? `${path}: ${issue.message}` : issue.message;
+}
+
+/** @internal */
+export function assertStandardSchema(
+  schema: unknown,
+): asserts schema is AnySchema {
+  const protocol =
+    typeof schema === 'object' && schema !== null && '~standard' in schema
+      ? schema['~standard']
+      : undefined;
+
+  if (
+    typeof protocol !== 'object' ||
+    protocol === null ||
+    !('version' in protocol) ||
+    protocol.version !== 1 ||
+    !('validate' in protocol) ||
+    typeof protocol.validate !== 'function'
+  ) {
+    throw new EdgeStoreError({
+      code: 'SERVER_ERROR',
+      message: 'Bucket input schemas must implement Standard Schema V1',
+    });
+  }
+}
+
+/** @internal */
+export async function parseBucketInput<TSchema extends AnyInput>(
+  schema: TSchema,
+  input: unknown,
+): Promise<
+  TSchema extends undefined ? Record<string, never> : InferSchemaOutput<TSchema>
+> {
+  if (schema === undefined) {
+    return {} as TSchema extends undefined
+      ? Record<string, never>
+      : InferSchemaOutput<TSchema>;
+  }
+
+  const result = await schema['~standard'].validate(input);
+  if (result.issues !== undefined) {
+    throw new EdgeStoreError({
+      code: 'BAD_REQUEST',
+      message: `Invalid input: ${result.issues.map(formatIssue).join('; ')}`,
+    });
+  }
+
+  if (
+    typeof result.value !== 'object' ||
+    result.value === null ||
+    Array.isArray(result.value)
+  ) {
+    throw new EdgeStoreError({
+      code: 'SERVER_ERROR',
+      message: 'Bucket input schemas must return an object',
+    });
+  }
+
+  return result.value as TSchema extends undefined
+    ? Record<string, never>
+    : InferSchemaOutput<TSchema>;
+}

package/src/internals/sharedFuncTypes.ts

@@ -1,17 +1,16 @@
 import { type Simplify } from '../types';
 import { type AnyMetadata } from './bucketBuilder';
 import {
-  type DeleteFileRes,
+  type ClientInit,
   type RequestUploadPartsRes,
   type RequestUploadRes,
 } from './providerTypes';
 
 export type SharedInitRes = {
   newCookies: string[];
-  token: string | undefined;
   baseUrl: string;
   providerName: string;
-  requiresFileAccessCookie: boolean;
+  clientInit?: ClientInit;
 };
 export type SharedRequestUploadRes = Simplify<
   RequestUploadRes & {
@@ -23,4 +22,17 @@ export type SharedRequestUploadRes = Simplify<
   }
 >;
 export type SharedRequestUploadPartsRes = RequestUploadPartsRes;
-export type SharedDeleteFileRes = DeleteFileRes;
+
+export type SharedFileMutationRes = {
+  succeeded: string[];
+  failed: {
+    url: string;
+    error: {
+      code: string;
+      message: string;
+    };
+  }[];
+};
+
+export type SharedConfirmUploadsRes = SharedFileMutationRes;
+export type SharedDeleteFilesRes = SharedFileMutationRes;

package/src/internals/types.ts

@@ -32,7 +32,7 @@ export type UploadOptions = {
    */
   replaceTargetUrl?: string;
   /**
-   * If true, the file needs to be confirmed by using the `confirmUpload` function.
+   * If true, the file needs to be confirmed by using the `confirm` 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,