npm package: @journeyrewards/hive-admin-sdk
Description: Admin SDK for the Journey Hive Agent Orchestration API — programmatic agent management, skill provisioning, and platform settings
Latest version: 1.2.1

# @journeyrewards/hive-admin-sdk

Admin SDK for the Journey Hive Agent Orchestration API. Provides programmatic access to agent lifecycle management, skill provisioning, and platform settings.

## Installation

```bash
npm install @journeyrewards/hive-admin-sdk
```

## Quick Start

```typescript
import { JourneyHiveAdminClient } from "@journeyrewards/hive-admin-sdk";

const client = new JourneyHiveAdminClient({
  apiKey: "jh_your_admin_api_key",
  // baseUrl: "https://your-instance.replit.app", // optional
});
```

## API Key Permissions

Your API key must include the appropriate admin scopes:

| Scope | Description |
|---|---|
| `admin:agents:create` | Create new agents |
| `admin:agents:delete` | Delete agents |
| `admin:agents:manage` | Provision sandbox, wake/sleep agents |
| `admin:skills:read` | List available skills and agent skills |
| `admin:skills:manage` | Install, uninstall, configure, redeploy skills |
| `admin:settings:read` | Read platform settings |
| `admin:settings:write` | Update platform settings |

Use `*` (wildcard) to grant all permissions including admin scopes.

## Usage

### Agent Management

```typescript
// Create a specialist agent
const agent = await client.agents.create({
  name: "Concierge Bot",
  slug: "concierge-bot",
  type: "specialist",
  soul_template: "hospitality-concierge",
  personality_notes: "Friendly and helpful hotel concierge",
  lifecycle_mode: "wake_on_demand",
  external_access: "api_enabled",
  metadata: { property: "grand-hotel" },
});

console.log(agent.id); // "abc123"
console.log(agent.status); // "idle"

// Create a member agent (personal loyalty concierge)
const memberAgent = await client.agents.create({
  name: "Member Agent — AJKDBC",
  slug: "member-ajkdbc",
  type: "member",
  member_id: "AJKDBC",                          // loyalty program ID
  clerk_user_id: "user_2nFZBKVLH3kMd9i...",     // Clerk auth ID
  personal_name: "Helga",                        // name the member chose
  personality_notes: "Warm, personal, proactive about rewards",
});

console.log(memberAgent.personal_name); // "Helga"
console.log(memberAgent.member_id);     // "AJKDBC"

// Provision a sandbox for the agent
const provisioned = await client.agents.provision(agent.id);
console.log(provisioned.sandbox_id); // "sandbox_xyz"

// Wake a sleeping agent
const awake = await client.agents.wake(agent.id);
console.log(awake.status); // "running"

// Put an agent to sleep
const sleeping = await client.agents.sleep(agent.id);
console.log(sleeping.status); // "sleeping"

// Delete an agent (also destroys its sandbox)
const deleted = await client.agents.delete(agent.id);
console.log(deleted.deleted); // true
```

### Skill Management

```typescript
// List all available skills
const skills = await client.skills.list();
console.log(skills.data); // [{ id: "...", name: "google-sheets", ... }]

// List skills installed on an agent
const agentSkills = await client.agents.listSkills(agentId);

// Install a skill on an agent
const installed = await client.agents.installSkill(agentId, {
  skill_id: "skill_abc",
  config: { SPREADSHEET_ID: "1234..." },
});

// Update skill configuration (env vars)
await client.agents.updateSkillConfig(agentId, skillId, {
  config: { SPREADSHEET_ID: "5678..." },
});

// Redeploy a skill to the agent's sandbox
await client.agents.redeploySkill(agentId, skillId);

// Uninstall a skill
await client.agents.uninstallSkill(agentId, skillId);
```

### Platform Settings

```typescript
// List all settings
const settings = await client.settings.list();

// Get a specific setting
const setting = await client.settings.get("default_model");
console.log(setting.value); // "anthropic/claude-opus-4-6"

// Update a setting
const updated = await client.settings.set("default_model", {
  value: "anthropic/claude-sonnet-4-20250514",
  description: "Default LLM model for new agents",
});
```

### Error Handling

```typescript
import {
  JourneyHiveAdminClient,
  JourneyHiveError,
  AuthenticationError,
  PermissionError,
  NotFoundError,
} from "@journeyrewards/hive-admin-sdk";

try {
  await client.agents.create({ name: "Test", slug: "test", type: "specialist" });
} catch (err) {
  if (err instanceof PermissionError) {
    console.error("Missing admin:agents:create permission");
  } else if (err instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (err instanceof NotFoundError) {
    console.error("Resource not found");
  } else if (err instanceof JourneyHiveError) {
    console.error(`API error ${err.status}: ${err.message} (${err.code})`);
  }
}
```

### Debug Mode

Enable debug logging to see all HTTP requests and responses:

```typescript
const client = new JourneyHiveAdminClient({
  apiKey: "jh_your_key",
  debug: true,
});
```

## Configuration

| Option | Type | Default | Description |
|---|---|---|---|
| `apiKey` | `string` | *required* | API key with admin scopes |
| `baseUrl` | `string` | `https://journey-hive.replit.app` | API base URL |
| `timeout` | `number` | `30000` | Request timeout in ms |
| `debug` | `boolean` | `false` | Enable debug logging |

## Agent Types

The `type` field determines the agent's role and which additional fields are relevant:

| Type | Purpose | Key Fields |
|---|---|---|
| `controller` | Primary routing and orchestration | — |
| `organization` | Organization-specific concierge | `organization_id`, `hxp_org_id` |
| `specialist` | Specialized task handler | — |
| `security` | Security monitoring | — |
| `auth` | Authentication gateway | — |
| `member` | Personal loyalty concierge for one traveler | `member_id`, `clerk_user_id`, `personal_name` |

### Member Agent Fields

When creating a member agent, pass these fields so the platform can scope data and route sessions correctly:

- **`member_id`** — The traveler's loyalty program ID (e.g. `"AJKDBC"`). Used for BigQuery row-level security and data scoping.
- **`clerk_user_id`** — The Clerk authentication user ID (e.g. `"user_abc123..."`). Used to bind authenticated sessions to this agent.
- **`personal_name`** *(optional)* — A name the member chose for their agent (e.g. `"Helga"`). When set, the agent's SOUL.md and IDENTITY.md are generated with instructions to introduce itself by this name.

## License

MIT