npm package: @m4rc1o/proof-sdk
Description: SDK intended to standardize and facilitate client integration with the ProofAPI
Author: Márcio I. Santana
Latest version: 1.2.2

# Proof SDK

SDK intended to standardize and facilitate client integration with the ProofAPI.

[![npm version](https://img.shields.io/npm/v/@m4rc1o/proof-sdk)](https://www.npmjs.com/package/@m4rc1o/proof-sdk)

## Installation

```bash
npm install @m4rc1o/proof-sdk
# or
yarn add @m4rc1o/proof-sdk
```

## Usage

```typescript
import { ProofSDK } from '@m4rc1o/proof-sdk';

(async () => {
  const sdk = await ProofSDK.create(
    process.env.CLIENT_KEY!,
    process.env.CLIENT_SECRET!,
    process.env.ENCRYPTION_KEY!,
    process.env.BASE_URL, // optional: base API URL (default production)
    process.env.ASYNC_BASE_URL, // optional: async API URL for async endpoints
  );

  // Example: fetch all audit logs with pagination
  const logs = await sdk.auditLogClient.getAllAuditLogs({ page: 1, limit: 10 });
  console.log(logs);
})();
```

## API Clients

`ProofSDK` exposes several client instances to interact with different parts of the ProofAPI. Below are examples for each:

### Encryption Key Management

Manage your tenant’s encryption key hash.

```typescript
// Get current hash
const currentHash = await sdk.encryptionKeyClient.getEncryptionKeyHash();

// Validate provided encryption key
const isValid = await sdk.encryptionKeyClient.validateEncryptionKey(
  process.env.ENCRYPTION_KEY!,
);

// Update encryption key hash (executed only once)
await sdk.encryptionKeyClient.setEncryptionKeyHash('newStrongKey123');
// Warning:
//  - KEEP YOUR ENCRYPTION KEY SAFE, DON'T LOSE OR SHARE IT.
//  - YOUR ENCRYPTION KEY IS NOT STORED IN THE PROOFAPI, SO IT CAN'T BE RECOVERD IF LOST.
```

### Encrypted Users

Create, list, retrieve, encrypt and decrypt user data.

```typescript
// Encrypt & create
const encryptedUser = sdk.encryptedUserClient.encryptUser({
  id: '1',
  name: 'Alice',
  role: 'user',
});
const newEncUser =
  await sdk.encryptedUserClient.createEncryptedUser(encryptedUser);
// Asynchronous creation with response via webhook
const asyncUserRes = await sdk.encryptedUserClient.createEncryptedUserAsync({
  id: 'e8f8a8e2-1234-5678-abcd-ef0123456789',
  encryptedData: encryptedUser,
});
console.log(asyncUserRes);

// List with pagination
const { items: users, meta } =
  await sdk.encryptedUserClient.getAllEncryptedUsers({ page: 1, limit: 20 });

// Fetch and decrypt
const fetched = await sdk.encryptedUserClient.getEncryptedUser(newUser.id);
const user = sdk.encryptedUserClient.decryptUser(fetched.encryptedData);
```

### Encrypted Actions

Create, list, retrieve, encrypt and decrypt action data.

```typescript
// Encrypt & create
const encAction = sdk.encryptedActionClient.encryptAction({
  id: 'act1',
  name: 'Login',
  description: 'User login',
});
const newAction =
  await sdk.encryptedActionClient.createEncryptedAction(encAction);
// Asynchronous creation with response via webhook
const asyncActionRes =
  await sdk.encryptedActionClient.createEncryptedActionAsync({
    id: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
    encryptedData: encAction,
  });
console.log(asyncActionRes);

// List with pagination
const { items: actions, meta } =
  await sdk.encryptedActionClient.getAllEncryptedActions({
    page: 1,
    limit: 10,
  });

// Fetch and decrypt
const fetchedAction = await sdk.encryptedActionClient.getEncryptedAction(
  newAction.id,
);
const decrypted = sdk.encryptedActionClient.decryptAction(
  fetchedAction.encryptedData,
);
```

### Audit Logs

Record and query audit logs.

```typescript
// Create a new audit log
const log = await sdk.auditLogClient.createAuditLog(newUser.id, newAction.id);
// Asynchronous creation with response via webhook
const asyncLogRes = await sdk.auditLogClient.createAuditLogAsync({
  id: 'f0f1f2f3-1234-5678-abcd-9876543210fe',
  userId: newUser.id,
  actionId: newAction.id,
});
console.log(asyncLogRes);

// List logs with pagination
const { items: logs, meta } = await sdk.auditLogClient.getAllAuditLogs({
  page: 1,
  limit: 5,
});

// Get by ID
const single = await sdk.auditLogClient.getAuditLogById(log.id);

// Filter by user or action
const { items: logsByUser } = await sdk.auditLogClient.getLogsByUser(
  newUser.id,
  {
    page: 1,
    limit: 5,
  },
);
const { items: logsByAction } = await sdk.auditLogClient.getLogsByAction(
  newAction.id,
  {
    page: 1,
    limit: 5,
  },
);
```

### File Records

Upload files or register fingerprints on‐chain.

```typescript
// Register a file from path
const fileRec = await sdk.recordClient.registerFile('/tmp/document.pdf');

// Register a raw fingerprint (sha256 hash)
const fpRec = await sdk.recordClient.registerFingerprint('abc123...');

// Lookup by fingerprint or tx hash
const byFp = await sdk.recordClient.getRecordByFingerprint(fpRec.fingerprint);
const byTx = await sdk.recordClient.getRecordByTxHash(fileRec.txHash);
```

### Webhooks

```typescript
// Create a webhook
const webhook = await sdk.webhookClient.create({
  url: 'https://example.com/webhook',
  name: 'MyWebhook',
});

// Get current webhook
const currentWebhook = await sdk.webhookClient.getCurrent();

// Update webhook
const updatedWebhook = await sdk.webhookClient.update({
  url: 'https://example.com/new',
  isActive: true,
});

// Remove webhook
const { status } = await sdk.webhookClient.remove();
```

You can also verify incoming webhook signatures to ensure payloads are genuine:

```typescript
// Raw request data
const rawPayload = JSON.stringify(event.body);
// Try both common signature headers
const signatureHeader =
  event.headers['X-Hub-Signature'] || event.headers['X-Signature'];

// Validate signature
const isValid = await sdk.webhookClient.validatePayloadSignature(
  rawPayload,
  signatureHeader,
  'your-webhook-secret',
);
console.log(`Webhook signature valid: ${isValid}`);
```