npm package: @humanos-ai/sdk
Description: Official Humanos API SDK for TypeScript/JavaScript with automatic request signing and webhook verification
Author: Humanos
Latest version: 1.0.10

# Humanos SDK for TypeScript/JavaScript

Official TypeScript/JavaScript SDK for the [Humanos](https://humanos.id) API. Provides automatic request signing, webhook verification and decryption, and full API access for credential management.

[![npm version](https://badge.fury.io/js/%40humanos-ai%2Fsdk.svg)](https://www.npmjs.com/package/@humanos-ai/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Automatic Request Signing** - All API requests are signed with HMAC-SHA256
- **Webhook Verification** - Verify signatures and decrypt encrypted payloads
- **TypeScript Support** - Full type definitions included
- **Simple API** - Clean interface for all Humanos endpoints

## Getting Started

### 1. Create an Account

Sign up at [humanos.id](https://humanos.id) and create your organization.

### 2. Get Your API Keys

In the Humanos Dashboard, go to **Settings > API Keys** and copy:

- **API Key** - Used to authenticate requests
- **Signature Secret** - Used to sign requests with HMAC-SHA256

### 3. Get Your Webhook Keys

In the Humanos Dashboard, go to **Settings > Webhooks** and copy:

- **Webhook Signature Secret** - Used to verify incoming webhook signatures
- **Webhook Encryption Secret** - Used to decrypt webhook payloads
- **Webhook Encryption Salt** - Used alongside the encryption secret

### 4. Install the SDK

```bash
npm install @humanos-ai/sdk
```

### 5. Initialize the Client

```typescript
import { HumanosClient } from "@humanos-ai/sdk";

const client = new HumanosClient({
  basePath: "https://api.humanos.id",
  apiKey: process.env.HUMANOS_API_KEY!,
  signatureSecret: process.env.HUMANOS_SIGNATURE_SECRET!,
});
```

### 6. Make Your First API Call

Fetch all your credential requests:

```typescript
const response = await client.requests.getRequests();
console.log(response.data);
```

## Usage Examples

### Create a Credential Request

Send a credential request to one or more contacts using pre-configured resources:

```typescript
const request = await client.requests.generate({
  contacts: ["user@example.com"],
  securityLevel: "CONTACT",
  resourcesIds: ["your-resource-id"],
});

console.log("Request ID:", request.data.id);
console.log("Credentials:", request.data.credentials);
```

You can also use group IDs to include all resources in a group:

```typescript
const request = await client.requests.generate({
  contacts: ["user@example.com"],
  securityLevel: "CONTACT",
  groupIds: ["your-group-id"],
});
```

Or provide inline credential data directly:

```typescript
const request = await client.requests.generate({
  contacts: ["user@example.com"],
  securityLevel: "CONTACT",
  credentials: [
    {
      scope: "onboarding",
      type: "JSON",
      name: "Service Agreement",
      data: [
        { label: "Company", type: "string", value: "Acme Corp" },
        { label: "Plan", type: "string", value: "Enterprise" },
      ],
    },
  ],
});
```

### Receive Webhooks

Humanos sends webhook events when credentials are signed, identity checks complete, or OTPs fail. Payloads are encrypted and signed.

The SDK provides `createWebhookHandler` which handles signature verification and payload decryption automatically:

```typescript
import express from "express";
import { createWebhookHandler, WebhookConfig } from "@humanos-ai/sdk";

const app = express();

// Use express.text() to preserve the raw body for signature verification
app.use(express.text({ type: "application/json" }));

const webhookConfig: WebhookConfig = {
  signatureSecret: process.env.HUMANOS_WEBHOOK_SIGNATURE_SECRET!,
  encryptionSecret: process.env.HUMANOS_WEBHOOK_ENCRYPTION_SECRET!,
  encryptionSalt: process.env.HUMANOS_WEBHOOK_ENCRYPTION_SALT!,
};

app.post(
  "/webhook",
  createWebhookHandler(webhookConfig, (payload) => {
    console.log("Event type:", payload.eventType);

    switch (payload.eventType) {
      case "credential":
        console.log("Credential signed:", payload.requestId);
        break;
      case "identity":
        console.log("Identity verified:", payload.requestId);
        break;
      case "otp.failed":
        console.log("OTP failed:", payload.requestId);
        break;
      case "test":
        console.log("Test event received");
        break;
    }
  }),
);

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});
```

For local development, use [ngrok](https://ngrok.com) to expose your server:

```bash
ngrok http 3000
```

Then set the ngrok URL (e.g. `https://xxxx.ngrok-free.app/webhook`) as your webhook URL in the Humanos Dashboard under **Settings > Webhooks**.

## API Reference

### Resources

```typescript
// List resources
const resources = await client.resources.getResources();

// List resource groups
const groups = await client.resources.getGroups();

// Download a credential file
const file = await client.resources.download(credentialId);
```

### Requests

```typescript
// List requests
const requests = await client.requests.getRequests();

// Get request details
const detail = await client.requests.getRequestDetail(requestId);

// Create a credential request
const request = await client.requests.generate({ ... });

// Cancel a request
await client.requests.cancelRequest(requestId);

// Resend OTP
await client.requests.resendOtp(requestId);
```

### Users

```typescript
// Create or update users
const users = await client.users.create([
  {
    contact: "user@example.com",
    internalId: "your-internal-id",
    identity: {
      fullName: "John Doe",
      birth: "1990-01-01",
      docId: "123456789",
      countryAlpha3: "USA",
    },
  },
]);
```

## Error Handling

The SDK throws errors for failed requests. The error object includes the HTTP response when available:

```typescript
try {
  const request = await client.requests.generate({ ... });
} catch (error) {
  if (error.response) {
    console.error('Status:', error.response.status);
    console.error('Body:', error.response.data);
  } else {
    console.error('Error:', error.message);
  }
}
```

## Documentation

- [API Documentation](https://humanos.mintlify.app/)
- [Humanos Website](https://humanos.id)

## Support

- **Email**: tech@humanos.tech

## License

MIT License - see [LICENSE](./LICENSE) file for details.