xmemory 3.6.0 → 3.8.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/README.md +54 -5
- package/dist/cjs/client.js +369 -0
- package/dist/{index.d.ts → cjs/index.d.ts} +1 -1
- package/dist/cjs/index.js +27 -0
- package/dist/{instance.d.ts → cjs/instance.d.ts} +13 -1
- package/dist/cjs/instance.js +364 -0
- package/dist/cjs/package.json +1 -0
- package/dist/{types.d.ts → cjs/types.d.ts} +21 -3
- package/dist/cjs/types.js +128 -0
- package/dist/esm/client.d.ts +73 -0
- package/dist/esm/index.d.ts +16 -0
- package/dist/esm/instance.d.ts +154 -0
- package/dist/{instance.js → esm/instance.js} +18 -6
- package/dist/esm/package.json +1 -0
- package/dist/esm/types.d.ts +813 -0
- package/package.json +21 -4
- /package/dist/{client.d.ts → cjs/client.d.ts} +0 -0
- /package/dist/{client.js → esm/client.js} +0 -0
- /package/dist/{index.js → esm/index.js} +0 -0
- /package/dist/{types.js → esm/types.js} +0 -0
package/README.md
CHANGED
|
@@ -8,6 +8,9 @@ TypeScript/JavaScript client library for the [xmemory](https://xmemory.ai) API.
|
|
|
8
8
|
npm install xmemory
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
+
The package ships both ESM and CommonJS builds. `import` and `require` both
|
|
12
|
+
work, and TypeScript resolves the matching declarations either way.
|
|
13
|
+
|
|
11
14
|
## Quick start
|
|
12
15
|
|
|
13
16
|
```typescript
|
|
@@ -191,7 +194,8 @@ Every data operation — `read`, `write`, `writeAsync`, `writeStatus`, `extract`
|
|
|
191
194
|
`console_url`, the deep link to that call's trace. It is per operation rather than per
|
|
192
195
|
record, and `null` when the server has no console configured.
|
|
193
196
|
|
|
194
|
-
Options: `{ extractionLogic?, diffEngine?, timeoutMs? }` — `extractionLogic`
|
|
197
|
+
Options: `{ extractionLogic?, diffEngine?, scope?, timeoutMs? }` — `extractionLogic`
|
|
198
|
+
defaults to `"fast"`; see [Scoped writes](#scoped-writes) for `scope`.
|
|
195
199
|
|
|
196
200
|
Or pass a `WriteMutation[]` for **structured writes** — deterministic, LLM-free
|
|
197
201
|
create/update/delete mutations applied in array order (later mutations may
|
|
@@ -219,8 +223,9 @@ Options for the mutations form: `{ timeoutMs? }` (extraction options don't apply
|
|
|
219
223
|
|
|
220
224
|
### `inst.writeAsync(text | mutations, options?)` → `AsyncWriteResult`
|
|
221
225
|
|
|
222
|
-
Start an asynchronous write (same text / `WriteMutation[]` dual input
|
|
223
|
-
`inst.write`). Returns a `write_id` for
|
|
226
|
+
Start an asynchronous write (same text / `WriteMutation[]` dual input and the
|
|
227
|
+
same options as `inst.write`, `scope` included). Returns a `write_id` for
|
|
228
|
+
tracking; a scope violation is reported by `inst.writeStatus` as a failed write.
|
|
224
229
|
|
|
225
230
|
```typescript
|
|
226
231
|
const { write_id } = await inst.writeAsync("Carol manages the London office.");
|
|
@@ -272,8 +277,9 @@ records you care about, or for keeping a per-user / per-entity read from leaking
|
|
|
272
277
|
into unrelated data.
|
|
273
278
|
|
|
274
279
|
Each object in the scope is identified by its `type` (the PascalCase class name
|
|
275
|
-
or snake_case table name) plus its user-defined primary `key
|
|
276
|
-
primary-key field name to value
|
|
280
|
+
or snake_case table name) plus its user-defined primary `key`, a mapping of
|
|
281
|
+
primary-key field name to value. Only objects of a type that has a user-defined
|
|
282
|
+
primary key can be scoped:
|
|
277
283
|
|
|
278
284
|
```typescript
|
|
279
285
|
const result = await inst.read("What do we know about these people?", {
|
|
@@ -291,6 +297,49 @@ const result = await inst.read("What do we know about these people?", {
|
|
|
291
297
|
restricts the read to the listed objects only, while `"all_relations"` also
|
|
292
298
|
exposes the relations among the in-scope objects.
|
|
293
299
|
|
|
300
|
+
#### Scoped writes
|
|
301
|
+
|
|
302
|
+
A write is normally free to touch anything in the instance: the extractor sees
|
|
303
|
+
the text alone, and whatever it produces is reconciled against the whole
|
|
304
|
+
instance. Pass a `scope` to anchor a text write to a set of concrete existing
|
|
305
|
+
objects instead — the same `ScopeObject` shape as a scoped read:
|
|
306
|
+
|
|
307
|
+
```typescript
|
|
308
|
+
const result = await inst.write(
|
|
309
|
+
"After her promotion she is a surgeon, and her desk phone is +1-555-0100.",
|
|
310
|
+
{ scope: { objects: [{ type: "Person", key: { full_name: "Alice Smith" } }] } },
|
|
311
|
+
);
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
This does two things at once. The scoped objects' **current values** are shown
|
|
315
|
+
to the extractor, so the new information is folded into them instead of
|
|
316
|
+
producing a near-duplicate record. And the write is then **confined** to the
|
|
317
|
+
scope: it may only modify or delete the scoped objects, and create new objects
|
|
318
|
+
and relations anchored to them. A write that would touch any other existing
|
|
319
|
+
object fails with a validation error rather than applying partially — that
|
|
320
|
+
confinement is checked against the resulting plan, so it holds regardless of
|
|
321
|
+
what the extractor produced.
|
|
322
|
+
|
|
323
|
+
A write scope takes the same `ScopeObject`s as a read scope, identified the same
|
|
324
|
+
way. Unlike a read scope there is no `relationsScope`: the relations among the
|
|
325
|
+
scoped objects always accompany the extraction hint.
|
|
326
|
+
|
|
327
|
+
Things to know before reaching for it:
|
|
328
|
+
|
|
329
|
+
- Scope applies to **text writes only**. The `WriteMutation[]` overload takes
|
|
330
|
+
`{ timeoutMs? }`, so passing a scope alongside structured mutations does not
|
|
331
|
+
compile — those bypass extraction entirely and leave a scope nothing to
|
|
332
|
+
anchor to.
|
|
333
|
+
- Only objects of a type with a **user-defined primary key** can be scoped. A
|
|
334
|
+
scope names records by that key, so a type declared `primary_key: []` has
|
|
335
|
+
nothing to name its records by.
|
|
336
|
+
- The server currently accepts a scope with **fast extraction only**, and caps
|
|
337
|
+
the number of scoped objects per write. Both are server-side rules, so they
|
|
338
|
+
surface as an `XmemoryAPIError`.
|
|
339
|
+
- A scoped write additionally requires **read** permission on the instance,
|
|
340
|
+
because the scoped objects' current values are shown to the extractor. An API
|
|
341
|
+
key with write access alone is refused.
|
|
342
|
+
|
|
294
343
|
### `inst.extract(text, options?)` → `ExtractResult`
|
|
295
344
|
|
|
296
345
|
Extract objects from text without storing them.
|
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* XmemoryClient — main entry point for the xmemory API.
|
|
4
|
+
*/
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.XmemoryClient = void 0;
|
|
7
|
+
exports.xmemoryInstance = xmemoryInstance;
|
|
8
|
+
const instance_js_1 = require("./instance.js");
|
|
9
|
+
const types_js_1 = require("./types.js");
|
|
10
|
+
const DEFAULT_BASE_URL = "https://api.xmemory.ai";
|
|
11
|
+
const DEFAULT_TIMEOUT_MS = 60_000;
|
|
12
|
+
const ORANGE = "\x1b[38;5;208m";
|
|
13
|
+
const RESET = "\x1b[0m";
|
|
14
|
+
function deprecationWarning(message) {
|
|
15
|
+
console.warn(`${ORANGE}[xmemory] DEPRECATION: ${message}${RESET}`);
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Pull a structured error out of an error body. Handles the schema-evolution
|
|
19
|
+
* shape (`{status: "error", error_type, error_message, details}`, where
|
|
20
|
+
* `error_type` is the code) and the standard `{errors: [{code, message}]}`
|
|
21
|
+
* envelope.
|
|
22
|
+
*/
|
|
23
|
+
function extractStructuredError(payload) {
|
|
24
|
+
if (typeof payload !== "object" || payload === null)
|
|
25
|
+
return {};
|
|
26
|
+
const p = payload;
|
|
27
|
+
if (p.status === "error" && typeof p.error_type === "string") {
|
|
28
|
+
return {
|
|
29
|
+
code: p.error_type,
|
|
30
|
+
message: typeof p.error_message === "string" ? p.error_message : undefined,
|
|
31
|
+
details: (p.details ?? null),
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
const errors = p.errors;
|
|
35
|
+
if (Array.isArray(errors) && errors.length > 0 && typeof errors[0] === "object" && errors[0] !== null) {
|
|
36
|
+
const first = errors[0];
|
|
37
|
+
return {
|
|
38
|
+
code: typeof first.code === "string" ? first.code : undefined,
|
|
39
|
+
message: typeof first.message === "string" ? first.message : undefined,
|
|
40
|
+
details: (first.details ?? null),
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
return {};
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Parse the HTTP `Retry-After` response header into a number of seconds, or
|
|
47
|
+
* `undefined` when the header is absent or unparseable. Supports both the
|
|
48
|
+
* delta-seconds form (`Retry-After: 30`) and the HTTP-date form; HTTP-dates
|
|
49
|
+
* are converted to a non-negative second offset from now.
|
|
50
|
+
*/
|
|
51
|
+
function parseRetryAfter(res) {
|
|
52
|
+
const raw = res.headers.get("Retry-After");
|
|
53
|
+
if (raw == null)
|
|
54
|
+
return undefined;
|
|
55
|
+
const trimmed = raw.trim();
|
|
56
|
+
if (trimmed === "")
|
|
57
|
+
return undefined;
|
|
58
|
+
if (/^\d+$/.test(trimmed))
|
|
59
|
+
return Number(trimmed);
|
|
60
|
+
const dateMs = Date.parse(trimmed);
|
|
61
|
+
if (Number.isNaN(dateMs))
|
|
62
|
+
return undefined;
|
|
63
|
+
return Math.max(0, Math.round((dateMs - Date.now()) / 1000));
|
|
64
|
+
}
|
|
65
|
+
// ---------------------------------------------------------------------------
|
|
66
|
+
// Client
|
|
67
|
+
// ---------------------------------------------------------------------------
|
|
68
|
+
class XmemoryClient {
|
|
69
|
+
_baseUrl;
|
|
70
|
+
_timeoutMs;
|
|
71
|
+
_apiKey;
|
|
72
|
+
admin;
|
|
73
|
+
constructor(options = {}) {
|
|
74
|
+
const env = typeof process !== "undefined" ? process.env : undefined;
|
|
75
|
+
this._baseUrl = (options.url ?? env?.XMEM_API_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
76
|
+
this._apiKey = XmemoryClient._resolveApiKey(options, env);
|
|
77
|
+
this._timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
78
|
+
this.admin = this._buildAdmin();
|
|
79
|
+
}
|
|
80
|
+
static _resolveApiKey(options, env) {
|
|
81
|
+
if (options.apiKey != null)
|
|
82
|
+
return options.apiKey;
|
|
83
|
+
if (options.token != null) {
|
|
84
|
+
deprecationWarning("The `token` constructor option is deprecated and will be removed soon. Use `apiKey` instead.");
|
|
85
|
+
return options.token;
|
|
86
|
+
}
|
|
87
|
+
if (env?.XMEM_API_KEY)
|
|
88
|
+
return env.XMEM_API_KEY;
|
|
89
|
+
if (env?.XMEM_AUTH_TOKEN) {
|
|
90
|
+
deprecationWarning("The `XMEM_AUTH_TOKEN` environment variable is deprecated and will be removed soon. Use `XMEM_API_KEY` instead.");
|
|
91
|
+
return env.XMEM_AUTH_TOKEN;
|
|
92
|
+
}
|
|
93
|
+
return undefined;
|
|
94
|
+
}
|
|
95
|
+
/** Factory that performs a health check before returning the client. */
|
|
96
|
+
static async create(options = {}) {
|
|
97
|
+
const client = new XmemoryClient(options);
|
|
98
|
+
await client.checkHealth();
|
|
99
|
+
return client;
|
|
100
|
+
}
|
|
101
|
+
/** Return an InstanceHandle scoped to the given instance ID. */
|
|
102
|
+
instance(instanceId) {
|
|
103
|
+
return new instance_js_1.InstanceHandle(instanceId, this._requestOne.bind(this));
|
|
104
|
+
}
|
|
105
|
+
/** GET /healthz — throws XmemoryHealthCheckError on failure. */
|
|
106
|
+
async checkHealth() {
|
|
107
|
+
const url = `${this._baseUrl}/healthz`;
|
|
108
|
+
try {
|
|
109
|
+
const res = await this._fetch(url, { method: "GET" }, this._timeoutMs);
|
|
110
|
+
if (!res.ok) {
|
|
111
|
+
throw new types_js_1.XmemoryHealthCheckError(`Health check failed: HTTP ${res.status} at ${url}`, res.status);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
catch (err) {
|
|
115
|
+
if (err instanceof types_js_1.XmemoryHealthCheckError)
|
|
116
|
+
throw err;
|
|
117
|
+
throw new types_js_1.XmemoryHealthCheckError(`Health check failed: ${err instanceof Error ? err.message : String(err)}`);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
// -----------------------------------------------------------------------
|
|
121
|
+
// Private: HTTP layer
|
|
122
|
+
// -----------------------------------------------------------------------
|
|
123
|
+
async _fetch(url, init, timeoutMs) {
|
|
124
|
+
const controller = new AbortController();
|
|
125
|
+
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
126
|
+
try {
|
|
127
|
+
return await fetch(url, { ...init, signal: controller.signal });
|
|
128
|
+
}
|
|
129
|
+
finally {
|
|
130
|
+
clearTimeout(timer);
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
_headers(hasBody = false) {
|
|
134
|
+
const h = {
|
|
135
|
+
Accept: "application/json",
|
|
136
|
+
};
|
|
137
|
+
if (hasBody)
|
|
138
|
+
h["Content-Type"] = "application/json";
|
|
139
|
+
if (this._apiKey)
|
|
140
|
+
h["Authorization"] = `Bearer ${this._apiKey}`;
|
|
141
|
+
return h;
|
|
142
|
+
}
|
|
143
|
+
/** Core request — returns the raw API wrapper `{ids, items, errors}`. */
|
|
144
|
+
async _request(method, path, options) {
|
|
145
|
+
let url = `${this._baseUrl}${path}`;
|
|
146
|
+
if (options?.params) {
|
|
147
|
+
const sp = new URLSearchParams();
|
|
148
|
+
for (const [key, val] of Object.entries(options.params)) {
|
|
149
|
+
if (Array.isArray(val)) {
|
|
150
|
+
for (const v of val)
|
|
151
|
+
sp.append(key, v);
|
|
152
|
+
}
|
|
153
|
+
else {
|
|
154
|
+
sp.append(key, val);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
const qs = sp.toString();
|
|
158
|
+
if (qs)
|
|
159
|
+
url += `?${qs}`;
|
|
160
|
+
}
|
|
161
|
+
const timeoutMs = options?.timeoutMs ?? this._timeoutMs;
|
|
162
|
+
const hasBody = !!(options?.body && method !== "GET");
|
|
163
|
+
const init = { method, headers: this._headers(hasBody) };
|
|
164
|
+
if (hasBody) {
|
|
165
|
+
init.body = JSON.stringify(options.body);
|
|
166
|
+
}
|
|
167
|
+
const res = await this._fetch(url, init, timeoutMs);
|
|
168
|
+
const raw = await res.text();
|
|
169
|
+
let payload;
|
|
170
|
+
try {
|
|
171
|
+
payload = raw ? JSON.parse(raw) : {};
|
|
172
|
+
}
|
|
173
|
+
catch {
|
|
174
|
+
throw new types_js_1.XmemoryAPIError(`Invalid JSON from server (${res.status}): ${raw.slice(0, 200)}`, res.status);
|
|
175
|
+
}
|
|
176
|
+
if (!res.ok) {
|
|
177
|
+
const structured = extractStructuredError(payload);
|
|
178
|
+
const msg = structured.message ??
|
|
179
|
+
(typeof payload === "object" && payload !== null && "message" in payload
|
|
180
|
+
? String(payload.message)
|
|
181
|
+
: raw.slice(0, 200));
|
|
182
|
+
throw new types_js_1.XmemoryAPIError(`HTTP ${res.status}: ${msg}`, res.status, structured.code, structured.details, parseRetryAfter(res));
|
|
183
|
+
}
|
|
184
|
+
const response = payload;
|
|
185
|
+
if (response.errors?.length) {
|
|
186
|
+
const first = response.errors[0];
|
|
187
|
+
throw new types_js_1.XmemoryAPIError(`API error: ${first.message} (${first.code})`, res.status, first.code);
|
|
188
|
+
}
|
|
189
|
+
return response;
|
|
190
|
+
}
|
|
191
|
+
async _requestOne(method, path, options) {
|
|
192
|
+
const response = await this._request(method, path, options);
|
|
193
|
+
const items = response.items ?? [];
|
|
194
|
+
if (items.length === 0) {
|
|
195
|
+
throw new types_js_1.XmemoryAPIError(`Expected one item from ${method} ${path}, got none`);
|
|
196
|
+
}
|
|
197
|
+
if (items.length > 1) {
|
|
198
|
+
throw new types_js_1.XmemoryAPIError(`Expected one item from ${method} ${path}, got ${items.length}`);
|
|
199
|
+
}
|
|
200
|
+
return items[0];
|
|
201
|
+
}
|
|
202
|
+
async _requestList(method, path, options) {
|
|
203
|
+
const response = await this._request(method, path, options);
|
|
204
|
+
return (response.items ?? []);
|
|
205
|
+
}
|
|
206
|
+
async _requestIds(method, path, options) {
|
|
207
|
+
const response = await this._request(method, path, options);
|
|
208
|
+
return response.ids ?? [];
|
|
209
|
+
}
|
|
210
|
+
// -----------------------------------------------------------------------
|
|
211
|
+
// Private: build admin namespace
|
|
212
|
+
// -----------------------------------------------------------------------
|
|
213
|
+
_buildAdmin() {
|
|
214
|
+
return {
|
|
215
|
+
listClusters: async (options) => {
|
|
216
|
+
const params = options?.ids ? { ids: options.ids } : undefined;
|
|
217
|
+
return this._requestList("GET", "/clusters", { params, timeoutMs: options?.timeoutMs });
|
|
218
|
+
},
|
|
219
|
+
getCluster: async (clusterId, options) => {
|
|
220
|
+
return this._requestOne("GET", `/clusters/${clusterId}`, {
|
|
221
|
+
timeoutMs: options?.timeoutMs,
|
|
222
|
+
});
|
|
223
|
+
},
|
|
224
|
+
createInstance: async (clusterId, name, schemaText, schemaType, options) => {
|
|
225
|
+
const body = {
|
|
226
|
+
name,
|
|
227
|
+
instance_schema: (0, types_js_1.buildInstanceSchema)(schemaText, schemaType),
|
|
228
|
+
};
|
|
229
|
+
if (options?.description != null)
|
|
230
|
+
body.description = options.description;
|
|
231
|
+
if (options?.schemaDescription != null)
|
|
232
|
+
body.schema_description = options.schemaDescription;
|
|
233
|
+
const info = await this._requestOne("POST", `/clusters/${clusterId}/instances`, {
|
|
234
|
+
body,
|
|
235
|
+
timeoutMs: options?.timeoutMs,
|
|
236
|
+
});
|
|
237
|
+
return this.instance(info.id);
|
|
238
|
+
},
|
|
239
|
+
listInstances: async (options) => {
|
|
240
|
+
const params = options?.ids ? { ids: options.ids } : undefined;
|
|
241
|
+
return this._requestList("GET", "/instances", { params, timeoutMs: options?.timeoutMs });
|
|
242
|
+
},
|
|
243
|
+
getInstance: async (instanceId, options) => {
|
|
244
|
+
return this._requestOne("GET", `/instances/${instanceId}`, {
|
|
245
|
+
timeoutMs: options?.timeoutMs,
|
|
246
|
+
});
|
|
247
|
+
},
|
|
248
|
+
getSetupInstructions: async (instanceId, options) => {
|
|
249
|
+
return this._requestOne("GET", `/instances/${instanceId}/agent_setup`, {
|
|
250
|
+
params: { format: options?.format ?? types_js_1.SetupFormat.AGENT },
|
|
251
|
+
timeoutMs: options?.timeoutMs,
|
|
252
|
+
});
|
|
253
|
+
},
|
|
254
|
+
deleteInstance: async (instanceId, options) => {
|
|
255
|
+
return this._requestIds("DELETE", `/instances/${instanceId}`, {
|
|
256
|
+
timeoutMs: options?.timeoutMs,
|
|
257
|
+
});
|
|
258
|
+
},
|
|
259
|
+
getInstanceSchema: async (instanceId, options) => {
|
|
260
|
+
return this._requestOne("GET", `/instances/${instanceId}/schema`, {
|
|
261
|
+
timeoutMs: options?.timeoutMs,
|
|
262
|
+
});
|
|
263
|
+
},
|
|
264
|
+
updateInstanceSchema: async (instanceId, schemaText, schemaType, options) => {
|
|
265
|
+
const body = {
|
|
266
|
+
instance_schema: (0, types_js_1.buildInstanceSchema)(schemaText, schemaType),
|
|
267
|
+
};
|
|
268
|
+
if (options?.migrationPlan != null)
|
|
269
|
+
body.migration_plan = options.migrationPlan;
|
|
270
|
+
if (options?.confirmDestructive != null)
|
|
271
|
+
body.confirm_destructive = options.confirmDestructive;
|
|
272
|
+
return this._requestOne("PUT", `/instances/${instanceId}/schema`, {
|
|
273
|
+
body,
|
|
274
|
+
timeoutMs: options?.timeoutMs,
|
|
275
|
+
});
|
|
276
|
+
},
|
|
277
|
+
updateInstanceMetadata: async (instanceId, name, description, options) => {
|
|
278
|
+
// Only the fields the caller named are sent. The endpoint treats a field
|
|
279
|
+
// present in the body as a field to set, so serializing
|
|
280
|
+
// `agent_owner_instructions` unasked would wipe an owner's standing rule
|
|
281
|
+
// as a side effect of a rename.
|
|
282
|
+
const body = { name, description };
|
|
283
|
+
if (options?.agentOwnerInstructions !== undefined) {
|
|
284
|
+
body.agent_owner_instructions = options.agentOwnerInstructions;
|
|
285
|
+
}
|
|
286
|
+
if (options?.expectedOwnerInstructionsEpoch !== undefined) {
|
|
287
|
+
body.expected_owner_instructions_epoch = options.expectedOwnerInstructionsEpoch;
|
|
288
|
+
}
|
|
289
|
+
return this._requestOne("PUT", `/instances/${instanceId}`, {
|
|
290
|
+
body,
|
|
291
|
+
timeoutMs: options?.timeoutMs,
|
|
292
|
+
});
|
|
293
|
+
},
|
|
294
|
+
patchInstanceMetadata: async (instanceId, options) => {
|
|
295
|
+
// Same rule as above, applied to every field: absent means "leave it as
|
|
296
|
+
// it is", an explicit null means "clear it".
|
|
297
|
+
const body = {};
|
|
298
|
+
if (options?.name !== undefined)
|
|
299
|
+
body.name = options.name;
|
|
300
|
+
if (options?.description !== undefined)
|
|
301
|
+
body.description = options.description;
|
|
302
|
+
if (options?.agentSurfaces !== undefined) {
|
|
303
|
+
// Copied so a caller mutating their array afterwards cannot change what
|
|
304
|
+
// a retry sends.
|
|
305
|
+
body.agent_surfaces = options.agentSurfaces && [...options.agentSurfaces];
|
|
306
|
+
}
|
|
307
|
+
if (options?.agentDefaultBindingTier !== undefined) {
|
|
308
|
+
body.agent_default_binding_tier = options.agentDefaultBindingTier;
|
|
309
|
+
}
|
|
310
|
+
if (options?.agentEngagementHints !== undefined) {
|
|
311
|
+
body.agent_engagement_hints = options.agentEngagementHints && [...options.agentEngagementHints];
|
|
312
|
+
}
|
|
313
|
+
if (options?.agentOwnerInstructions !== undefined) {
|
|
314
|
+
body.agent_owner_instructions = options.agentOwnerInstructions;
|
|
315
|
+
}
|
|
316
|
+
return this._requestOne("PATCH", `/instances/${instanceId}`, {
|
|
317
|
+
body,
|
|
318
|
+
timeoutMs: options?.timeoutMs,
|
|
319
|
+
});
|
|
320
|
+
},
|
|
321
|
+
generateSchema: async (clusterId, schemaDescription, options) => {
|
|
322
|
+
const body = { schema_description: schemaDescription };
|
|
323
|
+
if (options?.currentYmlSchema != null)
|
|
324
|
+
body.current_yml_schema = options.currentYmlSchema;
|
|
325
|
+
return this._requestOne("POST", `/clusters/${clusterId}/instances/generate_schema`, { body, timeoutMs: options?.timeoutMs });
|
|
326
|
+
},
|
|
327
|
+
enhanceSchema: async (clusterId, schemaDescription, currentYmlSchema, options) => {
|
|
328
|
+
return this._requestOne("POST", `/clusters/${clusterId}/instances/generate_schema`, {
|
|
329
|
+
body: { schema_description: schemaDescription, current_yml_schema: currentYmlSchema },
|
|
330
|
+
timeoutMs: options?.timeoutMs,
|
|
331
|
+
});
|
|
332
|
+
},
|
|
333
|
+
dryRunMigration: async (instanceId, schemaText, schemaType, options) => {
|
|
334
|
+
const body = {
|
|
335
|
+
instance_schema: (0, types_js_1.buildInstanceSchema)(schemaText, schemaType),
|
|
336
|
+
};
|
|
337
|
+
if (options?.migrationPlan != null)
|
|
338
|
+
body.migration_plan = options.migrationPlan;
|
|
339
|
+
if (options?.confirmDestructive != null)
|
|
340
|
+
body.confirm_destructive = options.confirmDestructive;
|
|
341
|
+
return this._requestOne("POST", `/instances/${instanceId}/migrations/dry_run`, {
|
|
342
|
+
body,
|
|
343
|
+
timeoutMs: options?.timeoutMs,
|
|
344
|
+
});
|
|
345
|
+
},
|
|
346
|
+
listMigrations: async (instanceId, options) => {
|
|
347
|
+
const params = {
|
|
348
|
+
limit: String(options?.limit ?? 50),
|
|
349
|
+
include_yaml: String(options?.includeYaml ?? false),
|
|
350
|
+
};
|
|
351
|
+
if (options?.beforeId != null)
|
|
352
|
+
params.before_id = options.beforeId;
|
|
353
|
+
return this._requestOne("GET", `/instances/${instanceId}/migrations`, {
|
|
354
|
+
params,
|
|
355
|
+
timeoutMs: options?.timeoutMs,
|
|
356
|
+
});
|
|
357
|
+
},
|
|
358
|
+
getMigration: async (instanceId, migrationId, options) => {
|
|
359
|
+
const result = await this._requestOne("GET", `/instances/${instanceId}/migrations/${migrationId}`, { params: { include_yaml: String(options?.includeYaml ?? false) }, timeoutMs: options?.timeoutMs });
|
|
360
|
+
return result.record;
|
|
361
|
+
},
|
|
362
|
+
};
|
|
363
|
+
}
|
|
364
|
+
}
|
|
365
|
+
exports.XmemoryClient = XmemoryClient;
|
|
366
|
+
/** Convenience factory — creates a client with a health check. */
|
|
367
|
+
async function xmemoryInstance(options = {}) {
|
|
368
|
+
return XmemoryClient.create(options);
|
|
369
|
+
}
|
|
@@ -8,7 +8,7 @@ export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
|
|
|
8
8
|
export { SchemaType } from "./types.js";
|
|
9
9
|
export { AgentSurface, BindingTier, FragmentMerge, SetupFormat, StepKind } from "./types.js";
|
|
10
10
|
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
11
|
-
export type { ScopeObject, ReadScope, RelationsScope } from "./types.js";
|
|
11
|
+
export type { ScopeObject, ReadScope, WriteScope, RelationsScope } from "./types.js";
|
|
12
12
|
export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceMetadataOptions, PatchInstanceMetadataOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
|
|
13
13
|
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
14
14
|
export type { WriteMutation, ObjectMutationBody, ObjectCreatePayload, ObjectUpdatePayload, ObjectDeletePayload, RelationMutationBody, RelationCreatePayload, RelationUpdatePayload, RelationDeletePayload, RelationEndpoint, } from "./types.js";
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* xmemory — TypeScript client for the xmemory API.
|
|
4
|
+
*/
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.StepKind = exports.SetupFormat = exports.FragmentMerge = exports.BindingTier = exports.AgentSurface = exports.SchemaType = exports.XmemoryHealthCheckError = exports.XmemoryAPIError = exports.InstanceHandle = exports.DescribeResult = exports.xmemoryInstance = exports.XmemoryClient = void 0;
|
|
7
|
+
// Client
|
|
8
|
+
var client_js_1 = require("./client.js");
|
|
9
|
+
Object.defineProperty(exports, "XmemoryClient", { enumerable: true, get: function () { return client_js_1.XmemoryClient; } });
|
|
10
|
+
Object.defineProperty(exports, "xmemoryInstance", { enumerable: true, get: function () { return client_js_1.xmemoryInstance; } });
|
|
11
|
+
// Instance handle
|
|
12
|
+
var instance_js_1 = require("./instance.js");
|
|
13
|
+
Object.defineProperty(exports, "DescribeResult", { enumerable: true, get: function () { return instance_js_1.DescribeResult; } });
|
|
14
|
+
Object.defineProperty(exports, "InstanceHandle", { enumerable: true, get: function () { return instance_js_1.InstanceHandle; } });
|
|
15
|
+
// Error classes
|
|
16
|
+
var types_js_1 = require("./types.js");
|
|
17
|
+
Object.defineProperty(exports, "XmemoryAPIError", { enumerable: true, get: function () { return types_js_1.XmemoryAPIError; } });
|
|
18
|
+
Object.defineProperty(exports, "XmemoryHealthCheckError", { enumerable: true, get: function () { return types_js_1.XmemoryHealthCheckError; } });
|
|
19
|
+
// Enums
|
|
20
|
+
var types_js_2 = require("./types.js");
|
|
21
|
+
Object.defineProperty(exports, "SchemaType", { enumerable: true, get: function () { return types_js_2.SchemaType; } });
|
|
22
|
+
var types_js_3 = require("./types.js");
|
|
23
|
+
Object.defineProperty(exports, "AgentSurface", { enumerable: true, get: function () { return types_js_3.AgentSurface; } });
|
|
24
|
+
Object.defineProperty(exports, "BindingTier", { enumerable: true, get: function () { return types_js_3.BindingTier; } });
|
|
25
|
+
Object.defineProperty(exports, "FragmentMerge", { enumerable: true, get: function () { return types_js_3.FragmentMerge; } });
|
|
26
|
+
Object.defineProperty(exports, "SetupFormat", { enumerable: true, get: function () { return types_js_3.SetupFormat; } });
|
|
27
|
+
Object.defineProperty(exports, "StepKind", { enumerable: true, get: function () { return types_js_3.StepKind; } });
|
|
@@ -69,12 +69,24 @@ export declare class InstanceHandle {
|
|
|
69
69
|
* objects created earlier in the batch, and a `null` value in a mutation's
|
|
70
70
|
* `values` clears that field). `extractionLogic` / `diffEngine` only apply
|
|
71
71
|
* to the text form.
|
|
72
|
+
*
|
|
73
|
+
* Pass `scope` — a `WriteScope` of concrete existing objects, each named by
|
|
74
|
+
* its user-defined primary key — to anchor a text write to them. Their current
|
|
75
|
+
* values are shown to the extractor so the write updates them instead of
|
|
76
|
+
* creating duplicates, and the write is then confined to the scope: it may
|
|
77
|
+
* only modify or delete the scoped objects and create new objects and
|
|
78
|
+
* relations anchored to them. A write that would touch any other existing
|
|
79
|
+
* object fails. The server accepts a scope with fast extraction only, and a
|
|
80
|
+
* scoped write additionally requires read permission on the instance, because
|
|
81
|
+
* the scoped objects' values are shown to the extractor.
|
|
72
82
|
*/
|
|
73
83
|
write(text: string, options?: WriteOptions): Promise<WriteResult>;
|
|
74
84
|
write(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<WriteResult>;
|
|
75
85
|
/**
|
|
76
86
|
* Submit a write job and return immediately with a `write_id` for polling.
|
|
77
|
-
* Accepts the same text / `WriteMutation[]` dual input as {@link write}
|
|
87
|
+
* Accepts the same text / `WriteMutation[]` dual input as {@link write}, and
|
|
88
|
+
* the same `scope`. A scope violation is reported by {@link writeStatus} as a
|
|
89
|
+
* failed write.
|
|
78
90
|
*/
|
|
79
91
|
writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
|
|
80
92
|
writeAsync(mutations: readonly WriteMutation[], options?: RequestOptions): Promise<AsyncWriteResult>;
|