@posthog/core 1.18.0 → 1.20.0

package/dist/posthog-core.d.ts

@@ -10,6 +10,7 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     private _sessionMaxLengthSeconds;
     protected sessionProps: PostHogEventProperties;
     protected _personProfiles: 'always' | 'identified_only' | 'never';
+    protected _cachedPersonProperties: string | null;
     constructor(apiKey: string, options?: PostHogCoreOptions);
     protected setupBootstrap(options?: Partial<PostHogCoreOptions>): void;
     private clearProps;
@@ -73,8 +74,8 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
      * PROPERTIES
      ***/
     setPersonPropertiesForFlags(properties: {
-        [type: string]: string;
-    }): void;
+        [type: string]: JsonType;
+    }, reloadFeatureFlags?: boolean): void;
     resetPersonPropertiesForFlags(): void;
     setGroupPropertiesForFlags(properties: {
         [type: string]: Record<string, string>;
@@ -223,6 +224,47 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
      * @public
      */
     createPersonProfile(): void;
+    /**
+     * Sets properties on the person profile associated with the current `distinct_id`.
+     * Learn more about [identifying users](https://posthog.com/docs/product-analytics/identify)
+     *
+     * {@label Identification}
+     *
+     * @remarks
+     * Updates user properties that are stored with the person profile in PostHog.
+     * If `personProfiles` is set to `identified_only` and no profile exists, this will create one.
+     *
+     * @example
+     * ```js
+     * // set user properties
+     * posthog.setPersonProperties({
+     *     email: 'user@example.com',
+     *     plan: 'premium'
+     * })
+     * ```
+     *
+     * @example
+     * ```js
+     * // set properties with $set_once
+     * posthog.setPersonProperties(
+     *     { name: 'Max Hedgehog' },  // $set properties
+     *     { initial_url: '/blog' }   // $set_once properties
+     * )
+     * ```
+     *
+     * @public
+     *
+     * @param userPropertiesToSet - Optional: An object of properties to store about the user.
+     *   These properties will overwrite any existing values for the same keys.
+     * @param userPropertiesToSetOnce - Optional: An object of properties to store about the user.
+     *   If a property is previously set, this does not override that value.
+     * @param reloadFeatureFlags - Whether to reload feature flags after setting the properties. Defaults to true.
+     */
+    setPersonProperties(userPropertiesToSet?: {
+        [key: string]: JsonType;
+    }, userPropertiesToSetOnce?: {
+        [key: string]: JsonType;
+    }, reloadFeatureFlags?: boolean): void;
     /**
      * Override processBeforeEnqueue to run before_send hooks.
      * This runs after prepareMessage, giving users full control over the final event.

package/dist/posthog-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"posthog-core.d.ts","sourceRoot":"","sources":["../src/posthog-core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"posthog-core.d.ts","sourceRoot":"","sources":["../src/posthog-core.ts"],"names":[],"mappings":"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"}

package/dist/posthog-core.js

@@ -39,7 +39,7 @@ class PostHogCore extends external_posthog_core_stateless_js_namespaceObject.Pos
             ...options,
             disableGeoip: disableGeoipOption,
             featureFlagsRequestTimeoutMs
-        }), this.flagCallReported = {}, this._sessionMaxLengthSeconds = 86400, this.sessionProps = {};
+        }), this.flagCallReported = {}, this._sessionMaxLengthSeconds = 86400, this.sessionProps = {}, this._cachedPersonProperties = null;
         this.sendFeatureFlagEvent = options?.sendFeatureFlagEvent ?? true;
         this._sessionExpirationTimeSeconds = options?.sessionExpirationTimeSeconds ?? 1800;
         this._personProfiles = options?.personProfiles ?? 'identified_only';
@@ -94,6 +94,7 @@ class PostHogCore extends external_posthog_core_stateless_js_namespaceObject.Pos
                 ...propertiesToKeep || []
             ];
             this.clearProps();
+            this._cachedPersonProperties = null;
             for (const key of Object.keys(external_types_js_namespaceObject.PostHogPersistedProperty))if (!allPropertiesToKeep.includes(external_types_js_namespaceObject.PostHogPersistedProperty[key])) this.setPersistedProperty(external_types_js_namespaceObject.PostHogPersistedProperty[key], null);
             this.reloadFeatureFlags();
         });
@@ -176,13 +177,16 @@ class PostHogCore extends external_posthog_core_stateless_js_namespaceObject.Pos
                 ...(0, external_posthog_core_stateless_js_namespaceObject.maybeAdd)('$set', userProps),
                 ...(0, external_posthog_core_stateless_js_namespaceObject.maybeAdd)('$set_once', userPropsOnce)
             });
+            const userPropsObj = (0, index_js_namespaceObject.isObject)(userProps) ? userProps : void 0;
+            const userPropsOnceObj = (0, index_js_namespaceObject.isObject)(userPropsOnce) ? userPropsOnce : void 0;
             if (distinctId !== previousDistinctId) {
                 this.setPersistedProperty(external_types_js_namespaceObject.PostHogPersistedProperty.AnonymousId, previousDistinctId);
                 this.setPersistedProperty(external_types_js_namespaceObject.PostHogPersistedProperty.DistinctId, distinctId);
                 this.setPersistedProperty(external_types_js_namespaceObject.PostHogPersistedProperty.PersonMode, 'identified');
                 this.reloadFeatureFlags();
-            }
-            super.identifyStateless(distinctId, allProperties, options);
+                super.identifyStateless(distinctId, allProperties, options);
+                this._cachedPersonProperties = (0, index_js_namespaceObject.getPersonPropertiesHash)(distinctId, userPropsObj, userPropsOnceObj);
+            } else if (userPropsObj || userPropsOnceObj) this.setPersonProperties(userPropsObj, userPropsOnceObj);
         });
     }
     capture(event, properties, options) {
@@ -249,13 +253,14 @@ class PostHogCore extends external_posthog_core_stateless_js_namespaceObject.Pos
             super.groupIdentifyStateless(groupType, groupKey, groupProperties, options, distinctId, eventProperties);
         });
     }
-    setPersonPropertiesForFlags(properties) {
+    setPersonPropertiesForFlags(properties, reloadFeatureFlags = true) {
         this.wrap(()=>{
             const existingProperties = this.getPersistedProperty(external_types_js_namespaceObject.PostHogPersistedProperty.PersonProperties) || {};
             this.setPersistedProperty(external_types_js_namespaceObject.PostHogPersistedProperty.PersonProperties, {
                 ...existingProperties,
                 ...properties
             });
+            if (reloadFeatureFlags) this.reloadFeatureFlags();
         });
     }
     resetPersonPropertiesForFlags() {
@@ -628,6 +633,26 @@ class PostHogCore extends external_posthog_core_stateless_js_namespaceObject.Pos
             $set_once: {}
         });
     }
+    setPersonProperties(userPropertiesToSet, userPropertiesToSetOnce, reloadFeatureFlags = true) {
+        this.wrap(()=>{
+            const isSetEmpty = (0, index_js_namespaceObject.isNullish)(userPropertiesToSet) || (0, index_js_namespaceObject.isEmptyObject)(userPropertiesToSet);
+            const isSetOnceEmpty = (0, index_js_namespaceObject.isNullish)(userPropertiesToSetOnce) || (0, index_js_namespaceObject.isEmptyObject)(userPropertiesToSetOnce);
+            if (isSetEmpty && isSetOnceEmpty) return;
+            if (!this._requirePersonProcessing('posthog.setPersonProperties')) return;
+            const hash = (0, index_js_namespaceObject.getPersonPropertiesHash)(this.getDistinctId(), userPropertiesToSet, userPropertiesToSetOnce);
+            if (this._cachedPersonProperties === hash) return void this._logger.info('A duplicate setPersonProperties call was made with the same properties. It has been ignored.');
+            const mergedProperties = {
+                ...userPropertiesToSetOnce || {},
+                ...userPropertiesToSet || {}
+            };
+            this.setPersonPropertiesForFlags(mergedProperties, reloadFeatureFlags);
+            this.capture('$set', {
+                $set: userPropertiesToSet || {},
+                $set_once: userPropertiesToSetOnce || {}
+            });
+            this._cachedPersonProperties = hash;
+        });
+    }
     processBeforeEnqueue(message) {
         if (!this._beforeSend) return message;
         const timestamp = message.timestamp;

package/dist/posthog-core.mjs

@@ -2,7 +2,7 @@ import { createFlagsResponseFromFlagsAndPayloads, getFeatureFlagValue, getFlagVa
 import { Compression, FeatureFlagError, PostHogPersistedProperty } from "./types.mjs";
 import { PostHogCoreStateless, QuotaLimitedFeature, maybeAdd } from "./posthog-core-stateless.mjs";
 import { uuidv7 } from "./vendor/uuidv7.mjs";
-import { isPlainError } from "./utils/index.mjs";
+import { getPersonPropertiesHash, isEmptyObject, isNullish, isObject, isPlainError } from "./utils/index.mjs";
 class PostHogCore extends PostHogCoreStateless {
     constructor(apiKey, options){
         const disableGeoipOption = options?.disableGeoip ?? false;
@@ -11,7 +11,7 @@ class PostHogCore extends PostHogCoreStateless {
             ...options,
             disableGeoip: disableGeoipOption,
             featureFlagsRequestTimeoutMs
-        }), this.flagCallReported = {}, this._sessionMaxLengthSeconds = 86400, this.sessionProps = {};
+        }), this.flagCallReported = {}, this._sessionMaxLengthSeconds = 86400, this.sessionProps = {}, this._cachedPersonProperties = null;
         this.sendFeatureFlagEvent = options?.sendFeatureFlagEvent ?? true;
         this._sessionExpirationTimeSeconds = options?.sessionExpirationTimeSeconds ?? 1800;
         this._personProfiles = options?.personProfiles ?? 'identified_only';
@@ -66,6 +66,7 @@ class PostHogCore extends PostHogCoreStateless {
                 ...propertiesToKeep || []
             ];
             this.clearProps();
+            this._cachedPersonProperties = null;
             for (const key of Object.keys(PostHogPersistedProperty))if (!allPropertiesToKeep.includes(PostHogPersistedProperty[key])) this.setPersistedProperty(PostHogPersistedProperty[key], null);
             this.reloadFeatureFlags();
         });
@@ -148,13 +149,16 @@ class PostHogCore extends PostHogCoreStateless {
                 ...maybeAdd('$set', userProps),
                 ...maybeAdd('$set_once', userPropsOnce)
             });
+            const userPropsObj = isObject(userProps) ? userProps : void 0;
+            const userPropsOnceObj = isObject(userPropsOnce) ? userPropsOnce : void 0;
             if (distinctId !== previousDistinctId) {
                 this.setPersistedProperty(PostHogPersistedProperty.AnonymousId, previousDistinctId);
                 this.setPersistedProperty(PostHogPersistedProperty.DistinctId, distinctId);
                 this.setPersistedProperty(PostHogPersistedProperty.PersonMode, 'identified');
                 this.reloadFeatureFlags();
-            }
-            super.identifyStateless(distinctId, allProperties, options);
+                super.identifyStateless(distinctId, allProperties, options);
+                this._cachedPersonProperties = getPersonPropertiesHash(distinctId, userPropsObj, userPropsOnceObj);
+            } else if (userPropsObj || userPropsOnceObj) this.setPersonProperties(userPropsObj, userPropsOnceObj);
         });
     }
     capture(event, properties, options) {
@@ -221,13 +225,14 @@ class PostHogCore extends PostHogCoreStateless {
             super.groupIdentifyStateless(groupType, groupKey, groupProperties, options, distinctId, eventProperties);
         });
     }
-    setPersonPropertiesForFlags(properties) {
+    setPersonPropertiesForFlags(properties, reloadFeatureFlags = true) {
         this.wrap(()=>{
             const existingProperties = this.getPersistedProperty(PostHogPersistedProperty.PersonProperties) || {};
             this.setPersistedProperty(PostHogPersistedProperty.PersonProperties, {
                 ...existingProperties,
                 ...properties
             });
+            if (reloadFeatureFlags) this.reloadFeatureFlags();
         });
     }
     resetPersonPropertiesForFlags() {
@@ -600,6 +605,26 @@ class PostHogCore extends PostHogCoreStateless {
             $set_once: {}
         });
     }
+    setPersonProperties(userPropertiesToSet, userPropertiesToSetOnce, reloadFeatureFlags = true) {
+        this.wrap(()=>{
+            const isSetEmpty = isNullish(userPropertiesToSet) || isEmptyObject(userPropertiesToSet);
+            const isSetOnceEmpty = isNullish(userPropertiesToSetOnce) || isEmptyObject(userPropertiesToSetOnce);
+            if (isSetEmpty && isSetOnceEmpty) return;
+            if (!this._requirePersonProcessing('posthog.setPersonProperties')) return;
+            const hash = getPersonPropertiesHash(this.getDistinctId(), userPropertiesToSet, userPropertiesToSetOnce);
+            if (this._cachedPersonProperties === hash) return void this._logger.info('A duplicate setPersonProperties call was made with the same properties. It has been ignored.');
+            const mergedProperties = {
+                ...userPropertiesToSetOnce || {},
+                ...userPropertiesToSet || {}
+            };
+            this.setPersonPropertiesForFlags(mergedProperties, reloadFeatureFlags);
+            this.capture('$set', {
+                $set: userPropertiesToSet || {},
+                $set_once: userPropertiesToSetOnce || {}
+            });
+            this._cachedPersonProperties = hash;
+        });
+    }
     processBeforeEnqueue(message) {
         if (!this._beforeSend) return message;
         const timestamp = message.timestamp;

package/dist/utils/string-utils.d.ts

@@ -1,6 +1,17 @@
+import type { JsonType } from '../types';
 export declare function includes(str: string, needle: string): boolean;
 export declare function includes<T>(arr: T[], needle: T): boolean;
 export declare const trim: (str: string) => string;
 export declare const stripLeadingDollar: (s: string) => string;
 export declare function isDistinctIdStringLike(value: string): boolean;
+/**
+ * Creates a hash string from distinct_id and person properties.
+ * Used to detect if person properties have changed to avoid duplicate $set events.
+ * Uses sorted keys to ensure consistent ordering regardless of object construction order.
+ */
+export declare function getPersonPropertiesHash(distinct_id: string, userPropertiesToSet?: {
+    [key: string]: JsonType;
+}, userPropertiesToSetOnce?: {
+    [key: string]: JsonType;
+}): string;
 //# sourceMappingURL=string-utils.d.ts.map

package/dist/utils/string-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string-utils.d.ts","sourceRoot":"","sources":["../../src/utils/string-utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;AAC9D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAA;AAKzD,eAAO,MAAM,IAAI,GAAa,KAAK,MAAM,KAAG,MAM3C,CAAA;AAID,eAAO,MAAM,kBAAkB,GAAa,GAAG,MAAM,KAAG,MAEvD,CAAA;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"string-utils.d.ts","sourceRoot":"","sources":["../../src/utils/string-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;AAC9D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAA;AAKzD,eAAO,MAAM,IAAI,GAAa,KAAK,MAAM,KAAG,MAM3C,CAAA;AAID,eAAO,MAAM,kBAAkB,GAAa,GAAG,MAAM,KAAG,MAEvD,CAAA;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAuBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,mBAAmB,CAAC,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAA;CAAE,EACjD,uBAAuB,CAAC,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAA;CAAE,GACpD,MAAM,CAMR"}

package/dist/utils/string-utils.js

@@ -24,6 +24,7 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    getPersonPropertiesHash: ()=>getPersonPropertiesHash,
     includes: ()=>includes,
     isDistinctIdStringLike: ()=>isDistinctIdStringLike,
     stripLeadingDollar: ()=>stripLeadingDollar,
@@ -44,11 +45,28 @@ function isDistinctIdStringLike(value) {
         'distinctid'
     ].includes(value.toLowerCase());
 }
+function deepSortKeys(value) {
+    if (null === value || 'object' != typeof value) return value;
+    if (Array.isArray(value)) return value.map(deepSortKeys);
+    return Object.keys(value).sort().reduce((acc, key)=>{
+        acc[key] = deepSortKeys(value[key]);
+        return acc;
+    }, {});
+}
+function getPersonPropertiesHash(distinct_id, userPropertiesToSet, userPropertiesToSetOnce) {
+    return JSON.stringify({
+        distinct_id,
+        userPropertiesToSet: userPropertiesToSet ? deepSortKeys(userPropertiesToSet) : void 0,
+        userPropertiesToSetOnce: userPropertiesToSetOnce ? deepSortKeys(userPropertiesToSetOnce) : void 0
+    });
+}
+exports.getPersonPropertiesHash = __webpack_exports__.getPersonPropertiesHash;
 exports.includes = __webpack_exports__.includes;
 exports.isDistinctIdStringLike = __webpack_exports__.isDistinctIdStringLike;
 exports.stripLeadingDollar = __webpack_exports__.stripLeadingDollar;
 exports.trim = __webpack_exports__.trim;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "getPersonPropertiesHash",
     "includes",
     "isDistinctIdStringLike",
     "stripLeadingDollar",

package/dist/utils/string-utils.mjs

@@ -13,4 +13,19 @@ function isDistinctIdStringLike(value) {
         'distinctid'
     ].includes(value.toLowerCase());
 }
-export { includes, isDistinctIdStringLike, stripLeadingDollar, trim };
+function deepSortKeys(value) {
+    if (null === value || 'object' != typeof value) return value;
+    if (Array.isArray(value)) return value.map(deepSortKeys);
+    return Object.keys(value).sort().reduce((acc, key)=>{
+        acc[key] = deepSortKeys(value[key]);
+        return acc;
+    }, {});
+}
+function getPersonPropertiesHash(distinct_id, userPropertiesToSet, userPropertiesToSetOnce) {
+    return JSON.stringify({
+        distinct_id,
+        userPropertiesToSet: userPropertiesToSet ? deepSortKeys(userPropertiesToSet) : void 0,
+        userPropertiesToSetOnce: userPropertiesToSetOnce ? deepSortKeys(userPropertiesToSetOnce) : void 0
+    });
+}
+export { getPersonPropertiesHash, includes, isDistinctIdStringLike, stripLeadingDollar, trim };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/core",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "license": "MIT",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/posthog-core.ts

@@ -30,7 +30,7 @@ import {
 import { Compression, FeatureFlagError, PostHogPersistedProperty } from './types'
 import { maybeAdd, PostHogCoreStateless, QuotaLimitedFeature } from './posthog-core-stateless'
 import { uuidv7 } from './vendor/uuidv7'
-import { isPlainError } from './utils'
+import { isEmptyObject, isNullish, isPlainError, getPersonPropertiesHash, isObject } from './utils'
 
 export abstract class PostHogCore extends PostHogCoreStateless {
   // options
@@ -47,6 +47,9 @@ export abstract class PostHogCore extends PostHogCoreStateless {
   // person profiles
   protected _personProfiles: 'always' | 'identified_only' | 'never'
 
+  // cache for person properties to avoid duplicate $set events
+  protected _cachedPersonProperties: string | null = null
+
   constructor(apiKey: string, options?: PostHogCoreOptions) {
     // Default for stateful mode is to not disable geoip. Only override if explicitly set
     const disableGeoipOption = options?.disableGeoip ?? false
@@ -130,6 +133,9 @@ export abstract class PostHogCore extends PostHogCoreStateless {
       // clean up props
       this.clearProps()
 
+      // clear cached person properties
+      this._cachedPersonProperties = null
+
       for (const key of <(keyof typeof PostHogPersistedProperty)[]>Object.keys(PostHogPersistedProperty)) {
         if (!allPropertiesToKeep.includes(PostHogPersistedProperty[key])) {
           this.setPersistedProperty((PostHogPersistedProperty as any)[key], null)
@@ -294,6 +300,10 @@ export abstract class PostHogCore extends PostHogCoreStateless {
         ...maybeAdd('$set_once', userPropsOnce),
       })
 
+      // Safely cast userProps and userPropsOnce to object types for hash and setPersonProperties
+      const userPropsObj = isObject(userProps) ? (userProps as { [key: string]: JsonType }) : undefined
+      const userPropsOnceObj = isObject(userPropsOnce) ? (userPropsOnce as { [key: string]: JsonType }) : undefined
+
       if (distinctId !== previousDistinctId) {
         // We keep the AnonymousId to be used by flags calls and identify to link the previousId
         this.setPersistedProperty(PostHogPersistedProperty.AnonymousId, previousDistinctId)
@@ -301,9 +311,16 @@ export abstract class PostHogCore extends PostHogCoreStateless {
         // Mark the user as identified
         this.setPersistedProperty(PostHogPersistedProperty.PersonMode, 'identified')
         this.reloadFeatureFlags()
-      }
 
-      super.identifyStateless(distinctId, allProperties, options)
+        super.identifyStateless(distinctId, allProperties, options)
+
+        // Update the cached person properties hash
+        this._cachedPersonProperties = getPersonPropertiesHash(distinctId, userPropsObj, userPropsOnceObj)
+      } else if (userPropsObj || userPropsOnceObj) {
+        // If the distinct_id is not changing, but we have user properties to set, we can check if they have changed
+        // and if so, send a $set event
+        this.setPersonProperties(userPropsObj, userPropsOnceObj)
+      }
     })
   }
 
@@ -429,16 +446,20 @@ export abstract class PostHogCore extends PostHogCoreStateless {
   /***
    * PROPERTIES
    ***/
-  setPersonPropertiesForFlags(properties: { [type: string]: string }): void {
+  setPersonPropertiesForFlags(properties: { [type: string]: JsonType }, reloadFeatureFlags = true): void {
     this.wrap(() => {
       // Get persisted person properties
       const existingProperties =
-        this.getPersistedProperty<Record<string, string>>(PostHogPersistedProperty.PersonProperties) || {}
+        this.getPersistedProperty<Record<string, JsonType>>(PostHogPersistedProperty.PersonProperties) || {}
 
       this.setPersistedProperty<PostHogEventProperties>(PostHogPersistedProperty.PersonProperties, {
         ...existingProperties,
         ...properties,
       })
+
+      if (reloadFeatureFlags) {
+        this.reloadFeatureFlags()
+      }
     })
   }
 
@@ -1162,6 +1183,79 @@ export abstract class PostHogCore extends PostHogCoreStateless {
     this.capture('$set', { $set: {}, $set_once: {} })
   }
 
+  /**
+   * Sets properties on the person profile associated with the current `distinct_id`.
+   * Learn more about [identifying users](https://posthog.com/docs/product-analytics/identify)
+   *
+   * {@label Identification}
+   *
+   * @remarks
+   * Updates user properties that are stored with the person profile in PostHog.
+   * If `personProfiles` is set to `identified_only` and no profile exists, this will create one.
+   *
+   * @example
+   * ```js
+   * // set user properties
+   * posthog.setPersonProperties({
+   *     email: 'user@example.com',
+   *     plan: 'premium'
+   * })
+   * ```
+   *
+   * @example
+   * ```js
+   * // set properties with $set_once
+   * posthog.setPersonProperties(
+   *     { name: 'Max Hedgehog' },  // $set properties
+   *     { initial_url: '/blog' }   // $set_once properties
+   * )
+   * ```
+   *
+   * @public
+   *
+   * @param userPropertiesToSet - Optional: An object of properties to store about the user.
+   *   These properties will overwrite any existing values for the same keys.
+   * @param userPropertiesToSetOnce - Optional: An object of properties to store about the user.
+   *   If a property is previously set, this does not override that value.
+   * @param reloadFeatureFlags - Whether to reload feature flags after setting the properties. Defaults to true.
+   */
+  setPersonProperties(
+    userPropertiesToSet?: { [key: string]: JsonType },
+    userPropertiesToSetOnce?: { [key: string]: JsonType },
+    reloadFeatureFlags = true
+  ): void {
+    this.wrap(() => {
+      const isSetEmpty = isNullish(userPropertiesToSet) || isEmptyObject(userPropertiesToSet)
+      const isSetOnceEmpty = isNullish(userPropertiesToSetOnce) || isEmptyObject(userPropertiesToSetOnce)
+      if (isSetEmpty && isSetOnceEmpty) {
+        return
+      }
+
+      if (!this._requirePersonProcessing('posthog.setPersonProperties')) {
+        return
+      }
+
+      const hash = getPersonPropertiesHash(this.getDistinctId(), userPropertiesToSet, userPropertiesToSetOnce)
+
+      // If exactly this $set call has been sent before, don't send it again - determine based on hash of properties
+      if (this._cachedPersonProperties === hash) {
+        this._logger.info(
+          'A duplicate setPersonProperties call was made with the same properties. It has been ignored.'
+        )
+        return
+      }
+
+      // Update person properties for feature flags evaluation
+      // Merge setOnce first, then set to allow overwriting
+      const mergedProperties = { ...(userPropertiesToSetOnce || {}), ...(userPropertiesToSet || {}) }
+      this.setPersonPropertiesForFlags(mergedProperties, reloadFeatureFlags)
+
+      this.capture('$set', { $set: userPropertiesToSet || {}, $set_once: userPropertiesToSetOnce || {} })
+
+      this._cachedPersonProperties = hash
+    })
+  }
+
   /**
    * Override processBeforeEnqueue to run before_send hooks.
    * This runs after prepareMessage, giving users full control over the final event.

package/src/utils/string-utils.spec.ts

@@ -0,0 +1,121 @@
+import { getPersonPropertiesHash } from './string-utils'
+
+describe('string-utils', () => {
+  describe('getPersonPropertiesHash', () => {
+    it('should return consistent hash regardless of top-level key order', () => {
+      const hash1 = getPersonPropertiesHash('user-1', { b: 'value-b', a: 'value-a' })
+      const hash2 = getPersonPropertiesHash('user-1', { a: 'value-a', b: 'value-b' })
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should return consistent hash regardless of nested object key order', () => {
+      const hash1 = getPersonPropertiesHash('user-1', {
+        nested: { z: 1, a: 2 },
+      })
+      const hash2 = getPersonPropertiesHash('user-1', {
+        nested: { a: 2, z: 1 },
+      })
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should return consistent hash for deeply nested objects', () => {
+      const hash1 = getPersonPropertiesHash('user-1', {
+        level1: {
+          level2: {
+            level3: { c: 3, a: 1, b: 2 },
+          },
+        },
+      })
+      const hash2 = getPersonPropertiesHash('user-1', {
+        level1: {
+          level2: {
+            level3: { a: 1, b: 2, c: 3 },
+          },
+        },
+      })
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should handle arrays with nested objects', () => {
+      const hash1 = getPersonPropertiesHash('user-1', {
+        items: [
+          { z: 1, a: 2 },
+          { y: 3, b: 4 },
+        ],
+      })
+      const hash2 = getPersonPropertiesHash('user-1', {
+        items: [
+          { a: 2, z: 1 },
+          { b: 4, y: 3 },
+        ],
+      })
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should preserve array order (not sort array elements)', () => {
+      const hash1 = getPersonPropertiesHash('user-1', {
+        items: [1, 2, 3],
+      })
+      const hash2 = getPersonPropertiesHash('user-1', {
+        items: [3, 2, 1],
+      })
+      expect(hash1).not.toBe(hash2)
+    })
+
+    it('should handle null values', () => {
+      const hash1 = getPersonPropertiesHash('user-1', { a: null, b: 'value' })
+      const hash2 = getPersonPropertiesHash('user-1', { b: 'value', a: null })
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should handle primitive values', () => {
+      const hash1 = getPersonPropertiesHash('user-1', {
+        str: 'string',
+        num: 42,
+        bool: true,
+        nil: null,
+      })
+      const hash2 = getPersonPropertiesHash('user-1', {
+        nil: null,
+        bool: true,
+        num: 42,
+        str: 'string',
+      })
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should handle userPropertiesToSetOnce with nested objects', () => {
+      const hash1 = getPersonPropertiesHash('user-1', undefined, {
+        nested: { z: 1, a: 2 },
+      })
+      const hash2 = getPersonPropertiesHash('user-1', undefined, {
+        nested: { a: 2, z: 1 },
+      })
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should handle both userPropertiesToSet and userPropertiesToSetOnce', () => {
+      const hash1 = getPersonPropertiesHash('user-1', { nested: { z: 1, a: 2 } }, { other: { y: 3, b: 4 } })
+      const hash2 = getPersonPropertiesHash('user-1', { nested: { a: 2, z: 1 } }, { other: { b: 4, y: 3 } })
+      expect(hash1).toBe(hash2)
+    })
+
+    it('should return different hash for different distinct_id', () => {
+      const hash1 = getPersonPropertiesHash('user-1', { a: 1 })
+      const hash2 = getPersonPropertiesHash('user-2', { a: 1 })
+      expect(hash1).not.toBe(hash2)
+    })
+
+    it('should return different hash for different property values', () => {
+      const hash1 = getPersonPropertiesHash('user-1', { a: 1 })
+      const hash2 = getPersonPropertiesHash('user-1', { a: 2 })
+      expect(hash1).not.toBe(hash2)
+    })
+
+    it('should handle undefined properties', () => {
+      const hash1 = getPersonPropertiesHash('user-1')
+      const hash2 = getPersonPropertiesHash('user-1', undefined, undefined)
+      expect(hash1).toBe(hash2)
+    })
+  })
+})

package/src/utils/string-utils.ts

@@ -1,3 +1,5 @@
+import type { JsonType } from '../types'
+
 export function includes(str: string, needle: string): boolean
 export function includes<T>(arr: T[], needle: T): boolean
 export function includes(str: unknown[] | string, needle: unknown): boolean {
@@ -21,3 +23,41 @@ export const stripLeadingDollar = function (s: string): string {
 export function isDistinctIdStringLike(value: string): boolean {
   return ['distinct_id', 'distinctid'].includes(value.toLowerCase())
 }
+
+/**
+ * Recursively sorts all keys in an object and its nested objects/arrays.
+ * Used to ensure deterministic JSON serialization regardless of object construction order.
+ */
+function deepSortKeys(value: JsonType): JsonType {
+  if (value === null || typeof value !== 'object') {
+    return value
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(deepSortKeys)
+  }
+
+  return Object.keys(value)
+    .sort()
+    .reduce((acc: { [key: string]: JsonType }, key) => {
+      acc[key] = deepSortKeys(value[key])
+      return acc
+    }, {})
+}
+
+/**
+ * Creates a hash string from distinct_id and person properties.
+ * Used to detect if person properties have changed to avoid duplicate $set events.
+ * Uses sorted keys to ensure consistent ordering regardless of object construction order.
+ */
+export function getPersonPropertiesHash(
+  distinct_id: string,
+  userPropertiesToSet?: { [key: string]: JsonType },
+  userPropertiesToSetOnce?: { [key: string]: JsonType }
+): string {
+  return JSON.stringify({
+    distinct_id,
+    userPropertiesToSet: userPropertiesToSet ? deepSortKeys(userPropertiesToSet) : undefined,
+    userPropertiesToSetOnce: userPropertiesToSetOnce ? deepSortKeys(userPropertiesToSetOnce) : undefined,
+  })
+}