# GCS (Google Cloud Storage) Client

Interact with Google Cloud Storage buckets with full type safety and runtime validation.

## Methods

| Method                                                  | Description              |
| ------------------------------------------------------- | ------------------------ |
| `listBuckets(schema, metadata?)`                        | List all buckets         |
| `listObjects(bucket, schema, options?, metadata?)`      | List objects in a bucket |
| `getObject(bucket, path, schema, options?, metadata?)`  | Get an object            |
| `deleteObject(bucket, path, metadata?)`                 | Delete an object         |
| `uploadObject(bucket, path, body, metadata?)`           | Upload a single object   |
| `uploadMultipleObjects(bucket, fileObjects, metadata?)` | Upload multiple objects  |
| `generateSignedUrl(bucket, path, schema, metadata?)`    | Generate a signed URL    |

## Usage

### List Objects in a Bucket

```typescript
import { api, z, gcs } from "@superblocksteam/sdk-api";

// Integration ID from the integrations panel
const PROD_GCS = "a1b2c3d4-5678-90ab-cdef-gcs0000001";

export default api({
  integrations: {
    storage: gcs(PROD_GCS),
  },
  input: z.object({
    bucket: z.string(),
    prefix: z.string().optional(),
  }),
  output: z.object({
    files: z.array(
      z.object({
        name: z.string(),
        size: z.string(),
      }),
    ),
  }),
  async run(ctx, { bucket, prefix }) {
    const files = await ctx.integrations.storage.listObjects(
      bucket,
      z.array(z.object({ name: z.string(), size: z.string() })),
      prefix ? { prefix } : undefined,
    );

    return { files };
  },
});
```

### Get Object Content

```typescript
// For text files
const content = await ctx.integrations.storage.getObject(
  "my-bucket",
  "data/file.txt",
  z.string(),
);

// For JSON files
const data = await ctx.integrations.storage.getObject(
  "my-bucket",
  "data/config.json",
  z.object({ name: z.string(), value: z.number() }),
);
```

### Upload Object

```typescript
await ctx.integrations.storage.uploadObject(
  "my-bucket",
  "uploads/file.txt",
  "File content here",
);
```

### Delete Object

```typescript
await ctx.integrations.storage.deleteObject("my-bucket", "uploads/file.txt");
```

### List Buckets

```typescript
const buckets = await ctx.integrations.storage.listBuckets(
  z.array(z.object({ name: z.string(), timeCreated: z.string() })),
);
```

### Generate Signed URL

```typescript
const url = await ctx.integrations.storage.generateSignedUrl(
  "my-bucket",
  "private/document.pdf",
  z.string(),
);
```

## Trace Metadata

All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.

## Common Pitfalls

### Size is Returned as String

GCS returns file sizes as strings:

```typescript
const schema = z.object({
  name: z.string(),
  size: z.string().transform((val) => parseInt(val, 10)),
});
```

## Error Handling

```typescript
import {
  RestApiValidationError,
  IntegrationError,
} from "@superblocksteam/sdk-api";

try {
  const content = await ctx.integrations.storage.getObject(
    "my-bucket",
    "file.txt",
    z.string(),
  );
} catch (error) {
  if (error instanceof RestApiValidationError) {
    console.error("Validation failed:", error.details.zodError);
  } else if (error instanceof IntegrationError) {
    console.error("GCS error:", error.message);
  }
}
```

## API Reference

- [Cloud Storage Documentation](https://cloud.google.com/storage/docs)