1import type { PresignError } from "@distilled.cloud/aws/Presign";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { Bucket } from "./Bucket.ts";
5
6export interface PresignGetObjectRequest {
7 /**
8 * Key of the object to mint a presigned download URL for.
9 */
10 key: string;
11 /**
12 * Specific object version to download. Signed as the `versionId` query
13 * parameter. If omitted, downloads the current version when the URL is used.
14 * Use the string `"null"` to select an existing null version.
15 */
16 versionId?: string;
17 /**
18 * Number of seconds the URL remains valid.
19 * @default 900
20 */
21 expiresIn?: number;
22 /**
23 * Override the `Content-Type` S3 responds with (signed as the
24 * `response-content-type` query parameter).
25 */
26 contentType?: string;
27}
28
29/**
30 * Mint presigned download (GET) URLs for objects in a {@link Bucket}.
31 *
32 * Presigning is a pure SigV4 computation performed client-side with the
33 * Function's own credentials — no S3 API call is made. Because the URL
34 * inherits the signer's IAM permissions, the binding grants `s3:GetObject`
35 * and `s3:GetObjectVersion` on the bucket's objects to the host Function.
36 * See the [S3 presigned URL
37 * guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html).
38 *
39 * ### Presigning Download URLs
40 * **Example:** Mint a presigned GET URL
41 * ```typescript
42 * const presignGetObject = yield* S3.PresignGetObject(bucket);
43 * const url = yield* presignGetObject({ key: "reports/2026.pdf" });
44 * // hand `url` to a browser — it can download the object without AWS credentials
45 * ```
46 *
47 * ### Downloading a Specific Version
48 * **Example:** Mint a presigned GET URL for an older version
49 * ```typescript
50 * const presignGetObject = yield* S3.PresignGetObject(bucket);
51 * const url = yield* presignGetObject({
52 * key: "reports/2026.pdf",
53 * versionId: "3HL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nrjfkd",
54 * });
55 * // downloads this version even if the key has since been overwritten
56 * ```
57 *
58 * ### Customizing Download URLs
59 * **Example:** Custom expiry and response Content-Type
60 * ```typescript
61 * const url = yield* presignGetObject({
62 * key: "reports/2026.pdf",
63 * expiresIn: 3600, // valid for 1 hour
64 * contentType: "application/pdf",
65 * });
66 * ```
67 *
68 * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html
69 *
70 * @binding
71 */
72export interface PresignGetObject extends Binding.Service<
73 PresignGetObject,
74 "AWS.S3.PresignGetObject",
75 (
76 bucket: Bucket,
77 ) => Effect.Effect<
78 (request: PresignGetObjectRequest) => Effect.Effect<string, PresignError>
79 >
80> {}
81
82export const PresignGetObject = Binding.Service<PresignGetObject>(
83 "AWS.S3.PresignGetObject",
84);