ultracontext 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +146 -0
- package/dist/index.d.ts +116 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +110 -0
- package/package.json +56 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ultracontext
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://ultracontext.ai">
|
|
3
|
+
<img src="https://github.com/user-attachments/assets/874841ae-374d-46df-bc2a-388aff7cd024" alt="UltraContext" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h3 align="center">The context API for AI agents.</h3>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://ultracontext.ai/docs/quickstart/nodejs">Quickstart</a>
|
|
11
|
+
·
|
|
12
|
+
<a href="https://ultracontext.ai/docs">Documentation</a>
|
|
13
|
+
·
|
|
14
|
+
<a href="https://ultracontext.ai/docs/api-reference/introduction">API Reference</a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<a href="https://www.npmjs.com/package/ultracontext">
|
|
19
|
+
<img src="https://img.shields.io/npm/v/ultracontext" alt="npm version" />
|
|
20
|
+
</a>
|
|
21
|
+
<a href="https://github.com/ultracontext/ultracontext-node/blob/main/LICENSE">
|
|
22
|
+
<img src="https://img.shields.io/npm/l/ultracontext" alt="license" />
|
|
23
|
+
</a>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
<br />
|
|
27
|
+
|
|
28
|
+
<p align="center">📚 Guides</p>
|
|
29
|
+
<p align="center">
|
|
30
|
+
<a href="https://ultracontext.ai/docs/guides/store-retrieve-contexts">Store & Retrieve</a>
|
|
31
|
+
·
|
|
32
|
+
<a href="https://ultracontext.ai/docs/guides/edit-contexts">Edit Contexts</a>
|
|
33
|
+
·
|
|
34
|
+
<a href="https://ultracontext.ai/docs/guides/fork-clone-contexts">Fork & Clone</a>
|
|
35
|
+
·
|
|
36
|
+
<a href="https://ultracontext.ai/docs/guides/view-context-history">View History</a>
|
|
37
|
+
</p>
|
|
38
|
+
|
|
39
|
+
<br />
|
|
40
|
+
|
|
41
|
+
UltraContext is the simplest way to control what your agents see.
|
|
42
|
+
|
|
43
|
+
Replace messages, compact/offload context, replay decisions and roll back mistakes — with a single API call. Versioned context out of the box. Full history. Zero complexity.
|
|
44
|
+
|
|
45
|
+
<br />
|
|
46
|
+
|
|
47
|
+
## Why Context Matters
|
|
48
|
+
|
|
49
|
+
Context is the RAM of LLMs — everything they can see.
|
|
50
|
+
|
|
51
|
+
As context grows, model attention spreads thin — this is known as **context rot**. We should aim to provide the smallest set of high-signal tokens that get the job done.
|
|
52
|
+
|
|
53
|
+
Right now, we're reinventing the wheel for every car we build. Instead of tackling interesting problems, we catch ourselves spending most of our time gluing context together.
|
|
54
|
+
|
|
55
|
+
**It's time to simplify.**
|
|
56
|
+
|
|
57
|
+
<br />
|
|
58
|
+
|
|
59
|
+
## Why UltraContext
|
|
60
|
+
|
|
61
|
+
- **Simple API** — Five methods. That's it.
|
|
62
|
+
- **Automatic versioning** — Updates/deletes create versions. Nothing is lost.
|
|
63
|
+
- **Time-travel** — Jump to any point by version, index, or timestamp.
|
|
64
|
+
- **Schema-free** — Store any JSON. Own your data structure.
|
|
65
|
+
- **Framework-agnostic** — Works with any LLM framework.
|
|
66
|
+
- **Fast** — Globally distributed. Low latency.
|
|
67
|
+
|
|
68
|
+
Just plug & play.
|
|
69
|
+
|
|
70
|
+
<br />
|
|
71
|
+
|
|
72
|
+
## Install
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npm install ultracontext
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
<br />
|
|
79
|
+
|
|
80
|
+
## 🚀 Quick Start
|
|
81
|
+
|
|
82
|
+
```js
|
|
83
|
+
import { UltraContext } from 'ultracontext';
|
|
84
|
+
|
|
85
|
+
const uc = new UltraContext({ apiKey: 'uc_live_...' });
|
|
86
|
+
|
|
87
|
+
const ctx = await uc.create();
|
|
88
|
+
await uc.append(ctx.id, { role: 'user', content: 'Hello!' });
|
|
89
|
+
|
|
90
|
+
// use with any LLM framework
|
|
91
|
+
const response = await generateText({ model, messages: ctx.data });
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Get an API key from the [UltraContext Dashboard](https://ultracontext.ai/dashboard).
|
|
95
|
+
|
|
96
|
+
<br />
|
|
97
|
+
|
|
98
|
+
## API
|
|
99
|
+
|
|
100
|
+
```js
|
|
101
|
+
// create - new context or fork from existing
|
|
102
|
+
const ctx = await uc.create();
|
|
103
|
+
const fork = await uc.create({ from: 'ctx_abc123' });
|
|
104
|
+
|
|
105
|
+
// get - retrieve context (supports version, index, timestamp)
|
|
106
|
+
const { data } = await uc.get('ctx_abc123');
|
|
107
|
+
const { data } = await uc.get('ctx_abc123', { version: 2 });
|
|
108
|
+
const { data } = await uc.get('ctx_abc123', { at: 5 });
|
|
109
|
+
const { data, versions } = await uc.get('ctx_abc123', { history: true });
|
|
110
|
+
|
|
111
|
+
// append - add messages (schema-free)
|
|
112
|
+
await uc.append(ctx.id, { role: 'user', content: 'Hi' });
|
|
113
|
+
await uc.append(ctx.id, [{ role: 'user', content: 'Hi' }, { foo: 'bar' }]);
|
|
114
|
+
|
|
115
|
+
// update - modify by id or index (auto-versions)
|
|
116
|
+
await uc.update(ctx.id, { id: 'msg_xyz', content: 'Fixed!' });
|
|
117
|
+
await uc.update(ctx.id, { index: -1, content: 'Fix last message' });
|
|
118
|
+
|
|
119
|
+
// delete - remove by id or index (auto-versions)
|
|
120
|
+
await uc.delete(ctx.id, 'msg_xyz');
|
|
121
|
+
await uc.delete(ctx.id, -1);
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
<br />
|
|
125
|
+
|
|
126
|
+
## Documentation
|
|
127
|
+
|
|
128
|
+
- [Quickstart](https://ultracontext.ai/docs/quickstart/nodejs) — Get running in 2 minutes
|
|
129
|
+
- [Guides](https://ultracontext.ai/docs/guides/store-retrieve-contexts) — Practical patterns for common use cases
|
|
130
|
+
- [API Reference](https://ultracontext.ai/docs/api-reference/introduction) — Full endpoint documentation
|
|
131
|
+
|
|
132
|
+
<br />
|
|
133
|
+
|
|
134
|
+
## License
|
|
135
|
+
|
|
136
|
+
MIT
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
<p align="center">
|
|
141
|
+
<a href="https://ultracontext.ai">Website</a>
|
|
142
|
+
·
|
|
143
|
+
<a href="https://ultracontext.ai/docs">Docs</a>
|
|
144
|
+
·
|
|
145
|
+
<a href="https://github.com/ultracontext/ultracontext-node/issues">Issues</a>
|
|
146
|
+
</p>
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
export type UltraContextConfig = {
|
|
2
|
+
apiKey: string;
|
|
3
|
+
baseUrl?: string;
|
|
4
|
+
fetch?: typeof fetch;
|
|
5
|
+
headers?: Record<string, string>;
|
|
6
|
+
timeoutMs?: number;
|
|
7
|
+
};
|
|
8
|
+
export type Version = {
|
|
9
|
+
version: number;
|
|
10
|
+
created_at: string;
|
|
11
|
+
operation: 'create' | 'update' | 'delete';
|
|
12
|
+
affected: string[] | null;
|
|
13
|
+
metadata?: Record<string, unknown>;
|
|
14
|
+
};
|
|
15
|
+
export type CreateContextInput = {
|
|
16
|
+
from?: string;
|
|
17
|
+
version?: number;
|
|
18
|
+
at?: number;
|
|
19
|
+
before?: string;
|
|
20
|
+
metadata?: Record<string, unknown>;
|
|
21
|
+
};
|
|
22
|
+
export type CreateContextResponse = {
|
|
23
|
+
id: string;
|
|
24
|
+
metadata: Record<string, unknown>;
|
|
25
|
+
created_at: string;
|
|
26
|
+
};
|
|
27
|
+
export type AppendMessage = Omit<Record<string, unknown>, 'metadata'> & {
|
|
28
|
+
metadata?: Record<string, unknown>;
|
|
29
|
+
};
|
|
30
|
+
export type AppendInput = AppendMessage | AppendMessage[];
|
|
31
|
+
export type AppendResponse<T = unknown> = {
|
|
32
|
+
data: Array<{
|
|
33
|
+
id: string;
|
|
34
|
+
index: number;
|
|
35
|
+
metadata: Record<string, unknown>;
|
|
36
|
+
} & T>;
|
|
37
|
+
version: number;
|
|
38
|
+
};
|
|
39
|
+
export type GetContextInput = {
|
|
40
|
+
version?: number;
|
|
41
|
+
at?: number;
|
|
42
|
+
before?: string;
|
|
43
|
+
history?: boolean;
|
|
44
|
+
};
|
|
45
|
+
export type GetContextResponse<T = unknown> = {
|
|
46
|
+
data: Array<{
|
|
47
|
+
id: string;
|
|
48
|
+
index: number;
|
|
49
|
+
metadata: Record<string, unknown>;
|
|
50
|
+
} & T>;
|
|
51
|
+
version: number;
|
|
52
|
+
versions?: Version[];
|
|
53
|
+
};
|
|
54
|
+
export type ListContextsResponse = {
|
|
55
|
+
data: Array<{
|
|
56
|
+
id: string;
|
|
57
|
+
metadata: Record<string, unknown>;
|
|
58
|
+
created_at: string;
|
|
59
|
+
}>;
|
|
60
|
+
};
|
|
61
|
+
export type MutationOptions = {
|
|
62
|
+
metadata?: Record<string, unknown>;
|
|
63
|
+
};
|
|
64
|
+
export type UpdateMessageInput = ({
|
|
65
|
+
id: string;
|
|
66
|
+
index?: never;
|
|
67
|
+
} & Record<string, unknown>) | ({
|
|
68
|
+
index: number;
|
|
69
|
+
id?: never;
|
|
70
|
+
} & Record<string, unknown>);
|
|
71
|
+
export type UpdateInput = UpdateMessageInput | UpdateMessageInput[];
|
|
72
|
+
export type UpdateResponse<T = unknown> = {
|
|
73
|
+
data: Array<{
|
|
74
|
+
id: string;
|
|
75
|
+
index: number;
|
|
76
|
+
metadata: Record<string, unknown>;
|
|
77
|
+
} & T>;
|
|
78
|
+
version: number;
|
|
79
|
+
};
|
|
80
|
+
export type DeleteInput = (string | number) | (string | number)[];
|
|
81
|
+
export type DeleteResponse<T = unknown> = {
|
|
82
|
+
data: Array<{
|
|
83
|
+
id: string;
|
|
84
|
+
index: number;
|
|
85
|
+
metadata: Record<string, unknown>;
|
|
86
|
+
} & T>;
|
|
87
|
+
version: number;
|
|
88
|
+
};
|
|
89
|
+
export declare class UltraContextHttpError extends Error {
|
|
90
|
+
readonly status: number;
|
|
91
|
+
readonly url: string;
|
|
92
|
+
readonly bodyText?: string;
|
|
93
|
+
constructor(args: {
|
|
94
|
+
status: number;
|
|
95
|
+
url: string;
|
|
96
|
+
bodyText?: string;
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
export declare class UltraContext {
|
|
100
|
+
private readonly baseUrl;
|
|
101
|
+
private readonly apiKey;
|
|
102
|
+
private readonly fetchFn;
|
|
103
|
+
private readonly headers?;
|
|
104
|
+
private readonly timeoutMs?;
|
|
105
|
+
constructor(cfg: UltraContextConfig);
|
|
106
|
+
create(input?: CreateContextInput): Promise<CreateContextResponse>;
|
|
107
|
+
append<T = unknown>(contextId: string, input: AppendInput): Promise<AppendResponse<T>>;
|
|
108
|
+
get(options?: {
|
|
109
|
+
limit?: number;
|
|
110
|
+
}): Promise<ListContextsResponse>;
|
|
111
|
+
get<T = unknown>(id: string, options?: GetContextInput): Promise<GetContextResponse<T>>;
|
|
112
|
+
update<T = unknown>(contextId: string, input: UpdateInput, options?: MutationOptions): Promise<UpdateResponse<T>>;
|
|
113
|
+
delete<T = unknown>(contextId: string, ids: DeleteInput, options?: MutationOptions): Promise<DeleteResponse<T>>;
|
|
114
|
+
private request;
|
|
115
|
+
}
|
|
116
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
export class UltraContextHttpError extends Error {
|
|
2
|
+
constructor(args) {
|
|
3
|
+
super(`UltraContext request failed: ${args.status} ${args.url}`);
|
|
4
|
+
this.name = 'UltraContextHttpError';
|
|
5
|
+
this.status = args.status;
|
|
6
|
+
this.url = args.url;
|
|
7
|
+
this.bodyText = args.bodyText;
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
export class UltraContext {
|
|
11
|
+
constructor(cfg) {
|
|
12
|
+
this.baseUrl = (cfg.baseUrl ?? 'https://api.ultracontext.ai').replace(/\/+$/, '');
|
|
13
|
+
this.apiKey = cfg.apiKey;
|
|
14
|
+
this.fetchFn = cfg.fetch ?? fetch;
|
|
15
|
+
this.headers = cfg.headers;
|
|
16
|
+
this.timeoutMs = cfg.timeoutMs;
|
|
17
|
+
}
|
|
18
|
+
async create(input = {}) {
|
|
19
|
+
return this.request('/contexts', {
|
|
20
|
+
method: 'POST',
|
|
21
|
+
body: input,
|
|
22
|
+
});
|
|
23
|
+
}
|
|
24
|
+
async append(contextId, input) {
|
|
25
|
+
return this.request(`/contexts/${encodeURIComponent(contextId)}`, {
|
|
26
|
+
method: 'POST',
|
|
27
|
+
body: input,
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
async get(idOrOptions, options) {
|
|
31
|
+
if (!idOrOptions || typeof idOrOptions === 'object') {
|
|
32
|
+
const params = new URLSearchParams();
|
|
33
|
+
if (typeof idOrOptions === 'object' && idOrOptions.limit)
|
|
34
|
+
params.set('limit', String(idOrOptions.limit));
|
|
35
|
+
const query = params.toString();
|
|
36
|
+
return this.request(`/contexts${query ? `?${query}` : ''}`, { method: 'GET' });
|
|
37
|
+
}
|
|
38
|
+
const params = new URLSearchParams();
|
|
39
|
+
if (options?.version !== undefined)
|
|
40
|
+
params.set('version', String(options.version));
|
|
41
|
+
if (options?.at !== undefined)
|
|
42
|
+
params.set('at', String(options.at));
|
|
43
|
+
if (options?.before)
|
|
44
|
+
params.set('before', options.before);
|
|
45
|
+
if (options?.history)
|
|
46
|
+
params.set('history', 'true');
|
|
47
|
+
const query = params.toString();
|
|
48
|
+
return this.request(`/contexts/${encodeURIComponent(idOrOptions)}${query ? `?${query}` : ''}`, { method: 'GET' });
|
|
49
|
+
}
|
|
50
|
+
async update(contextId, input, options) {
|
|
51
|
+
const body = options?.metadata
|
|
52
|
+
? { updates: Array.isArray(input) ? input : [input], metadata: options.metadata }
|
|
53
|
+
: input;
|
|
54
|
+
return this.request(`/contexts/${encodeURIComponent(contextId)}`, {
|
|
55
|
+
method: 'PATCH',
|
|
56
|
+
body,
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
async delete(contextId, ids, options) {
|
|
60
|
+
return this.request(`/contexts/${encodeURIComponent(contextId)}`, {
|
|
61
|
+
method: 'DELETE',
|
|
62
|
+
body: { ids, metadata: options?.metadata },
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
async request(path, init) {
|
|
66
|
+
const url = `${this.baseUrl}${path.startsWith('/') ? '' : '/'}${path}`;
|
|
67
|
+
const headers = {
|
|
68
|
+
Authorization: `Bearer ${this.apiKey}`,
|
|
69
|
+
...(this.headers ?? {}),
|
|
70
|
+
...(init.headers ?? {}),
|
|
71
|
+
};
|
|
72
|
+
let body;
|
|
73
|
+
if (init.body !== undefined) {
|
|
74
|
+
headers['Content-Type'] = headers['Content-Type'] ?? 'application/json';
|
|
75
|
+
body = JSON.stringify(init.body);
|
|
76
|
+
}
|
|
77
|
+
const ac = this.timeoutMs ? new AbortController() : undefined;
|
|
78
|
+
const timeout = this.timeoutMs ? setTimeout(() => ac?.abort(), this.timeoutMs) : undefined;
|
|
79
|
+
try {
|
|
80
|
+
const res = await this.fetchFn(url, {
|
|
81
|
+
method: init.method,
|
|
82
|
+
headers,
|
|
83
|
+
body,
|
|
84
|
+
signal: ac?.signal,
|
|
85
|
+
});
|
|
86
|
+
if (!res.ok) {
|
|
87
|
+
const bodyText = await safeReadText(res);
|
|
88
|
+
throw new UltraContextHttpError({ status: res.status, url, bodyText });
|
|
89
|
+
}
|
|
90
|
+
if (res.status === 204)
|
|
91
|
+
return undefined;
|
|
92
|
+
const contentType = res.headers.get('content-type') ?? '';
|
|
93
|
+
if (contentType.includes('application/json'))
|
|
94
|
+
return (await res.json());
|
|
95
|
+
return (await res.text());
|
|
96
|
+
}
|
|
97
|
+
finally {
|
|
98
|
+
if (timeout)
|
|
99
|
+
clearTimeout(timeout);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
async function safeReadText(res) {
|
|
104
|
+
try {
|
|
105
|
+
return await res.text();
|
|
106
|
+
}
|
|
107
|
+
catch {
|
|
108
|
+
return undefined;
|
|
109
|
+
}
|
|
110
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "ultracontext",
|
|
3
|
+
"description": "Node.js library for the UltraContext API",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"engines": {
|
|
6
|
+
"node": ">=18"
|
|
7
|
+
},
|
|
8
|
+
"scripts": {
|
|
9
|
+
"build": "tsc",
|
|
10
|
+
"dev": "tsc --watch",
|
|
11
|
+
"prepare": "npm run build"
|
|
12
|
+
},
|
|
13
|
+
"version": "1.0.0",
|
|
14
|
+
"main": "./dist/index.js",
|
|
15
|
+
"types": "./dist/index.d.ts",
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "git+https://github.com/ultracontext/ultracontext-node.git"
|
|
19
|
+
},
|
|
20
|
+
"author": "Ultracontext",
|
|
21
|
+
"license": "MIT",
|
|
22
|
+
"bugs": {
|
|
23
|
+
"url": "https://github.com/ultracontext/ultracontext-node/issues"
|
|
24
|
+
},
|
|
25
|
+
"homepage": "https://ultracontext.ai",
|
|
26
|
+
"keywords": [
|
|
27
|
+
"ai",
|
|
28
|
+
"llm",
|
|
29
|
+
"context",
|
|
30
|
+
"agents",
|
|
31
|
+
"ai-agents",
|
|
32
|
+
"context-engineering",
|
|
33
|
+
"context-management",
|
|
34
|
+
"context-window",
|
|
35
|
+
"versioning",
|
|
36
|
+
"time-travel",
|
|
37
|
+
"rollback",
|
|
38
|
+
"chat",
|
|
39
|
+
"conversation",
|
|
40
|
+
"typescript"
|
|
41
|
+
],
|
|
42
|
+
"exports": {
|
|
43
|
+
".": {
|
|
44
|
+
"types": "./dist/index.d.ts",
|
|
45
|
+
"import": "./dist/index.js",
|
|
46
|
+
"default": "./dist/index.js"
|
|
47
|
+
}
|
|
48
|
+
},
|
|
49
|
+
"files": [
|
|
50
|
+
"dist"
|
|
51
|
+
],
|
|
52
|
+
"devDependencies": {
|
|
53
|
+
"typescript": "^5.9.3"
|
|
54
|
+
},
|
|
55
|
+
"packageManager": "pnpm@10.25.0"
|
|
56
|
+
}
|