@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/gcs/client.ts

@@ -0,0 +1,195 @@
+/**
+ * GCS (Google Cloud Storage) client implementation.
+ *
+ * Uses the native GCS plugin type from @superblocksteam/types.
+ */
+
+import type { z } from 'zod';
+import type { PartialMessage } from '@bufbuild/protobuf';
+import type { Plugin as GCSPlugin } from '@superblocksteam/types/dist/src/plugins/gcs/v1/plugin_pb';
+import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
+import type { QueryExecutor } from '../registry.js';
+import { RestApiValidationError } from '../../errors.js';
+import { IntegrationError } from '../../runtime/errors.js';
+import type {
+  GCSClient,
+  GCSAction,
+  GCSListObjectsOptions,
+  GCSGetObjectOptions,
+} from './types.js';
+
+/**
+ * Internal implementation of GCSClient.
+ */
+export class GCSClientImpl implements GCSClient, IntegrationClientImpl {
+  readonly config: IntegrationConfig;
+  private readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  get name(): string {
+    return this.config.name;
+  }
+
+  get pluginId(): string {
+    return this.config.pluginId;
+  }
+
+  /**
+   * Builds a GCS plugin request and executes it.
+   */
+  private async execute(
+    action: GCSAction,
+    request: PartialMessage<GCSPlugin>,
+  ): Promise<unknown> {
+    const fullRequest: PartialMessage<GCSPlugin> = {
+      ...request,
+      action,
+    };
+
+    return this.executeQuery(fullRequest as Record<string, unknown>);
+  }
+
+  /**
+   * Validates a result against a Zod schema.
+   */
+  private validate<T>(
+    result: unknown,
+    schema: z.ZodSchema<T>,
+    operation: string,
+  ): T {
+    const parseResult = schema.safeParse(result);
+
+    if (!parseResult.success) {
+      throw new RestApiValidationError(
+        `Result validation failed: ${parseResult.error.message}`,
+        {
+          zodError: parseResult.error,
+          data: result,
+        },
+      );
+    }
+
+    return parseResult.data;
+  }
+
+  /**
+   * Wraps an operation with standard error handling.
+   */
+  private async withErrorHandling<T>(
+    operation: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    try {
+      return await fn();
+    } catch (error) {
+      if (
+        error instanceof RestApiValidationError ||
+        error instanceof IntegrationError
+      ) {
+        throw error;
+      }
+
+      throw new IntegrationError(this.config.name, operation, error);
+    }
+  }
+
+  async listBuckets<T>(schema: z.ZodSchema<T>): Promise<T> {
+    return this.withErrorHandling('listBuckets', async () => {
+      const result = await this.execute('LIST_BUCKETS', {});
+      return this.validate(result, schema, 'listBuckets');
+    });
+  }
+
+  async listObjects<T>(
+    bucket: string,
+    schema: z.ZodSchema<T>,
+    options?: GCSListObjectsOptions,
+  ): Promise<T> {
+    return this.withErrorHandling('listObjects', async () => {
+      const request: PartialMessage<GCSPlugin> = {
+        resource: bucket,
+      };
+
+      if (options?.prefix) {
+        request.prefix = options.prefix;
+      }
+
+      const result = await this.execute('LIST_BUCKET_OBJECTS', request);
+      return this.validate(result, schema, 'listObjects');
+    });
+  }
+
+  async getObject<T>(
+    bucket: string,
+    path: string,
+    schema: z.ZodSchema<T>,
+    options?: GCSGetObjectOptions,
+  ): Promise<T> {
+    return this.withErrorHandling('getObject', async () => {
+      const request: PartialMessage<GCSPlugin> = {
+        resource: bucket,
+        path,
+      };
+
+      if (options?.responseType) {
+        request.responseType = options.responseType;
+      }
+
+      const result = await this.execute('GET_OBJECT', request);
+      return this.validate(result, schema, 'getObject');
+    });
+  }
+
+  async deleteObject(bucket: string, path: string): Promise<void> {
+    return this.withErrorHandling('deleteObject', async () => {
+      await this.execute('DELETE_OBJECT', {
+        resource: bucket,
+        path,
+      });
+    });
+  }
+
+  async uploadObject(
+    bucket: string,
+    path: string,
+    body: string,
+  ): Promise<void> {
+    return this.withErrorHandling('uploadObject', async () => {
+      await this.execute('UPLOAD_OBJECT', {
+        resource: bucket,
+        path,
+        body,
+      });
+    });
+  }
+
+  async uploadMultipleObjects(
+    bucket: string,
+    fileObjects: string,
+  ): Promise<void> {
+    return this.withErrorHandling('uploadMultipleObjects', async () => {
+      await this.execute('UPLOAD_MULTIPLE_OBJECTS', {
+        resource: bucket,
+        fileObjects,
+      });
+    });
+  }
+
+  async generateSignedUrl<T>(
+    bucket: string,
+    path: string,
+    schema: z.ZodSchema<T>,
+  ): Promise<T> {
+    return this.withErrorHandling('generateSignedUrl', async () => {
+      const result = await this.execute('GENERATE_PRESIGNED_URL', {
+        resource: bucket,
+        path,
+      });
+      return this.validate(result, schema, 'generateSignedUrl');
+    });
+  }
+}

package/src/integrations/gcs/index.ts

@@ -0,0 +1,13 @@
+/**
+ * GCS (Google Cloud Storage) integration client.
+ *
+ * @module
+ */
+
+export type {
+  GCSClient,
+  GCSAction,
+  GCSListObjectsOptions,
+  GCSGetObjectOptions,
+} from './types.js';
+export { GCSClientImpl } from './client.js';

package/src/integrations/gcs/types.ts

@@ -0,0 +1,148 @@
+/**
+ * GCS (Google Cloud Storage) client types.
+ */
+
+import type { z } from 'zod';
+import type { BaseIntegrationClient } from '../../types.js';
+
+/**
+ * GCS action types (used internally by the client).
+ */
+export type GCSAction =
+  | 'LIST_OBJECTS'
+  | 'LIST_BUCKET_OBJECTS'
+  | 'GET_OBJECT'
+  | 'DELETE_OBJECT'
+  | 'UPLOAD_OBJECT'
+  | 'LIST_BUCKETS'
+  | 'UPLOAD_MULTIPLE_OBJECTS'
+  | 'GENERATE_PRESIGNED_URL';
+
+/**
+ * Options for listing objects in a bucket.
+ */
+export interface GCSListObjectsOptions {
+  /** Prefix filter for listing */
+  prefix?: string;
+}
+
+/**
+ * Options for getting an object.
+ */
+export interface GCSGetObjectOptions {
+  /** Response type (e.g., 'text', 'binary', 'json') */
+  responseType?: string;
+}
+
+/**
+ * GCS client for storage operations.
+ *
+ * Provides per-operation methods for common GCS tasks with schema validation.
+ *
+ * @example
+ * ```typescript
+ * const gcs = ctx.integrations.storage;
+ *
+ * // List buckets
+ * const buckets = await gcs.listBuckets(z.array(z.object({ name: z.string() })));
+ *
+ * // List objects in a bucket
+ * const files = await gcs.listObjects('my-bucket', z.array(z.object({
+ *   name: z.string(),
+ *   size: z.string(),
+ * })), { prefix: 'uploads/' });
+ *
+ * // Get an object
+ * const content = await gcs.getObject('my-bucket', 'data/file.txt', z.string());
+ *
+ * // Upload an object
+ * await gcs.uploadObject('my-bucket', 'data/file.txt', 'Hello, World!');
+ *
+ * // Delete an object
+ * await gcs.deleteObject('my-bucket', 'data/file.txt');
+ *
+ * // Generate a signed URL
+ * const url = await gcs.generateSignedUrl('my-bucket', 'data/file.txt', z.string());
+ * ```
+ */
+export interface GCSClient extends BaseIntegrationClient {
+  /**
+   * List all GCS buckets.
+   *
+   * @param schema - Zod schema for validating the result
+   * @returns The validated bucket list
+   */
+  listBuckets<T>(schema: z.ZodSchema<T>): Promise<T>;
+
+  /**
+   * List objects in a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param schema - Zod schema for validating the result
+   * @param options - Optional prefix filter
+   * @returns The validated object list
+   */
+  listObjects<T>(
+    bucket: string,
+    schema: z.ZodSchema<T>,
+    options?: GCSListObjectsOptions,
+  ): Promise<T>;
+
+  /**
+   * Get an object from a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param path - Object path
+   * @param schema - Zod schema for validating the result
+   * @param options - Optional response type
+   * @returns The validated object content
+   */
+  getObject<T>(
+    bucket: string,
+    path: string,
+    schema: z.ZodSchema<T>,
+    options?: GCSGetObjectOptions,
+  ): Promise<T>;
+
+  /**
+   * Delete an object from a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param path - Object path
+   */
+  deleteObject(bucket: string, path: string): Promise<void>;
+
+  /**
+   * Upload an object to a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param path - Object path
+   * @param body - File content (base64 or text)
+   */
+  uploadObject(bucket: string, path: string, body: string): Promise<void>;
+
+  /**
+   * Upload multiple objects to a bucket.
+   *
+   * @param bucket - Bucket name
+   * @param fileObjects - Serialized file objects
+   */
+  uploadMultipleObjects(
+    bucket: string,
+    fileObjects: string,
+  ): Promise<void>;
+
+  /**
+   * Generate a signed URL for an object.
+   *
+   * @param bucket - Bucket name
+   * @param path - Object path
+   * @param schema - Zod schema for validating the result
+   * @returns The validated signed URL
+   */
+  generateSignedUrl<T>(
+    bucket: string,
+    path: string,
+    schema: z.ZodSchema<T>,
+  ): Promise<T>;
+}