[P-830] make userId optional, and address required for identify; update the docs (#8)

* fix: remove trailing comma in package.json for valid JSON

* refactor: replace SDKServerSide with Formo client in analytics and event queue

* feat: Replace Stainless SDK client with direct HTTP event submission and introduce new internal event types.

* tests: Consolidate integration tests for track/identify and batching

* fix: Update test script paths from `src/` to `test/` directory.

* docs: Remove Stainless SDK generation details and enhance testing instructions and README examples.

* fix: Update Authorization header from Basic to Bearer in event queue and its tests.

* chore: make userId optional, address required for identify, update the docs

* chore: switch to npm for dependency management

* fix: default user_id to null instead of an empty string when undefined

* feat: add MIT license file and declare it in package.json

Author: HtetShwe

CONTRIBUTING.md

@@ -1,142 +1,119 @@
-# Contributing to Formo Node SDK
+# How to contribute
 
-Thank you for your interest in contributing to the Formo Node SDK! This guide will help you get started.
+If you want to contribute or run a local version of the Formo Node SDK, follow these steps:
 
-## Table of Contents
+## Build the SDK Locally
 
-- [Project Structure](#project-structure)
-- [Setting Up the Development Environment](#setting-up-the-development-environment)
-- [Making Changes](#making-changes)
-- [Running Tests](#running-tests)
-- [Code Style](#code-style)
+Run the following command to build both CommonJS and ESM versions of the SDK:
 
-## Project Structure
-
-```
-sdk-node/
-├── src/                              # Main SDK source code
-│   ├── FormoAnalytics.ts             # Main SDK class
-│   ├── queue/                        # Event batching and retry logic
-│   ├── types/                        # TypeScript type definitions
-│   ├── utils/                        # Utilities (address checksumming, etc.)
-│   └── validators/                   # Input validation
-├── test/                             # Tests
-│   ├── __tests__/                    # Integration tests
-│   └── queue/                        # Unit tests for queue/events
-├── scripts/                          # Utility and test scripts
-└── package.json
+```bash
+pnpm install
+pnpm build
+pnpm test
 ```
 
-## Setting Up the Development Environment
+## Testing Locally
 
-1. **Clone the repository:**
+### Link the Local Package
 
-   ```bash
-   git clone <repo-url>
-   cd sdk-node
-   ```
+To test your SDK changes in a test app, you can link the package locally using `npm link` or `pnpm link`.
 
-2. **Install dependencies:**
+For example, if your projects are in the same directory:
 
-   This project uses [pnpm](https://pnpm.io/). Other package managers may work but are not officially supported.
+```
+~/
+├── your-app/
+└── sdk-node/
+```
 
-   ```bash
-   pnpm install
-   ```
+Run the following commands:
 
-3. **Build the project:**
+```bash
+# In ~/your-app
+pnpm link ../sdk-node
+```
 
-   ```bash
-   pnpm build
-   ```
+Or with npm:
 
-## Making Changes
+```bash
+# In ~/your-app
+npm link ../sdk-node
+```
 
-The core SDK logic in `src/` is manually maintained.
+### Apply Changes
 
-Key components:
+Any changes you make to your local package require rebuilding to be reflected:
 
-- `FormoAnalytics.ts`: Main entry point and public API.
-- `queue/`: Handles event buffering, batching, and retrying.
-- `types/`: Use this for all shared interfaces and types.
+```bash
+# In ~/sdk-node
+pnpm build
+```
 
-When making changes:
+The changes will automatically be available in the linked project.
 
-1. Create a feature branch from `main`.
-2. Make your changes with appropriate tests.
-3. Ensure all unit tests pass: `npm test`.
-4. If modifying API interactions, verify with integration tests (see below).
-5. Submit a pull request.
+### Unlink the Package
 
-## Running Tests
+To remove the link:
 
-### Unit Tests
+```bash
+# In ~/your-app
+pnpm unlink ../sdk-node
+```
 
-Run the full unit test suite:
+Or with npm:
 
 ```bash
-npm test
+# In ~/your-app
+npm unlink ../sdk-node
 ```
 
-Or just the queue/logic tests:
+## Running Tests
+
+Run the test suite:
 
 ```bash
-npm run test:queue
+pnpm test
 ```
 
 ### Integration Tests
 
-These tests make real network requests to the Formo API. You need a valid Write Key.
+These tests make real network requests to the Formo API. You need a valid Write Key:
 
 ```bash
-FORMO_WRITE_KEY=your-key npm run test:integration
+FORMO_WRITE_KEY=your-key pnpm run test:integration
 ```
 
-### Manual Testing Script
-
-To verify functionality with a real script in a separate environment:
+## Linting
 
-1. Create a `.env` file with `FORMO_WRITE_KEY=your-key`
-2. Run the manual test script:
-   ```bash
-   pnpm run script:test-analytics
-   ```
+Check code style and types:
 
-### Testing Packaging
+```bash
+pnpm lint
+```
 
-To simulate consuming the package as a real user:
+## Publishing
 
-1. Create a tarball:
+1. **Update the version** using npm:
 
    ```bash
-   npm pack
+   npm version patch  # For bug fixes
+   npm version minor  # For new features
+   npm version major  # For breaking changes
    ```
 
-   This creates a file like `formo-analytics-node-1.0.0.tgz`.
+   This automatically:
 
-2. Install it in another project:
+   - Updates `package.json` with the new version
+   - Creates a git commit with the change
+   - Creates a version tag (e.g., `v1.0.1`)
+
+2. **Push the commit and tag**:
 
    ```bash
-   npm install /path/to/sdk-node/formo-analytics-node-1.0.0.tgz
+   git push --follow-tags
    ```
 
-3. Verify usage works as expected.
-
-## Code Style
-
-This project uses:
-
-- [Prettier](https://prettier.io/) for code formatting
-- [ESLint](https://eslint.org/) for linting
-
-```bash
-# Check linting
-pnpm lint
-
-# Fix linting and formatting issues
-pnpm fix
-```
-
-## Questions?
-
-If you have questions or need help, please open an issue on GitHub.
+3. **Automatic workflow execution**:
+   - GitHub Actions workflow triggers on the `v*` tag
+   - Builds and tests the package
+   - Publishes to npm

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Formo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.