From b719516d08a404d3735fd2395124cffc266d5d9c Mon Sep 17 00:00:00 2001 From: Xin Li <137219293+xinlili-statsig@users.noreply.github.com> Date: Fri, 17 Oct 2025 17:05:45 -0700 Subject: [PATCH] update --- .../_GlobalChanges.mdx | 12 +- docs/server-core/node-core.mdx | 8 ++ .../node/migration-guide/_api_changes.mdx | 20 ++++ .../node/migration-guide/_statsig_options.mdx | 18 +++ .../node/migration-guide/_user_creation.mdx | 39 +++++++ .../node/migration-guide/index.mdx | 104 ++++++++++++++++++ 6 files changed, 199 insertions(+), 2 deletions(-) create mode 100644 docs/server-core/node/migration-guide/_api_changes.mdx create mode 100644 docs/server-core/node/migration-guide/_statsig_options.mdx create mode 100644 docs/server-core/node/migration-guide/_user_creation.mdx create mode 100644 docs/server-core/node/migration-guide/index.mdx diff --git a/docs/server-core/MigrationGuideTemplates/_GlobalChanges.mdx b/docs/server-core/MigrationGuideTemplates/_GlobalChanges.mdx index 36b265c82..e88f94e8a 100644 --- a/docs/server-core/MigrationGuideTemplates/_GlobalChanges.mdx +++ b/docs/server-core/MigrationGuideTemplates/_GlobalChanges.mdx @@ -16,7 +16,7 @@ **Lazy Initialization: User-Agent Parser & Country Lookup** -- User-Agent parsing and country lookup are now **lazy-loaded by default** to improve SDK initialization performance. +- Country lookup and third-party ua parsersare now **lazy-loaded by default** to improve SDK initialization performance. - If your application relies on these features being ready **immediately after** `initialize()`, you can opt in by setting: - {props.waitForUserAgentInit || 'wait_for_user_agent_init'} - {props.waitForCountryLookupInit || 'wait_for_country_lookup_init'} @@ -37,4 +37,12 @@ - **Old**: `v1/download_config_specs` - **New**: `v2/download_config_specs` - If you are hosting your own **pass-through proxy**, ensure it supports and correctly routes the `v2` endpoint. -- If you are using the **Statsig Forward Proxy (SFP)**, this endpoint migration is handled automatically. \ No newline at end of file +- If you are using the **Statsig Forward Proxy (SFP)**, this endpoint migration is handled automatically. + +** New DataStore cache format** + - **Old**: (Except Node v6+) + - config_spec cahce key is: statsig.cache + - IDLists statsig.id_lists + - **New** + - config_spec cache key: `statsig|/v2/download_config_specs|plain_text|{SHA256HashedBase64(secretkey)}` + - IDLists: We don't support idlist data store. \ No newline at end of file diff --git a/docs/server-core/node-core.mdx b/docs/server-core/node-core.mdx index c0edf5012..8153cf021 100644 --- a/docs/server-core/node-core.mdx +++ b/docs/server-core/node-core.mdx @@ -26,6 +26,7 @@ import { FieldsNeededMethods, ClientInitResponse, EventSubscriptions, + MigrationGuide, } from "./Templates/index.mdx"; import Preamble from "./_preamble.mdx"; @@ -71,6 +72,13 @@ export const Builder = SDKDocsBuilder({ initialize: , }, ], + [ + MigrationGuide, + { + link: "/server-core/node/migration-guide", + sdkType: "Node", + }, + ], [ WorkingWith, { diff --git a/docs/server-core/node/migration-guide/_api_changes.mdx b/docs/server-core/node/migration-guide/_api_changes.mdx new file mode 100644 index 000000000..d6aac135f --- /dev/null +++ b/docs/server-core/node/migration-guide/_api_changes.mdx @@ -0,0 +1,20 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +### Key Package and Class Changes + +| Feature | Node Core SDK | Legacy Node SDK | Status | +|---------|---------------|----------------|--------| +| Package | `statsig-node-core` | `statsig-node` | ⚠️ Renamed | +| Import | `import {Statsig} '@statsig/statsig-node-core'` |`const Statsig = require("statsig-node");` | ⚠️ Change | +| Options | `StatsigOptions` | `StatsigOptions` | ✓ Same | +| User | `StatsigUser` | `StatsigUser` | ⚠️ Changed from type to class | +| Initialize | `await statsig.initialize()` | `await statsig.initialize()` | Same | +| Check Gate | `statsig.check_gate()` | `statsig.check_gate()` | ✓ Same | +| Get Config | `statsig.get_dynamic_config()` | `statsig.get_config()` | ⚠️ Renamed | +| Get Experiment | `statsig.get_experiment()` | `statsig.get_experiment()` | ✓ Same | +| Get Layer | `statsig.get_layer()` | `statsig.get_layer()` | ✓ Same | +| Log Event | `statsig.log_event()` | `statsig.log_event()` | ✓ Same | +| Shutdown | `await statsig.shutdown()` | `await statsig.shutdown()` | Same | + +For more details on the new API, see [Python Core SDK documentation](/server-core/python-core). \ No newline at end of file diff --git a/docs/server-core/node/migration-guide/_statsig_options.mdx b/docs/server-core/node/migration-guide/_statsig_options.mdx new file mode 100644 index 000000000..eb3459125 --- /dev/null +++ b/docs/server-core/node/migration-guide/_statsig_options.mdx @@ -0,0 +1,18 @@ +| Old Option | New / Notes | +| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| `api` | Deprecated | +| `idlists_thread_limit`, `logging_interval`, `enable_debug_logs`, `events_flushed_callback` | Deprecated | +| `timeout` | Deprecated (was only for network) | +| `apiForDownloadConfigSpecs` | `specsUrl` – must complete with endpoint | +| `apiForIdLists` | `idListsUrl` – must complete with endpoint | +| `apiForLogEvent` | `logEventUrl` – must complete with endpoint | +| `initTimeoutMs` | `initTimeoutMs` – applies to overall initialization (suggest adding +1000 ms if enabling UA) | +| `rulesetsSyncIntervalMs` | `specsSyncIntervalMs` (unit: milliseconds) | +| `idListsSyncIntervalMs` | `idListsSyncIntervalMs` (unit: milliseconds) | +| `loggingIntervalMs` | `eventLoggingFlushIntervalMs` | +| `loggingMaxBufferSize` | `eventLoggingMaxQueuesize` | +| `dataAdapter` | Still supported but interface changed | +| `initTimeoutMs` | Apply to overall initialize timeout | +| `observability_client`, `sdk_error_callback` | Now within `observability_client` interface | +| `logger` | Now `OutputLoggerProvider` interface | +| `bootstrap_values`, `evaluation_callback`, `rules_updated_callback` | Not yet supported | diff --git a/docs/server-core/node/migration-guide/_user_creation.mdx b/docs/server-core/node/migration-guide/_user_creation.mdx new file mode 100644 index 000000000..5c70c5c30 --- /dev/null +++ b/docs/server-core/node/migration-guide/_user_creation.mdx @@ -0,0 +1,39 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +User creation is still the same in the new python core SDK. + + + + ```python + from statsig_python_core import * + + user = StatsigUser( + user_id="user_123", + email="user@example.com", + ip="192.168.0.1", + user_agent="Mozilla/5.0", + country="US", + custom={ + "subscription_level": "premium" + } + ) + ``` + + + ```python + from statsig import StatsigUser + + user = StatsigUser( + user_id="user_123", + email="user@example.com", + ip="192.168.0.1", + user_agent="Mozilla/5.0", + country="US", + custom={ + "subscription_level": "premium" + } + ) + ``` + + diff --git a/docs/server-core/node/migration-guide/index.mdx b/docs/server-core/node/migration-guide/index.mdx new file mode 100644 index 000000000..b750370f1 --- /dev/null +++ b/docs/server-core/node/migration-guide/index.mdx @@ -0,0 +1,104 @@ +--- +title: Node Core SDK Migration Guide +displayed_sidebar: api +--- + +import CodeBlock from '@theme/CodeBlock'; +import { + SDKDocsBuilder, +} from "../../../sdks/_SDKDocsBuilder.mdx"; + +import { + APIChanges, + GlobalChanges, + Installation, + MigrationHelp, + StatsigOptions, + UserCreation, + NeedHelp, + Troubleshooting, + Intro, +} from "../../MigrationGuideTemplates/index.mdx"; +import NodeAPIChanges from "./_api_changes.mdx"; +import NodeUserCreation from "./_user_creation.mdx"; +import NodeStatsigOptions from "./_statsig_options.mdx"; + +export const Builder = SDKDocsBuilder({ + sections: [ + [ + Intro, + { + sdkType: "Node JS", + }, + ], + + [ + Installation, + { + legacyInstall: npm install statsig-node, + install: npm install @statsig/statsig-node-core, + }, + ], + [ + UserCreation, + { + newUserCreation: +{`import {StatsigUser} from "@statsig/statsig-node-core" +const user = new StatsigUser({ + userID: "user_123", + email: "user@example.com", + ip: "192.168.0.1", + userAgent: "Mozilla/5.0", + country: "US", + custom={ + "subscription_level": "premium" + } +}) +`}, + legacyUserCreation: +{`import type {StatsigUser} from "statsig-node" +user = { + userID: "user_123", + email: "user@example.com", + ip: "192.168.0.1", + userAgent: "Mozilla/5.0", + country: "US", + custom={ + "subscription_level": "premium" + } +} +`}, +} +], +[ +APIChanges, +{ +apiChanges: +} +], +[ +GlobalChanges, +{ +waitForUserAgentInit: "wait_for_user_agent_init", +waitForCountryLookupInit: "wait_for_country_lookup_init", +disableUserAgentParsing: "disable_user_agent_parsing", +disableCountryLookup: "disable_country_lookup", +enableIdLists: "enable_id_lists" +}, +], +[ +StatsigOptions, +{ +optionsMapping: +} +], +[ +NeedHelp, +{} +], +] +}) + +export const toc = Builder.toc; + +<>{Builder.result}