@relyio/sdk 0.18.0 → 0.19.0

package/dist/{chunk-IFKF72VJ.cjs → chunk-P23G5NXD.cjs}

@@ -3,7 +3,7 @@
 var chunkM7MWNV3Q_cjs = require('./chunk-M7MWNV3Q.cjs');
 var chunkZO6QDYJG_cjs = require('./chunk-ZO6QDYJG.cjs');
 var chunk7I3SC7SV_cjs = require('./chunk-7I3SC7SV.cjs');
-var chunkSHSK7UUY_cjs = require('./chunk-SHSK7UUY.cjs');
+var chunkNN45CSPZ_cjs = require('./chunk-NN45CSPZ.cjs');
 var chunkL6DXCKVQ_cjs = require('./chunk-L6DXCKVQ.cjs');
 
 /* RelyIO SDK - Built with ❤️ by the RelyIO Team */
@@ -171,13 +171,13 @@ var _ReadOnlyKeyError = class _ReadOnlyKeyError extends SDKError {
 chunkL6DXCKVQ_cjs.__name(_ReadOnlyKeyError, "ReadOnlyKeyError");
 var ReadOnlyKeyError = _ReadOnlyKeyError;
 var _PublishableKeyRefusedError = class _PublishableKeyRefusedError extends SDKError {
-  constructor(message = "A publishable key cannot read or write Records or run Functions", context) {
+  constructor(message = "A publishable key writes a Record only for a signed-in End user", context) {
     super(message, 403, void 0, context);
     chunkL6DXCKVQ_cjs.__publicField(this, "code", "PUBLISHABLE_KEY_REFUSED");
     chunkL6DXCKVQ_cjs.__publicField(this, "retryable", false);
   }
   getUserMessage() {
-    return "A publishable key cannot reach Records or Functions. Call them from your server with a secret key.";
+    return "A publishable key writes a Record only with a signed-in End user's token, and runs only a Function declaring endUsers. Send the End user's token, declare endUsers on the Function, or call it from your server with a secret key.";
   }
 };
 chunkL6DXCKVQ_cjs.__name(_PublishableKeyRefusedError, "PublishableKeyRefusedError");
@@ -394,6 +394,19 @@ var _InvalidApiKeyError = class _InvalidApiKeyError extends SDKError {
 };
 chunkL6DXCKVQ_cjs.__name(_InvalidApiKeyError, "InvalidApiKeyError");
 var InvalidApiKeyError = _InvalidApiKeyError;
+var _EndUserTokenInvalidError = class _EndUserTokenInvalidError extends SDKError {
+  constructor(message, reason, context) {
+    super(message, 401, void 0, context);
+    this.reason = reason;
+    chunkL6DXCKVQ_cjs.__publicField(this, "code", "END_USER_TOKEN_INVALID");
+    chunkL6DXCKVQ_cjs.__publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    return "Your session is not valid. Please sign in again.";
+  }
+};
+chunkL6DXCKVQ_cjs.__name(_EndUserTokenInvalidError, "EndUserTokenInvalidError");
+var EndUserTokenInvalidError = _EndUserTokenInvalidError;
 
 // src/errors/network-errors.ts
 var _NetworkError = class _NetworkError extends SDKError {
@@ -581,7 +594,7 @@ var _ErrorMapper = class _ErrorMapper {
       return new NetworkError(`HTTP ${status}: ${statusText}`.trim(), status, void 0, context);
     }
     const retryAfterMs = parseRetryAfterMs(
-      headerValue(headers, chunkSHSK7UUY_cjs.HEADER_RETRY_AFTER.name),
+      headerValue(headers, chunkNN45CSPZ_cjs.HEADER_RETRY_AFTER.name),
       Date.now()
     );
     return this.fromContractCode(refusal, status, context, retryAfterMs);
@@ -595,6 +608,9 @@ var _ErrorMapper = class _ErrorMapper {
       case "INVALID_API_KEY": {
         return new InvalidApiKeyError(message, void 0, context);
       }
+      case "END_USER_TOKEN_INVALID": {
+        return new EndUserTokenInvalidError(message, endUserTokenReasonOf(refusal), context);
+      }
       case "ACCESS_DENIED": {
         return new AuthorizationError(message, 403, void 0, context);
       }
@@ -802,6 +818,15 @@ function violationsOf(refusal) {
   }));
 }
 chunkL6DXCKVQ_cjs.__name(violationsOf, "violationsOf");
+function endUserTokenReasonOf(refusal) {
+  const reason = detailString(refusal, "reason");
+  return isEndUserTokenReason(reason) ? reason : void 0;
+}
+chunkL6DXCKVQ_cjs.__name(endUserTokenReasonOf, "endUserTokenReasonOf");
+function isEndUserTokenReason(value) {
+  return value !== void 0 && chunkNN45CSPZ_cjs.END_USER_TOKEN_REFUSAL_REASONS.includes(value);
+}
+chunkL6DXCKVQ_cjs.__name(isEndUserTokenReason, "isEndUserTokenReason");
 
 // src/http/api-routes.ts
 function fillPath(template, params) {
@@ -977,7 +1002,7 @@ var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
 ]);
 function isReplaySafe(request) {
   if (IDEMPOTENT_METHODS.has(request.method.toUpperCase())) return true;
-  return headerValue(request.headers, chunkSHSK7UUY_cjs.HEADER_IDEMPOTENCY_KEY.name) !== void 0;
+  return headerValue(request.headers, chunkNN45CSPZ_cjs.HEADER_IDEMPOTENCY_KEY.name) !== void 0;
 }
 chunkL6DXCKVQ_cjs.__name(isReplaySafe, "isReplaySafe");
 var UNREACHABLE_CODES = /* @__PURE__ */ new Set(["ECONNREFUSED", "ENOTFOUND"]);
@@ -1174,22 +1199,33 @@ var _HttpClient = class _HttpClient {
    * constructor accepts one so that a module-scope client can be evaluated by a
    * build that holds no key (REL-1120) — and so does one whose `setApiKey` was
    * given none.
+   *
+   * The End user's token is asked for once, after the key is known to be there and before the first
+   * attempt — of `getToken`, the nearest view's function, or the configuration's — so every retry
+   * of one call sends the token its first attempt sent. See `RelyIOConfig.getToken`.
    */
-  async request(config) {
+  async request(config, getToken) {
     if (this.view !== void 0) {
-      return this.view.client.request({
-        ...config,
-        headers: layerHeaders(this.view.headers, config.headers)
-      });
+      return this.view.client.request(
+        { ...config, headers: layerHeaders(this.view.headers, config.headers) },
+        getToken ?? this.view.getToken
+      );
     }
     if (config.timeout !== void 0) assertRequestTimeout(config.timeout);
     const mergedConfig = this.mergeRequestConfig(config);
-    if (presentKey(headerValue(mergedConfig.headers, API_KEY_HEADER)) === void 0) {
+    if (presentCredential(headerValue(mergedConfig.headers, API_KEY_HEADER)) === void 0) {
       throw new MissingApiKeyError(
         "`apiKey` is missing: this client holds no API key, so the request was not sent. Pass `apiKey` to createClient \u2014 the documented setup reads it from RELYIO_API_KEY.",
         { url: mergedConfig.url, method: mergedConfig.method, sent: false }
       );
     }
+    const tokenSource = getToken ?? this.connection.config.getToken;
+    if (tokenSource !== void 0) {
+      const token = presentCredential(await tokenSource());
+      mergedConfig.headers = layerHeaders(mergedConfig.headers ?? {}, {
+        [END_USER_HEADER]: token ?? null
+      });
+    }
     this.log("debug", "Making request", {
       method: mergedConfig.method,
       url: mergedConfig.url
@@ -1233,7 +1269,7 @@ var _HttpClient = class _HttpClient {
         });
         if (preview !== void 0 && answersUnknownDataset(sdkError, preview)) {
           rememberUnknownPreview(preview);
-          return this.request(config);
+          return this.request(config, getToken);
         }
         this.log("error", "Request failed after all retries", {
           error: sdkError.toJSON(),
@@ -1454,10 +1490,17 @@ var _ControlledHttpClient = class _ControlledHttpClient extends HttpClient {
    * retries and `fetch` are this client's as they are when each request is sent, so a later
    * `configure()` or `setApiKey()` on this client reaches the view, and one on the view reaches
    * this client. `client.with({ dataset })` is one (REL-2417).
+   *
+   * `options.getToken` is the End user's token function the view asks in place of this client's,
+   * and of any view it is made from: `client.with({ getToken })` (REL-3882).
    */
-  withHeaders(headers) {
+  withHeaders(headers, options = {}) {
     const view = new _ControlledHttpClient(this.connection.config);
-    view.view = { client: this, headers: { ...headers } };
+    view.view = {
+      client: this,
+      headers: { ...headers },
+      ...options.getToken === void 0 ? {} : { getToken: options.getToken }
+    };
     return view;
   }
   /**
@@ -1479,7 +1522,7 @@ var _ControlledHttpClient = class _ControlledHttpClient extends HttpClient {
    * Replace the key every later request sends as `X-API-Key`, and the `apiKey` the configuration
    * reports.
    *
-   * The key is read the way construction reads it (`presentKey`): an absent, empty or blank key is
+   * The key is read the way construction reads it (`presentCredential`): an absent, empty or blank key is
    * no key, so the header is dropped and the next request is refused with `MissingApiKeyError`
    * before anything is sent. A key header of any other spelling — one given in `headers` — goes
    * too, from the headers sent and from the headers the configuration reports, so the old key is
@@ -1500,7 +1543,7 @@ var _ControlledHttpClient = class _ControlledHttpClient extends HttpClient {
     this.connection = {
       ...this.connection,
       defaultHeaders: layerHeaders(this.connection.defaultHeaders, {
-        [API_KEY_HEADER]: presentKey(apiKey) ?? null
+        [API_KEY_HEADER]: presentCredential(apiKey) ?? null
       })
     };
   }
@@ -1509,6 +1552,7 @@ chunkL6DXCKVQ_cjs.__name(_ControlledHttpClient, "ControlledHttpClient");
 var ControlledHttpClient = _ControlledHttpClient;
 var API_KEY_HEADER = "X-API-Key";
 var DATASET_HEADER = "X-RelyIO-Dataset";
+var END_USER_HEADER = chunkNN45CSPZ_cjs.HEADER_END_USER.name;
 function derivedPreviewIn(headers) {
   const dataset = headerValue(headers, DATASET_HEADER);
   return dataset !== void 0 && isDerivedPreview(dataset) ? dataset : void 0;
@@ -1527,7 +1571,7 @@ function connectionFor(config) {
   const defaultHeaders = layerHeaders(
     layerHeaders({ "Content-Type": "application/json" }, config.headers),
     {
-      [API_KEY_HEADER]: presentKey(config.apiKey),
+      [API_KEY_HEADER]: presentCredential(config.apiKey),
       [DATASET_HEADER]: config.dataset,
       // Only outside a browser, which controls this header. "A browser" is the core's one
       // definition, `isBrowser()` — every environment question in this file asks it.
@@ -1559,10 +1603,10 @@ function layerHeaders(base, over) {
   return layered;
 }
 chunkL6DXCKVQ_cjs.__name(layerHeaders, "layerHeaders");
-function presentKey(value) {
+function presentCredential(value) {
   return typeof value === "string" && value.trim() !== "" ? value : void 0;
 }
-chunkL6DXCKVQ_cjs.__name(presentKey, "presentKey");
+chunkL6DXCKVQ_cjs.__name(presentCredential, "presentCredential");
 function credentialsModeFor(includeCredentials) {
   return includeCredentials ? "include" : "same-origin";
 }
@@ -1571,7 +1615,7 @@ chunkL6DXCKVQ_cjs.__name(credentialsModeFor, "credentialsModeFor");
 // src/http/write-options.ts
 function versionCheckOf(entry) {
   const { id, locale, version, sharedVersion } = entry._metadata;
-  return { id, locale, ifMatch: chunkSHSK7UUY_cjs.entityTag({ entryUid: id, locale, version, sharedVersion }) };
+  return { id, locale, ifMatch: chunkNN45CSPZ_cjs.entityTag({ entryUid: id, locale, version, sharedVersion }) };
 }
 chunkL6DXCKVQ_cjs.__name(versionCheckOf, "versionCheckOf");
 function mintIdempotencyKey() {
@@ -1583,11 +1627,11 @@ chunkL6DXCKVQ_cjs.__name(mintIdempotencyKey, "mintIdempotencyKey");
 function writeHeaders(options) {
   const headers = {};
   if (options?.ifMatch !== void 0) {
-    headers[chunkSHSK7UUY_cjs.HEADER_IF_MATCH.name] = options.ifMatch;
+    headers[chunkNN45CSPZ_cjs.HEADER_IF_MATCH.name] = options.ifMatch;
   }
   const idempotencyKey = options?.idempotencyKey ?? mintIdempotencyKey();
   if (idempotencyKey !== void 0) {
-    headers[chunkSHSK7UUY_cjs.HEADER_IDEMPOTENCY_KEY.name] = idempotencyKey;
+    headers[chunkNN45CSPZ_cjs.HEADER_IDEMPOTENCY_KEY.name] = idempotencyKey;
   }
   return Object.keys(headers).length > 0 ? headers : void 0;
 }
@@ -1684,7 +1728,7 @@ function writeDocumentTerms(query, options, clientLocale) {
     query.include = options.include.join(",");
   }
   writeLocale(query, options.locale ?? clientLocale);
-  if (typeof options.fresh === "string") query[chunkSHSK7UUY_cjs.FRESH_PARAMETER] = options.fresh;
+  if (typeof options.fresh === "string") query[chunkNN45CSPZ_cjs.FRESH_PARAMETER] = options.fresh;
 }
 chunkL6DXCKVQ_cjs.__name(writeDocumentTerms, "writeDocumentTerms");
 function writeLocale(query, locale) {
@@ -2878,7 +2922,8 @@ var _RecordsClient = class _RecordsClient {
    * Store a Record, live the moment it lands. Values that break the Record type's fields are
    * refused with `ValidationError` naming each field, and nothing is stored. Values a unique set of
    * the type claims, held by another Record, are refused with `ResourceConflictError` — its
-   * `blockage` is `{ kind: 'value-taken', facts: { fields, recordId } }` (REL-3782).
+   * `blockage` is `{ kind: 'value-taken', facts: { fields, recordId } }` (REL-3782) — with no
+   * `recordId` for an End user's write, whose read Policy may hide the holder (REL-3863).
    */
   async create(fields, options = {}) {
     return this.httpClient.fetchPayload(
@@ -3272,7 +3317,7 @@ chunkL6DXCKVQ_cjs.__name(originOf, "originOf");
 
 // src/changes/live-edge.ts
 var LIVE_KEEPALIVE_INTERVAL_MS = 3e4;
-var LIVE_SOCKET_OPEN_TIMEOUT_MS = chunkSHSK7UUY_cjs.VISITOR_POLL_INTERVAL_MS;
+var LIVE_SOCKET_OPEN_TIMEOUT_MS = chunkNN45CSPZ_cjs.VISITOR_POLL_INTERVAL_MS;
 var LIVE_POLLS_BEFORE_SOCKET = 4;
 async function* subscribeLiveEdge(client, options = {}) {
   const { signal } = options;
@@ -3342,12 +3387,12 @@ async function* followSocket(socket, reach, options) {
           return "unopened";
         }
         case "message": {
-          if (event.data === chunkSHSK7UUY_cjs.VISITOR_KEEPALIVE.response) continue;
-          const frame = typeof event.data === "string" ? chunkSHSK7UUY_cjs.parseVisitorFrame(event.data) : null;
+          if (event.data === chunkNN45CSPZ_cjs.VISITOR_KEEPALIVE.response) continue;
+          const frame = typeof event.data === "string" ? chunkNN45CSPZ_cjs.parseVisitorFrame(event.data) : null;
           if (frame === null)
             throw unreadable(`a frame the wire does not declare: ${sample(event.data)}`);
           switch (frame.type) {
-            case chunkSHSK7UUY_cjs.VISITOR_FRAMES.opened: {
+            case chunkNN45CSPZ_cjs.VISITOR_FRAMES.opened: {
               caughtUp = true;
               inbox.caughtUp();
               reach.position = frame.cursor;
@@ -3355,7 +3400,7 @@ async function* followSocket(socket, reach, options) {
               options.reached?.(frame.cursor);
               continue;
             }
-            case chunkSHSK7UUY_cjs.VISITOR_FRAMES.changes: {
+            case chunkNN45CSPZ_cjs.VISITOR_FRAMES.changes: {
               const prior = reach.position;
               if (prior === void 0) throw unreadable("changes before the socket had a position");
               for (const change of changesOf(frame.changes, frame.cursor, prior)) {
@@ -3366,7 +3411,7 @@ async function* followSocket(socket, reach, options) {
               if (frame.changes.length === 0) options.reached?.(frame.cursor);
               continue;
             }
-            case chunkSHSK7UUY_cjs.VISITOR_FRAMES.resync: {
+            case chunkNN45CSPZ_cjs.VISITOR_FRAMES.resync: {
               await expire(frame.reason, frame.cursor, options);
               if (isAborted(signal)) return "aborted";
               reach.position = frame.cursor;
@@ -3438,7 +3483,7 @@ function socketInbox(socket, signal) {
           return;
         }
         heard = false;
-        if (socket.readyState === SOCKET_OPEN) socket.send(chunkSHSK7UUY_cjs.VISITOR_KEEPALIVE.request);
+        if (socket.readyState === SOCKET_OPEN) socket.send(chunkNN45CSPZ_cjs.VISITOR_KEEPALIVE.request);
       }, LIVE_KEEPALIVE_INTERVAL_MS);
     },
     caughtUp() {
@@ -3474,19 +3519,19 @@ var AFTER_A_CLOSE = {
   "back-off": "Retrying after a back-off of at least a minute, without polling, which the same admission refuses."
 };
 function closeRetryOf(code) {
-  if (hasOwn(chunkSHSK7UUY_cjs.VISITOR_CLOSE_RETRY, code)) return chunkSHSK7UUY_cjs.VISITOR_CLOSE_RETRY[code];
+  if (hasOwn(chunkNN45CSPZ_cjs.VISITOR_CLOSE_RETRY, code)) return chunkNN45CSPZ_cjs.VISITOR_CLOSE_RETRY[code];
   return code < 4e3 ? "retry" : "stop";
 }
 chunkL6DXCKVQ_cjs.__name(closeRetryOf, "closeRetryOf");
 var CLOSE_MEANING = {
-  [chunkSHSK7UUY_cjs.VISITOR_CLOSE_CODES.requestInvalid]: "the edge could not read the request \u2014 a malformed cursor or filter",
-  [chunkSHSK7UUY_cjs.VISITOR_CLOSE_CODES.keyRefused]: "the key is not a publishable key the edge accepts \u2014 unknown, revoked or expired",
-  [chunkSHSK7UUY_cjs.VISITOR_CLOSE_CODES.originRefused]: "this page\u2019s origin is not on the publishable key\u2019s allowed origins",
-  [chunkSHSK7UUY_cjs.VISITOR_CLOSE_CODES.datasetRefused]: "`dataset` names no dataset the key reaches",
-  [chunkSHSK7UUY_cjs.VISITOR_CLOSE_CODES.unavailable]: "the edge could not serve this connection just now \u2014 it could not reach what it needed",
-  [chunkSHSK7UUY_cjs.VISITOR_CLOSE_CODES.allowanceReached]: "the project holds as many live connections as its plan allows",
-  [chunkSHSK7UUY_cjs.VISITOR_CLOSE_CODES.addressLimitReached]: "this address holds as many live connections to the project as one address may",
-  [chunkSHSK7UUY_cjs.VISITOR_CLOSE_CODES.ceilingReached]: "the project is at its safety ceiling of live connections"
+  [chunkNN45CSPZ_cjs.VISITOR_CLOSE_CODES.requestInvalid]: "the edge could not read the request \u2014 a malformed cursor or filter",
+  [chunkNN45CSPZ_cjs.VISITOR_CLOSE_CODES.keyRefused]: "the key is not a publishable key the edge accepts \u2014 unknown, revoked or expired",
+  [chunkNN45CSPZ_cjs.VISITOR_CLOSE_CODES.originRefused]: "this page\u2019s origin is not on the publishable key\u2019s allowed origins",
+  [chunkNN45CSPZ_cjs.VISITOR_CLOSE_CODES.datasetRefused]: "`dataset` names no dataset the key reaches",
+  [chunkNN45CSPZ_cjs.VISITOR_CLOSE_CODES.unavailable]: "the edge could not serve this connection just now \u2014 it could not reach what it needed",
+  [chunkNN45CSPZ_cjs.VISITOR_CLOSE_CODES.allowanceReached]: "the project holds as many live connections as its plan allows",
+  [chunkNN45CSPZ_cjs.VISITOR_CLOSE_CODES.addressLimitReached]: "this address holds as many live connections to the project as one address may",
+  [chunkNN45CSPZ_cjs.VISITOR_CLOSE_CODES.ceilingReached]: "the project is at its safety ceiling of live connections"
 };
 async function* followPolls(client, request, reach, options) {
   const { signal } = options;
@@ -3514,7 +3559,7 @@ async function* followPolls(client, request, reach, options) {
       if (starting) options.reached?.(answer.cursor);
     }
     starting = false;
-    await sleep(chunkSHSK7UUY_cjs.VISITOR_POLL_INTERVAL_MS, signal);
+    await sleep(chunkNN45CSPZ_cjs.VISITOR_POLL_INTERVAL_MS, signal);
   }
   return isAborted(signal) ? "aborted" : "socket";
 }
@@ -3556,7 +3601,7 @@ async function pollOnce2(client, request, since, signal) {
     }
     const body = parseJson(text);
     if (!response.ok) throw refusedPoll(response, body, context);
-    const answer = chunkSHSK7UUY_cjs.readVisitorPollAnswer(isRecord(body) ? body["data"] : void 0);
+    const answer = chunkNN45CSPZ_cjs.readVisitorPollAnswer(isRecord(body) ? body["data"] : void 0);
     if (answer === null)
       throw unreadable(`a poll answer the wire does not declare: ${sample(text)}`);
     return answer;
@@ -3576,13 +3621,13 @@ function refusedPoll(response, body, context) {
     { ...context, method: "GET" }
   );
   const refusal = readError(body);
-  if (refusal === void 0 || !hasOwn(chunkSHSK7UUY_cjs.VISITOR_POLL_RETRY, refusal.code)) return mapped;
+  if (refusal === void 0 || !hasOwn(chunkNN45CSPZ_cjs.VISITOR_POLL_RETRY, refusal.code)) return mapped;
   const code = refusal.code;
   const retryAfterMs = parseRetryAfterMs(headerValue(headers, "Retry-After"), Date.now());
   return new LiveEdgeError(
     `The live edge refused a poll (${code}): ${refusal.messages[0] ?? mapped.message}`,
     { kind: "refused", code },
-    chunkSHSK7UUY_cjs.VISITOR_POLL_RETRY[code],
+    chunkNN45CSPZ_cjs.VISITOR_POLL_RETRY[code],
     {
       statusCode: response.status,
       cause: mapped,
@@ -3610,17 +3655,17 @@ function edgeRequest(client, filter) {
 chunkL6DXCKVQ_cjs.__name(edgeRequest, "edgeRequest");
 function edgeUrl(request, since, transport, clientId) {
   const url = new URL(request.base.href);
-  url.pathname = `${url.pathname.replace(/\/+$/, "")}${chunkSHSK7UUY_cjs.VISITOR_LIVE_PATH}`;
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}${chunkNN45CSPZ_cjs.VISITOR_LIVE_PATH}`;
   if (transport === "socket") url.protocol = url.protocol === "http:" ? "ws:" : "wss:";
   const query = new URLSearchParams();
-  if (request.key !== void 0) query.set(chunkSHSK7UUY_cjs.VISITOR_QUERY.key, request.key);
+  if (request.key !== void 0) query.set(chunkNN45CSPZ_cjs.VISITOR_QUERY.key, request.key);
   if (request.dataset !== void 0 && request.dataset !== "") {
-    query.set(chunkSHSK7UUY_cjs.VISITOR_QUERY.dataset, request.dataset);
+    query.set(chunkNN45CSPZ_cjs.VISITOR_QUERY.dataset, request.dataset);
   }
-  if (since !== void 0) query.set(chunkSHSK7UUY_cjs.VISITOR_QUERY.since, since);
-  if (request.types !== void 0) query.set(chunkSHSK7UUY_cjs.VISITOR_QUERY.types, request.types.join(","));
-  if (request.ids !== void 0) query.set(chunkSHSK7UUY_cjs.VISITOR_QUERY.ids, request.ids.join(","));
-  if (transport === "poll" && clientId !== void 0) query.set(chunkSHSK7UUY_cjs.VISITOR_QUERY.client, clientId);
+  if (since !== void 0) query.set(chunkNN45CSPZ_cjs.VISITOR_QUERY.since, since);
+  if (request.types !== void 0) query.set(chunkNN45CSPZ_cjs.VISITOR_QUERY.types, request.types.join(","));
+  if (request.ids !== void 0) query.set(chunkNN45CSPZ_cjs.VISITOR_QUERY.ids, request.ids.join(","));
+  if (transport === "poll" && clientId !== void 0) query.set(chunkNN45CSPZ_cjs.VISITOR_QUERY.client, clientId);
   url.search = query.toString();
   return url.href;
 }
@@ -3683,7 +3728,7 @@ async function callFunction(http, name, input, options) {
     body: { input },
     headers: {
       ...readHeaders({ dataset: options.dataset }),
-      ...options.idempotencyKey === void 0 ? {} : { [chunkSHSK7UUY_cjs.HEADER_IDEMPOTENCY_KEY.name]: options.idempotencyKey }
+      ...options.idempotencyKey === void 0 ? {} : { [chunkNN45CSPZ_cjs.HEADER_IDEMPOTENCY_KEY.name]: options.idempotencyKey }
     },
     timeout: options.timeout ?? FUNCTION_CALL_TIMEOUT_MS,
     ...signalOf(options)
@@ -3733,7 +3778,7 @@ function transportOf(options) {
   return {
     ...signalOf(options),
     ...headers === void 0 ? {} : { headers },
-    ...typeof options.fresh === "string" ? { query: { [chunkSHSK7UUY_cjs.FRESH_PARAMETER]: options.fresh } } : {}
+    ...typeof options.fresh === "string" ? { query: { [chunkNN45CSPZ_cjs.FRESH_PARAMETER]: options.fresh } } : {}
   };
 }
 chunkL6DXCKVQ_cjs.__name(transportOf, "transportOf");
@@ -3914,7 +3959,7 @@ async function runAdhocQuery(http, query, clientLocale) {
   const terms = {};
   if (query.cursor !== void 0) terms.cursor = query.cursor;
   writeLocale(terms, query.locale ?? clientLocale);
-  if (typeof query.fresh === "string") terms[chunkSHSK7UUY_cjs.FRESH_PARAMETER] = query.fresh;
+  if (typeof query.fresh === "string") terms[chunkNN45CSPZ_cjs.FRESH_PARAMETER] = query.fresh;
   const parameters = { ...query.params };
   const body = {
     query: {
@@ -3949,7 +3994,7 @@ async function runNamedQuery(http, name, options, clientLocale) {
   const locale = options.locale ?? clientLocale;
   const terms = {};
   if (locale !== void 0 && locale !== "") terms.locale = locale;
-  if (typeof options.fresh === "string") terms[chunkSHSK7UUY_cjs.FRESH_PARAMETER] = options.fresh;
+  if (typeof options.fresh === "string") terms[chunkNN45CSPZ_cjs.FRESH_PARAMETER] = options.fresh;
   const headers = readHeaders(options);
   const response = await http.send(
     "/v1/queries/{name}",
@@ -4119,6 +4164,9 @@ function validateConfig(config) {
   if (config.webSocket != null && typeof config.webSocket !== "function") {
     throw new Error("webSocket must be a WebSocket class");
   }
+  if (config.getToken != null && typeof config.getToken !== "function") {
+    throw new Error("getToken must be a function that answers the End user\u2019s token, or null");
+  }
   if (config.timeout != null) assertRequestTimeout(config.timeout);
   if (config.retryAttempts != null && !(Number.isInteger(config.retryAttempts) && config.retryAttempts >= 1)) {
     throw new Error(
@@ -4180,7 +4228,7 @@ function withPreview(configured) {
   if (configured.dataset !== void 0 || !isPreviewKey(configured.apiKey)) return configured;
   const preview = readPreviewAtRequest();
   if (preview.state !== "preview") return configured;
-  const dataset = chunkSHSK7UUY_cjs.previewDatasetSlug(preview.branch);
+  const dataset = chunkNN45CSPZ_cjs.previewDatasetSlug(preview.branch);
   noteDerivedPreview(dataset);
   if (!previewNotified) {
     previewNotified = true;
@@ -4247,7 +4295,10 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
      * `createClient()` made, which reads its own.
      */
     chunkL6DXCKVQ_cjs.__publicField(this, "parent");
-    /** What `with()` gave this client over its parent's: the locale and dataset it names, and no other. */
+    /**
+     * What `with()` gave this client over its parent's: the locale, dataset and End user's token
+     * function it names, and no other.
+     */
     chunkL6DXCKVQ_cjs.__publicField(this, "defaults", {});
     /** The live edge's poll client id: chosen once, when first needed, and kept for this client's life. */
     chunkL6DXCKVQ_cjs.__publicField(this, "_liveClientId");
@@ -4258,7 +4309,9 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
      * all or none (REL-3774).
      *
      * A Record is an app's data, written by your server with a secret key and live the moment it
-     * lands; a publishable key is refused on every Record route (`PUBLISHABLE_KEY_REFUSED`).
+     * lands. A publishable key reads the Records a Record type's read Policy grants it (spec 4,
+     * REL-3883), and writes them only for the End user whose token it carries, as the type's write
+     * Policy allows (REL-3884); with no token it writes nothing (`PUBLISHABLE_KEY_REFUSED`).
      *
      * @example
      * ```typescript
@@ -4742,6 +4795,9 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * const { data } = await staging.content('post').list({ limit: 10 })
    *
    * const french = relyio.with({ locale: 'fr-FR' }) // ← autocompletes the schema's locales
+   *
+   * // Every request this one sends carries the signed-in End user's token (REL-3882)
+   * const visitor = relyio.with({ getToken: () => session.getToken() })
    * ```
    */
   with(defaults) {
@@ -4755,14 +4811,16 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   }
   /** Make this client one `with()` made from `parent`: see {@link with}. */
   follow(parent, defaults) {
-    const { locale, dataset } = defaults;
+    const { locale, dataset, getToken } = defaults;
     this.parent = parent;
     this.defaults = {
       ...locale === void 0 ? {} : { locale },
-      ...dataset === void 0 ? {} : { dataset }
+      ...dataset === void 0 ? {} : { dataset },
+      ...getToken === void 0 ? {} : { getToken }
     };
     this.httpClient = parent.httpClient.withHeaders(
-      dataset === void 0 ? {} : { [DATASET_HEADER]: dataset }
+      dataset === void 0 ? {} : { [DATASET_HEADER]: dataset },
+      getToken === void 0 ? {} : { getToken }
     );
   }
   /**
@@ -4822,6 +4880,7 @@ exports.ChangesExpiredError = ChangesExpiredError;
 exports.ConnectionError = ConnectionError;
 exports.ContentClient = ContentClient;
 exports.DefaultRetryPolicy = DefaultRetryPolicy;
+exports.EndUserTokenInvalidError = EndUserTokenInvalidError;
 exports.ErrorMapper = ErrorMapper;
 exports.FileUploadError = FileUploadError;
 exports.FileValidationError = FileValidationError;
@@ -4874,5 +4933,5 @@ exports.serviceInstructedDelayMs = serviceInstructedDelayMs;
 exports.sleep = sleep;
 exports.validateFile = validateFile;
 exports.versionCheckOf = versionCheckOf;
-//# sourceMappingURL=chunk-IFKF72VJ.cjs.map
-//# sourceMappingURL=chunk-IFKF72VJ.cjs.map
+//# sourceMappingURL=chunk-P23G5NXD.cjs.map
+//# sourceMappingURL=chunk-P23G5NXD.cjs.map