@maximem/synap-js-sdk 0.7.0 → 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.
package/dist/index.d.cts CHANGED
@@ -272,7 +272,16 @@ declare class ScopeAddress {
272
272
  customer_id?: string | null;
273
273
  scope_path?: Record<string, string> | null;
274
274
  });
275
- /** Options for reads (`fetch`, `*.context.fetch`, `send_message`, ...): the path is `scope_path`. */
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
+ */
276
285
  read_kwargs(): {
277
286
  user_id?: string;
278
287
  customer_id?: string;
@@ -447,6 +456,8 @@ declare class HttpTransport {
447
456
  * observed here.
448
457
  */
449
458
  invalidateScopeLadder(): void;
459
+ /** The ladder already held, or null when none has been read. Makes no request. */
460
+ cachedScopeLadder(): ScopeLadder | null;
450
461
  /**
451
462
  * The account's ladder, from whoami, cached for 300 s (`null` included).
452
463
  * Concurrent callers share one read. A failed re-read after expiry keeps the
@@ -1881,6 +1892,9 @@ interface AsToolOptions {
1881
1892
  /**
1882
1893
  * Closed-over rung for an account with a deeper ladder. Never part of the
1883
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.
1884
1898
  */
1885
1899
  scope_path?: Record<string, string> | null;
1886
1900
  }
@@ -2105,8 +2119,23 @@ interface UnifiedFetchOptions {
2105
2119
  /**
2106
2120
  * The rung to read at, one entry per level from the first, for an account
2107
2121
  * 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.
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.
2110
2139
  */
2111
2140
  scope_path?: Record<string, string> | null;
2112
2141
  }
@@ -2311,7 +2340,7 @@ declare class SynapClient {
2311
2340
  * build when the two disagree, which is the only thing that makes a manual
2312
2341
  * publish safe.
2313
2342
  */
2314
- declare const SDK_VERSION = "0.7.0";
2343
+ declare const SDK_VERSION = "0.7.1";
2315
2344
 
2316
2345
  /**
2317
2346
  * `response_shape: "ranked"`: one list in the order the server ranked it.
package/dist/index.d.ts CHANGED
@@ -272,7 +272,16 @@ declare class ScopeAddress {
272
272
  customer_id?: string | null;
273
273
  scope_path?: Record<string, string> | null;
274
274
  });
275
- /** Options for reads (`fetch`, `*.context.fetch`, `send_message`, ...): the path is `scope_path`. */
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
+ */
276
285
  read_kwargs(): {
277
286
  user_id?: string;
278
287
  customer_id?: string;
@@ -447,6 +456,8 @@ declare class HttpTransport {
447
456
  * observed here.
448
457
  */
449
458
  invalidateScopeLadder(): void;
459
+ /** The ladder already held, or null when none has been read. Makes no request. */
460
+ cachedScopeLadder(): ScopeLadder | null;
450
461
  /**
451
462
  * The account's ladder, from whoami, cached for 300 s (`null` included).
452
463
  * Concurrent callers share one read. A failed re-read after expiry keeps the
@@ -1881,6 +1892,9 @@ interface AsToolOptions {
1881
1892
  /**
1882
1893
  * Closed-over rung for an account with a deeper ladder. Never part of the
1883
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.
1884
1898
  */
1885
1899
  scope_path?: Record<string, string> | null;
1886
1900
  }
@@ -2105,8 +2119,23 @@ interface UnifiedFetchOptions {
2105
2119
  /**
2106
2120
  * The rung to read at, one entry per level from the first, for an account
2107
2121
  * 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.
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.
2110
2139
  */
2111
2140
  scope_path?: Record<string, string> | null;
2112
2141
  }
@@ -2311,7 +2340,7 @@ declare class SynapClient {
2311
2340
  * build when the two disagree, which is the only thing that makes a manual
2312
2341
  * publish safe.
2313
2342
  */
2314
- declare const SDK_VERSION = "0.7.0";
2343
+ declare const SDK_VERSION = "0.7.1";
2315
2344
 
2316
2345
  /**
2317
2346
  * `response_shape: "ranked"`: one list in the order the server ranked it.
package/dist/index.js CHANGED
@@ -232,7 +232,16 @@ var ScopeAddress = class {
232
232
  this.customer_id = init.customer_id ?? null;
233
233
  this.scope_path = init.scope_path ?? null;
234
234
  }
235
- /** Options for reads (`fetch`, `*.context.fetch`, `send_message`, ...): the path is `scope_path`. */
235
+ /**
236
+ * Options for reads: `fetch`, `send_message`, `record_message`,
237
+ * `user.context.fetch`, `conversation.context.fetch` and
238
+ * `client.context.fetch`. The path is `scope_path`.
239
+ *
240
+ * Not for `customer.context.fetch`: that route refuses a path that names the
241
+ * identity rung (HTTP 400, it reads shared material only) and takes no
242
+ * `user_id`. Call `client.fetch(addr.read_kwargs())`, which sends the
243
+ * customer route the path cut above the identity rung.
244
+ */
236
245
  read_kwargs() {
237
246
  const out = {};
238
247
  if (this.user_id) out.user_id = this.user_id;
@@ -253,6 +262,21 @@ var ScopeAddress = class {
253
262
  return out;
254
263
  }
255
264
  };
265
+ var RESERVED_IDENTITY_KEY = "user";
266
+ function pathAboveIdentity(scopePath, ladder) {
267
+ if (!scopePath || Object.keys(scopePath).length === 0) return void 0;
268
+ const identity = ladder?.levels.find((lv) => lv.role === ROLE_IDENTITY);
269
+ const out = {};
270
+ if (!ladder || !identity) {
271
+ for (const [k, v] of Object.entries(scopePath)) if (k !== RESERVED_IDENTITY_KEY) out[k] = v;
272
+ } else {
273
+ const position = new Map(ladder.levels.map((lv) => [lv.key, lv.position]));
274
+ for (const [k, v] of Object.entries(scopePath)) {
275
+ if ((position.get(k) ?? -1) < identity.position) out[k] = v;
276
+ }
277
+ }
278
+ return Object.keys(out).length > 0 ? out : void 0;
279
+ }
256
280
  var REFRESH_HINT = "The account's ladder may not be accepted yet, or nested scoping may be off for this instance. If that changed recently, `await sdk.get_scope_ladder({ refresh: true })` re-reads it.";
257
281
  var ScopeLadder = class {
258
282
  levels;
@@ -560,6 +584,10 @@ var HttpTransport = class {
560
584
  this.#ladderInvalidated = true;
561
585
  this.#ladderRetryAt = 0;
562
586
  }
587
+ /** The ladder already held, or null when none has been read. Makes no request. */
588
+ cachedScopeLadder() {
589
+ return this.#ladderLoaded ? this.#ladder : null;
590
+ }
563
591
  /**
564
592
  * The account's ladder, from whoami, cached for 300 s (`null` included).
565
593
  * Concurrent callers share one read. A failed re-read after expiry keeps the
@@ -3227,7 +3255,7 @@ function createInstanceNamespace(credentials, cache, onTurn, fetchOrAgentModel,
3227
3255
  }
3228
3256
 
3229
3257
  // src/version.ts
3230
- var SDK_VERSION = "0.7.0";
3258
+ var SDK_VERSION = "0.7.1";
3231
3259
 
3232
3260
  // src/registry.ts
3233
3261
  var instances = /* @__PURE__ */ new Map();
@@ -5499,6 +5527,19 @@ var SynapClient = class _SynapClient {
5499
5527
  // one hands every scope fetch exactly the options it always got.
5500
5528
  ...scopePath !== void 0 && scopePath !== null && Object.keys(scopePath).length > 0 ? { scope_path: scopePath } : {}
5501
5529
  };
5530
+ const { scope_path: _fullPath, ...sharedNoPath } = shared;
5531
+ void _fullPath;
5532
+ let customerPath;
5533
+ if (scopePath && Object.keys(scopePath).length > 0 && customerId !== void 0 && customerId !== null && customerId !== "" && wants("customer")) {
5534
+ let ladder = null;
5535
+ try {
5536
+ ladder = await this.get_scope_ladder();
5537
+ } catch (e) {
5538
+ this.#warn(`Could not read the scope ladder (${e instanceof Error ? e.message : String(e)}); cutting the customer scope's path at the reserved key 'user'.`);
5539
+ }
5540
+ customerPath = pathAboveIdentity(scopePath, ladder);
5541
+ }
5542
+ const customerShared = customerPath ? { ...sharedNoPath, scope_path: customerPath } : sharedNoPath;
5502
5543
  const labels = [];
5503
5544
  const tasks = [];
5504
5545
  const present = (v) => v !== void 0 && v !== null && v !== "";
@@ -5530,14 +5571,14 @@ var SynapClient = class _SynapClient {
5530
5571
  tasks.push(this.customer.context.fetch({
5531
5572
  customer_id: customerId,
5532
5573
  conversation_id: conversationId,
5533
- ...shared
5574
+ ...customerShared
5534
5575
  }));
5535
5576
  }
5536
5577
  if (scopes !== void 0 && scopes.includes("client")) {
5537
5578
  labels.push("client");
5538
5579
  tasks.push(this.client.context.fetch({
5539
5580
  conversation_id: conversationId,
5540
- ...shared
5581
+ ...sharedNoPath
5541
5582
  }));
5542
5583
  }
5543
5584
  if (tasks.length === 0 && !(conversationState && includeConversationContext)) {