@maximem/synap-js-sdk 0.6.8 → 0.7.0

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.
Files changed (36) hide show
  1. package/dist/anticipation-cache-Q7IYC3ID.cjs.map +1 -1
  2. package/dist/{chunk-DEFC7NHQ.js → chunk-BMA3HZEX.js} +6 -1
  3. package/dist/chunk-BMA3HZEX.js.map +1 -0
  4. package/dist/chunk-BYUGILQI.cjs.map +1 -1
  5. package/dist/{chunk-7IZHVYO2.cjs → chunk-JPDEKN5M.cjs} +28 -23
  6. package/dist/chunk-JPDEKN5M.cjs.map +1 -0
  7. package/dist/{chunk-YUCHB2YK.js → chunk-RKKTOLXP.js} +2 -2
  8. package/dist/{chunk-EI4AGILN.cjs → chunk-SAKMZI7G.cjs} +6 -6
  9. package/dist/chunk-SAKMZI7G.cjs.map +1 -0
  10. package/dist/chunk-ZKOJDUN4.cjs.map +1 -1
  11. package/dist/env-55ULHNJZ.cjs.map +1 -1
  12. package/dist/{errors-x5bpgxmC.d.ts → errors-DEJFTN6v.d.cts} +9 -2
  13. package/dist/{errors-x5bpgxmC.d.cts → errors-DEJFTN6v.d.ts} +9 -2
  14. package/dist/grpc/index.cjs +7 -7
  15. package/dist/grpc/index.cjs.map +1 -1
  16. package/dist/grpc/index.d.cts +1 -1
  17. package/dist/grpc/index.d.ts +1 -1
  18. package/dist/grpc/index.js +3 -3
  19. package/dist/index.cjs +666 -232
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +171 -4
  22. package/dist/index.d.ts +171 -4
  23. package/dist/index.js +443 -9
  24. package/dist/index.js.map +1 -1
  25. package/dist/onnx-encoder-4RSL6ID4.cjs.map +1 -1
  26. package/dist/{stream-client-Q2RR5SCS.js → stream-client-7A2DQ3H3.js} +3 -3
  27. package/dist/stream-client-H2ES74FF.cjs +22 -0
  28. package/dist/stream-client-H2ES74FF.cjs.map +1 -0
  29. package/package.json +1 -1
  30. package/dist/chunk-7IZHVYO2.cjs.map +0 -1
  31. package/dist/chunk-DEFC7NHQ.js.map +0 -1
  32. package/dist/chunk-EI4AGILN.cjs.map +0 -1
  33. package/dist/stream-client-TDHTS7F4.cjs +0 -22
  34. package/dist/stream-client-TDHTS7F4.cjs.map +0 -1
  35. /package/dist/{chunk-YUCHB2YK.js.map → chunk-RKKTOLXP.js.map} +0 -0
  36. /package/dist/{stream-client-Q2RR5SCS.js.map → stream-client-7A2DQ3H3.js.map} +0 -0
package/dist/index.d.cts CHANGED
@@ -1,5 +1,5 @@
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';
1
+ import { S as SynapError, E as Encoder, a as AnticipationCacheSnapshot } from './errors-DEJFTN6v.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 ScopeLadderError, v as ServiceUnavailableError, w as SessionExpiredError, x as SnapshotBundle, y as SnapshotItemPreview, z as SnapshotItemRecord, D as SynapErrorCode, F as SynapErrorOptions, G as SynapPermanentError, H as SynapTransientError, T as TranscriptConflictError, J as TransientError, K as isSynapError } from './errors-DEJFTN6v.cjs';
3
3
 
4
4
  /**
5
5
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -170,6 +170,16 @@ declare const ENDPOINTS: {
170
170
  readonly path: "/v1/telemetry/batch";
171
171
  readonly idempotent: false;
172
172
  };
173
+ readonly maca_generate: {
174
+ readonly method: "POST";
175
+ readonly path: "/v1/maca/generate";
176
+ readonly idempotent: false;
177
+ };
178
+ readonly maca_job: {
179
+ readonly method: "GET";
180
+ readonly path: "/v1/maca/jobs/{job_id}";
181
+ readonly idempotent: true;
182
+ };
173
183
  };
174
184
  type EndpointName = keyof typeof ENDPOINTS;
175
185
  /** Substitute `{placeholder}` segments. Values are URL-encoded.
@@ -245,6 +255,62 @@ interface KeepAliveOptions {
245
255
  maxConnections?: number;
246
256
  }
247
257
 
258
+ interface ScopeLevel {
259
+ readonly key: string;
260
+ readonly label: string;
261
+ readonly position: number;
262
+ readonly role: string | null;
263
+ readonly required: boolean;
264
+ }
265
+ /** Where a call reads or writes: ids, plus a path on a deeper ladder. `scope_path` is null on a default ladder. */
266
+ declare class ScopeAddress {
267
+ readonly user_id: string | null;
268
+ readonly customer_id: string | null;
269
+ readonly scope_path: Readonly<Record<string, string>> | null;
270
+ constructor(init?: {
271
+ user_id?: string | null;
272
+ customer_id?: string | null;
273
+ scope_path?: Record<string, string> | null;
274
+ });
275
+ /** Options for reads (`fetch`, `*.context.fetch`, `send_message`, ...): the path is `scope_path`. */
276
+ read_kwargs(): {
277
+ user_id?: string;
278
+ customer_id?: string;
279
+ scope_path?: Record<string, string>;
280
+ };
281
+ /** Options for `memories.create` / `create_from_file` / `forget`: the path is `scope`. */
282
+ write_kwargs(): {
283
+ user_id?: string;
284
+ customer_id?: string;
285
+ scope?: Record<string, string>;
286
+ };
287
+ }
288
+ declare class ScopeLadder {
289
+ readonly levels: readonly ScopeLevel[];
290
+ readonly is_default: boolean;
291
+ readonly ladder_ratified: boolean;
292
+ readonly nested_scoping_enabled: boolean;
293
+ /** "server" | "inferred" */
294
+ readonly source: 'server' | 'inferred';
295
+ /** True when the instance is B2C: the tenant and identity level are one node. */
296
+ readonly b2c: boolean;
297
+ constructor(init: {
298
+ levels: readonly ScopeLevel[];
299
+ is_default: boolean;
300
+ ladder_ratified: boolean;
301
+ nested_scoping_enabled: boolean;
302
+ source: 'server' | 'inferred';
303
+ b2c?: boolean;
304
+ });
305
+ get keys(): readonly string[];
306
+ /**
307
+ * Map `values` (outermost level first) to ids and, on a deeper ladder, the
308
+ * full prefix path. A shorter list addresses a higher level. Throws
309
+ * `ScopeLadderError` before any call when the values cannot be addressed.
310
+ */
311
+ address(values: readonly string[]): ScopeAddress;
312
+ }
313
+
248
314
  /**
249
315
  * Native HTTP transport.
250
316
  *
@@ -363,6 +429,31 @@ declare class HttpTransport {
363
429
  * deployment older than the field, and must mean "enforce nothing".
364
430
  */
365
431
  userContextIsolation: string | undefined;
432
+ /**
433
+ * Called as observer(error, carriedScopePath) for every 400 answer.
434
+ * `carriedScopePath` says whether the refused request named a scope path,
435
+ * which is how the client learns its cached ladder may be stale. Never
436
+ * allowed to throw.
437
+ */
438
+ onInvalidInput: ((error: SynapError, carriedScopePath: boolean) => void) | undefined;
439
+ /**
440
+ * A 400 answered a call that carried a scope path: the ladder we hold may be
441
+ * stale. The next read is at most one per LADDER_INVALIDATION_MIN_INTERVAL_MS,
442
+ * the last known ladder stays as the answer if it fails, and a read already
443
+ * in flight will not be stored.
444
+ *
445
+ * The server's refusal wording is deliberately not inspected. The gRPC
446
+ * stream does not surface HTTP 400, so a ladder error on the stream is not
447
+ * observed here.
448
+ */
449
+ invalidateScopeLadder(): void;
450
+ /**
451
+ * The account's ladder, from whoami, cached for 300 s (`null` included).
452
+ * Concurrent callers share one read. A failed re-read after expiry keeps the
453
+ * last known ladder (with a warning) and waits 60 s before trying again. A
454
+ * failure on the first read, or with `refresh`, is thrown.
455
+ */
456
+ getScopeLadder(refresh: boolean, warn: (message: string) => void): Promise<ScopeLadder | null>;
366
457
  /**
367
458
  * Set by the client to its identity resolution (`initialize()`'s whoami).
368
459
  * Python refuses every call before `initialize()`; here the first request
@@ -1454,6 +1545,48 @@ interface LedgerOptions {
1454
1545
  offset?: number;
1455
1546
  }
1456
1547
 
1548
+ /**
1549
+ * MACA plugin namespace (Synap Core). Mirrors `MacaInterface` in the Python SDK.
1550
+ *
1551
+ * A Synap Core server can have Synap Cloud write its memory config from a short
1552
+ * description of your use case. The server holds the Synap Cloud key; this
1553
+ * namespace only starts the job and reads it back. Synap Cloud has no such
1554
+ * route and answers 404.
1555
+ */
1556
+
1557
+ type MacaRelationship = 'b2c' | 'b2b';
1558
+ interface MacaJob {
1559
+ job_id: string;
1560
+ status: string;
1561
+ message: string;
1562
+ created_at: string | null;
1563
+ updated_at: string | null;
1564
+ removed_fields: string[];
1565
+ problems: string[];
1566
+ config_file: string | null;
1567
+ /** The generated config, once the job has ended with `succeeded` or `invalid`. */
1568
+ yaml: string | null;
1569
+ }
1570
+ interface MacaGenerateOptions {
1571
+ /** The use-case file (UTF-8 text, at most 256 KB), uploaded as is. */
1572
+ file_path?: string;
1573
+ filePath?: string;
1574
+ /** `b2c`: each user is their own customer. `b2b`: users sit under a customer. */
1575
+ user_relationship?: MacaRelationship;
1576
+ userRelationship?: MacaRelationship;
1577
+ }
1578
+ interface MacaWaitOptions {
1579
+ timeout_seconds?: number;
1580
+ timeoutSeconds?: number;
1581
+ poll_interval_seconds?: number;
1582
+ pollIntervalSeconds?: number;
1583
+ }
1584
+ interface MacaNamespace {
1585
+ generate(options: MacaGenerateOptions): Promise<MacaJob>;
1586
+ get_job(jobId: string): Promise<MacaJob>;
1587
+ wait_for_completion(jobId: string, options?: MacaWaitOptions): Promise<MacaJob>;
1588
+ }
1589
+
1457
1590
  /**
1458
1591
  * Cache namespace. Same method names as `CacheInterface` in the Python SDK,
1459
1592
  * but it covers only the in-memory cache of prefetched context: `stats()`
@@ -1745,6 +1878,11 @@ interface AsToolOptions {
1745
1878
  name?: string;
1746
1879
  description?: string;
1747
1880
  style?: string;
1881
+ /**
1882
+ * Closed-over rung for an account with a deeper ladder. Never part of the
1883
+ * schema the LLM sees, so the model cannot change it. Forwarded only when set.
1884
+ */
1885
+ scope_path?: Record<string, string> | null;
1748
1886
  }
1749
1887
  type ToolHandler = (callArgs?: Json) => Promise<Json>;
1750
1888
  interface OpenAiToolDefinition {
@@ -1886,6 +2024,8 @@ interface SynapClientOptions {
1886
2024
  * running two clients on one identity with separate caches.
1887
2025
  */
1888
2026
  _force_new?: boolean;
2027
+ /** Test seam: a monotonic clock in milliseconds for the scope-ladder cache. Not part of the everyday surface. */
2028
+ _clock?: () => number;
1889
2029
  }
1890
2030
  interface ScopedContext {
1891
2031
  context: {
@@ -1962,6 +2102,13 @@ interface UnifiedFetchOptions {
1962
2102
  * numbered list in that order. The typed lists are filled either way.
1963
2103
  */
1964
2104
  response_shape?: string;
2105
+ /**
2106
+ * The rung to read at, one entry per level from the first, for an account
2107
+ * with a deeper ladder (see `get_scope_ladder` and `ScopeLadder.address`).
2108
+ * Forwarded to every scope fetch that runs, and only when set. Send ids as
2109
+ * well. Not needed on a default ladder.
2110
+ */
2111
+ scope_path?: Record<string, string> | null;
1965
2112
  }
1966
2113
  declare class SynapClient {
1967
2114
  #private;
@@ -1972,6 +2119,7 @@ declare class SynapClient {
1972
2119
  readonly memories: MemoriesInterface;
1973
2120
  readonly data: DataInterface;
1974
2121
  readonly credits: CreditsNamespace;
2122
+ readonly maca: MacaNamespace;
1975
2123
  readonly cache: CacheNamespace;
1976
2124
  readonly instance: InstanceNamespace;
1977
2125
  constructor(options?: SynapClientOptions);
@@ -2058,6 +2206,25 @@ declare class SynapClient {
2058
2206
  * constructor resolved and is not fatal.
2059
2207
  */
2060
2208
  initialize(): Promise<void>;
2209
+ /**
2210
+ * The account's scope ladder, or `null` when it cannot be known.
2211
+ *
2212
+ * Mirrors Python's `get_scope_ladder()`. Read lazily from
2213
+ * `GET /api/v1/auth/whoami` (even when the client and instance ids are
2214
+ * already known), cached for 300 s (`null` included), re-read on `refresh: true`. Concurrent
2215
+ * callers share one read. If a re-read
2216
+ * after expiry fails, the last known ladder is returned with a warning and
2217
+ * the next try waits 60 s. A failure on the very first read, or with
2218
+ * `refresh`, is thrown. With no `scope_ladder` block the default ladder is
2219
+ * inferred from `user_context_isolation` (`source: "inferred"`).
2220
+ *
2221
+ * const ladder = await client.get_scope_ladder();
2222
+ * const addr = ladder!.address(['acme', 'payments', 'dana']);
2223
+ * await client.fetch({ search_query: ['...'], ...addr.read_kwargs() });
2224
+ */
2225
+ get_scope_ladder(options?: {
2226
+ refresh?: boolean;
2227
+ }): Promise<ScopeLadder | null>;
2061
2228
  /**
2062
2229
  * @deprecated Use `initialize()`, which is the Python name. `init()` was a
2063
2230
  * JS-only spelling with no Python counterpart; it now forwards, so a 0.3.x
@@ -2144,7 +2311,7 @@ declare class SynapClient {
2144
2311
  * build when the two disagree, which is the only thing that makes a manual
2145
2312
  * publish safe.
2146
2313
  */
2147
- declare const SDK_VERSION = "0.6.8";
2314
+ declare const SDK_VERSION = "0.7.0";
2148
2315
 
2149
2316
  /**
2150
2317
  * `response_shape: "ranked"`: one list in the order the server ranked it.
@@ -2385,4 +2552,4 @@ interface SynapSdkLike {
2385
2552
  };
2386
2553
  }
2387
2554
 
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 };
2555
+ 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 MacaGenerateOptions, type MacaJob, type MacaNamespace, type MacaRelationship, type MacaWaitOptions, 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, ScopeAddress, ScopeLadder, type ScopeLevel, 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 { 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';
1
+ import { S as SynapError, E as Encoder, a as AnticipationCacheSnapshot } from './errors-DEJFTN6v.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 ScopeLadderError, v as ServiceUnavailableError, w as SessionExpiredError, x as SnapshotBundle, y as SnapshotItemPreview, z as SnapshotItemRecord, D as SynapErrorCode, F as SynapErrorOptions, G as SynapPermanentError, H as SynapTransientError, T as TranscriptConflictError, J as TransientError, K as isSynapError } from './errors-DEJFTN6v.js';
3
3
 
4
4
  /**
5
5
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -170,6 +170,16 @@ declare const ENDPOINTS: {
170
170
  readonly path: "/v1/telemetry/batch";
171
171
  readonly idempotent: false;
172
172
  };
173
+ readonly maca_generate: {
174
+ readonly method: "POST";
175
+ readonly path: "/v1/maca/generate";
176
+ readonly idempotent: false;
177
+ };
178
+ readonly maca_job: {
179
+ readonly method: "GET";
180
+ readonly path: "/v1/maca/jobs/{job_id}";
181
+ readonly idempotent: true;
182
+ };
173
183
  };
174
184
  type EndpointName = keyof typeof ENDPOINTS;
175
185
  /** Substitute `{placeholder}` segments. Values are URL-encoded.
@@ -245,6 +255,62 @@ interface KeepAliveOptions {
245
255
  maxConnections?: number;
246
256
  }
247
257
 
258
+ interface ScopeLevel {
259
+ readonly key: string;
260
+ readonly label: string;
261
+ readonly position: number;
262
+ readonly role: string | null;
263
+ readonly required: boolean;
264
+ }
265
+ /** Where a call reads or writes: ids, plus a path on a deeper ladder. `scope_path` is null on a default ladder. */
266
+ declare class ScopeAddress {
267
+ readonly user_id: string | null;
268
+ readonly customer_id: string | null;
269
+ readonly scope_path: Readonly<Record<string, string>> | null;
270
+ constructor(init?: {
271
+ user_id?: string | null;
272
+ customer_id?: string | null;
273
+ scope_path?: Record<string, string> | null;
274
+ });
275
+ /** Options for reads (`fetch`, `*.context.fetch`, `send_message`, ...): the path is `scope_path`. */
276
+ read_kwargs(): {
277
+ user_id?: string;
278
+ customer_id?: string;
279
+ scope_path?: Record<string, string>;
280
+ };
281
+ /** Options for `memories.create` / `create_from_file` / `forget`: the path is `scope`. */
282
+ write_kwargs(): {
283
+ user_id?: string;
284
+ customer_id?: string;
285
+ scope?: Record<string, string>;
286
+ };
287
+ }
288
+ declare class ScopeLadder {
289
+ readonly levels: readonly ScopeLevel[];
290
+ readonly is_default: boolean;
291
+ readonly ladder_ratified: boolean;
292
+ readonly nested_scoping_enabled: boolean;
293
+ /** "server" | "inferred" */
294
+ readonly source: 'server' | 'inferred';
295
+ /** True when the instance is B2C: the tenant and identity level are one node. */
296
+ readonly b2c: boolean;
297
+ constructor(init: {
298
+ levels: readonly ScopeLevel[];
299
+ is_default: boolean;
300
+ ladder_ratified: boolean;
301
+ nested_scoping_enabled: boolean;
302
+ source: 'server' | 'inferred';
303
+ b2c?: boolean;
304
+ });
305
+ get keys(): readonly string[];
306
+ /**
307
+ * Map `values` (outermost level first) to ids and, on a deeper ladder, the
308
+ * full prefix path. A shorter list addresses a higher level. Throws
309
+ * `ScopeLadderError` before any call when the values cannot be addressed.
310
+ */
311
+ address(values: readonly string[]): ScopeAddress;
312
+ }
313
+
248
314
  /**
249
315
  * Native HTTP transport.
250
316
  *
@@ -363,6 +429,31 @@ declare class HttpTransport {
363
429
  * deployment older than the field, and must mean "enforce nothing".
364
430
  */
365
431
  userContextIsolation: string | undefined;
432
+ /**
433
+ * Called as observer(error, carriedScopePath) for every 400 answer.
434
+ * `carriedScopePath` says whether the refused request named a scope path,
435
+ * which is how the client learns its cached ladder may be stale. Never
436
+ * allowed to throw.
437
+ */
438
+ onInvalidInput: ((error: SynapError, carriedScopePath: boolean) => void) | undefined;
439
+ /**
440
+ * A 400 answered a call that carried a scope path: the ladder we hold may be
441
+ * stale. The next read is at most one per LADDER_INVALIDATION_MIN_INTERVAL_MS,
442
+ * the last known ladder stays as the answer if it fails, and a read already
443
+ * in flight will not be stored.
444
+ *
445
+ * The server's refusal wording is deliberately not inspected. The gRPC
446
+ * stream does not surface HTTP 400, so a ladder error on the stream is not
447
+ * observed here.
448
+ */
449
+ invalidateScopeLadder(): void;
450
+ /**
451
+ * The account's ladder, from whoami, cached for 300 s (`null` included).
452
+ * Concurrent callers share one read. A failed re-read after expiry keeps the
453
+ * last known ladder (with a warning) and waits 60 s before trying again. A
454
+ * failure on the first read, or with `refresh`, is thrown.
455
+ */
456
+ getScopeLadder(refresh: boolean, warn: (message: string) => void): Promise<ScopeLadder | null>;
366
457
  /**
367
458
  * Set by the client to its identity resolution (`initialize()`'s whoami).
368
459
  * Python refuses every call before `initialize()`; here the first request
@@ -1454,6 +1545,48 @@ interface LedgerOptions {
1454
1545
  offset?: number;
1455
1546
  }
1456
1547
 
1548
+ /**
1549
+ * MACA plugin namespace (Synap Core). Mirrors `MacaInterface` in the Python SDK.
1550
+ *
1551
+ * A Synap Core server can have Synap Cloud write its memory config from a short
1552
+ * description of your use case. The server holds the Synap Cloud key; this
1553
+ * namespace only starts the job and reads it back. Synap Cloud has no such
1554
+ * route and answers 404.
1555
+ */
1556
+
1557
+ type MacaRelationship = 'b2c' | 'b2b';
1558
+ interface MacaJob {
1559
+ job_id: string;
1560
+ status: string;
1561
+ message: string;
1562
+ created_at: string | null;
1563
+ updated_at: string | null;
1564
+ removed_fields: string[];
1565
+ problems: string[];
1566
+ config_file: string | null;
1567
+ /** The generated config, once the job has ended with `succeeded` or `invalid`. */
1568
+ yaml: string | null;
1569
+ }
1570
+ interface MacaGenerateOptions {
1571
+ /** The use-case file (UTF-8 text, at most 256 KB), uploaded as is. */
1572
+ file_path?: string;
1573
+ filePath?: string;
1574
+ /** `b2c`: each user is their own customer. `b2b`: users sit under a customer. */
1575
+ user_relationship?: MacaRelationship;
1576
+ userRelationship?: MacaRelationship;
1577
+ }
1578
+ interface MacaWaitOptions {
1579
+ timeout_seconds?: number;
1580
+ timeoutSeconds?: number;
1581
+ poll_interval_seconds?: number;
1582
+ pollIntervalSeconds?: number;
1583
+ }
1584
+ interface MacaNamespace {
1585
+ generate(options: MacaGenerateOptions): Promise<MacaJob>;
1586
+ get_job(jobId: string): Promise<MacaJob>;
1587
+ wait_for_completion(jobId: string, options?: MacaWaitOptions): Promise<MacaJob>;
1588
+ }
1589
+
1457
1590
  /**
1458
1591
  * Cache namespace. Same method names as `CacheInterface` in the Python SDK,
1459
1592
  * but it covers only the in-memory cache of prefetched context: `stats()`
@@ -1745,6 +1878,11 @@ interface AsToolOptions {
1745
1878
  name?: string;
1746
1879
  description?: string;
1747
1880
  style?: string;
1881
+ /**
1882
+ * Closed-over rung for an account with a deeper ladder. Never part of the
1883
+ * schema the LLM sees, so the model cannot change it. Forwarded only when set.
1884
+ */
1885
+ scope_path?: Record<string, string> | null;
1748
1886
  }
1749
1887
  type ToolHandler = (callArgs?: Json) => Promise<Json>;
1750
1888
  interface OpenAiToolDefinition {
@@ -1886,6 +2024,8 @@ interface SynapClientOptions {
1886
2024
  * running two clients on one identity with separate caches.
1887
2025
  */
1888
2026
  _force_new?: boolean;
2027
+ /** Test seam: a monotonic clock in milliseconds for the scope-ladder cache. Not part of the everyday surface. */
2028
+ _clock?: () => number;
1889
2029
  }
1890
2030
  interface ScopedContext {
1891
2031
  context: {
@@ -1962,6 +2102,13 @@ interface UnifiedFetchOptions {
1962
2102
  * numbered list in that order. The typed lists are filled either way.
1963
2103
  */
1964
2104
  response_shape?: string;
2105
+ /**
2106
+ * The rung to read at, one entry per level from the first, for an account
2107
+ * with a deeper ladder (see `get_scope_ladder` and `ScopeLadder.address`).
2108
+ * Forwarded to every scope fetch that runs, and only when set. Send ids as
2109
+ * well. Not needed on a default ladder.
2110
+ */
2111
+ scope_path?: Record<string, string> | null;
1965
2112
  }
1966
2113
  declare class SynapClient {
1967
2114
  #private;
@@ -1972,6 +2119,7 @@ declare class SynapClient {
1972
2119
  readonly memories: MemoriesInterface;
1973
2120
  readonly data: DataInterface;
1974
2121
  readonly credits: CreditsNamespace;
2122
+ readonly maca: MacaNamespace;
1975
2123
  readonly cache: CacheNamespace;
1976
2124
  readonly instance: InstanceNamespace;
1977
2125
  constructor(options?: SynapClientOptions);
@@ -2058,6 +2206,25 @@ declare class SynapClient {
2058
2206
  * constructor resolved and is not fatal.
2059
2207
  */
2060
2208
  initialize(): Promise<void>;
2209
+ /**
2210
+ * The account's scope ladder, or `null` when it cannot be known.
2211
+ *
2212
+ * Mirrors Python's `get_scope_ladder()`. Read lazily from
2213
+ * `GET /api/v1/auth/whoami` (even when the client and instance ids are
2214
+ * already known), cached for 300 s (`null` included), re-read on `refresh: true`. Concurrent
2215
+ * callers share one read. If a re-read
2216
+ * after expiry fails, the last known ladder is returned with a warning and
2217
+ * the next try waits 60 s. A failure on the very first read, or with
2218
+ * `refresh`, is thrown. With no `scope_ladder` block the default ladder is
2219
+ * inferred from `user_context_isolation` (`source: "inferred"`).
2220
+ *
2221
+ * const ladder = await client.get_scope_ladder();
2222
+ * const addr = ladder!.address(['acme', 'payments', 'dana']);
2223
+ * await client.fetch({ search_query: ['...'], ...addr.read_kwargs() });
2224
+ */
2225
+ get_scope_ladder(options?: {
2226
+ refresh?: boolean;
2227
+ }): Promise<ScopeLadder | null>;
2061
2228
  /**
2062
2229
  * @deprecated Use `initialize()`, which is the Python name. `init()` was a
2063
2230
  * JS-only spelling with no Python counterpart; it now forwards, so a 0.3.x
@@ -2144,7 +2311,7 @@ declare class SynapClient {
2144
2311
  * build when the two disagree, which is the only thing that makes a manual
2145
2312
  * publish safe.
2146
2313
  */
2147
- declare const SDK_VERSION = "0.6.8";
2314
+ declare const SDK_VERSION = "0.7.0";
2148
2315
 
2149
2316
  /**
2150
2317
  * `response_shape: "ranked"`: one list in the order the server ranked it.
@@ -2385,4 +2552,4 @@ interface SynapSdkLike {
2385
2552
  };
2386
2553
  }
2387
2554
 
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 };
2555
+ 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 MacaGenerateOptions, type MacaJob, type MacaNamespace, type MacaRelationship, type MacaWaitOptions, 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, ScopeAddress, ScopeLadder, type ScopeLevel, 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 };