@archildata/client 0.8.6 → 0.8.8

package/README.md

@@ -20,7 +20,7 @@ npm install @archildata/client
 
 An Archil "disk" is a filesystem that sits in front of your cloud storage. You create one by telling Archil which bucket to use. This doesn't move or copy your data — Archil reads and writes directly to your bucket.
 
-You also need to authorize a mount token on the disk. This is a separate credential from your API key — it's what clients use to connect to the disk's data plane. Pick any string as the principal (it's just an identifier).
+A mount token is automatically generated when you create a disk; it is recommended to save it.
 
 ```typescript
 import { Archil } from '@archildata/client/api';
@@ -30,25 +30,19 @@ const archil = new Archil({
   region: 'aws-us-east-1',
 });
 
-const MOUNT_TOKEN = 'my-secret-mount-token';
-
-const disk = await archil.disks.create({
+const { disk, token } = await archil.disks.create({
   name: 'my-disk',
   mounts: [{
     type: 's3',
     bucketName: 'my-bucket',
     accessKeyId: 'AKIA...',
     secretAccessKey: '...',
-  }],
-  authMethods: [{
-    type: 'token',
-    principal: MOUNT_TOKEN,
-    nickname: 'my-mount-token',
-    tokenSuffix: MOUNT_TOKEN.slice(-4),
+    bucketPrefix: 'data/',  // optional — only expose a subfolder of the bucket
   }],
 });
 
 console.log(`Created disk: ${disk.organization}/${disk.name}`);
+console.log(`Mount token: ${token}`);  // save this — it won't be shown again
 ```
 
 You only do this once. After that, the disk is available by name whenever you want to connect.
@@ -61,10 +55,10 @@ Install `@archildata/just-bash` to get a shell that runs against your disk:
 npm install @archildata/just-bash
 ```
 
-Then connect using the mount token you authorized above:
+Then connect using the mount token from step 3:
 
 ```bash
-ARCHIL_TOKEN=my-secret-mount-token npx @archildata/just-bash aws-us-east-1 myaccount/my-disk
+ARCHIL_DISK_TOKEN=<your-mount-token> npx @archildata/just-bash aws-us-east-1 myaccount/my-disk
 ```
 
 This drops you into an interactive shell. The files you see are the contents of your S3 bucket:
@@ -94,7 +88,7 @@ import { Bash } from 'just-bash';
 const client = await ArchilClient.connect({
   region: 'aws-us-east-1',
   diskName: 'myaccount/my-disk',
-  authToken: 'my-secret-mount-token',
+  authToken: '<your-mount-token>',
 });
 
 // Create a filesystem adapter and a bash executor
@@ -146,7 +140,7 @@ import { ArchilClient } from '@archildata/client';
 const client = await ArchilClient.connect({
   region: 'aws-us-east-1',
   diskName: 'myaccount/my-disk',
-  authToken: 'my-secret-mount-token',
+  authToken: '<your-mount-token>',
 });
 ```
 
@@ -254,17 +248,13 @@ const disks = await archil.disks.list();
 // Get a specific disk by ID
 const disk = await archil.disks.get('dsk-xxx');
 
-// Authorize another mount token on an existing disk
-const CI_TOKEN = 'ci-mount-token';
-await disk.addUser({
-  type: 'token',
-  principal: CI_TOKEN,
-  nickname: 'ci-token',
-  tokenSuffix: CI_TOKEN.slice(-4),
-});
+// Add an additional mount token to an existing disk
+const { token, identifier } = await disk.createToken('ci-token');
+// save `token` — it's only returned once
+// use `identifier` to manage or remove the token later
 
 // Remove access
-await disk.removeUser('token', CI_TOKEN);
+await disk.removeTokenUser(identifier);
 
 // Delete a disk (this does not delete your bucket data)
 await disk.delete();

package/dist/api/index.d.mts

@@ -21,8 +21,13 @@ interface paths {
         put?: never;
         /**
          * Create a new disk
-         * @description Creates a new disk with the specified configuration. The disk will be
-         *     provisioned in the specified region with the given mounts and authentication methods.
+         * @description Creates a new disk with the specified configuration. A default token
+         *     user is automatically generated and returned in the response, so the
+         *     disk is immediately mountable. The one-time token appears in
+         *     `authorizedUsers[].token` and cannot be retrieved again.
+         *
+         *     To provide your own users instead, pass the deprecated `authMethods`
+         *     field or call AddDiskUser after creation.
          */
         post: operations["createDisk"];
         delete?: never;
@@ -97,6 +102,28 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/disks/{id}/exec": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Execute a command on a disk
+         * @description Launches a container with the specified disk mounted, runs the given
+         *     command to completion, and shuts down the container. Returns immediately
+         *     with the container info; poll the container endpoint for completion.
+         */
+        post: operations["execDisk"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/tokens": {
         parameters: {
             query?: never;
@@ -170,7 +197,10 @@ interface components {
             name: string;
             /** @description Storage mount to attach. Omit for archil-managed storage. */
             mounts?: components["schemas"]["MountConfig"][];
-            /** @description Authentication methods for disk access */
+            /**
+             * @deprecated
+             * @description Deprecated. Use AddDiskUser after creation instead. When provided, suppresses the default auto-generated token user.
+             */
             authMethods?: components["schemas"]["DiskUser"][];
         };
         MountConfig: components["schemas"]["S3Mount"] | components["schemas"]["GCSMount"] | components["schemas"]["R2Mount"] | components["schemas"]["S3CompatibleMount"] | components["schemas"]["AzureBlobMount"];
@@ -344,9 +374,17 @@ interface components {
              * @enum {string}
              */
             type: "token";
-            principal: string;
+            /**
+             * @deprecated
+             * @description Deprecated. Client-provided token. If omitted, the server generates a cryptographically secure token and returns it in the response.
+             */
+            principal?: string;
             nickname: string;
-            tokenSuffix: string;
+            /**
+             * @deprecated
+             * @description Deprecated. Last 4 characters of the token. Required when principal is provided; ignored when the server generates the token.
+             */
+            tokenSuffix?: string;
         };
         AwsStsUser: {
             /**
@@ -461,10 +499,17 @@ interface components {
         AuthorizedUser: {
             /** @enum {string} */
             type?: "token" | "awssts";
-            /** @description The user's principal identifier. Only populated for awssts type (the IAM ARN). Omitted for token type users to avoid exposing sensitive hashes. */
+            /**
+             * @deprecated
+             * @description Use identifier instead. Only populated for awssts type (the IAM ARN).
+             */
             principal?: string;
             nickname?: string;
             tokenSuffix?: string;
+            /** @description The generated mount token. Only present in the response when the server generates the token (i.e. principal was not provided). This value is shown exactly once and cannot be retrieved again. */
+            token?: string;
+            /** @description Stable identifier for this user, returned in creation and list responses. Use this value with DELETE /api/disks/{id}/users/{type}?identifier={identifier} to remove the user. For awssts users, this is the IAM ARN. */
+            identifier?: string;
             /** Format: date-time */
             createdAt?: string;
         };
@@ -485,6 +530,7 @@ interface components {
             data: {
                 /** @example dsk-0123456789abcdef */
                 diskId?: string;
+                authorizedUsers?: components["schemas"]["AuthorizedUser"][];
             };
         };
         ApiResponse_AuthorizedUser: {
@@ -528,6 +574,29 @@ interface components {
                 token?: string;
             };
         };
+        ExecDiskRequest: {
+            /**
+             * @description Shell command to execute inside the container
+             * @example ls -la /mnt/archil
+             */
+            command: string;
+        };
+        ExecDiskResult: {
+            /**
+             * @description Exit code of the command (0 = success)
+             * @example 0
+             */
+            exitCode: number;
+            /** @description Standard output from the command */
+            stdout: string;
+            /** @description Standard error from the command */
+            stderr: string;
+        };
+        ApiResponse_ExecDisk: {
+            /** @example true */
+            success: boolean;
+            data: components["schemas"]["ExecDiskResult"];
+        };
     };
     responses: {
         /** @description Invalid or missing authentication credentials */
@@ -749,9 +818,14 @@ interface operations {
     };
     removeDiskUser: {
         parameters: {
-            query: {
-                /** @description The user's principal identifier. For token type, this is the MD5 hash (hex-encoded) of the token principal. For awssts type, this is the full IAM ARN (e.g., arn:aws:iam::123456789012:role/MyRole). */
-                principal: string;
+            query?: {
+                /** @description Identifier of the user to remove, as returned in the creation or list response. For awssts users, this is the IAM ARN. */
+                identifier?: string;
+                /**
+                 * @deprecated
+                 * @description Use identifier instead.
+                 */
+                principal?: string;
             };
             header?: never;
             path: {
@@ -778,6 +852,46 @@ interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    execDisk: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Disk ID (format `dsk-{16 hex chars}`) */
+                id: components["parameters"]["DiskId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ExecDiskRequest"];
+            };
+        };
+        responses: {
+            /** @description Command completed */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_ExecDisk"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+            /** @description Command timed out */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listApiTokens: {
         parameters: {
             query?: {
@@ -888,6 +1002,20 @@ interface MountOptions {
     serverAddress?: string;
     insecure?: boolean;
 }
+interface ExecTiming {
+    /** End-to-end wall-clock measured on the server (from request arrival to response). */
+    totalMs: number;
+    /** Time spent queueing, scheduling, booting/claiming a VM, and mounting the filesystem. */
+    queueMs: number;
+    /** Time the user's command itself ran, measured by the runtime. */
+    executeMs: number;
+}
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timing: ExecTiming;
+}
 declare class Disk {
     readonly id: string;
     readonly name: string;
@@ -911,8 +1039,18 @@ declare class Disk {
     /** @internal */
     constructor(data: DiskResponse, client: ApiClient, archilRegion: string);
     addUser(user: DiskUser): Promise<AuthorizedUser>;
-    removeUser(userType: "token" | "awssts", principal: string): Promise<void>;
+    removeUser(userType: "token" | "awssts", identifier: string): Promise<void>;
+    createToken(nickname: string): Promise<AuthorizedUser & {
+        token: string;
+        identifier: string;
+    }>;
+    removeTokenUser(identifier: string): Promise<void>;
     delete(): Promise<void>;
+    /**
+     * Execute a command in a container with this disk mounted.
+     * Blocks until the command completes and returns stdout, stderr, and exit code.
+     */
+    exec(command: string): Promise<ExecResult>;
     /**
      * Connect to this disk's data plane via the native ArchilClient.
      *
@@ -925,6 +1063,12 @@ interface ListDisksOptions {
     limit?: number;
     cursor?: string;
 }
+interface CreateDiskResult {
+    disk: Disk;
+    token: string | null;
+    tokenIdentifier: string | null;
+    authorizedUsers: AuthorizedUser[];
+}
 declare class Disks {
     /** @internal */
     private readonly _client;
@@ -935,11 +1079,12 @@ declare class Disks {
     list(opts?: ListDisksOptions): Promise<Disk[]>;
     get(id: string): Promise<Disk>;
     /**
-     * Create a new disk and return a Disk object with full details.
+     * Create a new disk with an auto-generated mount token.
      *
-     * Internally calls POST /api/disks (returns diskId) then GET /api/disks/{id}.
+     * Returns the Disk, the one-time token (save it — it cannot be retrieved
+     * again), and the token identifier for later management.
      */
-    create(req: CreateDiskRequest): Promise<Disk>;
+    create(req: CreateDiskRequest): Promise<CreateDiskResult>;
 }
 
 interface ListTokensOptions {
@@ -959,15 +1104,17 @@ declare class Tokens {
 }
 
 interface ArchilOptions {
-    apiKey: string;
-    region: string;
+    /** API key. Falls back to ARCHIL_API_KEY env var if not provided. */
+    apiKey?: string;
+    /** Region. Falls back to ARCHIL_REGION env var if not provided. */
+    region?: string;
     /** Override the control plane base URL (useful for testing). */
     baseUrl?: string;
 }
 declare class Archil {
     readonly disks: Disks;
     readonly tokens: Tokens;
-    constructor(opts: ArchilOptions);
+    constructor(opts?: ArchilOptions);
 }
 
 declare class ArchilApiError extends Error {
@@ -976,4 +1123,4 @@ declare class ArchilApiError extends Error {
     constructor(message: string, status: number, code?: string);
 }
 
-export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type GCSMount, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens };
+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 ExecResult, type GCSMount, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens };

package/dist/api/index.d.ts

@@ -21,8 +21,13 @@ interface paths {
         put?: never;
         /**
          * Create a new disk
-         * @description Creates a new disk with the specified configuration. The disk will be
-         *     provisioned in the specified region with the given mounts and authentication methods.
+         * @description Creates a new disk with the specified configuration. A default token
+         *     user is automatically generated and returned in the response, so the
+         *     disk is immediately mountable. The one-time token appears in
+         *     `authorizedUsers[].token` and cannot be retrieved again.
+         *
+         *     To provide your own users instead, pass the deprecated `authMethods`
+         *     field or call AddDiskUser after creation.
          */
         post: operations["createDisk"];
         delete?: never;
@@ -97,6 +102,28 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/disks/{id}/exec": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Execute a command on a disk
+         * @description Launches a container with the specified disk mounted, runs the given
+         *     command to completion, and shuts down the container. Returns immediately
+         *     with the container info; poll the container endpoint for completion.
+         */
+        post: operations["execDisk"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/tokens": {
         parameters: {
             query?: never;
@@ -170,7 +197,10 @@ interface components {
             name: string;
             /** @description Storage mount to attach. Omit for archil-managed storage. */
             mounts?: components["schemas"]["MountConfig"][];
-            /** @description Authentication methods for disk access */
+            /**
+             * @deprecated
+             * @description Deprecated. Use AddDiskUser after creation instead. When provided, suppresses the default auto-generated token user.
+             */
             authMethods?: components["schemas"]["DiskUser"][];
         };
         MountConfig: components["schemas"]["S3Mount"] | components["schemas"]["GCSMount"] | components["schemas"]["R2Mount"] | components["schemas"]["S3CompatibleMount"] | components["schemas"]["AzureBlobMount"];
@@ -344,9 +374,17 @@ interface components {
              * @enum {string}
              */
             type: "token";
-            principal: string;
+            /**
+             * @deprecated
+             * @description Deprecated. Client-provided token. If omitted, the server generates a cryptographically secure token and returns it in the response.
+             */
+            principal?: string;
             nickname: string;
-            tokenSuffix: string;
+            /**
+             * @deprecated
+             * @description Deprecated. Last 4 characters of the token. Required when principal is provided; ignored when the server generates the token.
+             */
+            tokenSuffix?: string;
         };
         AwsStsUser: {
             /**
@@ -461,10 +499,17 @@ interface components {
         AuthorizedUser: {
             /** @enum {string} */
             type?: "token" | "awssts";
-            /** @description The user's principal identifier. Only populated for awssts type (the IAM ARN). Omitted for token type users to avoid exposing sensitive hashes. */
+            /**
+             * @deprecated
+             * @description Use identifier instead. Only populated for awssts type (the IAM ARN).
+             */
             principal?: string;
             nickname?: string;
             tokenSuffix?: string;
+            /** @description The generated mount token. Only present in the response when the server generates the token (i.e. principal was not provided). This value is shown exactly once and cannot be retrieved again. */
+            token?: string;
+            /** @description Stable identifier for this user, returned in creation and list responses. Use this value with DELETE /api/disks/{id}/users/{type}?identifier={identifier} to remove the user. For awssts users, this is the IAM ARN. */
+            identifier?: string;
             /** Format: date-time */
             createdAt?: string;
         };
@@ -485,6 +530,7 @@ interface components {
             data: {
                 /** @example dsk-0123456789abcdef */
                 diskId?: string;
+                authorizedUsers?: components["schemas"]["AuthorizedUser"][];
             };
         };
         ApiResponse_AuthorizedUser: {
@@ -528,6 +574,29 @@ interface components {
                 token?: string;
             };
         };
+        ExecDiskRequest: {
+            /**
+             * @description Shell command to execute inside the container
+             * @example ls -la /mnt/archil
+             */
+            command: string;
+        };
+        ExecDiskResult: {
+            /**
+             * @description Exit code of the command (0 = success)
+             * @example 0
+             */
+            exitCode: number;
+            /** @description Standard output from the command */
+            stdout: string;
+            /** @description Standard error from the command */
+            stderr: string;
+        };
+        ApiResponse_ExecDisk: {
+            /** @example true */
+            success: boolean;
+            data: components["schemas"]["ExecDiskResult"];
+        };
     };
     responses: {
         /** @description Invalid or missing authentication credentials */
@@ -749,9 +818,14 @@ interface operations {
     };
     removeDiskUser: {
         parameters: {
-            query: {
-                /** @description The user's principal identifier. For token type, this is the MD5 hash (hex-encoded) of the token principal. For awssts type, this is the full IAM ARN (e.g., arn:aws:iam::123456789012:role/MyRole). */
-                principal: string;
+            query?: {
+                /** @description Identifier of the user to remove, as returned in the creation or list response. For awssts users, this is the IAM ARN. */
+                identifier?: string;
+                /**
+                 * @deprecated
+                 * @description Use identifier instead.
+                 */
+                principal?: string;
             };
             header?: never;
             path: {
@@ -778,6 +852,46 @@ interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    execDisk: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Disk ID (format `dsk-{16 hex chars}`) */
+                id: components["parameters"]["DiskId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ExecDiskRequest"];
+            };
+        };
+        responses: {
+            /** @description Command completed */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_ExecDisk"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+            /** @description Command timed out */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listApiTokens: {
         parameters: {
             query?: {
@@ -888,6 +1002,20 @@ interface MountOptions {
     serverAddress?: string;
     insecure?: boolean;
 }
+interface ExecTiming {
+    /** End-to-end wall-clock measured on the server (from request arrival to response). */
+    totalMs: number;
+    /** Time spent queueing, scheduling, booting/claiming a VM, and mounting the filesystem. */
+    queueMs: number;
+    /** Time the user's command itself ran, measured by the runtime. */
+    executeMs: number;
+}
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timing: ExecTiming;
+}
 declare class Disk {
     readonly id: string;
     readonly name: string;
@@ -911,8 +1039,18 @@ declare class Disk {
     /** @internal */
     constructor(data: DiskResponse, client: ApiClient, archilRegion: string);
     addUser(user: DiskUser): Promise<AuthorizedUser>;
-    removeUser(userType: "token" | "awssts", principal: string): Promise<void>;
+    removeUser(userType: "token" | "awssts", identifier: string): Promise<void>;
+    createToken(nickname: string): Promise<AuthorizedUser & {
+        token: string;
+        identifier: string;
+    }>;
+    removeTokenUser(identifier: string): Promise<void>;
     delete(): Promise<void>;
+    /**
+     * Execute a command in a container with this disk mounted.
+     * Blocks until the command completes and returns stdout, stderr, and exit code.
+     */
+    exec(command: string): Promise<ExecResult>;
     /**
      * Connect to this disk's data plane via the native ArchilClient.
      *
@@ -925,6 +1063,12 @@ interface ListDisksOptions {
     limit?: number;
     cursor?: string;
 }
+interface CreateDiskResult {
+    disk: Disk;
+    token: string | null;
+    tokenIdentifier: string | null;
+    authorizedUsers: AuthorizedUser[];
+}
 declare class Disks {
     /** @internal */
     private readonly _client;
@@ -935,11 +1079,12 @@ declare class Disks {
     list(opts?: ListDisksOptions): Promise<Disk[]>;
     get(id: string): Promise<Disk>;
     /**
-     * Create a new disk and return a Disk object with full details.
+     * Create a new disk with an auto-generated mount token.
      *
-     * Internally calls POST /api/disks (returns diskId) then GET /api/disks/{id}.
+     * Returns the Disk, the one-time token (save it — it cannot be retrieved
+     * again), and the token identifier for later management.
      */
-    create(req: CreateDiskRequest): Promise<Disk>;
+    create(req: CreateDiskRequest): Promise<CreateDiskResult>;
 }
 
 interface ListTokensOptions {
@@ -959,15 +1104,17 @@ declare class Tokens {
 }
 
 interface ArchilOptions {
-    apiKey: string;
-    region: string;
+    /** API key. Falls back to ARCHIL_API_KEY env var if not provided. */
+    apiKey?: string;
+    /** Region. Falls back to ARCHIL_REGION env var if not provided. */
+    region?: string;
     /** Override the control plane base URL (useful for testing). */
     baseUrl?: string;
 }
 declare class Archil {
     readonly disks: Disks;
     readonly tokens: Tokens;
-    constructor(opts: ArchilOptions);
+    constructor(opts?: ArchilOptions);
 }
 
 declare class ArchilApiError extends Error {
@@ -976,4 +1123,4 @@ declare class ArchilApiError extends Error {
     constructor(message: string, status: number, code?: string);
 }
 
-export { type ApiTokenResponse, Archil, ArchilApiError, type ArchilOptions, type AuthorizedUser, type AwsStsUser, type AzureBlobMount, type ConnectedClient, type CreateApiTokenRequest, type CreateDiskRequest, Disk, type DiskMetrics, type DiskResponse, type DiskStatus, type DiskUser, Disks, type GCSMount, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens };
+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 ExecResult, type GCSMount, type ListDisksOptions, type ListTokensOptions, type MountConfig, type MountConfigResponse, type MountOptions, type MountResponse, type R2Mount, type S3CompatibleMount, type S3Mount, type TokenUser, Tokens };

package/dist/api/index.js

@@ -76,7 +76,7 @@ function createApiClient(opts) {
   return (0, import_openapi_fetch.default)({
     baseUrl,
     headers: {
-      Authorization: `key-${opts.apiKey}`
+      Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`
     }
   });
 }
@@ -166,16 +166,31 @@ var Disk = class {
       })
     );
   }
-  async removeUser(userType, principal) {
+  async removeUser(userType, identifier) {
     await unwrapEmpty(
       this._client.DELETE("/api/disks/{id}/users/{userType}", {
         params: {
           path: { id: this.id, userType },
-          query: { principal }
+          query: { identifier }
         }
       })
     );
   }
+  async createToken(nickname) {
+    const user = await unwrap(
+      this._client.POST("/api/disks/{id}/users", {
+        params: { path: { id: this.id } },
+        body: { type: "token", nickname }
+      })
+    );
+    if (!user.token || !user.identifier) {
+      throw new Error("Server did not return a generated token");
+    }
+    return user;
+  }
+  async removeTokenUser(identifier) {
+    await this.removeUser("token", identifier);
+  }
   async delete() {
     await unwrapEmpty(
       this._client.DELETE("/api/disks/{id}", {
@@ -183,6 +198,21 @@ var Disk = class {
       })
     );
   }
+  /**
+   * Execute a command in a container with this disk mounted.
+   * Blocks until the command completes and returns stdout, stderr, and exit code.
+   */
+  async exec(command) {
+    return unwrap(
+      this._client.POST(
+        "/api/disks/{id}/exec",
+        {
+          params: { path: { id: this.id } },
+          body: { command }
+        }
+      )
+    );
+  }
   /**
    * Connect to this disk's data plane via the native ArchilClient.
    *
@@ -241,19 +271,28 @@ var Disks = class {
     return new Disk(data, this._client, this._region);
   }
   /**
-   * Create a new disk and return a Disk object with full details.
+   * Create a new disk with an auto-generated mount token.
    *
-   * Internally calls POST /api/disks (returns diskId) then GET /api/disks/{id}.
+   * Returns the Disk, the one-time token (save it — it cannot be retrieved
+   * again), and the token identifier for later management.
    */
   async create(req) {
     const created = await unwrap(
       this._client.POST("/api/disks", { body: req })
     );
-    const diskId = created.diskId;
-    if (!diskId) {
+    const resp = created;
+    if (!resp.diskId) {
       throw new Error("API returned success but no diskId");
     }
-    return this.get(diskId);
+    const authorizedUsers = resp.authorizedUsers ?? [];
+    const tokenUser = authorizedUsers.find((u) => u.token);
+    const disk = await this.get(resp.diskId);
+    return {
+      disk,
+      token: tokenUser?.token ?? null,
+      tokenIdentifier: tokenUser?.identifier ?? null,
+      authorizedUsers
+    };
   }
 };
 
@@ -292,13 +331,21 @@ var Tokens = class {
 var Archil = class {
   disks;
   tokens;
-  constructor(opts) {
+  constructor(opts = {}) {
+    const apiKey = opts.apiKey ?? process.env.ARCHIL_API_KEY;
+    const region = opts.region ?? process.env.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 client = createApiClient({
-      apiKey: opts.apiKey,
-      region: opts.region,
+      apiKey,
+      region,
       baseUrl: opts.baseUrl
     });
-    this.disks = new Disks(client, opts.region);
+    this.disks = new Disks(client, region);
     this.tokens = new Tokens(client);
   }
 };

package/dist/api/index.mjs

@@ -36,7 +36,7 @@ function createApiClient(opts) {
   return createClient({
     baseUrl,
     headers: {
-      Authorization: `key-${opts.apiKey}`
+      Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`
     }
   });
 }
@@ -125,16 +125,31 @@ var Disk = class {
       })
     );
   }
-  async removeUser(userType, principal) {
+  async removeUser(userType, identifier) {
     await unwrapEmpty(
       this._client.DELETE("/api/disks/{id}/users/{userType}", {
         params: {
           path: { id: this.id, userType },
-          query: { principal }
+          query: { identifier }
         }
       })
     );
   }
+  async createToken(nickname) {
+    const user = await unwrap(
+      this._client.POST("/api/disks/{id}/users", {
+        params: { path: { id: this.id } },
+        body: { type: "token", nickname }
+      })
+    );
+    if (!user.token || !user.identifier) {
+      throw new Error("Server did not return a generated token");
+    }
+    return user;
+  }
+  async removeTokenUser(identifier) {
+    await this.removeUser("token", identifier);
+  }
   async delete() {
     await unwrapEmpty(
       this._client.DELETE("/api/disks/{id}", {
@@ -142,6 +157,21 @@ var Disk = class {
       })
     );
   }
+  /**
+   * Execute a command in a container with this disk mounted.
+   * Blocks until the command completes and returns stdout, stderr, and exit code.
+   */
+  async exec(command) {
+    return unwrap(
+      this._client.POST(
+        "/api/disks/{id}/exec",
+        {
+          params: { path: { id: this.id } },
+          body: { command }
+        }
+      )
+    );
+  }
   /**
    * Connect to this disk's data plane via the native ArchilClient.
    *
@@ -200,19 +230,28 @@ var Disks = class {
     return new Disk(data, this._client, this._region);
   }
   /**
-   * Create a new disk and return a Disk object with full details.
+   * Create a new disk with an auto-generated mount token.
    *
-   * Internally calls POST /api/disks (returns diskId) then GET /api/disks/{id}.
+   * Returns the Disk, the one-time token (save it — it cannot be retrieved
+   * again), and the token identifier for later management.
    */
   async create(req) {
     const created = await unwrap(
       this._client.POST("/api/disks", { body: req })
     );
-    const diskId = created.diskId;
-    if (!diskId) {
+    const resp = created;
+    if (!resp.diskId) {
       throw new Error("API returned success but no diskId");
     }
-    return this.get(diskId);
+    const authorizedUsers = resp.authorizedUsers ?? [];
+    const tokenUser = authorizedUsers.find((u) => u.token);
+    const disk = await this.get(resp.diskId);
+    return {
+      disk,
+      token: tokenUser?.token ?? null,
+      tokenIdentifier: tokenUser?.identifier ?? null,
+      authorizedUsers
+    };
   }
 };
 
@@ -251,13 +290,21 @@ var Tokens = class {
 var Archil = class {
   disks;
   tokens;
-  constructor(opts) {
+  constructor(opts = {}) {
+    const apiKey = opts.apiKey ?? process.env.ARCHIL_API_KEY;
+    const region = opts.region ?? process.env.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 client = createApiClient({
-      apiKey: opts.apiKey,
-      region: opts.region,
+      apiKey,
+      region,
       baseUrl: opts.baseUrl
     });
-    this.disks = new Disks(client, opts.region);
+    this.disks = new Disks(client, region);
     this.tokens = new Tokens(client);
   }
 };

package/main.mjs

@@ -15,3 +15,4 @@ try {
 export const ArchilClient = native.ArchilClient;
 export const initLogging = native.initLogging;
 export const JsInodeType = native.JsInodeType;
+export const MAXIMUM_READ_SIZE = native.MAXIMUM_READ_SIZE;

package/native.d.ts

@@ -3,6 +3,11 @@
 
 /* auto-generated by NAPI-RS */
 
+/**
+ * Maximum size (in bytes) of a single read request.
+ * Matches MAXIMUM_READ_SIZE in the Rust protocol layer (rust-common/src/network/mod.rs).
+ */
+export declare const MAXIMUM_READ_SIZE: number
 /**
  * Initialize the Rust logger to output to stderr.
  *

package/native.js

@@ -72,8 +72,9 @@ if (!existsSync(localPath)) {
 
 const nativeBinding = require(localPath)
 
-const { initLogging, ArchilClient, JsInodeType } = nativeBinding
+const { initLogging, ArchilClient, JsInodeType, MAXIMUM_READ_SIZE } = nativeBinding
 
 module.exports.initLogging = initLogging
 module.exports.ArchilClient = ArchilClient
 module.exports.JsInodeType = JsInodeType
+module.exports.MAXIMUM_READ_SIZE = MAXIMUM_READ_SIZE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archildata/client",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "High-performance Node.js client for Archil distributed filesystem",
   "main": "main.js",
   "types": "main.d.ts",