@aepstore-dev/contracts 1.1.0 → 1.2.0

package/gen/upload.ts

@@ -10,84 +10,203 @@ import { Observable } from "rxjs";
 
 export const protobufPackage = "upload.v1";
 
-export interface FileChunk {
-  filename: string;
-  data: Uint8Array;
+/**
+ * Determines the object key prefix (and future ACL/privacy policy).
+ * ATTACHMENT = paid product deliverable (private; presigned GET only after purchase).
+ * MEDIA / AVATAR / BANNER = preview assets.
+ */
+export enum UploadKind {
+  UPLOAD_KIND_UNSPECIFIED = 0,
+  UPLOAD_KIND_ATTACHMENT = 1,
+  UPLOAD_KIND_MEDIA = 2,
+  UPLOAD_KIND_AVATAR = 3,
+  UPLOAD_KIND_BANNER = 4,
+  UNRECOGNIZED = -1,
+}
+
+export interface Ok {
+  ok: boolean;
+}
+
+export interface CreateMultipartUploadRequest {
+  fileName: string;
   mimeType: string;
-  isLast: boolean;
-  chunkIndex: number;
+  fileSize: number;
+  kind: UploadKind;
+  /** user initiating, for key namespacing + audit */
+  ownerId: string;
+}
+
+export interface CreateMultipartUploadResponse {
+  /** S3 multipart UploadId */
   uploadId: string;
+  /** object key this service generated */
+  fileKey: string;
+  /** recommended part size (bytes) the client should slice with */
+  partSize: number;
+  /** number of parts for file_size at part_size */
+  partCount: number;
 }
 
-export interface UploadResponse {
-  fileUrl: string;
-  success: boolean;
-  message: string;
+export interface SignPartRequest {
+  fileKey: string;
   uploadId: string;
+  /** 1-based */
+  partNumber: number;
+}
+
+export interface SignPartResponse {
+  /** presigned PUT URL for this single part */
+  url: string;
+  expiresIn: number;
+}
+
+export interface CompletedPart {
+  partNumber: number;
+  /** ETag the client received in the S3 PUT response header for this part */
+  etag: string;
+}
+
+export interface CompleteMultipartUploadRequest {
+  fileKey: string;
+  uploadId: string;
+  parts: CompletedPart[];
+}
+
+export interface CompleteMultipartUploadResponse {
+  fileKey: string;
+  /** final object location (internal reference) */
+  location: string;
   fileSize: number;
 }
 
-export interface UploadStatusRequest {
+export interface AbortMultipartUploadRequest {
+  fileKey: string;
   uploadId: string;
 }
 
-export interface UploadStatusResponse {
-  status: string;
-  progressPercent: number;
-  message: string;
+export interface CreateUploadUrlRequest {
+  fileName: string;
+  mimeType: string;
+  kind: UploadKind;
+  ownerId: string;
+}
+
+export interface CreateUploadUrlResponse {
+  /** presigned PUT URL (client PUTs the whole file) */
+  url: string;
+  fileKey: string;
+  expiresIn: number;
 }
 
 export interface SignedUrlRequest {
   fileKey: string;
+  /** optional, default 3600 */
   expiresIn: number;
+  /** optional: forces Content-Disposition attachment filename */
+  downloadFileName: string;
 }
 
 export interface SignedUrlResponse {
   signedUrl: string;
-  success: boolean;
-  message: string;
+  expiresIn: number;
+}
+
+export interface DeleteObjectRequest {
+  fileKey: string;
 }
 
 export const UPLOAD_V1_PACKAGE_NAME = "upload.v1";
 
 /**
- * Ported from legacy libs/shared/src/proto/upload.proto.
- * Bumped package to upload.v1 for consistency with the rest of the new stack.
+ * Thin signing service. File bytes NEVER pass through this service — clients
+ * upload/download directly to/from S3 (Yandex Object Storage) using presigned
+ * URLs this service mints. Memory/bandwidth flat regardless of file size.
+ *
+ * Large files (product deliverables, up to ~1GB) use the multipart flow:
+ *   CreateMultipartUpload → (SignPart × N, client PUTs each part to S3) →
+ *   CompleteMultipartUpload   (or AbortMultipartUpload on failure)
+ *
+ * Small files (preview images, avatars) use the single-PUT flow: CreateUploadUrl.
+ *
+ * Downloads are gated elsewhere (products-service verifies purchase, then calls
+ * GenerateSignedUrl). This service does not know about purchases.
  */
 
 export interface UploadServiceClient {
-  uploadFile(request: Observable<FileChunk>): Observable<UploadResponse>;
+  createMultipartUpload(request: CreateMultipartUploadRequest): Observable<CreateMultipartUploadResponse>;
+
+  signPart(request: SignPartRequest): Observable<SignPartResponse>;
+
+  completeMultipartUpload(request: CompleteMultipartUploadRequest): Observable<CompleteMultipartUploadResponse>;
+
+  abortMultipartUpload(request: AbortMultipartUploadRequest): Observable<Ok>;
 
-  getUploadStatus(request: UploadStatusRequest): Observable<UploadStatusResponse>;
+  createUploadUrl(request: CreateUploadUrlRequest): Observable<CreateUploadUrlResponse>;
 
   generateSignedUrl(request: SignedUrlRequest): Observable<SignedUrlResponse>;
+
+  deleteObject(request: DeleteObjectRequest): Observable<Ok>;
 }
 
 /**
- * Ported from legacy libs/shared/src/proto/upload.proto.
- * Bumped package to upload.v1 for consistency with the rest of the new stack.
+ * Thin signing service. File bytes NEVER pass through this service — clients
+ * upload/download directly to/from S3 (Yandex Object Storage) using presigned
+ * URLs this service mints. Memory/bandwidth flat regardless of file size.
+ *
+ * Large files (product deliverables, up to ~1GB) use the multipart flow:
+ *   CreateMultipartUpload → (SignPart × N, client PUTs each part to S3) →
+ *   CompleteMultipartUpload   (or AbortMultipartUpload on failure)
+ *
+ * Small files (preview images, avatars) use the single-PUT flow: CreateUploadUrl.
+ *
+ * Downloads are gated elsewhere (products-service verifies purchase, then calls
+ * GenerateSignedUrl). This service does not know about purchases.
  */
 
 export interface UploadServiceController {
-  uploadFile(request: Observable<FileChunk>): Promise<UploadResponse> | Observable<UploadResponse> | UploadResponse;
+  createMultipartUpload(
+    request: CreateMultipartUploadRequest,
+  ): Promise<CreateMultipartUploadResponse> | Observable<CreateMultipartUploadResponse> | CreateMultipartUploadResponse;
+
+  signPart(request: SignPartRequest): Promise<SignPartResponse> | Observable<SignPartResponse> | SignPartResponse;
+
+  completeMultipartUpload(
+    request: CompleteMultipartUploadRequest,
+  ):
+    | Promise<CompleteMultipartUploadResponse>
+    | Observable<CompleteMultipartUploadResponse>
+    | CompleteMultipartUploadResponse;
 
-  getUploadStatus(
-    request: UploadStatusRequest,
-  ): Promise<UploadStatusResponse> | Observable<UploadStatusResponse> | UploadStatusResponse;
+  abortMultipartUpload(request: AbortMultipartUploadRequest): Promise<Ok> | Observable<Ok> | Ok;
+
+  createUploadUrl(
+    request: CreateUploadUrlRequest,
+  ): Promise<CreateUploadUrlResponse> | Observable<CreateUploadUrlResponse> | CreateUploadUrlResponse;
 
   generateSignedUrl(
     request: SignedUrlRequest,
   ): Promise<SignedUrlResponse> | Observable<SignedUrlResponse> | SignedUrlResponse;
+
+  deleteObject(request: DeleteObjectRequest): Promise<Ok> | Observable<Ok> | Ok;
 }
 
 export function UploadServiceControllerMethods() {
   return function (constructor: Function) {
-    const grpcMethods: string[] = ["getUploadStatus", "generateSignedUrl"];
+    const grpcMethods: string[] = [
+      "createMultipartUpload",
+      "signPart",
+      "completeMultipartUpload",
+      "abortMultipartUpload",
+      "createUploadUrl",
+      "generateSignedUrl",
+      "deleteObject",
+    ];
     for (const method of grpcMethods) {
       const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
       GrpcMethod("UploadService", method)(constructor.prototype[method], method, descriptor);
     }
-    const grpcStreamMethods: string[] = ["uploadFile"];
+    const grpcStreamMethods: string[] = [];
     for (const method of grpcStreamMethods) {
       const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
       GrpcStreamMethod("UploadService", method)(constructor.prototype[method], method, descriptor);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aepstore-dev/contracts",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Protobuf definitions for aepstore microservices",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/proto/upload.proto

@@ -2,48 +2,134 @@ syntax = "proto3";
 
 package upload.v1;
 
-// Ported from legacy libs/shared/src/proto/upload.proto.
-// Bumped package to upload.v1 for consistency with the rest of the new stack.
+// Thin signing service. File bytes NEVER pass through this service — clients
+// upload/download directly to/from S3 (Yandex Object Storage) using presigned
+// URLs this service mints. Memory/bandwidth flat regardless of file size.
+//
+// Large files (product deliverables, up to ~1GB) use the multipart flow:
+//   CreateMultipartUpload → (SignPart × N, client PUTs each part to S3) →
+//   CompleteMultipartUpload   (or AbortMultipartUpload on failure)
+//
+// Small files (preview images, avatars) use the single-PUT flow: CreateUploadUrl.
+//
+// Downloads are gated elsewhere (products-service verifies purchase, then calls
+// GenerateSignedUrl). This service does not know about purchases.
 service UploadService {
-    rpc UploadFile(stream FileChunk) returns (UploadResponse);
-    rpc GetUploadStatus(UploadStatusRequest) returns (UploadStatusResponse);
+    rpc CreateMultipartUpload(CreateMultipartUploadRequest) returns (CreateMultipartUploadResponse);
+    rpc SignPart(SignPartRequest) returns (SignPartResponse);
+    rpc CompleteMultipartUpload(CompleteMultipartUploadRequest) returns (CompleteMultipartUploadResponse);
+    rpc AbortMultipartUpload(AbortMultipartUploadRequest) returns (Ok);
+
+    rpc CreateUploadUrl(CreateUploadUrlRequest) returns (CreateUploadUrlResponse);
+
     rpc GenerateSignedUrl(SignedUrlRequest) returns (SignedUrlResponse);
+
+    rpc DeleteObject(DeleteObjectRequest) returns (Ok);
 }
 
-message FileChunk {
-    string filename = 1;
-    bytes data = 2;
-    string mime_type = 3;
-    bool is_last = 4;
-    int32 chunk_index = 5;
-    string upload_id = 6;
+// Determines the object key prefix (and future ACL/privacy policy).
+// ATTACHMENT = paid product deliverable (private; presigned GET only after purchase).
+// MEDIA / AVATAR / BANNER = preview assets.
+enum UploadKind {
+    UPLOAD_KIND_UNSPECIFIED = 0;
+    UPLOAD_KIND_ATTACHMENT = 1;
+    UPLOAD_KIND_MEDIA = 2;
+    UPLOAD_KIND_AVATAR = 3;
+    UPLOAD_KIND_BANNER = 4;
 }
 
-message UploadResponse {
-    string file_url = 1;
-    bool success = 2;
-    string message = 3;
-    string upload_id = 4;
-    int64 file_size = 5;
+message Ok {
+    bool ok = 1;
 }
 
-message UploadStatusRequest {
-    string upload_id = 1;
+// ---------------------------------------------------------------------------
+// Multipart upload (large files)
+// ---------------------------------------------------------------------------
+
+message CreateMultipartUploadRequest {
+    string file_name = 1;
+    string mime_type = 2;
+    int64 file_size = 3;
+    UploadKind kind = 4;
+    string owner_id = 5; // user initiating, for key namespacing + audit
 }
 
-message UploadStatusResponse {
-    string status = 1;
-    int32 progress_percent = 2;
-    string message = 3;
+message CreateMultipartUploadResponse {
+    string upload_id = 1; // S3 multipart UploadId
+    string file_key = 2;  // object key this service generated
+    int64 part_size = 3;  // recommended part size (bytes) the client should slice with
+    int32 part_count = 4; // number of parts for file_size at part_size
 }
 
-message SignedUrlRequest {
+message SignPartRequest {
     string file_key = 1;
+    string upload_id = 2;
+    int32 part_number = 3; // 1-based
+}
+
+message SignPartResponse {
+    string url = 1;       // presigned PUT URL for this single part
     int32 expires_in = 2;
 }
 
+message CompletedPart {
+    int32 part_number = 1;
+    string etag = 2; // ETag the client received in the S3 PUT response header for this part
+}
+
+message CompleteMultipartUploadRequest {
+    string file_key = 1;
+    string upload_id = 2;
+    repeated CompletedPart parts = 3;
+}
+
+message CompleteMultipartUploadResponse {
+    string file_key = 1;
+    string location = 2; // final object location (internal reference)
+    int64 file_size = 3;
+}
+
+message AbortMultipartUploadRequest {
+    string file_key = 1;
+    string upload_id = 2;
+}
+
+// ---------------------------------------------------------------------------
+// Single-PUT upload (small files)
+// ---------------------------------------------------------------------------
+
+message CreateUploadUrlRequest {
+    string file_name = 1;
+    string mime_type = 2;
+    UploadKind kind = 3;
+    string owner_id = 4;
+}
+
+message CreateUploadUrlResponse {
+    string url = 1;      // presigned PUT URL (client PUTs the whole file)
+    string file_key = 2;
+    int32 expires_in = 3;
+}
+
+// ---------------------------------------------------------------------------
+// Download
+// ---------------------------------------------------------------------------
+
+message SignedUrlRequest {
+    string file_key = 1;
+    int32 expires_in = 2;          // optional, default 3600
+    string download_file_name = 3; // optional: forces Content-Disposition attachment filename
+}
+
 message SignedUrlResponse {
     string signed_url = 1;
-    bool success = 2;
-    string message = 3;
+    int32 expires_in = 2;
+}
+
+// ---------------------------------------------------------------------------
+// Cleanup
+// ---------------------------------------------------------------------------
+
+message DeleteObjectRequest {
+    string file_key = 1;
 }