feat(node-sdk): add push-based flags sync mode

[roncohen]

Summary

• add a new flagsSyncMode option for node-sdk: polling | in-request | push
• add push transport support via SSE (default https://pubsub.reflag.com/sse)
• on push updates, refresh /features using waitForVersion from flags-updated messages
• add flagsPushUrl option
• keep cacheStrategy as deprecated backward compatibility
• set EdgeClient default to flagsSyncMode: "in-request"
• update node-sdk docs and tests

Validation

• yarn workspace @reflag/node-sdk test
• yarn workspace @reflag/node-sdk build

[Copilot]

Pull request overview

Adds a new flag-definition synchronization system to @reflag/node-sdk, introducing a push (SSE) mode alongside polling and in-request refresh behavior, and updates the client, docs, and examples accordingly.

Changes:

• Introduces flagsSyncMode (polling | in-request | push) and flagsPushUrl, plus new SSE-based push transport.
• Replaces the prior cache-strategy-specific cache implementations with a unified FlagsCache that supports throttling and version-aware refresh (waitForVersion).
• Updates tests, documentation, and the Express example to reflect the new sync modes and defaults (including EdgeClient defaulting to "in-request").

Reviewed changes

Copilot reviewed 24 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
yarn.lock	Adds dependencies for the new example workspace and updated tooling deps.
packages/node-sdk/test/periodicallyUpdatingCache.test.ts	Removes tests for deleted periodic cache implementation.
packages/node-sdk/test/inRequestCache.test.ts	Removes tests for deleted in-request cache implementation.
packages/node-sdk/test/flags-refresher.test.ts	Adds coverage for controller behavior (e.g., catching background refresh failures).
packages/node-sdk/test/flags-cache.test.ts	Adds coverage for throttling and versioned refresh coordination in FlagsCache.
packages/node-sdk/test/client.test.ts	Adds push-mode tests (SSE message handling, reconnect refresh) and updates expectations for new API fields.
packages/node-sdk/src/types.ts	Adds FlagsSyncMode, flagsSyncMode/flagsPushUrl options, and flagStateVersion on FlagsAPIResponse.
packages/node-sdk/src/periodicallyUpdatingCache.ts	Deletes old periodic cache implementation in favor of unified FlagsCache.
packages/node-sdk/src/inRequestCache.ts	Deletes old in-request cache implementation in favor of unified FlagsCache.
packages/node-sdk/src/index.ts	Re-exports FlagsSyncMode.
packages/node-sdk/src/flags-refresher.ts	Adds sync controllers for polling / in-request / push modes.
packages/node-sdk/src/flags-cache.ts	Adds unified cache with throttling, trailing refresh scheduling, and version-aware updates.
packages/node-sdk/src/flag-updates-sse.ts	Adds SSE transport with reconnect/backoff and flags-updated message parsing.
packages/node-sdk/src/edgeClient.ts	Forces EdgeClient to use flagsSyncMode: "in-request" and updates docs.
packages/node-sdk/src/config.ts	Adds PUBSUB_SSE_URL constant for default push endpoint.
packages/node-sdk/src/client.ts	Integrates FlagsCache + sync controllers, supports waitForVersion, and wires push channel selection.
packages/node-sdk/README.md	Documents new sync modes/options and clarifies EdgeClient behavior under throttling.
packages/node-sdk/examples/express/reflag.ts	Updates example to use published package import and configures flagsSyncMode: "push".
packages/node-sdk/examples/express/README.md	Updates run command to use the new example workspace name.
packages/node-sdk/examples/express/package.json	Renames and wires the Express example as a private workspace depending on @reflag/node-sdk.
packages/node-sdk/examples/express/bucketConfig.json	Removes old local-bucket override config.
packages/node-sdk/examples/express/bucket.ts	Removes old example client wiring via local source import.
packages/node-sdk/examples/express/app.ts	Updates type import to come from @reflag/node-sdk.
package.json	Adds the Express example to workspace list.
.changeset/dull-deserts-begin.md	Declares minor releases describing the new flagsSyncMode functionality.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.