Client and Bucket Operations

/**
 * Creates a new Google Cloud Storage client using HTTP/JSON transport.
 * The default scope is ScopeFullControl.
 * Clients should be reused and are safe for concurrent use.
 * @param ctx - Context for the operation
 * @param opts - Optional client configuration options
 * @returns Client and error
 */
func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error)

/**
 * Creates a new Google Cloud Storage client using gRPC transport.
 * Provides better performance for large transfers and lower latency.
 * @param ctx - Context for the operation
 * @param opts - Optional client configuration options
 * @returns Client and error
 */
func NewGRPCClient(ctx context.Context, opts ...option.ClientOption) (*Client, error)

/**
 * Checks if gRPC direct connectivity is supported for a bucket.
 * Direct connectivity bypasses Google Front Ends for better performance.
 * @param ctx - Context for the operation
 * @param bucket - Bucket name to check
 * @param opts - Optional client configuration options
 * @returns Error if direct connectivity is not supported
 */
func CheckDirectConnectivitySupported(ctx context.Context, bucket string, opts ...option.ClientOption) error

import (
    "context"
    "cloud.google.com/go/storage"
    "google.golang.org/api/option"
)

// Create HTTP/JSON client with default credentials
ctx := context.Background()
client, err := storage.NewClient(ctx)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Create client with custom credentials
client, err := storage.NewClient(ctx,
    option.WithCredentialsFile("path/to/keyfile.json"),
)

// Create client with read-only scope
client, err := storage.NewClient(ctx,
    option.WithScopes(storage.ScopeReadOnly),
)

// Create gRPC client
grpcClient, err := storage.NewGRPCClient(ctx)
if err != nil {
    log.Fatal(err)
}
defer grpcClient.Close()

// Check direct connectivity support
err = storage.CheckDirectConnectivitySupported(ctx, "my-bucket")
if err != nil {
    log.Printf("Direct connectivity not supported: %v", err)
}

/**
 * Forces the use of Cloud Storage JSON API for read operations.
 * @returns ClientOption for use with NewClient or NewGRPCClient
 */
func WithJSONReads() option.ClientOption

/**
 * Forces the use of Cloud Storage XML API for read operations.
 * @returns ClientOption for use with NewClient or NewGRPCClient
 */
func WithXMLReads() option.ClientOption

/**
 * Disables gRPC metrics export to Cloud Monitoring.
 * Only applicable for gRPC clients.
 * @returns ClientOption for use with NewGRPCClient
 */
func WithDisabledClientMetrics() option.ClientOption

/**
 * Client is a client for interacting with Google Cloud Storage.
 * Clients should be reused instead of created as needed.
 * The methods of Client are safe for concurrent use by multiple goroutines.
 */
type Client struct {
    // contains filtered or unexported fields
}

/**
 * Returns a BucketHandle for the named bucket.
 * This call does not perform any network operations.
 * @param name - Bucket name
 * @returns BucketHandle for the bucket
 */
func (c *Client) Bucket(name string) *BucketHandle

/**
 * Returns an iterator over the buckets in the project.
 * @param ctx - Context for the operation
 * @param projectID - Google Cloud project ID
 * @returns BucketIterator for listing buckets
 */
func (c *Client) Buckets(ctx context.Context, projectID string) *BucketIterator

/**
 * Creates a new HMAC key for the given service account.
 * @param ctx - Context for the operation
 * @param projectID - Google Cloud project ID
 * @param serviceAccountEmail - Service account email address
 * @param opts - Optional HMAC key configuration options
 * @returns HMACKey and error
 */
func (c *Client) CreateHMACKey(ctx context.Context, projectID, serviceAccountEmail string, opts ...HMACKeyOption) (*HMACKey, error)

/**
 * Returns a handle to an HMAC key.
 * @param projectID - Google Cloud project ID
 * @param accessID - HMAC key access ID
 * @returns HMACKeyHandle for the key
 */
func (c *Client) HMACKeyHandle(projectID, accessID string) *HMACKeyHandle

/**
 * Returns an iterator over HMAC keys in the project.
 * @param ctx - Context for the operation
 * @param projectID - Google Cloud project ID
 * @param opts - Optional HMAC key filter options
 * @returns HMACKeysIterator for listing keys
 */
func (c *Client) ListHMACKeys(ctx context.Context, projectID string, opts ...HMACKeyOption) *HMACKeysIterator

/**
 * Retrieves the default service account email for the project.
 * @param ctx - Context for the operation
 * @param projectID - Google Cloud project ID
 * @returns Service account email and error
 */
func (c *Client) ServiceAccount(ctx context.Context, projectID string) (string, error)

/**
 * Configures retry behavior for the client.
 * This affects all operations performed with this client.
 * @param opts - Retry configuration options
 */
func (c *Client) SetRetry(opts ...RetryOption)

/**
 * Closes the client and releases resources.
 * @returns Error if close fails
 */
func (c *Client) Close() error

const (
    // ScopeFullControl grants permissions to manage data and permissions in GCS
    ScopeFullControl = "https://www.googleapis.com/auth/devstorage.full_control"

    // ScopeReadOnly grants permissions to view data in GCS
    ScopeReadOnly = "https://www.googleapis.com/auth/devstorage.read_only"

    // ScopeReadWrite grants permissions to manage data in GCS
    ScopeReadWrite = "https://www.googleapis.com/auth/devstorage.read_write"
)

/**
 * BucketHandle provides operations on a Google Cloud Storage bucket.
 * Use Client.Bucket to get a handle.
 */
type BucketHandle struct {
    // contains filtered or unexported fields
}

/**
 * Creates the bucket in the project.
 * @param ctx - Context for the operation
 * @param projectID - Google Cloud project ID
 * @param attrs - Bucket attributes (nil uses API defaults)
 * @returns Error if creation fails
 */
func (b *BucketHandle) Create(ctx context.Context, projectID string, attrs *BucketAttrs) error

/**
 * Deletes the bucket.
 * The bucket must be empty to be deleted.
 * @param ctx - Context for the operation
 * @returns Error if deletion fails
 */
func (b *BucketHandle) Delete(ctx context.Context) error

/**
 * Returns the bucket's metadata.
 * @param ctx - Context for the operation
 * @returns BucketAttrs and error
 */
func (b *BucketHandle) Attrs(ctx context.Context) (*BucketAttrs, error)

/**
 * Updates the bucket's attributes.
 * @param ctx - Context for the operation
 * @param uattrs - Attributes to update
 * @returns Updated BucketAttrs and error
 */
func (b *BucketHandle) Update(ctx context.Context, uattrs BucketAttrsToUpdate) (*BucketAttrs, error)

/**
 * Returns an ObjectHandle for the named object.
 * This call does not perform any network operations.
 * @param name - Object name
 * @returns ObjectHandle for the object
 */
func (b *BucketHandle) Object(name string) *ObjectHandle

/**
 * Returns an iterator over objects in the bucket.
 * @param ctx - Context for the operation
 * @param q - Query to filter objects (nil lists all objects)
 * @returns ObjectIterator for listing objects
 */
func (b *BucketHandle) Objects(ctx context.Context, q *Query) *ObjectIterator

/**
 * Returns the bucket's ACL handle.
 * This controls who can list, create or overwrite objects in the bucket.
 * @returns ACLHandle for bucket-level access control
 */
func (b *BucketHandle) ACL() *ACLHandle

/**
 * Returns the bucket's default object ACL handle.
 * These ACLs are applied to newly created objects without a defined ACL.
 * @returns ACLHandle for default object access control
 */
func (b *BucketHandle) DefaultObjectACL() *ACLHandle

/**
 * Returns the bucket's IAM handle for policy management.
 * @returns iam.Handle for IAM policy operations
 */
func (b *BucketHandle) IAM() *iam.Handle

/**
 * Generates a signed URL for the specified object.
 * Signed URLs allow time-limited access without authentication.
 * @param object - Object name
 * @param opts - Signed URL options
 * @returns Signed URL string and error
 */
func (b *BucketHandle) SignedURL(object string, opts *SignedURLOptions) (string, error)

/**
 * Generates a PostPolicyV4 for browser-based uploads.
 * @param object - Object name
 * @param opts - POST policy options
 * @returns PostPolicyV4 and error
 */
func (b *BucketHandle) GenerateSignedPostPolicyV4(object string, opts *PostPolicyV4Options) (*PostPolicyV4, error)

/**
 * Adds a Pub/Sub notification configuration to the bucket.
 * @param ctx - Context for the operation
 * @param n - Notification configuration
 * @returns Created Notification and error
 */
func (b *BucketHandle) AddNotification(ctx context.Context, n *Notification) (*Notification, error)

/**
 * Deletes a notification configuration.
 * @param ctx - Context for the operation
 * @param id - Notification ID
 * @returns Error if deletion fails
 */
func (b *BucketHandle) DeleteNotification(ctx context.Context, id string) error

/**
 * Returns all notification configurations for the bucket.
 * @param ctx - Context for the operation
 * @returns Map of notification ID to Notification and error
 */
func (b *BucketHandle) Notifications(ctx context.Context) (map[string]*Notification, error)

/**
 * Locks the bucket's retention policy.
 * After locking, the policy cannot be removed or shortened.
 * @param ctx - Context for the operation
 * @returns Error if lock fails
 */
func (b *BucketHandle) LockRetentionPolicy(ctx context.Context) error

/**
 * Returns a bucket handle with preconditions applied.
 * @param conds - Preconditions for bucket operations
 * @returns BucketHandle with conditions
 */
func (b *BucketHandle) If(conds BucketConditions) *BucketHandle

/**
 * Sets the user project for Requester Pays buckets.
 * @param projectID - Project ID to bill
 * @returns BucketHandle with user project set
 */
func (b *BucketHandle) UserProject(projectID string) *BucketHandle

/**
 * Configures retry behavior for this bucket handle.
 * @param opts - Retry configuration options
 * @returns BucketHandle with retry configuration
 */
func (b *BucketHandle) Retryer(opts ...RetryOption) *BucketHandle

/**
 * Returns the name of the bucket.
 * @returns Bucket name
 */
func (b *BucketHandle) BucketName() string

/**
 * Configures whether to enable object retention for this bucket.
 * Can only be set when creating the bucket.
 * @param enable - True to enable object retention
 * @returns BucketHandle with object retention configured
 */
func (b *BucketHandle) SetObjectRetention(enable bool) *BucketHandle

/**
 * BucketAttrs represents the metadata for a Google Cloud Storage bucket.
 */
type BucketAttrs struct {
    // Name is the name of the bucket
    Name string

    // ACL is the list of access control rules on the bucket
    ACL []ACLRule

    // DefaultObjectACL is the list of access controls to apply to new objects
    // when no object ACL is provided
    DefaultObjectACL []ACLRule

    // Location is the geographic location of the bucket
    Location string

    // LocationType describes the location type (region, dual-region, multi-region)
    LocationType string

    // MetaGeneration is the metadata generation of the bucket
    MetaGeneration int64

    // StorageClass is the default storage class of the bucket
    // Valid values: STANDARD, NEARLINE, COLDLINE, ARCHIVE, MULTI_REGIONAL, REGIONAL
    StorageClass string

    // Created is the creation time of the bucket
    Created time.Time

    // Updated is the last modification time of the bucket metadata
    Updated time.Time

    // VersioningEnabled indicates if object versioning is enabled
    VersioningEnabled bool

    // Labels are user-provided labels for the bucket
    Labels map[string]string

    // RequesterPays reports whether the bucket is a Requester Pays bucket
    // Operations on this bucket require a user project (see UserProject)
    RequesterPays bool

    // Lifecycle is the lifecycle configuration for objects in the bucket
    Lifecycle Lifecycle

    // RetentionPolicy enforces a minimum retention time for objects
    RetentionPolicy *RetentionPolicy

    // ObjectRetentionMode reports whether individual objects can be configured
    // with a retention policy. Read-only. Can only be enabled at bucket creation
    ObjectRetentionMode string

    // CORS is the Cross-Origin Resource Sharing configuration
    CORS []CORS

    // Encryption is the default encryption configuration
    Encryption *BucketEncryption

    // Logging is the access logging configuration
    Logging *BucketLogging

    // Website is the website configuration
    Website *BucketWebsite

    // BucketPolicyOnly is deprecated, use UniformBucketLevelAccess
    BucketPolicyOnly BucketPolicyOnly

    // UniformBucketLevelAccess configures bucket-level IAM access
    UniformBucketLevelAccess UniformBucketLevelAccess

    // PublicAccessPrevention configures public access prevention
    PublicAccessPrevention PublicAccessPrevention

    // DefaultEventBasedHold is the default event-based hold for new objects
    DefaultEventBasedHold bool

    // Etag is the HTTP/1.1 Entity tag for the bucket
    Etag string

    // ProjectNumber is the project number of the project owning the bucket
    ProjectNumber uint64

    // RPO (Recovery Point Objective) configures replication
    RPO RPO

    // CustomPlacementConfig holds custom dual-region configuration
    CustomPlacementConfig *CustomPlacementConfig

    // Autoclass configures automatic storage class management
    Autoclass *Autoclass

    // SoftDeletePolicy defines soft delete retention period
    SoftDeletePolicy *SoftDeletePolicy

    // HierarchicalNamespace enables folder support
    HierarchicalNamespace *HierarchicalNamespace

    // OwnerEntity is the bucket owner in the form "project-owner-projectId"
    OwnerEntity string

    // PredefinedACL is a predefined ACL to apply when creating the bucket
    // Valid values: authenticatedRead, private, projectPrivate, publicRead, publicReadWrite
    PredefinedACL string

    // PredefinedDefaultObjectACL is a predefined default object ACL
    // Valid values: authenticatedRead, bucketOwnerFullControl, bucketOwnerRead,
    // private, projectPrivate, publicRead
    PredefinedDefaultObjectACL string
}

/**
 * BucketAttrsToUpdate defines the attributes to update during an Update call.
 * Use optional.Bool type for boolean fields to distinguish between false and unset.
 */
type BucketAttrsToUpdate struct {
    // VersioningEnabled updates whether the bucket uses versioning
    VersioningEnabled optional.Bool

    // RequesterPays updates whether the bucket is a Requester Pays bucket
    RequesterPays optional.Bool

    // DefaultEventBasedHold is the default event-based hold for new objects
    DefaultEventBasedHold optional.Bool

    // BucketPolicyOnly is deprecated, use UniformBucketLevelAccess
    BucketPolicyOnly *BucketPolicyOnly

    // UniformBucketLevelAccess configures bucket-level IAM access
    UniformBucketLevelAccess *UniformBucketLevelAccess

    // PublicAccessPrevention updates public access prevention policy
    PublicAccessPrevention PublicAccessPrevention

    // StorageClass updates the default storage class
    StorageClass string

    // RetentionPolicy updates the retention policy
    // Use RetentionPolicy.RetentionPeriod = 0 to delete the policy
    RetentionPolicy *RetentionPolicy

    // CORS replaces the CORS configuration
    // An empty (rather than nil) slice removes all CORS policies
    CORS []CORS

    // Encryption updates the default encryption configuration
    Encryption *BucketEncryption

    // Logging updates the access logging configuration
    Logging *BucketLogging

    // Website updates the website configuration
    Website *BucketWebsite

    // PredefinedACL applies a predefined ACL during update
    PredefinedACL string

    // PredefinedDefaultObjectACL applies a predefined default object ACL
    PredefinedDefaultObjectACL string

    // Lifecycle replaces the lifecycle configuration
    Lifecycle *Lifecycle

    // RPO updates the Recovery Point Objective
    RPO RPO

    // Autoclass updates the autoclass configuration
    Autoclass *Autoclass

    // SoftDeletePolicy updates the soft delete policy
    SoftDeletePolicy *SoftDeletePolicy
}

/**
 * Sets a user-defined label on the bucket.
 * @param name - Label key
 * @param value - Label value
 */
func (ua *BucketAttrsToUpdate) SetLabel(name, value string)

/**
 * Deletes a user-defined label from the bucket.
 * @param name - Label key to delete
 */
func (ua *BucketAttrsToUpdate) DeleteLabel(name string)

/**
 * BucketConditions constrain bucket methods to act on specific metagenerations.
 */
type BucketConditions struct {
    // MetagenerationMatch specifies that the bucket must have this metageneration
    // for the operation to proceed
    MetagenerationMatch int64

    // MetagenerationNotMatch specifies that the bucket must not have this
    // metageneration for the operation to proceed
    MetagenerationNotMatch int64
}

/**
 * BucketIterator is an iterator over buckets in a project.
 */
type BucketIterator struct {
    // contains filtered or unexported fields
}

/**
 * Returns the next bucket. Returns iterator.Done when iteration is complete.
 * @returns BucketAttrs and error
 */
func (it *BucketIterator) Next() (*BucketAttrs, error)

/**
 * Returns a list of project IDs for projects that could not be reached.
 * This occurs when listing buckets with user project specified.
 * @returns Slice of unreachable project IDs
 */
func (it *BucketIterator) Unreachable() []string

/**
 * Returns pagination information for controlling iteration.
 * @returns iterator.PageInfo
 */
func (it *BucketIterator) PageInfo() *iterator.PageInfo

/**
 * Lifecycle is the lifecycle configuration for objects in the bucket.
 */
type Lifecycle struct {
    // Rules is the list of lifecycle rules
    Rules []LifecycleRule
}

/**
 * LifecycleRule is a lifecycle configuration rule.
 * When all configured conditions are met, the configured action is taken.
 */
type LifecycleRule struct {
    // Action is the action to take when conditions are met
    Action LifecycleAction

    // Condition is the set of conditions that must be met
    Condition LifecycleCondition
}

/**
 * LifecycleAction is a lifecycle configuration action.
 */
type LifecycleAction struct {
    // Type is the action type
    // Values: Delete, SetStorageClass, AbortIncompleteMultipartUpload
    Type string

    // StorageClass is the target storage class (for SetStorageClass action)
    // Values: STANDARD, NEARLINE, COLDLINE, ARCHIVE
    StorageClass string
}

// Lifecycle action constants
const (
    // DeleteAction deletes live and/or archived objects
    DeleteAction = "Delete"

    // SetStorageClassAction changes the storage class
    SetStorageClassAction = "SetStorageClass"

    // AbortIncompleteMPUAction aborts incomplete multipart uploads
    AbortIncompleteMPUAction = "AbortIncompleteMultipartUpload"
)

/**
 * LifecycleCondition is a set of conditions for lifecycle actions.
 * All configured conditions must be met for the action to be taken.
 */
type LifecycleCondition struct {
    // AllObjects matches all objects when AgeInDays is 0
    AllObjects bool

    // AgeInDays is the age of the object in days
    AgeInDays int64

    // CreatedBefore matches objects created before midnight of this date (UTC)
    CreatedBefore time.Time

    // CustomTimeBefore matches objects with CustomTime before midnight (UTC)
    CustomTimeBefore time.Time

    // DaysSinceCustomTime is days elapsed since CustomTime
    DaysSinceCustomTime int64

    // DaysSinceNoncurrentTime is days since noncurrent timestamp (versioned objects)
    DaysSinceNoncurrentTime int64

    // Liveness specifies live or archived objects (versioned buckets)
    Liveness Liveness

    // MatchesPrefix matches objects with any of these name prefixes
    MatchesPrefix []string

    // MatchesStorageClasses matches objects with these storage classes
    MatchesStorageClasses []string

    // MatchesSuffix matches objects with any of these name suffixes
    MatchesSuffix []string

    // NoncurrentTimeBefore matches noncurrent objects before midnight (UTC)
    NoncurrentTimeBefore time.Time

    // NumNewerVersions matches when there are at least N newer versions
    NumNewerVersions int64
}

/**
 * Liveness specifies whether an object is live or archived.
 */
type Liveness int

const (
    // LiveAndArchived includes both live and archived objects
    LiveAndArchived Liveness = iota
    // Live specifies live objects only
    Live
    // Archived specifies archived objects only
    Archived
)

import (
    "cloud.google.com/go/storage"
    "time"
)

// Create lifecycle rules
lifecycle := storage.Lifecycle{
    Rules: []storage.LifecycleRule{
        {
            Action: storage.LifecycleAction{
                Type:         storage.SetStorageClassAction,
                StorageClass: "NEARLINE",
            },
            Condition: storage.LifecycleCondition{
                AgeInDays:             30,
                MatchesStorageClasses: []string{"STANDARD"},
            },
        },
        {
            Action: storage.LifecycleAction{
                Type: storage.DeleteAction,
            },
            Condition: storage.LifecycleCondition{
                AgeInDays: 365,
                Liveness:  storage.Archived,
            },
        },
        {
            Action: storage.LifecycleAction{
                Type: storage.AbortIncompleteMPUAction,
            },
            Condition: storage.LifecycleCondition{
                AgeInDays: 7,
            },
        },
    },
}

// Apply to bucket
bucket := client.Bucket("my-bucket")
attrs, err := bucket.Update(ctx, storage.BucketAttrsToUpdate{
    Lifecycle: &lifecycle,
})

/**
 * CORS is the bucket's Cross-Origin Resource Sharing configuration.
 */
type CORS struct {
    // MaxAge is the Access-Control-Max-Age header value for preflight responses
    MaxAge time.Duration

    // Methods is the list of HTTP methods to include CORS headers for
    // Note: "*" means any method
    Methods []string

    // Origins is the list of origins eligible to receive CORS headers
    // Note: "*" means any origin
    Origins []string

    // ResponseHeaders is the list of headers to allow in responses
    ResponseHeaders []string
}

/**
 * BucketEncryption is a bucket's encryption configuration.
 */
type BucketEncryption struct {
    // DefaultKMSKeyName is a Cloud KMS key for encrypting objects
    // Format: projects/P/locations/L/keyRings/R/cryptoKeys/K
    // The key's location must match the bucket's location
    DefaultKMSKeyName string
}

/**
 * BucketLogging holds the bucket's logging configuration.
 */
type BucketLogging struct {
    // LogBucket is the destination bucket for logs
    LogBucket string

    // LogObjectPrefix is the prefix for log object names
    LogObjectPrefix string
}

/**
 * BucketWebsite holds the bucket's website configuration.
 */
type BucketWebsite struct {
    // MainPageSuffix is appended to the path (e.g., "index.html")
    MainPageSuffix string

    // NotFoundPage is returned for 404 errors
    NotFoundPage string
}

/**
 * UniformBucketLevelAccess configures bucket-level IAM policies.
 */
type UniformBucketLevelAccess struct {
    // Enabled specifies whether only bucket-level IAM policies are used
    Enabled bool

    // LockedTime is the deadline for disabling UBLA
    LockedTime time.Time
}

/**
 * BucketPolicyOnly is deprecated. Use UniformBucketLevelAccess.
 */
type BucketPolicyOnly struct {
    Enabled    bool
    LockedTime time.Time
}

/**
 * PublicAccessPrevention configures public access prevention.
 */
type PublicAccessPrevention int

const (
    // PublicAccessPreventionUnknown is the zero value
    PublicAccessPreventionUnknown PublicAccessPrevention = iota

    // PublicAccessPreventionUnspecified is deprecated, use Inherited
    PublicAccessPreventionUnspecified

    // PublicAccessPreventionEnforced blocks all public access
    PublicAccessPreventionEnforced

    // PublicAccessPreventionInherited is the default (inherits from parent)
    PublicAccessPreventionInherited
)

/**
 * RetentionPolicy enforces minimum retention time for all objects.
 * Locked policies cannot be removed or shortened.
 */
type RetentionPolicy struct {
    // RetentionPeriod is the minimum retention duration
    // Must be greater than zero and less than 100 years
    RetentionPeriod time.Duration

    // EffectiveTime is when the policy became effective (read-only)
    EffectiveTime time.Time

    // IsLocked indicates if the policy is locked (read-only)
    IsLocked bool
}

/**
 * RPO (Recovery Point Objective) configures replication for dual-region buckets.
 */
type RPO string

const (
    // RPOUnknown is the zero value (non-dual-region buckets)
    RPOUnknown RPO = ""

    // RPODefault is the default replication
    RPODefault RPO = "DEFAULT"

    // RPOAsyncTurbo enables turbo replication (dual-region only)
    RPOAsyncTurbo RPO = "ASYNC_TURBO"
)

/**
 * CustomPlacementConfig holds custom dual-region configuration.
 */
type CustomPlacementConfig struct {
    // DataLocations is the list of regional locations for data placement
    // Custom dual-regions require exactly 2 regional locations
    DataLocations []string
}

/**
 * Autoclass holds the bucket's autoclass configuration.
 * Enables automatic storage class selection based on access patterns.
 */
type Autoclass struct {
    // Enabled specifies whether autoclass is enabled
    Enabled bool

    // ToggleTime is when autoclass was last toggled (read-only)
    ToggleTime time.Time

    // TerminalStorageClass is the final storage class for unaccessed objects
    // Valid values: NEARLINE, ARCHIVE
    TerminalStorageClass string

    // TerminalStorageClassUpdateTime is when TerminalStorageClass was updated (read-only)
    TerminalStorageClassUpdateTime time.Time
}

/**
 * SoftDeletePolicy defines retention for soft-deleted objects.
 */
type SoftDeletePolicy struct {
    // EffectiveTime is when the policy became effective (read-only)
    EffectiveTime time.Time

    // RetentionDuration is how long soft-deleted objects are retained
    RetentionDuration time.Duration
}

/**
 * HierarchicalNamespace enables folder support in buckets.
 * Can only be set at bucket creation time.
 * Requires UniformBucketLevelAccess to be enabled.
 */
type HierarchicalNamespace struct {
    // Enabled indicates whether hierarchical namespace is enabled
    Enabled bool
}

/**
 * Notification is a Pub/Sub notification configuration.
 */
type Notification struct {
    // ID is the notification identifier (read-only after creation)
    ID string

    // TopicID is the Pub/Sub topic name (not the full path)
    TopicID string

    // TopicProjectID is the project containing the topic
    TopicProjectID string

    // EventTypes are the event types to notify on
    // Values: OBJECT_FINALIZE, OBJECT_METADATA_UPDATE, OBJECT_DELETE, OBJECT_ARCHIVE
    EventTypes []string

    // CustomAttributes are custom attributes included in notifications
    CustomAttributes map[string]string

    // ObjectNamePrefix filters objects by name prefix
    ObjectNamePrefix string

    // PayloadFormat is the format of the notification payload
    // Values: NONE, JSON_API_V1
    PayloadFormat string
}

// Notification event type constants
const (
    ObjectFinalizeEvent       = "OBJECT_FINALIZE"
    ObjectMetadataUpdateEvent = "OBJECT_METADATA_UPDATE"
    ObjectDeleteEvent         = "OBJECT_DELETE"
    ObjectArchiveEvent        = "OBJECT_ARCHIVE"
)

// Notification payload format constants
const (
    NoPayload   = "NONE"
    JSONPayload = "JSON_API_V1"
)