@maximem/synap-js-sdk 0.6.8 → 0.7.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.
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 +710 -235
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +200 -4
  22. package/dist/index.d.ts +200 -4
  23. package/dist/index.js +486 -11
  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,71 @@ 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
+ /**
276
+ * Options for reads: `fetch`, `send_message`, `record_message`,
277
+ * `user.context.fetch`, `conversation.context.fetch` and
278
+ * `client.context.fetch`. The path is `scope_path`.
279
+ *
280
+ * Not for `customer.context.fetch`: that route refuses a path that names the
281
+ * identity rung (HTTP 400, it reads shared material only) and takes no
282
+ * `user_id`. Call `client.fetch(addr.read_kwargs())`, which sends the
283
+ * customer route the path cut above the identity rung.
284
+ */
285
+ read_kwargs(): {
286
+ user_id?: string;
287
+ customer_id?: string;
288
+ scope_path?: Record<string, string>;
289
+ };
290
+ /** Options for `memories.create` / `create_from_file` / `forget`: the path is `scope`. */
291
+ write_kwargs(): {
292
+ user_id?: string;
293
+ customer_id?: string;
294
+ scope?: Record<string, string>;
295
+ };
296
+ }
297
+ declare class ScopeLadder {
298
+ readonly levels: readonly ScopeLevel[];
299
+ readonly is_default: boolean;
300
+ readonly ladder_ratified: boolean;
301
+ readonly nested_scoping_enabled: boolean;
302
+ /** "server" | "inferred" */
303
+ readonly source: 'server' | 'inferred';
304
+ /** True when the instance is B2C: the tenant and identity level are one node. */
305
+ readonly b2c: boolean;
306
+ constructor(init: {
307
+ levels: readonly ScopeLevel[];
308
+ is_default: boolean;
309
+ ladder_ratified: boolean;
310
+ nested_scoping_enabled: boolean;
311
+ source: 'server' | 'inferred';
312
+ b2c?: boolean;
313
+ });
314
+ get keys(): readonly string[];
315
+ /**
316
+ * Map `values` (outermost level first) to ids and, on a deeper ladder, the
317
+ * full prefix path. A shorter list addresses a higher level. Throws
318
+ * `ScopeLadderError` before any call when the values cannot be addressed.
319
+ */
320
+ address(values: readonly string[]): ScopeAddress;
321
+ }
322
+
248
323
  /**
249
324
  * Native HTTP transport.
250
325
  *
@@ -363,6 +438,33 @@ declare class HttpTransport {
363
438
  * deployment older than the field, and must mean "enforce nothing".
364
439
  */
365
440
  userContextIsolation: string | undefined;
441
+ /**
442
+ * Called as observer(error, carriedScopePath) for every 400 answer.
443
+ * `carriedScopePath` says whether the refused request named a scope path,
444
+ * which is how the client learns its cached ladder may be stale. Never
445
+ * allowed to throw.
446
+ */
447
+ onInvalidInput: ((error: SynapError, carriedScopePath: boolean) => void) | undefined;
448
+ /**
449
+ * A 400 answered a call that carried a scope path: the ladder we hold may be
450
+ * stale. The next read is at most one per LADDER_INVALIDATION_MIN_INTERVAL_MS,
451
+ * the last known ladder stays as the answer if it fails, and a read already
452
+ * in flight will not be stored.
453
+ *
454
+ * The server's refusal wording is deliberately not inspected. The gRPC
455
+ * stream does not surface HTTP 400, so a ladder error on the stream is not
456
+ * observed here.
457
+ */
458
+ invalidateScopeLadder(): void;
459
+ /** The ladder already held, or null when none has been read. Makes no request. */
460
+ cachedScopeLadder(): ScopeLadder | null;
461
+ /**
462
+ * The account's ladder, from whoami, cached for 300 s (`null` included).
463
+ * Concurrent callers share one read. A failed re-read after expiry keeps the
464
+ * last known ladder (with a warning) and waits 60 s before trying again. A
465
+ * failure on the first read, or with `refresh`, is thrown.
466
+ */
467
+ getScopeLadder(refresh: boolean, warn: (message: string) => void): Promise<ScopeLadder | null>;
366
468
  /**
367
469
  * Set by the client to its identity resolution (`initialize()`'s whoami).
368
470
  * Python refuses every call before `initialize()`; here the first request
@@ -1454,6 +1556,48 @@ interface LedgerOptions {
1454
1556
  offset?: number;
1455
1557
  }
1456
1558
 
1559
+ /**
1560
+ * MACA plugin namespace (Synap Core). Mirrors `MacaInterface` in the Python SDK.
1561
+ *
1562
+ * A Synap Core server can have Synap Cloud write its memory config from a short
1563
+ * description of your use case. The server holds the Synap Cloud key; this
1564
+ * namespace only starts the job and reads it back. Synap Cloud has no such
1565
+ * route and answers 404.
1566
+ */
1567
+
1568
+ type MacaRelationship = 'b2c' | 'b2b';
1569
+ interface MacaJob {
1570
+ job_id: string;
1571
+ status: string;
1572
+ message: string;
1573
+ created_at: string | null;
1574
+ updated_at: string | null;
1575
+ removed_fields: string[];
1576
+ problems: string[];
1577
+ config_file: string | null;
1578
+ /** The generated config, once the job has ended with `succeeded` or `invalid`. */
1579
+ yaml: string | null;
1580
+ }
1581
+ interface MacaGenerateOptions {
1582
+ /** The use-case file (UTF-8 text, at most 256 KB), uploaded as is. */
1583
+ file_path?: string;
1584
+ filePath?: string;
1585
+ /** `b2c`: each user is their own customer. `b2b`: users sit under a customer. */
1586
+ user_relationship?: MacaRelationship;
1587
+ userRelationship?: MacaRelationship;
1588
+ }
1589
+ interface MacaWaitOptions {
1590
+ timeout_seconds?: number;
1591
+ timeoutSeconds?: number;
1592
+ poll_interval_seconds?: number;
1593
+ pollIntervalSeconds?: number;
1594
+ }
1595
+ interface MacaNamespace {
1596
+ generate(options: MacaGenerateOptions): Promise<MacaJob>;
1597
+ get_job(jobId: string): Promise<MacaJob>;
1598
+ wait_for_completion(jobId: string, options?: MacaWaitOptions): Promise<MacaJob>;
1599
+ }
1600
+
1457
1601
  /**
1458
1602
  * Cache namespace. Same method names as `CacheInterface` in the Python SDK,
1459
1603
  * but it covers only the in-memory cache of prefetched context: `stats()`
@@ -1745,6 +1889,14 @@ interface AsToolOptions {
1745
1889
  name?: string;
1746
1890
  description?: string;
1747
1891
  style?: string;
1892
+ /**
1893
+ * Closed-over rung for an account with a deeper ladder. Never part of the
1894
+ * schema the LLM sees, so the model cannot change it. Forwarded only when set.
1895
+ * With `scope: 'unified'` the customer fetch gets it cut above the identity
1896
+ * rung, as in `fetch`. With `scope: 'customer'` it goes as given, and the
1897
+ * server refuses (HTTP 400) a path that names the identity rung.
1898
+ */
1899
+ scope_path?: Record<string, string> | null;
1748
1900
  }
1749
1901
  type ToolHandler = (callArgs?: Json) => Promise<Json>;
1750
1902
  interface OpenAiToolDefinition {
@@ -1886,6 +2038,8 @@ interface SynapClientOptions {
1886
2038
  * running two clients on one identity with separate caches.
1887
2039
  */
1888
2040
  _force_new?: boolean;
2041
+ /** Test seam: a monotonic clock in milliseconds for the scope-ladder cache. Not part of the everyday surface. */
2042
+ _clock?: () => number;
1889
2043
  }
1890
2044
  interface ScopedContext {
1891
2045
  context: {
@@ -1962,6 +2116,28 @@ interface UnifiedFetchOptions {
1962
2116
  * numbered list in that order. The typed lists are filled either way.
1963
2117
  */
1964
2118
  response_shape?: string;
2119
+ /**
2120
+ * The rung to read at, one entry per level from the first, for an account
2121
+ * with a deeper ladder (see `get_scope_ladder` and `ScopeLadder.address`).
2122
+ * Only when set. Send ids as well. Not needed on a default ladder. The user
2123
+ * and conversation fetches get the path as given. The client fetch gets no
2124
+ * path. The client read is meant to return the account-wide shared memory,
2125
+ * and the user and customer reads already cover the person's and the team's
2126
+ * own levels. The server does apply a path on that route (it narrows the read
2127
+ * to that chain's own nodes), so sending one would narrow the shared read,
2128
+ * duplicate results the other reads return, and create registry nodes on a
2129
+ * read; it is also validated strictly (HTTP 400 if it is invalid or nested
2130
+ * scoping is off). SDK 0.7.0 sent it. The customer fetch
2131
+ * reads shared material only and the server refuses (HTTP 400) a path that
2132
+ * names the identity rung, so it gets the path with the identity level and
2133
+ * every level below it removed. The identity level is found by its role on
2134
+ * the account's ladder, which `fetch` reads first when a path is set and the
2135
+ * customer scope runs (one shared read, cached 300 s; no request when it is
2136
+ * cached, and none for a call without a path). If that read fails, a warning
2137
+ * is logged and only the reserved key `user` is removed. A path with no
2138
+ * identity level goes to the user, conversation and customer fetches as given.
2139
+ */
2140
+ scope_path?: Record<string, string> | null;
1965
2141
  }
1966
2142
  declare class SynapClient {
1967
2143
  #private;
@@ -1972,6 +2148,7 @@ declare class SynapClient {
1972
2148
  readonly memories: MemoriesInterface;
1973
2149
  readonly data: DataInterface;
1974
2150
  readonly credits: CreditsNamespace;
2151
+ readonly maca: MacaNamespace;
1975
2152
  readonly cache: CacheNamespace;
1976
2153
  readonly instance: InstanceNamespace;
1977
2154
  constructor(options?: SynapClientOptions);
@@ -2058,6 +2235,25 @@ declare class SynapClient {
2058
2235
  * constructor resolved and is not fatal.
2059
2236
  */
2060
2237
  initialize(): Promise<void>;
2238
+ /**
2239
+ * The account's scope ladder, or `null` when it cannot be known.
2240
+ *
2241
+ * Mirrors Python's `get_scope_ladder()`. Read lazily from
2242
+ * `GET /api/v1/auth/whoami` (even when the client and instance ids are
2243
+ * already known), cached for 300 s (`null` included), re-read on `refresh: true`. Concurrent
2244
+ * callers share one read. If a re-read
2245
+ * after expiry fails, the last known ladder is returned with a warning and
2246
+ * the next try waits 60 s. A failure on the very first read, or with
2247
+ * `refresh`, is thrown. With no `scope_ladder` block the default ladder is
2248
+ * inferred from `user_context_isolation` (`source: "inferred"`).
2249
+ *
2250
+ * const ladder = await client.get_scope_ladder();
2251
+ * const addr = ladder!.address(['acme', 'payments', 'dana']);
2252
+ * await client.fetch({ search_query: ['...'], ...addr.read_kwargs() });
2253
+ */
2254
+ get_scope_ladder(options?: {
2255
+ refresh?: boolean;
2256
+ }): Promise<ScopeLadder | null>;
2061
2257
  /**
2062
2258
  * @deprecated Use `initialize()`, which is the Python name. `init()` was a
2063
2259
  * JS-only spelling with no Python counterpart; it now forwards, so a 0.3.x
@@ -2144,7 +2340,7 @@ declare class SynapClient {
2144
2340
  * build when the two disagree, which is the only thing that makes a manual
2145
2341
  * publish safe.
2146
2342
  */
2147
- declare const SDK_VERSION = "0.6.8";
2343
+ declare const SDK_VERSION = "0.7.1";
2148
2344
 
2149
2345
  /**
2150
2346
  * `response_shape: "ranked"`: one list in the order the server ranked it.
@@ -2385,4 +2581,4 @@ interface SynapSdkLike {
2385
2581
  };
2386
2582
  }
2387
2583
 
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 };
2584
+ 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,71 @@ 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
+ /**
276
+ * Options for reads: `fetch`, `send_message`, `record_message`,
277
+ * `user.context.fetch`, `conversation.context.fetch` and
278
+ * `client.context.fetch`. The path is `scope_path`.
279
+ *
280
+ * Not for `customer.context.fetch`: that route refuses a path that names the
281
+ * identity rung (HTTP 400, it reads shared material only) and takes no
282
+ * `user_id`. Call `client.fetch(addr.read_kwargs())`, which sends the
283
+ * customer route the path cut above the identity rung.
284
+ */
285
+ read_kwargs(): {
286
+ user_id?: string;
287
+ customer_id?: string;
288
+ scope_path?: Record<string, string>;
289
+ };
290
+ /** Options for `memories.create` / `create_from_file` / `forget`: the path is `scope`. */
291
+ write_kwargs(): {
292
+ user_id?: string;
293
+ customer_id?: string;
294
+ scope?: Record<string, string>;
295
+ };
296
+ }
297
+ declare class ScopeLadder {
298
+ readonly levels: readonly ScopeLevel[];
299
+ readonly is_default: boolean;
300
+ readonly ladder_ratified: boolean;
301
+ readonly nested_scoping_enabled: boolean;
302
+ /** "server" | "inferred" */
303
+ readonly source: 'server' | 'inferred';
304
+ /** True when the instance is B2C: the tenant and identity level are one node. */
305
+ readonly b2c: boolean;
306
+ constructor(init: {
307
+ levels: readonly ScopeLevel[];
308
+ is_default: boolean;
309
+ ladder_ratified: boolean;
310
+ nested_scoping_enabled: boolean;
311
+ source: 'server' | 'inferred';
312
+ b2c?: boolean;
313
+ });
314
+ get keys(): readonly string[];
315
+ /**
316
+ * Map `values` (outermost level first) to ids and, on a deeper ladder, the
317
+ * full prefix path. A shorter list addresses a higher level. Throws
318
+ * `ScopeLadderError` before any call when the values cannot be addressed.
319
+ */
320
+ address(values: readonly string[]): ScopeAddress;
321
+ }
322
+
248
323
  /**
249
324
  * Native HTTP transport.
250
325
  *
@@ -363,6 +438,33 @@ declare class HttpTransport {
363
438
  * deployment older than the field, and must mean "enforce nothing".
364
439
  */
365
440
  userContextIsolation: string | undefined;
441
+ /**
442
+ * Called as observer(error, carriedScopePath) for every 400 answer.
443
+ * `carriedScopePath` says whether the refused request named a scope path,
444
+ * which is how the client learns its cached ladder may be stale. Never
445
+ * allowed to throw.
446
+ */
447
+ onInvalidInput: ((error: SynapError, carriedScopePath: boolean) => void) | undefined;
448
+ /**
449
+ * A 400 answered a call that carried a scope path: the ladder we hold may be
450
+ * stale. The next read is at most one per LADDER_INVALIDATION_MIN_INTERVAL_MS,
451
+ * the last known ladder stays as the answer if it fails, and a read already
452
+ * in flight will not be stored.
453
+ *
454
+ * The server's refusal wording is deliberately not inspected. The gRPC
455
+ * stream does not surface HTTP 400, so a ladder error on the stream is not
456
+ * observed here.
457
+ */
458
+ invalidateScopeLadder(): void;
459
+ /** The ladder already held, or null when none has been read. Makes no request. */
460
+ cachedScopeLadder(): ScopeLadder | null;
461
+ /**
462
+ * The account's ladder, from whoami, cached for 300 s (`null` included).
463
+ * Concurrent callers share one read. A failed re-read after expiry keeps the
464
+ * last known ladder (with a warning) and waits 60 s before trying again. A
465
+ * failure on the first read, or with `refresh`, is thrown.
466
+ */
467
+ getScopeLadder(refresh: boolean, warn: (message: string) => void): Promise<ScopeLadder | null>;
366
468
  /**
367
469
  * Set by the client to its identity resolution (`initialize()`'s whoami).
368
470
  * Python refuses every call before `initialize()`; here the first request
@@ -1454,6 +1556,48 @@ interface LedgerOptions {
1454
1556
  offset?: number;
1455
1557
  }
1456
1558
 
1559
+ /**
1560
+ * MACA plugin namespace (Synap Core). Mirrors `MacaInterface` in the Python SDK.
1561
+ *
1562
+ * A Synap Core server can have Synap Cloud write its memory config from a short
1563
+ * description of your use case. The server holds the Synap Cloud key; this
1564
+ * namespace only starts the job and reads it back. Synap Cloud has no such
1565
+ * route and answers 404.
1566
+ */
1567
+
1568
+ type MacaRelationship = 'b2c' | 'b2b';
1569
+ interface MacaJob {
1570
+ job_id: string;
1571
+ status: string;
1572
+ message: string;
1573
+ created_at: string | null;
1574
+ updated_at: string | null;
1575
+ removed_fields: string[];
1576
+ problems: string[];
1577
+ config_file: string | null;
1578
+ /** The generated config, once the job has ended with `succeeded` or `invalid`. */
1579
+ yaml: string | null;
1580
+ }
1581
+ interface MacaGenerateOptions {
1582
+ /** The use-case file (UTF-8 text, at most 256 KB), uploaded as is. */
1583
+ file_path?: string;
1584
+ filePath?: string;
1585
+ /** `b2c`: each user is their own customer. `b2b`: users sit under a customer. */
1586
+ user_relationship?: MacaRelationship;
1587
+ userRelationship?: MacaRelationship;
1588
+ }
1589
+ interface MacaWaitOptions {
1590
+ timeout_seconds?: number;
1591
+ timeoutSeconds?: number;
1592
+ poll_interval_seconds?: number;
1593
+ pollIntervalSeconds?: number;
1594
+ }
1595
+ interface MacaNamespace {
1596
+ generate(options: MacaGenerateOptions): Promise<MacaJob>;
1597
+ get_job(jobId: string): Promise<MacaJob>;
1598
+ wait_for_completion(jobId: string, options?: MacaWaitOptions): Promise<MacaJob>;
1599
+ }
1600
+
1457
1601
  /**
1458
1602
  * Cache namespace. Same method names as `CacheInterface` in the Python SDK,
1459
1603
  * but it covers only the in-memory cache of prefetched context: `stats()`
@@ -1745,6 +1889,14 @@ interface AsToolOptions {
1745
1889
  name?: string;
1746
1890
  description?: string;
1747
1891
  style?: string;
1892
+ /**
1893
+ * Closed-over rung for an account with a deeper ladder. Never part of the
1894
+ * schema the LLM sees, so the model cannot change it. Forwarded only when set.
1895
+ * With `scope: 'unified'` the customer fetch gets it cut above the identity
1896
+ * rung, as in `fetch`. With `scope: 'customer'` it goes as given, and the
1897
+ * server refuses (HTTP 400) a path that names the identity rung.
1898
+ */
1899
+ scope_path?: Record<string, string> | null;
1748
1900
  }
1749
1901
  type ToolHandler = (callArgs?: Json) => Promise<Json>;
1750
1902
  interface OpenAiToolDefinition {
@@ -1886,6 +2038,8 @@ interface SynapClientOptions {
1886
2038
  * running two clients on one identity with separate caches.
1887
2039
  */
1888
2040
  _force_new?: boolean;
2041
+ /** Test seam: a monotonic clock in milliseconds for the scope-ladder cache. Not part of the everyday surface. */
2042
+ _clock?: () => number;
1889
2043
  }
1890
2044
  interface ScopedContext {
1891
2045
  context: {
@@ -1962,6 +2116,28 @@ interface UnifiedFetchOptions {
1962
2116
  * numbered list in that order. The typed lists are filled either way.
1963
2117
  */
1964
2118
  response_shape?: string;
2119
+ /**
2120
+ * The rung to read at, one entry per level from the first, for an account
2121
+ * with a deeper ladder (see `get_scope_ladder` and `ScopeLadder.address`).
2122
+ * Only when set. Send ids as well. Not needed on a default ladder. The user
2123
+ * and conversation fetches get the path as given. The client fetch gets no
2124
+ * path. The client read is meant to return the account-wide shared memory,
2125
+ * and the user and customer reads already cover the person's and the team's
2126
+ * own levels. The server does apply a path on that route (it narrows the read
2127
+ * to that chain's own nodes), so sending one would narrow the shared read,
2128
+ * duplicate results the other reads return, and create registry nodes on a
2129
+ * read; it is also validated strictly (HTTP 400 if it is invalid or nested
2130
+ * scoping is off). SDK 0.7.0 sent it. The customer fetch
2131
+ * reads shared material only and the server refuses (HTTP 400) a path that
2132
+ * names the identity rung, so it gets the path with the identity level and
2133
+ * every level below it removed. The identity level is found by its role on
2134
+ * the account's ladder, which `fetch` reads first when a path is set and the
2135
+ * customer scope runs (one shared read, cached 300 s; no request when it is
2136
+ * cached, and none for a call without a path). If that read fails, a warning
2137
+ * is logged and only the reserved key `user` is removed. A path with no
2138
+ * identity level goes to the user, conversation and customer fetches as given.
2139
+ */
2140
+ scope_path?: Record<string, string> | null;
1965
2141
  }
1966
2142
  declare class SynapClient {
1967
2143
  #private;
@@ -1972,6 +2148,7 @@ declare class SynapClient {
1972
2148
  readonly memories: MemoriesInterface;
1973
2149
  readonly data: DataInterface;
1974
2150
  readonly credits: CreditsNamespace;
2151
+ readonly maca: MacaNamespace;
1975
2152
  readonly cache: CacheNamespace;
1976
2153
  readonly instance: InstanceNamespace;
1977
2154
  constructor(options?: SynapClientOptions);
@@ -2058,6 +2235,25 @@ declare class SynapClient {
2058
2235
  * constructor resolved and is not fatal.
2059
2236
  */
2060
2237
  initialize(): Promise<void>;
2238
+ /**
2239
+ * The account's scope ladder, or `null` when it cannot be known.
2240
+ *
2241
+ * Mirrors Python's `get_scope_ladder()`. Read lazily from
2242
+ * `GET /api/v1/auth/whoami` (even when the client and instance ids are
2243
+ * already known), cached for 300 s (`null` included), re-read on `refresh: true`. Concurrent
2244
+ * callers share one read. If a re-read
2245
+ * after expiry fails, the last known ladder is returned with a warning and
2246
+ * the next try waits 60 s. A failure on the very first read, or with
2247
+ * `refresh`, is thrown. With no `scope_ladder` block the default ladder is
2248
+ * inferred from `user_context_isolation` (`source: "inferred"`).
2249
+ *
2250
+ * const ladder = await client.get_scope_ladder();
2251
+ * const addr = ladder!.address(['acme', 'payments', 'dana']);
2252
+ * await client.fetch({ search_query: ['...'], ...addr.read_kwargs() });
2253
+ */
2254
+ get_scope_ladder(options?: {
2255
+ refresh?: boolean;
2256
+ }): Promise<ScopeLadder | null>;
2061
2257
  /**
2062
2258
  * @deprecated Use `initialize()`, which is the Python name. `init()` was a
2063
2259
  * JS-only spelling with no Python counterpart; it now forwards, so a 0.3.x
@@ -2144,7 +2340,7 @@ declare class SynapClient {
2144
2340
  * build when the two disagree, which is the only thing that makes a manual
2145
2341
  * publish safe.
2146
2342
  */
2147
- declare const SDK_VERSION = "0.6.8";
2343
+ declare const SDK_VERSION = "0.7.1";
2148
2344
 
2149
2345
  /**
2150
2346
  * `response_shape: "ranked"`: one list in the order the server ranked it.
@@ -2385,4 +2581,4 @@ interface SynapSdkLike {
2385
2581
  };
2386
2582
  }
2387
2583
 
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 };
2584
+ 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 };