humanos 1.0.1

package/README.md

@@ -0,0 +1,246 @@
+# 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%2Fsdk.svg)](https://www.npmjs.com/package/humanos)
+[![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. Install the SDK
+
+```bash
+npm install humanos
+```
+
+### 2. Create an Account
+
+Sign up at [humanos.id](https://humanos.id) and create your organization.
+
+### 3. 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
+
+### 4. 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
+
+### 5. Initialize the Client
+
+```typescript
+import { HumanosClient } from "humanos";
+
+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";
+
+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.