API Reference

Every page in this section is generated by TypeDoc from the packages' real src/index.ts on every build — not hand-transcribed. If a symbol appears here, it is exported by the published 0.1.0 package; if it does not appear here, it does not exist.

The six packages split into three layers:

Layer	Package	Owns
Core	@idhub/identity-core	The canonical anonymous id, the state machine, the IdentityProvider contract
Providers	@idhub/identity-provider-segment	Segment identify / track / page fan-out
Providers	@idhub/identity-provider-launchdarkly	LaunchDarkly multi-kind context on every identify
Providers	@idhub/identity-provider-fullstory	FullStory setIdentity / anonymize
Adapters	@idhub/identity-adapter-nextjs	Edge middleware, React context, useIdentity()
Adapters	@idhub/identity-adapter-angular	IdentityModule.forRoot(), IdentityService, Express/SSR middleware

Providers never import each other, and the core never imports a provider — the only shared vocabulary is identity-core's IdentityProvider interface.

Import cheat sheet

@idhub/identity-core

The factory, the state machine types, and the cookie primitives every adapter is built on.

import {
  createIdentityClient,
  DEFAULT_ANONYMOUS_ID_COOKIE_NAME,
  DEFAULT_ANONYMOUS_ID_MAX_AGE,
  applyAnonymousIdCookie,
  generateAnonymousId,
  getAnonymousIdBrowser,
  getAnonymousIdFromHeaders,
  getOrCreateAnonymousIdBrowser,
  getOrCreateAnonymousIdFromRequest,
  parseCookieHeader,
  resolveCookieConfig,
  serializeAnonymousIdCookie,
  writeAnonymousIdBrowser,
} from "@idhub/identity-core";

import type {
  AnonymousId,
  AnonymousIdCookieConfig,
  AnonymousIdFromRequest,
  CreateIdentityClient,
  IdentityClient,
  IdentityClientConfig,
  IdentityEvent,
  IdentityProvider,
  IdentityState,
  IdentityWarningCode,
  ResolvedAnonymousIdCookieConfig,
  Traits,
  UserId,
} from "@idhub/identity-core";

createIdentityClient(config) returns the single object your app talks to:

import { createIdentityClient } from "@idhub/identity-core";

const identity = createIdentityClient({ providers: [] });

identity.identify("user_123", { plan: "pro" });
identity.track("Checkout Started", { cartValue: 42 });
identity.page("Pricing");
identity.getState(); // { status: 'anonymous' | 'identified', anonymousId, … }
identity.reset();

@idhub/identity-provider-segment

import { segmentProvider } from "@idhub/identity-provider-segment";
import type {
  SegmentAliasMessage,
  SegmentAnalyticsClient,
  SegmentIdentifyMessage,
  SegmentPageMessage,
  SegmentProviderConfig,
  SegmentTrackMessage,
} from "@idhub/identity-provider-segment";

The Segment SDK is a peer dependency you construct yourself — the provider takes the already-built client:

import { segmentProvider } from "@idhub/identity-provider-segment";

const provider = segmentProvider({
  client: analytics, // anything matching SegmentAnalyticsClient
  writeKey: process.env.SEGMENT_WRITE_KEY!,
  useAlias: false, // opt-in only; identify() alone is Segment's default guidance
});

@idhub/identity-provider-launchdarkly

import { launchDarklyProvider } from "@idhub/identity-provider-launchdarkly";
import type {
  ExtraContextKind,
  LaunchDarklyProviderConfig,
} from "@idhub/identity-provider-launchdarkly";

const provider = launchDarklyProvider({
  clientSideId: process.env.NEXT_PUBLIC_LD_CLIENT_ID!,
  extraContextKinds: [{ kind: "organization", key: "org_42" }],
});

This provider constructs its own LDClient lazily via the peer SDK's initialize(clientSideId, context). The removed alias-user call is never used; a multi-kind user + device context is sent on every identify() instead.

@idhub/identity-provider-fullstory

import { fullStoryProvider } from "@idhub/identity-provider-fullstory";
import type {
  FullStoryFunction,
  FullStoryProviderConfig,
} from "@idhub/identity-provider-fullstory";

const provider = fullStoryProvider({ orgId: "ABC123" });

onAnonymous is a deliberate no-op (FullStory's own guidance is never to identify anonymous state); onIdentify issues FS('setIdentity', …) and onReset issues FS('anonymize').

@idhub/identity-adapter-nextjs

Three entry points. The package root is the React client surface:

import { IdentityProvider, useIdentity } from "@idhub/identity-adapter-nextjs";
import type {
  IdentityProviderProps,
  UseIdentityResult,
} from "@idhub/identity-adapter-nextjs";

/middleware is Edge-runtime safe and holds the cookie guarantee:

import {
  applyAnonymousIdCookie,
  identityMiddleware,
  withIdentity,
} from "@idhub/identity-adapter-nextjs/middleware";
import type {
  IdentityMiddlewareConfig,
  IdentityMiddlewareResult,
} from "@idhub/identity-adapter-nextjs/middleware";

/server is the Server Component read path — no React, no next value import:

import {
  DEFAULT_ANONYMOUS_ID_COOKIE_NAME,
  getAnonymousIdFromCookies,
  getAnonymousIdFromHeaders,
  resolveCookieConfig,
} from "@idhub/identity-adapter-nextjs/server";
import type { AnonymousIdCookieStore } from "@idhub/identity-adapter-nextjs/server";

note

The React component exported as IdentityProvider is not the same thing as identity-core's IdentityProvider interface (the vendor contract). The adapter deliberately does not re-export the interface from its root, to avoid the name collision — import the contract from @idhub/identity-core when you are writing your own provider.

@idhub/identity-adapter-angular

import {
  IDENTITY_CONFIG,
  IDENTITY_ID_HEADER,
  IdentityHttpInterceptor,
  IdentityModule,
  IdentityService,
  identityInitializerFactory,
} from "@idhub/identity-adapter-angular";
import type { IdentityModuleConfig } from "@idhub/identity-adapter-angular";

identity-core's state types are re-exported so an Angular app only needs the one dependency:

import type {
  AnonymousId,
  AnonymousIdCookieConfig,
  IdentityEvent,
  IdentityProvider,
  IdentityState,
  IdentityWarningCode,
  Traits,
  UserId,
} from "@idhub/identity-adapter-angular";

/server holds the Angular Universal / SSR companion middleware:

import { identityExpressMiddleware } from "@idhub/identity-adapter-angular/server";
import type {
  IdentityExpressMiddlewareConfig,
  IdentityRequestLike,
  IdentityResponseLike,
} from "@idhub/identity-adapter-angular/server";

Keeping these pages honest

Two guards run against this documentation:

1. Generation. The per-package pages are produced by TypeDoc from source during pnpm --filter docs build, so a renamed or removed export changes the docs in the same commit that changes the code.
2. Verification. pnpm --filter docs verify-samples walks every .md / .mdx page on this site, extracts each fenced code block containing an import … from "@idhub/…" statement, and checks every imported name against the corresponding package's built build/esm/*.d.ts. A sample that references a symbol the package does not export fails the check.