@maximem/synap-js-sdk 0.5.21 → 0.6.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.
@@ -318,7 +318,7 @@ declare class AnticipationCache {
318
318
  * works across realms too -- but `.code` is the documented contract.
319
319
  */
320
320
  /** Stable, format-independent discriminators. Never renumber or reuse. */
321
- type SynapErrorCode = 'synap_error' | 'transient' | 'permanent' | 'network_timeout' | 'rate_limit' | 'insufficient_credits' | 'service_unavailable' | 'invalid_input' | 'invalid_instance_id' | 'invalid_conversation_id' | 'customer_id_not_accepted' | 'authentication' | 'context_not_found' | 'conflict' | 'transcript_conflict' | 'session_expired' | 'listening_already_active' | 'listening_not_active' | 'agent_unavailable';
321
+ type SynapErrorCode = 'synap_error' | 'transient' | 'permanent' | 'network_timeout' | 'rate_limit' | 'insufficient_credits' | 'service_unavailable' | 'invalid_input' | 'invalid_instance_id' | 'invalid_conversation_id' | 'customer_id_not_accepted' | 'authentication' | 'context_not_found' | 'conflict' | 'transcript_conflict' | 'instance_not_ready' | 'instance_build_failed' | 'session_expired' | 'listening_already_active' | 'listening_not_active' | 'agent_unavailable';
322
322
  interface SynapErrorOptions {
323
323
  correlationId?: string | null;
324
324
  cause?: unknown;
@@ -463,6 +463,64 @@ declare class ConflictError extends SynapPermanentError {
463
463
  declare class TranscriptConflictError extends ConflictError {
464
464
  static readonly errorCode: SynapErrorCode;
465
465
  }
466
+ /**
467
+ * The instance's memory architecture is still being built (HTTP 409).
468
+ *
469
+ * A new instance usually spends 15 to 20 minutes building. Until that finishes the
470
+ * server refuses memory writes and reads with
471
+ * `409 {"error": "instance_not_ready", ...}` plus a `Retry-After` header.
472
+ * Nothing was recorded; the same call works once the build is done.
473
+ *
474
+ * Extends `ConflictError`, so existing `catch` code that handles
475
+ * `ConflictError` keeps working. Thrown immediately and **never retried inside
476
+ * the SDK**: a wait this long must not hide inside a call. Mirrors
477
+ * `InstanceNotReadyError` in `maximem_synap/models/errors.py`.
478
+ */
479
+ declare class InstanceNotReadyError extends ConflictError {
480
+ static readonly errorCode: SynapErrorCode;
481
+ /** The server's estimate of the wait. Python calls this `retry_after_seconds`. */
482
+ readonly retryAfterSeconds: number | null;
483
+ readonly instanceId: string | null;
484
+ /** Build state reported by the server (`'building'`). */
485
+ readonly state: string | null;
486
+ /**
487
+ * `true` when the SDK threw this itself, without a network call, because an
488
+ * earlier call to the same instance was refused and the server's wait has not
489
+ * elapsed. Then `retryAfterSeconds` is the REMAINING wait (rounded up, at
490
+ * least 1). `false` when the server sent this refusal just now. Python:
491
+ * `from_cooldown`.
492
+ */
493
+ readonly fromCooldown: boolean;
494
+ constructor(message?: string, options?: SynapErrorOptions & {
495
+ retryAfterSeconds?: number | null;
496
+ instanceId?: string | null;
497
+ state?: string | null;
498
+ fromCooldown?: boolean;
499
+ });
500
+ }
501
+ /**
502
+ * The instance's memory architecture build failed for good (HTTP 409
503
+ * `{"error": "instance_build_failed", ...}`).
504
+ *
505
+ * The server tried the build several times and gave up. Waiting does not help:
506
+ * a person has to start a rebuild (see `hint`, e.g.
507
+ * `maximem-synap instances rebuild <instance_id>`). Extends `ConflictError`.
508
+ * Thrown immediately, **never retried** and sets **no cooldown**: it is not time
509
+ * based. Mirrors `InstanceBuildFailedError` in `maximem_synap/models/errors.py`.
510
+ */
511
+ declare class InstanceBuildFailedError extends ConflictError {
512
+ static readonly errorCode: SynapErrorCode;
513
+ readonly instanceId: string | null;
514
+ /** How many build attempts the server made. Python: `attempts`. */
515
+ readonly attempts: number | null;
516
+ /** The server's instruction for recovering. */
517
+ readonly hint: string | null;
518
+ constructor(message?: string, options?: SynapErrorOptions & {
519
+ instanceId?: string | null;
520
+ attempts?: number | null;
521
+ hint?: string | null;
522
+ });
523
+ }
466
524
  declare class SessionExpiredError extends SynapPermanentError {
467
525
  static readonly errorCode: SynapErrorCode;
468
526
  }
@@ -477,4 +535,4 @@ declare const TransientError: typeof SynapTransientError;
477
535
  declare const PermanentError: typeof SynapPermanentError;
478
536
  declare const ConnectionError: typeof NetworkTimeoutError;
479
537
 
480
- export { AnticipationCache as A, type BundleItem as B, ConflictError as C, SynapTransientError as D, type Encoder as E, TransientError as F, isSynapError as G, InsufficientCreditsError as I, ListeningAlreadyActiveError as L, NetworkTimeoutError as N, PermanentError as P, RateLimitError as R, SynapError as S, TranscriptConflictError as T, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, AgentUnavailableError as c, type AnticipationCacheOptions as d, AuthenticationError as e, ConnectionError as f, type ContextBundle as g, ContextNotFoundError as h, CustomerIdNotAcceptedError as i, type ExitReason as j, InvalidConversationIdError as k, InvalidInputError as l, InvalidInstanceIdError as m, ListeningNotActiveError as n, type LookupParams as o, type LookupResult as p, type LookupTelemetry as q, SDKError as r, ServiceUnavailableError as s, SessionExpiredError as t, type SnapshotBundle as u, type SnapshotItemPreview as v, type SnapshotItemRecord as w, type SynapErrorCode as x, type SynapErrorOptions as y, SynapPermanentError as z };
538
+ export { AnticipationCache as A, type BundleItem as B, ConflictError as C, type SynapErrorOptions as D, type Encoder as E, SynapPermanentError as F, SynapTransientError as G, TransientError as H, InstanceBuildFailedError as I, isSynapError as J, ListeningAlreadyActiveError as L, NetworkTimeoutError as N, PermanentError as P, RateLimitError as R, SynapError as S, TranscriptConflictError as T, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, AgentUnavailableError as c, type AnticipationCacheOptions as d, AuthenticationError as e, ConnectionError as f, type ContextBundle as g, ContextNotFoundError as h, CustomerIdNotAcceptedError as i, type ExitReason as j, InstanceNotReadyError as k, InsufficientCreditsError as l, InvalidConversationIdError as m, InvalidInputError as n, InvalidInstanceIdError as o, ListeningNotActiveError as p, type LookupParams as q, type LookupResult as r, type LookupTelemetry as s, SDKError as t, ServiceUnavailableError as u, SessionExpiredError as v, type SnapshotBundle as w, type SnapshotItemPreview as x, type SnapshotItemRecord as y, type SynapErrorCode as z };
@@ -318,7 +318,7 @@ declare class AnticipationCache {
318
318
  * works across realms too -- but `.code` is the documented contract.
319
319
  */
320
320
  /** Stable, format-independent discriminators. Never renumber or reuse. */
321
- type SynapErrorCode = 'synap_error' | 'transient' | 'permanent' | 'network_timeout' | 'rate_limit' | 'insufficient_credits' | 'service_unavailable' | 'invalid_input' | 'invalid_instance_id' | 'invalid_conversation_id' | 'customer_id_not_accepted' | 'authentication' | 'context_not_found' | 'conflict' | 'transcript_conflict' | 'session_expired' | 'listening_already_active' | 'listening_not_active' | 'agent_unavailable';
321
+ type SynapErrorCode = 'synap_error' | 'transient' | 'permanent' | 'network_timeout' | 'rate_limit' | 'insufficient_credits' | 'service_unavailable' | 'invalid_input' | 'invalid_instance_id' | 'invalid_conversation_id' | 'customer_id_not_accepted' | 'authentication' | 'context_not_found' | 'conflict' | 'transcript_conflict' | 'instance_not_ready' | 'instance_build_failed' | 'session_expired' | 'listening_already_active' | 'listening_not_active' | 'agent_unavailable';
322
322
  interface SynapErrorOptions {
323
323
  correlationId?: string | null;
324
324
  cause?: unknown;
@@ -463,6 +463,64 @@ declare class ConflictError extends SynapPermanentError {
463
463
  declare class TranscriptConflictError extends ConflictError {
464
464
  static readonly errorCode: SynapErrorCode;
465
465
  }
466
+ /**
467
+ * The instance's memory architecture is still being built (HTTP 409).
468
+ *
469
+ * A new instance usually spends 15 to 20 minutes building. Until that finishes the
470
+ * server refuses memory writes and reads with
471
+ * `409 {"error": "instance_not_ready", ...}` plus a `Retry-After` header.
472
+ * Nothing was recorded; the same call works once the build is done.
473
+ *
474
+ * Extends `ConflictError`, so existing `catch` code that handles
475
+ * `ConflictError` keeps working. Thrown immediately and **never retried inside
476
+ * the SDK**: a wait this long must not hide inside a call. Mirrors
477
+ * `InstanceNotReadyError` in `maximem_synap/models/errors.py`.
478
+ */
479
+ declare class InstanceNotReadyError extends ConflictError {
480
+ static readonly errorCode: SynapErrorCode;
481
+ /** The server's estimate of the wait. Python calls this `retry_after_seconds`. */
482
+ readonly retryAfterSeconds: number | null;
483
+ readonly instanceId: string | null;
484
+ /** Build state reported by the server (`'building'`). */
485
+ readonly state: string | null;
486
+ /**
487
+ * `true` when the SDK threw this itself, without a network call, because an
488
+ * earlier call to the same instance was refused and the server's wait has not
489
+ * elapsed. Then `retryAfterSeconds` is the REMAINING wait (rounded up, at
490
+ * least 1). `false` when the server sent this refusal just now. Python:
491
+ * `from_cooldown`.
492
+ */
493
+ readonly fromCooldown: boolean;
494
+ constructor(message?: string, options?: SynapErrorOptions & {
495
+ retryAfterSeconds?: number | null;
496
+ instanceId?: string | null;
497
+ state?: string | null;
498
+ fromCooldown?: boolean;
499
+ });
500
+ }
501
+ /**
502
+ * The instance's memory architecture build failed for good (HTTP 409
503
+ * `{"error": "instance_build_failed", ...}`).
504
+ *
505
+ * The server tried the build several times and gave up. Waiting does not help:
506
+ * a person has to start a rebuild (see `hint`, e.g.
507
+ * `maximem-synap instances rebuild <instance_id>`). Extends `ConflictError`.
508
+ * Thrown immediately, **never retried** and sets **no cooldown**: it is not time
509
+ * based. Mirrors `InstanceBuildFailedError` in `maximem_synap/models/errors.py`.
510
+ */
511
+ declare class InstanceBuildFailedError extends ConflictError {
512
+ static readonly errorCode: SynapErrorCode;
513
+ readonly instanceId: string | null;
514
+ /** How many build attempts the server made. Python: `attempts`. */
515
+ readonly attempts: number | null;
516
+ /** The server's instruction for recovering. */
517
+ readonly hint: string | null;
518
+ constructor(message?: string, options?: SynapErrorOptions & {
519
+ instanceId?: string | null;
520
+ attempts?: number | null;
521
+ hint?: string | null;
522
+ });
523
+ }
466
524
  declare class SessionExpiredError extends SynapPermanentError {
467
525
  static readonly errorCode: SynapErrorCode;
468
526
  }
@@ -477,4 +535,4 @@ declare const TransientError: typeof SynapTransientError;
477
535
  declare const PermanentError: typeof SynapPermanentError;
478
536
  declare const ConnectionError: typeof NetworkTimeoutError;
479
537
 
480
- export { AnticipationCache as A, type BundleItem as B, ConflictError as C, SynapTransientError as D, type Encoder as E, TransientError as F, isSynapError as G, InsufficientCreditsError as I, ListeningAlreadyActiveError as L, NetworkTimeoutError as N, PermanentError as P, RateLimitError as R, SynapError as S, TranscriptConflictError as T, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, AgentUnavailableError as c, type AnticipationCacheOptions as d, AuthenticationError as e, ConnectionError as f, type ContextBundle as g, ContextNotFoundError as h, CustomerIdNotAcceptedError as i, type ExitReason as j, InvalidConversationIdError as k, InvalidInputError as l, InvalidInstanceIdError as m, ListeningNotActiveError as n, type LookupParams as o, type LookupResult as p, type LookupTelemetry as q, SDKError as r, ServiceUnavailableError as s, SessionExpiredError as t, type SnapshotBundle as u, type SnapshotItemPreview as v, type SnapshotItemRecord as w, type SynapErrorCode as x, type SynapErrorOptions as y, SynapPermanentError as z };
538
+ export { AnticipationCache as A, type BundleItem as B, ConflictError as C, type SynapErrorOptions as D, type Encoder as E, SynapPermanentError as F, SynapTransientError as G, TransientError as H, InstanceBuildFailedError as I, isSynapError as J, ListeningAlreadyActiveError as L, NetworkTimeoutError as N, PermanentError as P, RateLimitError as R, SynapError as S, TranscriptConflictError as T, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, AgentUnavailableError as c, type AnticipationCacheOptions as d, AuthenticationError as e, ConnectionError as f, type ContextBundle as g, ContextNotFoundError as h, CustomerIdNotAcceptedError as i, type ExitReason as j, InstanceNotReadyError as k, InsufficientCreditsError as l, InvalidConversationIdError as m, InvalidInputError as n, InvalidInstanceIdError as o, ListeningNotActiveError as p, type LookupParams as q, type LookupResult as r, type LookupTelemetry as s, SDKError as t, ServiceUnavailableError as u, SessionExpiredError as v, type SnapshotBundle as w, type SnapshotItemPreview as x, type SnapshotItemRecord as y, type SynapErrorCode as z };
@@ -1,10 +1,10 @@
1
1
  "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
2
2
 
3
3
 
4
- var _chunkCBK3H2LUcjs = require('../chunk-CBK3H2LU.cjs');
4
+ var _chunk2VJV4HCFcjs = require('../chunk-2VJV4HCF.cjs');
5
5
 
6
6
 
7
- var _chunkUXNVTP4Dcjs = require('../chunk-UXNVTP4D.cjs');
7
+ var _chunk7IZHVYO2cjs = require('../chunk-7IZHVYO2.cjs');
8
8
 
9
9
  // src/grpc/index.ts
10
10
  async function checkGrpcAvailability() {
@@ -32,20 +32,20 @@ async function checkGrpcAvailability() {
32
32
  }
33
33
  async function listen(options) {
34
34
  if (!options.conversationId) {
35
- throw new (0, _chunkUXNVTP4Dcjs.ListeningNotActiveError)("conversation_id is required to start a listening stream");
35
+ throw new (0, _chunk7IZHVYO2cjs.ListeningNotActiveError)("conversation_id is required to start a listening stream");
36
36
  }
37
37
  const availability = await checkGrpcAvailability();
38
38
  if (!availability.available) {
39
- throw new (0, _chunkUXNVTP4Dcjs.ListeningNotActiveError)(availability.detail);
39
+ throw new (0, _chunk7IZHVYO2cjs.ListeningNotActiveError)(availability.detail);
40
40
  }
41
41
  const [{ GrpcStreamClient: StreamClient }, { AnticipationCache }, { getEnv }] = await Promise.all([
42
- Promise.resolve().then(() => _interopRequireWildcard(require("../stream-client-FKKCBVCB.cjs"))),
42
+ Promise.resolve().then(() => _interopRequireWildcard(require("../stream-client-SZIYGVVJ.cjs"))),
43
43
  Promise.resolve().then(() => _interopRequireWildcard(require("../anticipation-cache-LPNKMRBH.cjs"))),
44
44
  Promise.resolve().then(() => _interopRequireWildcard(require("../env-55ULHNJZ.cjs")))
45
45
  ]);
46
46
  const apiKey = _nullishCoalesce(_nullishCoalesce(options.apiKey, () => ( getEnv("SYNAP_API_KEY"))), () => ( ""));
47
47
  if (apiKey === "") {
48
- throw new (0, _chunkUXNVTP4Dcjs.ListeningNotActiveError)(
48
+ throw new (0, _chunk7IZHVYO2cjs.ListeningNotActiveError)(
49
49
  "No Synap API key found. Set SYNAP_API_KEY or pass apiKey."
50
50
  );
51
51
  }
@@ -83,5 +83,5 @@ async function listen(options) {
83
83
 
84
84
 
85
85
 
86
- exports.GrpcStreamClient = _chunkCBK3H2LUcjs.GrpcStreamClient; exports.PROTO_SHA = _chunkCBK3H2LUcjs.PROTO_SHA; exports.checkGrpcAvailability = checkGrpcAvailability; exports.listen = listen;
86
+ exports.GrpcStreamClient = _chunk2VJV4HCFcjs.GrpcStreamClient; exports.PROTO_SHA = _chunk2VJV4HCFcjs.PROTO_SHA; exports.checkGrpcAvailability = checkGrpcAvailability; exports.listen = listen;
87
87
  //# sourceMappingURL=index.cjs.map
@@ -1,4 +1,4 @@
1
- import { A as AnticipationCache, S as SynapError } from '../errors-BvUA5EW8.cjs';
1
+ import { A as AnticipationCache, S as SynapError } from '../errors-DWjdpExq.cjs';
2
2
 
3
3
  /**
4
4
  * Bidirectional gRPC stream client for the Synap anticipation channel.
@@ -18,6 +18,18 @@ import { A as AnticipationCache, S as SynapError } from '../errors-BvUA5EW8.cjs'
18
18
  */
19
19
 
20
20
  type StreamState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
21
+ /** What the server said when it refused events for an unfinished build. */
22
+ interface InstanceNotReadyInfo {
23
+ retryAfterSeconds: number;
24
+ instanceId: string;
25
+ state: string;
26
+ message: string;
27
+ /** `instance_not_ready` (building) or `instance_build_failed`. */
28
+ code: string;
29
+ /** Recovery instruction from the server; only set for `instance_build_failed`. */
30
+ hint?: string;
31
+ attempts?: string;
32
+ }
21
33
  interface StreamCredentials {
22
34
  apiKey: string;
23
35
  clientId: string;
@@ -99,6 +111,15 @@ declare class GrpcStreamClient {
99
111
  * ordinary disconnect.
100
112
  */
101
113
  get lastError(): SynapError | null;
114
+ /**
115
+ * Why the server is refusing events right now, or null.
116
+ *
117
+ * Set from the moment the server answers an event with an
118
+ * `instance_not_ready` throttle until a replay of the held events is
119
+ * accepted. The events are held, not dropped. Mirrors Python's
120
+ * `GRPCTransport.instance_not_ready`.
121
+ */
122
+ get instanceNotReady(): InstanceNotReadyInfo | null;
102
123
  connect(): Promise<void>;
103
124
  disconnect(): Promise<void>;
104
125
  /**
@@ -1,4 +1,4 @@
1
- import { A as AnticipationCache, S as SynapError } from '../errors-BvUA5EW8.js';
1
+ import { A as AnticipationCache, S as SynapError } from '../errors-DWjdpExq.js';
2
2
 
3
3
  /**
4
4
  * Bidirectional gRPC stream client for the Synap anticipation channel.
@@ -18,6 +18,18 @@ import { A as AnticipationCache, S as SynapError } from '../errors-BvUA5EW8.js';
18
18
  */
19
19
 
20
20
  type StreamState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
21
+ /** What the server said when it refused events for an unfinished build. */
22
+ interface InstanceNotReadyInfo {
23
+ retryAfterSeconds: number;
24
+ instanceId: string;
25
+ state: string;
26
+ message: string;
27
+ /** `instance_not_ready` (building) or `instance_build_failed`. */
28
+ code: string;
29
+ /** Recovery instruction from the server; only set for `instance_build_failed`. */
30
+ hint?: string;
31
+ attempts?: string;
32
+ }
21
33
  interface StreamCredentials {
22
34
  apiKey: string;
23
35
  clientId: string;
@@ -99,6 +111,15 @@ declare class GrpcStreamClient {
99
111
  * ordinary disconnect.
100
112
  */
101
113
  get lastError(): SynapError | null;
114
+ /**
115
+ * Why the server is refusing events right now, or null.
116
+ *
117
+ * Set from the moment the server answers an event with an
118
+ * `instance_not_ready` throttle until a replay of the held events is
119
+ * accepted. The events are held, not dropped. Mirrors Python's
120
+ * `GRPCTransport.instance_not_ready`.
121
+ */
122
+ get instanceNotReady(): InstanceNotReadyInfo | null;
102
123
  connect(): Promise<void>;
103
124
  disconnect(): Promise<void>;
104
125
  /**
@@ -1,10 +1,10 @@
1
1
  import {
2
2
  GrpcStreamClient,
3
3
  PROTO_SHA
4
- } from "../chunk-5G3FNDB3.js";
4
+ } from "../chunk-N55UBGER.js";
5
5
  import {
6
6
  ListeningNotActiveError
7
- } from "../chunk-4GE7SORD.js";
7
+ } from "../chunk-DEFC7NHQ.js";
8
8
 
9
9
  // src/grpc/index.ts
10
10
  async function checkGrpcAvailability() {
@@ -39,7 +39,7 @@ async function listen(options) {
39
39
  throw new ListeningNotActiveError(availability.detail);
40
40
  }
41
41
  const [{ GrpcStreamClient: StreamClient }, { AnticipationCache }, { getEnv }] = await Promise.all([
42
- import("../stream-client-2UMDGCMQ.js"),
42
+ import("../stream-client-GRDVRBFA.js"),
43
43
  import("../anticipation-cache-RWKF55J4.js"),
44
44
  import("../env-QCUKKW36.js")
45
45
  ]);