disk 0.8.12 → 0.8.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/dist/index.d.cts CHANGED
@@ -1475,6 +1475,84 @@ interface GrepOptions {
1475
1475
  */
1476
1476
  maxResults?: number;
1477
1477
  }
1478
+ interface ShareUrlOptions {
1479
+ /**
1480
+ * Lifetime of the URL in seconds — any positive integer, up to 604800
1481
+ * (7 days). Defaults to 86400 (24 hours).
1482
+ */
1483
+ expiresIn?: number;
1484
+ }
1485
+ interface ShareUrlResult {
1486
+ /** Public, signed, time-limited URL that downloads the file. */
1487
+ url: string;
1488
+ /** Lifetime of the URL in seconds. */
1489
+ expiresIn: number;
1490
+ }
1491
+ interface ListObjectsOptions {
1492
+ /**
1493
+ * List the entire subtree under the prefix. When false (the default), only
1494
+ * the immediate level is returned — direct objects in `objects` and
1495
+ * subdirectory prefixes in `commonPrefixes`, like listing a single directory.
1496
+ * When true, every key under the prefix is returned flat (and
1497
+ * `commonPrefixes` is empty).
1498
+ */
1499
+ recursive?: boolean;
1500
+ /**
1501
+ * Return only the first page instead of auto-paginating. By default
1502
+ * listObjects follows continuation tokens until the listing is exhausted and
1503
+ * returns every matching key. With `singlePage: true` it makes one request
1504
+ * and the result carries `isTruncated` / `nextContinuationToken` so you can
1505
+ * page manually (pass the token back via `continuationToken`).
1506
+ */
1507
+ singlePage?: boolean;
1508
+ /**
1509
+ * Stop after this many objects total (only meaningful when auto-paginating).
1510
+ * The result's `isTruncated` is true if the cap cut the listing short.
1511
+ */
1512
+ limit?: number;
1513
+ /** Start listing from this continuation token (from a prior `nextContinuationToken`). */
1514
+ continuationToken?: string;
1515
+ /** Return keys lexicographically after this one. */
1516
+ startAfter?: string;
1517
+ }
1518
+ interface S3Object {
1519
+ /** Object key (path on the disk). */
1520
+ key: string;
1521
+ /** Size in bytes. */
1522
+ size: number;
1523
+ /** Entity tag (quoted MD5 for single-part objects). */
1524
+ etag?: string;
1525
+ /** Last-modified time, if reported by the server. */
1526
+ lastModified?: Date;
1527
+ }
1528
+ interface PutObjectResult {
1529
+ /** Entity tag the server assigned (quoted, per S3 — e.g. `"\"abc123\""`). */
1530
+ etag?: string;
1531
+ }
1532
+ interface ObjectMetadata {
1533
+ /** Size in bytes. */
1534
+ size: number;
1535
+ /** Entity tag (quoted MD5 for single-part objects). */
1536
+ etag?: string;
1537
+ /** MIME type the object was stored with, if any. */
1538
+ contentType?: string;
1539
+ /** Last-modified time, if reported by the server. */
1540
+ lastModified?: Date;
1541
+ }
1542
+ interface ListObjectsResult {
1543
+ /** Objects in this page. */
1544
+ objects: S3Object[];
1545
+ /** Directory-like prefixes rolled up by `delimiter` (empty if no delimiter). */
1546
+ commonPrefixes: string[];
1547
+ /** True if more keys exist beyond this page. */
1548
+ isTruncated: boolean;
1549
+ /** Token to pass as `continuationToken` to fetch the next page. */
1550
+ nextContinuationToken?: string;
1551
+ /** Number of keys returned in this page. */
1552
+ keyCount: number;
1553
+ /** The prefix the listing was filtered by, echoed back by the server. */
1554
+ prefix?: string;
1555
+ }
1478
1556
  declare class Disk {
1479
1557
  readonly id: string;
1480
1558
  readonly name: string;
@@ -1496,8 +1574,10 @@ declare class Disk {
1496
1574
  private readonly _client;
1497
1575
  /** @internal */
1498
1576
  private readonly _archilRegion;
1577
+ /** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
1578
+ private readonly _s3BaseUrl;
1499
1579
  /** @internal */
1500
- constructor(data: DiskResponse, client: ApiClient, archilRegion: string);
1580
+ constructor(data: DiskResponse, client: ApiClient, archilRegion: string, s3BaseUrl?: string);
1501
1581
  toJSON(): DiskResponse;
1502
1582
  addUser(user: DiskUser): Promise<AuthorizedUser>;
1503
1583
  removeUser(userType: "token" | "awssts", identifier: string): Promise<void>;
@@ -1527,6 +1607,97 @@ declare class Disk {
1527
1607
  * reported first), not the lexicographically first N.
1528
1608
  */
1529
1609
  grep(opts: GrepOptions): Promise<GrepResult>;
1610
+ /**
1611
+ * Create a signed, time-limited URL that lets anyone download a single file
1612
+ * from this disk without authentication. The returned URL embeds a
1613
+ * cryptographically signed token carrying the disk, the file's key, and an
1614
+ * expiry — share it directly; no API key is needed to redeem it.
1615
+ *
1616
+ * @param key Path to the file on the disk (e.g. "reports/2026-01/data.pdf").
1617
+ * @param opts `expiresIn` sets the URL lifetime in seconds (any positive
1618
+ * integer, max 604800 = 7 days). Defaults to 24h.
1619
+ */
1620
+ share(key: string, opts?: ShareUrlOptions): Promise<ShareUrlResult>;
1621
+ /**
1622
+ * Read an object from the disk via the S3-compatible GetObject API and return
1623
+ * its full contents as bytes. Throws `ArchilS3Error` if the object does not
1624
+ * exist (status 404, code "NoSuchKey") or the request is rejected; use
1625
+ * `headObject`/`objectExists` to check existence without throwing.
1626
+ *
1627
+ * @param key Path on the disk (e.g. "reports/2026-01/data.json")
1628
+ */
1629
+ getObject(key: string): Promise<Uint8Array>;
1630
+ /**
1631
+ * Fetch an object's metadata (size, etag, content type, last-modified) without
1632
+ * downloading its contents, via the S3-compatible HeadObject API. Returns
1633
+ * `null` if the object does not exist.
1634
+ *
1635
+ * @param key Path on the disk (e.g. "reports/2026-01/data.json")
1636
+ */
1637
+ headObject(key: string): Promise<ObjectMetadata | null>;
1638
+ /** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
1639
+ objectExists(key: string): Promise<boolean>;
1640
+ /**
1641
+ * Write an object to the disk using the S3-compatible PutObject API. Faster
1642
+ * than exec for large files — no container overhead, no command-length limits.
1643
+ * Returns the entity tag the server assigned.
1644
+ *
1645
+ * @param key Path on the disk (e.g. "reports/2026-01/data.json")
1646
+ * @param body Contents as a string, Uint8Array/Buffer, or ArrayBuffer
1647
+ * @param contentType MIME type (default: "application/octet-stream")
1648
+ */
1649
+ putObject(key: string, body: string | Uint8Array | ArrayBuffer, contentType?: string): Promise<PutObjectResult>;
1650
+ /**
1651
+ * Delete an object from the disk via the S3-compatible DeleteObject API.
1652
+ * Idempotent: deleting a key that doesn't exist resolves successfully, per
1653
+ * S3 semantics.
1654
+ *
1655
+ * @param key Path on the disk (e.g. "project/dist/server.cjs")
1656
+ */
1657
+ deleteObject(key: string): Promise<void>;
1658
+ /**
1659
+ * List objects on the disk via the S3-compatible ListObjectsV2 API. By
1660
+ * default this follows continuation tokens until the listing is exhausted and
1661
+ * returns every matching key. Use `limit` to cap the total, `singlePage` for a
1662
+ * single request, or {@link listObjectsPages} to stream pages without loading
1663
+ * everything into memory.
1664
+ *
1665
+ * @param prefix Only return keys beginning with this prefix (omit for all).
1666
+ * @param opts Listing and pagination options.
1667
+ */
1668
+ listObjects(prefix?: string, opts?: ListObjectsOptions): Promise<ListObjectsResult>;
1669
+ /**
1670
+ * Yield ListObjectsV2 pages lazily, following continuation tokens. A
1671
+ * memory-friendly way to process a large listing without materializing it:
1672
+ *
1673
+ * ```ts
1674
+ * for await (const page of disk.listObjectsPages("logs/")) {
1675
+ * for (const obj of page.objects) process(obj);
1676
+ * }
1677
+ * ```
1678
+ *
1679
+ * @param prefix Only return keys beginning with this prefix (omit for all).
1680
+ * @param opts Listing options (`limit` / `singlePage` are ignored here —
1681
+ * control your own loop).
1682
+ */
1683
+ listObjectsPages(prefix?: string, opts?: ListObjectsOptions): AsyncGenerator<ListObjectsResult>;
1684
+ /** Fetch a single ListObjectsV2 page. @internal */
1685
+ private _listObjectsPage;
1686
+ /**
1687
+ * Send a single request to the disk's S3-compatible endpoint. This reuses the
1688
+ * control-plane client purely for its credential and transport — the same
1689
+ * `Authorization` header is sent and verified by the same code server-side —
1690
+ * pointed at the S3 host. Returns the response status and fully-buffered body
1691
+ * so callers can inspect both regardless of the verb used.
1692
+ *
1693
+ * The S3 routes (`/{diskId}/{key}` for objects, `/{diskId}` for the bucket)
1694
+ * are not part of the typed control-plane API, so the path and per-request
1695
+ * options are passed untyped. An empty `key` targets the bucket itself (used
1696
+ * by listObjects).
1697
+ *
1698
+ * @internal
1699
+ */
1700
+ private _s3Request;
1530
1701
  /**
1531
1702
  * Connect to this disk's data plane via the native ArchilClient.
1532
1703
  *
@@ -1552,7 +1723,9 @@ declare class Disks {
1552
1723
  /** @internal */
1553
1724
  private readonly _region;
1554
1725
  /** @internal */
1555
- constructor(client: ApiClient, region: string);
1726
+ private readonly _s3BaseUrl?;
1727
+ /** @internal */
1728
+ constructor(client: ApiClient, region: string, s3BaseUrl?: string);
1556
1729
  list(opts?: ListDisksOptions): Promise<Disk[]>;
1557
1730
  get(id: string): Promise<Disk>;
1558
1731
  /**
@@ -1587,6 +1760,12 @@ interface ArchilOptions {
1587
1760
  region?: string;
1588
1761
  /** Override the control plane base URL (useful for testing). */
1589
1762
  baseUrl?: string;
1763
+ /**
1764
+ * Override the S3-compatible API base URL used by Disk#getObject /
1765
+ * putObject / deleteObject. Falls back to ARCHIL_S3_BASE_URL, then to the
1766
+ * control plane URL with its `control.` hostname prefix swapped for `s3.`.
1767
+ */
1768
+ s3BaseUrl?: string;
1590
1769
  }
1591
1770
  /**
1592
1771
  * Options that apply to a single mounted disk in an exec request.
@@ -1641,11 +1820,46 @@ declare class Archil {
1641
1820
  exec(opts: ExecOptions): Promise<ExecDiskResult>;
1642
1821
  }
1643
1822
 
1644
- declare class ArchilApiError extends Error {
1823
+ /**
1824
+ * Base class for every error the SDK throws. Catch with `instanceof ArchilError`
1825
+ * to handle control-plane and S3 failures uniformly; `status` is the HTTP status
1826
+ * code and `code` a machine-readable error code when the server provided one.
1827
+ */
1828
+ declare class ArchilError extends Error {
1829
+ /** HTTP status code associated with the failure. */
1645
1830
  readonly status: number;
1831
+ /** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
1646
1832
  readonly code?: string;
1647
1833
  constructor(message: string, status: number, code?: string);
1648
1834
  }
1835
+ /** Error from the control-plane REST API. */
1836
+ declare class ArchilApiError extends ArchilError {
1837
+ constructor(message: string, status: number, code?: string);
1838
+ }
1839
+ /**
1840
+ * Error from the S3-compatible object API (getObject/putObject/deleteObject/
1841
+ * headObject/listObjects). The gateway returns an S3-style XML `<Error>` body;
1842
+ * this surfaces its parts as structured fields (`status`, `code`, `requestId`)
1843
+ * rather than a raw blob, while keeping the full body on `raw` for debugging.
1844
+ */
1845
+ declare class ArchilS3Error extends ArchilError {
1846
+ /** S3 request id, if the gateway returned one. */
1847
+ readonly requestId?: string;
1848
+ /** Raw response body (the XML document), for debugging. */
1849
+ readonly raw: string;
1850
+ constructor(opts: {
1851
+ operation: string;
1852
+ statusCode: number;
1853
+ statusText?: string;
1854
+ code?: string;
1855
+ message?: string;
1856
+ requestId?: string;
1857
+ raw: string;
1858
+ });
1859
+ }
1860
+
1861
+ declare const VERSION: string;
1862
+ declare const USER_AGENT: string;
1649
1863
 
1650
1864
  declare function configure(options: ArchilOptions): void;
1651
1865
  declare function createDisk(req: CreateDiskRequest): Promise<CreateDiskResult>;
@@ -1663,4 +1877,4 @@ declare function deleteApiKey(id: string): Promise<void>;
1663
1877
  */
1664
1878
  declare function exec(opts: ExecOptions): Promise<ExecDiskResult>;
1665
1879
 
1666
- export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };
1880
+ export { type ApiTokenResponse, Archil, ArchilApiError, ArchilError, type ArchilOptions, ArchilS3Error, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListObjectsOptions, type ListObjectsResult, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type ObjectMetadata, type PutObjectResult, type R2Mount, type S3CompatibleMount, type S3Mount, type S3Object, type ShareUrlOptions, type ShareUrlResult, type TokenUser, Tokens, USER_AGENT, VERSION, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };
package/dist/index.d.ts CHANGED
@@ -1475,6 +1475,84 @@ interface GrepOptions {
1475
1475
  */
1476
1476
  maxResults?: number;
1477
1477
  }
1478
+ interface ShareUrlOptions {
1479
+ /**
1480
+ * Lifetime of the URL in seconds — any positive integer, up to 604800
1481
+ * (7 days). Defaults to 86400 (24 hours).
1482
+ */
1483
+ expiresIn?: number;
1484
+ }
1485
+ interface ShareUrlResult {
1486
+ /** Public, signed, time-limited URL that downloads the file. */
1487
+ url: string;
1488
+ /** Lifetime of the URL in seconds. */
1489
+ expiresIn: number;
1490
+ }
1491
+ interface ListObjectsOptions {
1492
+ /**
1493
+ * List the entire subtree under the prefix. When false (the default), only
1494
+ * the immediate level is returned — direct objects in `objects` and
1495
+ * subdirectory prefixes in `commonPrefixes`, like listing a single directory.
1496
+ * When true, every key under the prefix is returned flat (and
1497
+ * `commonPrefixes` is empty).
1498
+ */
1499
+ recursive?: boolean;
1500
+ /**
1501
+ * Return only the first page instead of auto-paginating. By default
1502
+ * listObjects follows continuation tokens until the listing is exhausted and
1503
+ * returns every matching key. With `singlePage: true` it makes one request
1504
+ * and the result carries `isTruncated` / `nextContinuationToken` so you can
1505
+ * page manually (pass the token back via `continuationToken`).
1506
+ */
1507
+ singlePage?: boolean;
1508
+ /**
1509
+ * Stop after this many objects total (only meaningful when auto-paginating).
1510
+ * The result's `isTruncated` is true if the cap cut the listing short.
1511
+ */
1512
+ limit?: number;
1513
+ /** Start listing from this continuation token (from a prior `nextContinuationToken`). */
1514
+ continuationToken?: string;
1515
+ /** Return keys lexicographically after this one. */
1516
+ startAfter?: string;
1517
+ }
1518
+ interface S3Object {
1519
+ /** Object key (path on the disk). */
1520
+ key: string;
1521
+ /** Size in bytes. */
1522
+ size: number;
1523
+ /** Entity tag (quoted MD5 for single-part objects). */
1524
+ etag?: string;
1525
+ /** Last-modified time, if reported by the server. */
1526
+ lastModified?: Date;
1527
+ }
1528
+ interface PutObjectResult {
1529
+ /** Entity tag the server assigned (quoted, per S3 — e.g. `"\"abc123\""`). */
1530
+ etag?: string;
1531
+ }
1532
+ interface ObjectMetadata {
1533
+ /** Size in bytes. */
1534
+ size: number;
1535
+ /** Entity tag (quoted MD5 for single-part objects). */
1536
+ etag?: string;
1537
+ /** MIME type the object was stored with, if any. */
1538
+ contentType?: string;
1539
+ /** Last-modified time, if reported by the server. */
1540
+ lastModified?: Date;
1541
+ }
1542
+ interface ListObjectsResult {
1543
+ /** Objects in this page. */
1544
+ objects: S3Object[];
1545
+ /** Directory-like prefixes rolled up by `delimiter` (empty if no delimiter). */
1546
+ commonPrefixes: string[];
1547
+ /** True if more keys exist beyond this page. */
1548
+ isTruncated: boolean;
1549
+ /** Token to pass as `continuationToken` to fetch the next page. */
1550
+ nextContinuationToken?: string;
1551
+ /** Number of keys returned in this page. */
1552
+ keyCount: number;
1553
+ /** The prefix the listing was filtered by, echoed back by the server. */
1554
+ prefix?: string;
1555
+ }
1478
1556
  declare class Disk {
1479
1557
  readonly id: string;
1480
1558
  readonly name: string;
@@ -1496,8 +1574,10 @@ declare class Disk {
1496
1574
  private readonly _client;
1497
1575
  /** @internal */
1498
1576
  private readonly _archilRegion;
1577
+ /** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
1578
+ private readonly _s3BaseUrl;
1499
1579
  /** @internal */
1500
- constructor(data: DiskResponse, client: ApiClient, archilRegion: string);
1580
+ constructor(data: DiskResponse, client: ApiClient, archilRegion: string, s3BaseUrl?: string);
1501
1581
  toJSON(): DiskResponse;
1502
1582
  addUser(user: DiskUser): Promise<AuthorizedUser>;
1503
1583
  removeUser(userType: "token" | "awssts", identifier: string): Promise<void>;
@@ -1527,6 +1607,97 @@ declare class Disk {
1527
1607
  * reported first), not the lexicographically first N.
1528
1608
  */
1529
1609
  grep(opts: GrepOptions): Promise<GrepResult>;
1610
+ /**
1611
+ * Create a signed, time-limited URL that lets anyone download a single file
1612
+ * from this disk without authentication. The returned URL embeds a
1613
+ * cryptographically signed token carrying the disk, the file's key, and an
1614
+ * expiry — share it directly; no API key is needed to redeem it.
1615
+ *
1616
+ * @param key Path to the file on the disk (e.g. "reports/2026-01/data.pdf").
1617
+ * @param opts `expiresIn` sets the URL lifetime in seconds (any positive
1618
+ * integer, max 604800 = 7 days). Defaults to 24h.
1619
+ */
1620
+ share(key: string, opts?: ShareUrlOptions): Promise<ShareUrlResult>;
1621
+ /**
1622
+ * Read an object from the disk via the S3-compatible GetObject API and return
1623
+ * its full contents as bytes. Throws `ArchilS3Error` if the object does not
1624
+ * exist (status 404, code "NoSuchKey") or the request is rejected; use
1625
+ * `headObject`/`objectExists` to check existence without throwing.
1626
+ *
1627
+ * @param key Path on the disk (e.g. "reports/2026-01/data.json")
1628
+ */
1629
+ getObject(key: string): Promise<Uint8Array>;
1630
+ /**
1631
+ * Fetch an object's metadata (size, etag, content type, last-modified) without
1632
+ * downloading its contents, via the S3-compatible HeadObject API. Returns
1633
+ * `null` if the object does not exist.
1634
+ *
1635
+ * @param key Path on the disk (e.g. "reports/2026-01/data.json")
1636
+ */
1637
+ headObject(key: string): Promise<ObjectMetadata | null>;
1638
+ /** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
1639
+ objectExists(key: string): Promise<boolean>;
1640
+ /**
1641
+ * Write an object to the disk using the S3-compatible PutObject API. Faster
1642
+ * than exec for large files — no container overhead, no command-length limits.
1643
+ * Returns the entity tag the server assigned.
1644
+ *
1645
+ * @param key Path on the disk (e.g. "reports/2026-01/data.json")
1646
+ * @param body Contents as a string, Uint8Array/Buffer, or ArrayBuffer
1647
+ * @param contentType MIME type (default: "application/octet-stream")
1648
+ */
1649
+ putObject(key: string, body: string | Uint8Array | ArrayBuffer, contentType?: string): Promise<PutObjectResult>;
1650
+ /**
1651
+ * Delete an object from the disk via the S3-compatible DeleteObject API.
1652
+ * Idempotent: deleting a key that doesn't exist resolves successfully, per
1653
+ * S3 semantics.
1654
+ *
1655
+ * @param key Path on the disk (e.g. "project/dist/server.cjs")
1656
+ */
1657
+ deleteObject(key: string): Promise<void>;
1658
+ /**
1659
+ * List objects on the disk via the S3-compatible ListObjectsV2 API. By
1660
+ * default this follows continuation tokens until the listing is exhausted and
1661
+ * returns every matching key. Use `limit` to cap the total, `singlePage` for a
1662
+ * single request, or {@link listObjectsPages} to stream pages without loading
1663
+ * everything into memory.
1664
+ *
1665
+ * @param prefix Only return keys beginning with this prefix (omit for all).
1666
+ * @param opts Listing and pagination options.
1667
+ */
1668
+ listObjects(prefix?: string, opts?: ListObjectsOptions): Promise<ListObjectsResult>;
1669
+ /**
1670
+ * Yield ListObjectsV2 pages lazily, following continuation tokens. A
1671
+ * memory-friendly way to process a large listing without materializing it:
1672
+ *
1673
+ * ```ts
1674
+ * for await (const page of disk.listObjectsPages("logs/")) {
1675
+ * for (const obj of page.objects) process(obj);
1676
+ * }
1677
+ * ```
1678
+ *
1679
+ * @param prefix Only return keys beginning with this prefix (omit for all).
1680
+ * @param opts Listing options (`limit` / `singlePage` are ignored here —
1681
+ * control your own loop).
1682
+ */
1683
+ listObjectsPages(prefix?: string, opts?: ListObjectsOptions): AsyncGenerator<ListObjectsResult>;
1684
+ /** Fetch a single ListObjectsV2 page. @internal */
1685
+ private _listObjectsPage;
1686
+ /**
1687
+ * Send a single request to the disk's S3-compatible endpoint. This reuses the
1688
+ * control-plane client purely for its credential and transport — the same
1689
+ * `Authorization` header is sent and verified by the same code server-side —
1690
+ * pointed at the S3 host. Returns the response status and fully-buffered body
1691
+ * so callers can inspect both regardless of the verb used.
1692
+ *
1693
+ * The S3 routes (`/{diskId}/{key}` for objects, `/{diskId}` for the bucket)
1694
+ * are not part of the typed control-plane API, so the path and per-request
1695
+ * options are passed untyped. An empty `key` targets the bucket itself (used
1696
+ * by listObjects).
1697
+ *
1698
+ * @internal
1699
+ */
1700
+ private _s3Request;
1530
1701
  /**
1531
1702
  * Connect to this disk's data plane via the native ArchilClient.
1532
1703
  *
@@ -1552,7 +1723,9 @@ declare class Disks {
1552
1723
  /** @internal */
1553
1724
  private readonly _region;
1554
1725
  /** @internal */
1555
- constructor(client: ApiClient, region: string);
1726
+ private readonly _s3BaseUrl?;
1727
+ /** @internal */
1728
+ constructor(client: ApiClient, region: string, s3BaseUrl?: string);
1556
1729
  list(opts?: ListDisksOptions): Promise<Disk[]>;
1557
1730
  get(id: string): Promise<Disk>;
1558
1731
  /**
@@ -1587,6 +1760,12 @@ interface ArchilOptions {
1587
1760
  region?: string;
1588
1761
  /** Override the control plane base URL (useful for testing). */
1589
1762
  baseUrl?: string;
1763
+ /**
1764
+ * Override the S3-compatible API base URL used by Disk#getObject /
1765
+ * putObject / deleteObject. Falls back to ARCHIL_S3_BASE_URL, then to the
1766
+ * control plane URL with its `control.` hostname prefix swapped for `s3.`.
1767
+ */
1768
+ s3BaseUrl?: string;
1590
1769
  }
1591
1770
  /**
1592
1771
  * Options that apply to a single mounted disk in an exec request.
@@ -1641,11 +1820,46 @@ declare class Archil {
1641
1820
  exec(opts: ExecOptions): Promise<ExecDiskResult>;
1642
1821
  }
1643
1822
 
1644
- declare class ArchilApiError extends Error {
1823
+ /**
1824
+ * Base class for every error the SDK throws. Catch with `instanceof ArchilError`
1825
+ * to handle control-plane and S3 failures uniformly; `status` is the HTTP status
1826
+ * code and `code` a machine-readable error code when the server provided one.
1827
+ */
1828
+ declare class ArchilError extends Error {
1829
+ /** HTTP status code associated with the failure. */
1645
1830
  readonly status: number;
1831
+ /** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
1646
1832
  readonly code?: string;
1647
1833
  constructor(message: string, status: number, code?: string);
1648
1834
  }
1835
+ /** Error from the control-plane REST API. */
1836
+ declare class ArchilApiError extends ArchilError {
1837
+ constructor(message: string, status: number, code?: string);
1838
+ }
1839
+ /**
1840
+ * Error from the S3-compatible object API (getObject/putObject/deleteObject/
1841
+ * headObject/listObjects). The gateway returns an S3-style XML `<Error>` body;
1842
+ * this surfaces its parts as structured fields (`status`, `code`, `requestId`)
1843
+ * rather than a raw blob, while keeping the full body on `raw` for debugging.
1844
+ */
1845
+ declare class ArchilS3Error extends ArchilError {
1846
+ /** S3 request id, if the gateway returned one. */
1847
+ readonly requestId?: string;
1848
+ /** Raw response body (the XML document), for debugging. */
1849
+ readonly raw: string;
1850
+ constructor(opts: {
1851
+ operation: string;
1852
+ statusCode: number;
1853
+ statusText?: string;
1854
+ code?: string;
1855
+ message?: string;
1856
+ requestId?: string;
1857
+ raw: string;
1858
+ });
1859
+ }
1860
+
1861
+ declare const VERSION: string;
1862
+ declare const USER_AGENT: string;
1649
1863
 
1650
1864
  declare function configure(options: ArchilOptions): void;
1651
1865
  declare function createDisk(req: CreateDiskRequest): Promise<CreateDiskResult>;
@@ -1663,4 +1877,4 @@ declare function deleteApiKey(id: string): Promise<void>;
1663
1877
  */
1664
1878
  declare function exec(opts: ExecOptions): Promise<ExecDiskResult>;
1665
1879
 
1666
- export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };
1880
+ export { type ApiTokenResponse, Archil, ArchilApiError, ArchilError, type ArchilOptions, ArchilS3Error, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, type CreateDiskResult, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type ExecMount, type ExecMountSpec, type ExecOptions, type ExecRequest, type ExecResult, type GCSMount, type GrepMatch, type GrepOptions, type GrepResult, type GrepStoppedReason, type ListDisksOptions, type ListObjectsOptions, type ListObjectsResult, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type ObjectMetadata, type PutObjectResult, type R2Mount, type S3CompatibleMount, type S3Mount, type S3Object, type ShareUrlOptions, type ShareUrlResult, type TokenUser, Tokens, USER_AGENT, VERSION, configure, createApiKey, createDisk, deleteApiKey, exec, getDisk, listApiKeys, listDisks };