@procedures/s3 0.48.0 → 0.48.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @procedures/s3
 
+## 0.48.1
+
+### Patch Changes
+
+- dd1a84b: `s3.upload` takes a new input `sourcePath`, the path of a file. The upload reads one part at a time, so the memory stays bounded, and the object is whole or absent. This is a PATCH by the rule for a new feature before 1.0.0: `S3UploadInput` and `S3UploadInputSchema` do not change. The new exports are `S3UploadFileInput` with its schema, `S3UploadCall` and `S3UploadCallSchema`. A call with `body` and `sourcePath`, or with neither, fails at the type and at run time. `s3Upload` takes `S3UploadCall`, so a value of `S3UploadInput` is still a call. Under the root of a host, `sourcePath` is in the root. The effects of `s3.upload` now name `fs` in `reads`.
+- Updated dependencies [2d7edae]
+  - @procedures/client@0.48.1
+
 ## 0.48.0
 
 ### Patch Changes

package/README.md

@@ -175,8 +175,25 @@ console.log(result.etag);
 console.log(result.location);  // s3://my-bucket/files/document.pdf
 ```
 
+To send a large file, give `sourcePath` in place of `body`:
+
+```typescript
+await client.exec(["s3", "upload"], {
+  bucket: "my-bucket",
+  key: "backups/archive.tar.gz",
+  sourcePath: "/var/backups/archive.tar.gz",
+});
+```
+
+- The memory that the upload holds is one part: 8 MiB. For a file above 80,000 MiB, a part is the size of the file divided by 10,000.
+- A file of one part or less goes in one put. A larger file goes in a multipart upload, one part at a time.
+- The object is whole or absent. On a failure, the upload aborts and the call gives the first error.
+- When the abort also fails, S3 keeps the parts. A lifecycle rule of the bucket removes them.
+- The call fails when the size or the modification time of the file changes during the upload.
+
 **Input:**
 ```typescript
+// A call gives one of these two forms. A call with body and sourcePath, or with neither, fails.
 interface S3UploadInput {
   bucket: string;                    // S3 bucket name
   key: string;                       // Object key (path in bucket)
@@ -185,6 +202,14 @@ interface S3UploadInput {
   base64?: boolean;                  // If true, body is base64 encoded
   metadata?: Record<string, string>; // Custom metadata
 }
+
+interface S3UploadFileInput {
+  bucket: string;                    // S3 bucket name
+  key: string;                       // Object key (path in bucket)
+  sourcePath: string;                // The path of a file to upload
+  contentType?: string;              // MIME type
+  metadata?: Record<string, string>; // Custom metadata
+}
 ```
 
 **Output:**
@@ -922,7 +947,7 @@ npm run clean
 
 ## The root of the files
 
-Under the root of a host (`mark --fs-root`, `procedure-server --fs-root`, `MCP_FS_ROOT`), `s3.download` writes its `destPath` only in the root. A relative `destPath` starts at the root. `s3.presign` has no path input, and the other procedures reach no file. The AWS SDK reads the credentials of the host, also under a root.
+Under the root of a host (`mark --fs-root`, `procedure-server --fs-root`, `MCP_FS_ROOT`), `s3.download` writes its `destPath` only in the root, and `s3.upload` reads its `sourcePath` only in the root. A relative `destPath` or `sourcePath` starts at the root. `s3.presign` has no path input, and the other procedures reach no file. The AWS SDK reads the credentials of the host, also under a root.
 
 The rules and the table of the procedures are in [CAPABILITIES-2026-10.md](../documentation/CAPABILITIES-2026-10.md#the-root-of-the-files-roadmap-r33).