@ayepi/aws 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @ayepi/aws
+
+AWS backends for ayepi: an SQS-backed [`@ayepi/work`](https://www.npmjs.com/package/@ayepi/work)
+`Queue` (with transparent S3 offload of large payloads) and an S3-backed
+[`@ayepi/files`](https://www.npmjs.com/package/@ayepi/files) `FileStore` + `Presigner`, all
+wrapped in [`@ayepi/core`](https://www.npmjs.com/package/@ayepi/core) `retry` so SQS/S3
+throttling is absorbed under load. The AWS SDK v3 clients are **optional peer dependencies**
+you install and own — the package talks to them via `client.send(command)`.
+
+```sh
+pnpm add @ayepi/aws @aws-sdk/client-s3 @aws-sdk/client-sqs @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
+```
+
+```ts
+import { S3Client } from '@aws-sdk/client-s3'
+import { SQSClient } from '@aws-sdk/client-sqs'
+import { createWork } from '@ayepi/work'
+import { s3Files } from '@ayepi/aws/s3'
+import { sqsQueue } from '@ayepi/aws/sqs'
+
+const s3 = new S3Client({ region: 'us-east-1' })
+const sqs = new SQSClient({ region: 'us-east-1' })
+
+const files = s3Files({ client: s3, bucket: 'my-bucket' })
+const queue = sqsQueue({
+  client: sqs,
+  queueUrl: process.env.SQS_URL!,
+  waitTimeSeconds: 10,
+  largePayload: { store: files }, // bodies near SQS's 256 KB cap go to S3
+})
+
+const w = createWork({ queue, pubsub, store, work: [/* ... */] as const })
+```
+
+## How it works
+
+- **S3 store.** `s3Files` implements the `@ayepi/files` `FileStore` (and `Presigner`):
+  streaming `put` (multipart via `@aws-sdk/lib-storage`), `get`/`head`/`delete`,
+  prefix-paginated `list`, and native presigned download/upload URLs — no server route needed.
+- **SQS queue.** `sqsQueue` maps SQS's native visibility-timeout model onto the `@ayepi/work`
+  `Queue`: `push` is `SendMessage`, `pop` is `ReceiveMessage` (a lease), `heartbeat` is
+  `ChangeMessageVisibility`, `ack` is `DeleteMessage`, `fail` returns the message early.
+  Dead-lettering is the queue's own SQS redrive policy.
+- **Large payloads.** SQS caps a message at 256 KB. With `largePayload`, a body over the
+  threshold (default ~240 KB) is written to a `FileStore` and the message carries a small
+  pointer; `pop` inlines it back and `ack` deletes the S3 object.
+- **Throttle resilience.** Every `client.send(...)` is wrapped in `@ayepi/core` `retry`, so a
+  throttled (rate-limited) reply is retried; on exhaustion the error is reported to `onError`
+  and rethrown.
+- **You own the SDK clients.** The clients are optional peer deps — you construct and configure
+  them (region, credentials, endpoint) and manage their lifecycle.
+
+## Options
+
+```ts
+// S3 file store
+s3Files({
+  client: s3,              // a configured @aws-sdk/client-s3 S3Client
+  bucket: 'my-bucket',
+  prefix: 'docs/',         // key namespace prepended to every key (default '')
+  retry: { attempts: 8 },  // core retry policy (default absorbs throttling)
+  onError: (err) => log(err),
+})
+
+// SQS work queue
+sqsQueue({
+  client: sqs,             // a configured @aws-sdk/client-sqs SQSClient
+  queueUrl: process.env.SQS_URL!,
+  waitTimeSeconds: 10,     // long-poll seconds for pop (0–20, default 0)
+  largePayload: {          // optional S3 offload of oversized bodies
+    store: files,          // any @ayepi/files FileStore
+    threshold: 240 * 1024, // offload bodies larger than this (default ~240 KB)
+    prefix: 'sqs-payloads/', // key prefix for offloaded bodies (default)
+  },
+  retry: { attempts: 8 },
+  onError: (err) => log(err),
+})
+```
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-aws.md`](./ayepi-aws.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/aws) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/index.cjs

@@ -0,0 +1,32 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _ayepi_core = require("@ayepi/core");
+//#region src/index.ts
+/**
+* # @ayepi/aws
+*
+* AWS backends for ayepi:
+* - **`@ayepi/aws/s3`** — an {@link FileStore} over S3 (stream get/put, prefix list,
+*   presigned URLs).
+* - **`@ayepi/aws/sqs`** — an `@ayepi/work` `Queue` over SQS, with large payloads
+*   transparently offloaded to S3 (SQS caps a message at 256 KB).
+*
+* Both wrap every AWS call in core {@link retry} (configurable) because SQS/S3 throttle
+* under load, and expose an `onError` hook fired when a call finally gives up. The AWS SDK
+* v3 clients are **optional peer dependencies** — install the ones you use.
+*
+* @module
+*/
+/** Build a retry-wrapping runner that reports a final failure through `onError`. */
+function makeRun(opts) {
+	const report = (err) => {
+		try {
+			opts.onError?.(err);
+		} catch {}
+	};
+	return (fn) => (0, _ayepi_core.retry)(fn, {
+		...opts.retry,
+		onError: (err) => report(err)
+	});
+}
+//#endregion
+exports.makeRun = makeRun;

package/dist/index.d.cts

@@ -0,0 +1,23 @@
+import { RetryOptions } from "@ayepi/core";
+
+//#region src/index.d.ts
+
+/**
+ * The minimal AWS SDK v3 client surface used internally — `send(command)`. The real
+ * `S3Client` / `SQSClient` satisfy it; a test can pass `{ send: vi.fn() }`. (Presigning and
+ * multipart upload need the *concrete* `S3Client`, so `@ayepi/aws/s3` takes that directly.)
+ */
+interface AwsClient {
+  send(command: unknown): Promise<unknown>;
+}
+/** Resilience options shared by the S3 store and the SQS queue. */
+interface ResilientOptions {
+  /** Retry policy for each AWS call (core `retry` — `attempts`/`base`/`factor`/`max`/`jitter`/…). Defaults absorb throttling. */
+  readonly retry?: Omit<RetryOptions, 'errorResult'>;
+  /** Notified when a call fails after exhausting retries (the error then propagates). Off by default; must not throw. */
+  readonly onError?: (err: unknown) => void;
+}
+/** Build a retry-wrapping runner that reports a final failure through `onError`. */
+declare function makeRun(opts: ResilientOptions): <T>(fn: () => Promise<T>) => Promise<T>;
+//#endregion
+export { AwsClient, ResilientOptions, makeRun };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { RetryOptions } from "@ayepi/core";
+
+//#region src/index.d.ts
+
+/**
+ * The minimal AWS SDK v3 client surface used internally — `send(command)`. The real
+ * `S3Client` / `SQSClient` satisfy it; a test can pass `{ send: vi.fn() }`. (Presigning and
+ * multipart upload need the *concrete* `S3Client`, so `@ayepi/aws/s3` takes that directly.)
+ */
+interface AwsClient {
+  send(command: unknown): Promise<unknown>;
+}
+/** Resilience options shared by the S3 store and the SQS queue. */
+interface ResilientOptions {
+  /** Retry policy for each AWS call (core `retry` — `attempts`/`base`/`factor`/`max`/`jitter`/…). Defaults absorb throttling. */
+  readonly retry?: Omit<RetryOptions, 'errorResult'>;
+  /** Notified when a call fails after exhausting retries (the error then propagates). Off by default; must not throw. */
+  readonly onError?: (err: unknown) => void;
+}
+/** Build a retry-wrapping runner that reports a final failure through `onError`. */
+declare function makeRun(opts: ResilientOptions): <T>(fn: () => Promise<T>) => Promise<T>;
+//#endregion
+export { AwsClient, ResilientOptions, makeRun };

package/dist/index.js

@@ -0,0 +1,31 @@
+import { retry } from "@ayepi/core";
+//#region src/index.ts
+/**
+* # @ayepi/aws
+*
+* AWS backends for ayepi:
+* - **`@ayepi/aws/s3`** — an {@link FileStore} over S3 (stream get/put, prefix list,
+*   presigned URLs).
+* - **`@ayepi/aws/sqs`** — an `@ayepi/work` `Queue` over SQS, with large payloads
+*   transparently offloaded to S3 (SQS caps a message at 256 KB).
+*
+* Both wrap every AWS call in core {@link retry} (configurable) because SQS/S3 throttle
+* under load, and expose an `onError` hook fired when a call finally gives up. The AWS SDK
+* v3 clients are **optional peer dependencies** — install the ones you use.
+*
+* @module
+*/
+/** Build a retry-wrapping runner that reports a final failure through `onError`. */
+function makeRun(opts) {
+	const report = (err) => {
+		try {
+			opts.onError?.(err);
+		} catch {}
+	};
+	return (fn) => retry(fn, {
+		...opts.retry,
+		onError: (err) => report(err)
+	});
+}
+//#endregion
+export { makeRun };

package/dist/s3.cjs

@@ -0,0 +1,138 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_index = require("./index.cjs");
+let node_stream = require("node:stream");
+let _aws_sdk_client_s3 = require("@aws-sdk/client-s3");
+let _aws_sdk_s3_request_presigner = require("@aws-sdk/s3-request-presigner");
+let _aws_sdk_lib_storage = require("@aws-sdk/lib-storage");
+let _ayepi_files = require("@ayepi/files");
+//#region src/s3.ts
+/**
+* # @ayepi/aws/s3 — an S3-backed {@link FileStore}
+*
+* Stream objects to/from S3 under a key, list by prefix, and mint presigned upload/download
+* URLs (native to S3 — no server route needed). Every call is wrapped in core {@link retry}
+* so a throttled reply is absorbed.
+*
+* ```ts
+* import { S3Client } from '@aws-sdk/client-s3';
+* import { s3Files } from '@ayepi/aws/s3';
+* const files = s3Files({ client: new S3Client({ region: 'us-east-1' }), bucket: 'my-bucket' });
+* await files.put('reports/2026.csv', readableStream, { contentType: 'text/csv' });
+* const url = await files.presignDownload('reports/2026.csv', { expiresIn: 300 });
+* ```
+*
+* Note: an S3 `FileObject`'s body is read **once** — call one of `stream()`/`bytes()`/`text()`.
+*
+* @module
+*/
+/** Default presigned-URL lifetime (seconds). */
+const DEFAULT_EXPIRES_IN = 900;
+/** S3 surfaces a missing key differently per op (`NoSuchKey` on GET, `NotFound` on HEAD). */
+function isNotFound(err) {
+	const name = err?.name;
+	const status = err?.$metadata?.httpStatusCode;
+	return name === "NoSuchKey" || name === "NotFound" || status === 404;
+}
+/**
+* Create an S3-backed {@link FileStore} (and {@link Presigner}). Pass a configured `S3Client`
+* and a bucket; `prefix` namespaces all keys.
+*/
+function s3Files(opts) {
+	const { client, bucket } = opts;
+	const ns = opts.prefix ?? "";
+	const run = require_index.makeRun(opts);
+	const k = (key) => ns + key;
+	/* v8 ignore start -- SDK glue: exercised only against real S3 (integration test) */
+	const sdkUpload = (key, body, contentType, metadata) => new _aws_sdk_lib_storage.Upload({
+		client,
+		params: {
+			Bucket: bucket,
+			Key: k(key),
+			Body: node_stream.Readable.fromWeb((0, _ayepi_files.toStream)(body)),
+			ContentType: contentType,
+			Metadata: metadata
+		}
+	}).done().then(() => void 0);
+	const sdkPresign = (kind, key, expiresIn, contentType) => (0, _aws_sdk_s3_request_presigner.getSignedUrl)(client, kind === "get" ? new _aws_sdk_client_s3.GetObjectCommand({
+		Bucket: bucket,
+		Key: k(key)
+	}) : new _aws_sdk_client_s3.PutObjectCommand({
+		Bucket: bucket,
+		Key: k(key),
+		ContentType: contentType
+	}), { expiresIn });
+	/* v8 ignore stop */
+	const upload = opts.upload ?? sdkUpload;
+	const presign = opts.presign ?? sdkPresign;
+	const infoFrom = (key, size, contentType, etag, modified, metadata) => ({
+		key,
+		size: size ?? 0,
+		contentType,
+		etag,
+		modifiedAt: modified ? modified.getTime() : 0,
+		metadata
+	});
+	const headRaw = async (key) => {
+		try {
+			const out = await client.send(new _aws_sdk_client_s3.HeadObjectCommand({
+				Bucket: bucket,
+				Key: k(key)
+			}));
+			return infoFrom(key, out.ContentLength, out.ContentType, out.ETag, out.LastModified, out.Metadata);
+		} catch (err) {
+			if (isNotFound(err)) return;
+			throw err;
+		}
+	};
+	return {
+		put: (key, body, options) => run(async () => {
+			await upload(key, body, options?.contentType, options?.metadata);
+			return await headRaw(key);
+		}),
+		head: (key) => run(() => headRaw(key)),
+		get: (key) => run(async () => {
+			let out;
+			try {
+				out = await client.send(new _aws_sdk_client_s3.GetObjectCommand({
+					Bucket: bucket,
+					Key: k(key)
+				}));
+			} catch (err) {
+				if (isNotFound(err)) return;
+				throw err;
+			}
+			const info = infoFrom(key, out.ContentLength, out.ContentType, out.ETag, out.LastModified, out.Metadata);
+			const body = out.Body;
+			return {
+				info,
+				stream: () => body.transformToWebStream(),
+				bytes: () => body.transformToByteArray(),
+				text: () => body.transformToString()
+			};
+		}),
+		delete: (key) => run(async () => {
+			const existed = await headRaw(key) !== void 0;
+			await client.send(new _aws_sdk_client_s3.DeleteObjectCommand({
+				Bucket: bucket,
+				Key: k(key)
+			}));
+			return existed;
+		}),
+		list: (prefix, options) => run(async () => {
+			const out = await client.send(new _aws_sdk_client_s3.ListObjectsV2Command({
+				Bucket: bucket,
+				Prefix: k(prefix),
+				MaxKeys: options?.limit,
+				ContinuationToken: options?.cursor
+			}));
+			return {
+				files: (out.Contents ?? []).map((o) => infoFrom((o.Key ?? "").slice(ns.length), o.Size, void 0, o.ETag, o.LastModified)),
+				cursor: out.NextContinuationToken
+			};
+		}),
+		presignDownload: (key, o) => presign("get", key, o?.expiresIn ?? DEFAULT_EXPIRES_IN),
+		presignUpload: (key, o) => presign("put", key, o?.expiresIn ?? DEFAULT_EXPIRES_IN, o?.contentType)
+	};
+}
+//#endregion
+exports.s3Files = s3Files;

package/dist/s3.d.cts

@@ -0,0 +1,26 @@
+import { ResilientOptions } from "./index.cjs";
+import { S3Client } from "@aws-sdk/client-s3";
+import { FileBody, FileStore, Presigner } from "@ayepi/files";
+
+//#region src/s3.d.ts
+
+/** Options for {@link s3Files}. */
+interface S3FilesOptions extends ResilientOptions {
+  /** A configured `@aws-sdk/client-s3` `S3Client`. */
+  readonly client: S3Client;
+  /** Target bucket. */
+  readonly bucket: string;
+  /** Key prefix prepended to every key (default `''`). */
+  readonly prefix?: string;
+  /** @internal Upload seam (default: `@aws-sdk/lib-storage` multipart `Upload`) — injectable for tests. */
+  readonly upload?: (key: string, body: FileBody, contentType?: string, metadata?: Record<string, string>) => Promise<void>;
+  /** @internal Presign seam (default: `@aws-sdk/s3-request-presigner`) — injectable for tests. */
+  readonly presign?: (kind: 'get' | 'put', key: string, expiresIn: number, contentType?: string) => Promise<string>;
+}
+/**
+ * Create an S3-backed {@link FileStore} (and {@link Presigner}). Pass a configured `S3Client`
+ * and a bucket; `prefix` namespaces all keys.
+ */
+declare function s3Files(opts: S3FilesOptions): FileStore & Presigner;
+//#endregion
+export { S3FilesOptions, s3Files };

package/dist/s3.d.ts

@@ -0,0 +1,26 @@
+import { ResilientOptions } from "./index.js";
+import { S3Client } from "@aws-sdk/client-s3";
+import { FileBody, FileStore, Presigner } from "@ayepi/files";
+
+//#region src/s3.d.ts
+
+/** Options for {@link s3Files}. */
+interface S3FilesOptions extends ResilientOptions {
+  /** A configured `@aws-sdk/client-s3` `S3Client`. */
+  readonly client: S3Client;
+  /** Target bucket. */
+  readonly bucket: string;
+  /** Key prefix prepended to every key (default `''`). */
+  readonly prefix?: string;
+  /** @internal Upload seam (default: `@aws-sdk/lib-storage` multipart `Upload`) — injectable for tests. */
+  readonly upload?: (key: string, body: FileBody, contentType?: string, metadata?: Record<string, string>) => Promise<void>;
+  /** @internal Presign seam (default: `@aws-sdk/s3-request-presigner`) — injectable for tests. */
+  readonly presign?: (kind: 'get' | 'put', key: string, expiresIn: number, contentType?: string) => Promise<string>;
+}
+/**
+ * Create an S3-backed {@link FileStore} (and {@link Presigner}). Pass a configured `S3Client`
+ * and a bucket; `prefix` namespaces all keys.
+ */
+declare function s3Files(opts: S3FilesOptions): FileStore & Presigner;
+//#endregion
+export { S3FilesOptions, s3Files };

package/dist/s3.js

@@ -0,0 +1,137 @@
+import { makeRun } from "./index.js";
+import { Readable } from "node:stream";
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { Upload } from "@aws-sdk/lib-storage";
+import { toStream } from "@ayepi/files";
+//#region src/s3.ts
+/**
+* # @ayepi/aws/s3 — an S3-backed {@link FileStore}
+*
+* Stream objects to/from S3 under a key, list by prefix, and mint presigned upload/download
+* URLs (native to S3 — no server route needed). Every call is wrapped in core {@link retry}
+* so a throttled reply is absorbed.
+*
+* ```ts
+* import { S3Client } from '@aws-sdk/client-s3';
+* import { s3Files } from '@ayepi/aws/s3';
+* const files = s3Files({ client: new S3Client({ region: 'us-east-1' }), bucket: 'my-bucket' });
+* await files.put('reports/2026.csv', readableStream, { contentType: 'text/csv' });
+* const url = await files.presignDownload('reports/2026.csv', { expiresIn: 300 });
+* ```
+*
+* Note: an S3 `FileObject`'s body is read **once** — call one of `stream()`/`bytes()`/`text()`.
+*
+* @module
+*/
+/** Default presigned-URL lifetime (seconds). */
+const DEFAULT_EXPIRES_IN = 900;
+/** S3 surfaces a missing key differently per op (`NoSuchKey` on GET, `NotFound` on HEAD). */
+function isNotFound(err) {
+	const name = err?.name;
+	const status = err?.$metadata?.httpStatusCode;
+	return name === "NoSuchKey" || name === "NotFound" || status === 404;
+}
+/**
+* Create an S3-backed {@link FileStore} (and {@link Presigner}). Pass a configured `S3Client`
+* and a bucket; `prefix` namespaces all keys.
+*/
+function s3Files(opts) {
+	const { client, bucket } = opts;
+	const ns = opts.prefix ?? "";
+	const run = makeRun(opts);
+	const k = (key) => ns + key;
+	/* v8 ignore start -- SDK glue: exercised only against real S3 (integration test) */
+	const sdkUpload = (key, body, contentType, metadata) => new Upload({
+		client,
+		params: {
+			Bucket: bucket,
+			Key: k(key),
+			Body: Readable.fromWeb(toStream(body)),
+			ContentType: contentType,
+			Metadata: metadata
+		}
+	}).done().then(() => void 0);
+	const sdkPresign = (kind, key, expiresIn, contentType) => getSignedUrl(client, kind === "get" ? new GetObjectCommand({
+		Bucket: bucket,
+		Key: k(key)
+	}) : new PutObjectCommand({
+		Bucket: bucket,
+		Key: k(key),
+		ContentType: contentType
+	}), { expiresIn });
+	/* v8 ignore stop */
+	const upload = opts.upload ?? sdkUpload;
+	const presign = opts.presign ?? sdkPresign;
+	const infoFrom = (key, size, contentType, etag, modified, metadata) => ({
+		key,
+		size: size ?? 0,
+		contentType,
+		etag,
+		modifiedAt: modified ? modified.getTime() : 0,
+		metadata
+	});
+	const headRaw = async (key) => {
+		try {
+			const out = await client.send(new HeadObjectCommand({
+				Bucket: bucket,
+				Key: k(key)
+			}));
+			return infoFrom(key, out.ContentLength, out.ContentType, out.ETag, out.LastModified, out.Metadata);
+		} catch (err) {
+			if (isNotFound(err)) return;
+			throw err;
+		}
+	};
+	return {
+		put: (key, body, options) => run(async () => {
+			await upload(key, body, options?.contentType, options?.metadata);
+			return await headRaw(key);
+		}),
+		head: (key) => run(() => headRaw(key)),
+		get: (key) => run(async () => {
+			let out;
+			try {
+				out = await client.send(new GetObjectCommand({
+					Bucket: bucket,
+					Key: k(key)
+				}));
+			} catch (err) {
+				if (isNotFound(err)) return;
+				throw err;
+			}
+			const info = infoFrom(key, out.ContentLength, out.ContentType, out.ETag, out.LastModified, out.Metadata);
+			const body = out.Body;
+			return {
+				info,
+				stream: () => body.transformToWebStream(),
+				bytes: () => body.transformToByteArray(),
+				text: () => body.transformToString()
+			};
+		}),
+		delete: (key) => run(async () => {
+			const existed = await headRaw(key) !== void 0;
+			await client.send(new DeleteObjectCommand({
+				Bucket: bucket,
+				Key: k(key)
+			}));
+			return existed;
+		}),
+		list: (prefix, options) => run(async () => {
+			const out = await client.send(new ListObjectsV2Command({
+				Bucket: bucket,
+				Prefix: k(prefix),
+				MaxKeys: options?.limit,
+				ContinuationToken: options?.cursor
+			}));
+			return {
+				files: (out.Contents ?? []).map((o) => infoFrom((o.Key ?? "").slice(ns.length), o.Size, void 0, o.ETag, o.LastModified)),
+				cursor: out.NextContinuationToken
+			};
+		}),
+		presignDownload: (key, o) => presign("get", key, o?.expiresIn ?? DEFAULT_EXPIRES_IN),
+		presignUpload: (key, o) => presign("put", key, o?.expiresIn ?? DEFAULT_EXPIRES_IN, o?.contentType)
+	};
+}
+//#endregion
+export { s3Files };

package/dist/sqs.cjs

@@ -0,0 +1,135 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_index = require("./index.cjs");
+let node_crypto = require("node:crypto");
+let _aws_sdk_client_sqs = require("@aws-sdk/client-sqs");
+//#region src/sqs.ts
+/**
+* # @ayepi/aws/sqs — an SQS-backed `@ayepi/work` {@link Queue}
+*
+* SQS's native visibility-timeout model maps directly onto the work {@link Queue} contract:
+* `pop` is `ReceiveMessage` (a lease), `heartbeat` is `ChangeMessageVisibility`, `ack` is
+* `DeleteMessage`, `fail` returns the message early. A worker that dies lets the visibility
+* lapse and SQS redelivers (with `ApproximateReceiveCount` → `attempt`); exhausted retries go
+* to the queue's configured **dead-letter queue** (SQS redrive).
+*
+* **Large payloads** (SQS caps a message at 256 KB) are transparently offloaded: a body over
+* the threshold is written to S3 (any {@link FileStore}) and the message carries a small
+* pointer; `pop` inlines it back and `ack` deletes the S3 object. Every AWS call is wrapped in
+* core {@link retry}.
+*
+* @module
+*/
+/** SQS allows at most 10 messages per `ReceiveMessage`. */
+const MAX_RECEIVE = 10;
+/** SQS rejects `DelaySeconds` outside 0–900 (15 min). */
+const MAX_DELAY_SECONDS = 900;
+/** SQS rejects a visibility timeout outside 0–43200 (12 h). */
+const MAX_VISIBILITY_SECONDS = 43200;
+/** Default large-payload threshold (bytes) — comfortably under SQS's 256 KB message limit. */
+const DEFAULT_THRESHOLD = 240 * 1024;
+/** The marker key identifying an S3-offloaded message body. */
+const S3_MARKER = "__ayepiS3__";
+const MS_PER_SECOND = 1e3;
+const secs = (ms) => Math.ceil(ms / MS_PER_SECOND);
+/** Clamp a delay (ms) to SQS's `DelaySeconds` range so a far-future schedule doesn't error (the engine re-defers). */
+const delaySecs = (ms) => Math.min(MAX_DELAY_SECONDS, Math.max(0, secs(ms)));
+/** Clamp a visibility/backoff (ms) to SQS's max so a long `fail`/`heartbeat` doesn't error (the engine re-defers). */
+const visSecs = (ms) => Math.min(MAX_VISIBILITY_SECONDS, Math.max(0, secs(ms)));
+/** If `body` is an S3 pointer, return the key; else `undefined`. */
+function pointerKey(body) {
+	try {
+		const key = JSON.parse(body)[S3_MARKER];
+		return typeof key === "string" ? key : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Create an SQS-backed `@ayepi/work` {@link Queue}. Configure the SQS DLQ (redrive policy) on
+* the queue itself for dead-lettering; pass `largePayload` to offload oversized bodies to S3.
+*
+* @example
+* ```ts
+* import { SQSClient } from '@aws-sdk/client-sqs';
+* import { sqsQueue } from '@ayepi/aws/sqs';
+* import { s3Files } from '@ayepi/aws/s3';
+* const queue = sqsQueue({
+*   client: new SQSClient({ region: 'us-east-1' }),
+*   queueUrl: process.env.SQS_URL!,
+*   waitTimeSeconds: 10,
+*   largePayload: { store: s3Files({ client: s3, bucket: 'work-payloads' }) },
+* });
+* createWork({ work, queue, store: redisStore(redis), pubsub: redisPubSub(redis) });
+* ```
+*/
+function sqsQueue(opts) {
+	const { client, queueUrl } = opts;
+	const run = require_index.makeRun(opts);
+	const large = opts.largePayload;
+	const threshold = large?.threshold ?? DEFAULT_THRESHOLD;
+	const largePrefix = large?.prefix ?? "sqs-payloads/";
+	const waitTimeSeconds = opts.waitTimeSeconds;
+	const handleOf = (pulled) => pulled.handle;
+	return {
+		push: (body, o) => run(async () => {
+			let messageBody = body;
+			if (large && body.length > threshold) {
+				const key = `${largePrefix}${(0, node_crypto.randomUUID)()}`;
+				await large.store.put(key, body, { contentType: "application/json" });
+				messageBody = JSON.stringify({ [S3_MARKER]: key });
+			}
+			await client.send(new _aws_sdk_client_sqs.SendMessageCommand({
+				QueueUrl: queueUrl,
+				MessageBody: messageBody,
+				DelaySeconds: o?.delay !== void 0 ? delaySecs(o.delay) : void 0
+			}));
+		}),
+		pop: (max, visibility) => run(async () => {
+			const out = await client.send(new _aws_sdk_client_sqs.ReceiveMessageCommand({
+				QueueUrl: queueUrl,
+				MaxNumberOfMessages: Math.min(max, MAX_RECEIVE),
+				VisibilityTimeout: visSecs(visibility),
+				WaitTimeSeconds: waitTimeSeconds,
+				MessageSystemAttributeNames: ["ApproximateReceiveCount"]
+			}));
+			return Promise.all((out.Messages ?? []).map(async (m) => {
+				const attempt = Number(m.Attributes?.ApproximateReceiveCount ?? "1");
+				let body = m.Body ?? "";
+				const s3Key = large ? pointerKey(body) : void 0;
+				if (s3Key) body = await (await large.store.get(s3Key))?.text() ?? "";
+				return {
+					body,
+					handle: {
+						receiptHandle: m.ReceiptHandle ?? "",
+						s3Key
+					},
+					attempt
+				};
+			}));
+		}),
+		heartbeat: (pulled, visibility) => run(async () => {
+			await client.send(new _aws_sdk_client_sqs.ChangeMessageVisibilityCommand({
+				QueueUrl: queueUrl,
+				ReceiptHandle: handleOf(pulled).receiptHandle,
+				VisibilityTimeout: visSecs(visibility)
+			}));
+		}),
+		ack: (pulled) => run(async () => {
+			const h = handleOf(pulled);
+			await client.send(new _aws_sdk_client_sqs.DeleteMessageCommand({
+				QueueUrl: queueUrl,
+				ReceiptHandle: h.receiptHandle
+			}));
+			if (h.s3Key && large) await large.store.delete(h.s3Key);
+		}),
+		fail: (pulled, delay) => run(async () => {
+			await client.send(new _aws_sdk_client_sqs.ChangeMessageVisibilityCommand({
+				QueueUrl: queueUrl,
+				ReceiptHandle: handleOf(pulled).receiptHandle,
+				VisibilityTimeout: visSecs(delay ?? 0)
+			}));
+		})
+	};
+}
+//#endregion
+exports.sqsQueue = sqsQueue;

package/dist/sqs.d.cts

@@ -0,0 +1,48 @@
+import { ResilientOptions } from "./index.cjs";
+import { FileStore } from "@ayepi/files";
+import { SQSClient } from "@aws-sdk/client-sqs";
+import { Queue } from "@ayepi/work";
+
+//#region src/sqs.d.ts
+
+/** Offload config — where oversized message bodies live. */
+interface LargePayloadOptions {
+  /** The store oversized bodies are written to (e.g. `s3Files({...})`). */
+  readonly store: FileStore;
+  /** Offload bodies larger than this many bytes (default ~240 KB). */
+  readonly threshold?: number;
+  /** Key prefix for offloaded bodies (default `'sqs-payloads/'`). */
+  readonly prefix?: string;
+}
+/** Options for {@link sqsQueue}. */
+interface SqsQueueOptions extends ResilientOptions {
+  /** A configured `@aws-sdk/client-sqs` `SQSClient`. */
+  readonly client: SQSClient;
+  /** The target queue URL. */
+  readonly queueUrl: string;
+  /** Long-poll seconds for `pop` (0–20, default 0). */
+  readonly waitTimeSeconds?: number;
+  /** Transparently offload large bodies to S3. */
+  readonly largePayload?: LargePayloadOptions;
+}
+/**
+ * Create an SQS-backed `@ayepi/work` {@link Queue}. Configure the SQS DLQ (redrive policy) on
+ * the queue itself for dead-lettering; pass `largePayload` to offload oversized bodies to S3.
+ *
+ * @example
+ * ```ts
+ * import { SQSClient } from '@aws-sdk/client-sqs';
+ * import { sqsQueue } from '@ayepi/aws/sqs';
+ * import { s3Files } from '@ayepi/aws/s3';
+ * const queue = sqsQueue({
+ *   client: new SQSClient({ region: 'us-east-1' }),
+ *   queueUrl: process.env.SQS_URL!,
+ *   waitTimeSeconds: 10,
+ *   largePayload: { store: s3Files({ client: s3, bucket: 'work-payloads' }) },
+ * });
+ * createWork({ work, queue, store: redisStore(redis), pubsub: redisPubSub(redis) });
+ * ```
+ */
+declare function sqsQueue(opts: SqsQueueOptions): Queue;
+//#endregion
+export { LargePayloadOptions, SqsQueueOptions, sqsQueue };

package/dist/sqs.d.ts

@@ -0,0 +1,48 @@
+import { ResilientOptions } from "./index.js";
+import { FileStore } from "@ayepi/files";
+import { SQSClient } from "@aws-sdk/client-sqs";
+import { Queue } from "@ayepi/work";
+
+//#region src/sqs.d.ts
+
+/** Offload config — where oversized message bodies live. */
+interface LargePayloadOptions {
+  /** The store oversized bodies are written to (e.g. `s3Files({...})`). */
+  readonly store: FileStore;
+  /** Offload bodies larger than this many bytes (default ~240 KB). */
+  readonly threshold?: number;
+  /** Key prefix for offloaded bodies (default `'sqs-payloads/'`). */
+  readonly prefix?: string;
+}
+/** Options for {@link sqsQueue}. */
+interface SqsQueueOptions extends ResilientOptions {
+  /** A configured `@aws-sdk/client-sqs` `SQSClient`. */
+  readonly client: SQSClient;
+  /** The target queue URL. */
+  readonly queueUrl: string;
+  /** Long-poll seconds for `pop` (0–20, default 0). */
+  readonly waitTimeSeconds?: number;
+  /** Transparently offload large bodies to S3. */
+  readonly largePayload?: LargePayloadOptions;
+}
+/**
+ * Create an SQS-backed `@ayepi/work` {@link Queue}. Configure the SQS DLQ (redrive policy) on
+ * the queue itself for dead-lettering; pass `largePayload` to offload oversized bodies to S3.
+ *
+ * @example
+ * ```ts
+ * import { SQSClient } from '@aws-sdk/client-sqs';
+ * import { sqsQueue } from '@ayepi/aws/sqs';
+ * import { s3Files } from '@ayepi/aws/s3';
+ * const queue = sqsQueue({
+ *   client: new SQSClient({ region: 'us-east-1' }),
+ *   queueUrl: process.env.SQS_URL!,
+ *   waitTimeSeconds: 10,
+ *   largePayload: { store: s3Files({ client: s3, bucket: 'work-payloads' }) },
+ * });
+ * createWork({ work, queue, store: redisStore(redis), pubsub: redisPubSub(redis) });
+ * ```
+ */
+declare function sqsQueue(opts: SqsQueueOptions): Queue;
+//#endregion
+export { LargePayloadOptions, SqsQueueOptions, sqsQueue };

package/dist/sqs.js

@@ -0,0 +1,134 @@
+import { makeRun } from "./index.js";
+import { randomUUID } from "node:crypto";
+import { ChangeMessageVisibilityCommand, DeleteMessageCommand, ReceiveMessageCommand, SendMessageCommand } from "@aws-sdk/client-sqs";
+//#region src/sqs.ts
+/**
+* # @ayepi/aws/sqs — an SQS-backed `@ayepi/work` {@link Queue}
+*
+* SQS's native visibility-timeout model maps directly onto the work {@link Queue} contract:
+* `pop` is `ReceiveMessage` (a lease), `heartbeat` is `ChangeMessageVisibility`, `ack` is
+* `DeleteMessage`, `fail` returns the message early. A worker that dies lets the visibility
+* lapse and SQS redelivers (with `ApproximateReceiveCount` → `attempt`); exhausted retries go
+* to the queue's configured **dead-letter queue** (SQS redrive).
+*
+* **Large payloads** (SQS caps a message at 256 KB) are transparently offloaded: a body over
+* the threshold is written to S3 (any {@link FileStore}) and the message carries a small
+* pointer; `pop` inlines it back and `ack` deletes the S3 object. Every AWS call is wrapped in
+* core {@link retry}.
+*
+* @module
+*/
+/** SQS allows at most 10 messages per `ReceiveMessage`. */
+const MAX_RECEIVE = 10;
+/** SQS rejects `DelaySeconds` outside 0–900 (15 min). */
+const MAX_DELAY_SECONDS = 900;
+/** SQS rejects a visibility timeout outside 0–43200 (12 h). */
+const MAX_VISIBILITY_SECONDS = 43200;
+/** Default large-payload threshold (bytes) — comfortably under SQS's 256 KB message limit. */
+const DEFAULT_THRESHOLD = 240 * 1024;
+/** The marker key identifying an S3-offloaded message body. */
+const S3_MARKER = "__ayepiS3__";
+const MS_PER_SECOND = 1e3;
+const secs = (ms) => Math.ceil(ms / MS_PER_SECOND);
+/** Clamp a delay (ms) to SQS's `DelaySeconds` range so a far-future schedule doesn't error (the engine re-defers). */
+const delaySecs = (ms) => Math.min(MAX_DELAY_SECONDS, Math.max(0, secs(ms)));
+/** Clamp a visibility/backoff (ms) to SQS's max so a long `fail`/`heartbeat` doesn't error (the engine re-defers). */
+const visSecs = (ms) => Math.min(MAX_VISIBILITY_SECONDS, Math.max(0, secs(ms)));
+/** If `body` is an S3 pointer, return the key; else `undefined`. */
+function pointerKey(body) {
+	try {
+		const key = JSON.parse(body)[S3_MARKER];
+		return typeof key === "string" ? key : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Create an SQS-backed `@ayepi/work` {@link Queue}. Configure the SQS DLQ (redrive policy) on
+* the queue itself for dead-lettering; pass `largePayload` to offload oversized bodies to S3.
+*
+* @example
+* ```ts
+* import { SQSClient } from '@aws-sdk/client-sqs';
+* import { sqsQueue } from '@ayepi/aws/sqs';
+* import { s3Files } from '@ayepi/aws/s3';
+* const queue = sqsQueue({
+*   client: new SQSClient({ region: 'us-east-1' }),
+*   queueUrl: process.env.SQS_URL!,
+*   waitTimeSeconds: 10,
+*   largePayload: { store: s3Files({ client: s3, bucket: 'work-payloads' }) },
+* });
+* createWork({ work, queue, store: redisStore(redis), pubsub: redisPubSub(redis) });
+* ```
+*/
+function sqsQueue(opts) {
+	const { client, queueUrl } = opts;
+	const run = makeRun(opts);
+	const large = opts.largePayload;
+	const threshold = large?.threshold ?? DEFAULT_THRESHOLD;
+	const largePrefix = large?.prefix ?? "sqs-payloads/";
+	const waitTimeSeconds = opts.waitTimeSeconds;
+	const handleOf = (pulled) => pulled.handle;
+	return {
+		push: (body, o) => run(async () => {
+			let messageBody = body;
+			if (large && body.length > threshold) {
+				const key = `${largePrefix}${randomUUID()}`;
+				await large.store.put(key, body, { contentType: "application/json" });
+				messageBody = JSON.stringify({ [S3_MARKER]: key });
+			}
+			await client.send(new SendMessageCommand({
+				QueueUrl: queueUrl,
+				MessageBody: messageBody,
+				DelaySeconds: o?.delay !== void 0 ? delaySecs(o.delay) : void 0
+			}));
+		}),
+		pop: (max, visibility) => run(async () => {
+			const out = await client.send(new ReceiveMessageCommand({
+				QueueUrl: queueUrl,
+				MaxNumberOfMessages: Math.min(max, MAX_RECEIVE),
+				VisibilityTimeout: visSecs(visibility),
+				WaitTimeSeconds: waitTimeSeconds,
+				MessageSystemAttributeNames: ["ApproximateReceiveCount"]
+			}));
+			return Promise.all((out.Messages ?? []).map(async (m) => {
+				const attempt = Number(m.Attributes?.ApproximateReceiveCount ?? "1");
+				let body = m.Body ?? "";
+				const s3Key = large ? pointerKey(body) : void 0;
+				if (s3Key) body = await (await large.store.get(s3Key))?.text() ?? "";
+				return {
+					body,
+					handle: {
+						receiptHandle: m.ReceiptHandle ?? "",
+						s3Key
+					},
+					attempt
+				};
+			}));
+		}),
+		heartbeat: (pulled, visibility) => run(async () => {
+			await client.send(new ChangeMessageVisibilityCommand({
+				QueueUrl: queueUrl,
+				ReceiptHandle: handleOf(pulled).receiptHandle,
+				VisibilityTimeout: visSecs(visibility)
+			}));
+		}),
+		ack: (pulled) => run(async () => {
+			const h = handleOf(pulled);
+			await client.send(new DeleteMessageCommand({
+				QueueUrl: queueUrl,
+				ReceiptHandle: h.receiptHandle
+			}));
+			if (h.s3Key && large) await large.store.delete(h.s3Key);
+		}),
+		fail: (pulled, delay) => run(async () => {
+			await client.send(new ChangeMessageVisibilityCommand({
+				QueueUrl: queueUrl,
+				ReceiptHandle: handleOf(pulled).receiptHandle,
+				VisibilityTimeout: visSecs(delay ?? 0)
+			}));
+		})
+	};
+}
+//#endregion
+export { sqsQueue };

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@ayepi/aws",
+  "version": "0.1.0",
+  "description": "AWS backends for ayepi — an SQS @ayepi/work queue (large payloads offloaded to S3) and an S3 @ayepi/files store, all retry-wrapped for throttle resilience",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/aws"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/aws#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./s3": {
+      "import": {
+        "types": "./dist/s3.d.ts",
+        "default": "./dist/s3.js"
+      },
+      "require": {
+        "types": "./dist/s3.d.cts",
+        "default": "./dist/s3.cjs"
+      }
+    },
+    "./sqs": {
+      "import": {
+        "types": "./dist/sqs.d.ts",
+        "default": "./dist/sqs.js"
+      },
+      "require": {
+        "types": "./dist/sqs.d.cts",
+        "default": "./dist/sqs.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3",
+    "@aws-sdk/client-sqs": "^3",
+    "@aws-sdk/lib-storage": "^3",
+    "@aws-sdk/s3-request-presigner": "^3",
+    "@ayepi/core": "^0.1.0",
+    "@ayepi/files": "^0.1.0",
+    "@ayepi/work": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@ayepi/work": {
+      "optional": true
+    },
+    "@ayepi/files": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/client-sqs": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/client-sqs": "^3.700.0",
+    "@aws-sdk/lib-storage": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@vitest/coverage-v8": "^2.1.8",
+    "publint": "^0.3.0",
+    "testcontainers": "^10.13.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8",
+    "zod": "^4.4.3",
+    "@ayepi/files": "0.1.0",
+    "@ayepi/core": "0.1.0",
+    "@ayepi/work": "0.1.0"
+  },
+  "keywords": [
+    "ayepi",
+    "aws",
+    "sqs",
+    "s3",
+    "work-queue",
+    "file-storage",
+    "@ayepi/work",
+    "@ayepi/files"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "publint": "publint"
+  }
+}