----++                                ----++                    ---+++     
  ---+++                                ---++                     ---++      
 ----+---     -----     ---------  --------++ ------     -----   ----++----- 
 ---------+ --------++----------++--------+++--------+ --------++---++---++++
 ---+++---++ ++++---++---+++---++---+++---++---+++---++---++---++------++++  
----++ ---++--------++---++----++---+++---++---++ ---+---++     -------++    
----+----+---+++---++---++----++---++----++---++---+++--++ --------+---++   
---------++--------+++--------+++--------++ -------+++ -------++---++----++  
 +++++++++   +++++++++- +++---++   ++++++++    ++++++    ++++++  ++++  ++++  
                     --------+++                                             
                       +++++++                                               

@bagdock/hive

Embeddable AI-powered storage management for your app — streaming chat, pluggable authentication, and multi-tenant operator scoping.

Install

npm install @bagdock/hive

yarn add @bagdock/hive

pnpm add @bagdock/hive

bun add @bagdock/hive

How it works

Your app talks to the Bagdock API through the SDK. The API handles AI responses, tool execution, and data access on your behalf.

graph LR
  subgraph Your App
    SDK["@bagdock/hive"]
  end

  SDK -- "ek_* / rk_*" --> API["Bagdock API"]

Key types

Bagdock uses a Stripe-style three-tier key model:

| Prefix | Name | Use case | Scopes | |--------|------|----------|--------| | ek_* | Embed Key | Client-side widgets, iframes | Origin-locked, read-only by default | | rk_* | Restricted Key | Server-side integrations, APIs | Granular scopes, no origin lock | | whsec_* | Webhook Signing Key | Verifying webhook payloads | HMAC-SHA256 signatures |

All keys support live and test environments:

'ek_live_abc123...'  // Production embed key
'ek_test_abc123...'  // Sandbox embed key

Use cases

1. Quick chat (simplest)

Embed a chat widget in 10 lines. The SDK handles streaming, tool execution, and session management.

sequenceDiagram
  participant Browser
  participant SDK as @bagdock/hive
  participant API as Bagdock API

  Browser->>SDK: sendMessage("Find storage in London")
  SDK->>API: POST /hive/chat/stream<br/>Authorization: Bearer ek_live_...
  API-->>SDK: SSE stream (text + tool results)
  SDK-->>Browser: messages[] updated

import { BagdockHive } from '@bagdock/hive'

const hive = new BagdockHive({
  apiKey: 'ek_live_...',
})

const stream = hive.chat.stream({
  messages: [{ role: 'user', content: 'Find storage near King\'s Cross' }],
})

2. With user authentication

Attach a user identity so the agent can access their rentals, payments, and profile.

sequenceDiagram
  participant User
  participant App
  participant Auth as Auth Provider<br/>(Clerk/Stytch/Auth0)
  participant SDK as @bagdock/hive
  participant API as Bagdock API

  User->>App: Sign in
  App->>Auth: Authenticate
  Auth-->>App: JWT token
  App->>SDK: new BagdockHive({ auth: { getToken } })
  SDK->>API: POST /hive/chat/stream<br/>+ X-Bagdock-User-Token: jwt
  API-->>SDK: Personalised response (rentals, loyalty, etc.)

import { BagdockHive } from '@bagdock/hive'

const hive = new BagdockHive({
  apiKey: 'ek_live_...',
  auth: {
    provider: 'clerk',
    getToken: () => clerk.session?.getToken() ?? '',
  },
})

const stream = hive.chat.stream({
  messages: [{ role: 'user', content: 'Show my upcoming payments' }],
})

Supported providers: Clerk, Auth0, Stytch (client-side), or any custom JWT.

3. Server-side proxy (httpOnly cookies)

If your auth provider uses httpOnly cookies (e.g. Stytch session tokens), the JWT is not accessible to client-side JavaScript. Use a thin server-side proxy that authenticates and forwards requests to the Bagdock API.

sequenceDiagram
  participant User
  participant Browser
  participant Proxy as Your API Route<br/>(Next.js / Express)
  participant API as Bagdock API

  User->>Browser: Chat message
  Browser->>Proxy: POST /api/hive/stream<br/>(httpOnly cookie sent automatically)
  Proxy->>Proxy: Read cookie, authenticate server-side
  Proxy->>API: POST /hive/chat/stream<br/>+ Authorization: Bearer ek_live_...<br/>+ X-Bagdock-User-Token: jwt
  API-->>Proxy: SSE stream
  Proxy-->>Browser: SSE stream (passthrough)

// app/api/hive/stream/route.ts (Next.js App Router)
import { type NextRequest } from 'next/server'

export async function POST(req: NextRequest) {
  // 1. Read httpOnly cookie (never exposed to client JS)
  const sessionToken = req.cookies.get('stytch_session')?.value

  // 2. Authenticate server-side
  const headers: Record<string, string> = {
    'Authorization': `Bearer ${process.env.HIVE_EMBED_KEY}`,
    'Content-Type': 'application/json',
  }
  if (sessionToken) {
    const session = await stytch.sessions.authenticate({ session_token: sessionToken })
    headers['X-Bagdock-User-Token'] = session.session_jwt
    headers['X-Bagdock-Contact-Id'] = session.user.user_id
  }

  // 3. Forward to Bagdock API
  const upstream = await fetch(
    `${process.env.HIVE_API_URL}/api/v1/hive/chat/stream`,
    { method: 'POST', headers, body: req.body, duplex: 'half' as any },
  )

  // 4. Stream response back to client
  return new Response(upstream.body, {
    status: upstream.status,
    headers: { 'Content-Type': 'text/event-stream' },
  })
}

Security: Use this pattern when your auth provider uses httpOnly cookies. The JWT and embed key never leave your server — they are not accessible to client-side JavaScript or NEXT_PUBLIC_ environment variables. This satisfies SOC 2 CC6.1, CC6.3 and GDPR Art. 32 requirements.

Auth pattern decision guide

| Your auth setup | Recommended pattern | Example | |---|---|---| | Client-accessible JWT (Clerk, Auth0, Firebase) | auth adapter directly | auth: { provider: 'clerk', getToken } | | httpOnly session cookies (Stytch, custom cookies) | Server-side proxy | Next.js API route → Bagdock API | | Server-to-server (backend integrations) | Restricted key (rk_*) | apiKey: 'rk_live_...' |

4. Operator-scoped (multi-tenant)

Scope all requests to a specific operator — their facilities, pricing, and branding.

graph TB
  subgraph Your Platform
    SDK["@bagdock/hive<br/>rk_live_..."]
  end

  SDK --> |"forOperator('opreg_acme')"| OpA["Acme Storage"]
  SDK --> |"forOperator('opreg_globalvault')"| OpB["Global Vault"]

const hive = new BagdockHive({ apiKey: 'rk_live_...' })

// Scoped to Acme Storage
const acme = hive.forOperator('opreg_acme')
const units = await acme.units.list({ status: 'available' })
const codes = await acme.access.list(unitId)

// Scoped to Global Vault
const vault = hive.forOperator('opreg_globalvault')
const vaultUnits = await vault.units.list()

4. Server-side with restricted key

Full API access from your backend — manage units, trigger webhooks, read analytics.

// Server-side only — never expose rk_* keys to the browser
import { BagdockHive } from '@bagdock/hive'

const hive = new BagdockHive({
  apiKey: process.env.BAGDOCK_RESTRICTED_KEY!, // rk_live_...
})

const units = await hive.units.list({ status: 'available' })
const rental = await hive.units.book({
  unitId: 'unit_abc',
  contactId: 'contact_123',
  moveInDate: '2025-02-01',
})

5. AI SDK integration (useChat)

Use HiveChatTransport with the Vercel AI SDK for seamless useChat integration.

import { useChat } from '@ai-sdk/react'
import { HiveChatTransport } from '@bagdock/hive'

function ChatPage() {
  const { messages, sendMessage, status } = useChat({
    transport: new HiveChatTransport({
      apiKey: 'ek_live_...',
      operatorId: 'opreg_acme', // optional
    }),
  })

  return (
    <div>
      {messages.map(m => <p key={m.id}>{m.content}</p>)}
      <button onClick={() => sendMessage({ text: 'Find storage' })}>
        Send
      </button>
    </div>
  )
}

6. Local development

Override the API URL for local testing against a development marketplace API.

const hive = new BagdockHive({
  apiKey: 'ek_test_...',
  baseUrl: 'https://abc123.ngrok.io', // or http://localhost:3001
})

Or via environment variable (no code change needed):

BAGDOCK_API_URL=https://abc123.ngrok.io bun run dev

Note: Non-HTTPS URLs are blocked when NODE_ENV=production.

API reference

hive.chat

| Method | Description | |--------|-------------| | chat.create() | Start a new chat session | | chat.send(sessionId, { message }) | Send a message | | chat.stream(params) | Stream a chat response (SSE) | | chat.history(sessionId) | Get session history |

hive.units

| Method | Description | |--------|-------------| | units.list(params?) | List units (filter by status, size, location) | | units.get(unitId) | Get unit details | | units.book(params) | Create a rental |

hive.access

| Method | Description | |--------|-------------| | access.list(unitId) | List access codes for a unit | | access.create(params) | Generate a new access code | | access.revoke(codeId) | Revoke an access code |

hive.embedTokens

| Method | Description | |--------|-------------| | embedTokens.create(params) | Create a new embed token | | embedTokens.validate(token) | Validate a token | | embedTokens.revoke(tokenId) | Revoke a token |

Utility exports

| Export | Description | |--------|-------------| | HiveChatTransport | AI SDK ChatTransport for useChat integration | | BagdockHiveError | Typed error class with status, code, requestId | | detectKeyType(key) | Returns 'embed', 'restricted', 'webhook', or 'unknown' | | isTestKey(key) | true if key contains _test_ | | isLiveKey(key) | true if key contains _live_ | | scrubPii(text) | Redact PII from a single string (re-exported from @bagdock/pii-patterns) | | scrubPiiDeep(value) | Recursively scrub PII from objects and arrays | | scrubMessagesForModel(messages) | Scrub PII from user role messages before AI inference |

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Required. Your Bagdock API key (ek_* or rk_*) | | baseUrl | string | https://api.bagdock.com | API base URL | | maxRetries | number | 3 | Max retries for failed requests | | timeoutMs | number | 30000 | Request timeout in milliseconds | | auth | AuthAdapterConfig | — | Pluggable auth provider config |

Auth providers

// Clerk
{ provider: 'clerk', getToken: () => clerk.session?.getToken() ?? '' }

// Auth0
{ provider: 'auth0', domain: 'my-app.us.auth0.com', clientId: '...' }

// Stytch
{ provider: 'stytch' }

// Custom JWT
{ provider: 'custom', getToken: async () => myJwt }

Security

• HTTPS enforced in production — the SDK throws if a non-https:// base URL is used when NODE_ENV=production
• Client-side PII scrubbing — chat.create(), chat.send(), chat.stream(), and HiveChatTransport automatically scrub PII from user messages before they leave your application (defense-in-depth via @bagdock/pii-patterns). Server-side WASM scrubbing remains authoritative.
• Embed keys (ek_*) are origin-locked and safe for client-side use
• Restricted keys (rk_*) should only be used server-side
• Never expose rk_* or whsec_* keys in client-side code

License

MIT