@ariestools/aries-datalake-client 0.1.20 → 0.1.21

package/README.md

@@ -5,7 +5,7 @@ REST clients for the Aries datalake control and data planes, with Node-only loca
 ## Entry points
 
 - `@ariestools/aries-datalake-client` is the Node entry point. It includes the REST clients plus local filesystem-backed clients, credentials, defaults, and `ARIES_HOME` helpers.
-- `@ariestools/aries-datalake-client/browser` is the browser entry point. It exports only REST clients, their interfaces, the asynchronous token-supplier contract, and browser-safe datalake wire contracts.
+- `@ariestools/aries-datalake-client/browser` is the browser entry point. It exports REST clients, the composite client, their interfaces, the asynchronous token-supplier contract, and browser-safe datalake wire contracts.
 
 Use an asynchronous token supplier that is invoked for each request. The application adapter may return a still-valid short-lived token from page memory or request a fresh wallet JWT through the XL1 browser wallet gateway:
 
@@ -37,6 +37,80 @@ const payloads = new RestPayloadsClient({
 
 The supplier receives the exact control-plane audience or datalake id. Treat its return value as a sensitive, short-lived bearer token: cache it only in page memory when useful, and never persist it in browser storage or logs. The wallet gateway controls key access; the Aries HTTP services independently verify audience, signature, origin, scope, signer identity, and live ACL state.
 
+## Multiple required datalakes
+
+`CompositePayloadsClient` writes each target's eligible subset and verifies it by
+reading the content back. Configure a complete S3 collection alongside a selected
+Auto Drive collection using already authenticated `RestPayloadsClient` instances:
+
+```ts
+import { CompositePayloadsClient, type RestPayloadsClient } from '@ariestools/aries-datalake-client/browser'
+import { asAnyPayload, PayloadBuilder } from '@xyo-network/sdk'
+
+declare const autoDriveClient: RestPayloadsClient
+declare const s3Client: RestPayloadsClient
+
+const composite = new CompositePayloadsClient({
+  identify: async (payload) => {
+    const canonical = asAnyPayload(payload, true)
+    return {
+      hash: await PayloadBuilder.hash(canonical),
+      dataHash: await PayloadBuilder.dataHash(canonical),
+    }
+  },
+  targets: [
+    {
+      name: 'auto-drive',
+      client: autoDriveClient,
+      policy: {
+        mode: 'selected',
+        allowedSchemas: ['com.example.smallrecord'],
+        maxPayloadBytes: 4096, // Example deployment limit, not a provider default.
+        revision: 'v1',
+      },
+    },
+    { name: 's3', client: s3Client, policy: { mode: 'all' } },
+  ],
+})
+
+const result = await composite.insertWithReceipts([
+  { schema: 'com.example.smallrecord', value: 1 },
+  { schema: 'com.example.other', value: 2 },
+])
+const read = await composite.getWithReceipts(result.acknowledged.map(payload => payload._hash))
+```
+
+All targets are required for their eligible subset. A selected policy requires
+an explicit allowlist and positive byte limit; an empty list selects nothing.
+`disallowedSchemas` takes precedence. `schemaMaxPayloadBytes` may tighten the
+global byte limit, and `isValid` may supply a trusted structural validator.
+Sizes count UTF-8 JSON including client metadata and excluding storage metadata.
+The receiving service must enforce its policy independently; this client does not
+authorize permanent uploads or implement service quotas.
+
+`insert(payloads)` returns the verified acknowledgment array, including duplicates;
+`insertWithReceipts(payloads)` also returns per-target eligibility and outcomes.
+A rejected expected-eligible item or failed required target throws
+`CompositePayloadsWriteError`. Its `result` retains verified partial success and
+sanitized receipts, not raw provider errors. A complete target's success does not
+satisfy a different target's obligation. Callers own durable retry state and
+policy-revision coordination; this client does not resume a failed operation.
+
+`get(hashes)` and `getMany(hashes)` return verified payload arrays.
+`getWithReceipts(hashes)` adds source attribution. Reads try targets in declared
+order for unresolved hashes only. Provider errors or corrupt responses throw
+`CompositePayloadsReadError`; they are not silently converted into misses.
+Reads never copy content between targets. Supply canonical XYO `PayloadBuilder`
+hashes through `identify`; the composite package itself adds no XYO runtime
+dependency to browser consumers.
+
+Only flat payload bodies are accepted. Validate and flatten known hydrated
+protocol envelopes before insertion. There is no global sequence, clear, delete,
+or usage API and no automatic registration into an XL1 connection. The
+payload-array `insert`/`get` methods are intended for a protocol adapter; keep
+the SDK's exact transaction-content acknowledgment check in that adapter.
+Successful read-back is readable storage, not proof of provider network archival.
+
 ## Explicit public payload reads
 
 Use `RestPublicPayloadsReader` when the provider has granted public viewer access

package/dist/browser/CompositePayloadsClient.d.ts

@@ -0,0 +1,91 @@
+import type { Payload, WithStorageMeta } from '@ariestools/aries-datalake-core/browser';
+import type { PayloadsClient } from './PayloadsClient.ts';
+/** Supply the canonical XYO PayloadBuilder hashes, without adding its runtime to browser clients. */
+export interface CompositePayloadIdentity {
+    dataHash: string;
+    hash: string;
+}
+export interface CompositePayloadsPolicy {
+    /** Required for selected mode; an empty array selects nothing. */
+    allowedSchemas?: readonly string[];
+    disallowedSchemas?: readonly string[];
+    /** Trusted local validator; receiving services must independently enforce their policy. */
+    isValid?: (payload: Payload) => boolean;
+    /** Required for selected mode. Measured as UTF-8 JSON, before compression. */
+    maxPayloadBytes?: number;
+    /** Explicitly choose a complete collection or an allowlisted collection. */
+    mode: 'all' | 'selected';
+    revision?: string;
+    /** Per-schema limits can only tighten the overall payload limit. */
+    schemaMaxPayloadBytes?: Readonly<Record<string, number>>;
+}
+export interface CompositePayloadsTarget {
+    client: Pick<PayloadsClient, 'getMany' | 'insert'>;
+    /** A non-secret identifier, not an endpoint or credential. Also determines receipt provenance. */
+    name: string;
+    policy: CompositePayloadsPolicy;
+}
+export interface CompositePayloadsClientOptions {
+    /** Trusted canonical XYO hash implementation. Storage metadata must not affect either hash. */
+    identify: (payload: Payload) => Promise<CompositePayloadIdentity>;
+    /** Every target is required for its eligible subset. Array order is read priority. */
+    targets: readonly CompositePayloadsTarget[];
+}
+export interface CompositePayloadExclusion {
+    hash: string;
+    reason: 'schema' | 'size' | 'validation';
+}
+export interface CompositeWriteReceipt {
+    acknowledged: string[];
+    eligible: string[];
+    error?: 'provider_error' | 'invalid_response' | 'policy_rejected' | 'incomplete_readback';
+    excluded: CompositePayloadExclusion[];
+    policyRevision?: string;
+    rejected: string[];
+    status: 'complete' | 'excluded' | 'failed';
+    target: string;
+}
+export interface CompositeWriteResult {
+    /** Verified union, including previously stored duplicates. Not an aggregate success on an error. */
+    acknowledged: WithStorageMeta<Payload>[];
+    receipts: CompositeWriteReceipt[];
+}
+export declare class CompositePayloadsWriteError extends Error {
+    readonly result: CompositeWriteResult;
+    constructor(result: CompositeWriteResult);
+}
+export interface CompositeReadReceipt {
+    error?: 'provider_error' | 'invalid_response';
+    found: string[];
+    requested: string[];
+    target: string;
+}
+export interface CompositeReadResult {
+    payloads: WithStorageMeta<Payload>[];
+    receipts: CompositeReadReceipt[];
+    sources: Record<string, string>;
+}
+export declare class CompositePayloadsReadError extends Error {
+    readonly result: CompositeReadResult;
+    constructor(result: CompositeReadResult);
+}
+/**
+ * Required-subset writes and verified hash reads across named datalakes.
+ * Accepts flat payload bodies only. Callers validate and flatten protocol envelopes first.
+ * Deliberately has no global next/clear/delete/usage: store-local sequences and lifecycles differ.
+ */
+export declare class CompositePayloadsClient {
+    private readonly identify;
+    private readonly targets;
+    constructor(options: CompositePayloadsClientOptions);
+    /** Missing hashes fall through in target order. Provider errors and corruption fail explicitly. */
+    get(hashes: string[]): Promise<WithStorageMeta<Payload>[]>;
+    getMany(hashes: string[]): Promise<WithStorageMeta<Payload>[]>;
+    getWithReceipts(hashes: readonly string[]): Promise<CompositeReadResult>;
+    /** Payload-array acknowledgment suitable for consumers of insert/get method contracts. */
+    insert(payloads: Payload[]): Promise<WithStorageMeta<Payload>[]>;
+    insertWithReceipts(payloads: readonly Payload[]): Promise<CompositeWriteResult>;
+    private verify;
+    private writeTarget;
+}
+//# sourceMappingURL=CompositePayloadsClient.d.ts.map

package/dist/browser/CompositePayloadsClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositePayloadsClient.d.ts","sourceRoot":"","sources":["../../src/CompositePayloadsClient.ts"],"names":[],"mappings":"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"}

package/dist/browser/browser.d.ts

@@ -1,4 +1,6 @@
 export type { AuthTokenRequest, AuthTokenSource, AuthTokenSupplier, } from './AuthToken.ts';
+export type { CompositePayloadExclusion, CompositePayloadIdentity, CompositePayloadsClientOptions, CompositePayloadsPolicy, CompositePayloadsTarget, CompositeReadReceipt, CompositeReadResult, CompositeWriteReceipt, CompositeWriteResult, } from './CompositePayloadsClient.ts';
+export { CompositePayloadsClient, CompositePayloadsReadError, CompositePayloadsWriteError, } from './CompositePayloadsClient.ts';
 export type { CreateDatalakeRequest, DatalakeClient, GrantRequest, RevokeRequest, TokenRequest, } from './DatalakeClient.ts';
 export type { DatalakeUsageReport, PayloadsAuthTokenSource, PayloadsClient, RestPayloadsClientOptions, } from './PayloadsClient.ts';
 export { RestPayloadsClient } from './PayloadsClient.ts';

package/dist/browser/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,GACrD,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,yBAAyB,GAC1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,YAAY,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EAAE,+BAA+B,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAA;AACnH,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACxE,cAAc,yCAAyC,CAAA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,GACrD,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,8BAA8B,EAC9B,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,uBAAuB,EAAE,0BAA0B,EAAE,2BAA2B,GACjF,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,yBAAyB,GAC1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,YAAY,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EAAE,+BAA+B,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAA;AACnH,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AACxE,cAAc,yCAAyC,CAAA"}

package/dist/browser/browser.mjs

@@ -1,3 +1,252 @@
+// src/CompositePayloadsClient.ts
+var CompositePayloadsWriteError = class extends Error {
+  result;
+  constructor(result) {
+    super("Required datalake writes did not complete");
+    this.name = "CompositePayloadsWriteError";
+    this.result = result;
+  }
+};
+var CompositePayloadsReadError = class extends Error {
+  result;
+  constructor(result) {
+    super("Datalake read could not be verified");
+    this.name = "CompositePayloadsReadError";
+    this.result = result;
+  }
+};
+var CompositePayloadsClient = class {
+  identify;
+  targets;
+  constructor(options) {
+    if (typeof options.identify !== "function") throw new TypeError("Canonical payload identity is required");
+    if (options.targets.length === 0) throw new TypeError("At least one datalake target is required");
+    const names = /* @__PURE__ */ new Set();
+    this.targets = options.targets.map((target) => {
+      if (!/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(target.name) || names.has(target.name)) {
+        throw new TypeError("Datalake target names must be unique non-secret identifiers");
+      }
+      names.add(target.name);
+      return { ...target, policy: snapshotPolicy(target.policy) };
+    });
+    this.identify = options.identify;
+  }
+  /** Missing hashes fall through in target order. Provider errors and corruption fail explicitly. */
+  async get(hashes) {
+    return (await this.getWithReceipts(hashes)).payloads;
+  }
+  async getMany(hashes) {
+    return await this.get(hashes);
+  }
+  async getWithReceipts(hashes) {
+    const requested = [...new Set(hashes)];
+    if (requested.some((hash) => typeof hash !== "string" || hash.length === 0)) throw new TypeError("Hashes must be non-empty strings");
+    const found = /* @__PURE__ */ new Map();
+    const result = {
+      payloads: [],
+      receipts: [],
+      sources: {}
+    };
+    for (const target of this.targets) {
+      const remaining = requested.filter((hash) => !found.has(hash));
+      if (remaining.length === 0) break;
+      const receipt = {
+        target: target.name,
+        requested: remaining,
+        found: []
+      };
+      result.receipts.push(receipt);
+      let response;
+      try {
+        response = await target.client.getMany([...remaining]);
+      } catch {
+        receipt.error = "provider_error";
+        throw new CompositePayloadsReadError(result);
+      }
+      try {
+        const verified = await this.verify(response, new Set(remaining));
+        for (const payload of verified.values()) {
+          found.set(payload._hash, payload);
+          result.sources[payload._hash] = target.name;
+          receipt.found.push(payload._hash);
+        }
+        result.payloads = requested.flatMap((hash) => found.has(hash) ? [found.get(hash)] : []);
+      } catch {
+        receipt.error = "invalid_response";
+        throw new CompositePayloadsReadError(result);
+      }
+    }
+    return result;
+  }
+  /** Payload-array acknowledgment suitable for consumers of insert/get method contracts. */
+  async insert(payloads) {
+    return (await this.insertWithReceipts(payloads)).acknowledged;
+  }
+  async insertWithReceipts(payloads) {
+    const snapshots = payloads.map(snapshotPayload);
+    const prepared = [];
+    const seen = /* @__PURE__ */ new Set();
+    const encoder = new TextEncoder();
+    for (const payload of snapshots) {
+      const { hash } = await this.identify(payload);
+      requireHash(hash);
+      if (!seen.has(hash)) {
+        prepared.push({
+          payload,
+          hash,
+          bytes: encoder.encode(JSON.stringify(payload)).byteLength
+        });
+        seen.add(hash);
+      }
+    }
+    const writes = this.targets.map((target) => prepareWrite(target, prepared));
+    const outcomes = await Promise.all(writes.map((write) => this.writeTarget(write)));
+    const acknowledged = /* @__PURE__ */ new Map();
+    for (const outcome of outcomes) {
+      for (const payload of outcome.acknowledged) acknowledged.set(payload._hash, payload);
+    }
+    const result = {
+      acknowledged: prepared.flatMap(({ hash }) => acknowledged.has(hash) ? [acknowledged.get(hash)] : []),
+      receipts: writes.map((write) => write.receipt)
+    };
+    if (result.receipts.some((receipt) => receipt.status === "failed")) throw new CompositePayloadsWriteError(result);
+    return result;
+  }
+  async verify(payloads, expected) {
+    if (!Array.isArray(payloads)) throw new TypeError("Expected payload array");
+    const snapshots = payloads.map((payload) => {
+      if (typeof payload?._sequence !== "string" || payload._sequence.length === 0) throw new TypeError("Missing storage sequence");
+      return {
+        ...snapshotPayload(payload),
+        _hash: payload._hash,
+        _dataHash: payload._dataHash,
+        _sequence: payload._sequence
+      };
+    });
+    const verified = /* @__PURE__ */ new Map();
+    for (const payload of snapshots) {
+      const identity = await this.identify(snapshotPayload(payload));
+      if (identity.hash !== payload._hash || identity.dataHash !== payload._dataHash || !expected.has(identity.hash)) {
+        throw new TypeError("Unexpected payload identity");
+      }
+      verified.set(identity.hash, payload);
+    }
+    return verified;
+  }
+  async writeTarget({
+    target,
+    payloads,
+    receipt
+  }) {
+    const result = { acknowledged: [], receipts: [receipt] };
+    if (payloads.length === 0) return result;
+    let response;
+    try {
+      response = await target.client.insert(payloads.map((item) => snapshotPayload(item.payload)));
+    } catch {
+      receipt.status = "failed";
+      receipt.error = "provider_error";
+      return result;
+    }
+    try {
+      await this.verify(response.inserted, new Set(receipt.eligible));
+      if (!Array.isArray(response.summary.rejected) || response.summary.rejected.some((hash) => !receipt.eligible.includes(hash))) {
+        throw new TypeError("Unexpected rejected hashes");
+      }
+      receipt.rejected = [...new Set(response.summary.rejected)];
+    } catch {
+      receipt.status = "failed";
+      receipt.error = "invalid_response";
+      return result;
+    }
+    let readback;
+    try {
+      readback = await target.client.getMany([...receipt.eligible]);
+    } catch {
+      receipt.status = "failed";
+      receipt.error = "provider_error";
+      return result;
+    }
+    try {
+      const verified = await this.verify(readback, new Set(receipt.eligible));
+      result.acknowledged = receipt.eligible.flatMap((hash) => verified.has(hash) ? [verified.get(hash)] : []);
+      receipt.acknowledged = result.acknowledged.map((payload) => payload._hash);
+      if (receipt.rejected.length > 0 || verified.size !== receipt.eligible.length) {
+        receipt.status = "failed";
+        receipt.error = receipt.rejected.length > 0 ? "policy_rejected" : "incomplete_readback";
+      }
+    } catch {
+      receipt.status = "failed";
+      receipt.error = "invalid_response";
+    }
+    return result;
+  }
+};
+function snapshotPolicy(policy) {
+  if (!policy || policy.mode !== "all" && policy.mode !== "selected") throw new TypeError("Explicit datalake policy is required");
+  if (policy.mode === "selected" && (!Array.isArray(policy.allowedSchemas) || policy.maxPayloadBytes === void 0)) {
+    throw new TypeError("Selected datalakes require an allowlist and byte limit");
+  }
+  for (const schemas of [policy.allowedSchemas, policy.disallowedSchemas]) {
+    if (schemas !== void 0 && (!Array.isArray(schemas) || schemas.some((schema) => typeof schema !== "string" || schema.length === 0))) {
+      throw new TypeError("Schema lists must contain non-empty identifiers");
+    }
+  }
+  for (const limit of [policy.maxPayloadBytes, ...Object.values(policy.schemaMaxPayloadBytes ?? {})]) {
+    if (limit !== void 0 && (!Number.isSafeInteger(limit) || limit <= 0)) throw new RangeError("Payload byte limits must be positive safe integers");
+  }
+  return {
+    ...policy,
+    allowedSchemas: policy.allowedSchemas === void 0 ? void 0 : [...policy.allowedSchemas],
+    disallowedSchemas: policy.disallowedSchemas === void 0 ? void 0 : [...policy.disallowedSchemas],
+    schemaMaxPayloadBytes: { ...policy.schemaMaxPayloadBytes }
+  };
+}
+function prepareWrite(target, payloads) {
+  const selected = [];
+  const excluded = [];
+  for (const item of payloads) {
+    const reason = exclusionReason(target.policy, item);
+    if (reason) excluded.push({ hash: item.hash, reason });
+    else selected.push(item);
+  }
+  return {
+    target,
+    payloads: selected,
+    receipt: {
+      target: target.name,
+      policyRevision: target.policy.revision,
+      eligible: selected.map((item) => item.hash),
+      excluded,
+      acknowledged: [],
+      rejected: [],
+      status: selected.length > 0 ? "complete" : "excluded"
+    }
+  };
+}
+function exclusionReason(policy, item) {
+  const { schema } = item.payload;
+  if (policy.allowedSchemas !== void 0 && !policy.allowedSchemas.includes(schema) || policy.disallowedSchemas?.includes(schema)) return "schema";
+  const schemaLimit = policy.schemaMaxPayloadBytes && Object.hasOwn(policy.schemaMaxPayloadBytes, schema) ? policy.schemaMaxPayloadBytes[schema] : void 0;
+  const limit = Math.min(policy.maxPayloadBytes ?? Infinity, schemaLimit ?? Infinity);
+  if (item.bytes > limit) return "size";
+  if (policy.isValid && !policy.isValid(snapshotPayload(item.payload))) return "validation";
+  return void 0;
+}
+function snapshotPayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload) || typeof payload.schema !== "string" || payload.schema.length === 0) {
+    throw new TypeError("Expected flat schema-bearing payloads");
+  }
+  const stripped = Object.fromEntries(Object.entries(payload).filter(([key]) => !key.startsWith("_")));
+  const serialized = JSON.stringify(stripped);
+  const copy = JSON.parse(serialized);
+  if (copy.schema !== payload.schema) throw new TypeError("Payload serialization changed its schema");
+  return copy;
+}
+function requireHash(hash) {
+  if (typeof hash !== "string" || hash.length === 0) throw new TypeError("Canonical payload identity returned an invalid hash");
+}
+
 // src/PayloadsClient.ts
 import {
   DATALAKE_HEADER_DUPLICATES,
@@ -136,7 +385,7 @@ var RestPayloadsClient = class {
 };
 function readInsertSummary(headers) {
   const duplicatesRaw = headers.get(DATALAKE_HEADER_DUPLICATES);
-  const duplicates = duplicatesRaw === null ? 0 : Number.parseInt(duplicatesRaw, 10);
+  const duplicates = duplicatesRaw === null ? 0 : Math.trunc(Number(duplicatesRaw));
   const rejectedRaw = headers.get(DATALAKE_HEADER_REJECTED);
   const rejected = rejectedRaw === null || rejectedRaw.length === 0 ? [] : rejectedRaw.split(",").map((value) => value.trim()).filter((value) => value.length > 0);
   return {
@@ -320,6 +569,9 @@ function isStoredPayload(value) {
 // src/browser.ts
 export * from "@ariestools/aries-datalake-core/browser";
 export {
+  CompositePayloadsClient,
+  CompositePayloadsReadError,
+  CompositePayloadsWriteError,
   RestDatalakeClient,
   RestPayloadsClient,
   RestPublicPayloadsReader