xmemory 3.8.2 → 3.10.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 +80 -1
- package/dist/cjs/client.d.ts +45 -0
- package/dist/cjs/client.js +86 -18
- package/dist/cjs/index.d.ts +2 -2
- package/dist/cjs/instance.js +10 -2
- package/dist/cjs/types.d.ts +127 -2
- package/dist/cjs/version.d.ts +2 -0
- package/dist/cjs/version.js +5 -0
- package/dist/esm/client.d.ts +45 -0
- package/dist/esm/client.js +83 -17
- package/dist/esm/index.d.ts +2 -2
- package/dist/esm/instance.js +10 -2
- package/dist/esm/types.d.ts +127 -2
- package/dist/esm/version.d.ts +2 -0
- package/dist/esm/version.js +2 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -249,7 +249,30 @@ const result = await inst.read("Who is on the team?");
|
|
|
249
249
|
console.log(result.reader_result);
|
|
250
250
|
```
|
|
251
251
|
|
|
252
|
-
Options: `{ readMode?, scope?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
|
|
252
|
+
Options: `{ readMode?, scope?, includeRelatedTypes?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
|
|
253
|
+
|
|
254
|
+
#### What comes back
|
|
255
|
+
|
|
256
|
+
In `"single-answer"` mode `reader_result` is always the prose answer. In
|
|
257
|
+
`"raw-tables"` and `"xresponse"` mode its value says which of four answers the
|
|
258
|
+
read gave:
|
|
259
|
+
|
|
260
|
+
| `reader_result` | Meaning | What to do |
|
|
261
|
+
| --- | --- | --- |
|
|
262
|
+
| rows | Answered. | Use them. |
|
|
263
|
+
| exactly `{ columns: [], rows: [] }` / `{ objects: [], relations: [] }` | The query executed and matched nothing — every table and column it used exists, so the data is absent. | Trust the empty result. |
|
|
264
|
+
| `null` | The schema provably cannot represent the concept. An answer, not a variant of the empty one. | Try a better-matching instance; this memory cannot hold it. |
|
|
265
|
+
| *(throws)* | Every sub-query's SQL failed, so nothing was answered. | Catch `XmemoryAPIError` with `status` 422 and `code` `"INVALID_INPUT"`. It is the same answer for the same input, so do not retry it. |
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
const result = await inst.read("Which invoices are overdue?", { readMode: "raw-tables" });
|
|
269
|
+
if (result.reader_result === null) {
|
|
270
|
+
// Not a concept this memory holds — try another instance.
|
|
271
|
+
} else {
|
|
272
|
+
const { rows } = result.reader_result as { columns: string[]; rows: unknown[][] };
|
|
273
|
+
// rows.length === 0 means the data is absent, not that the read failed.
|
|
274
|
+
}
|
|
275
|
+
```
|
|
253
276
|
|
|
254
277
|
#### Composite queries
|
|
255
278
|
|
|
@@ -269,6 +292,15 @@ for (const part of result.reader_results) {
|
|
|
269
292
|
}
|
|
270
293
|
```
|
|
271
294
|
|
|
295
|
+
Each part's `reader_result` uses the same four answers as above, with one more
|
|
296
|
+
case: a sub-query whose SQL failed carries the empty result *and* a user-safe
|
|
297
|
+
`error`, while the others are answered regardless. Its bytes then equal those
|
|
298
|
+
of a sub-query that matched nothing, so read `error` before `reader_result`, as
|
|
299
|
+
the loop above does. The combined `reader_result` folds the parts: rows if any
|
|
300
|
+
sub-query answered; else the empty result if any executed and matched nothing;
|
|
301
|
+
else `null`. In the tabular modes a read where *every* sub-query failed throws
|
|
302
|
+
the 422 above instead.
|
|
303
|
+
|
|
272
304
|
#### Scoped reads
|
|
273
305
|
|
|
274
306
|
By default a read may draw on the whole instance. Pass a `scope` to restrict it
|
|
@@ -297,6 +329,39 @@ const result = await inst.read("What do we know about these people?", {
|
|
|
297
329
|
restricts the read to the listed objects only, while `"all_relations"` also
|
|
298
330
|
exposes the relations among the in-scope objects.
|
|
299
331
|
|
|
332
|
+
#### Related types
|
|
333
|
+
|
|
334
|
+
A read can also say what else the memory could answer about. Pass
|
|
335
|
+
`includeRelatedTypes: "types"` and `related_types` on the result names the
|
|
336
|
+
object types the read touched, each with the fields it did not return and the
|
|
337
|
+
object types a declared relation links it to (the relation, both roles, and its
|
|
338
|
+
cardinality seen from the touched type), plus a catalog that describes every
|
|
339
|
+
named type (description, primary key, field names) and relation once. It is
|
|
340
|
+
derived from the instance schema and the statements the read executed — no
|
|
341
|
+
extra rows, no model call — so an agent can ask a deliberate follow-up instead
|
|
342
|
+
of guessing what the store holds.
|
|
343
|
+
|
|
344
|
+
```typescript
|
|
345
|
+
const result = await inst.read("Which courses require an English test?", {
|
|
346
|
+
includeRelatedTypes: "types",
|
|
347
|
+
});
|
|
348
|
+
for (const touched of result.related_types?.touched ?? []) {
|
|
349
|
+
console.log(touched.object_type, "did not return", touched.fields_not_returned);
|
|
350
|
+
for (const link of touched.related) {
|
|
351
|
+
const neighbour = result.related_types!.types[link.object_type];
|
|
352
|
+
console.log(" linked to", link.object_type, "via", link.relation, neighbour.fields);
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
`related_types` is `null` unless the read asked for it. A requested read that
|
|
358
|
+
executed nothing arrives with `touched: []`. The server caps the payload;
|
|
359
|
+
`truncated` says when it did, and `omitted_touched` and each entry's
|
|
360
|
+
`omitted_related` count what was dropped. Asking for it needs the
|
|
361
|
+
`instance.get_own` permission on the API key, the same one the schema
|
|
362
|
+
endpoints need, on top of `data.read`: a key without it gets a 403 whose
|
|
363
|
+
message names the permission, and the plain read is unaffected.
|
|
364
|
+
|
|
300
365
|
#### Scoped writes
|
|
301
366
|
|
|
302
367
|
A write is normally free to touch anything in the instance: the extractor sees
|
|
@@ -527,6 +592,18 @@ Advisory values — `step.kind`, `fragment.merge`, `format` — are widened to a
|
|
|
527
592
|
added to the server after this release, so an additive change does not become a breaking
|
|
528
593
|
one. A `step.kind` you do not recognise is not something to execute.
|
|
529
594
|
|
|
595
|
+
## Request identification
|
|
596
|
+
|
|
597
|
+
Every request this client issues carries an `X-Xmemory-Client` header naming the package and its
|
|
598
|
+
release, followed by the host — for example `xmemory-node/3.9.0 (node v24.5.0; darwin)`. The
|
|
599
|
+
parenthetical reports `process.version` and `process.platform`, says `unknown` for either one a host
|
|
600
|
+
does not supply, and never carries a hostname. The API uses it to tell its own clients apart.
|
|
601
|
+
|
|
602
|
+
The identity travels in a dedicated header rather than in `User-Agent`, which belongs to the runtime:
|
|
603
|
+
your `User-Agent` is neither read nor written, and every other header on the request is left alone. A
|
|
604
|
+
proxy that strips unknown `X-` headers costs the attribution but not the request — the call still goes
|
|
605
|
+
through, counted as a generic caller.
|
|
606
|
+
|
|
530
607
|
## Error handling
|
|
531
608
|
|
|
532
609
|
All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCheckError` (a subclass).
|
|
@@ -562,6 +639,8 @@ different things:
|
|
|
562
639
|
| ---- | ----------------- | ---------------------------------------------------- | ---------------------------------- |
|
|
563
640
|
| 402 | `QUOTA_EXCEEDED` | Tenant exhausted its plan/usage allowance (a daily or monthly token quota). | **No.** Wait for the window to reset. |
|
|
564
641
|
| 429 | `RATE_LIMITED` | Genuine velocity / rate limit. | **Yes**, with backoff. |
|
|
642
|
+
| 422 | `INVALID_INPUT` | A read that answered nothing: in `"raw-tables"` / `"xresponse"` mode every sub-query's SQL failed, or the model provider declined the input. See [What comes back](#what-comes-back). | **No.** Same input, same answer. |
|
|
643
|
+
| 403 | `FORBIDDEN` | The API key lacks a permission the call needs — for a read with `includeRelatedTypes: "types"`, `instance.get_own`; the message names it. See [Related types](#related-types). | **No.** Repeat without the option, or use a key that holds it. |
|
|
565
644
|
|
|
566
645
|
For `QUOTA_EXCEEDED`, `details` carries `kind`
|
|
567
646
|
(`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
package/dist/cjs/client.d.ts
CHANGED
|
@@ -3,6 +3,41 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import { InstanceHandle } from "./instance.js";
|
|
5
5
|
import { type AgentSetupResult, type ClusterInfo, type CreateInstanceOptions, type DryRunMigrationOptions, type DryRunResult, type EnhanceSchemaResult, type GenerateSchemaOptions, type GenerateSchemaResult, type GetMigrationOptions, type InstanceInfo, type InstanceSchemaInfo, type ListMigrationsOptions, type ListMigrationsResult, type MigrationRecord, type PatchInstanceMetadataOptions, type RequestOptions, type SchemaTypeValue, type SetupFormatValue, type UpdateInstanceMetadataOptions, type UpdateInstanceSchemaOptions, type XmemoryClientOptions } from "./types.js";
|
|
6
|
+
/**
|
|
7
|
+
* The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
|
|
8
|
+
* non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
|
|
9
|
+
* `unknown` otherwise.
|
|
10
|
+
* The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
|
|
11
|
+
* missing fields would write the word "undefined" into the header. A control character such as NUL
|
|
12
|
+
* or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
|
|
13
|
+
* converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
|
|
14
|
+
* a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
|
|
15
|
+
* The length cap is there because nothing else bounds what a host may report into a header this
|
|
16
|
+
* sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
|
|
17
|
+
* those substitutions directly.
|
|
18
|
+
*/
|
|
19
|
+
export declare function buildClientIdentity(version: string, host: {
|
|
20
|
+
version?: unknown;
|
|
21
|
+
platform?: unknown;
|
|
22
|
+
} | undefined): string;
|
|
23
|
+
/**
|
|
24
|
+
* The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
|
|
25
|
+
* belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
|
|
26
|
+
* treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
|
|
27
|
+
*/
|
|
28
|
+
export declare const CLIENT_HEADER = "X-Xmemory-Client";
|
|
29
|
+
/**
|
|
30
|
+
* The headers a request goes out with: everything the caller built, in a new object so the
|
|
31
|
+
* caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
|
|
32
|
+
* header is dropped first — header names are case-insensitive on the wire, so leaving one behind
|
|
33
|
+
* would put two values under one name, and `fetch` joins those into a single comma-separated value
|
|
34
|
+
* whose first token is the one the API reads. `User-Agent` and everything else pass through
|
|
35
|
+
* untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
|
|
36
|
+
* sees what `_headers()` built — so the drop is defensive against a future call site that does, not
|
|
37
|
+
* a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
|
|
38
|
+
* directly.
|
|
39
|
+
*/
|
|
40
|
+
export declare function withClientHeader(existing: Record<string, string> | undefined): Record<string, string>;
|
|
6
41
|
export interface AdminNamespace {
|
|
7
42
|
listClusters(options?: RequestOptions & {
|
|
8
43
|
ids?: string[];
|
|
@@ -62,6 +97,16 @@ export declare class XmemoryClient {
|
|
|
62
97
|
checkHealth(): Promise<void>;
|
|
63
98
|
private _fetch;
|
|
64
99
|
private _headers;
|
|
100
|
+
/**
|
|
101
|
+
* The request URL for `path`, honouring whatever the configured base carries.
|
|
102
|
+
*
|
|
103
|
+
* Composed through `URL` rather than concatenated. Concatenation put the API path
|
|
104
|
+
* inside the query of a base that had one (`https://host?tenant=x` requested `/`),
|
|
105
|
+
* and appended a second `?` for request parameters. A plain `new URL(path, base)`
|
|
106
|
+
* is not the fix either: it drops a base path prefix, so a gateway base like
|
|
107
|
+
* `https://gw.example/xmemory` would lose `/xmemory`.
|
|
108
|
+
*/
|
|
109
|
+
private _requestUrl;
|
|
65
110
|
/** Core request — returns the raw API wrapper `{ids, items, errors}`. */
|
|
66
111
|
private _request;
|
|
67
112
|
private _requestOne;
|
package/dist/cjs/client.js
CHANGED
|
@@ -3,10 +3,13 @@
|
|
|
3
3
|
* XmemoryClient — main entry point for the xmemory API.
|
|
4
4
|
*/
|
|
5
5
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
-
exports.XmemoryClient = void 0;
|
|
6
|
+
exports.XmemoryClient = exports.CLIENT_HEADER = void 0;
|
|
7
|
+
exports.buildClientIdentity = buildClientIdentity;
|
|
8
|
+
exports.withClientHeader = withClientHeader;
|
|
7
9
|
exports.xmemoryInstance = xmemoryInstance;
|
|
8
10
|
const instance_js_1 = require("./instance.js");
|
|
9
11
|
const types_js_1 = require("./types.js");
|
|
12
|
+
const version_js_1 = require("./version.js");
|
|
10
13
|
const DEFAULT_BASE_URL = "https://api.xmemory.ai";
|
|
11
14
|
/**
|
|
12
15
|
* An *own* property of a decoded response, or `undefined`.
|
|
@@ -27,6 +30,59 @@ function ownArray(source, key) {
|
|
|
27
30
|
return Array.isArray(value) ? value : [];
|
|
28
31
|
}
|
|
29
32
|
const DEFAULT_TIMEOUT_MS = 60_000;
|
|
33
|
+
const HOST_FIELD_MAX = 64;
|
|
34
|
+
/** One host detail, reduced to something a header value may safely carry. */
|
|
35
|
+
const hostField = (value) => typeof value === "string" &&
|
|
36
|
+
value.length <= HOST_FIELD_MAX &&
|
|
37
|
+
/^[\x21-\x7e]+$/.test(value) &&
|
|
38
|
+
!/[;()]/.test(value)
|
|
39
|
+
? value
|
|
40
|
+
: "unknown";
|
|
41
|
+
/**
|
|
42
|
+
* The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
|
|
43
|
+
* non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
|
|
44
|
+
* `unknown` otherwise.
|
|
45
|
+
* The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
|
|
46
|
+
* missing fields would write the word "undefined" into the header. A control character such as NUL
|
|
47
|
+
* or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
|
|
48
|
+
* converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
|
|
49
|
+
* a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
|
|
50
|
+
* The length cap is there because nothing else bounds what a host may report into a header this
|
|
51
|
+
* sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
|
|
52
|
+
* those substitutions directly.
|
|
53
|
+
*/
|
|
54
|
+
function buildClientIdentity(version, host) {
|
|
55
|
+
return `xmemory-node/${version} (node ${hostField(host?.version)}; ${hostField(host?.platform)})`;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
|
|
59
|
+
* belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
|
|
60
|
+
* treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
|
|
61
|
+
*/
|
|
62
|
+
exports.CLIENT_HEADER = "X-Xmemory-Client";
|
|
63
|
+
// `process` is absent in a browser and partial under some bundler shims, so the fields are read
|
|
64
|
+
// defensively and each one falls back to `unknown`.
|
|
65
|
+
const CLIENT_IDENTITY = buildClientIdentity(version_js_1.VERSION, typeof process !== "undefined" ? process : undefined);
|
|
66
|
+
/**
|
|
67
|
+
* The headers a request goes out with: everything the caller built, in a new object so the
|
|
68
|
+
* caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
|
|
69
|
+
* header is dropped first — header names are case-insensitive on the wire, so leaving one behind
|
|
70
|
+
* would put two values under one name, and `fetch` joins those into a single comma-separated value
|
|
71
|
+
* whose first token is the one the API reads. `User-Agent` and everything else pass through
|
|
72
|
+
* untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
|
|
73
|
+
* sees what `_headers()` built — so the drop is defensive against a future call site that does, not
|
|
74
|
+
* a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
|
|
75
|
+
* directly.
|
|
76
|
+
*/
|
|
77
|
+
function withClientHeader(existing) {
|
|
78
|
+
const headers = {};
|
|
79
|
+
for (const [name, value] of Object.entries(existing ?? {})) {
|
|
80
|
+
if (name.toLowerCase() !== exports.CLIENT_HEADER.toLowerCase())
|
|
81
|
+
headers[name] = value;
|
|
82
|
+
}
|
|
83
|
+
headers[exports.CLIENT_HEADER] = CLIENT_IDENTITY;
|
|
84
|
+
return headers;
|
|
85
|
+
}
|
|
30
86
|
const ORANGE = "\x1b[38;5;208m";
|
|
31
87
|
const RESET = "\x1b[0m";
|
|
32
88
|
function deprecationWarning(message) {
|
|
@@ -142,7 +198,11 @@ class XmemoryClient {
|
|
|
142
198
|
const controller = new AbortController();
|
|
143
199
|
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
144
200
|
try {
|
|
145
|
-
return await fetch(url, {
|
|
201
|
+
return await fetch(url, {
|
|
202
|
+
...init,
|
|
203
|
+
headers: withClientHeader(init.headers),
|
|
204
|
+
signal: controller.signal,
|
|
205
|
+
});
|
|
146
206
|
}
|
|
147
207
|
finally {
|
|
148
208
|
clearTimeout(timer);
|
|
@@ -158,24 +218,32 @@ class XmemoryClient {
|
|
|
158
218
|
h["Authorization"] = `Bearer ${this._apiKey}`;
|
|
159
219
|
return h;
|
|
160
220
|
}
|
|
161
|
-
/**
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
221
|
+
/**
|
|
222
|
+
* The request URL for `path`, honouring whatever the configured base carries.
|
|
223
|
+
*
|
|
224
|
+
* Composed through `URL` rather than concatenated. Concatenation put the API path
|
|
225
|
+
* inside the query of a base that had one (`https://host?tenant=x` requested `/`),
|
|
226
|
+
* and appended a second `?` for request parameters. A plain `new URL(path, base)`
|
|
227
|
+
* is not the fix either: it drops a base path prefix, so a gateway base like
|
|
228
|
+
* `https://gw.example/xmemory` would lose `/xmemory`.
|
|
229
|
+
*/
|
|
230
|
+
_requestUrl(path, params) {
|
|
231
|
+
const url = new URL(this._baseUrl);
|
|
232
|
+
url.pathname = `${url.pathname.replace(/\/+$/, "")}${path}`;
|
|
233
|
+
for (const [key, val] of Object.entries(params ?? {})) {
|
|
234
|
+
if (Array.isArray(val)) {
|
|
235
|
+
for (const v of val)
|
|
236
|
+
url.searchParams.append(key, v);
|
|
237
|
+
}
|
|
238
|
+
else {
|
|
239
|
+
url.searchParams.append(key, val);
|
|
174
240
|
}
|
|
175
|
-
const qs = sp.toString();
|
|
176
|
-
if (qs)
|
|
177
|
-
url += `?${qs}`;
|
|
178
241
|
}
|
|
242
|
+
return url.toString();
|
|
243
|
+
}
|
|
244
|
+
/** Core request — returns the raw API wrapper `{ids, items, errors}`. */
|
|
245
|
+
async _request(method, path, options) {
|
|
246
|
+
const url = this._requestUrl(path, options?.params);
|
|
179
247
|
const timeoutMs = options?.timeoutMs ?? this._timeoutMs;
|
|
180
248
|
const hasBody = !!(options?.body && method !== "GET");
|
|
181
249
|
const init = { method, headers: this._headers(hasBody) };
|
package/dist/cjs/index.d.ts
CHANGED
|
@@ -7,10 +7,10 @@ export { DescribeResult, InstanceHandle } from "./instance.js";
|
|
|
7
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
|
-
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
10
|
+
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, RelatedTypesMode, RelationCardinality, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
11
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
|
-
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
13
|
+
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, 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";
|
|
15
15
|
export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
|
|
16
16
|
export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
|
package/dist/cjs/instance.js
CHANGED
|
@@ -234,11 +234,14 @@ class InstanceHandle {
|
|
|
234
234
|
relations_scope: options.scope.relationsScope ?? "no_relations",
|
|
235
235
|
};
|
|
236
236
|
}
|
|
237
|
+
if (options?.includeRelatedTypes != null)
|
|
238
|
+
body.include_related_types = options.includeRelatedTypes;
|
|
237
239
|
if (options?.traceId != null)
|
|
238
240
|
body.trace_id = options.traceId;
|
|
239
241
|
// The wire shape omits `reader_results` on a server without question
|
|
240
|
-
// decomposition,
|
|
241
|
-
//
|
|
242
|
+
// decomposition, and `related_types` unless the read asked for it, so type
|
|
243
|
+
// them as optional here and normalize (always-array, `null`) for the public
|
|
244
|
+
// `ReadResult` below.
|
|
242
245
|
const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
|
|
243
246
|
body,
|
|
244
247
|
timeoutMs: options?.timeoutMs,
|
|
@@ -248,10 +251,15 @@ class InstanceHandle {
|
|
|
248
251
|
// by `Object.prototype` when the caller reads it.
|
|
249
252
|
const readerResults = own(result, "reader_results");
|
|
250
253
|
const traceId = own(result, "trace_id");
|
|
254
|
+
const relatedTypes = own(result, "related_types");
|
|
255
|
+
// `reader_result` is required on the wire and `null` is one of its answers (a
|
|
256
|
+
// refusal, in the tabular modes), so the coalescing only stands in for a field
|
|
257
|
+
// the server omitted; a `null` the server sent arrives as the same `null`.
|
|
251
258
|
return withConsoleUrl({
|
|
252
259
|
...result,
|
|
253
260
|
reader_result: own(result, "reader_result") ?? null,
|
|
254
261
|
reader_results: Array.isArray(readerResults) ? readerResults : [],
|
|
262
|
+
related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
|
|
255
263
|
trace_id: typeof traceId === "string" ? traceId : null,
|
|
256
264
|
});
|
|
257
265
|
}
|
package/dist/cjs/types.d.ts
CHANGED
|
@@ -8,6 +8,23 @@ export declare const SchemaType: {
|
|
|
8
8
|
export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
|
|
9
9
|
export type ExtractionLogic = "fast" | "deep";
|
|
10
10
|
export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
|
|
11
|
+
/**
|
|
12
|
+
* What a read says about the schema around its answer. `"types"` adds
|
|
13
|
+
* {@link ReadResult.related_types} to the result; `"none"` (the server default)
|
|
14
|
+
* leaves it out. Asking for it needs the `instance.get_own` permission on the
|
|
15
|
+
* API key, the same one the schema endpoints need, on top of `data.read`: a key
|
|
16
|
+
* without it gets a 403 whose message names the permission, and the plain read
|
|
17
|
+
* is unaffected.
|
|
18
|
+
*/
|
|
19
|
+
export type RelatedTypesMode = "none" | "types";
|
|
20
|
+
/**
|
|
21
|
+
* Cardinality of a relation seen from the touched type's role, derived from the
|
|
22
|
+
* relation's unique keys: `"one_to_many"` means one touched record links to many
|
|
23
|
+
* neighbours and each neighbour to at most one touched record; `"many_to_one"`
|
|
24
|
+
* is the reverse; `"unconstrained"` means the schema declares no uniqueness rule
|
|
25
|
+
* for the relation.
|
|
26
|
+
*/
|
|
27
|
+
export type RelationCardinality = "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" | "unconstrained";
|
|
11
28
|
/**
|
|
12
29
|
* One concrete object a scoped read or a scoped write may touch. Identify it by
|
|
13
30
|
* `type` (PascalCase class name or snake_case table name) plus its user-defined
|
|
@@ -155,20 +172,112 @@ export interface InstanceSchemaInfo {
|
|
|
155
172
|
* One sub-query and its own answer, in the requested read mode. Appears in
|
|
156
173
|
* {@link ReadResult.reader_results} when the server decomposed a composite query
|
|
157
174
|
* into independent sub-queries.
|
|
175
|
+
*
|
|
176
|
+
* `reader_result` gives one of the four answers described on
|
|
177
|
+
* {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
|
|
178
|
+
* failed carries the empty result *and* `error`, while the other sub-queries
|
|
179
|
+
* are answered regardless. Its bytes then equal those of a sub-query that
|
|
180
|
+
* matched nothing, so read `error` before `reader_result`.
|
|
158
181
|
*/
|
|
159
182
|
export interface TaggedReaderResult {
|
|
160
183
|
readonly sub_query: string;
|
|
161
184
|
readonly reader_result: unknown;
|
|
162
185
|
/**
|
|
163
|
-
* A user-safe message set when this sub-query could not be
|
|
164
|
-
*
|
|
186
|
+
* A user-safe message set when this sub-query's SQL could not be executed;
|
|
187
|
+
* `null` otherwise. In `"raw-tables"` / `"xresponse"` mode a read where every
|
|
188
|
+
* sub-query failed does not return at all: it throws {@link XmemoryAPIError}
|
|
189
|
+
* with `status` 422 and `code` `"INVALID_INPUT"`.
|
|
165
190
|
*/
|
|
166
191
|
readonly error: string | null;
|
|
167
192
|
}
|
|
193
|
+
/** One relation edge from a touched type to a neighbouring type; {@link RelatedTypes.types} describes both ends. */
|
|
194
|
+
export interface RelatedTypesLink {
|
|
195
|
+
/** The neighbouring object type, described once under `types`. */
|
|
196
|
+
readonly object_type: string;
|
|
197
|
+
/** The relation that links the two, described once under `relations`. */
|
|
198
|
+
readonly relation: string;
|
|
199
|
+
/** The relation role the touched type plays in this edge. */
|
|
200
|
+
readonly touched_role: string;
|
|
201
|
+
/** The relation role the neighbouring type plays in this edge. */
|
|
202
|
+
readonly related_role: string;
|
|
203
|
+
readonly cardinality: RelationCardinality;
|
|
204
|
+
}
|
|
205
|
+
/** One object type the read touched, with what it withheld and what it is linked to. */
|
|
206
|
+
export interface RelatedTypesTouched {
|
|
207
|
+
/** Object type name as declared in the schema, described under `types`. */
|
|
208
|
+
readonly object_type: string;
|
|
209
|
+
/**
|
|
210
|
+
* Fields of this type the read did not project. Ask for one by name to see it;
|
|
211
|
+
* an expression the reader could not attribute to a field counts here rather
|
|
212
|
+
* than as returned.
|
|
213
|
+
*/
|
|
214
|
+
readonly fields_not_returned: readonly string[];
|
|
215
|
+
/** Relation edges to neighbouring types, sorted by relation then type. A self-relation lists one edge per role. */
|
|
216
|
+
readonly related: readonly RelatedTypesLink[];
|
|
217
|
+
/** Edges dropped from `related` to stay within the server's payload budget. */
|
|
218
|
+
readonly omitted_related: number;
|
|
219
|
+
}
|
|
220
|
+
/** Catalog entry for an object type named anywhere in {@link RelatedTypes.touched}. */
|
|
221
|
+
export interface RelatedTypesObjectType {
|
|
222
|
+
readonly description: string | null;
|
|
223
|
+
/** Declared primary-key fields, in declared order. */
|
|
224
|
+
readonly primary_key: readonly string[];
|
|
225
|
+
/** Every field of the object type, by name. */
|
|
226
|
+
readonly fields: readonly string[];
|
|
227
|
+
}
|
|
228
|
+
/** Catalog entry for a relation named by any edge. */
|
|
229
|
+
export interface RelatedTypesRelation {
|
|
230
|
+
readonly description: string | null;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* What else the memory could answer about, for a read that asked with
|
|
234
|
+
* `includeRelatedTypes: "types"`: the object types the read touched, each with
|
|
235
|
+
* the fields it did not return and its relation edges, plus a catalog that
|
|
236
|
+
* describes every named type and relation exactly once. It is derived from the
|
|
237
|
+
* instance schema and the statements the read executed — no extra rows are
|
|
238
|
+
* read and no model is called — so an agent can phrase a deliberate follow-up
|
|
239
|
+
* read instead of guessing. The server caps the payload; whatever it dropped is
|
|
240
|
+
* counted on the entry it was dropped from, and `truncated` says that something
|
|
241
|
+
* was.
|
|
242
|
+
*/
|
|
243
|
+
export interface RelatedTypes {
|
|
244
|
+
/** Object types the read touched, sorted by name. Empty when the read executed nothing. */
|
|
245
|
+
readonly touched: readonly RelatedTypesTouched[];
|
|
246
|
+
/** Every object type named in `touched`, touched or neighbouring, once. */
|
|
247
|
+
readonly types: Readonly<Record<string, RelatedTypesObjectType>>;
|
|
248
|
+
/** Every relation named by an edge, once. */
|
|
249
|
+
readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
|
|
250
|
+
/** Touched types dropped to stay within the budget. */
|
|
251
|
+
readonly omitted_touched: number;
|
|
252
|
+
/** `true` when any type or edge was dropped for the budget. */
|
|
253
|
+
readonly truncated: boolean;
|
|
254
|
+
}
|
|
168
255
|
export interface ReadResult {
|
|
169
256
|
readonly trace_id: string | null;
|
|
170
257
|
/** Deep link to this read's trace in the console; `null` if no console is configured. */
|
|
171
258
|
readonly console_url: string | null;
|
|
259
|
+
/**
|
|
260
|
+
* The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
|
|
261
|
+
* prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
|
|
262
|
+
* says which of four answers the read gave:
|
|
263
|
+
*
|
|
264
|
+
* - rows — answered;
|
|
265
|
+
* - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
|
|
266
|
+
* `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
|
|
267
|
+
* matched nothing: every table and column it used exists, so the data is
|
|
268
|
+
* absent;
|
|
269
|
+
* - `null` — the schema provably cannot represent the concept. An answer in
|
|
270
|
+
* its own right, not a variant of the empty one: this memory cannot hold
|
|
271
|
+
* it, so a better-matching instance is worth trying;
|
|
272
|
+
* - no result at all — every sub-query's SQL failed, so nothing was
|
|
273
|
+
* answered. The read throws {@link XmemoryAPIError} with `status` 422 and
|
|
274
|
+
* `code` `"INVALID_INPUT"` rather than reporting an empty result.
|
|
275
|
+
*
|
|
276
|
+
* For a composite query this is the combined answer, folded from the parts:
|
|
277
|
+
* rows if any sub-query answered; else the empty result if any executed and
|
|
278
|
+
* matched nothing; else `null`. `reader_results` carries each part's own
|
|
279
|
+
* answer.
|
|
280
|
+
*/
|
|
172
281
|
readonly reader_result: unknown;
|
|
173
282
|
/**
|
|
174
283
|
* Per-sub-query answers when the server decomposed the query into independent
|
|
@@ -179,6 +288,14 @@ export interface ReadResult {
|
|
|
179
288
|
* so the array is empty regardless of how many questions the query held.
|
|
180
289
|
*/
|
|
181
290
|
readonly reader_results: readonly TaggedReaderResult[];
|
|
291
|
+
/**
|
|
292
|
+
* The schema around the answer, when the read asked for it with
|
|
293
|
+
* `includeRelatedTypes: "types"`; `null` otherwise. The wire omits the field
|
|
294
|
+
* unless it was requested, and a server that predates the option never sends
|
|
295
|
+
* it; the client normalizes both to `null`, so `null` means "not asked for" and
|
|
296
|
+
* a requested read that executed nothing arrives with `touched: []` instead.
|
|
297
|
+
*/
|
|
298
|
+
readonly related_types: RelatedTypes | null;
|
|
182
299
|
}
|
|
183
300
|
export interface WriteResult {
|
|
184
301
|
readonly write_id: string;
|
|
@@ -554,6 +671,14 @@ export interface ReadOptions {
|
|
|
554
671
|
readMode?: ReadMode;
|
|
555
672
|
/** Restrict the read to a set of concrete objects (plus optional relation traversal). */
|
|
556
673
|
scope?: ReadScope;
|
|
674
|
+
/**
|
|
675
|
+
* `"types"` asks for {@link ReadResult.related_types}: the object types the read
|
|
676
|
+
* touched, the fields it did not return, and the object types a declared
|
|
677
|
+
* relation links them to. Left unset, nothing is sent and the server default
|
|
678
|
+
* (`"none"`) applies. Needs `instance.get_own` on the API key; see
|
|
679
|
+
* {@link RelatedTypesMode}.
|
|
680
|
+
*/
|
|
681
|
+
includeRelatedTypes?: RelatedTypesMode;
|
|
557
682
|
traceId?: string;
|
|
558
683
|
timeoutMs?: number;
|
|
559
684
|
}
|
package/dist/esm/client.d.ts
CHANGED
|
@@ -3,6 +3,41 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import { InstanceHandle } from "./instance.js";
|
|
5
5
|
import { type AgentSetupResult, type ClusterInfo, type CreateInstanceOptions, type DryRunMigrationOptions, type DryRunResult, type EnhanceSchemaResult, type GenerateSchemaOptions, type GenerateSchemaResult, type GetMigrationOptions, type InstanceInfo, type InstanceSchemaInfo, type ListMigrationsOptions, type ListMigrationsResult, type MigrationRecord, type PatchInstanceMetadataOptions, type RequestOptions, type SchemaTypeValue, type SetupFormatValue, type UpdateInstanceMetadataOptions, type UpdateInstanceSchemaOptions, type XmemoryClientOptions } from "./types.js";
|
|
6
|
+
/**
|
|
7
|
+
* The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
|
|
8
|
+
* non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
|
|
9
|
+
* `unknown` otherwise.
|
|
10
|
+
* The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
|
|
11
|
+
* missing fields would write the word "undefined" into the header. A control character such as NUL
|
|
12
|
+
* or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
|
|
13
|
+
* converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
|
|
14
|
+
* a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
|
|
15
|
+
* The length cap is there because nothing else bounds what a host may report into a header this
|
|
16
|
+
* sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
|
|
17
|
+
* those substitutions directly.
|
|
18
|
+
*/
|
|
19
|
+
export declare function buildClientIdentity(version: string, host: {
|
|
20
|
+
version?: unknown;
|
|
21
|
+
platform?: unknown;
|
|
22
|
+
} | undefined): string;
|
|
23
|
+
/**
|
|
24
|
+
* The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
|
|
25
|
+
* belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
|
|
26
|
+
* treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
|
|
27
|
+
*/
|
|
28
|
+
export declare const CLIENT_HEADER = "X-Xmemory-Client";
|
|
29
|
+
/**
|
|
30
|
+
* The headers a request goes out with: everything the caller built, in a new object so the
|
|
31
|
+
* caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
|
|
32
|
+
* header is dropped first — header names are case-insensitive on the wire, so leaving one behind
|
|
33
|
+
* would put two values under one name, and `fetch` joins those into a single comma-separated value
|
|
34
|
+
* whose first token is the one the API reads. `User-Agent` and everything else pass through
|
|
35
|
+
* untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
|
|
36
|
+
* sees what `_headers()` built — so the drop is defensive against a future call site that does, not
|
|
37
|
+
* a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
|
|
38
|
+
* directly.
|
|
39
|
+
*/
|
|
40
|
+
export declare function withClientHeader(existing: Record<string, string> | undefined): Record<string, string>;
|
|
6
41
|
export interface AdminNamespace {
|
|
7
42
|
listClusters(options?: RequestOptions & {
|
|
8
43
|
ids?: string[];
|
|
@@ -62,6 +97,16 @@ export declare class XmemoryClient {
|
|
|
62
97
|
checkHealth(): Promise<void>;
|
|
63
98
|
private _fetch;
|
|
64
99
|
private _headers;
|
|
100
|
+
/**
|
|
101
|
+
* The request URL for `path`, honouring whatever the configured base carries.
|
|
102
|
+
*
|
|
103
|
+
* Composed through `URL` rather than concatenated. Concatenation put the API path
|
|
104
|
+
* inside the query of a base that had one (`https://host?tenant=x` requested `/`),
|
|
105
|
+
* and appended a second `?` for request parameters. A plain `new URL(path, base)`
|
|
106
|
+
* is not the fix either: it drops a base path prefix, so a gateway base like
|
|
107
|
+
* `https://gw.example/xmemory` would lose `/xmemory`.
|
|
108
|
+
*/
|
|
109
|
+
private _requestUrl;
|
|
65
110
|
/** Core request — returns the raw API wrapper `{ids, items, errors}`. */
|
|
66
111
|
private _request;
|
|
67
112
|
private _requestOne;
|
package/dist/esm/client.js
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import { InstanceHandle } from "./instance.js";
|
|
5
5
|
import { SetupFormat, XmemoryAPIError, XmemoryHealthCheckError, buildInstanceSchema, } from "./types.js";
|
|
6
|
+
import { VERSION } from "./version.js";
|
|
6
7
|
const DEFAULT_BASE_URL = "https://api.xmemory.ai";
|
|
7
8
|
/**
|
|
8
9
|
* An *own* property of a decoded response, or `undefined`.
|
|
@@ -23,6 +24,59 @@ function ownArray(source, key) {
|
|
|
23
24
|
return Array.isArray(value) ? value : [];
|
|
24
25
|
}
|
|
25
26
|
const DEFAULT_TIMEOUT_MS = 60_000;
|
|
27
|
+
const HOST_FIELD_MAX = 64;
|
|
28
|
+
/** One host detail, reduced to something a header value may safely carry. */
|
|
29
|
+
const hostField = (value) => typeof value === "string" &&
|
|
30
|
+
value.length <= HOST_FIELD_MAX &&
|
|
31
|
+
/^[\x21-\x7e]+$/.test(value) &&
|
|
32
|
+
!/[;()]/.test(value)
|
|
33
|
+
? value
|
|
34
|
+
: "unknown";
|
|
35
|
+
/**
|
|
36
|
+
* The identity this client sends in `X-Xmemory-Client`. A host detail is admitted only as a short,
|
|
37
|
+
* non-empty run of printable ASCII carrying no space, semicolon or parenthesis, and becomes
|
|
38
|
+
* `unknown` otherwise.
|
|
39
|
+
* The reasons differ by character. A bundler shim routinely supplies a partial `process`, whose
|
|
40
|
+
* missing fields would write the word "undefined" into the header. A control character such as NUL
|
|
41
|
+
* or a newline makes `fetch` reject the request outright, and a character above `\xff` cannot be
|
|
42
|
+
* converted to a header value at all. The rest — a byte outside ASCII, a tab, a space, a semicolon,
|
|
43
|
+
* a parenthesis — is carried fine, but would blur the boundaries of the parenthetical this builds.
|
|
44
|
+
* The length cap is there because nothing else bounds what a host may report into a header this
|
|
45
|
+
* sends on every request. Not re-exported from `index.ts` — exported here so the tests can cover
|
|
46
|
+
* those substitutions directly.
|
|
47
|
+
*/
|
|
48
|
+
export function buildClientIdentity(version, host) {
|
|
49
|
+
return `xmemory-node/${version} (node ${hostField(host?.version)}; ${hostField(host?.platform)})`;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* The header this client identifies itself in. A dedicated field rather than `User-Agent`: that one
|
|
53
|
+
* belongs to whoever built the request — the runtime, or the caller — and in a browser `fetch`
|
|
54
|
+
* treats it as forbidden and drops it silently. Nothing else on the wire claims this name.
|
|
55
|
+
*/
|
|
56
|
+
export const CLIENT_HEADER = "X-Xmemory-Client";
|
|
57
|
+
// `process` is absent in a browser and partial under some bundler shims, so the fields are read
|
|
58
|
+
// defensively and each one falls back to `unknown`.
|
|
59
|
+
const CLIENT_IDENTITY = buildClientIdentity(VERSION, typeof process !== "undefined" ? process : undefined);
|
|
60
|
+
/**
|
|
61
|
+
* The headers a request goes out with: everything the caller built, in a new object so the
|
|
62
|
+
* caller's own is left untouched, plus this client's identity. Any existing spelling of the identity
|
|
63
|
+
* header is dropped first — header names are case-insensitive on the wire, so leaving one behind
|
|
64
|
+
* would put two values under one name, and `fetch` joins those into a single comma-separated value
|
|
65
|
+
* whose first token is the one the API reads. `User-Agent` and everything else pass through
|
|
66
|
+
* untouched. No public entry point lets a caller supply request headers today — `_fetch` only ever
|
|
67
|
+
* sees what `_headers()` built — so the drop is defensive against a future call site that does, not
|
|
68
|
+
* a live collision. Not re-exported from `index.ts`; exported here so the tests can cover the merge
|
|
69
|
+
* directly.
|
|
70
|
+
*/
|
|
71
|
+
export function withClientHeader(existing) {
|
|
72
|
+
const headers = {};
|
|
73
|
+
for (const [name, value] of Object.entries(existing ?? {})) {
|
|
74
|
+
if (name.toLowerCase() !== CLIENT_HEADER.toLowerCase())
|
|
75
|
+
headers[name] = value;
|
|
76
|
+
}
|
|
77
|
+
headers[CLIENT_HEADER] = CLIENT_IDENTITY;
|
|
78
|
+
return headers;
|
|
79
|
+
}
|
|
26
80
|
const ORANGE = "\x1b[38;5;208m";
|
|
27
81
|
const RESET = "\x1b[0m";
|
|
28
82
|
function deprecationWarning(message) {
|
|
@@ -138,7 +192,11 @@ export class XmemoryClient {
|
|
|
138
192
|
const controller = new AbortController();
|
|
139
193
|
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
140
194
|
try {
|
|
141
|
-
return await fetch(url, {
|
|
195
|
+
return await fetch(url, {
|
|
196
|
+
...init,
|
|
197
|
+
headers: withClientHeader(init.headers),
|
|
198
|
+
signal: controller.signal,
|
|
199
|
+
});
|
|
142
200
|
}
|
|
143
201
|
finally {
|
|
144
202
|
clearTimeout(timer);
|
|
@@ -154,24 +212,32 @@ export class XmemoryClient {
|
|
|
154
212
|
h["Authorization"] = `Bearer ${this._apiKey}`;
|
|
155
213
|
return h;
|
|
156
214
|
}
|
|
157
|
-
/**
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
215
|
+
/**
|
|
216
|
+
* The request URL for `path`, honouring whatever the configured base carries.
|
|
217
|
+
*
|
|
218
|
+
* Composed through `URL` rather than concatenated. Concatenation put the API path
|
|
219
|
+
* inside the query of a base that had one (`https://host?tenant=x` requested `/`),
|
|
220
|
+
* and appended a second `?` for request parameters. A plain `new URL(path, base)`
|
|
221
|
+
* is not the fix either: it drops a base path prefix, so a gateway base like
|
|
222
|
+
* `https://gw.example/xmemory` would lose `/xmemory`.
|
|
223
|
+
*/
|
|
224
|
+
_requestUrl(path, params) {
|
|
225
|
+
const url = new URL(this._baseUrl);
|
|
226
|
+
url.pathname = `${url.pathname.replace(/\/+$/, "")}${path}`;
|
|
227
|
+
for (const [key, val] of Object.entries(params ?? {})) {
|
|
228
|
+
if (Array.isArray(val)) {
|
|
229
|
+
for (const v of val)
|
|
230
|
+
url.searchParams.append(key, v);
|
|
231
|
+
}
|
|
232
|
+
else {
|
|
233
|
+
url.searchParams.append(key, val);
|
|
170
234
|
}
|
|
171
|
-
const qs = sp.toString();
|
|
172
|
-
if (qs)
|
|
173
|
-
url += `?${qs}`;
|
|
174
235
|
}
|
|
236
|
+
return url.toString();
|
|
237
|
+
}
|
|
238
|
+
/** Core request — returns the raw API wrapper `{ids, items, errors}`. */
|
|
239
|
+
async _request(method, path, options) {
|
|
240
|
+
const url = this._requestUrl(path, options?.params);
|
|
175
241
|
const timeoutMs = options?.timeoutMs ?? this._timeoutMs;
|
|
176
242
|
const hasBody = !!(options?.body && method !== "GET");
|
|
177
243
|
const init = { method, headers: this._headers(hasBody) };
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -7,10 +7,10 @@ export { DescribeResult, InstanceHandle } from "./instance.js";
|
|
|
7
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
|
-
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
10
|
+
export type { AgentSetupResult, AgentSetupStep, AgentSetupSurface, AgentSurfaceValue, FragmentMergeValue, ProjectFragment, ProjectSetup, SetupFormatValue, StepKindValue, BindingTierValue, SchemaTypeValue, ExtractionLogic, ReadMode, RelatedTypesMode, RelationCardinality, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
|
|
11
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
|
-
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
|
|
13
|
+
export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, RelatedTypes, RelatedTypesTouched, RelatedTypesLink, RelatedTypesObjectType, RelatedTypesRelation, 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";
|
|
15
15
|
export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
|
|
16
16
|
export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
|
package/dist/esm/instance.js
CHANGED
|
@@ -230,11 +230,14 @@ export class InstanceHandle {
|
|
|
230
230
|
relations_scope: options.scope.relationsScope ?? "no_relations",
|
|
231
231
|
};
|
|
232
232
|
}
|
|
233
|
+
if (options?.includeRelatedTypes != null)
|
|
234
|
+
body.include_related_types = options.includeRelatedTypes;
|
|
233
235
|
if (options?.traceId != null)
|
|
234
236
|
body.trace_id = options.traceId;
|
|
235
237
|
// The wire shape omits `reader_results` on a server without question
|
|
236
|
-
// decomposition,
|
|
237
|
-
//
|
|
238
|
+
// decomposition, and `related_types` unless the read asked for it, so type
|
|
239
|
+
// them as optional here and normalize (always-array, `null`) for the public
|
|
240
|
+
// `ReadResult` below.
|
|
238
241
|
const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
|
|
239
242
|
body,
|
|
240
243
|
timeoutMs: options?.timeoutMs,
|
|
@@ -244,10 +247,15 @@ export class InstanceHandle {
|
|
|
244
247
|
// by `Object.prototype` when the caller reads it.
|
|
245
248
|
const readerResults = own(result, "reader_results");
|
|
246
249
|
const traceId = own(result, "trace_id");
|
|
250
|
+
const relatedTypes = own(result, "related_types");
|
|
251
|
+
// `reader_result` is required on the wire and `null` is one of its answers (a
|
|
252
|
+
// refusal, in the tabular modes), so the coalescing only stands in for a field
|
|
253
|
+
// the server omitted; a `null` the server sent arrives as the same `null`.
|
|
247
254
|
return withConsoleUrl({
|
|
248
255
|
...result,
|
|
249
256
|
reader_result: own(result, "reader_result") ?? null,
|
|
250
257
|
reader_results: Array.isArray(readerResults) ? readerResults : [],
|
|
258
|
+
related_types: relatedTypes != null && typeof relatedTypes === "object" ? relatedTypes : null,
|
|
251
259
|
trace_id: typeof traceId === "string" ? traceId : null,
|
|
252
260
|
});
|
|
253
261
|
}
|
package/dist/esm/types.d.ts
CHANGED
|
@@ -8,6 +8,23 @@ export declare const SchemaType: {
|
|
|
8
8
|
export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
|
|
9
9
|
export type ExtractionLogic = "fast" | "deep";
|
|
10
10
|
export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
|
|
11
|
+
/**
|
|
12
|
+
* What a read says about the schema around its answer. `"types"` adds
|
|
13
|
+
* {@link ReadResult.related_types} to the result; `"none"` (the server default)
|
|
14
|
+
* leaves it out. Asking for it needs the `instance.get_own` permission on the
|
|
15
|
+
* API key, the same one the schema endpoints need, on top of `data.read`: a key
|
|
16
|
+
* without it gets a 403 whose message names the permission, and the plain read
|
|
17
|
+
* is unaffected.
|
|
18
|
+
*/
|
|
19
|
+
export type RelatedTypesMode = "none" | "types";
|
|
20
|
+
/**
|
|
21
|
+
* Cardinality of a relation seen from the touched type's role, derived from the
|
|
22
|
+
* relation's unique keys: `"one_to_many"` means one touched record links to many
|
|
23
|
+
* neighbours and each neighbour to at most one touched record; `"many_to_one"`
|
|
24
|
+
* is the reverse; `"unconstrained"` means the schema declares no uniqueness rule
|
|
25
|
+
* for the relation.
|
|
26
|
+
*/
|
|
27
|
+
export type RelationCardinality = "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" | "unconstrained";
|
|
11
28
|
/**
|
|
12
29
|
* One concrete object a scoped read or a scoped write may touch. Identify it by
|
|
13
30
|
* `type` (PascalCase class name or snake_case table name) plus its user-defined
|
|
@@ -155,20 +172,112 @@ export interface InstanceSchemaInfo {
|
|
|
155
172
|
* One sub-query and its own answer, in the requested read mode. Appears in
|
|
156
173
|
* {@link ReadResult.reader_results} when the server decomposed a composite query
|
|
157
174
|
* into independent sub-queries.
|
|
175
|
+
*
|
|
176
|
+
* `reader_result` gives one of the four answers described on
|
|
177
|
+
* {@link ReadResult.reader_result}, with one more case: a sub-query whose SQL
|
|
178
|
+
* failed carries the empty result *and* `error`, while the other sub-queries
|
|
179
|
+
* are answered regardless. Its bytes then equal those of a sub-query that
|
|
180
|
+
* matched nothing, so read `error` before `reader_result`.
|
|
158
181
|
*/
|
|
159
182
|
export interface TaggedReaderResult {
|
|
160
183
|
readonly sub_query: string;
|
|
161
184
|
readonly reader_result: unknown;
|
|
162
185
|
/**
|
|
163
|
-
* A user-safe message set when this sub-query could not be
|
|
164
|
-
*
|
|
186
|
+
* A user-safe message set when this sub-query's SQL could not be executed;
|
|
187
|
+
* `null` otherwise. In `"raw-tables"` / `"xresponse"` mode a read where every
|
|
188
|
+
* sub-query failed does not return at all: it throws {@link XmemoryAPIError}
|
|
189
|
+
* with `status` 422 and `code` `"INVALID_INPUT"`.
|
|
165
190
|
*/
|
|
166
191
|
readonly error: string | null;
|
|
167
192
|
}
|
|
193
|
+
/** One relation edge from a touched type to a neighbouring type; {@link RelatedTypes.types} describes both ends. */
|
|
194
|
+
export interface RelatedTypesLink {
|
|
195
|
+
/** The neighbouring object type, described once under `types`. */
|
|
196
|
+
readonly object_type: string;
|
|
197
|
+
/** The relation that links the two, described once under `relations`. */
|
|
198
|
+
readonly relation: string;
|
|
199
|
+
/** The relation role the touched type plays in this edge. */
|
|
200
|
+
readonly touched_role: string;
|
|
201
|
+
/** The relation role the neighbouring type plays in this edge. */
|
|
202
|
+
readonly related_role: string;
|
|
203
|
+
readonly cardinality: RelationCardinality;
|
|
204
|
+
}
|
|
205
|
+
/** One object type the read touched, with what it withheld and what it is linked to. */
|
|
206
|
+
export interface RelatedTypesTouched {
|
|
207
|
+
/** Object type name as declared in the schema, described under `types`. */
|
|
208
|
+
readonly object_type: string;
|
|
209
|
+
/**
|
|
210
|
+
* Fields of this type the read did not project. Ask for one by name to see it;
|
|
211
|
+
* an expression the reader could not attribute to a field counts here rather
|
|
212
|
+
* than as returned.
|
|
213
|
+
*/
|
|
214
|
+
readonly fields_not_returned: readonly string[];
|
|
215
|
+
/** Relation edges to neighbouring types, sorted by relation then type. A self-relation lists one edge per role. */
|
|
216
|
+
readonly related: readonly RelatedTypesLink[];
|
|
217
|
+
/** Edges dropped from `related` to stay within the server's payload budget. */
|
|
218
|
+
readonly omitted_related: number;
|
|
219
|
+
}
|
|
220
|
+
/** Catalog entry for an object type named anywhere in {@link RelatedTypes.touched}. */
|
|
221
|
+
export interface RelatedTypesObjectType {
|
|
222
|
+
readonly description: string | null;
|
|
223
|
+
/** Declared primary-key fields, in declared order. */
|
|
224
|
+
readonly primary_key: readonly string[];
|
|
225
|
+
/** Every field of the object type, by name. */
|
|
226
|
+
readonly fields: readonly string[];
|
|
227
|
+
}
|
|
228
|
+
/** Catalog entry for a relation named by any edge. */
|
|
229
|
+
export interface RelatedTypesRelation {
|
|
230
|
+
readonly description: string | null;
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* What else the memory could answer about, for a read that asked with
|
|
234
|
+
* `includeRelatedTypes: "types"`: the object types the read touched, each with
|
|
235
|
+
* the fields it did not return and its relation edges, plus a catalog that
|
|
236
|
+
* describes every named type and relation exactly once. It is derived from the
|
|
237
|
+
* instance schema and the statements the read executed — no extra rows are
|
|
238
|
+
* read and no model is called — so an agent can phrase a deliberate follow-up
|
|
239
|
+
* read instead of guessing. The server caps the payload; whatever it dropped is
|
|
240
|
+
* counted on the entry it was dropped from, and `truncated` says that something
|
|
241
|
+
* was.
|
|
242
|
+
*/
|
|
243
|
+
export interface RelatedTypes {
|
|
244
|
+
/** Object types the read touched, sorted by name. Empty when the read executed nothing. */
|
|
245
|
+
readonly touched: readonly RelatedTypesTouched[];
|
|
246
|
+
/** Every object type named in `touched`, touched or neighbouring, once. */
|
|
247
|
+
readonly types: Readonly<Record<string, RelatedTypesObjectType>>;
|
|
248
|
+
/** Every relation named by an edge, once. */
|
|
249
|
+
readonly relations: Readonly<Record<string, RelatedTypesRelation>>;
|
|
250
|
+
/** Touched types dropped to stay within the budget. */
|
|
251
|
+
readonly omitted_touched: number;
|
|
252
|
+
/** `true` when any type or edge was dropped for the budget. */
|
|
253
|
+
readonly truncated: boolean;
|
|
254
|
+
}
|
|
168
255
|
export interface ReadResult {
|
|
169
256
|
readonly trace_id: string | null;
|
|
170
257
|
/** Deep link to this read's trace in the console; `null` if no console is configured. */
|
|
171
258
|
readonly console_url: string | null;
|
|
259
|
+
/**
|
|
260
|
+
* The answer, shaped by `readMode`. In `"single-answer"` mode it is always the
|
|
261
|
+
* prose answer, never `null`. In `"raw-tables"` / `"xresponse"` mode its value
|
|
262
|
+
* says which of four answers the read gave:
|
|
263
|
+
*
|
|
264
|
+
* - rows — answered;
|
|
265
|
+
* - exactly `{ columns: [], rows: [] }` (`"raw-tables"`) or
|
|
266
|
+
* `{ objects: [], relations: [] }` (`"xresponse"`) — the query executed and
|
|
267
|
+
* matched nothing: every table and column it used exists, so the data is
|
|
268
|
+
* absent;
|
|
269
|
+
* - `null` — the schema provably cannot represent the concept. An answer in
|
|
270
|
+
* its own right, not a variant of the empty one: this memory cannot hold
|
|
271
|
+
* it, so a better-matching instance is worth trying;
|
|
272
|
+
* - no result at all — every sub-query's SQL failed, so nothing was
|
|
273
|
+
* answered. The read throws {@link XmemoryAPIError} with `status` 422 and
|
|
274
|
+
* `code` `"INVALID_INPUT"` rather than reporting an empty result.
|
|
275
|
+
*
|
|
276
|
+
* For a composite query this is the combined answer, folded from the parts:
|
|
277
|
+
* rows if any sub-query answered; else the empty result if any executed and
|
|
278
|
+
* matched nothing; else `null`. `reader_results` carries each part's own
|
|
279
|
+
* answer.
|
|
280
|
+
*/
|
|
172
281
|
readonly reader_result: unknown;
|
|
173
282
|
/**
|
|
174
283
|
* Per-sub-query answers when the server decomposed the query into independent
|
|
@@ -179,6 +288,14 @@ export interface ReadResult {
|
|
|
179
288
|
* so the array is empty regardless of how many questions the query held.
|
|
180
289
|
*/
|
|
181
290
|
readonly reader_results: readonly TaggedReaderResult[];
|
|
291
|
+
/**
|
|
292
|
+
* The schema around the answer, when the read asked for it with
|
|
293
|
+
* `includeRelatedTypes: "types"`; `null` otherwise. The wire omits the field
|
|
294
|
+
* unless it was requested, and a server that predates the option never sends
|
|
295
|
+
* it; the client normalizes both to `null`, so `null` means "not asked for" and
|
|
296
|
+
* a requested read that executed nothing arrives with `touched: []` instead.
|
|
297
|
+
*/
|
|
298
|
+
readonly related_types: RelatedTypes | null;
|
|
182
299
|
}
|
|
183
300
|
export interface WriteResult {
|
|
184
301
|
readonly write_id: string;
|
|
@@ -554,6 +671,14 @@ export interface ReadOptions {
|
|
|
554
671
|
readMode?: ReadMode;
|
|
555
672
|
/** Restrict the read to a set of concrete objects (plus optional relation traversal). */
|
|
556
673
|
scope?: ReadScope;
|
|
674
|
+
/**
|
|
675
|
+
* `"types"` asks for {@link ReadResult.related_types}: the object types the read
|
|
676
|
+
* touched, the fields it did not return, and the object types a declared
|
|
677
|
+
* relation links them to. Left unset, nothing is sent and the server default
|
|
678
|
+
* (`"none"`) applies. Needs `instance.get_own` on the API key; see
|
|
679
|
+
* {@link RelatedTypesMode}.
|
|
680
|
+
*/
|
|
681
|
+
includeRelatedTypes?: RelatedTypesMode;
|
|
557
682
|
traceId?: string;
|
|
558
683
|
timeoutMs?: number;
|
|
559
684
|
}
|