@c9up/archive 0.1.12 → 0.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/GcsDriver.ts CHANGED
@@ -46,11 +46,30 @@ function gcsStrictEncode(str: string): string {
46
46
  );
47
47
  }
48
48
 
49
- /** Encode an object path segment-by-segment, preserving `/`. */
49
+ /**
50
+ * Encode an object path segment-by-segment, preserving `/`.
51
+ *
52
+ * This is the form the XML download endpoint and the V4 signing canonical
53
+ * resource want: the signing rules list the characters to percent-encode and
54
+ * `/` is not among them, so encoding it there would break every signature.
55
+ */
50
56
  function gcsEncodeKey(key: string): string {
51
57
  return key.split("/").map(gcsStrictEncode).join("/");
52
58
  }
53
59
 
60
+ /**
61
+ * Encode an object NAME for the JSON API, where the whole name is one path
62
+ * segment and `/` is part of it.
63
+ *
64
+ * The JSON API addresses `…/b/{bucket}/o/{object}`; an unencoded slash there
65
+ * makes the request address a different resource, which answers 404. Since
66
+ * `exists()` and `delete()` read a 404 as "not there", every object inside a
67
+ * prefix would silently look absent.
68
+ */
69
+ function gcsEncodeObjectName(key: string): string {
70
+ return gcsStrictEncode(key);
71
+ }
72
+
54
73
  /** Type guard matching the same pattern as `S3Driver.hasDestroy` —
55
74
  * duplicated on purpose (package-local). */
56
75
  function hasDestroy(x: unknown): x is { destroy(err?: Error): void } {
@@ -112,7 +131,7 @@ export class GcsDriver implements StorageDriver {
112
131
  } catch (err) {
113
132
  if (err instanceof Error && err.name === "TimeoutError") {
114
133
  throw new ArchiveError(
115
- "ARCHIVE_REQUEST_TIMEOUT",
134
+ "E_ARCHIVE_REQUEST_TIMEOUT",
116
135
  `The storage provider did not answer within ${ms}ms.`,
117
136
  {
118
137
  hint: "Raise `requestTimeoutMs` for large objects, or check connectivity to the bucket.",
@@ -178,7 +197,7 @@ export class GcsDriver implements StorageDriver {
178
197
  const buf = await this.get(filePath);
179
198
  if (buf === null) {
180
199
  throw new ArchiveError(
181
- "ARCHIVE_NOT_FOUND",
200
+ "E_ARCHIVE_NOT_FOUND",
182
201
  `GCS object does not exist at path '${filePath}'`,
183
202
  {
184
203
  hint: "Confirm the bucket + key and that the object was put() first.",
@@ -218,7 +237,7 @@ export class GcsDriver implements StorageDriver {
218
237
 
219
238
  async get(filePath: string): Promise<Buffer | null> {
220
239
  const token = await this.#getAccessToken();
221
- const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}?alt=media`;
240
+ const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeObjectName(filePath)}?alt=media`;
222
241
  const res = await this.#fetch(url, {
223
242
  method: "GET",
224
243
  headers: { authorization: `Bearer ${token}` },
@@ -230,14 +249,14 @@ export class GcsDriver implements StorageDriver {
230
249
 
231
250
  async getStream(filePath: string): Promise<NodeJS.ReadableStream> {
232
251
  const token = await this.#getAccessToken();
233
- const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}?alt=media`;
252
+ const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeObjectName(filePath)}?alt=media`;
234
253
  const res = await this.#fetch(url, {
235
254
  method: "GET",
236
255
  headers: { authorization: `Bearer ${token}` },
237
256
  });
238
257
  if (res.status === 404) {
239
258
  throw new ArchiveError(
240
- "ARCHIVE_NOT_FOUND",
259
+ "E_ARCHIVE_NOT_FOUND",
241
260
  `GCS object does not exist at path '${filePath}'`,
242
261
  {
243
262
  hint: "Confirm the bucket + key and that the object was put() first.",
@@ -251,7 +270,7 @@ export class GcsDriver implements StorageDriver {
251
270
 
252
271
  async delete(filePath: string): Promise<boolean> {
253
272
  const token = await this.#getAccessToken();
254
- const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}`;
273
+ const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeObjectName(filePath)}`;
255
274
  const res = await this.#fetch(url, {
256
275
  method: "DELETE",
257
276
  headers: { authorization: `Bearer ${token}` },
@@ -262,7 +281,7 @@ export class GcsDriver implements StorageDriver {
262
281
 
263
282
  async exists(filePath: string): Promise<boolean> {
264
283
  const token = await this.#getAccessToken();
265
- const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}`;
284
+ const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeObjectName(filePath)}`;
266
285
  const res = await this.#fetch(url, {
267
286
  method: "GET",
268
287
  headers: { authorization: `Bearer ${token}` },
@@ -292,14 +311,14 @@ export class GcsDriver implements StorageDriver {
292
311
 
293
312
  async getMetadata(filePath: string): Promise<Metadata> {
294
313
  const token = await this.#getAccessToken();
295
- const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}`;
314
+ const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeObjectName(filePath)}`;
296
315
  const res = await this.#fetch(url, {
297
316
  method: "GET",
298
317
  headers: { authorization: `Bearer ${token}` },
299
318
  });
300
319
  if (res.status === 404) {
301
320
  throw new ArchiveError(
302
- "ARCHIVE_NOT_FOUND",
321
+ "E_ARCHIVE_NOT_FOUND",
303
322
  `GCS object does not exist at path '${filePath}'`,
304
323
  { hint: "Confirm the bucket + key." },
305
324
  );
@@ -342,7 +361,7 @@ export class GcsDriver implements StorageDriver {
342
361
 
343
362
  async setVisibility(filePath: string, visibility: Visibility): Promise<void> {
344
363
  const token = await this.#getAccessToken();
345
- const base = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(filePath)}/acl`;
364
+ const base = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeObjectName(filePath)}/acl`;
346
365
  if (visibility === "public") {
347
366
  const res = await this.#fetch(base, {
348
367
  method: "POST",
@@ -373,14 +392,14 @@ export class GcsDriver implements StorageDriver {
373
392
 
374
393
  async copy(from: string, to: string, options?: WriteOptions): Promise<void> {
375
394
  const token = await this.#getAccessToken();
376
- const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeKey(from)}/copyTo/b/${this.#config.bucket}/o/${gcsEncodeKey(to)}`;
395
+ const url = `${GCS_META_ROOT}/b/${this.#config.bucket}/o/${gcsEncodeObjectName(from)}/copyTo/b/${this.#config.bucket}/o/${gcsEncodeObjectName(to)}`;
377
396
  const res = await this.#fetch(url, {
378
397
  method: "POST",
379
398
  headers: { authorization: `Bearer ${token}` },
380
399
  });
381
400
  if (res.status === 404) {
382
401
  throw new ArchiveError(
383
- "ARCHIVE_NOT_FOUND",
402
+ "E_ARCHIVE_NOT_FOUND",
384
403
  `GCS copy source does not exist at path '${from}'`,
385
404
  { hint: "Confirm the source object was put() first." },
386
405
  );
package/src/S3Driver.ts CHANGED
@@ -91,7 +91,7 @@ export class S3Driver implements StorageDriver {
91
91
  } catch (err) {
92
92
  if (err instanceof Error && err.name === "TimeoutError") {
93
93
  throw new ArchiveError(
94
- "ARCHIVE_REQUEST_TIMEOUT",
94
+ "E_ARCHIVE_REQUEST_TIMEOUT",
95
95
  `The storage provider did not answer within ${ms}ms.`,
96
96
  {
97
97
  hint: "Raise `requestTimeoutMs` for large objects, or check connectivity to the bucket.",
@@ -236,7 +236,7 @@ export class S3Driver implements StorageDriver {
236
236
  const res = await this.#fetch(url, { method: "GET", headers });
237
237
  if (res.status === 404) {
238
238
  throw new ArchiveError(
239
- "ARCHIVE_NOT_FOUND",
239
+ "E_ARCHIVE_NOT_FOUND",
240
240
  `S3 object does not exist at path '${filePath}'`,
241
241
  {
242
242
  hint: "Confirm the bucket + key and that the object was put() first.",
@@ -273,7 +273,7 @@ export class S3Driver implements StorageDriver {
273
273
  const res = await this.#fetch(url, { method: "GET", headers });
274
274
  if (res.status === 404) {
275
275
  throw new ArchiveError(
276
- "ARCHIVE_NOT_FOUND",
276
+ "E_ARCHIVE_NOT_FOUND",
277
277
  `S3 object does not exist at path '${filePath}'`,
278
278
  {
279
279
  hint: "Confirm the bucket + key and that the object was put() first.",
@@ -325,7 +325,7 @@ export class S3Driver implements StorageDriver {
325
325
  });
326
326
  if (headRes.status === 404) {
327
327
  throw new ArchiveError(
328
- "ARCHIVE_NOT_FOUND",
328
+ "E_ARCHIVE_NOT_FOUND",
329
329
  `S3 object does not exist at path '${filePath}'`,
330
330
  {
331
331
  hint: "Confirm the bucket + key and that the object was put() first.",
@@ -394,7 +394,7 @@ export class S3Driver implements StorageDriver {
394
394
  });
395
395
  if (aclRes.status === 404) {
396
396
  throw new ArchiveError(
397
- "ARCHIVE_NOT_FOUND",
397
+ "E_ARCHIVE_NOT_FOUND",
398
398
  `S3 object does not exist at path '${filePath}'`,
399
399
  { hint: "Confirm the bucket + key." },
400
400
  );
@@ -547,7 +547,7 @@ export class S3Driver implements StorageDriver {
547
547
  const body = await res.text();
548
548
  if (/\bNoSuchKey\b/.test(body) || res.status === 404) {
549
549
  throw new ArchiveError(
550
- "ARCHIVE_NOT_FOUND",
550
+ "E_ARCHIVE_NOT_FOUND",
551
551
  `S3 copy source does not exist at path '${from}'`,
552
552
  { hint: "Confirm the source object was put() first." },
553
553
  );
@@ -158,12 +158,12 @@ export interface StorageDriver {
158
158
  get(filePath: string): Promise<Buffer | null>;
159
159
  /**
160
160
  * Contents as a `Uint8Array`. AdonisJS Drive parity. Throws
161
- * `ARCHIVE_NOT_FOUND` when the object is absent (unlike {@link get},
161
+ * `E_ARCHIVE_NOT_FOUND` when the object is absent (unlike {@link get},
162
162
  * a byte accessor can't express absence as a value).
163
163
  */
164
164
  getBytes(filePath: string): Promise<Uint8Array>;
165
165
  /**
166
- * Download as a readable stream. Throws `ARCHIVE_NOT_FOUND` when
166
+ * Download as a readable stream. Throws `E_ARCHIVE_NOT_FOUND` when
167
167
  * the object is missing — streams can't express absence as a value.
168
168
  */
169
169
  getStream(filePath: string): Promise<NodeJS.ReadableStream>;
@@ -185,7 +185,7 @@ export interface StorageDriver {
185
185
  * Return a time-boxed URL that grants read access to `filePath`.
186
186
  * Implementations must validate `options.expiresIn` via
187
187
  * {@link assertValidExpiry} and reject out-of-range values with
188
- * `ARCHIVE_INVALID_EXPIRY`.
188
+ * `E_ARCHIVE_INVALID_EXPIRY`.
189
189
  */
190
190
  getSignedUrl(
191
191
  filePath: string,
@@ -195,14 +195,14 @@ export interface StorageDriver {
195
195
  * Return a time-boxed URL that grants **write** (PUT) access, letting
196
196
  * a client upload directly to the backend. AdonisJS Drive parity.
197
197
  * Cloud-only — the LocalDriver has no presigned-upload equivalent and
198
- * throws `ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED`.
198
+ * throws `E_ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED`.
199
199
  */
200
200
  getSignedUploadUrl(
201
201
  filePath: string,
202
202
  options?: SignedUrlOptions,
203
203
  ): string | Promise<string>;
204
204
  /**
205
- * Resolve object metadata. Throws `ArchiveError('ARCHIVE_NOT_FOUND', ...)`
205
+ * Resolve object metadata. Throws `ArchiveError('E_ARCHIVE_NOT_FOUND', ...)`
206
206
  * when the object does not exist.
207
207
  */
208
208
  getMetadata(filePath: string): Promise<Metadata>;
@@ -217,7 +217,7 @@ export interface StorageDriver {
217
217
  */
218
218
  setVisibility(filePath: string, visibility: Visibility): Promise<void>;
219
219
  /**
220
- * Duplicate an object. Throws `ARCHIVE_NOT_FOUND` if `from` is
220
+ * Duplicate an object. Throws `E_ARCHIVE_NOT_FOUND` if `from` is
221
221
  * missing. Target is overwritten if it exists. Visibility is NOT
222
222
  * carried over unless `options.visibility` is passed — the new object
223
223
  * takes default visibility.
@@ -255,7 +255,7 @@ export interface LocalDriverOptions {
255
255
  /**
256
256
  * HMAC-SHA256 secret used by {@link LocalDriver.getSignedUrl}.
257
257
  * When omitted, signing is disabled and `getSignedUrl` throws
258
- * `ARCHIVE_SIGNING_DISABLED`. The non-signing methods
258
+ * `E_ARCHIVE_SIGNING_DISABLED`. The non-signing methods
259
259
  * (`put`/`get`/`delete`/`exists`/`url`) work either way.
260
260
  */
261
261
  signingSecret?: string;
@@ -280,7 +280,7 @@ export class LocalDriver implements StorageDriver {
280
280
  // values without being annoyingly strict about format.
281
281
  if (typeof secret !== "string" || secret.length < 16) {
282
282
  throw new ArchiveError(
283
- "ARCHIVE_WEAK_SIGNING_SECRET",
283
+ "E_ARCHIVE_WEAK_SIGNING_SECRET",
284
284
  `LocalDriver signingSecret must be a string of at least 16 chars (got length ${typeof secret === "string" ? secret.length : "non-string"})`,
285
285
  {
286
286
  hint: "Use a cryptographically random secret, e.g. `crypto.randomBytes(32).toString('hex')`.",
@@ -363,7 +363,7 @@ export class LocalDriver implements StorageDriver {
363
363
  const buf = await this.get(filePath);
364
364
  if (buf === null) {
365
365
  throw new ArchiveError(
366
- "ARCHIVE_NOT_FOUND",
366
+ "E_ARCHIVE_NOT_FOUND",
367
367
  `File does not exist at path '${filePath}'`,
368
368
  { hint: "Confirm the path and that the file was put() first." },
369
369
  );
@@ -398,7 +398,7 @@ export class LocalDriver implements StorageDriver {
398
398
  const full = this.#safePath(filePath);
399
399
  if (!fs.existsSync(full)) {
400
400
  throw new ArchiveError(
401
- "ARCHIVE_NOT_FOUND",
401
+ "E_ARCHIVE_NOT_FOUND",
402
402
  `File does not exist at path '${filePath}'`,
403
403
  { hint: "Confirm the path and that the file was put() first." },
404
404
  );
@@ -456,7 +456,7 @@ export class LocalDriver implements StorageDriver {
456
456
  } catch (err) {
457
457
  if ((err as NodeJS.ErrnoException).code === "ENOENT") {
458
458
  throw new ArchiveError(
459
- "ARCHIVE_NOT_FOUND",
459
+ "E_ARCHIVE_NOT_FOUND",
460
460
  `File does not exist at path '${filePath}'`,
461
461
  { hint: "Confirm the path and that the file was put() first." },
462
462
  );
@@ -490,7 +490,7 @@ export class LocalDriver implements StorageDriver {
490
490
  const full = this.#safePath(filePath);
491
491
  if (!fs.existsSync(full)) {
492
492
  throw new ArchiveError(
493
- "ARCHIVE_NOT_FOUND",
493
+ "E_ARCHIVE_NOT_FOUND",
494
494
  `Cannot set visibility — file does not exist at path '${filePath}'`,
495
495
  { hint: "put() the file before calling setVisibility()." },
496
496
  );
@@ -516,7 +516,7 @@ export class LocalDriver implements StorageDriver {
516
516
  raw = fs.readFileSync(sidecar, "utf8");
517
517
  } catch (err) {
518
518
  throw new ArchiveError(
519
- "ARCHIVE_VISIBILITY_CORRUPT",
519
+ "E_ARCHIVE_VISIBILITY_CORRUPT",
520
520
  `Failed to read visibility sidecar for '${filePath}' (${(err as NodeJS.ErrnoException).code ?? "I/O error"}); refusing to default to 'public'.`,
521
521
  {
522
522
  hint: "Inspect the sidecar file or re-apply visibility via setVisibility().",
@@ -528,7 +528,7 @@ export class LocalDriver implements StorageDriver {
528
528
  parsed = JSON.parse(raw) as { visibility?: unknown };
529
529
  } catch {
530
530
  throw new ArchiveError(
531
- "ARCHIVE_VISIBILITY_CORRUPT",
531
+ "E_ARCHIVE_VISIBILITY_CORRUPT",
532
532
  `Sidecar for '${filePath}' is not valid JSON; refusing to default to 'public'.`,
533
533
  {
534
534
  hint: "Delete the sidecar file and re-apply visibility via setVisibility().",
@@ -548,7 +548,7 @@ export class LocalDriver implements StorageDriver {
548
548
  const secret = this.#signingSecret;
549
549
  if (secret === null) {
550
550
  throw new ArchiveError(
551
- "ARCHIVE_SIGNING_DISABLED",
551
+ "E_ARCHIVE_SIGNING_DISABLED",
552
552
  "LocalDriver.getSignedUrl requires a signingSecret at construction time",
553
553
  {
554
554
  hint: "Pass { signingSecret: <hex or random string> } to the LocalDriver constructor, or set config.archive.local.signingSecret. Private files require a signing secret.",
@@ -571,7 +571,7 @@ export class LocalDriver implements StorageDriver {
571
571
  */
572
572
  getSignedUploadUrl(_filePath: string, _options?: SignedUrlOptions): string {
573
573
  throw new ArchiveError(
574
- "ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED",
574
+ "E_ARCHIVE_SIGNED_UPLOAD_UNSUPPORTED",
575
575
  "LocalDriver does not support presigned upload URLs",
576
576
  {
577
577
  hint: "Presigned uploads are an S3/GCS feature. For local storage, upload through your app's HTTP handler.",
@@ -592,7 +592,7 @@ export class LocalDriver implements StorageDriver {
592
592
  const toFull = this.#safePath(to);
593
593
  if (!fs.existsSync(fromFull)) {
594
594
  throw new ArchiveError(
595
- "ARCHIVE_NOT_FOUND",
595
+ "E_ARCHIVE_NOT_FOUND",
596
596
  `Cannot copy — source does not exist at path '${from}'`,
597
597
  { hint: "Confirm the source path was put() first." },
598
598
  );
@@ -612,7 +612,7 @@ export class LocalDriver implements StorageDriver {
612
612
  const toFull = this.#safePath(to);
613
613
  if (!fs.existsSync(fromFull)) {
614
614
  throw new ArchiveError(
615
- "ARCHIVE_NOT_FOUND",
615
+ "E_ARCHIVE_NOT_FOUND",
616
616
  `Cannot move — source does not exist at path '${from}'`,
617
617
  { hint: "Confirm the source path was put() first." },
618
618
  );
@@ -655,7 +655,7 @@ export class LocalDriver implements StorageDriver {
655
655
  );
656
656
  } catch (err) {
657
657
  throw new ArchiveError(
658
- "ARCHIVE_VISIBILITY_MOVE_FAILED",
658
+ "E_ARCHIVE_VISIBILITY_MOVE_FAILED",
659
659
  `move('${from}' -> '${to}'): main file moved but visibility sidecar write failed (${(err as NodeJS.ErrnoException).code ?? "unknown"}). Target visibility is undefined.`,
660
660
  {
661
661
  hint: "Re-apply visibility via setVisibility() on the target path.",
@@ -890,7 +890,7 @@ export class StorageManager {
890
890
  return this.#driver.get(filePath);
891
891
  }
892
892
 
893
- /** Contents as a `Uint8Array`. Throws `ARCHIVE_NOT_FOUND` if absent. */
893
+ /** Contents as a `Uint8Array`. Throws `E_ARCHIVE_NOT_FOUND` if absent. */
894
894
  getBytes(filePath: string): Promise<Uint8Array> {
895
895
  return this.#driver.getBytes(filePath);
896
896
  }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * `ream configure @c9up/archive` — wire file storage in one command.
3
+ *
4
+ * The provider alone is not enough: it reads `config/archive.ts`, and a package
5
+ * registered without one falls back to a default that is rarely the one an
6
+ * application wants. Writing both together is what makes `ream add` mean
7
+ * installed AND working.
8
+ */
9
+
10
+ interface Codemods {
11
+ addProvider(importPath: string): Promise<void>;
12
+ addEnvVars(vars: Record<string, string>): Promise<void>;
13
+ writeFile(
14
+ filePath: string,
15
+ content: string,
16
+ options?: { force?: boolean },
17
+ ): Promise<void>;
18
+ }
19
+
20
+ export async function configure(codemods: Codemods): Promise<void> {
21
+ // The config below reads these, so they are declared here. Writing the file
22
+ // without them leaves an application whose config asks the environment for
23
+ // something nothing ever put there.
24
+ await codemods.addEnvVars({
25
+ DRIVE_DISK: "fs",
26
+ });
27
+
28
+ await codemods.addProvider("@c9up/archive/provider");
29
+ await codemods.writeFile(
30
+ "config/archive.ts",
31
+ `import { defineConfig, services } from '@c9up/archive'
32
+ import env from '#start/env'
33
+
34
+ export default defineConfig({
35
+ // The disk used when \`drive.use()\` is called with no argument.
36
+ default: env.get('DRIVE_DISK', 'fs'),
37
+
38
+ services: {
39
+ fs: services.fs({
40
+ location: 'storage/uploads',
41
+ // Required before \`getSignedUrl\` will answer on the local disk.
42
+ signingSecret: env.get('APP_KEY'),
43
+ }),
44
+ // s3: services.s3({ bucket: env.get('S3_BUCKET'), region: env.get('S3_REGION') }),
45
+ },
46
+ })`,
47
+ );
48
+ }
package/src/expiry.ts CHANGED
@@ -45,7 +45,7 @@ const UNIT_SECONDS: Record<string, number> = {
45
45
  * Normalise a signed-URL `expiresIn` into a number of seconds. Accepts
46
46
  * either a raw number of seconds (returned as-is) or a human-friendly
47
47
  * duration string such as `'30mins'`, `'7 days'`, `'1h'` — AdonisJS
48
- * Drive parity. Unrecognised strings throw `ARCHIVE_INVALID_EXPIRY`.
48
+ * Drive parity. Unrecognised strings throw `E_ARCHIVE_INVALID_EXPIRY`.
49
49
  */
50
50
  export function parseExpiry(expiresIn: number | string): number {
51
51
  if (typeof expiresIn === "number") return expiresIn;
@@ -54,7 +54,7 @@ export function parseExpiry(expiresIn: number | string): number {
54
54
  const multiplier = unitKey === "" ? 1 : UNIT_SECONDS[unitKey];
55
55
  if (match === undefined || match === null || multiplier === undefined) {
56
56
  throw new ArchiveError(
57
- "ARCHIVE_INVALID_EXPIRY",
57
+ "E_ARCHIVE_INVALID_EXPIRY",
58
58
  `Signed-URL expiresIn string '${expiresIn}' could not be parsed`,
59
59
  {
60
60
  hint: "Use a number of seconds, or a duration like '30mins', '1h', '7 days'.",
@@ -66,26 +66,26 @@ export function parseExpiry(expiresIn: number | string): number {
66
66
 
67
67
  /**
68
68
  * Reject non-finite, zero, negative, or out-of-range expiries. Throws
69
- * `ARCHIVE_INVALID_EXPIRY` so callers get a typed error with a hint.
69
+ * `E_ARCHIVE_INVALID_EXPIRY` so callers get a typed error with a hint.
70
70
  */
71
71
  export function assertValidExpiry(expiresIn: number): void {
72
72
  if (!Number.isFinite(expiresIn)) {
73
73
  throw new ArchiveError(
74
- "ARCHIVE_INVALID_EXPIRY",
74
+ "E_ARCHIVE_INVALID_EXPIRY",
75
75
  `Signed-URL expiresIn must be finite, got ${expiresIn}`,
76
76
  { hint: "Pass a positive number of seconds between 1 and 604800." },
77
77
  );
78
78
  }
79
79
  if (expiresIn <= 0) {
80
80
  throw new ArchiveError(
81
- "ARCHIVE_INVALID_EXPIRY",
81
+ "E_ARCHIVE_INVALID_EXPIRY",
82
82
  `Signed-URL expiresIn must be > 0 seconds, got ${expiresIn}`,
83
83
  { hint: "Pass a positive number of seconds between 1 and 604800." },
84
84
  );
85
85
  }
86
86
  if (expiresIn > MAX_EXPIRES_IN) {
87
87
  throw new ArchiveError(
88
- "ARCHIVE_INVALID_EXPIRY",
88
+ "E_ARCHIVE_INVALID_EXPIRY",
89
89
  `Signed-URL expiresIn must be <= ${MAX_EXPIRES_IN} seconds (7 days), got ${expiresIn}`,
90
90
  { hint: "AWS SigV4 caps presigned URLs at 7 days." },
91
91
  );
@@ -75,7 +75,7 @@ export class FakeStorage implements StorageDriver {
75
75
  const obj = this.#store.get(filePath);
76
76
  if (!obj) {
77
77
  throw new ArchiveError(
78
- "ARCHIVE_NOT_FOUND",
78
+ "E_ARCHIVE_NOT_FOUND",
79
79
  `Fake object does not exist at path '${filePath}'`,
80
80
  { hint: "put() it first, or verify the test setup." },
81
81
  );
@@ -114,7 +114,7 @@ export class FakeStorage implements StorageDriver {
114
114
  const obj = this.#store.get(filePath);
115
115
  if (!obj) {
116
116
  throw new ArchiveError(
117
- "ARCHIVE_NOT_FOUND",
117
+ "E_ARCHIVE_NOT_FOUND",
118
118
  `Fake object does not exist at path '${filePath}'`,
119
119
  { hint: "put() it first, or verify the test setup." },
120
120
  );
@@ -164,7 +164,7 @@ export class FakeStorage implements StorageDriver {
164
164
  const obj = this.#store.get(filePath);
165
165
  if (!obj) {
166
166
  throw new ArchiveError(
167
- "ARCHIVE_NOT_FOUND",
167
+ "E_ARCHIVE_NOT_FOUND",
168
168
  `Fake object does not exist at path '${filePath}'`,
169
169
  { hint: "put() it first, or verify the test setup." },
170
170
  );
@@ -176,7 +176,7 @@ export class FakeStorage implements StorageDriver {
176
176
  const obj = this.#store.get(filePath);
177
177
  if (!obj) {
178
178
  throw new ArchiveError(
179
- "ARCHIVE_NOT_FOUND",
179
+ "E_ARCHIVE_NOT_FOUND",
180
180
  `Fake object does not exist at path '${filePath}'`,
181
181
  { hint: "put() it first, or verify the test setup." },
182
182
  );
@@ -199,7 +199,7 @@ export class FakeStorage implements StorageDriver {
199
199
  const obj = this.#store.get(filePath);
200
200
  if (!obj) {
201
201
  throw new ArchiveError(
202
- "ARCHIVE_NOT_FOUND",
202
+ "E_ARCHIVE_NOT_FOUND",
203
203
  `Cannot set visibility — fake object does not exist at path '${filePath}'`,
204
204
  { hint: "put() the file before calling setVisibility()." },
205
205
  );
@@ -211,7 +211,7 @@ export class FakeStorage implements StorageDriver {
211
211
  const src = this.#store.get(from);
212
212
  if (!src) {
213
213
  throw new ArchiveError(
214
- "ARCHIVE_NOT_FOUND",
214
+ "E_ARCHIVE_NOT_FOUND",
215
215
  `Cannot copy — fake source does not exist at path '${from}'`,
216
216
  { hint: "Confirm the source path was put() first." },
217
217
  );
@@ -230,7 +230,7 @@ export class FakeStorage implements StorageDriver {
230
230
  const src = this.#store.get(from);
231
231
  if (!src) {
232
232
  throw new ArchiveError(
233
- "ARCHIVE_NOT_FOUND",
233
+ "E_ARCHIVE_NOT_FOUND",
234
234
  `Cannot move — fake source does not exist at path '${from}'`,
235
235
  { hint: "Confirm the source path was put() first." },
236
236
  );