@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/box/README.md

@@ -0,0 +1,565 @@
+# Box Client
+
+Upload, download, and manage files in Box.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `apiRequest(options, schema)` | Make any Box API request with schema validation |
+
+## Usage
+
+### List Files in a Folder
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_BOX = "a1b2c3d4-5678-90ab-cdef-box000000001";
+
+const ItemSchema = z.object({
+  type: z.enum(["file", "folder", "web_link"]),
+  id: z.string(),
+  name: z.string(),
+  sequence_id: z.string().nullable(),
+  etag: z.string().nullable(),
+});
+
+const FileSchema = ItemSchema.extend({
+  type: z.literal("file"),
+  sha1: z.string().optional(),
+  size: z.number().optional(),
+  created_at: z.string().optional(),
+  modified_at: z.string().optional(),
+  content_created_at: z.string().optional(),
+  content_modified_at: z.string().optional(),
+});
+
+const FolderSchema = ItemSchema.extend({
+  type: z.literal("folder"),
+});
+
+const ListItemsResponseSchema = z.object({
+  entries: z.array(z.union([FileSchema, FolderSchema, ItemSchema])),
+  total_count: z.number(),
+  offset: z.number(),
+  limit: z.number(),
+  order: z.array(z.object({
+    by: z.string(),
+    direction: z.string(),
+  })).optional(),
+});
+
+export default api({
+  name: "BoxExample",
+  input: z.object({
+    folderId: z.string().default("0"), // "0" is root folder
+    limit: z.number().default(100),
+  }),
+  output: z.object({
+    items: z.array(z.object({
+      id: z.string(),
+      name: z.string(),
+      type: z.string(),
+    })),
+    totalCount: z.number(),
+  }),
+  async run(ctx, { folderId, limit }) {
+    const box = ctx.box(PROD_BOX);
+
+    const result = await box.apiRequest(
+      {
+        method: "GET",
+        path: `/2.0/folders/${folderId}/items`,
+        params: {
+          limit: limit,
+          offset: 0,
+          fields: "id,name,type,size,created_at,modified_at",
+        },
+      },
+      { response: ListItemsResponseSchema }
+    );
+
+    return {
+      items: result.entries.map((entry) => ({
+        id: entry.id,
+        name: entry.name,
+        type: entry.type,
+      })),
+      totalCount: result.total_count,
+    };
+  },
+});
+```
+
+### Get File Information
+
+```typescript
+const FileInfoSchema = z.object({
+  type: z.literal("file"),
+  id: z.string(),
+  name: z.string(),
+  size: z.number(),
+  created_at: z.string(),
+  modified_at: z.string(),
+  created_by: z.object({
+    id: z.string(),
+    name: z.string(),
+    login: z.string(),
+  }),
+  modified_by: z.object({
+    id: z.string(),
+    name: z.string(),
+    login: z.string(),
+  }),
+  parent: z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
+  sha1: z.string(),
+  shared_link: z.object({
+    url: z.string(),
+    access: z.string(),
+  }).nullable(),
+});
+
+const file = await box.apiRequest(
+  {
+    method: "GET",
+    path: `/2.0/files/${fileId}`,
+    params: {
+      fields: "id,name,size,created_at,modified_at,created_by,modified_by,parent,sha1,shared_link",
+    },
+  },
+  { response: FileInfoSchema }
+);
+
+console.log(`File: ${file.name} (${file.size} bytes)`);
+```
+
+### Download a File
+
+```typescript
+// Get download URL
+const DownloadUrlResponseSchema = z.string();
+
+const content = await box.apiRequest(
+  {
+    method: "GET",
+    path: `/2.0/files/${fileId}/content`,
+  },
+  { response: DownloadUrlResponseSchema }
+);
+```
+
+### Upload a File
+
+```typescript
+const UploadResponseSchema = z.object({
+  entries: z.array(FileInfoSchema),
+  total_count: z.number(),
+});
+
+// For files < 50MB, use direct upload
+const result = await box.apiRequest(
+  {
+    method: "POST",
+    path: "/2.0/files/content",
+    headers: {
+      "Content-Type": "multipart/form-data",
+    },
+    body: {
+      attributes: JSON.stringify({
+        name: "new-file.txt",
+        parent: { id: folderId },
+      }),
+      file: fileContent,
+    },
+  },
+  { response: UploadResponseSchema }
+);
+
+const uploadedFile = result.entries[0];
+console.log(`Uploaded: ${uploadedFile.name} (${uploadedFile.id})`);
+```
+
+### Create a Folder
+
+```typescript
+const FolderInfoSchema = z.object({
+  type: z.literal("folder"),
+  id: z.string(),
+  name: z.string(),
+  created_at: z.string(),
+  modified_at: z.string(),
+  parent: z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
+});
+
+const folder = await box.apiRequest(
+  {
+    method: "POST",
+    path: "/2.0/folders",
+    body: {
+      name: "New Folder",
+      parent: {
+        id: parentFolderId, // Use "0" for root
+      },
+    },
+  },
+  { response: FolderInfoSchema }
+);
+
+console.log(`Created folder: ${folder.name} (${folder.id})`);
+```
+
+### Copy a File
+
+```typescript
+const copiedFile = await box.apiRequest(
+  {
+    method: "POST",
+    path: `/2.0/files/${fileId}/copy`,
+    body: {
+      parent: {
+        id: destinationFolderId,
+      },
+      name: "Copy of file.txt", // Optional new name
+    },
+  },
+  { response: FileInfoSchema }
+);
+```
+
+### Move a File
+
+```typescript
+const movedFile = await box.apiRequest(
+  {
+    method: "PUT",
+    path: `/2.0/files/${fileId}`,
+    body: {
+      parent: {
+        id: newParentFolderId,
+      },
+    },
+  },
+  { response: FileInfoSchema }
+);
+```
+
+### Update File Information
+
+```typescript
+const updatedFile = await box.apiRequest(
+  {
+    method: "PUT",
+    path: `/2.0/files/${fileId}`,
+    body: {
+      name: "renamed-file.txt",
+      description: "Updated file description",
+      tags: ["important", "quarterly"],
+    },
+  },
+  { response: FileInfoSchema }
+);
+```
+
+### Delete a File
+
+```typescript
+await box.apiRequest(
+  {
+    method: "DELETE",
+    path: `/2.0/files/${fileId}`,
+  },
+  { response: z.void() }
+);
+```
+
+### Create a Shared Link
+
+```typescript
+const SharedLinkSchema = z.object({
+  url: z.string(),
+  download_url: z.string().optional(),
+  access: z.string(),
+  effective_access: z.string(),
+  permissions: z.object({
+    can_download: z.boolean(),
+    can_preview: z.boolean(),
+  }),
+});
+
+const file = await box.apiRequest(
+  {
+    method: "PUT",
+    path: `/2.0/files/${fileId}`,
+    params: {
+      fields: "shared_link",
+    },
+    body: {
+      shared_link: {
+        access: "open", // open, company, collaborators
+        permissions: {
+          can_download: true,
+          can_preview: true,
+        },
+      },
+    },
+  },
+  { response: z.object({ shared_link: SharedLinkSchema }) }
+);
+
+console.log(`Share URL: ${file.shared_link.url}`);
+```
+
+### Search Files
+
+```typescript
+const SearchResponseSchema = z.object({
+  entries: z.array(z.union([FileSchema, FolderSchema])),
+  total_count: z.number(),
+  offset: z.number(),
+  limit: z.number(),
+});
+
+const result = await box.apiRequest(
+  {
+    method: "GET",
+    path: "/2.0/search",
+    params: {
+      query: "quarterly report",
+      type: "file",
+      file_extensions: "pdf,docx",
+      ancestor_folder_ids: folderId,
+      limit: 25,
+      fields: "id,name,type,size,created_at",
+    },
+  },
+  { response: SearchResponseSchema }
+);
+
+result.entries.forEach((entry) => {
+  console.log(`Found: ${entry.name}`);
+});
+```
+
+### Add a Comment
+
+```typescript
+const CommentSchema = z.object({
+  id: z.string(),
+  type: z.literal("comment"),
+  message: z.string(),
+  created_by: z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
+  created_at: z.string(),
+});
+
+const comment = await box.apiRequest(
+  {
+    method: "POST",
+    path: "/2.0/comments",
+    body: {
+      item: {
+        type: "file",
+        id: fileId,
+      },
+      message: "Great work on this document!",
+    },
+  },
+  { response: CommentSchema }
+);
+```
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await box.listFiles({ ... });
+await box.uploadFile({ ... });
+
+// CORRECT - Use apiRequest
+await box.apiRequest(
+  { method: "GET", path: `/2.0/folders/${folderId}/items`, params: { ... } },
+  { response: ListItemsResponseSchema }
+);
+```
+
+### API Version in Path
+
+Box API paths include version:
+
+```typescript
+// CORRECT - Include version
+const path = "/2.0/files/123";
+const path = "/2.0/folders/0/items";
+
+// WRONG - Missing version
+const path = "/files/123";
+```
+
+### Root Folder ID is "0"
+
+The root folder has ID "0", not "root":
+
+```typescript
+// CORRECT - Root folder
+const folderId = "0";
+
+// WRONG - "root" is not valid
+const folderId = "root";
+```
+
+### Fields Parameter
+
+Use `fields` to get specific data:
+
+```typescript
+// Without fields, you get minimal data
+const result = await box.apiRequest(
+  { method: "GET", path: `/2.0/files/${fileId}` },
+  { response: FileSchema }
+);
+
+// With fields, specify what you need
+const result = await box.apiRequest(
+  {
+    method: "GET",
+    path: `/2.0/files/${fileId}`,
+    params: {
+      fields: "id,name,size,created_at,modified_at,parent,shared_link",
+    },
+  },
+  { response: FileInfoSchema }
+);
+```
+
+### Upload Returns Array
+
+File uploads return an array in `entries`:
+
+```typescript
+// Response structure
+const schema = z.object({
+  entries: z.array(FileInfoSchema), // Array even for single file
+  total_count: z.number(),
+});
+
+// Access the uploaded file
+const uploadedFile = result.entries[0];
+```
+
+### If-Match Header for Updates
+
+Use `If-Match` with etag for safe updates:
+
+```typescript
+const result = await box.apiRequest(
+  {
+    method: "PUT",
+    path: `/2.0/files/${fileId}`,
+    headers: {
+      "If-Match": file.etag, // Prevents overwriting concurrent changes
+    },
+    body: {
+      name: "new-name.txt",
+    },
+  },
+  { response: FileInfoSchema }
+);
+```
+
+### Pagination
+
+Box uses offset-based pagination:
+
+```typescript
+async function getAllItems(box: BoxClient, folderId: string) {
+  const allItems: Item[] = [];
+  const limit = 100;
+  let offset = 0;
+
+  while (true) {
+    const result = await box.apiRequest(
+      {
+        method: "GET",
+        path: `/2.0/folders/${folderId}/items`,
+        params: { limit, offset, fields: "id,name,type" },
+      },
+      { response: ListItemsResponseSchema }
+    );
+
+    allItems.push(...result.entries);
+    if (offset + result.entries.length >= result.total_count) break;
+    offset += limit;
+  }
+
+  return allItems;
+}
+```
+
+### File Size Limits
+
+Different upload methods for different file sizes:
+
+```typescript
+// < 50MB - Use /files/content (simple upload)
+// > 50MB - Use chunked upload session
+
+// Chunked upload for large files:
+// 1. POST /files/upload_sessions - Create session
+// 2. PUT /files/upload_sessions/:id - Upload parts
+// 3. POST /files/upload_sessions/:id/commit - Finalize
+```
+
+### Shared Link Access Levels
+
+```typescript
+const accessLevels = {
+  open: "Anyone with the link",
+  company: "Anyone in the enterprise",
+  collaborators: "Only collaborators",
+};
+
+const body = {
+  shared_link: {
+    access: "company",
+    password: "optional-password", // Optional
+    unshared_at: "2024-12-31T23:59:59Z", // Optional expiration
+  },
+};
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await box.apiRequest(
+    { method: "GET", path: `/2.0/folders/${folderId}/items`, params: { ... } },
+    { response: ListItemsResponseSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Box API Documentation](https://developer.box.com/reference/)
+- [Files](https://developer.box.com/reference/resources/file/)
+- [Folders](https://developer.box.com/reference/resources/folder/)
+- [Shared Links](https://developer.box.com/guides/shared-links/)
+- [Search](https://developer.box.com/reference/get-search/)

package/src/integrations/box/client.ts

@@ -0,0 +1,21 @@
+/**
+ * Box client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Box integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from '../base/index.js';
+import type { BoxClient } from './types.js';
+
+/**
+ * Internal implementation of BoxClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Box API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class BoxClientImpl extends RestApiIntegrationClient implements BoxClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/box/index.ts

@@ -0,0 +1,2 @@
+export { BoxClientImpl } from './client.js';
+export type { BoxClient } from './types.js';

package/src/integrations/box/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Box client types.
+ */
+
+import type { BaseIntegrationClient } from '../../types.js';
+import type { SupportsApiRequest } from '../base/index.js';
+
+/**
+ * Box client for API interactions.
+ *
+ * Provides generic API request method for interacting with Box's API.
+ * Use apiRequest() to make calls to any Box API endpoint.
+ *
+ * @example
+ * ```typescript
+ * const box = ctx.box('My Box');
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await box.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/2.0/folders/0',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface BoxClient extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}