# @archildata/client

High-performance Node.js bindings for the Archil distributed filesystem client.

## Overview

This package provides low-level N-API bindings to the Archil client library, exposing the `ArchilService` trait methods directly to JavaScript/TypeScript. It's designed for use cases where you need direct protocol access without FUSE overhead.

## Installation

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

## Supported Platforms

This package includes pre-built binaries for:

- **macOS** (Apple Silicon) - `darwin-arm64`
- **Linux** (x86_64) - `linux-x64-gnu`
- **Linux** (ARM64) - `linux-arm64-gnu`

Other platforms are not currently supported.

> **Note:** For best performance, run your application in the same region as your Archil disk (e.g., if your disk is in `aws-us-east-1`, deploy your app to AWS us-east-1).

## Usage

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

// Connect to Archil
const client = await ArchilClient.connect({
  region: 'aws-us-east-1',
  diskName: 'myaccount/mydisk',
  authToken: process.env.ARCHIL_TOKEN, // optional, uses IAM if not provided
});

// Get root directory attributes
const rootAttrs = await client.getAttributes(1);
console.log('Root size:', rootAttrs.size);

// List directory contents
const entries = await client.readDirectory(1);
for (const entry of entries) {
  console.log(`${entry.name} (inode: ${entry.inodeId})`);
}

// Read a file
const lookup = await client.lookupInode(1, 'myfile.txt');
const data = await client.readInode(lookup.inodeId, 0, 1024);
console.log('File content:', data.toString());

// Close when done
await client.close();
```

## API

### `ArchilClient`

The main client class for interacting with Archil filesystems.

#### Connection Methods

- `connect(config)` - Connect using region and disk name (recommended)
- `connectDirect(config)` - Connect directly to a server (for testing)

#### Metadata Operations

- `getAttributes(inodeId, user?)` - Get inode attributes
- `lookupInode(parentInodeId, name, user?)` - Lookup entry by name
- `readDirectory(inodeId, offset?, cookie?, user?)` - List directory entries
- `getExtendedAttribute(inodeId, name, user?)` - Get xattr value
- `listExtendedAttributes(inodeId, user?)` - List xattr names

#### Data Operations

- `readInode(inodeId, offset, length, user?)` - Read file data
- `writeData(inodeId, offset, data, user?)` - Write file data (requires delegation)
- `sync()` - Sync all pending writes to server

#### Delegation Operations

- `checkout(inodeId, options?, user?)` - Acquire write delegation
- `checkin(inodeId, user?)` - Release delegation
- `checkinAll()` - Release all delegations
- `listDelegations()` - List currently held delegations

#### Mutation Operations

- `create(parentInodeId, name, attributes, user?)` - Create file/directory
- `unlink(parentInodeId, name, user?)` - Delete file or empty directory
- `rename(parentInodeId, name, newParentInodeId, newName, user?)` - Move/rename
- `setattr(inodeId, options, user)` - Update file attributes
- `setImmutable(inodeId)` - Mark subtree as immutable
- `setMutable(inodeId)` - Mark subtree as mutable
- `listImmutableSubtrees()` - List immutable roots

### Types

```typescript
interface SimpleConnectionConfig {
  region: string;      // e.g., "aws-us-east-1"
  diskName: string;    // e.g., "myaccount/mydisk"
  authToken?: string;  // optional, uses IAM if not provided
  logLevel?: string;   // optional: "trace", "debug", "info", "warn", "error"
}

interface UnixUser {
  uid: number;
  gid: number;
}

interface InodeAttributes {
  inodeId: number;
  inodeType: 'File' | 'Directory' | 'Symlink' | ...;
  size: number;
  uid: number;
  gid: number;
  mode: number;
  nlink: number;
  ctimeMs: number;
  atimeMs: number;
  mtimeMs: number;
  btimeMs: number;
  rdev?: number;
  symlinkTarget?: string;
}

interface DirectoryEntry {
  name: string;
  inodeId: number;
  inodeType: string;
}

interface SetAttrOptions {
  mode?: number;
  uid?: number;
  gid?: number;
  size?: number;
  atimeMs?: number;   // use -1 for current time
  mtimeMs?: number;   // use -1 for current time
}
```

## Building

This package uses napi-rs for native bindings. To build from source:

```bash
cd rust-libs/archil-node
npm install
npm run build
```

## License

Proprietary - Archil Inc.
