# @archildata/client

Node.js client for [Archil](https://archil.com) — a high-performance distributed filesystem that turns your cloud storage (S3, GCS, Azure Blob, R2) into something you can read, write, and run commands against like a local disk.

## Quick Start: Connect an S3 Bucket

This walks you through creating an Archil disk backed by your S3 bucket and running bash commands on it. The whole thing takes about two minutes.

### 1. Sign up

Go to [console.archil.com](https://console.archil.com) and create an account.

### 2. Install

```bash
npm install @archildata/client
```

### 3. Create a disk

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).

```typescript
import { Archil } from '@archildata/client/api';

const archil = new Archil({
  apiKey: 'your-api-key',
  region: 'aws-us-east-1',
});

const MOUNT_TOKEN = 'my-secret-mount-token';

const disk = 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),
  }],
});

console.log(`Created disk: ${disk.organization}/${disk.name}`);
```

You only do this once. After that, the disk is available by name whenever you want to connect.

### 4. Run bash commands on it

Install `@archildata/just-bash` to get a shell that runs against your disk:

```bash
npm install @archildata/just-bash
```

Then connect using the mount token you authorized above:

```bash
ARCHIL_TOKEN=my-secret-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:

```
$ ls
data/  logs/  config.json

$ cat config.json
{"version": 2, "debug": false}

$ echo "hello from archil" > greeting.txt
```

Everything you do here — reads, writes, renames, deletes — goes through Archil to your bucket.

## Using just-bash Programmatically

The interactive shell is great for poking around, but you can also run bash commands from your own code. This is useful for scripts, CI pipelines, or anywhere you want to run shell commands against your disk without mounting it.

```typescript
import { ArchilClient } from '@archildata/client';
import { ArchilFs, createArchilCommand } from '@archildata/just-bash';
import { Bash } from 'just-bash';

// Connect to your disk
const client = await ArchilClient.connect({
  region: 'aws-us-east-1',
  diskName: 'myaccount/my-disk',
  authToken: 'my-secret-mount-token',
});

// Create a filesystem adapter and a bash executor
const fs = await ArchilFs.create(client);
const bash = new Bash({
  fs,
  customCommands: [createArchilCommand(client, fs)],
});

// Run commands just like you would in a terminal
const result = await bash.exec('ls -la /');
console.log(result.stdout);

// Write a file
await bash.exec('echo "hello world" > /greeting.txt');

// Read it back
const cat = await bash.exec('cat /greeting.txt');
console.log(cat.stdout); // "hello world"

// Clean up
await client.close();
```

You can also use the filesystem adapter directly without bash, if you just need standard file operations:

```typescript
const fs = await ArchilFs.create(client);

// These work like their Node.js fs equivalents
await fs.writeFile('/notes.txt', 'some content');
const content = await fs.readFile('/notes.txt');
const entries = await fs.readdir('/');
const stats = await fs.stat('/notes.txt');
await fs.mkdir('/mydir', { recursive: true });
await fs.cp('/notes.txt', '/mydir/notes-copy.txt');
await fs.rm('/notes.txt');
```

## Using the Native Client Directly

For more control, you can use the `ArchilClient` directly. This gives you access to the full filesystem protocol — inodes, delegations, paginated directory reads, etc.

### Connecting

```typescript
import { ArchilClient } from '@archildata/client';

const client = await ArchilClient.connect({
  region: 'aws-us-east-1',
  diskName: 'myaccount/my-disk',
  authToken: 'my-secret-mount-token',
});
```

### Reading files

Every file and directory on an Archil disk has an inode ID. The root directory is always inode `1`. You navigate by looking up names inside directories, then reading the inodes you find.

```typescript
// Look up a file by name in the root directory
const entry = await client.lookupInode(1, 'config.json');

// Read its contents
const data = await client.readInode(entry.inodeId, 0, entry.attributes.size);
console.log(data.toString());
```

### Listing directories

```typescript
const handle = await client.openDirectory(1);
const page = await client.readDirectory(1, handle, 100);

for (const entry of page.entries) {
  console.log(`${entry.name} (${entry.inodeType})`);
}

client.closeDirectory(1, handle);
```

For large directories, pass the returned `page.nextCursor` back into `readDirectory` to get the next page. When `nextCursor` is `undefined`, you've seen everything.

### Writing files

Archil uses a delegation model for writes. Before you can write to a file, you "check out" a delegation on it — this tells the server you intend to modify it and gives you exclusive access. When you're done, you "check in" to release it so other clients can write.

```typescript
// Check out the file to acquire a write delegation
await client.checkout(inodeId);

// Write data
await client.writeData(inodeId, 0, Buffer.from('new contents'));

// Make sure the write is durable on the server
await client.sync();

// Release the delegation so other clients can write
await client.checkin(inodeId);
```

### Creating files and directories

```typescript
// Create a directory in root (inode 1)
const dir = await client.create(1, 'mydir', {
  inodeType: 'Directory',
  uid: 1000,
  gid: 1000,
  mode: 0o755,
});

// Create a file inside it
const file = await client.create(dir.inodeId, 'data.txt', {
  inodeType: 'File',
  uid: 1000,
  gid: 1000,
  mode: 0o644,
});

// Write to the new file
await client.checkout(file.inodeId);
await client.writeData(file.inodeId, 0, Buffer.from('file contents'));
await client.checkin(file.inodeId);
```

### Renaming and deleting

```typescript
await client.rename(parentInodeId, 'old.txt', parentInodeId, 'new.txt');
await client.unlink(parentInodeId, 'new.txt');
```

### Cleaning up

Always close the client when you're done. This flushes pending writes and releases any delegations you're still holding.

```typescript
await client.close();
```

## Managing Disks

The control plane API lets you manage disks and access control after initial setup.

```typescript
import { Archil } from '@archildata/client/api';

const archil = new Archil({
  apiKey: 'your-api-key',
  region: 'aws-us-east-1',
});

// List your disks
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),
});

// Remove access
await disk.removeUser('token', CI_TOKEN);

// Delete a disk (this does not delete your bucket data)
await disk.delete();
```

### Going from a disk to a client

If you have a `Disk` object from the API, you can connect directly without specifying the region and name again:

```typescript
const disk = await archil.disks.get('dsk-xxx');
const client = await disk.mount({ authToken: '<your-token>' });

// client is an ArchilClient — use it for reads, writes, etc.
await client.close();
```

## Supported Regions

| Region             | Provider |
| ------------------ | -------- |
| `aws-us-east-1`   | AWS      |
| `aws-us-west-2`   | AWS      |
| `aws-eu-west-1`   | AWS      |
| `gcp-us-central1` | GCP      |

## Supported Storage Backends

- **Amazon S3** (`type: 's3'`)
- **Google Cloud Storage** (`type: 'gcs'`)
- **Azure Blob Storage** (`type: 'azure-blob'`)
- **Cloudflare R2** (`type: 'r2'`)
- **S3-compatible services** (`type: 's3-compatible'`)

## Platform Support

The control plane API (`@archildata/client/api`) works on any platform — macOS, Windows, Linux.

The native filesystem client (connecting to disks, reading/writing files) supports **Linux** (x64 or arm64, glibc) and **macOS** (Apple Silicon / arm64). On other platforms, the API-only imports still work.

## Support

Questions, feature requests, or issues? Reach us at **support@archil.com**.
