xmemory 3.0.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  # xmemory
2
2
 
3
- TypeScript/JavaScript client library for the [Xmemory](https://xmemory.ai) API.
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 Xmemory API |
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
 
@@ -339,9 +339,54 @@ try {
339
339
  ```
340
340
 
341
341
  `XmemoryAPIError` carries `status` (HTTP status), `code` (structured error code,
342
- when the server returned one), and `details`. The schema-evolution endpoints
343
- return codes you can pattern match on via `.code` — for example
344
- `stale_proposal_version`, `dependency_closure_failed`,
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`,
345
390
  `destructive_confirmation_required`, `non_additive_change_requires_plan`,
346
391
  `stale_schema_version`, `migration_not_found`, `instance_not_initialised`:
347
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/types.d.ts CHANGED
@@ -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. For the
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
- /** Optional structured `details` payload attached to some errors. */
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. For the
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
- /** Optional structured `details` payload attached to some errors. */
52
- details?: (Record<string, unknown> | null) | undefined);
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);
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. For the
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
- /** Optional structured `details` payload attached to some errors. */
24
- details) {
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
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xmemory",
3
- "version": "3.0.0",
3
+ "version": "3.1.1",
4
4
  "description": "xmemory",
5
5
  "keywords": [
6
6
  "xmemory"