Merge branch 'main' into ta/sdk-1209/initmetadata-fdv2-datasources

Author: tanderson-ld

.cursor/rules/dependencies.mdc

@@ -0,0 +1,30 @@
+---
+description: Rules about dependencies.
+globs: *
+alwaysApply: true
+---
+# Dependency Management Guidelines
+
+## General Principles
+- Dependencies should be avoided unless absolutely necessary
+- Consider the following factors when evaluating dependencies:
+  - Size: Impact on final bundle size (especially important for browser SDK)
+  - Maintenance: Risk of becoming unmaintained or deprecated
+  - Security: Potential security vulnerabilities
+  - Compatibility: Support across all target platforms
+  - Conflicts: Potential conflicts with application dependencies
+
+## Package-Specific Guidelines
+- Most important to avoid dependencies in:
+  - common package
+  - sdk-client package
+  - sdk-server package
+- Individual SDK packages may have specific platform dependencies
+- Edge SDKs must use their provider's edge store and may require specific dependencies
+
+## Dependency Selection Criteria
+- Only use dependencies for functionality with:
+  - Highly-specified behavior
+  - Wide usage
+  - Active maintenance
+  - Large community support

.cursor/rules/development.mdc

@@ -0,0 +1,30 @@
+---
+description: Rules for building and understanding the repository.
+globs: *
+alwaysApply: true
+---
+# General Development Guidelines
+
+## Project Structure
+- This is a monorepo containing multiple JavaScript SDK packages
+- Packages are organized into categories:
+  - Shared packages (common code)
+  - SDK packages (platform-specific implementations)
+  - Store packages (persistent storage)
+  - Telemetry packages (monitoring)
+  - Tooling packages (development tools)
+
+## Build Requirements
+- Node environment version 16 required, this is a minimum.
+- yarn required
+- Some projects may have specific environment prerequisites
+
+## Build Process
+- Use `yarn` to install dependencies from project root
+- Use `yarn build` to build all projects
+- For single project builds:
+  ```
+  yarn workspaces foreach -pR --topological-dev --from '@launchdarkly/js-client-sdk' run build
+  ```
+- Replace package name as needed
+- Running `yarn build` in individual packages won't rebuild dependencies

.cursor/rules/linting.mdc

@@ -0,0 +1,63 @@
+---
+description: Rules for finding and addressing linting issues.
+globs: *.ts
+alwaysApply: true
+---
+# Linting Guidelines
+
+## Running Lint Checks
+
+Lint checks can be run for any package using the following command:
+
+```bash
+yarn workspace <package name> lint
+```
+
+For example, to lint the common SDK package:
+
+```bash
+yarn workspace @launchdarkly/js-sdk-common lint
+```
+
+## Fixing Lint Issues
+
+Many lint issues can be automatically fixed using the `--fix` flag:
+
+```bash
+yarn workspace <package name> lint --fix
+```
+
+For example:
+
+```bash
+yarn workspace @launchdarkly/js-sdk-common lint --fix
+```
+
+## Manual Fixes
+
+If automatic fixes don't resolve all issues, you should fix them manually. Pay special attention to:
+
+- TypeScript type errors
+- ESLint rule violations
+- Code style inconsistencies
+
+## Mock Type Handling
+
+When working with mocks in tests, it's acceptable to use ESLint ignore or TypeScript ignore comments if typing issues arise. This is only appropriate for test mocks, not for implementation code.
+
+Example:
+
+```typescript
+// @ts-ignore - Mock implementation doesn't need full typing
+const mockClient = {
+  // mock implementation
+};
+```
+
+## Package Names
+
+Package names can be found in the respective `package.json` files. Always use the exact package name as specified there when running lint commands.
+
+## When to Run Lint
+
+- Run lint checks on any package you've modified

.cursor/rules/testing.mdc

@@ -0,0 +1,52 @@
+---
+description: Rules for running and developing tests.
+globs: *
+alwaysApply: true
+---
+# Testing Guidelines
+
+## Test Structure
+- Unit tests should be implemented in a `__tests__` folder in the root of the package
+- The directory structure inside of `__tests__` should mirror that of the source directory
+- Tests should only be run for single projects
+
+## Test Naming and Organization
+- Test cases should be written using `it` and should read as a sentence including the `it`
+- Example: `it('does not load flags prior to start', async () => {/* test code */})`
+- Describe blocks should ONLY be used for common setup for a series of tests
+- Example: `describe('given a mock filesystem and memory feature store', { /* tests */})`
+- If there is no shared configuration, do not use a describe block
+- Combined test names should be understandable: `given a mock filesystem and memory feature store > it does not load flags prior to start`
+
+- Example of proper describe usage:
+  ```javascript
+  describe('given a mock filesystem and memory feature store', () => {
+    // Shared setup code here
+    
+    it('does not load flags prior to start', async () => {
+      // Test code
+    });
+    
+    it('loads flags after start', async () => {
+      // Test code
+    });
+  });
+  ```
+- Example of when not to use describe:
+  ```javascript
+  // No shared configuration, so no describe block needed
+  it('returns true when flag is enabled', () => {
+    // Test code
+  });
+  
+  it('returns false when flag is disabled', () => {
+    // Test code
+  });
+  ```
+
+## Running Tests
+- Tests should be run using `yarn workspace <package name> test`
+- The package name can be found in the package.json file
+- Unit tests should be run for any packages that have been modified
+
+

.cursor/rules/typescript.mdc

@@ -0,0 +1,20 @@
+---
+description:  Rules for typescript development.
+globs: *.ts
+alwaysApply: true
+---
+# TypeScript Guidelines
+
+## TypeScript vs JavaScript
+- While we develop in TypeScript, aim for compiled JavaScript to not be substantially different than if written as JavaScript
+- Consider JavaScript consumers when making TypeScript decisions
+
+## TypeScript Best Practices
+- Avoid using TypeScript enumerations. Instead use unions of strings
+  - Bad: `enum ValueType { Bool = 'bool', Int = 'int' }`
+  - Good: `type ValueType = 'bool' | 'int'`
+- Prefer interfaces over classes when reasonable, especially if publicly exposed
+  - Bad: Using classes for simple data structures
+  - Good: Using interfaces with factory functions
+- Remember that `private` and `readonly` only affect TypeScript - JavaScript can still access and mutate
+- For private members that need to be minified, prefix with underscore

.github/ISSUE_TEMPLATE/package-sdk-combined-browser--bug_report.md

@@ -0,0 +1,36 @@
+---
+name: '@launchdarkly/browser Bug Report'
+about: Create a report to help us improve
+title: ''
+labels: 'package: sdk/combined-browser, bug'
+assignees: ''
+---
+
+**Is this a support request?**
+This issue tracker is maintained by LaunchDarkly SDK developers and is intended for feedback on the code in this library. If you're not sure whether the problem you are having is specifically related to this library, or to the LaunchDarkly service overall, it may be more appropriate to contact the LaunchDarkly support team; they can help to investigate the problem and will consult the SDK team if necessary. You can submit a support request by going [here](https://support.launchdarkly.com/) and clicking "submit a request", or by emailing [email protected].
+
+Note that issues filed on this issue tracker are publicly accessible. Do not provide any private account information on your issues. If your problem is specific to your account, you should submit a support request as described above.
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behavior.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Logs**
+If applicable, add any log output related to your problem.
+
+**SDK version**
+The version of this SDK that you are using.
+
+**Language version, developer tools**
+For instance, Go 1.11 or Ruby 2.5.3. If you are using a language that requires a separate compiler, such as C, please include the name and version of the compiler too.
+
+**OS/platform**
+For instance, Ubuntu 16.04, Windows 10, or Android 4.0.3. If your code is running in a browser, please also include the browser type and version.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/package-sdk-combined-browser--feature_request.md

@@ -0,0 +1,19 @@
+---
+name: '@launchdarkly/browser Feature Request'
+about: Create a report to help us improve
+title: ''
+labels: 'package: sdk/combined-browser, feature'
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I would love to see the SDK [...does something new...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context about the feature request here.

.github/workflows/combined-browser.yml

@@ -0,0 +1,44 @@
+name: sdk/combined-browser
+
+on:
+  push:
+    branches: [main, 'feat/**']
+    paths-ignore:
+      - '**.md' #Do not need to run CI for markdown changes.
+  pull_request:
+    branches: [main, 'feat/**']
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  build-test-browser:
+    permissions:
+      pull-requests: write
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        # Node versions to run on.
+        version: [18, 21]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.version }}
+          registry-url: 'https://registry.npmjs.org'
+      - id: shared
+        name: Shared CI Steps
+        uses: ./actions/ci
+        with:
+          workspace_name: '@launchdarkly/browser'
+          workspace_path: packages/sdk/combined-browser
+      - name: Check package size
+        if: github.event_name == 'pull_request' && matrix.version == '21'
+        uses: ./actions/package-size
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          target_file: 'packages/sdk/combined-browser/dist/index.js'
+          package_name: '@launchdarkly/browser'
+          pr_number: ${{ github.event.number }}
+          size_limit: 200000

.github/workflows/manual-publish-docs.yml

@@ -23,6 +23,7 @@ on:
           - packages/sdk/browser
           - packages/sdk/server-ai
           - packages/telemetry/browser-telemetry
+          - packages/sdk/combined-browser
 name: Publish Documentation
 jobs:
   build-publish:

.github/workflows/manual-publish.yml

@@ -36,6 +36,7 @@ on:
           - packages/sdk/browser
           - packages/sdk/server-ai
           - packages/telemetry/browser-telemetry
+          - packages/sdk/combined-browser
       prerelease:
         description: 'Is this a prerelease. If so, then the latest tag will not be updated in npm.'
         type: boolean