xmemory 2.3.0 → 3.1.1
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 +51 -5
- package/dist/client.js +22 -1
- package/dist/instance.d.ts +1 -0
- package/dist/instance.js +5 -0
- package/dist/types.d.ts +47 -7
- package/dist/types.js +24 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# xmemory
|
|
2
2
|
|
|
3
|
-
TypeScript/JavaScript client library for the [
|
|
3
|
+
TypeScript/JavaScript client library for the [xmemory](https://xmemory.ai) API.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
@@ -30,7 +30,7 @@ console.log(result.reader_result);
|
|
|
30
30
|
|
|
31
31
|
| Parameter | Env var | Default | Description |
|
|
32
32
|
|-------------|------------------|---------------------------|-----------------------------------------|
|
|
33
|
-
| `url` | `XMEM_API_URL` | `https://api.xmemory.ai` | Base URL of the
|
|
33
|
+
| `url` | `XMEM_API_URL` | `https://api.xmemory.ai` | Base URL of the xmemory API |
|
|
34
34
|
| `apiKey` | `XMEM_API_KEY` | `undefined` | Bearer API key for authentication |
|
|
35
35
|
| `timeoutMs` | — | `60000` | Default request timeout in milliseconds |
|
|
36
36
|
|
|
@@ -122,6 +122,7 @@ Extract and store structured objects from text.
|
|
|
122
122
|
```typescript
|
|
123
123
|
const result = await inst.write("Bob is a designer based in Berlin.");
|
|
124
124
|
console.log(result.write_id, result.trace_id);
|
|
125
|
+
console.log(result.changes); // what the write created / updated / deleted
|
|
125
126
|
```
|
|
126
127
|
|
|
127
128
|
Options: `{ extractionLogic?, diffEngine?, timeoutMs? }` — `extractionLogic` defaults to `"fast"`.
|
|
@@ -338,9 +339,54 @@ try {
|
|
|
338
339
|
```
|
|
339
340
|
|
|
340
341
|
`XmemoryAPIError` carries `status` (HTTP status), `code` (structured error code,
|
|
341
|
-
when the server returned one),
|
|
342
|
-
|
|
343
|
-
|
|
342
|
+
when the server returned one), `details` (an optional structured payload), and
|
|
343
|
+
`retryAfter` (the `Retry-After` header in seconds, when the server sent one).
|
|
344
|
+
|
|
345
|
+
**Branch on `code`, not on the bare HTTP status** — the same status can mean
|
|
346
|
+
different things. In particular HTTP `402 Payment Required` is now overloaded:
|
|
347
|
+
|
|
348
|
+
| HTTP | `code` | Meaning | Retryable? |
|
|
349
|
+
| ---- | ----------------- | ---------------------------------------------------- | ---------------------------------- |
|
|
350
|
+
| 402 | `QUOTA_EXCEEDED` | Tenant exhausted its plan/usage allowance (a daily or monthly token quota). | **No.** Wait for the window to reset. |
|
|
351
|
+
| 402 | `TRIAL_ENDED` | Trial over / subscription lapsed. | **No.** Needs a plan change. |
|
|
352
|
+
| 429 | `RATE_LIMITED` | Genuine velocity / rate limit. | **Yes**, with backoff. |
|
|
353
|
+
|
|
354
|
+
For `QUOTA_EXCEEDED`, `details` carries `kind`
|
|
355
|
+
(`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
|
356
|
+
`retry_after_seconds` (`number | null`); when the window is resettable the
|
|
357
|
+
server also sends a `Retry-After` header, surfaced as `retryAfter` (seconds).
|
|
358
|
+
`TRIAL_ENDED` may carry `details.kind === "trial_exceeded"` or no details.
|
|
359
|
+
`RATE_LIMITED` is retryable — honour `retryAfter` (or `Retry-After`) for backoff.
|
|
360
|
+
The client never retries on its own; it only surfaces the value.
|
|
361
|
+
|
|
362
|
+
```typescript
|
|
363
|
+
try {
|
|
364
|
+
await inst.write("...");
|
|
365
|
+
} catch (e) {
|
|
366
|
+
if (!(e instanceof XmemoryAPIError)) throw e;
|
|
367
|
+
switch (e.code) {
|
|
368
|
+
case "QUOTA_EXCEEDED": {
|
|
369
|
+
// Non-retryable: plan/usage allowance exhausted.
|
|
370
|
+
const kind = (e.details as { kind?: string } | null)?.kind; // daily_ | monthly_quota_exceeded
|
|
371
|
+
console.error(`Quota exhausted (${kind}); resets in ${e.retryAfter ?? "?"}s`);
|
|
372
|
+
break;
|
|
373
|
+
}
|
|
374
|
+
case "TRIAL_ENDED":
|
|
375
|
+
// Non-retryable: trial over / subscription lapsed — upgrade required.
|
|
376
|
+
console.error("Trial ended — upgrade the plan.");
|
|
377
|
+
break;
|
|
378
|
+
case "RATE_LIMITED":
|
|
379
|
+
// Retryable: back off and retry, honouring Retry-After.
|
|
380
|
+
console.error(`Rate limited; retry after ${e.retryAfter ?? "a short delay"}s`);
|
|
381
|
+
break;
|
|
382
|
+
default:
|
|
383
|
+
console.error(`API error (HTTP ${e.status}, code ${e.code}): ${e.message}`);
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
The schema-evolution endpoints return codes you can pattern match on via `.code`
|
|
389
|
+
the same way — for example `stale_proposal_version`, `dependency_closure_failed`,
|
|
344
390
|
`destructive_confirmation_required`, `non_additive_change_requires_plan`,
|
|
345
391
|
`stale_schema_version`, `migration_not_found`, `instance_not_initialised`:
|
|
346
392
|
|
package/dist/client.js
CHANGED
|
@@ -33,10 +33,31 @@ function extractStructuredError(payload) {
|
|
|
33
33
|
return {
|
|
34
34
|
code: typeof first.code === "string" ? first.code : undefined,
|
|
35
35
|
message: typeof first.message === "string" ? first.message : undefined,
|
|
36
|
+
details: (first.details ?? null),
|
|
36
37
|
};
|
|
37
38
|
}
|
|
38
39
|
return {};
|
|
39
40
|
}
|
|
41
|
+
/**
|
|
42
|
+
* Parse the HTTP `Retry-After` response header into a number of seconds, or
|
|
43
|
+
* `undefined` when the header is absent or unparseable. Supports both the
|
|
44
|
+
* delta-seconds form (`Retry-After: 30`) and the HTTP-date form; HTTP-dates
|
|
45
|
+
* are converted to a non-negative second offset from now.
|
|
46
|
+
*/
|
|
47
|
+
function parseRetryAfter(res) {
|
|
48
|
+
const raw = res.headers.get("Retry-After");
|
|
49
|
+
if (raw == null)
|
|
50
|
+
return undefined;
|
|
51
|
+
const trimmed = raw.trim();
|
|
52
|
+
if (trimmed === "")
|
|
53
|
+
return undefined;
|
|
54
|
+
if (/^\d+$/.test(trimmed))
|
|
55
|
+
return Number(trimmed);
|
|
56
|
+
const dateMs = Date.parse(trimmed);
|
|
57
|
+
if (Number.isNaN(dateMs))
|
|
58
|
+
return undefined;
|
|
59
|
+
return Math.max(0, Math.round((dateMs - Date.now()) / 1000));
|
|
60
|
+
}
|
|
40
61
|
// ---------------------------------------------------------------------------
|
|
41
62
|
// Client
|
|
42
63
|
// ---------------------------------------------------------------------------
|
|
@@ -154,7 +175,7 @@ export class XmemoryClient {
|
|
|
154
175
|
(typeof payload === "object" && payload !== null && "message" in payload
|
|
155
176
|
? String(payload.message)
|
|
156
177
|
: raw.slice(0, 200));
|
|
157
|
-
throw new XmemoryAPIError(`HTTP ${res.status}: ${msg}`, res.status, structured.code, structured.details);
|
|
178
|
+
throw new XmemoryAPIError(`HTTP ${res.status}: ${msg}`, res.status, structured.code, structured.details, parseRetryAfter(res));
|
|
158
179
|
}
|
|
159
180
|
const response = payload;
|
|
160
181
|
if (response.errors?.length) {
|
package/dist/instance.d.ts
CHANGED
|
@@ -5,6 +5,7 @@ import type { ApplyPendingDecisionsResult, AsyncWriteResult, DecideSuggestionsRe
|
|
|
5
5
|
export declare class DescribeResult {
|
|
6
6
|
readonly instanceId: string;
|
|
7
7
|
readonly instanceName: string;
|
|
8
|
+
readonly about: string;
|
|
8
9
|
readonly schemaSummary: string;
|
|
9
10
|
readonly tools: readonly ToolDescription[];
|
|
10
11
|
constructor(raw: RawDescribeResult);
|
package/dist/instance.js
CHANGED
|
@@ -5,11 +5,13 @@ const DEFAULT_DESCRIBE_TTL_MS = 300_000; // 5 minutes
|
|
|
5
5
|
export class DescribeResult {
|
|
6
6
|
instanceId;
|
|
7
7
|
instanceName;
|
|
8
|
+
about;
|
|
8
9
|
schemaSummary;
|
|
9
10
|
tools;
|
|
10
11
|
constructor(raw) {
|
|
11
12
|
this.instanceId = raw.instance_id;
|
|
12
13
|
this.instanceName = raw.instance_name;
|
|
14
|
+
this.about = raw.about ?? "";
|
|
13
15
|
this.schemaSummary = raw.schema_summary;
|
|
14
16
|
this.tools = raw.tools;
|
|
15
17
|
}
|
|
@@ -24,6 +26,9 @@ export class DescribeResult {
|
|
|
24
26
|
const includeHttp = options?.includeHttp ?? false;
|
|
25
27
|
const lines = [];
|
|
26
28
|
lines.push(`Instance: ${this.instanceName} (${this.instanceId})`);
|
|
29
|
+
if (this.about) {
|
|
30
|
+
lines.push(`\n${this.about}`);
|
|
31
|
+
}
|
|
27
32
|
if (this.schemaSummary) {
|
|
28
33
|
lines.push(`\n${this.schemaSummary}`);
|
|
29
34
|
}
|
package/dist/types.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ export declare const SchemaType: {
|
|
|
6
6
|
readonly JSON: 1;
|
|
7
7
|
};
|
|
8
8
|
export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
|
|
9
|
-
export type ExtractionLogic = "fast" | "
|
|
9
|
+
export type ExtractionLogic = "fast" | "deep";
|
|
10
10
|
export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
|
|
11
11
|
/**
|
|
12
12
|
* One concrete object a scoped read may touch. Identify it by `type` (PascalCase
|
|
@@ -32,24 +32,62 @@ export type WriteQueueStatus = "queued" | "processing" | "extracting" | "extract
|
|
|
32
32
|
export declare class XmemoryAPIError extends Error {
|
|
33
33
|
readonly status?: number | undefined;
|
|
34
34
|
/**
|
|
35
|
-
* Structured error code when the server returned one.
|
|
35
|
+
* Structured error code when the server returned one. **Branch on this,
|
|
36
|
+
* not on the bare HTTP `status`** — the same status can mean different
|
|
37
|
+
* things. HTTP 402 carries either `"QUOTA_EXCEEDED"` (plan/usage allowance
|
|
38
|
+
* exhausted — non-retryable) or `"TRIAL_ENDED"` (trial over / subscription
|
|
39
|
+
* lapsed — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
40
|
+
* velocity limit — retryable with backoff, honour `retryAfter`). For the
|
|
36
41
|
* schema-evolution endpoints this is the `error_type` discriminator
|
|
37
42
|
* (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
|
|
38
43
|
* Pattern match on this instead of parsing the message.
|
|
39
44
|
*/
|
|
40
45
|
readonly code?: string | undefined;
|
|
41
|
-
/**
|
|
46
|
+
/**
|
|
47
|
+
* Optional structured `details` payload attached to some errors. For
|
|
48
|
+
* `"QUOTA_EXCEEDED"` this carries `kind`
|
|
49
|
+
* (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
|
50
|
+
* `retry_after_seconds` (`number | null`); `"TRIAL_ENDED"` may carry
|
|
51
|
+
* `kind: "trial_exceeded"` or no details at all.
|
|
52
|
+
*/
|
|
42
53
|
readonly details?: (Record<string, unknown> | null) | undefined;
|
|
54
|
+
/**
|
|
55
|
+
* The HTTP `Retry-After` response header, in seconds, when the server sent
|
|
56
|
+
* one — e.g. on `429 RATE_LIMITED`, or a resettable `402 QUOTA_EXCEEDED`.
|
|
57
|
+
* This is the transport-level header value; for quota errors the same hint
|
|
58
|
+
* may also appear as `details.retry_after_seconds`. Surfaced for callers
|
|
59
|
+
* that implement their own backoff — the client does not retry on its own.
|
|
60
|
+
*/
|
|
61
|
+
readonly retryAfter?: number | undefined;
|
|
43
62
|
constructor(message: string, status?: number | undefined,
|
|
44
63
|
/**
|
|
45
|
-
* Structured error code when the server returned one.
|
|
64
|
+
* Structured error code when the server returned one. **Branch on this,
|
|
65
|
+
* not on the bare HTTP `status`** — the same status can mean different
|
|
66
|
+
* things. HTTP 402 carries either `"QUOTA_EXCEEDED"` (plan/usage allowance
|
|
67
|
+
* exhausted — non-retryable) or `"TRIAL_ENDED"` (trial over / subscription
|
|
68
|
+
* lapsed — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
69
|
+
* velocity limit — retryable with backoff, honour `retryAfter`). For the
|
|
46
70
|
* schema-evolution endpoints this is the `error_type` discriminator
|
|
47
71
|
* (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
|
|
48
72
|
* Pattern match on this instead of parsing the message.
|
|
49
73
|
*/
|
|
50
74
|
code?: string | undefined,
|
|
51
|
-
/**
|
|
52
|
-
|
|
75
|
+
/**
|
|
76
|
+
* Optional structured `details` payload attached to some errors. For
|
|
77
|
+
* `"QUOTA_EXCEEDED"` this carries `kind`
|
|
78
|
+
* (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
|
79
|
+
* `retry_after_seconds` (`number | null`); `"TRIAL_ENDED"` may carry
|
|
80
|
+
* `kind: "trial_exceeded"` or no details at all.
|
|
81
|
+
*/
|
|
82
|
+
details?: (Record<string, unknown> | null) | undefined,
|
|
83
|
+
/**
|
|
84
|
+
* The HTTP `Retry-After` response header, in seconds, when the server sent
|
|
85
|
+
* one — e.g. on `429 RATE_LIMITED`, or a resettable `402 QUOTA_EXCEEDED`.
|
|
86
|
+
* This is the transport-level header value; for quota errors the same hint
|
|
87
|
+
* may also appear as `details.retry_after_seconds`. Surfaced for callers
|
|
88
|
+
* that implement their own backoff — the client does not retry on its own.
|
|
89
|
+
*/
|
|
90
|
+
retryAfter?: number | undefined);
|
|
53
91
|
}
|
|
54
92
|
export declare class XmemoryHealthCheckError extends XmemoryAPIError {
|
|
55
93
|
constructor(message: string, status?: number);
|
|
@@ -81,7 +119,8 @@ export interface ReadResult {
|
|
|
81
119
|
export interface WriteResult {
|
|
82
120
|
readonly write_id: string;
|
|
83
121
|
readonly trace_id: string | null;
|
|
84
|
-
|
|
122
|
+
/** What the write did, grouped into `created` / `updated` / `deleted`. */
|
|
123
|
+
readonly changes: unknown;
|
|
85
124
|
}
|
|
86
125
|
export interface AsyncWriteResult {
|
|
87
126
|
readonly write_id: string;
|
|
@@ -326,6 +365,7 @@ export interface ToolDescription {
|
|
|
326
365
|
export interface RawDescribeResult {
|
|
327
366
|
readonly instance_id: string;
|
|
328
367
|
readonly instance_name: string;
|
|
368
|
+
readonly about?: string;
|
|
329
369
|
readonly schema_summary: string;
|
|
330
370
|
readonly tools: ToolDescription[];
|
|
331
371
|
}
|
package/dist/types.js
CHANGED
|
@@ -12,20 +12,41 @@ export class XmemoryAPIError extends Error {
|
|
|
12
12
|
status;
|
|
13
13
|
code;
|
|
14
14
|
details;
|
|
15
|
+
retryAfter;
|
|
15
16
|
constructor(message, status,
|
|
16
17
|
/**
|
|
17
|
-
* Structured error code when the server returned one.
|
|
18
|
+
* Structured error code when the server returned one. **Branch on this,
|
|
19
|
+
* not on the bare HTTP `status`** — the same status can mean different
|
|
20
|
+
* things. HTTP 402 carries either `"QUOTA_EXCEEDED"` (plan/usage allowance
|
|
21
|
+
* exhausted — non-retryable) or `"TRIAL_ENDED"` (trial over / subscription
|
|
22
|
+
* lapsed — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
|
|
23
|
+
* velocity limit — retryable with backoff, honour `retryAfter`). For the
|
|
18
24
|
* schema-evolution endpoints this is the `error_type` discriminator
|
|
19
25
|
* (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
|
|
20
26
|
* Pattern match on this instead of parsing the message.
|
|
21
27
|
*/
|
|
22
28
|
code,
|
|
23
|
-
/**
|
|
24
|
-
|
|
29
|
+
/**
|
|
30
|
+
* Optional structured `details` payload attached to some errors. For
|
|
31
|
+
* `"QUOTA_EXCEEDED"` this carries `kind`
|
|
32
|
+
* (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
|
|
33
|
+
* `retry_after_seconds` (`number | null`); `"TRIAL_ENDED"` may carry
|
|
34
|
+
* `kind: "trial_exceeded"` or no details at all.
|
|
35
|
+
*/
|
|
36
|
+
details,
|
|
37
|
+
/**
|
|
38
|
+
* The HTTP `Retry-After` response header, in seconds, when the server sent
|
|
39
|
+
* one — e.g. on `429 RATE_LIMITED`, or a resettable `402 QUOTA_EXCEEDED`.
|
|
40
|
+
* This is the transport-level header value; for quota errors the same hint
|
|
41
|
+
* may also appear as `details.retry_after_seconds`. Surfaced for callers
|
|
42
|
+
* that implement their own backoff — the client does not retry on its own.
|
|
43
|
+
*/
|
|
44
|
+
retryAfter) {
|
|
25
45
|
super(message);
|
|
26
46
|
this.status = status;
|
|
27
47
|
this.code = code;
|
|
28
48
|
this.details = details;
|
|
49
|
+
this.retryAfter = retryAfter;
|
|
29
50
|
this.name = "XmemoryAPIError";
|
|
30
51
|
}
|
|
31
52
|
}
|