Package Exports

@sisu-ai/tool-aws-s3
@sisu-ai/tool-aws-s3/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@sisu-ai/tool-aws-s3) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@sisu-ai/tool-aws-s3

AWS S3 tools for Sisu. Read, list, delete, and write objects. Includes metadata helpers.

Exports

s3GetObject({ bucket, key }) → { content: string }
s3ListObjects({ bucket, prefix? }) → string[]
s3ListObjectsDetailed({ bucket, prefix? }) → { key: string; lastModified?: string; size?: number }[]
s3GetObjectMetadata({ bucket, key }) → Record<string, string> (user metadata)
s3PutObject({ bucket, key, content }) → { ok: true } | { ok: false, error: string }
s3DeleteObject({ bucket, key }) → { ok: true } | { ok: false, error: string }

Write operations are guarded. When disabled, write tools return { ok: false, error } (they do not throw).

Configuration

Region: AWS_REGION or AWS_DEFAULT_REGION (defaults to us-east-1)
Credentials (optional): AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY when set; otherwise it relies on the default credential chain
Optional client injection: Provide your own client via ctx.state.s3.client (v3 S3Client or v2‑like shape with getObject, listObjectsV2, putObject, deleteObject, headObject).
Write guard (default: disabled):
- ctx.state.s3.allowWrite = true, or
- AWS_S3_ALLOW_WRITE=1.

Usage

import { Agent } from '@sisu-ai/core';
import { registerTools } from '@sisu-ai/mw-register-tools';
import { s3GetObject, s3ListObjectsDetailed, s3DeleteObject } from '@sisu-ai/tool-aws-s3';

const app = new Agent().use(registerTools([
  s3GetObject, s3ListObjectsDetailed, s3DeleteObject
]));

// Optional: tweak write policy; region/creds read from env
ctx.state.s3 = { allowWrite: false };

Env vars commonly used

AWS_REGION or AWS_DEFAULT_REGION
AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (optional if using instance/profile/role creds)
AWS_S3_ALLOW_WRITE (set to 1/true to enable writes)

Read “latest” example

const items: any[] = await s3ListObjectsDetailed.handler({ bucket: 'my-bucket', prefix: 'folder/' } as any, ctx) as any;
const latest = items
  .filter(i => i.lastModified)
  .sort((a,b) => (a.lastModified! < b.lastModified! ? 1 : -1))[0]?.key;
if (latest) {
  const { content } = await s3GetObject.handler({ bucket: 'my-bucket', key: latest } as any, ctx) as any;
  // optionally delete
  await s3DeleteObject.handler({ bucket: 'my-bucket', key: latest } as any, ctx);
}

Community & Support

Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu. Example projects live under examples/ in the repo.