npm package: @sourcenetwork/acp-js
Description: A client/bridge library for interacting with the SourceHub ACP. This library provides both low-level client access and high-level helper functions for managing policies, objects, actor relationships, and performing access verification.
Latest version: 1.1.0

# SourceHub ACP JS Client

A client/bridge library for interacting with the SourceHub ACP. This library provides both low-level client access and high-level helper functions for managing policies, objects, actor relationships, and performing access verification.

## Features

- **Policy Management** - Create and retrieve access control policies
- **Object Registration** - Register objects within policy contexts  
- **Actor Relationships** - Manage relationships between actors and objects
- **Access Verification** - Verify access permissions for specific operations
- **Key Management** - Automatic wallet creation and session management via `@sourcenetwork/hublet`

## Installation

```bash
npm install @sourcenetwork/acp-js
# or
yarn add @sourcenetwork/acp-js
```

## Quick Start

```typescript
import { 
  createPolicy, 
  registerObject, 
  setRelationship,
  verifyAccess,
  getObjectOwner 
} from '@sourcenetwork/acp-js';

// Configure global settings (optional)
if (typeof window !== 'undefined') {
  window.globalACPConfig = {
    apiUrl: 'http://localhost:1317',
    rpcUrl: 'http://localhost:26657', 
    grpcUrl: 'http://localhost:9090',
    chainId: 'sourcehub-dev',
    denom: 'uopen',
    useZeroFees: false
  };
}

// Create a policy and get the policy ID
const policyId = await createPolicy(1, policyDefinition);

// Register an object
await registerObject(policyId, 'documents', 'doc123');

// Set actor relationship
await setRelationship(policyId, 'documents', 'doc123', 'owner', 'alice');

// Verify access
const canRead = await verifyAccess(policyId, 'documents', 'doc123', 'read', 'alice');

// Get object owner
const owner = await getObjectOwner(policyId, 'documents', 'doc123');
```

## API Reference

### SourceHubACP Class

- `SourceHubACP.create(apiUrl, rpcUrl, grpcUrl, chainId, denom?, useZeroFees?)` - Create with new signer
- `SourceHubACP.createFromKeys(privateKey, pubkey, compressedPubkey, ...)` - Create with existing keys

### Helper Functions

- `createPolicy(marshalType, policyContent): Promise<string>` - Create policy and return ID
- `registerObject(policyId, resourceName, objectId): Promise<TxResponse>` - Register object
- `setRelationship(policyId, resourceName, objectId, relation, targetActor): Promise<TxResponse>` - Set relationship
- `deleteRelationship(policyId, resourceName, objectId, relation, targetActor): Promise<TxResponse>` - Delete relationship  
- `verifyAccess(policyId, resourceName, objectId, permission, actorId): Promise<boolean>` - Verify access
- `getObjectOwner(policyId, resourceName, objectId): Promise<string | null>` - Get owner
- `getPolicy(policyId): Promise<Policy | null>` - Get policy
- `initAccount(address): Promise<FaucetResponse>` - Initialize account via faucet
- `grantAllowance(address): Promise<FaucetResponse>` - Grant fee allowance via faucet
- `deleteKeypair(): Promise<void>` - Clear session wallet

## Configuration

```typescript
window.globalACPConfig = {
  apiUrl: 'https://api.sourcehub.dev',
  rpcUrl: 'https://rpc.sourcehub.dev', 
  grpcUrl: 'https://grpc.sourcehub.dev',
  chainId: 'sourcehub-1',
  denom: 'uopen',
  useZeroFees: false
};
```

## Development

### Prerequisites

- Node.js 18+
- Yarn (recommended) or npm

### Building

```bash
# Install dependencies
yarn install
# Build both ESM and CJS versions
yarn build
# Build individual formats
yarn build:esm
yarn build:cjs
```

### Testing

```bash
yarn test
```

### Linting

```bash
yarn lint
```

### Proto Generation

```bash
# Generate protobuf files
./generate-proto.sh
```

## License

This project is licensed under the Apache License 2.0.