@idhub/identity-core

The framework-agnostic, vendor-agnostic core of the identity resolution stack. Zero runtime dependencies. No React, no Angular, no vendor SDK.

It owns exactly three things:

1. the canonical anonymous id — one id in one first-party cookie, generated upstream of every vendor SDK;
2. the identity state machine — anonymous ⇄ identified;
3. the provider registry + fan-out — every call reaches every registered provider.

Install

npm install @idhub/identity-core

Usage

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

const identity = createIdentityClient({
  providers: [segmentProvider(...), launchDarklyProvider(...), fullStoryProvider(...)],
  cookie: { domain: ".example.com" },
});

identity.identify("member-123", { plan: "pro" }); // once, at login
identity.track("Checkout Started", { cartValue: 99 });
identity.page("Pricing");
identity.reset();                                  // at logout

const unsubscribe = identity.subscribe((event, state) => {
  console.log(event.type, state.status);
});

Anonymous id, before any vendor loads

Edge middleware / any Web-Standard Request context:

import {
  getOrCreateAnonymousIdFromRequest,
  applyAnonymousIdCookie,
} from "@idhub/identity-core";

export function middleware(request: Request) {
  const { anonymousId, setCookieHeader } = getOrCreateAnonymousIdFromRequest(request);
  return applyAnonymousIdCookie(NextResponse.next(), setCookieHeader);
}

Browser context:

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

const anonymousId = getOrCreateAnonymousIdBrowser();

These are two separate functions on purpose. Nothing here sniffs the environment and guesses — the caller picks the one that matches its context. The Request-mode function uses only Web Standard APIs (Headers, crypto.randomUUID()), so it is Edge/Workers safe.

Behavior contract

Startup

createIdentityClient() resolves the anonymous id (reading the cookie the server/middleware already set, or minting and persisting one), enters the anonymous state, and immediately fans onAnonymous(anonymousId) out to every provider. Every vendor therefore sees the same id from its very first call — there is no leader/follower race between vendors.

identify(userId, traits)

Fans onIdentify(userId, anonymousId, traits) out to every provider and moves to the identified state.

| Call | Behavior | | --- | --- | | First identify | Fan-out, state → identified. | | identify again, same userId | Passes through normally. Fan-out happens again — this is the supported trait-update path, and providers are required to be idempotent for it. | | identify again, different userId, while identified | No-op. No provider is called, and state keeps the original userId and traits. A reidentify_with_different_user_id warning is emitted. |

That last row is the documented resolution of the plan's warning semantics. Re-identifying mid-session is almost always a bug, and silently letting it through is actively destructive: FullStory's setIdentity is write-once per session, so a second uid splits the session into a new one rather than merging. Refusing the call keeps every vendor consistent with the state the client reports. To legitimately switch users, call reset() first.

The no-op guard is unconditional — it applies in production exactly as in development. Only the warning is dev-mode-only, so behavior never diverges between builds.

reset()

Generates a fresh anonymous id, persists it, moves to anonymous, and fans onReset(newAnonymousId) out to every provider. The pre-logout id is passed to nobody and is not reachable from getState() afterward — a second person on a shared device cannot inherit the first person's anonymous history.

track() / page()

Fanned out to every provider that implements the optional onTrack / onPage. Providers that omit them (a flag-only vendor, say) are skipped silently.

Warnings

IdentityWarningCode is reidentify_with_different_user_id, provider_init_failed, or track_before_ready. Warnings are emitted both as a { type: 'warning' } event to subscribers and to config.onWarning, which defaults to console.warn. Per the type contract, warnings are never fired in production builds (process.env.NODE_ENV === 'production', checked isomorphically — runtimes with no process global are treated as non-production).

Provider isolation

One vendor SDK throwing (or returning a rejected promise) never stops the remaining providers from being notified. The failure surfaces as a provider_init_failed warning naming the provider.

Cookie defaults

| Option | Default | | --- | --- | | name | _anon_id | | maxAge | 31536000 (1 year) | | httpOnly | false — must stay readable by vendor client SDKs | | sameSite | Lax | | secure | true in production, false otherwise | | domain | unset (host-only); set .example.com to share across subdomains |

Scripts

pnpm --filter @idhub/identity-core build      # tsup -> build/esm + build/cjs
pnpm --filter @idhub/identity-core test       # vitest run
pnpm --filter @idhub/identity-core typecheck  # tsc --noEmit