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/README.md +74 -0
- package/dist/cli.js +390 -22
- package/dist/index.cjs +357 -20
- package/dist/index.d.cts +218 -4
- package/dist/index.d.ts +218 -4
- package/dist/index.js +353 -19
- package/package.json +7 -4
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 };
|