@mastra/s3 0.0.0

package/LICENSE.md

@@ -0,0 +1,15 @@
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,72 @@
+# @mastra/s3
+
+S3-compatible filesystem provider for Mastra workspaces. Works with AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, and other S3-compatible storage services.
+
+## Installation
+
+```bash
+npm install @mastra/s3
+```
+
+## Usage
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { Workspace } from '@mastra/core/workspace';
+import { S3Filesystem } from '@mastra/s3';
+
+const workspace = new Workspace({
+  filesystem: new S3Filesystem({
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  }),
+});
+
+const agent = new Agent({
+  name: 'my-agent',
+  model: 'anthropic/claude-opus-4-5',
+  workspace,
+});
+```
+
+### Cloudflare R2
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new S3Filesystem({
+    bucket: 'my-r2-bucket',
+    region: 'auto',
+    endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+    accessKeyId: process.env.R2_ACCESS_KEY_ID,
+    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
+  }),
+});
+```
+
+### With E2B Sandbox
+
+When used with `@mastra/e2b`, S3 filesystems can be mounted into E2B sandboxes via s3fs-fuse:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace';
+import { S3Filesystem } from '@mastra/s3';
+import { E2BSandbox } from '@mastra/e2b';
+
+const workspace = new Workspace({
+  mounts: {
+    '/my-bucket': new S3Filesystem({
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+  },
+  sandbox: new E2BSandbox(),
+});
+```
+
+## Documentation
+
+For more information, see the [Mastra Workspaces documentation](https://mastra.ai/docs/workspace/overview).

package/dist/filesystem/index.d.ts

@@ -0,0 +1,141 @@
+import type { FileContent, FileStat, FileEntry, ReadOptions, WriteOptions, ListOptions, RemoveOptions, CopyOptions, FilesystemMountConfig, FilesystemIcon, FilesystemInfo, ProviderStatus } from '@mastra/core/workspace';
+import { MastraFilesystem } from '@mastra/core/workspace';
+/**
+ * S3 mount configuration.
+ * Returned by S3Filesystem.getMountConfig() for FUSE mounting in sandboxes.
+ */
+export interface S3MountConfig extends FilesystemMountConfig {
+    type: 's3';
+    /** S3 bucket name */
+    bucket: string;
+    /** AWS region (use 'auto' for R2) */
+    region?: string;
+    /** Optional endpoint for S3-compatible storage (MinIO, R2, etc.) */
+    endpoint?: string;
+    /** AWS access key ID */
+    accessKeyId?: string;
+    /** AWS secret access key */
+    secretAccessKey?: string;
+    /** Mount as read-only */
+    readOnly?: boolean;
+}
+/**
+ * S3 filesystem provider configuration.
+ */
+export interface S3FilesystemOptions {
+    /** Unique identifier for this filesystem instance */
+    id?: string;
+    /** S3 bucket name */
+    bucket: string;
+    /** Human-friendly display name for the UI */
+    displayName?: string;
+    /** Icon identifier for the UI (defaults to 's3') */
+    icon?: FilesystemIcon;
+    /** Description shown in tooltips */
+    description?: string;
+    /** AWS region (use 'auto' for R2) */
+    region: string;
+    /**
+     * AWS access key ID.
+     * Optional - omit for public buckets (read-only access).
+     */
+    accessKeyId?: string;
+    /**
+     * AWS secret access key.
+     * Optional - omit for public buckets (read-only access).
+     */
+    secretAccessKey?: string;
+    /**
+     * Custom endpoint URL for S3-compatible storage.
+     * Examples:
+     * - Cloudflare R2: 'https://{accountId}.r2.cloudflarestorage.com'
+     * - MinIO: 'http://localhost:9000'
+     * - DigitalOcean Spaces: 'https://{region}.digitaloceanspaces.com'
+     */
+    endpoint?: string;
+    /** Force path-style URLs (required for some S3-compatible services) */
+    forcePathStyle?: boolean;
+    /** Optional prefix for all keys (acts like a subdirectory) */
+    prefix?: string;
+    /** Mount as read-only (blocks write operations, mounts read-only in sandboxes) */
+    readOnly?: boolean;
+}
+export declare class S3Filesystem extends MastraFilesystem {
+    readonly id: string;
+    readonly name = "S3Filesystem";
+    readonly provider = "s3";
+    readonly readOnly?: boolean;
+    status: ProviderStatus;
+    readonly displayName?: string;
+    readonly icon: FilesystemIcon;
+    readonly description?: string;
+    private readonly bucket;
+    private readonly region;
+    private readonly accessKeyId?;
+    private readonly secretAccessKey?;
+    private readonly endpoint?;
+    private readonly forcePathStyle;
+    private readonly prefix;
+    private _client;
+    constructor(options: S3FilesystemOptions);
+    /**
+     * Get mount configuration for E2B sandbox.
+     * Returns S3-compatible config that works with s3fs-fuse.
+     */
+    getMountConfig(): S3MountConfig;
+    /**
+     * Get filesystem info for status reporting.
+     */
+    getInfo(): FilesystemInfo;
+    /**
+     * Handle an error, checking for access denied and updating status accordingly.
+     * Returns the error for re-throwing.
+     */
+    private handleError;
+    /**
+     * Get instructions describing this S3 filesystem.
+     * Used by agents to understand storage semantics.
+     */
+    getInstructions(): string;
+    /**
+     * Detect the appropriate icon based on the S3 endpoint.
+     */
+    private detectIconFromEndpoint;
+    /**
+     * Get a user-friendly display name based on the icon/provider.
+     */
+    private getDefaultDisplayName;
+    private getClient;
+    /**
+     * Ensure the filesystem is initialized and return the S3 client.
+     * Uses base class ensureReady() for status management, then returns client.
+     */
+    private getReadyClient;
+    private toKey;
+    readFile(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    writeFile(path: string, content: FileContent, _options?: WriteOptions): Promise<void>;
+    appendFile(path: string, content: FileContent): Promise<void>;
+    deleteFile(path: string, options?: RemoveOptions): Promise<void>;
+    copyFile(src: string, dest: string, _options?: CopyOptions): Promise<void>;
+    moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    mkdir(_path: string, _options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: RemoveOptions): Promise<void>;
+    readdir(path: string, options?: ListOptions): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    isFile(path: string): Promise<boolean>;
+    isDirectory(path: string): Promise<boolean>;
+    /**
+     * Initialize the S3 client.
+     * Status management is handled by the base class.
+     */
+    init(): Promise<void>;
+    /**
+     * Clean up the S3 client.
+     * Status management is handled by the base class.
+     */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/filesystem/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/filesystem/index.ts"],"names":[],"mappings":"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"}