API Reference

parseS3UrlExpiration

Parses an S3 pre-signed URL to extract expiration information.

Pre-signed URLs contain X-Amz-Date (signing time) and X-Amz-Expires (validity in seconds).

### Parameters
| Name | Type | Description |
|------|------|-------------|
| `url` | `string` | The S3 pre-signed URL to parse. |

### Returns
**Type:** `object`

- Object with signedAt (Date), expiresInSeconds (number),
                       and expiresAt (Date), or null if parsing fails.

### Examples

  ```javascript
  const info = parseS3UrlExpiration('https://...?X-Amz-Date=20240115T120000Z&X-Amz-Expires=7200...');

// Returns: { signedAt: Date, expiresInSeconds: 7200, expiresAt: Date } ```

---

isUrlExpiringSoon

Checks if an S3 pre-signed URL is expiring soon or has already expired.

### Parameters
| Name | Type | Description |
|------|------|-------------|
| `url` | `string` | The S3 pre-signed URL to check. |
| `thresholdMinutes` | `number` | Minutes before expiration to consider "expiring soon".
                                  Defaults to 5 minutes. |

### Returns
**Type:** `boolean`

- True if the URL is expired or expiring within the threshold.

### Examples

  ```javascript
  if (isUrlExpiringSoon(downloadUrl)) {

// Refresh the URL } ```

---

getUrlRemainingTime

Gets the remaining time until a URL expires.

### Parameters
| Name | Type | Description |
|------|------|-------------|
| `url` | `string` | The S3 pre-signed URL. |

### Returns
**Type:** `number`

- Remaining time in seconds, or null if parsing fails.
                       Negative values indicate the URL has already expired.

---

formatRemainingTime

Formats remaining time in a human-readable format.

### Parameters
| Name | Type | Description |
|------|------|-------------|
| `seconds` | `number` | Remaining time in seconds. |

### Returns
**Type:** `string`

- Formatted string like "1h 30m" or "5m 30s".

---