disk 0.8.12 → 0.8.13

package/dist/index.cjs

@@ -32,9 +32,13 @@ var index_exports = {};
 __export(index_exports, {
   Archil: () => Archil,
   ArchilApiError: () => ArchilApiError,
+  ArchilError: () => ArchilError,
+  ArchilS3Error: () => ArchilS3Error,
   Disk: () => Disk,
   Disks: () => Disks,
   Tokens: () => Tokens,
+  USER_AGENT: () => USER_AGENT,
+  VERSION: () => VERSION,
   configure: () => configure,
   createApiKey: () => createApiKey,
   createDisk: () => createDisk,
@@ -49,17 +53,77 @@ module.exports = __toCommonJS(index_exports);
 // src/client.ts
 var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
 
+// src/s3xml.ts
+var import_fast_xml_parser = require("fast-xml-parser");
+var parser = new import_fast_xml_parser.XMLParser({
+  isArray: (name) => name === "Contents" || name === "CommonPrefixes",
+  parseTagValue: false,
+  trimValues: true,
+  ignoreAttributes: true
+});
+function parseXml(xml) {
+  if (!xml.trim()) return {};
+  return parser.parse(xml);
+}
+
 // src/errors.ts
-var ArchilApiError = class extends Error {
+var ArchilError = class extends Error {
+  /** HTTP status code associated with the failure. */
   status;
+  /** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
   code;
   constructor(message, status, code) {
     super(message);
-    this.name = "ArchilApiError";
+    this.name = "ArchilError";
     this.status = status;
     this.code = code;
   }
 };
+var ArchilApiError = class extends ArchilError {
+  constructor(message, status, code) {
+    super(message, status, code);
+    this.name = "ArchilApiError";
+  }
+};
+var ArchilS3Error = class extends ArchilError {
+  /** S3 request id, if the gateway returned one. */
+  requestId;
+  /** Raw response body (the XML document), for debugging. */
+  raw;
+  constructor(opts) {
+    const detail = opts.message ?? opts.statusText ?? "";
+    const codePart = opts.code ? ` ${opts.code}` : "";
+    super(
+      `S3 ${opts.operation} failed: ${opts.statusCode}${codePart}${detail ? ` \u2014 ${detail}` : ""}`,
+      opts.statusCode,
+      opts.code
+    );
+    this.name = "ArchilS3Error";
+    this.requestId = opts.requestId;
+    this.raw = opts.raw;
+  }
+};
+function tagString(obj, tag) {
+  const value = obj[tag];
+  return value === void 0 || value === null ? void 0 : String(value);
+}
+function parseS3Error(operation, statusCode, statusText, body) {
+  let err = {};
+  try {
+    err = parseXml(body).Error ?? {};
+  } catch {
+    err = {};
+  }
+  return new ArchilS3Error({
+    operation,
+    statusCode,
+    statusText,
+    code: tagString(err, "Code"),
+    message: tagString(err, "Message"),
+    requestId: tagString(err, "RequestId"),
+    raw: body
+  });
+}
 
 // src/regions.ts
 var REGION_URLS = {
@@ -77,14 +141,32 @@ function resolveBaseUrl(region) {
   }
   return url;
 }
+function deriveS3BaseUrl(controlBaseUrl) {
+  try {
+    const u = new URL(controlBaseUrl);
+    u.hostname = u.hostname.replace(/^control\./, "s3.");
+    return u.toString().replace(/\/$/, "");
+  } catch {
+    return void 0;
+  }
+}
+
+// src/version.ts
+var VERSION = true ? "0.8.13" : "0.0.0-dev";
+var USER_AGENT = `archil-js/${VERSION}`;
 
 // src/client.ts
+var createClient = typeof import_openapi_fetch.default === "function" ? import_openapi_fetch.default : import_openapi_fetch.default.default;
 function createApiClient(opts) {
   const baseUrl = opts.baseUrl ?? resolveBaseUrl(opts.region);
-  return (0, import_openapi_fetch.default)({
+  return createClient({
     baseUrl,
     headers: {
-      Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`
+      Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`,
+      // Identifies the JS SDK (and its version) to the control plane. Honored
+      // by Node's fetch; browsers treat User-Agent as a forbidden header and
+      // drop it, which is fine — the SDK's primary use is server-side.
+      "User-Agent": USER_AGENT
     }
   });
 }
@@ -123,9 +205,6 @@ async function unwrapEmpty(promise) {
 }
 
 // src/disk.ts
-var import_node_module = require("module");
-var import_node_url = require("url");
-var import_meta = {};
 var Disk = class {
   id;
   name;
@@ -147,8 +226,10 @@ var Disk = class {
   _client;
   /** @internal */
   _archilRegion;
+  /** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
+  _s3BaseUrl;
   /** @internal */
-  constructor(data, client, archilRegion) {
+  constructor(data, client, archilRegion, s3BaseUrl) {
     this.id = data.id;
     this.name = data.name;
     this.organization = data.organization;
@@ -167,6 +248,7 @@ var Disk = class {
     this.allowedIps = data.allowedIps;
     this._client = client;
     this._archilRegion = archilRegion;
+    this._s3BaseUrl = s3BaseUrl ?? "";
   }
   toJSON() {
     return {
@@ -291,6 +373,219 @@ var Disk = class {
       })
     );
   }
+  /**
+   * Create a signed, time-limited URL that lets anyone download a single file
+   * from this disk without authentication. The returned URL embeds a
+   * cryptographically signed token carrying the disk, the file's key, and an
+   * expiry — share it directly; no API key is needed to redeem it.
+   *
+   * @param key   Path to the file on the disk (e.g. "reports/2026-01/data.pdf").
+   * @param opts  `expiresIn` sets the URL lifetime in seconds (any positive
+   *              integer, max 604800 = 7 days). Defaults to 24h.
+   */
+  async share(key, opts = {}) {
+    const body = { key };
+    if (opts.expiresIn !== void 0) body.expiresIn = opts.expiresIn;
+    const call = this._client.POST;
+    return unwrap(call(`/api/disks/${this.id}/share`, { body }));
+  }
+  /**
+   * Read an object from the disk via the S3-compatible GetObject API and return
+   * its full contents as bytes. Throws `ArchilS3Error` if the object does not
+   * exist (status 404, code "NoSuchKey") or the request is rejected; use
+   * `headObject`/`objectExists` to check existence without throwing.
+   *
+   * @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+   */
+  async getObject(key) {
+    const resp = await this._s3Request("GET", key);
+    if (!resp.ok) {
+      throw parseS3Error("GetObject", resp.status, resp.statusText, decodeText(resp.body));
+    }
+    return resp.body;
+  }
+  /**
+   * Fetch an object's metadata (size, etag, content type, last-modified) without
+   * downloading its contents, via the S3-compatible HeadObject API. Returns
+   * `null` if the object does not exist.
+   *
+   * @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+   */
+  async headObject(key) {
+    const resp = await this._s3Request("HEAD", key);
+    if (resp.status === 404) return null;
+    if (!resp.ok) {
+      throw parseS3Error("HeadObject", resp.status, resp.statusText, decodeText(resp.body));
+    }
+    const lastModified = resp.headers.get("last-modified");
+    return {
+      size: Number(resp.headers.get("content-length") ?? 0),
+      etag: resp.headers.get("etag") ?? void 0,
+      contentType: resp.headers.get("content-type") ?? void 0,
+      lastModified: lastModified ? new Date(lastModified) : void 0
+    };
+  }
+  /** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
+  async objectExists(key) {
+    return await this.headObject(key) !== null;
+  }
+  /**
+   * Write an object to the disk using the S3-compatible PutObject API. Faster
+   * than exec for large files — no container overhead, no command-length limits.
+   * Returns the entity tag the server assigned.
+   *
+   * @param key          Path on the disk (e.g. "reports/2026-01/data.json")
+   * @param body         Contents as a string, Uint8Array/Buffer, or ArrayBuffer
+   * @param contentType  MIME type (default: "application/octet-stream")
+   */
+  async putObject(key, body, contentType = "application/octet-stream") {
+    const resp = await this._s3Request("PUT", key, { body, contentType });
+    if (!resp.ok) {
+      throw parseS3Error("PutObject", resp.status, resp.statusText, decodeText(resp.body));
+    }
+    return { etag: resp.headers.get("etag") ?? void 0 };
+  }
+  /**
+   * Delete an object from the disk via the S3-compatible DeleteObject API.
+   * Idempotent: deleting a key that doesn't exist resolves successfully, per
+   * S3 semantics.
+   *
+   * @param key  Path on the disk (e.g. "project/dist/server.cjs")
+   */
+  async deleteObject(key) {
+    const resp = await this._s3Request("DELETE", key);
+    if (!resp.ok && resp.status !== 404) {
+      throw parseS3Error("DeleteObject", resp.status, resp.statusText, decodeText(resp.body));
+    }
+  }
+  /**
+   * List objects on the disk via the S3-compatible ListObjectsV2 API. By
+   * default this follows continuation tokens until the listing is exhausted and
+   * returns every matching key. Use `limit` to cap the total, `singlePage` for a
+   * single request, or {@link listObjectsPages} to stream pages without loading
+   * everything into memory.
+   *
+   * @param prefix  Only return keys beginning with this prefix (omit for all).
+   * @param opts    Listing and pagination options.
+   */
+  async listObjects(prefix, opts = {}) {
+    if (opts.singlePage) {
+      return this._listObjectsPage(prefix, opts);
+    }
+    const objects = [];
+    const commonPrefixes = [];
+    const seenPrefixes = /* @__PURE__ */ new Set();
+    let echoedPrefix;
+    let truncated = false;
+    outer: for await (const page of this.listObjectsPages(prefix, opts)) {
+      echoedPrefix = page.prefix;
+      for (const cp of page.commonPrefixes) {
+        if (!seenPrefixes.has(cp)) {
+          seenPrefixes.add(cp);
+          commonPrefixes.push(cp);
+        }
+      }
+      for (const obj of page.objects) {
+        if (opts.limit !== void 0 && objects.length >= opts.limit) {
+          truncated = true;
+          break outer;
+        }
+        objects.push(obj);
+      }
+    }
+    return { objects, commonPrefixes, isTruncated: truncated, keyCount: objects.length, prefix: echoedPrefix };
+  }
+  /**
+   * Yield ListObjectsV2 pages lazily, following continuation tokens. A
+   * memory-friendly way to process a large listing without materializing it:
+   *
+   * ```ts
+   * for await (const page of disk.listObjectsPages("logs/")) {
+   *   for (const obj of page.objects) process(obj);
+   * }
+   * ```
+   *
+   * @param prefix  Only return keys beginning with this prefix (omit for all).
+   * @param opts    Listing options (`limit` / `singlePage` are ignored here —
+   *                control your own loop).
+   */
+  async *listObjectsPages(prefix, opts = {}) {
+    const seenTokens = /* @__PURE__ */ new Set();
+    let continuationToken = opts.continuationToken;
+    for (; ; ) {
+      const page = await this._listObjectsPage(prefix, { ...opts, continuationToken });
+      yield page;
+      const next = page.isTruncated ? page.nextContinuationToken : void 0;
+      if (!next || seenTokens.has(next)) break;
+      seenTokens.add(next);
+      continuationToken = next;
+    }
+  }
+  /** Fetch a single ListObjectsV2 page. @internal */
+  async _listObjectsPage(prefix, opts) {
+    const query = { "list-type": 2 };
+    if (prefix !== void 0) query.prefix = prefix;
+    if (!opts.recursive) query.delimiter = "/";
+    if (opts.continuationToken !== void 0) query["continuation-token"] = opts.continuationToken;
+    if (opts.startAfter !== void 0) query["start-after"] = opts.startAfter;
+    const resp = await this._s3Request("GET", "", { query });
+    if (!resp.ok) {
+      throw parseS3Error("ListObjectsV2", resp.status, resp.statusText, decodeText(resp.body));
+    }
+    return parseListObjectsResult(decodeText(resp.body));
+  }
+  /**
+   * Send a single request to the disk's S3-compatible endpoint. This reuses the
+   * control-plane client purely for its credential and transport — the same
+   * `Authorization` header is sent and verified by the same code server-side —
+   * pointed at the S3 host. Returns the response status and fully-buffered body
+   * so callers can inspect both regardless of the verb used.
+   *
+   * The S3 routes (`/{diskId}/{key}` for objects, `/{diskId}` for the bucket)
+   * are not part of the typed control-plane API, so the path and per-request
+   * options are passed untyped. An empty `key` targets the bucket itself (used
+   * by listObjects).
+   *
+   * @internal
+   */
+  async _s3Request(method, key, opts = {}) {
+    if (!this._s3BaseUrl) {
+      throw new Error(
+        "S3 base URL not configured. Pass s3BaseUrl to new Archil({...}) or set ARCHIL_S3_BASE_URL."
+      );
+    }
+    const call = this._client[method];
+    const trimmedKey = key.replace(/^\//, "");
+    const encodedKey = trimmedKey.split("/").map(encodeURIComponent).join("/");
+    const path = encodedKey ? `/${this.id}/${encodedKey}` : `/${this.id}`;
+    const { error, response } = await call(path, {
+      baseUrl: this._s3BaseUrl,
+      parseAs: "stream",
+      ...opts.query ? { params: { query: opts.query } } : {},
+      // fetch accepts string / Uint8Array / ArrayBuffer bodies directly; pass it
+      // through unchanged (no Node Buffer in the data path).
+      ...opts.body !== void 0 ? { body: opts.body, bodySerializer: (b) => b } : {},
+      ...opts.contentType ? { headers: { "Content-Type": opts.contentType } } : {}
+    });
+    if (!response.ok) {
+      const message = typeof error === "string" ? error : error ? JSON.stringify(error) : "";
+      return {
+        ok: false,
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        body: new TextEncoder().encode(message)
+      };
+    }
+    const bytes = method === "GET" ? new Uint8Array(await response.arrayBuffer()) : new Uint8Array(0);
+    return {
+      ok: true,
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+      body: bytes
+    };
+  }
   /**
    * Connect to this disk's data plane via the native ArchilClient.
    *
@@ -299,13 +594,15 @@ var Disk = class {
   async mount(opts) {
     let ArchilClient;
     try {
-      const base = typeof import_meta !== "undefined" && import_meta.url ? import_meta.url : (0, import_node_url.pathToFileURL)(__filename).href;
-      const nativeRequire = (0, import_node_module.createRequire)(base);
-      const native = nativeRequire("@archildata/native");
-      ArchilClient = native.ArchilClient;
+      const nativeSpecifier = "@archildata/native";
+      const native = await import(nativeSpecifier);
+      ArchilClient = native.ArchilClient ?? native.default?.ArchilClient;
+      if (!ArchilClient) {
+        throw new Error("@archildata/native did not export ArchilClient");
+      }
     } catch {
       throw new Error(
-        "Native client not available. Install @archildata/native (platform-specific binary) or use ArchilClient.connect() directly."
+        "Native client not available. Install @archildata/native (platform-specific binary) or use ArchilClient.connect() directly. mount() is not supported in browsers."
       );
     }
     return ArchilClient.connect({
@@ -318,6 +615,34 @@ var Disk = class {
     });
   }
 };
+function optionalString(value) {
+  return value === void 0 || value === null ? void 0 : String(value);
+}
+function optionalDate(value) {
+  return value === void 0 || value === null ? void 0 : new Date(String(value));
+}
+function decodeText(bytes) {
+  return new TextDecoder().decode(bytes);
+}
+function parseListObjectsResult(xml) {
+  const root = parseXml(xml).ListBucketResult ?? {};
+  const contents = root.Contents ?? [];
+  const objects = contents.map((c) => ({
+    key: String(c.Key ?? ""),
+    size: Number(c.Size ?? 0),
+    etag: optionalString(c.ETag),
+    lastModified: optionalDate(c.LastModified)
+  }));
+  const commonPrefixes = (root.CommonPrefixes ?? []).map((cp) => optionalString(cp.Prefix)).filter((p) => p !== void 0);
+  return {
+    objects,
+    commonPrefixes,
+    isTruncated: root.IsTruncated === "true" || root.IsTruncated === true,
+    nextContinuationToken: optionalString(root.NextContinuationToken),
+    keyCount: root.KeyCount !== void 0 ? Number(root.KeyCount) : objects.length,
+    prefix: optionalString(root.Prefix)
+  };
+}
 
 // src/disks.ts
 var Disks = class {
@@ -326,9 +651,12 @@ var Disks = class {
   /** @internal */
   _region;
   /** @internal */
-  constructor(client, region) {
+  _s3BaseUrl;
+  /** @internal */
+  constructor(client, region, s3BaseUrl) {
     this._client = client;
     this._region = region;
+    this._s3BaseUrl = s3BaseUrl;
   }
   async list(opts) {
     const data = await unwrap(
@@ -337,7 +665,7 @@ var Disks = class {
       })
     );
     return data.map(
-      (d) => new Disk(d, this._client, this._region)
+      (d) => new Disk(d, this._client, this._region, this._s3BaseUrl)
     );
   }
   async get(id) {
@@ -346,7 +674,7 @@ var Disks = class {
         params: { path: { id } }
       })
     );
-    return new Disk(data, this._client, this._region);
+    return new Disk(data, this._client, this._region, this._s3BaseUrl);
   }
   /**
    * Create a new disk with an auto-generated mount token.
@@ -406,6 +734,9 @@ var Tokens = class {
 };
 
 // src/archil.ts
+function envVar(name) {
+  return typeof process !== "undefined" && process.env ? process.env[name] : void 0;
+}
 function isExecMountSpec(m) {
   return typeof m === "object" && m !== null && "disk" in m;
 }
@@ -418,21 +749,23 @@ var Archil = class {
   /** @internal */
   _client;
   constructor(opts = {}) {
-    const apiKey = opts.apiKey ?? process.env.ARCHIL_API_KEY;
-    const region = opts.region ?? process.env.ARCHIL_REGION;
+    const apiKey = opts.apiKey ?? envVar("ARCHIL_API_KEY");
+    const region = opts.region ?? envVar("ARCHIL_REGION");
     if (!apiKey) {
       throw new Error("Missing API key: pass apiKey in options or set ARCHIL_API_KEY environment variable");
     }
     if (!region) {
       throw new Error("Missing region: pass region in options or set ARCHIL_REGION environment variable");
     }
+    const controlBaseUrl = opts.baseUrl ?? resolveBaseUrl(region);
     const client = createApiClient({
       apiKey,
       region,
-      baseUrl: opts.baseUrl
+      baseUrl: controlBaseUrl
     });
+    const s3BaseUrl = opts.s3BaseUrl ?? envVar("ARCHIL_S3_BASE_URL") ?? deriveS3BaseUrl(controlBaseUrl);
     this._client = client;
-    this.disks = new Disks(client, region);
+    this.disks = new Disks(client, region, s3BaseUrl);
     this.tokens = new Tokens(client);
   }
   /**
@@ -500,9 +833,13 @@ function exec(opts) {
 0 && (module.exports = {
   Archil,
   ArchilApiError,
+  ArchilError,
+  ArchilS3Error,
   Disk,
   Disks,
   Tokens,
+  USER_AGENT,
+  VERSION,
   configure,
   createApiKey,
   createDisk,