xmemory 3.1.1 → 3.2.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 CHANGED
@@ -155,6 +155,24 @@ console.log(result.reader_result);
155
155
 
156
156
  Options: `{ readMode?, scope?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
157
157
 
158
+ #### Composite queries
159
+
160
+ When a query bundles several independent questions, the server may decompose it
161
+ into sub-queries and answer each one. `reader_result` is still the combined
162
+ answer (for `"single-answer"` mode, a labelled multi-part string); `reader_results`
163
+ holds one `TaggedReaderResult` (`{ sub_query, reader_result, error }`) per
164
+ sub-query so you can read each answer unambiguously — a single-intent query
165
+ decomposes to one entry. `reader_results` is always an array: a server without
166
+ question decomposition omits the field on the wire and the client normalizes it
167
+ to `[]`, so it is empty regardless of how many questions the query held.
168
+
169
+ ```typescript
170
+ const result = await inst.read("Who leads sales, and where is HQ?");
171
+ for (const part of result.reader_results) {
172
+ console.log(part.sub_query, "→", part.error ?? part.reader_result);
173
+ }
174
+ ```
175
+
158
176
  #### Scoped reads
159
177
 
160
178
  By default a read may draw on the whole instance. Pass a `scope` to restrict it
@@ -343,19 +361,17 @@ when the server returned one), `details` (an optional structured payload), and
343
361
  `retryAfter` (the `Retry-After` header in seconds, when the server sent one).
344
362
 
345
363
  **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:
364
+ different things:
347
365
 
348
366
  | HTTP | `code` | Meaning | Retryable? |
349
367
  | ---- | ----------------- | ---------------------------------------------------- | ---------------------------------- |
350
368
  | 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
369
  | 429 | `RATE_LIMITED` | Genuine velocity / rate limit. | **Yes**, with backoff. |
353
370
 
354
371
  For `QUOTA_EXCEEDED`, `details` carries `kind`
355
372
  (`"daily_quota_exceeded"` | `"monthly_quota_exceeded"`) and
356
373
  `retry_after_seconds` (`number | null`); when the window is resettable the
357
374
  server also sends a `Retry-After` header, surfaced as `retryAfter` (seconds).
358
- `TRIAL_ENDED` may carry `details.kind === "trial_exceeded"` or no details.
359
375
  `RATE_LIMITED` is retryable — honour `retryAfter` (or `Retry-After`) for backoff.
360
376
  The client never retries on its own; it only surfaces the value.
361
377
 
@@ -371,10 +387,6 @@ try {
371
387
  console.error(`Quota exhausted (${kind}); resets in ${e.retryAfter ?? "?"}s`);
372
388
  break;
373
389
  }
374
- case "TRIAL_ENDED":
375
- // Non-retryable: trial over / subscription lapsed — upgrade required.
376
- console.error("Trial ended — upgrade the plan.");
377
- break;
378
390
  case "RATE_LIMITED":
379
391
  // Retryable: back off and retry, honouring Retry-After.
380
392
  console.error(`Rate limited; retry after ${e.retryAfter ?? "a short delay"}s`);
package/dist/index.d.ts CHANGED
@@ -9,6 +9,6 @@ export { SchemaType } from "./types.js";
9
9
  export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus, FieldType, OnDelete, CastStrategy, DecisionKind, MigrationSource, } from "./types.js";
10
10
  export type { ScopeObject, ReadScope, RelationsScope } from "./types.js";
11
11
  export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, UpdateInstanceSchemaOptions, DryRunMigrationOptions, ListMigrationsOptions, GetMigrationOptions, SuggestionRequestOptions, } from "./types.js";
12
- export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
12
+ export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, TaggedReaderResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, ToolDescription, ToolParameterDescription, RawDescribeResult, } from "./types.js";
13
13
  export type { MigrationPlan, MigrationOp, FieldSpec, AddObject, RemoveObject, RenameObject, ChangeObject, AddField, RemoveField, RenameField, ChangeField, AddRelation, RemoveRelation, RenameRelation, ChangeRelation, DefaultValue, EnumValues, } from "./types.js";
14
14
  export type { EnhanceSchemaResult, PlanSummary, DryRunResult, MigrationRecord, ListMigrationsResult, GetMigrationResult, ConsolidatedProposal, ProposalItem, ReviewSuggestionsResult, DecisionInput, RecordedDecision, DependencyWarning, DecideSuggestionsResult, ApplyPendingDecisionsResult, } from "./types.js";
package/dist/instance.js CHANGED
@@ -127,10 +127,14 @@ export class InstanceHandle {
127
127
  }
128
128
  if (options?.traceId != null)
129
129
  body.trace_id = options.traceId;
130
- return this._requestOne("POST", `/instances/${this.id}/read`, {
130
+ // The wire shape omits `reader_results` on a server without question
131
+ // decomposition, so type it as optional here and normalize to an always-array
132
+ // for the public `ReadResult` below.
133
+ const result = await this._requestOne("POST", `/instances/${this.id}/read`, {
131
134
  body,
132
135
  timeoutMs: options?.timeoutMs,
133
136
  });
137
+ return { ...result, reader_results: result.reader_results ?? [] };
134
138
  }
135
139
  async write(text, options) {
136
140
  const body = {
package/dist/types.d.ts CHANGED
@@ -34,9 +34,8 @@ export declare class XmemoryAPIError extends Error {
34
34
  /**
35
35
  * Structured error code when the server returned one. **Branch on this,
36
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
37
+ * things. HTTP 402 carries `"QUOTA_EXCEEDED"` (plan/usage allowance
38
+ * exhausted — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
40
39
  * velocity limit — retryable with backoff, honour `retryAfter`). For the
41
40
  * schema-evolution endpoints this is the `error_type` discriminator
42
41
  * (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
@@ -47,8 +46,7 @@ export declare class XmemoryAPIError extends Error {
47
46
  * Optional structured `details` payload attached to some errors. For
48
47
  * `"QUOTA_EXCEEDED"` this carries `kind`
49
48
  * (`"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.
49
+ * `retry_after_seconds` (`number | null`).
52
50
  */
53
51
  readonly details?: (Record<string, unknown> | null) | undefined;
54
52
  /**
@@ -63,9 +61,8 @@ export declare class XmemoryAPIError extends Error {
63
61
  /**
64
62
  * Structured error code when the server returned one. **Branch on this,
65
63
  * 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
64
+ * things. HTTP 402 carries `"QUOTA_EXCEEDED"` (plan/usage allowance
65
+ * exhausted — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
69
66
  * velocity limit — retryable with backoff, honour `retryAfter`). For the
70
67
  * schema-evolution endpoints this is the `error_type` discriminator
71
68
  * (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
@@ -76,8 +73,7 @@ export declare class XmemoryAPIError extends Error {
76
73
  * Optional structured `details` payload attached to some errors. For
77
74
  * `"QUOTA_EXCEEDED"` this carries `kind`
78
75
  * (`"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.
76
+ * `retry_after_seconds` (`number | null`).
81
77
  */
82
78
  details?: (Record<string, unknown> | null) | undefined,
83
79
  /**
@@ -112,9 +108,32 @@ export interface InstanceInfo {
112
108
  export interface InstanceSchemaInfo {
113
109
  readonly data_schema: Record<string, unknown>;
114
110
  }
111
+ /**
112
+ * One sub-query and its own answer, in the requested read mode. Appears in
113
+ * {@link ReadResult.reader_results} when the server decomposed a composite query
114
+ * into independent sub-queries.
115
+ */
116
+ export interface TaggedReaderResult {
117
+ readonly sub_query: string;
118
+ readonly reader_result: unknown;
119
+ /**
120
+ * A user-safe message set when this sub-query could not be answered while the
121
+ * others still were (partial tolerance); `null` otherwise.
122
+ */
123
+ readonly error: string | null;
124
+ }
115
125
  export interface ReadResult {
116
126
  readonly trace_id: string | null;
117
127
  readonly reader_result: unknown;
128
+ /**
129
+ * Per-sub-query answers when the server decomposed the query into independent
130
+ * sub-queries — one entry per sub-query, so a single-intent query decomposes
131
+ * to exactly one. `reader_result` above stays the combined back-compat value.
132
+ * Always an array: a server without question decomposition (or with it
133
+ * disabled) omits the field on the wire and the client normalizes it to `[]`,
134
+ * so the array is empty regardless of how many questions the query held.
135
+ */
136
+ readonly reader_results: readonly TaggedReaderResult[];
118
137
  }
119
138
  export interface WriteResult {
120
139
  readonly write_id: string;
package/dist/types.js CHANGED
@@ -17,9 +17,8 @@ export class XmemoryAPIError extends Error {
17
17
  /**
18
18
  * Structured error code when the server returned one. **Branch on this,
19
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
20
+ * things. HTTP 402 carries `"QUOTA_EXCEEDED"` (plan/usage allowance
21
+ * exhausted — non-retryable); HTTP 429 carries `"RATE_LIMITED"` (genuine
23
22
  * velocity limit — retryable with backoff, honour `retryAfter`). For the
24
23
  * schema-evolution endpoints this is the `error_type` discriminator
25
24
  * (e.g. `"stale_proposal_version"`, `"destructive_confirmation_required"`).
@@ -30,8 +29,7 @@ export class XmemoryAPIError extends Error {
30
29
  * Optional structured `details` payload attached to some errors. For
31
30
  * `"QUOTA_EXCEEDED"` this carries `kind`
32
31
  * (`"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.
32
+ * `retry_after_seconds` (`number | null`).
35
33
  */
36
34
  details,
37
35
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.1.1",
3
+ "version": "3.2.1",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"