@maximem/synap-js-sdk 0.6.5 → 0.6.7

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/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { E as Encoder, a as AnticipationCacheSnapshot } from './errors-x5bpgxmC.cjs';
2
- export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as CustomerIdNotAcceptedError, j as ExitReason, I as InstanceBuildFailedError, k as InstanceNotReadyError, l as InsufficientCreditsError, m as InvalidConversationIdError, n as InvalidInputError, o as InvalidInstanceIdError, L as ListeningAlreadyActiveError, p as ListeningNotActiveError, q as LookupParams, r as LookupResult, s as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, t as SDKError, u as ServiceUnavailableError, v as SessionExpiredError, w as SnapshotBundle, x as SnapshotItemPreview, y as SnapshotItemRecord, S as SynapError, z as SynapErrorCode, D as SynapErrorOptions, F as SynapPermanentError, G as SynapTransientError, T as TranscriptConflictError, H as TransientError, J as isSynapError } from './errors-x5bpgxmC.cjs';
1
+ import { S as SynapError, E as Encoder, a as AnticipationCacheSnapshot } from './errors-x5bpgxmC.cjs';
2
+ export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as CustomerIdNotAcceptedError, j as ExitReason, I as InstanceBuildFailedError, k as InstanceNotReadyError, l as InsufficientCreditsError, m as InvalidConversationIdError, n as InvalidInputError, o as InvalidInstanceIdError, L as ListeningAlreadyActiveError, p as ListeningNotActiveError, q as LookupParams, r as LookupResult, s as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, t as SDKError, u as ServiceUnavailableError, v as SessionExpiredError, w as SnapshotBundle, x as SnapshotItemPreview, y as SnapshotItemRecord, z as SynapErrorCode, D as SynapErrorOptions, F as SynapPermanentError, G as SynapTransientError, T as TranscriptConflictError, H as TransientError, J as isSynapError } from './errors-x5bpgxmC.cjs';
3
3
 
4
4
  /**
5
5
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -40,6 +40,11 @@ declare const ENDPOINTS: {
40
40
  readonly path: "/api/v1/memories/upload";
41
41
  readonly idempotent: false;
42
42
  };
43
+ readonly memories_create_multipart: {
44
+ readonly method: "POST";
45
+ readonly path: "/api/v1/memories/create-multipart";
46
+ readonly idempotent: false;
47
+ };
43
48
  readonly memories_status: {
44
49
  readonly method: "GET";
45
50
  readonly path: "/api/v1/memories/status/{ingestion_id}";
@@ -300,6 +305,12 @@ interface RequestOptions {
300
305
  correlationId?: string;
301
306
  /** Overrides the endpoint's declared idempotency. */
302
307
  idempotent?: boolean;
308
+ /**
309
+ * Re-map an HTTP error for this one call, given the status. Returns the
310
+ * error to throw instead, or undefined to keep it. Applied before the retry
311
+ * decision, so the retry policy sees what the caller will.
312
+ */
313
+ mapError?: (status: number, error: SynapError) => SynapError | undefined;
303
314
  signal?: AbortSignal;
304
315
  }
305
316
  declare class HttpTransport {
@@ -315,6 +326,14 @@ declare class HttpTransport {
315
326
  private readonly clock;
316
327
  private readonly notReadyCooldown;
317
328
  constructor(options: HttpTransportOptions);
329
+ /**
330
+ * @internal Fetch a URL that is not Synap's, with this transport's fetch.
331
+ *
332
+ * Used to read a `FilePart` given by `url`: the SDK fetches it, the server
333
+ * never does. Deliberately sends none of this transport's headers, because
334
+ * the URL belongs to somebody else and the API key must not reach them.
335
+ */
336
+ fetchExternal(url: string, init?: RequestInit): Promise<Response>;
318
337
  /** Start keeping the connection warm. Opt-in: it is pointless in serverless. */
319
338
  startHeartbeat(): void;
320
339
  /**
@@ -737,6 +756,87 @@ interface FlatMemory {
737
756
  }
738
757
  declare function flattenContextItems(context: RawContext): FlatMemory[];
739
758
 
759
+ /**
760
+ * Content parts: text and files (today, images) carried by `memories.create`,
761
+ * `conversation.record_message` and `instance.send_message`.
762
+ *
763
+ * Mirrors `TextPart`, `FilePart` and `AttachmentResult` in the Python SDK.
764
+ *
765
+ * ## A text-only list is a string
766
+ *
767
+ * Every existing call has to keep sending exactly the bytes it sends today, so
768
+ * a list with no file in it is joined with `"\n"` and sent as that one string,
769
+ * down the same route a string always took. Only a file changes the shape of a
770
+ * request.
771
+ *
772
+ * ## Runs everywhere
773
+ *
774
+ * Nothing here imports a node builtin at the top level. Reading a `path` uses a
775
+ * lazy `import('node:fs/promises')`, the same as `create_from_file`, and base64
776
+ * uses `Buffer` when the runtime has it and `btoa` when it does not, so the main
777
+ * entry stays safe on Edge, Workers and in a browser.
778
+ */
779
+ /**
780
+ * What the caller is asking a memory to do. Stored with the ingestion as
781
+ * metadata; any other string is accepted too. Mirrors Python's `OBJECTIVES`.
782
+ */
783
+ declare const OBJECTIVES: readonly ["conversation", "bootstrap", "knowledge-base", "record", "profile"];
784
+ type Objective = (typeof OBJECTIVES)[number];
785
+ /** Raw bytes for a `FilePart`. A Node `Buffer` is a `Uint8Array`. */
786
+ type FileData = Uint8Array | ArrayBuffer | Blob;
787
+ interface TextPart {
788
+ type: 'text';
789
+ text: string;
790
+ }
791
+ /**
792
+ * A file. Exactly one of `data`, `path` or `url`.
793
+ *
794
+ * Build one with `filePart()`, which fills `filename` and `media_type`. A
795
+ * literal `{ type: 'file', ... }` works too; the same defaults are applied when
796
+ * it is sent.
797
+ */
798
+ interface FilePart {
799
+ type: 'file';
800
+ data?: FileData;
801
+ /** Node only: read from disk when the call is made. */
802
+ path?: string;
803
+ /** Fetched by the SDK when the call is made (30 s, at most 10 MB). */
804
+ url?: string;
805
+ /** Defaults to the basename of `path` or `url`, else `"file"`. */
806
+ filename?: string;
807
+ /** Defaults to a guess from `filename`, else `"application/octet-stream"`. */
808
+ media_type?: string;
809
+ }
810
+ interface FilePartInit {
811
+ data?: FileData | null;
812
+ path?: string | null;
813
+ url?: string | null;
814
+ filename?: string | null;
815
+ media_type?: string | null;
816
+ mediaType?: string | null;
817
+ }
818
+ /** One item of a content list. A bare string is a text part. */
819
+ type ContentPart = string | TextPart | FilePart;
820
+ /**
821
+ * What the server did with one file of a `memories.create` call, in the order
822
+ * the files were sent. Mirrors Python's `AttachmentResult`.
823
+ */
824
+ interface AttachmentResult {
825
+ filename: string;
826
+ media_type: string;
827
+ status: 'read' | 'failed' | string;
828
+ error?: string | null;
829
+ }
830
+ /** `{ type: 'text', text }`. Mirrors Python's `TextPart(text)`. */
831
+ declare function textPart(text: string): TextPart;
832
+ /**
833
+ * A file part with its defaults filled in. Mirrors Python's `FilePart(...)`.
834
+ *
835
+ * Throws `InvalidInputError` unless exactly one of `data`, `path` or `url` is
836
+ * given.
837
+ */
838
+ declare function filePart(init: FilePartInit): FilePart;
839
+
740
840
  /**
741
841
  * Memories namespace. Mirrors `maximem_synap.memories.interface.MemoriesInterface`.
742
842
  *
@@ -764,8 +864,17 @@ declare const INGEST_MODES: readonly ["fast", "long-range"];
764
864
  type IngestMode = (typeof INGEST_MODES)[number];
765
865
  declare const DEFAULT_DOCUMENT_TYPE: DocumentType;
766
866
  declare const DEFAULT_INGEST_MODE: IngestMode;
867
+ /**
868
+ * What `memories.create` takes as `document`. Mirrors Python's
869
+ * `Union[str, Dict[str, Any], TextPart, FilePart, List[Union[str, TextPart, FilePart]]]`.
870
+ *
871
+ * A string, a dict, a `TextPart` or a list with no file in it is sent as JSON
872
+ * to `/create`, byte for byte as a string always was (a list is joined with
873
+ * `"\n"`). Any `FilePart` sends the call as multipart to `/create-multipart`.
874
+ */
875
+ type CreateDocument = string | Record<string, unknown> | TextPart | FilePart | Array<string | TextPart | FilePart>;
767
876
  interface CreateMemoryOptions {
768
- document: string;
877
+ document: CreateDocument;
769
878
  user_id?: string | null;
770
879
  userId?: string | null;
771
880
  customer_id?: string | null;
@@ -794,6 +903,12 @@ interface CreateMemoryOptions {
794
903
  * narrowed and is ignored gets widened instead.
795
904
  */
796
905
  scope?: Record<string, string> | null;
906
+ /**
907
+ * What this memory is for. One of `OBJECTIVES` (`conversation`, `bootstrap`,
908
+ * `knowledge-base`, `record`, `profile`) or free text, at most 500
909
+ * characters. Sent only when set, so a call without it is unchanged.
910
+ */
911
+ objective?: Objective | string | null;
797
912
  }
798
913
  /**
799
914
  * Mirrors Python's `CreateMemoryResponse`.
@@ -812,6 +927,12 @@ interface CreateMemoryResult {
812
927
  queued_at: string;
813
928
  error_message?: string | null;
814
929
  memories_created?: number;
930
+ /**
931
+ * One per file part, in order, when the call carried files. Absent
932
+ * otherwise. A file that could not be read is still `failed` here while the
933
+ * rest of the document was ingested.
934
+ */
935
+ attachments?: AttachmentResult[] | null;
815
936
  [key: string]: unknown;
816
937
  }
817
938
  /**
@@ -849,6 +970,19 @@ interface ForgetOptions {
849
970
  scope?: Record<string, string> | null;
850
971
  /** `"preview"` (default) or `"direct"`. See `MemoriesInterface.forget`. */
851
972
  mode?: ForgetMode | string;
973
+ /**
974
+ * The conversation this request is made in (1 to 200 characters). Used only
975
+ * by `mode: "direct"`. Pass it when you record the conversation through the
976
+ * SDK's listening stream (gRPC): messages on that path are saved in batches,
977
+ * so what the user just said may not exist as a memory yet. With the id, the
978
+ * request also stays open until the batch of that conversation that holds it
979
+ * has been saved and checked, whether or not the search finds something now,
980
+ * and removes what it describes then (`retry_scheduled` is true). Without it,
981
+ * the request is answered once (`nothing_matches` if nothing is found) and
982
+ * nothing waits. Not needed for `memories.create()`.
983
+ */
984
+ conversation_id?: string | null;
985
+ conversationId?: string | null;
852
986
  }
853
987
  /** A memory the description matched. Mirrors Python's `ForgetCandidate`. */
854
988
  interface ForgetCandidate {
@@ -868,6 +1002,13 @@ interface ForgetResult {
868
1002
  failed_ids: string[];
869
1003
  still_present_in: string[];
870
1004
  may_be_incomplete: boolean;
1005
+ /**
1006
+ * True when a `direct` request named its `conversation_id` and stays open until
1007
+ * the batch of that conversation that holds it has been saved and checked,
1008
+ * whether or not the search found something now. Absent from servers that
1009
+ * predate it; read it as false.
1010
+ */
1011
+ retry_scheduled?: boolean;
871
1012
  }
872
1013
  interface MemoriesInterface {
873
1014
  create(options: CreateMemoryOptions): Promise<CreateMemoryResult>;
@@ -990,7 +1131,13 @@ interface RecordMessageOptions {
990
1131
  conversation_id?: string;
991
1132
  conversationId?: string;
992
1133
  role: string;
993
- content: string;
1134
+ /**
1135
+ * The message. A string, or a list of strings, `TextPart`s and `FilePart`s
1136
+ * (images today). A list with no file is joined with `"\n"` and sent as that
1137
+ * string. With a file, the parts are sent in order with each file inline as
1138
+ * base64; the server reads the images and stores the message as text.
1139
+ */
1140
+ content: string | ContentPart[];
994
1141
  user_id?: string;
995
1142
  userId?: string;
996
1143
  customer_id?: string;
@@ -1364,7 +1511,14 @@ interface ListenOptions {
1364
1511
  useTls?: boolean;
1365
1512
  }
1366
1513
  interface SendMessageOptions {
1367
- content: string;
1514
+ /**
1515
+ * A string, or a list of strings, `TextPart`s and `FilePart`s (images). A
1516
+ * list with no file is joined with `"\n"`. With a file, the parts go in
1517
+ * `metadata.synap_content_parts` (images inline as base64, at most 2.5 MB of
1518
+ * raw image bytes per event) and `content` becomes the placeholder text,
1519
+ * each image as `[image: <filename>]`.
1520
+ */
1521
+ content: string | ContentPart[];
1368
1522
  role?: string;
1369
1523
  conversation_id?: string;
1370
1524
  conversationId?: string;
@@ -1490,6 +1644,8 @@ interface InstanceInternals {
1490
1644
  * bundles begin to arrive, so the local embedding model loads then.
1491
1645
  */
1492
1646
  setOnListen(handle: () => void): void;
1647
+ /** Set by the client in local mode: `listen()` then throws this message instead of opening a stream. */
1648
+ blockListen(message: string): void;
1493
1649
  /**
1494
1650
  * Set by the client. Receives the server's message count for a conversation
1495
1651
  * after each streamed write has been stored.
@@ -1988,7 +2144,7 @@ declare class SynapClient {
1988
2144
  * build when the two disagree, which is the only thing that makes a manual
1989
2145
  * publish safe.
1990
2146
  */
1991
- declare const SDK_VERSION = "0.6.5";
2147
+ declare const SDK_VERSION = "0.6.7";
1992
2148
 
1993
2149
  /**
1994
2150
  * `response_shape: "ranked"`: one list in the order the server ranked it.
@@ -2229,4 +2385,4 @@ interface SynapSdkLike {
2229
2385
  };
2230
2386
  }
2231
2387
 
2232
- export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContextMetadata, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DATA_SCOPES, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DataInterface, type DataScope, type DeleteDataOptions, type DeleteDataResult, type DocumentType, ENDPOINTS, EXCERPT_CATEGORY, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, FORGET_MODES, type Fact, type FetchOptions, type FlatMemory, type ForgetCandidate, type ForgetMode, type ForgetOptions, type ForgetResult, type ForgetStatus, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, MEMORY_TYPES, type MemoriesInterface, type NormalisedContext, type OpenAiToolDefinition, type Preference, RESPONSE_SHAPES, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type ResponseShape, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, applyResponseShape, flattenContextItems, formatForPrompt, isOutcomeUnknown, mergeScopeResults, rankItems, resolvePath, shouldRetry, stem, tokenize, wireRankScore };
2388
+ export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, type AttachmentResult, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContentPart, type ContextMetadata, type ConversationContext, type ConversationNamespace, type CreateDocument, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DATA_SCOPES, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DataInterface, type DataScope, type DeleteDataOptions, type DeleteDataResult, type DocumentType, ENDPOINTS, EXCERPT_CATEGORY, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, FORGET_MODES, type Fact, type FetchOptions, type FileData, type FilePart, type FilePartInit, type FlatMemory, type ForgetCandidate, type ForgetMode, type ForgetOptions, type ForgetResult, type ForgetStatus, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, MEMORY_TYPES, type MemoriesInterface, type NormalisedContext, OBJECTIVES, type Objective, type OpenAiToolDefinition, type Preference, RESPONSE_SHAPES, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type ResponseShape, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, SynapError, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TextPart, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, applyResponseShape, filePart, flattenContextItems, formatForPrompt, isOutcomeUnknown, mergeScopeResults, rankItems, resolvePath, shouldRetry, stem, textPart, tokenize, wireRankScore };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { E as Encoder, a as AnticipationCacheSnapshot } from './errors-x5bpgxmC.js';
2
- export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as CustomerIdNotAcceptedError, j as ExitReason, I as InstanceBuildFailedError, k as InstanceNotReadyError, l as InsufficientCreditsError, m as InvalidConversationIdError, n as InvalidInputError, o as InvalidInstanceIdError, L as ListeningAlreadyActiveError, p as ListeningNotActiveError, q as LookupParams, r as LookupResult, s as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, t as SDKError, u as ServiceUnavailableError, v as SessionExpiredError, w as SnapshotBundle, x as SnapshotItemPreview, y as SnapshotItemRecord, S as SynapError, z as SynapErrorCode, D as SynapErrorOptions, F as SynapPermanentError, G as SynapTransientError, T as TranscriptConflictError, H as TransientError, J as isSynapError } from './errors-x5bpgxmC.js';
1
+ import { S as SynapError, E as Encoder, a as AnticipationCacheSnapshot } from './errors-x5bpgxmC.js';
2
+ export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as CustomerIdNotAcceptedError, j as ExitReason, I as InstanceBuildFailedError, k as InstanceNotReadyError, l as InsufficientCreditsError, m as InvalidConversationIdError, n as InvalidInputError, o as InvalidInstanceIdError, L as ListeningAlreadyActiveError, p as ListeningNotActiveError, q as LookupParams, r as LookupResult, s as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, t as SDKError, u as ServiceUnavailableError, v as SessionExpiredError, w as SnapshotBundle, x as SnapshotItemPreview, y as SnapshotItemRecord, z as SynapErrorCode, D as SynapErrorOptions, F as SynapPermanentError, G as SynapTransientError, T as TranscriptConflictError, H as TransientError, J as isSynapError } from './errors-x5bpgxmC.js';
3
3
 
4
4
  /**
5
5
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -40,6 +40,11 @@ declare const ENDPOINTS: {
40
40
  readonly path: "/api/v1/memories/upload";
41
41
  readonly idempotent: false;
42
42
  };
43
+ readonly memories_create_multipart: {
44
+ readonly method: "POST";
45
+ readonly path: "/api/v1/memories/create-multipart";
46
+ readonly idempotent: false;
47
+ };
43
48
  readonly memories_status: {
44
49
  readonly method: "GET";
45
50
  readonly path: "/api/v1/memories/status/{ingestion_id}";
@@ -300,6 +305,12 @@ interface RequestOptions {
300
305
  correlationId?: string;
301
306
  /** Overrides the endpoint's declared idempotency. */
302
307
  idempotent?: boolean;
308
+ /**
309
+ * Re-map an HTTP error for this one call, given the status. Returns the
310
+ * error to throw instead, or undefined to keep it. Applied before the retry
311
+ * decision, so the retry policy sees what the caller will.
312
+ */
313
+ mapError?: (status: number, error: SynapError) => SynapError | undefined;
303
314
  signal?: AbortSignal;
304
315
  }
305
316
  declare class HttpTransport {
@@ -315,6 +326,14 @@ declare class HttpTransport {
315
326
  private readonly clock;
316
327
  private readonly notReadyCooldown;
317
328
  constructor(options: HttpTransportOptions);
329
+ /**
330
+ * @internal Fetch a URL that is not Synap's, with this transport's fetch.
331
+ *
332
+ * Used to read a `FilePart` given by `url`: the SDK fetches it, the server
333
+ * never does. Deliberately sends none of this transport's headers, because
334
+ * the URL belongs to somebody else and the API key must not reach them.
335
+ */
336
+ fetchExternal(url: string, init?: RequestInit): Promise<Response>;
318
337
  /** Start keeping the connection warm. Opt-in: it is pointless in serverless. */
319
338
  startHeartbeat(): void;
320
339
  /**
@@ -737,6 +756,87 @@ interface FlatMemory {
737
756
  }
738
757
  declare function flattenContextItems(context: RawContext): FlatMemory[];
739
758
 
759
+ /**
760
+ * Content parts: text and files (today, images) carried by `memories.create`,
761
+ * `conversation.record_message` and `instance.send_message`.
762
+ *
763
+ * Mirrors `TextPart`, `FilePart` and `AttachmentResult` in the Python SDK.
764
+ *
765
+ * ## A text-only list is a string
766
+ *
767
+ * Every existing call has to keep sending exactly the bytes it sends today, so
768
+ * a list with no file in it is joined with `"\n"` and sent as that one string,
769
+ * down the same route a string always took. Only a file changes the shape of a
770
+ * request.
771
+ *
772
+ * ## Runs everywhere
773
+ *
774
+ * Nothing here imports a node builtin at the top level. Reading a `path` uses a
775
+ * lazy `import('node:fs/promises')`, the same as `create_from_file`, and base64
776
+ * uses `Buffer` when the runtime has it and `btoa` when it does not, so the main
777
+ * entry stays safe on Edge, Workers and in a browser.
778
+ */
779
+ /**
780
+ * What the caller is asking a memory to do. Stored with the ingestion as
781
+ * metadata; any other string is accepted too. Mirrors Python's `OBJECTIVES`.
782
+ */
783
+ declare const OBJECTIVES: readonly ["conversation", "bootstrap", "knowledge-base", "record", "profile"];
784
+ type Objective = (typeof OBJECTIVES)[number];
785
+ /** Raw bytes for a `FilePart`. A Node `Buffer` is a `Uint8Array`. */
786
+ type FileData = Uint8Array | ArrayBuffer | Blob;
787
+ interface TextPart {
788
+ type: 'text';
789
+ text: string;
790
+ }
791
+ /**
792
+ * A file. Exactly one of `data`, `path` or `url`.
793
+ *
794
+ * Build one with `filePart()`, which fills `filename` and `media_type`. A
795
+ * literal `{ type: 'file', ... }` works too; the same defaults are applied when
796
+ * it is sent.
797
+ */
798
+ interface FilePart {
799
+ type: 'file';
800
+ data?: FileData;
801
+ /** Node only: read from disk when the call is made. */
802
+ path?: string;
803
+ /** Fetched by the SDK when the call is made (30 s, at most 10 MB). */
804
+ url?: string;
805
+ /** Defaults to the basename of `path` or `url`, else `"file"`. */
806
+ filename?: string;
807
+ /** Defaults to a guess from `filename`, else `"application/octet-stream"`. */
808
+ media_type?: string;
809
+ }
810
+ interface FilePartInit {
811
+ data?: FileData | null;
812
+ path?: string | null;
813
+ url?: string | null;
814
+ filename?: string | null;
815
+ media_type?: string | null;
816
+ mediaType?: string | null;
817
+ }
818
+ /** One item of a content list. A bare string is a text part. */
819
+ type ContentPart = string | TextPart | FilePart;
820
+ /**
821
+ * What the server did with one file of a `memories.create` call, in the order
822
+ * the files were sent. Mirrors Python's `AttachmentResult`.
823
+ */
824
+ interface AttachmentResult {
825
+ filename: string;
826
+ media_type: string;
827
+ status: 'read' | 'failed' | string;
828
+ error?: string | null;
829
+ }
830
+ /** `{ type: 'text', text }`. Mirrors Python's `TextPart(text)`. */
831
+ declare function textPart(text: string): TextPart;
832
+ /**
833
+ * A file part with its defaults filled in. Mirrors Python's `FilePart(...)`.
834
+ *
835
+ * Throws `InvalidInputError` unless exactly one of `data`, `path` or `url` is
836
+ * given.
837
+ */
838
+ declare function filePart(init: FilePartInit): FilePart;
839
+
740
840
  /**
741
841
  * Memories namespace. Mirrors `maximem_synap.memories.interface.MemoriesInterface`.
742
842
  *
@@ -764,8 +864,17 @@ declare const INGEST_MODES: readonly ["fast", "long-range"];
764
864
  type IngestMode = (typeof INGEST_MODES)[number];
765
865
  declare const DEFAULT_DOCUMENT_TYPE: DocumentType;
766
866
  declare const DEFAULT_INGEST_MODE: IngestMode;
867
+ /**
868
+ * What `memories.create` takes as `document`. Mirrors Python's
869
+ * `Union[str, Dict[str, Any], TextPart, FilePart, List[Union[str, TextPart, FilePart]]]`.
870
+ *
871
+ * A string, a dict, a `TextPart` or a list with no file in it is sent as JSON
872
+ * to `/create`, byte for byte as a string always was (a list is joined with
873
+ * `"\n"`). Any `FilePart` sends the call as multipart to `/create-multipart`.
874
+ */
875
+ type CreateDocument = string | Record<string, unknown> | TextPart | FilePart | Array<string | TextPart | FilePart>;
767
876
  interface CreateMemoryOptions {
768
- document: string;
877
+ document: CreateDocument;
769
878
  user_id?: string | null;
770
879
  userId?: string | null;
771
880
  customer_id?: string | null;
@@ -794,6 +903,12 @@ interface CreateMemoryOptions {
794
903
  * narrowed and is ignored gets widened instead.
795
904
  */
796
905
  scope?: Record<string, string> | null;
906
+ /**
907
+ * What this memory is for. One of `OBJECTIVES` (`conversation`, `bootstrap`,
908
+ * `knowledge-base`, `record`, `profile`) or free text, at most 500
909
+ * characters. Sent only when set, so a call without it is unchanged.
910
+ */
911
+ objective?: Objective | string | null;
797
912
  }
798
913
  /**
799
914
  * Mirrors Python's `CreateMemoryResponse`.
@@ -812,6 +927,12 @@ interface CreateMemoryResult {
812
927
  queued_at: string;
813
928
  error_message?: string | null;
814
929
  memories_created?: number;
930
+ /**
931
+ * One per file part, in order, when the call carried files. Absent
932
+ * otherwise. A file that could not be read is still `failed` here while the
933
+ * rest of the document was ingested.
934
+ */
935
+ attachments?: AttachmentResult[] | null;
815
936
  [key: string]: unknown;
816
937
  }
817
938
  /**
@@ -849,6 +970,19 @@ interface ForgetOptions {
849
970
  scope?: Record<string, string> | null;
850
971
  /** `"preview"` (default) or `"direct"`. See `MemoriesInterface.forget`. */
851
972
  mode?: ForgetMode | string;
973
+ /**
974
+ * The conversation this request is made in (1 to 200 characters). Used only
975
+ * by `mode: "direct"`. Pass it when you record the conversation through the
976
+ * SDK's listening stream (gRPC): messages on that path are saved in batches,
977
+ * so what the user just said may not exist as a memory yet. With the id, the
978
+ * request also stays open until the batch of that conversation that holds it
979
+ * has been saved and checked, whether or not the search finds something now,
980
+ * and removes what it describes then (`retry_scheduled` is true). Without it,
981
+ * the request is answered once (`nothing_matches` if nothing is found) and
982
+ * nothing waits. Not needed for `memories.create()`.
983
+ */
984
+ conversation_id?: string | null;
985
+ conversationId?: string | null;
852
986
  }
853
987
  /** A memory the description matched. Mirrors Python's `ForgetCandidate`. */
854
988
  interface ForgetCandidate {
@@ -868,6 +1002,13 @@ interface ForgetResult {
868
1002
  failed_ids: string[];
869
1003
  still_present_in: string[];
870
1004
  may_be_incomplete: boolean;
1005
+ /**
1006
+ * True when a `direct` request named its `conversation_id` and stays open until
1007
+ * the batch of that conversation that holds it has been saved and checked,
1008
+ * whether or not the search found something now. Absent from servers that
1009
+ * predate it; read it as false.
1010
+ */
1011
+ retry_scheduled?: boolean;
871
1012
  }
872
1013
  interface MemoriesInterface {
873
1014
  create(options: CreateMemoryOptions): Promise<CreateMemoryResult>;
@@ -990,7 +1131,13 @@ interface RecordMessageOptions {
990
1131
  conversation_id?: string;
991
1132
  conversationId?: string;
992
1133
  role: string;
993
- content: string;
1134
+ /**
1135
+ * The message. A string, or a list of strings, `TextPart`s and `FilePart`s
1136
+ * (images today). A list with no file is joined with `"\n"` and sent as that
1137
+ * string. With a file, the parts are sent in order with each file inline as
1138
+ * base64; the server reads the images and stores the message as text.
1139
+ */
1140
+ content: string | ContentPart[];
994
1141
  user_id?: string;
995
1142
  userId?: string;
996
1143
  customer_id?: string;
@@ -1364,7 +1511,14 @@ interface ListenOptions {
1364
1511
  useTls?: boolean;
1365
1512
  }
1366
1513
  interface SendMessageOptions {
1367
- content: string;
1514
+ /**
1515
+ * A string, or a list of strings, `TextPart`s and `FilePart`s (images). A
1516
+ * list with no file is joined with `"\n"`. With a file, the parts go in
1517
+ * `metadata.synap_content_parts` (images inline as base64, at most 2.5 MB of
1518
+ * raw image bytes per event) and `content` becomes the placeholder text,
1519
+ * each image as `[image: <filename>]`.
1520
+ */
1521
+ content: string | ContentPart[];
1368
1522
  role?: string;
1369
1523
  conversation_id?: string;
1370
1524
  conversationId?: string;
@@ -1490,6 +1644,8 @@ interface InstanceInternals {
1490
1644
  * bundles begin to arrive, so the local embedding model loads then.
1491
1645
  */
1492
1646
  setOnListen(handle: () => void): void;
1647
+ /** Set by the client in local mode: `listen()` then throws this message instead of opening a stream. */
1648
+ blockListen(message: string): void;
1493
1649
  /**
1494
1650
  * Set by the client. Receives the server's message count for a conversation
1495
1651
  * after each streamed write has been stored.
@@ -1988,7 +2144,7 @@ declare class SynapClient {
1988
2144
  * build when the two disagree, which is the only thing that makes a manual
1989
2145
  * publish safe.
1990
2146
  */
1991
- declare const SDK_VERSION = "0.6.5";
2147
+ declare const SDK_VERSION = "0.6.7";
1992
2148
 
1993
2149
  /**
1994
2150
  * `response_shape: "ranked"`: one list in the order the server ranked it.
@@ -2229,4 +2385,4 @@ interface SynapSdkLike {
2229
2385
  };
2230
2386
  }
2231
2387
 
2232
- export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContextMetadata, type ConversationContext, type ConversationNamespace, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DATA_SCOPES, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DataInterface, type DataScope, type DeleteDataOptions, type DeleteDataResult, type DocumentType, ENDPOINTS, EXCERPT_CATEGORY, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, FORGET_MODES, type Fact, type FetchOptions, type FlatMemory, type ForgetCandidate, type ForgetMode, type ForgetOptions, type ForgetResult, type ForgetStatus, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, MEMORY_TYPES, type MemoriesInterface, type NormalisedContext, type OpenAiToolDefinition, type Preference, RESPONSE_SHAPES, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type ResponseShape, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, applyResponseShape, flattenContextItems, formatForPrompt, isOutcomeUnknown, mergeScopeResults, rankItems, resolvePath, shouldRetry, stem, tokenize, wireRankScore };
2388
+ export { type AnthropicToolDefinition, AnticipationCacheSnapshot, type AsToolOptions, type AttachmentResult, BM25, type BatchCreateResult, COMPACTION_LEVELS, CONTRACT, type CacheNamespace, type CacheStats, type CompactOptions, type CompactionCallback, type CompactionLevel, type ConfigureOptions, type ContentPart, type ContextMetadata, type ConversationContext, type ConversationNamespace, type CreateDocument, type CreateFromFileOptions, type CreateMemoryOptions, type CreateMemoryResult, type Credentials, type CreditBalance, type CreditBucket, type CreditEstimate, type CreditLedgerEntry, type CreditLedgerPage, type CreditsNamespace, DATA_SCOPES, DEFAULT_BASE_URL, DEFAULT_DOCUMENT_TYPE, DEFAULT_INGEST_MODE, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUTS, DOCUMENT_TYPES, type DataInterface, type DataScope, type DeleteDataOptions, type DeleteDataResult, type DocumentType, ENDPOINTS, EXCERPT_CATEGORY, type Emotion, type EndpointName, type EndpointSpec, type Episode, type EstimateOptions, FORGET_MODES, type Fact, type FetchOptions, type FileData, type FilePart, type FilePartInit, type FlatMemory, type ForgetCandidate, type ForgetMode, type ForgetOptions, type ForgetResult, type ForgetStatus, type FormatOptions, HttpTransport, type HttpTransportOptions, INGEST_MODES, ITEM_COLLECTIONS, type IngestMode, type IngestTranscriptOptions, type InstanceNamespace, type ItemCollection, type Json, type LedgerOptions, type ListenOptions, MEMORY_TYPES, type MemoriesInterface, type NormalisedContext, OBJECTIVES, type Objective, type OpenAiToolDefinition, type Preference, RESPONSE_SHAPES, type RawContext, type RawContextItem, type RawConversationContext, type RecordMessageOptions, type RecordThinkingOptions, type RedeemResult, type RequestOptions, type ResponseShape, type RetryPolicy, SDK_VERSION, type Scope, type SendMessageOptions, SynapClient, type SynapClientOptions, SynapError, type SynapLogLevel, type SynapLogger, type SynapSdkLike, THRESHOLDS, type TemporalEvent, type TemporalFields, type TextPart, type TimeoutConfig, type ToolDefinition, type ToolHandler, type ToolScope, type ToolStyle, type TranscriptIngestResult, type TranscriptTurn, type UnifiedContext, type UnifiedFetchOptions, type UpdateMemoryOptions, type UserNamespace, type WaitOptions, type WriteInvalidator, applyResponseShape, filePart, flattenContextItems, formatForPrompt, isOutcomeUnknown, mergeScopeResults, rankItems, resolvePath, shouldRetry, stem, textPart, tokenize, wireRankScore };