:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { DateTime } from 'luxon'
import { Properties } from '~/plugin-scaffold'
import { InternalPerson, PropertiesLastOperation, PropertiesLastUpdatedAt } from '~/types'
export interface PersonUpdate {
id: string // bigint ID from database as string
team_id: number
uuid: string
distinct_id: string
properties: Properties // The properties this pod last read or landed
properties_last_updated_at: PropertiesLastUpdatedAt
properties_last_operation: PropertiesLastOperation
created_at: DateTime
/** The row version the base reflects, from the newest write answer or row read the entry has taken. */
version: number
is_identified: boolean
is_user_id: number | null
last_seen_at: DateTime | null
needs_write: boolean
// Fine-grained property tracking
properties_to_set: Properties // Properties to set/update
properties_to_set_once: Properties // Properties to set only where the row has none
properties_to_unset: string[] // Property keys to unset
original_is_identified: boolean
original_created_at: DateTime
original_last_seen_at: DateTime | null
/** If true, bypass batch-level filtering for person property updates (set for $identify, $set, etc.) */
force_update?: boolean
/** Set on a record a flush re-targeted after its person was merged away; its lanes are then the only carrier. */
retargeted?: boolean
}
/** A merge's write to the survivor; `properties` holds only the keys to set. Identity and version are the row's. */
export type MergePersonUpdate = Omit<Partial<InternalPerson>, 'id' | 'uuid' | 'team_id' | 'version'> & {
properties_to_set_once?: Properties
properties_to_unset?: string[]
}
export type PendingPersonChanges = { toSet: Properties; toSetOnce: Properties; toUnset: string[]; createdAt: DateTime }
export interface PersonPropertyUpdate {
updated: boolean
properties: Properties
properties_last_updated_at: PropertiesLastUpdatedAt
properties_last_operation: PropertiesLastOperation
}
export function fromInternalPerson(person: InternalPerson, distinctId: string): PersonUpdate {
return {
id: person.id,
team_id: person.team_id,
uuid: person.uuid,
distinct_id: distinctId,
properties: person.properties,
properties_last_updated_at: person.properties_last_updated_at,
properties_last_operation: person.properties_last_operation || {},
created_at: person.created_at,
version: person.version,
is_identified: person.is_identified,
is_user_id: person.is_user_id,
last_seen_at: person.last_seen_at,
needs_write: false,
properties_to_set: {},
properties_to_set_once: {},
properties_to_unset: [],
original_is_identified: person.is_identified,
original_created_at: person.created_at,
original_last_seen_at: person.last_seen_at,
force_update: false, // Default to false, can be set to true by $identify/$set events
}
}
export function toInternalPerson(personUpdate: PersonUpdate): InternalPerson {
// Calculate final properties by applying set and unset operations
const finalProperties = { ...personUpdate.properties }
for (const [key, value] of Object.entries(personUpdate.properties_to_set_once)) {
if (!Object.hasOwn(finalProperties, key)) {
finalProperties[key] = value
}
}
// Apply properties to set
Object.entries(personUpdate.properties_to_set).forEach(([key, value]) => {
finalProperties[key] = value
})
// Apply properties to unset
personUpdate.properties_to_unset.forEach((key) => {
delete finalProperties[key]
})
return {
id: personUpdate.id, // Use the actual database ID, not the UUID
uuid: personUpdate.uuid,
team_id: personUpdate.team_id,
properties: finalProperties,
properties_last_updated_at: personUpdate.properties_last_updated_at,
properties_last_operation: personUpdate.properties_last_operation,
created_at: personUpdate.created_at,
version: personUpdate.version,
is_identified: personUpdate.is_identified,
is_user_id: personUpdate.is_user_id,
last_seen_at: personUpdate.last_seen_at,
}
}