Skip to content

Commit 9eb05fc

Browse files
ben-fornefeldben-fornefeld
committed
feat: enhance SDK configuration with version-specific overrides and add versioning documentation
1 parent 5748e31 commit 9eb05fc

12 files changed

Lines changed: 727 additions & 111 deletions

File tree

‎sdk-reference-generator/VERSIONING.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# SDK Versioning Documentation
2+
3+
This document tracks the version-specific configuration changes for each SDK.
4+
5+
## JavaScript SDK (js-sdk)
6+
7+
### Verified Version History
8+
9+
All version ranges have been verified by checking actual git tags and TypeDoc configurations.
10+
11+
| Version Range | Entry Points | Notes |
12+
|--------------|-------------|--------|
13+
| `1.0.0` | sandbox/index.ts, filesystem/index.ts, process/index.ts, **pty.ts**, errors.ts | Used pty.ts instead of commands.ts |
14+
| `>=1.1.0 <2.3.0` | sandbox/index.ts, filesystem/index.ts, process/index.ts, **commands/index.ts**, errors.ts | Standard sandbox APIs |
15+
| `>=2.3.0` | + **template/index.ts**, **template/readycmd.ts**, **template/logger.ts** | Added template build support |
16+
17+
### Configuration in sdks.config.ts
18+
19+
```typescript
20+
"js-sdk": {
21+
defaultConfig: {
22+
entryPoints: [
23+
// v2.3.0+ configuration (with template modules)
24+
"src/sandbox/index.ts",
25+
"src/sandbox/filesystem/index.ts",
26+
"src/sandbox/process/index.ts",
27+
"src/sandbox/commands/index.ts",
28+
"src/errors.ts",
29+
"src/template/index.ts",
30+
"src/template/readycmd.ts",
31+
"src/template/logger.ts",
32+
],
33+
},
34+
configOverrides: {
35+
"1.0.0": {
36+
entryPoints: [/* pty.ts version */],
37+
},
38+
">=1.1.0 <2.3.0": {
39+
entryPoints: [/* without template */],
40+
},
41+
},
42+
}
43+
```
44+
45+
## Python SDK (python-sdk)
46+
47+
### Verified Version History
48+
49+
All version ranges have been verified by checking actual git tags and package structure.
50+
51+
| Version Range | Allowed Packages | Notes |
52+
|--------------|-----------------|--------|
53+
| `>=1.0.0 <2.1.0` | e2b.sandbox_sync, e2b.sandbox_async, e2b.exceptions | Basic sandbox APIs only |
54+
| `>=2.1.0` | + e2b.template, e2b.template_sync, e2b.template_async, e2b.template.logger, e2b.template.readycmd | Template SDK added in v2.1.0 (PR #871) |
55+
56+
### Configuration in sdks.config.ts
57+
58+
```typescript
59+
"python-sdk": {
60+
defaultConfig: {
61+
allowedPackages: [
62+
// v2.1.0+ configuration (with template modules)
63+
"e2b.sandbox_sync",
64+
"e2b.sandbox_async",
65+
"e2b.exceptions",
66+
"e2b.template",
67+
"e2b.template_sync",
68+
"e2b.template_async",
69+
"e2b.template.logger",
70+
"e2b.template.readycmd",
71+
],
72+
},
73+
configOverrides: {
74+
">=1.0.0 <2.1.0": {
75+
allowedPackages: [
76+
"e2b.sandbox_sync",
77+
"e2b.sandbox_async",
78+
"e2b.exceptions",
79+
],
80+
},
81+
},
82+
}
83+
```
84+
85+
## Code Interpreter SDKs
86+
87+
### code-interpreter-js-sdk
88+
89+
**Current Configuration**: Single entry point (`src/index.ts`)
90+
91+
No version-specific overrides needed - the SDK has a simple, stable structure since v1.0.0. The code-interpreter is a focused wrapper around the base E2B SDK for code execution.
92+
93+
### code-interpreter-python-sdk
94+
95+
**Current Configuration**: Single package (`e2b_code_interpreter`)
96+
97+
No version-specific overrides needed - the Python package structure has remained consistent.
98+
99+
## Desktop SDKs
100+
101+
### desktop-js-sdk & desktop-python-sdk
102+
103+
**Current Configuration**: Simple defaults (`src/index.ts` and `e2b_desktop`)
104+
105+
No version-specific overrides needed yet. These SDKs are relatively new and haven't had breaking structural changes requiring versioned configs.
106+
107+
**Note**: If any of these SDKs introduce breaking changes in future versions (e.g., new modules, renamed packages), add appropriate `configOverrides` following the same pattern used for js-sdk and python-sdk.
108+
109+
## Adding New Version Overrides
110+
111+
When you discover that a specific version range needs different configuration:
112+
113+
1. **Identify the version range** using semver syntax (e.g., `>=1.5.0 <2.0.0`)
114+
2. **Add to configOverrides** with partial config (only override what changed)
115+
3. **Add tests** in `src/__tests__/sdks-config.test.ts`
116+
4. **Document here** with notes on what changed and why
117+
118+
### Example: Adding a new override
119+
120+
```typescript
121+
configOverrides: {
122+
">=1.0.0 <1.5.0": {
123+
// Old structure
124+
},
125+
">=1.5.0 <2.0.0": {
126+
// New structure introduced in 1.5.0
127+
},
128+
">=2.0.0": {
129+
// Breaking changes in 2.0.0
130+
},
131+
}
132+
```
133+
134+
## Resolution Logic
135+
136+
The config resolution follows these rules:
137+
138+
1. Start with `defaultConfig`
139+
2. Find the **first matching** semver range in `configOverrides`
140+
3. Shallow merge override into default (override wins)
141+
4. Return merged config
142+
143+
This means:
144+
- `defaultConfig` should represent the **latest/current** structure
145+
- `configOverrides` handles older versions or special cases
146+
- Order matters when multiple ranges could match (first match wins)
147+
148+
## Testing
149+
150+
Tests in `src/__tests__/sdks-config.test.ts` verify:
151+
- Correct packages/entry points for each version range
152+
- Proper semver range matching
153+
- Expected counts of items per version
154+
155+
Run tests with:
156+
```bash
157+
pnpm test src/__tests__/sdks-config.test.ts
158+
```
159+

‎sdk-reference-generator/configs/typedoc.json‎

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

‎sdk-reference-generator/sdks.config.ts‎

Lines changed: 74 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,41 @@ const sdks = {
2525
generator: "typedoc",
2626
required: true,
2727
minVersion: "1.0.0",
28+
29+
defaultConfig: {
30+
entryPoints: [
31+
"src/sandbox/index.ts",
32+
"src/sandbox/filesystem/index.ts",
33+
"src/sandbox/process/index.ts",
34+
"src/sandbox/commands/index.ts",
35+
"src/errors.ts",
36+
"src/template/index.ts",
37+
"src/template/readycmd.ts",
38+
"src/template/logger.ts",
39+
],
40+
},
41+
42+
configOverrides: {
43+
"1.0.0": {
44+
entryPoints: [
45+
"src/sandbox/index.ts",
46+
"src/sandbox/filesystem/index.ts",
47+
"src/sandbox/process/index.ts",
48+
"src/sandbox/pty.ts",
49+
"src/errors.ts",
50+
],
51+
},
52+
53+
">=1.1.0 <2.3.0": {
54+
entryPoints: [
55+
"src/sandbox/index.ts",
56+
"src/sandbox/filesystem/index.ts",
57+
"src/sandbox/process/index.ts",
58+
"src/sandbox/commands/index.ts",
59+
"src/errors.ts",
60+
],
61+
},
62+
},
2863
},
2964

3065
"python-sdk": {
@@ -38,16 +73,29 @@ const sdks = {
3873
generator: "pydoc",
3974
required: true,
4075
minVersion: "1.0.0",
41-
allowedPackages: [
42-
"e2b.sandbox_sync",
43-
"e2b.sandbox_async",
44-
"e2b.exceptions",
45-
"e2b.template",
46-
"e2b.template_sync",
47-
"e2b.template_async",
48-
"e2b.template.logger",
49-
"e2b.template.readycmd",
50-
],
76+
77+
defaultConfig: {
78+
allowedPackages: [
79+
"e2b.sandbox_sync",
80+
"e2b.sandbox_async",
81+
"e2b.exceptions",
82+
"e2b.template",
83+
"e2b.template_sync",
84+
"e2b.template_async",
85+
"e2b.template.logger",
86+
"e2b.template.readycmd",
87+
],
88+
},
89+
90+
configOverrides: {
91+
">=1.0.0 <2.1.0": {
92+
allowedPackages: [
93+
"e2b.sandbox_sync",
94+
"e2b.sandbox_async",
95+
"e2b.exceptions",
96+
],
97+
},
98+
},
5199
},
52100

53101
"code-interpreter-js-sdk": {
@@ -61,6 +109,10 @@ const sdks = {
61109
generator: "typedoc",
62110
required: false,
63111
minVersion: "1.0.0",
112+
113+
defaultConfig: {
114+
entryPoints: ["src/index.ts"],
115+
},
64116
},
65117

66118
"code-interpreter-python-sdk": {
@@ -74,7 +126,10 @@ const sdks = {
74126
generator: "pydoc",
75127
required: false,
76128
minVersion: "1.0.0",
77-
allowedPackages: ["e2b_code_interpreter"],
129+
130+
defaultConfig: {
131+
allowedPackages: ["e2b_code_interpreter"],
132+
},
78133
},
79134

80135
"desktop-js-sdk": {
@@ -88,6 +143,10 @@ const sdks = {
88143
generator: "typedoc",
89144
required: false,
90145
minVersion: "1.0.0",
146+
147+
defaultConfig: {
148+
entryPoints: ["src/index.ts"],
149+
},
91150
},
92151

93152
"desktop-python-sdk": {
@@ -101,7 +160,10 @@ const sdks = {
101160
generator: "pydoc",
102161
required: false,
103162
minVersion: "1.0.0",
104-
allowedPackages: ["e2b_desktop"],
163+
164+
defaultConfig: {
165+
allowedPackages: ["e2b_desktop"],
166+
},
105167
},
106168
} as const satisfies Record<string, SDKConfig>;
107169

0 commit comments

Comments
 (0)