npm package: @hacktionbase/node
Description: Hacktionbase Node.js SDK — track users, accounts and events from your backend.
Latest version: 0.1.1

# @hacktionbase/node

Official Node.js SDK for [Hacktionbase](https://hacktionbase.com). Track users, accounts and events from your backend.

## Install

```bash
npm install @hacktionbase/node
```

## Quick Start

```typescript
import { Hacktionbase } from "@hacktionbase/node";

const hb = new Hacktionbase({ apiKey: "hb_live_xxx" });

await hb.users({ externalId: "user_123", email: "john@acme.com" });
await hb.track("project_created", { projectId: "p_789" });
```

## Usage

### Initialize

```typescript
import { Hacktionbase } from "@hacktionbase/node";

const hb = new Hacktionbase({
  apiKey: "hb_live_xxx",       // Required — from your dashboard
  baseUrl: "https://...",      // Optional — defaults to https://api.hacktionbase.com/v1
  timeout: 10000,              // Optional — request timeout in ms (default: 10000)
  retries: 2,                  // Optional — retries on 5xx/network errors (default: 2)
});
```

### Users

Create or update a user.

```typescript
await hb.users({
  externalId: "user_123",          // Required — your internal user ID
  email: "john@acme.com",         // Optional
  anonymousId: "anon_abc",        // Optional — link to anonymous session
  attributes: {                    // Optional — custom attributes
    plan: "pro",
    signedUpAt: "2025-01-15",
  },
});
```

### Accounts

Create or update an account (company / organization).

```typescript
await hb.accounts({
  externalId: "org_456",          // Required — your internal account ID
  name: "Acme Inc",              // Optional
  attributes: {                   // Optional — custom attributes
    industry: "SaaS",
    employees: 50,
  },
});
```

### Events

Track an event. Two calling styles:

```typescript
// Short form
await hb.track("project_created", { projectId: "p_789" });

// Full form
await hb.track({
  event: "project_created",
  userExternalId: "user_123",
  accountExternalId: "org_456",
  properties: { projectId: "p_789" },
  timestamp: Date.now(),          // Optional — defaults to server time
});
```

### Identify

Merge an anonymous user with an identified user.

```typescript
await hb.identify({
  anonymousId: "anon_abc",
  externalId: "user_123",
});
```

### Batch

Send multiple users, accounts and events in a single request.

```typescript
await hb.batch({
  users: [
    { externalId: "user_123", email: "john@acme.com" },
    { externalId: "user_456", email: "jane@acme.com" },
  ],
  accounts: [
    { externalId: "org_456", name: "Acme Inc" },
  ],
  events: [
    { event: "signed_up", userExternalId: "user_123" },
    { event: "invited_teammate", userExternalId: "user_123", properties: { inviteeId: "user_456" } },
  ],
});
```

## Error Handling

```typescript
import { Hacktionbase, HacktionbaseError } from "@hacktionbase/node";

try {
  await hb.track("event_name");
} catch (err) {
  if (err instanceof HacktionbaseError) {
    console.error(err.status); // HTTP status code
    console.error(err.body);   // Response body
  }
}
```

4xx errors are thrown immediately. 5xx and network errors are retried automatically with exponential backoff.

## Requirements

- Node.js 18+ (uses native `fetch`)

## License

MIT