@idhub/identity-core

Interfaces

AnonymousIdCookieConfig

Defined in: types.ts:40

Properties

domain?

optional domain?: string

Defined in: types.ts:44

Cookie domain, e.g. '.example.com' for cross-subdomain sharing.

httpOnly?

optional httpOnly?: boolean

Defined in: types.ts:48

Must stay readable by vendor client SDKs. Default: false.

maxAge?

optional maxAge?: number

Defined in: types.ts:46

Seconds. Default: 31536000 (1 year).

name?

optional name?: string

Defined in: types.ts:42

Cookie name. Default: '_anon_id'.

sameSite?

optional sameSite?: "Strict" | "Lax" | "None"

Defined in: types.ts:50

Default: 'Lax'.

secure?

optional secure?: boolean

Defined in: types.ts:52

Default: true in production, false in local dev over http.

---

AnonymousIdFromRequest

Defined in: cookie.ts:91

Properties

anonymousId

anonymousId: AnonymousId

Defined in: cookie.ts:93

The id read from the incoming cookie, or a freshly generated one.

created

created: boolean

Defined in: cookie.ts:98

True when no usable cookie was present and a new id was generated.

setCookieHeader

setCookieHeader: string

Defined in: cookie.ts:96

Value to append as a Set-Cookie response header. Always returned so the 1-year window slides forward on every request.

---

IdentityClient

Defined in: types.ts:98

Methods

getState()

getState(): IdentityState

Defined in: types.ts:116

Current snapshot — used by adapters for SSR hydration and by useIdentity()/IdentityService for initial render.

Returns

IdentityState

identify()

identify(userId, traits?): void

Defined in: types.ts:102

Fans out to every provider's onIdentify. No-op with a dev warning if called again with a different userId while already identified (see IdentityWarningCode.reidentify_with_different_user_id).

Parameters

userId

string

traits?

Traits

Returns

void

page()

page(name?, properties?): void

Defined in: types.ts:112

Fans out to every provider's onPage.

Parameters

name?

string

properties?

Traits

Returns

void

reset()

reset(): void

Defined in: types.ts:105

Generates a fresh anonymousId, fans out to every provider's onReset.

Returns

void

subscribe()

subscribe(listener): () => void

Defined in: types.ts:120

Adapters (React context, Angular Observable) subscribe here instead of polling getState(). Returns an unsubscribe function.

Parameters

listener

(event, state) => void

Returns

() => void

track()

track(event, properties?): void

Defined in: types.ts:109

Fans out to every provider's onTrack (skipped for providers that don't implement it).

Parameters

event

string

properties?

Traits

Returns

void

---

IdentityClientConfig

Defined in: types.ts:90

Properties

cookie?

optional cookie?: AnonymousIdCookieConfig

Defined in: types.ts:92

onWarning?

optional onWarning?: (code, message) => void

Defined in: types.ts:95

Called for every IdentityEvent of type 'warning'. Defaults to console.warn in development, no-op in production.

Parameters

code

IdentityWarningCode

message

string

Returns

void

providers

providers: IdentityProvider[]

Defined in: types.ts:91

---

IdentityProvider

Defined in: types.ts:60

Every vendor package (identity-provider-segment, -launchdarkly, -fullstory, or a future 4th vendor) implements exactly this interface. identity-core never imports a concrete provider — only this shape.

Properties

name

readonly name: string

Defined in: types.ts:62

Unique name for logging/debugging, e.g. 'segment'.

Methods

onAnonymous()

onAnonymous(anonymousId): void | Promise<void>

Defined in: types.ts:67

Called once, as early as possible, before the user is known. Segment/LaunchDarkly use this; FullStory's implementation is a documented no-op (see provider table).

Parameters

anonymousId

AnonymousId

Returns

void | Promise<void>

onIdentify()

onIdentify(userId, anonymousId, traits?): void | Promise<void>

Defined in: types.ts:73

Called exactly once per login/registration. Implementations must be idempotent if called twice with the SAME userId (e.g. traits update), but IdentityClient guards against calls with a DIFFERENT userId while already identified (see IdentityClientConfig.onWarning).

Parameters

userId

string

anonymousId

AnonymousId

traits?

Traits

Returns

void | Promise<void>

onPage()?

optional onPage(name?, properties?): void | Promise<void>

Defined in: types.ts:85

Optional: page-view tracking, same rationale as onTrack.

Parameters

name?

string

properties?

Traits

Returns

void | Promise<void>

onReset()

onReset(newAnonymousId): void | Promise<void>

Defined in: types.ts:77

Called on logout. Receives the newly generated anonymous id (the old one is intentionally not passed — providers must not persist it).

Parameters

newAnonymousId

AnonymousId

Returns

void | Promise<void>

onTrack()?

optional onTrack(event, properties?): void | Promise<void>

Defined in: types.ts:82

Optional: only implement if the vendor has an event-tracking API distinct from identify (Segment/FullStory track events; a future flag-only provider might omit this entirely).

Parameters

event

string

properties?

Traits

Returns

void | Promise<void>

---

ResolvedAnonymousIdCookieConfig

Defined in: cookie.ts:10

Fully-resolved cookie settings — every optional field defaulted.

Properties

domain?

optional domain?: string

Defined in: cookie.ts:12

httpOnly

httpOnly: boolean

Defined in: cookie.ts:14

maxAge

maxAge: number

Defined in: cookie.ts:13

name

name: string

Defined in: cookie.ts:11

sameSite

sameSite: "Strict" | "Lax" | "None"

Defined in: cookie.ts:15

secure

secure: boolean

Defined in: cookie.ts:16

Type Aliases

AnonymousId

AnonymousId = string & object

Defined in: types.ts:9

Canonical anonymous id. Branded so it can't be silently mixed up with a plain userId string at call sites.

Type Declaration

__brand

readonly __brand: "AnonymousId"

---

CreateIdentityClient

CreateIdentityClient = (config) => IdentityClient

Defined in: types.ts:127

Signature of the createIdentityClient(config) factory declared in the plan's Appendix A. The runtime implementation lives in ./client.ts; this alias keeps the signature itself part of the shared type contract so adapter packages can type against the factory without importing it.

Parameters

config

IdentityClientConfig

Returns

IdentityClient

---

IdentityEvent

IdentityEvent = { anonymousId: AnonymousId; type: "anonymous_id_created"; } | { anonymousId: AnonymousId; traits?: Traits; type: "identified"; userId: UserId; } | { anonymousId: AnonymousId; previousAnonymousId: AnonymousId; type: "reset"; } | { event: string; properties?: Traits; type: "track"; } | { name?: string; properties?: Traits; type: "page"; } | { code: IdentityWarningCode; message: string; type: "warning"; }

Defined in: types.ts:22

Emitted on every state transition; adapters subscribe to drive React context / Angular Observable updates.

Union Members

Type Literal

{ anonymousId: AnonymousId; type: "anonymous_id_created"; }

---

Type Literal

{ anonymousId: AnonymousId; traits?: Traits; type: "identified"; userId: UserId; }

---

Type Literal

{ anonymousId: AnonymousId; previousAnonymousId: AnonymousId; type: "reset"; }

---

Type Literal

{ event: string; properties?: Traits; type: "track"; }

---

Type Literal

{ name?: string; properties?: Traits; type: "page"; }

---

Type Literal

{ code: IdentityWarningCode; message: string; type: "warning"; }

Dev-mode-only warning event, e.g. re-identify with a different userId while already identified (see Risks: FullStory split-not-merge). Never fired in production builds.

---

IdentityState

IdentityState = { anonymousId: AnonymousId; status: "anonymous"; } | { anonymousId: AnonymousId; status: "identified"; traits?: Traits; userId: UserId; }

Defined in: types.ts:16

---

IdentityWarningCode

IdentityWarningCode = "reidentify_with_different_user_id" | "provider_init_failed" | "track_before_ready"

Defined in: types.ts:33

---

Traits

Traits = Record<string, string | number | boolean | null | undefined>

Defined in: types.ts:5

Free-form traits attached to a user or event. Vendor packages map this onto their own SDK's trait/property shape internally.

---

UserId

UserId = string

Defined in: types.ts:12

Vendor-supplied known user id (e.g. memberId, sub claim).

Variables

DEFAULT_ANONYMOUS_ID_COOKIE_NAME

const DEFAULT_ANONYMOUS_ID_COOKIE_NAME: "_anon_id" = "_anon_id"

Defined in: cookie.ts:4

Default cookie name for the canonical anonymous id.

---

DEFAULT_ANONYMOUS_ID_MAX_AGE

const DEFAULT_ANONYMOUS_ID_MAX_AGE: 31536000 = 31536000

Defined in: cookie.ts:7

One year, in seconds.

Functions

applyAnonymousIdCookie()

applyAnonymousIdCookie(response, setCookieHeader): Response

Defined in: cookie.ts:130

Convenience: append the Set-Cookie header onto an outgoing Response.

Parameters

response

Response

setCookieHeader

string

Returns

Response

---

createIdentityClient()

createIdentityClient(config): IdentityClient

Defined in: client.ts:44

Creates the single object app code talks to. Every call fans out to every registered provider; the client owns the canonical anonymous id and the anonymous <-> identified state machine, and knows nothing about any vendor.

Warning semantics (plan Appendix A + Risks table): calling identify() a second time with a DIFFERENT userId while already identified is treated as a bug — it is a no-op (no provider fan-out, state keeps the ORIGINAL userId) and emits the reidentify_with_different_user_id warning. The no-op guard is unconditional; only the warning itself is dev-mode-only, so dev and production behave identically apart from the diagnostic. Re-identifying with the SAME userId (e.g. a traits update) passes through normally and is expected to be idempotent at the provider level.

Parameters

config

IdentityClientConfig

Returns

IdentityClient

---

generateAnonymousId()

generateAnonymousId(): AnonymousId

Defined in: cookie.ts:48

Generates a canonical anonymous id using the Web Standard crypto global, so this works unchanged in Edge middleware, Workers, Node and browsers.

Returns

AnonymousId

---

getAnonymousIdBrowser()

getAnonymousIdBrowser(config?): AnonymousId | undefined

Defined in: cookie.ts:146

Reads the anonymous id from document.cookie, if present.

Parameters

config?

AnonymousIdCookieConfig = {}

Returns

AnonymousId | undefined

---

getAnonymousIdFromHeaders()

getAnonymousIdFromHeaders(headers, config?): AnonymousId | undefined

Defined in: cookie.ts:102

Reads the anonymous id from a Headers object, if present.

Parameters

headers

Headers

config?

AnonymousIdCookieConfig = {}

Returns

AnonymousId | undefined

---

getOrCreateAnonymousIdBrowser()

getOrCreateAnonymousIdBrowser(config?): AnonymousId

Defined in: cookie.ts:172

Browser entry point: read the canonical anonymous id from document.cookie (typically already set by the server/middleware), generating and persisting one only if it is missing. Outside a browser this still returns a usable id — it just has nowhere to persist it.

Parameters

config?

AnonymousIdCookieConfig = {}

Returns

AnonymousId

---

getOrCreateAnonymousIdFromRequest()

getOrCreateAnonymousIdFromRequest(request, config?): AnonymousIdFromRequest

Defined in: cookie.ts:116

Edge/middleware entry point: read the canonical anonymous id off the incoming request, generating one if it isn't there yet. Uses only Web Standard APIs (Headers, crypto.randomUUID) — no Node-only imports.

Parameters

request

Request

config?

AnonymousIdCookieConfig = {}

Returns

AnonymousIdFromRequest

---

parseCookieHeader()

parseCookieHeader(header): Record<string, string>

Defined in: cookie.ts:53

Parses a Cookie: request header value into a name -> value map.

Parameters

header

string | null | undefined

Returns

Record<string, string>

---

resolveCookieConfig()

resolveCookieConfig(config?): ResolvedAnonymousIdCookieConfig

Defined in: cookie.ts:30

Applies the documented defaults from AnonymousIdCookieConfig.

Parameters

config?

AnonymousIdCookieConfig = {}

Returns

ResolvedAnonymousIdCookieConfig

---

serializeAnonymousIdCookie()

serializeAnonymousIdCookie(anonymousId, config?): string

Defined in: cookie.ts:72

Builds a Set-Cookie header value for the anonymous id cookie.

Parameters

anonymousId

AnonymousId

config?

AnonymousIdCookieConfig = {}

Returns

string

---

writeAnonymousIdBrowser()

writeAnonymousIdBrowser(anonymousId, config?): void

Defined in: cookie.ts:157

Writes the anonymous id to document.cookie. No-op outside a browser.

Parameters

anonymousId

AnonymousId

config?

AnonymousIdCookieConfig = {}

Returns

void