@procedures/s3 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @procedures/s3
 
+## 0.3.0
+
+### Minor Changes
+
+- ffb35f3: Three object procedures (roadmap R44). `s3.head` gives the metadata of an object without its content, and `exists: false` for a 404. `s3.copy` copies an object inside S3. It replaces the destination, unless `overwrite` is false. `s3.presign` gives a presigned URL for a `GET` or a `PUT`, with an expiry in seconds. It sends no request to S3. A call whose capability does not permit the writes of `s3.upload` gets no `PUT` URL. The new dependency is `@aws-sdk/s3-request-presigner`.
+
+### Patch Changes
+
+- Updated dependencies [ddea529]
+- Updated dependencies [b2a3e3a]
+- Updated dependencies [a8c47f1]
+- Updated dependencies [381ce3a]
+- Updated dependencies [0c627f8]
+- Updated dependencies [ae7f05f]
+- Updated dependencies [7873940]
+- Updated dependencies [a70d445]
+- Updated dependencies [bc70357]
+- Updated dependencies [07cc998]
+- Updated dependencies [a6b01a9]
+- Updated dependencies [c799cdd]
+- Updated dependencies [540f8d9]
+- Updated dependencies [b6daaec]
+- Updated dependencies [5b9264e]
+- Updated dependencies [956e88b]
+- Updated dependencies [ff62281]
+- Updated dependencies [d81d0ed]
+- Updated dependencies [aa67cc7]
+- Updated dependencies [061fa22]
+- Updated dependencies [cfb9d69]
+- Updated dependencies [43f7de5]
+- Updated dependencies [b07bb50]
+- Updated dependencies [4a3bfa1]
+- Updated dependencies [bd0b626]
+- Updated dependencies [a6be873]
+- Updated dependencies [fb30718]
+- Updated dependencies [c5528e4]
+- Updated dependencies [fee5d9c]
+- Updated dependencies [21f7743]
+- Updated dependencies [31a0b46]
+  - @procedures/client@0.3.0
+
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies [15e48cf]
+  - @procedures/client@0.2.3
+
 ## 0.2.2
 
 ### Patch Changes

package/README.md

@@ -17,8 +17,9 @@ AWS S3 operations as RPC procedures. Upload, download, list, delete, and perform
 - **Zod validation**: Runtime type safety on all inputs
 - **MinIO/LocalStack support**: Custom S3 endpoints for testing
 
-The package has 9 procedures. Its register entry (`import "@procedures/s3/register"`) registers them:
+The package has 12 procedures. Its register entry (`import "@procedures/s3/register"`) registers them:
 - **Standard**: `s3.upload`, `s3.download`, `s3.list`, `s3.listAll`, `s3.delete`
+- **Metadata, copies and URLs**: `s3.head`, `s3.copy`, `s3.presign`
 - **Multipart**: `s3.multipart.init`, `s3.multipart.upload`, `s3.multipart.complete`, `s3.multipart.abort`
 
 ## Architecture
@@ -373,6 +374,47 @@ interface S3DeleteOutput {
 }
 ```
 
+#### `s3.head`
+
+The procedure gives the metadata of an object without its content. The metadata is the size, the content type, the ETag, the time of the last change and the user metadata. A 404 gives `exists: false`. S3 gives no body with a 404 to a HEAD request, so a missing bucket also gives `exists: false`.
+
+```typescript
+const head = await client.exec(["s3", "head"], { bucket: "my-bucket", key: "files/report.pdf" });
+if (head.exists) console.log(head.contentLength, head.etag);
+```
+
+#### `s3.copy`
+
+The procedure copies an object inside S3. The bytes do not go through the host. The copy replaces the object of the destination key. With `overwrite: false`, S3 refuses the copy when the destination key exists. One request copies an object of 5 GiB or less.
+
+The source bucket is the destination bucket when the input does not give `sourceBucket`. With `contentType` or `metadata`, the copy gets new metadata. Without them, it keeps the metadata of the source.
+
+```typescript
+await client.exec(["s3", "copy"], {
+  sourceBucket: "my-bucket",
+  sourceKey: "files/report.pdf",
+  bucket: "my-archive",
+  key: "2026/report.pdf",
+  overwrite: false,
+});
+```
+
+#### `s3.presign`
+
+The procedure gives a presigned URL for a `GET` (the default) or a `PUT` of one object. `expiresIn` is the life of the URL in seconds: 900 by default, and 604800 (7 days) or less. The procedure sends no request to S3. It reads the credentials and calculates a Signature Version 4.
+
+Its effects are `reads: ["fs", "network"]` and `writes: []`. The default credential chain can read the AWS files of the host or the instance metadata service. A `PUT` URL lets its holder write the object. Thus a call whose capability does not permit the writes of `s3.upload` gets `FORBIDDEN` for a `PUT` URL.
+
+```typescript
+const { url, expiresAt } = await client.exec(["s3", "presign"], {
+  bucket: "my-bucket",
+  key: "uploads/photo.jpg",
+  method: "PUT",
+  expiresIn: 300,
+  contentType: "image/jpeg",
+});
+```
+
 ### Multipart Upload Operations
 
 For large files (>5MB), use multipart upload:
@@ -808,6 +850,7 @@ import "@procedures/fs/register"; // registers its procedures
 
 - **@procedures/client** - Core client procedure system
 - **@aws-sdk/client-s3** (^3.705.0) - AWS SDK for S3
+- **@aws-sdk/s3-request-presigner** (3.1147.0) - The signature of the URLs of `s3.presign`
 - **zod** (^3.24.0) - Runtime type validation
 
 ### Development Dependencies
@@ -832,6 +875,9 @@ client-s3/
 │   │       ├── download.ts           # s3.download
 │   │       ├── list.ts               # s3.list
 │   │       ├── delete.ts             # s3.delete
+│   │       ├── head.ts               # s3.head
+│   │       ├── copy.ts               # s3.copy
+│   │       ├── presign.ts            # s3.presign
 │   │       ├── multipart-init.ts     # s3.multipart.init
 │   │       ├── multipart-upload.ts   # s3.multipart.upload
 │   │       ├── multipart-complete.ts # s3.multipart.complete