Storage Client

class Storage {
  constructor(options?: StorageOptions);
  
  // Static references to other classes
  static Bucket: typeof Bucket;
  static Channel: typeof Channel;
  static File: typeof File;
  static HmacKey: typeof HmacKey;
  
  // ACL constants
  static acl: {
    OWNER_ROLE: 'OWNER';
    READER_ROLE: 'READER';
    WRITER_ROLE: 'WRITER';
  };
}

interface StorageOptions {
  projectId?: string;
  keyFilename?: string;
  credentials?: object;
  apiEndpoint?: string;
  crc32cGenerator?: CRC32CValidatorGenerator;
  retryOptions?: RetryOptions;
  userAgent?: string;
  authClient?: AuthClient;
}

// Default configuration (uses Application Default Credentials)
const storage = new Storage();

// With explicit project ID
const storage = new Storage({
  projectId: 'my-project-id'
});

// With service account key file
const storage = new Storage({
  projectId: 'my-project-id',
  keyFilename: '/path/to/service-account-key.json'
});

// With explicit credentials object
const storage = new Storage({
  projectId: 'my-project-id',
  credentials: {
    client_email: 'service-account@project.iam.gserviceaccount.com',
    private_key: '-----BEGIN PRIVATE KEY-----\n...'
  }
});

// With custom endpoint (for testing/emulator)
const storage = new Storage({
  apiEndpoint: 'http://localhost:8080',
  projectId: 'test-project'
});

// With retry configuration
const storage = new Storage({
  retryOptions: {
    autoRetry: true,
    maxRetries: 3,
    retryDelayMultiplier: 2,
    totalTimeout: 600000,
    idempotencyStrategy: IdempotencyStrategy.RetryConditional
  }
});

bucket(name: string, options?: BucketOptions): Bucket

// Get bucket reference
const bucket = storage.bucket('my-bucket');

// With options
const bucket = storage.bucket('my-bucket', {
  userProject: 'billing-project-id',
  generation: 123456789
});

createBucket(name: string, metadata?: CreateBucketRequest): Promise<CreateBucketResponse>

interface CreateBucketRequest {
  cors?: Cors[];
  defaultEventBasedHold?: boolean;
  defaultObjectAcl?: AclMetadata[];
  encryption?: {
    defaultKmsKeyName?: string;
  };
  iamConfiguration?: {
    bucketPolicyOnly?: {
      enabled?: boolean;
    };
    publicAccessPrevention?: 'inherited' | 'enforced';
  };
  labels?: { [key: string]: string };
  lifecycle?: {
    rule?: LifecycleRule[];
  };
  location?: string;
  logging?: {
    logBucket?: string;
    logObjectPrefix?: string;
  };
  retentionPolicy?: {
    retentionPeriod?: number;
  };
  storageClass?: string;
  versioning?: {
    enabled?: boolean;
  };
  website?: {
    mainPageSuffix?: string;
    notFoundPage?: string;
  };
  requesterPays?: boolean;
  uniformBucketLevelAccess?: {
    enabled?: boolean;
  };
}

type CreateBucketResponse = [Bucket, unknown]; // [bucket, apiResponse]

// Create basic bucket
const [bucket] = await storage.createBucket('new-bucket');

// Create with location and storage class
const [bucket] = await storage.createBucket('new-bucket', {
  location: 'us-central1',
  storageClass: 'STANDARD'
});

// Create with lifecycle rules
const [bucket] = await storage.createBucket('new-bucket', {
  lifecycle: {
    rule: [
      {
        action: { type: 'Delete' },
        condition: { age: 365 }
      },
      {
        action: { 
          type: 'SetStorageClass',
          storageClass: 'COLDLINE'
        },
        condition: { age: 30 }
      }
    ]
  }
});

// Create with encryption
const [bucket] = await storage.createBucket('encrypted-bucket', {
  encryption: {
    defaultKmsKeyName: 'projects/PROJECT_ID/locations/LOCATION/keyRings/RING_ID/cryptoKeys/KEY_ID'
  }
});

getBuckets(options?: GetBucketsRequest): Promise<GetBucketsResponse>
getBucketsStream(): Readable

interface GetBucketsRequest {
  maxResults?: number;
  pageToken?: string;
  prefix?: string;
  project?: string;
  userProject?: string;
}

type GetBucketsResponse = [Bucket[], {}, unknown]; // [buckets, nextQuery, apiResponse]

// List all buckets
const [buckets] = await storage.getBuckets();
buckets.forEach(bucket => {
  console.log(`Bucket: ${bucket.name}`);
});

// List with prefix filter
const [buckets] = await storage.getBuckets({
  prefix: 'prod-'
});

// List with pagination
const [buckets, nextQuery] = await storage.getBuckets({
  maxResults: 10
});

if (nextQuery) {
  const [moreBuckets] = await storage.getBuckets(nextQuery);
}

// Stream buckets for large lists
storage.getBucketsStream()
  .on('data', bucket => {
    console.log(`Bucket: ${bucket.name}`);
  })
  .on('end', () => {
    console.log('Finished listing buckets');
  });

getServiceAccount(options?: GetServiceAccountOptions): Promise<GetServiceAccountResponse>

interface GetServiceAccountOptions {
  userProject?: string;
}

interface ServiceAccount {
  emailAddress?: string;
}

type GetServiceAccountResponse = [ServiceAccount, unknown]; // [serviceAccount, apiResponse]

// Get service account information
const [serviceAccount] = await storage.getServiceAccount();
console.log('Service Account Email:', serviceAccount.emailAddress);

// With user project for billing
const [serviceAccount] = await storage.getServiceAccount({
  userProject: 'billing-project-id'
});

createHmacKey(serviceAccountEmail: string, options?: CreateHmacKeyOptions): Promise<CreateHmacKeyResponse>

interface CreateHmacKeyOptions {
  projectId?: string;
  userProject?: string;
}

interface HmacKeyResourceResponse {
  metadata?: HmacKeyMetadata;
  secret?: string;
}

type CreateHmacKeyResponse = [HmacKey, string, unknown]; // [hmacKey, secret, apiResponse]

// Create HMAC key for service account
const serviceAccountEmail = 'service-account@project.iam.gserviceaccount.com';
const [hmacKey, secret] = await storage.createHmacKey(serviceAccountEmail);

console.log('Access ID:', hmacKey.accessId);
console.log('Secret (store securely):', secret);

// With explicit project
const [hmacKey, secret] = await storage.createHmacKey(serviceAccountEmail, {
  projectId: 'my-project-id'
});

getHmacKeys(options?: GetHmacKeysOptions): Promise<GetHmacKeysResponse>
getHmacKeysStream(): Readable

interface GetHmacKeysOptions {
  serviceAccountEmail?: string;
  showDeletedKeys?: boolean;
  maxResults?: number;
  pageToken?: string;
  projectId?: string;
  userProject?: string;
}

type GetHmacKeysResponse = [HmacKey[], {}, unknown]; // [hmacKeys, nextQuery, apiResponse]

// List all HMAC keys
const [hmacKeys] = await storage.getHmacKeys();
hmacKeys.forEach(key => {
  console.log(`HMAC Key: ${key.accessId}`);
});

// List keys for specific service account
const [hmacKeys] = await storage.getHmacKeys({
  serviceAccountEmail: 'service-account@project.iam.gserviceaccount.com'
});

// Include deleted keys
const [hmacKeys] = await storage.getHmacKeys({
  showDeletedKeys: true
});

// Stream HMAC keys
storage.getHmacKeysStream()
  .on('data', hmacKey => {
    console.log(`HMAC Key: ${hmacKey.accessId}`);
  })
  .on('end', () => {
    console.log('Finished listing HMAC keys');
  });

hmacKey(accessId: string, options?: HmacKeyOptions): HmacKey

interface HmacKeyOptions {
  projectId?: string;
  userProject?: string;
}

// Get HMAC key reference
const hmacKey = storage.hmacKey('GOOG1EXAMPLE');

// With project specification
const hmacKey = storage.hmacKey('GOOG1EXAMPLE', {
  projectId: 'my-project-id'
});

channel(id: string, resourceId: string): Channel

// Create channel reference for notifications
const channel = storage.channel('channel-id', 'resource-id');

// Use with bucket watch operations
const bucket = storage.bucket('my-bucket');
const [channel] = await bucket.createChannel('my-channel', {
  address: 'https://example.com/webhook'
});

// Promise pattern (recommended)
const [buckets] = await storage.getBuckets();

// Callback pattern
storage.getBuckets((err, buckets, nextQuery, apiResponse) => {
  if (err) {
    console.error('Error:', err);
    return;
  }
  console.log('Buckets:', buckets);
});

// Callback types
interface BucketCallback {
  (err: Error | null, bucket?: Bucket, apiResponse?: unknown): void;
}

interface GetBucketsCallback {
  (err: Error | null, buckets?: Bucket[], nextQuery?: {}, apiResponse?: unknown): void;
}

interface CreateHmacKeyCallback {
  (err: Error | null, hmacKey?: HmacKey, secret?: string, apiResponse?: unknown): void;
}

interface GetServiceAccountCallback {
  (err: Error | null, serviceAccount?: ServiceAccount, apiResponse?: unknown): void;
}

import { ApiError } from '@google-cloud/storage';

try {
  const [bucket] = await storage.createBucket('existing-bucket');
} catch (error) {
  if (error instanceof ApiError) {
    if (error.code === 409) {
      console.log('Bucket already exists');
    } else {
      console.error(`API Error ${error.code}: ${error.message}`);
    }
  }
}

// Configure custom retry function
const storage = new Storage({
  retryOptions: {
    retryableErrorFn: (err) => {
      return err.code >= 500 || err.code === 429;
    }
  }
});

// Custom CRC32C generator
import { CRC32C } from '@google-cloud/storage';

const storage = new Storage({
  crc32cGenerator: () => new CRC32C()
});

// Custom user agent
const storage = new Storage({
  userAgent: 'my-app/1.0.0'
});

// Using with custom auth client
import { GoogleAuth } from 'google-auth-library';

const auth = new GoogleAuth({
  scopes: ['https://www.googleapis.com/auth/cloud-platform']
});

const storage = new Storage({
  authClient: await auth.getClient()
});