Skip to content

Commit d60765c

Browse files
HtetShweHtetShwe
authored
[P-830] use custom code and remove stainless (#4)
* 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.
1 parent 6719055 commit d60765c

15 files changed

Lines changed: 577 additions & 1085 deletions

‎.gitignore‎

Lines changed: 61 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,63 @@
1-
node_modules/
2-
dist/
1+
# Logs
2+
logs
33
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
lerna-debug.log*
8+
9+
# Diagnostic reports (https://nodejs.org/api/report.html)
10+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
11+
12+
# Runtime data
13+
pids
14+
*.pid
15+
*.seed
16+
*.pid.lock
17+
18+
# nyc test coverage
19+
.nyc_output
20+
coverage
21+
22+
# Dependency directories
23+
node_modules/
24+
25+
# Build output
26+
dist
27+
28+
# TypeScript build artifacts
29+
tsconfig.tsbuildinfo
30+
*.tsbuildinfo
31+
32+
# Compiled JS files in src (TypeScript source only)
33+
src/**/*.js
34+
test/**/*.js
35+
!src/**/*.spec.js
36+
!test/**/*.spec.js
37+
38+
# Optional npm cache directory
39+
.npm
40+
41+
# Output of 'npm pack'
42+
*.tgz
43+
44+
# Yarn Integrity file
45+
.yarn-integrity
46+
47+
# dotenv environment variables file
448
.env
5-
.DS_Store
49+
.env.test
50+
.env.local
51+
52+
# parcel-bundler cache
53+
.cache
54+
55+
# OS files
56+
.DS_Store
57+
Thumbs.db
58+
59+
# IDE
60+
.idea
61+
.vscode
62+
*.swp
63+
*.swo

‎.stainless/stainless.yml‎

Lines changed: 0 additions & 119 deletions
This file was deleted.

‎.stainless/workspace.json‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎CONTRIBUTING.md‎

Lines changed: 47 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ Thank you for your interest in contributing to the Formo Node SDK! This guide wi
66

77
- [Project Structure](#project-structure)
88
- [Setting Up the Development Environment](#setting-up-the-development-environment)
9-
- [Stainless SDK Generation](#stainless-sdk-generation)
109
- [Making Changes](#making-changes)
1110
- [Running Tests](#running-tests)
1211
- [Code Style](#code-style)
@@ -15,18 +14,16 @@ Thank you for your interest in contributing to the Formo Node SDK! This guide wi
1514

1615
```
1716
sdk-node/
18-
├── src/ # Main SDK source code (manually maintained)
17+
├── src/ # Main SDK source code
1918
│ ├── FormoAnalytics.ts # Main SDK class
2019
│ ├── queue/ # Event batching and retry logic
2120
│ ├── types/ # TypeScript type definitions
2221
│ ├── utils/ # Utilities (address checksumming, etc.)
2322
│ └── validators/ # Input validation
24-
├── sdks/
25-
│ └── sdk-server-side-typescript/ # Generated API client (via Stainless)
26-
├── openapi.json # OpenAPI specification for the Formo API
27-
├── .stainless/ # Stainless configuration
28-
│ ├── stainless.yml # Stainless SDK configuration
29-
│ └── workspace.json # Stainless workspace settings
23+
├── test/ # Tests
24+
│ ├── __tests__/ # Integration tests
25+
│ └── queue/ # Unit tests for queue/events
26+
├── scripts/ # Utility and test scripts
3027
└── package.json
3128
```
3229

@@ -53,118 +50,77 @@ sdk-node/
5350
pnpm build
5451
```
5552

56-
## Stainless SDK Generation
57-
58-
This project uses [Stainless](https://www.stainless.com/) to generate type-safe API clients from our OpenAPI specification. The generated code lives in `sdks/sdk-server-side-typescript/`.
59-
60-
### Initial Setup
61-
62-
If you need to set up Stainless for the first time:
63-
64-
1. **Install the Stainless CLI:**
65-
66-
```bash
67-
brew install stainless-api/tap/stl
68-
```
69-
70-
2. **Initialize Stainless in your project:**
71-
72-
```bash
73-
stl init
74-
```
53+
## Making Changes
7554

76-
During initialization, you'll be prompted to:
55+
The core SDK logic in `src/` is manually maintained.
7756

78-
- Select your OpenAPI specification file (`openapi.json`)
79-
- Choose the target language(s) (TypeScript for this project)
80-
- Configure output directories
57+
Key components:
8158

82-
3. **Configuration files:**
59+
- `FormoAnalytics.ts`: Main entry point and public API.
60+
- `queue/`: Handles event buffering, batching, and retrying.
61+
- `types/`: Use this for all shared interfaces and types.
8362

84-
The `.stainless/` directory is included in the repository and contains:
63+
When making changes:
8564

86-
- `stainless.yml` - Main configuration file for SDK generation
87-
- `workspace.json` - Workspace settings
65+
1. Create a feature branch from `main`.
66+
2. Make your changes with appropriate tests.
67+
3. Ensure all unit tests pass: `npm test`.
68+
4. If modifying API interactions, verify with integration tests (see below).
69+
5. Submit a pull request.
8870

89-
Commit any changes to these files to ensure all contributors stay in sync.
71+
## Running Tests
9072

91-
### Regenerating the SDK
73+
### Unit Tests
9274

93-
When the OpenAPI specification (`openapi.json`) or Stainless configuration (`.stainless/stainless.yml`) is updated, you need to regenerate the SDK:
75+
Run the full unit test suite:
9476

9577
```bash
96-
# Commit your changes first
97-
git add .stainless/stainless.yml openapi.json
98-
git commit -m "Update API specification"
99-
100-
# Create a new build on your current branch
101-
stl builds create --branch $(git branch --show-current)
78+
npm test
10279
```
10380

104-
Alternatively, use development mode to see live updates and errors:
81+
Or just the queue/logic tests:
10582

10683
```bash
107-
stl dev
84+
npm run test:queue
10885
```
10986

110-
This will regenerate the files in `sdks/sdk-server-side-typescript/` based on the current OpenAPI spec and Stainless configuration.
111-
112-
### Modifying Generated Code
113-
114-
> **Important:** Most of the code in `sdks/sdk-server-side-typescript/` is auto-generated.
87+
### Integration Tests
11588

116-
- Modifications to generated files may persist between generations but could result in merge conflicts.
117-
- The generator will **never** modify the contents of `src/lib/` and `examples/` directories within the generated SDK.
118-
- For custom logic, prefer adding code to the main `src/` directory rather than modifying generated files.
89+
These tests make real network requests to the Formo API. You need a valid Write Key.
11990

120-
### Updating the OpenAPI Specification
121-
122-
When making API changes:
123-
124-
1. Update `openapi.json` with the new endpoints, schemas, or modifications
125-
2. Update `.stainless/stainless.yml` if needed (e.g., new resources, methods, or examples)
126-
3. Validate the configuration: `stl lint`
127-
4. Commit your changes: `git add openapi.json .stainless/stainless.yml && git commit -m "Update API spec"`
128-
5. Regenerate the SDK: `stl builds create --branch $(git branch --show-current)`
129-
6. Test the changes thoroughly
130-
7. Review and commit the regenerated SDK files in `sdks/sdk-server-side-typescript/`
131-
132-
## Making Changes
91+
```bash
92+
FORMO_WRITE_KEY=your-key npm run test:integration
93+
```
13394

134-
### Main SDK Code (`src/`)
95+
### Manual Testing Script
13596

136-
The core SDK logic in `src/` is manually maintained:
97+
To verify functionality with a real script in a separate environment:
13798

138-
- `FormoAnalytics.ts` - Main entry point and public API
139-
- `queue/` - Event batching, retry logic, and graceful shutdown
140-
- `types/` - TypeScript interfaces and type definitions
141-
- `utils/` - Helper functions for address checksumming, property normalization
142-
- `validators/` - Input validation logic
99+
1. Create a `.env` file with `FORMO_WRITE_KEY=your-key`
100+
2. Run the manual test script:
101+
```bash
102+
pnpm run script:test-analytics
103+
```
143104

144-
When making changes:
105+
### Testing Packaging
145106

146-
1. Create a feature branch from `main`
147-
2. Make your changes with appropriate tests
148-
3. Ensure all tests pass: `pnpm test`
149-
4. Submit a pull request
107+
To simulate consuming the package as a real user:
150108

151-
### Generated SDK Code (`sdks/`)
109+
1. Create a tarball:
152110

153-
ForUpdate `.stainless/stainless.yml` if adding new methods or resources 3. Validate with `stl lint` 4. Commit: `git add openapi.json .stainless/stainless.yml && git commit -m "Update API"` 5. Regenerate the SDK: `stl builds create --branch $(git branch --show-current)` 6. Test the changes 7. Review and commit the regeneratednapi.json`with the required changes
154-
2. Regenerate the SDK:`stainless generate` 3. Test the changes 4. Commit both files
111+
```bash
112+
npm pack
113+
```
155114

156-
## Running Tests
115+
This creates a file like `formo-analytics-node-1.0.0.tgz`.
157116

158-
```bash
159-
# Run all tests
160-
pnpm test
117+
2. Install it in another project:
161118

162-
# Run tests in watch mode
163-
pnpm test:watch
119+
```bash
120+
npm install /path/to/sdk-node/formo-analytics-node-1.0.0.tgz
121+
```
164122

165-
# Run integration tests (requires API key)
166-
FORMO_WRITE_KEY=your-key pnpm run test:integration
167-
```
123+
3. Verify usage works as expected.
168124

169125
## Code Style
170126

0 commit comments

Comments
 (0)