syntax = "proto3";

package artifact.v1alpha;

// Google API
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
// Protocol Buffers Well-Known Types
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

// Object represents a blob storage object.
message Object {
  option (google.api.resource) = {
    type: "api.instill.tech/Object"
    pattern: "namespaces/{namespace}/objects/{object}"
  };

  // Canonical resource name.
  // Format: `namespaces/{namespace}/objects/{object}`
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Immutable canonical resource ID (e.g., "obj-3k7m9p2w5t1").
  // Hash-based, unique within a namespace.
  string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Human-readable display name (user-provided filename).
  string display_name = 3 [(google.api.field_behavior) = OPTIONAL];

  // Resource name of the owner namespace.
  // Format: `namespaces/{namespace}`
  string owner_name = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Full resource name of the user who created this object.
  // Format: `users/{user}`
  string creator_name = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Object creation time.
  google.protobuf.Timestamp create_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Object update time.
  google.protobuf.Timestamp update_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Size in bytes.
  int64 size = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Content type (MIME type from Content-Type header or file extension).
  string content_type = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Whether the file has been uploaded to storage.
  bool is_uploaded = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Object expiration time in days.
  // If set to 0, the object will not be deleted automatically.
  int32 object_expire_days = 11 [(google.api.field_behavior) = OPTIONAL];

  // Last modified time (client-provided metadata).
  optional google.protobuf.Timestamp last_modified_time = 12 [(google.api.field_behavior) = OPTIONAL];

  // Object delete time (for soft delete). Output only.
  optional google.protobuf.Timestamp delete_time = 13 [(google.api.field_behavior) = OUTPUT_ONLY];

  // URL-friendly slug derived from display_name.
  // Example: "my-document-pdf"
  string slug = 14 [(google.api.field_behavior) = OPTIONAL];

  // Previous slugs for backward compatibility when display_name changes.
  repeated string aliases = 15 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// GetObjectUploadURLRequest represents a request to get a presigned upload URL.
// Follows AIP-133 (Create pattern with custom method).
message GetObjectUploadURLRequest {
  // The parent resource name.
  // Format: `namespaces/{namespace}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Display name for the object (user-provided filename, max 1024 characters).
  // This will be stored as the object's display_name.
  string display_name = 2 [(google.api.field_behavior) = REQUIRED];

  // URL expiration time in days.
  // Maximum is 7 days. If set to 0, URL will not expire.
  int32 url_expire_days = 3 [(google.api.field_behavior) = OPTIONAL];

  // Last modified time (client-provided metadata).
  // Must be in RFC3339 formatted date-time string.
  google.protobuf.Timestamp last_modified_time = 4 [(google.api.field_behavior) = OPTIONAL];

  // Object expiration time in days.
  // Minimum is 1 day. If set to 0, the object will not be deleted
  // automatically.
  int32 object_expire_days = 5 [(google.api.field_behavior) = OPTIONAL];
}

// GetObjectUploadURLResponse
message GetObjectUploadURLResponse {
  // upload url
  string upload_url = 1;
  // expire at in UTC (UTC+0)
  google.protobuf.Timestamp url_expire_at = 2;
  // object
  Object object = 3;
}

// GetObjectDownloadURLRequest represents a request to get a presigned download
// URL. Follows AIP-131 (Get pattern with custom method).
message GetObjectDownloadURLRequest {
  // The resource name of the object.
  // Format: `namespaces/{namespace}/objects/{object}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/Object"}
  ];

  // URL expiration time in days.
  // Maximum is 7 days. If set to 0, URL will not expire.
  int32 url_expire_days = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional custom filename for the download.
  // If provided, this filename will be used in the Content-Disposition header.
  string download_filename = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional output format for the download.
  // Supported values: "pdf". When set, the backend converts the object
  // on-demand (supported for DOC, DOCX, PPT, PPTX, XLS, XLSX) and returns
  // a presigned URL to the converted file. The result is cached in storage
  // so subsequent requests are served instantly.
  string format = 4 [(google.api.field_behavior) = OPTIONAL];
}

// GetObjectDownloadURLResponse
message GetObjectDownloadURLResponse {
  // download url
  string download_url = 1;
  // expire at in UTC (UTC+0)
  google.protobuf.Timestamp url_expire_at = 2;
  // object
  Object object = 3;
}

// GetObjectRequest represents a request to get an object.
// Follows AIP-131.
message GetObjectRequest {
  // The resource name of the object to retrieve.
  // Format: `namespaces/{namespace}/objects/{object}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/Object"}
  ];
}

// GetObjectResponse contains the requested object.
message GetObjectResponse {
  // The requested object.
  Object object = 1;
}

// UpdateObjectRequest represents a request to update an object.
// Follows AIP-134: resource's `name` field identifies it.
message UpdateObjectRequest {
  // The object to update. The object's `name` field identifies it.
  // Format: `namespaces/{namespace}/objects/{object}`
  Object object = 1 [(google.api.field_behavior) = REQUIRED];

  // The update mask specifies which fields to update.
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = OPTIONAL];
}

// UpdateObjectResponse contains the updated object.
message UpdateObjectResponse {
  // The updated object.
  Object object = 1;
}

// DeleteObjectRequest represents a request to delete an object.
// Follows AIP-135.
message DeleteObjectRequest {
  // The resource name of the object to delete.
  // Format: `namespaces/{namespace}/objects/{object}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/Object"}
  ];
}

// DeleteObjectResponse is an empty response for deleting an object.
message DeleteObjectResponse {}

// Admin-only object operations

// GetObjectAdminRequest represents a request to get an object by name (admin
// only).
message GetObjectAdminRequest {
  // The resource name of the object.
  // Format: `namespaces/{namespace}/objects/{object}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/Object"}
  ];
}

// GetObjectAdminResponse contains the requested object (admin only).
message GetObjectAdminResponse {
  // The requested object.
  Object object = 1;
}

// UpdateObjectAdminRequest represents a request to update an object by name
// (admin only).
message UpdateObjectAdminRequest {
  // The resource name of the object.
  // Format: `namespaces/{namespace}/objects/{object}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/Object"}
  ];

  // Size in bytes.
  optional int64 size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Content type (MIME type).
  optional string content_type = 3 [(google.api.field_behavior) = OPTIONAL];

  // Whether the file has been uploaded.
  optional bool is_uploaded = 4 [(google.api.field_behavior) = OPTIONAL];

  // Last modified time (client-provided metadata).
  optional google.protobuf.Timestamp last_modified_time = 5 [(google.api.field_behavior) = OPTIONAL];
}

// UpdateObjectAdminResponse contains the updated object (admin only).
message UpdateObjectAdminResponse {
  // The updated object.
  Object object = 1;
}

// TransferObjectsNamespaceAdminRequest transfers objects from one namespace to
// another (admin only). Follows AIP-136 (custom method).
//
// Used by agent-backend during visitor chat claim to move generated artifacts
// (images, code outputs, etc.) to the new user's namespace after signup.
message TransferObjectsNamespaceAdminRequest {
  // The object IDs to transfer.
  // Format: hash-based IDs (e.g., "obj-a1b2c3d4e5f6g7h8").
  repeated string object_ids = 1 [(google.api.field_behavior) = REQUIRED];

  // The target namespace resource name.
  // Format: `namespaces/{namespace}`
  string new_namespace = 2 [(google.api.field_behavior) = REQUIRED];

  // The new creator's user resource name.
  // Format: `users/{user}`
  string new_creator = 3 [(google.api.field_behavior) = REQUIRED];
}

// TransferObjectsNamespaceAdminResponse is the response after transferring
// objects.
message TransferObjectsNamespaceAdminResponse {
  // The number of objects successfully transferred.
  int32 transferred_count = 1;
}