sessionhero-sdk

Public TypeScript SDK for Session Hero integrations. Ships:

• Open API client — typed access to /api/v1/open/* (topics, campaigns, embed tokens, controls)
• Env helpers — reads required API keys from the environment
• Session Player embed — drop-in Next.js Session Player + withSessionsEmbed()

npm install sessionhero-sdk

Required environment variables

| Variable | Used by | Purpose | |----------|---------|---------| | SESSIONS_OPEN_API_KEY | Open API client (server only) | Organisation Open API app key | | NEXT_PUBLIC_SESSIONS_APP_API_KEY | Session Player embed (browser) | Session Hero core/app key for guest conduct | | SESSIONS_ORGANISATION_ID | Open API client (optional) | Sent as X-Organisation-ID | | SESSIONS_API_BASE_URL | Open API client | API origin (default http://localhost:8080) | | NEXT_PUBLIC_API_BASE_URL | Embed | Browser API base (e.g. /sessions-api) |

Never put SESSIONS_OPEN_API_KEY in a NEXT_PUBLIC_* variable.

createSessionHeroClient() throws if SESSIONS_OPEN_API_KEY is missing.
Live Session Player throws / fails closed if NEXT_PUBLIC_SESSIONS_APP_API_KEY is missing. Mock mode does not need the core key.

Open API (server)

import { createSessionHeroClient } from "sessionhero-sdk";

const client = createSessionHeroClient(); // requires SESSIONS_OPEN_API_KEY

const topics = await client.listPublicTopics({ page: 1, page_size: 50 });
const { token } = await client.mintEmbedAccessToken(campaignId, topicId);

Session Player embed (Next.js)

// next.config.ts
import path from "path";
import type { NextConfig } from "next";
import { withSessionsEmbed } from "sessionhero-sdk/next";

const nextConfig: NextConfig = { /* … */ };

export default withSessionsEmbed(nextConfig, {
  hostDir: __dirname,
  // Optional host-only aliases:
  // hostAliases: { "@admin": path.join(__dirname, "app") },
});

import { SessionPlayer, embedTopicPlayerSeed } from "sessionhero-sdk/embed";
import { createSessionHeroClient } from "sessionhero-sdk";

const topic = await createSessionHeroClient().getTopic(topicId);

<SessionPlayer
  topicId={topic.id}
  organisationId={orgId}
  embeddedTopic={embedTopicPlayerSeed(topic)}
  className="h-[min(720px,80vh)] w-full"
/>

See sessions-fe-next/embed/INTEGRATION.md and organisation admin Docs → TypeScript SDK for full host setup.

Subpath exports

| Import | Contents | |--------|----------| | sessionhero-sdk | Open API client + env + types | | sessionhero-sdk/open-api | Open API only | | sessionhero-sdk/embed | React Session Player + helpers | | sessionhero-sdk/next | withSessionsEmbed() |

Monorepo / local development

From the Session Hero monorepo:

cd sessions-integrate-sdk
npm run prepare-package   # vendors sessions-fe-next embed+app into runtime/

Hosts may use "sessionhero-sdk": "file:../sessions-integrate-sdk" while iterating. postinstall runs prepare-package when a sibling sessions-fe-next is present.

Publishing

Requires npm org ownership of @session-hero and an NPM_TOKEN secret.

npm run prepare-package
npm publish --access public

Or push a v* tag to run .github/workflows/publish.yml.