@sequenceholdings/orm 2.6.1 → 2.6.2

package/dist/canonical.d.ts

@@ -102,8 +102,8 @@ type CanonicalFetchShape = z.infer<typeof canonicalFetchShapeSchema>;
 declare const canonicalResolvedSourceSchema: z.ZodObject<{
     name: z.ZodString;
     kind: z.ZodEnum<{
-        prefetch: "prefetch";
         manual: "manual";
+        prefetch: "prefetch";
         etl: "etl";
     }>;
     table: z.ZodString;
@@ -160,8 +160,8 @@ declare const canonicalResolvedSchema: z.ZodObject<{
     sources: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         kind: z.ZodEnum<{
-            prefetch: "prefetch";
             manual: "manual";
+            prefetch: "prefetch";
             etl: "etl";
         }>;
         table: z.ZodString;
@@ -325,13 +325,13 @@ declare const canonicalColumnSchema: z.ZodObject<{
         bigint: "bigint";
         boolean: "boolean";
         date: "date";
-        uuid: "uuid";
         text: "text";
+        timestamptz: "timestamptz";
+        jsonb: "jsonb";
+        uuid: "uuid";
         integer: "integer";
         numeric: "numeric";
         double: "double";
-        timestamptz: "timestamptz";
-        jsonb: "jsonb";
     }>, z.ZodObject<{
         enum: z.ZodString;
     }, z.core.$strip>]>;
@@ -353,10 +353,10 @@ declare const canonicalColumnSchema: z.ZodObject<{
         of: z.ZodString;
         part: z.ZodEnum<{
             at: "at";
-            source: "source";
             by: "by";
-            conflicts: "conflicts";
             rev: "rev";
+            source: "source";
+            conflicts: "conflicts";
         }>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
@@ -460,21 +460,21 @@ declare const canonicalActionSchema: z.ZodObject<{
             bigint: "bigint";
             boolean: "boolean";
             date: "date";
-            uuid: "uuid";
             text: "text";
+            timestamptz: "timestamptz";
+            jsonb: "jsonb";
+            uuid: "uuid";
             integer: "integer";
             numeric: "numeric";
             double: "double";
-            timestamptz: "timestamptz";
-            jsonb: "jsonb";
         }>;
         nullable: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>>;
     executes: z.ZodString;
     returns: z.ZodDefault<z.ZodEnum<{
         rows: "rows";
-        scalar: "scalar";
         rowsAffected: "rowsAffected";
+        scalar: "scalar";
     }>>;
     audit: z.ZodOptional<z.ZodObject<{
         action: z.ZodString;
@@ -540,13 +540,13 @@ declare const canonicalTableSchema: z.ZodObject<{
             bigint: "bigint";
             boolean: "boolean";
             date: "date";
-            uuid: "uuid";
             text: "text";
+            timestamptz: "timestamptz";
+            jsonb: "jsonb";
+            uuid: "uuid";
             integer: "integer";
             numeric: "numeric";
             double: "double";
-            timestamptz: "timestamptz";
-            jsonb: "jsonb";
         }>, z.ZodObject<{
             enum: z.ZodString;
         }, z.core.$strip>]>;
@@ -568,10 +568,10 @@ declare const canonicalTableSchema: z.ZodObject<{
             of: z.ZodString;
             part: z.ZodEnum<{
                 at: "at";
-                source: "source";
                 by: "by";
-                conflicts: "conflicts";
                 rev: "rev";
+                source: "source";
+                conflicts: "conflicts";
             }>;
         }, z.core.$strict>>;
     }, z.core.$strip>>>;
@@ -655,21 +655,21 @@ declare const canonicalTableSchema: z.ZodObject<{
                 bigint: "bigint";
                 boolean: "boolean";
                 date: "date";
-                uuid: "uuid";
                 text: "text";
+                timestamptz: "timestamptz";
+                jsonb: "jsonb";
+                uuid: "uuid";
                 integer: "integer";
                 numeric: "numeric";
                 double: "double";
-                timestamptz: "timestamptz";
-                jsonb: "jsonb";
             }>;
             nullable: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>>;
         executes: z.ZodString;
         returns: z.ZodDefault<z.ZodEnum<{
             rows: "rows";
-            scalar: "scalar";
             rowsAffected: "rowsAffected";
+            scalar: "scalar";
         }>>;
         audit: z.ZodOptional<z.ZodObject<{
             action: z.ZodString;
@@ -726,13 +726,13 @@ declare const canonicalViewSchema: z.ZodObject<{
             bigint: "bigint";
             boolean: "boolean";
             date: "date";
-            uuid: "uuid";
             text: "text";
+            timestamptz: "timestamptz";
+            jsonb: "jsonb";
+            uuid: "uuid";
             integer: "integer";
             numeric: "numeric";
             double: "double";
-            timestamptz: "timestamptz";
-            jsonb: "jsonb";
         }>, z.ZodObject<{
             enum: z.ZodString;
         }, z.core.$strip>]>;
@@ -754,10 +754,10 @@ declare const canonicalViewSchema: z.ZodObject<{
             of: z.ZodString;
             part: z.ZodEnum<{
                 at: "at";
-                source: "source";
                 by: "by";
-                conflicts: "conflicts";
                 rev: "rev";
+                source: "source";
+                conflicts: "conflicts";
             }>;
         }, z.core.$strict>>;
     }, z.core.$strip>>;
@@ -806,8 +806,8 @@ declare const canonicalViewSchema: z.ZodObject<{
         sources: z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             kind: z.ZodEnum<{
-                prefetch: "prefetch";
                 manual: "manual";
+                prefetch: "prefetch";
                 etl: "etl";
             }>;
             table: z.ZodString;
@@ -947,13 +947,13 @@ declare const localDefinitionSchema: z.ZodObject<{
                 bigint: "bigint";
                 boolean: "boolean";
                 date: "date";
-                uuid: "uuid";
                 text: "text";
+                timestamptz: "timestamptz";
+                jsonb: "jsonb";
+                uuid: "uuid";
                 integer: "integer";
                 numeric: "numeric";
                 double: "double";
-                timestamptz: "timestamptz";
-                jsonb: "jsonb";
             }>, z.ZodObject<{
                 enum: z.ZodString;
             }, z.core.$strip>]>;
@@ -975,10 +975,10 @@ declare const localDefinitionSchema: z.ZodObject<{
                 of: z.ZodString;
                 part: z.ZodEnum<{
                     at: "at";
-                    source: "source";
                     by: "by";
-                    conflicts: "conflicts";
                     rev: "rev";
+                    source: "source";
+                    conflicts: "conflicts";
                 }>;
             }, z.core.$strict>>;
         }, z.core.$strip>>>;
@@ -1062,21 +1062,21 @@ declare const localDefinitionSchema: z.ZodObject<{
                     bigint: "bigint";
                     boolean: "boolean";
                     date: "date";
-                    uuid: "uuid";
                     text: "text";
+                    timestamptz: "timestamptz";
+                    jsonb: "jsonb";
+                    uuid: "uuid";
                     integer: "integer";
                     numeric: "numeric";
                     double: "double";
-                    timestamptz: "timestamptz";
-                    jsonb: "jsonb";
                 }>;
                 nullable: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>>>;
             executes: z.ZodString;
             returns: z.ZodDefault<z.ZodEnum<{
                 rows: "rows";
-                scalar: "scalar";
                 rowsAffected: "rowsAffected";
+                scalar: "scalar";
             }>>;
             audit: z.ZodOptional<z.ZodObject<{
                 action: z.ZodString;
@@ -1132,13 +1132,13 @@ declare const localDefinitionSchema: z.ZodObject<{
                 bigint: "bigint";
                 boolean: "boolean";
                 date: "date";
-                uuid: "uuid";
                 text: "text";
+                timestamptz: "timestamptz";
+                jsonb: "jsonb";
+                uuid: "uuid";
                 integer: "integer";
                 numeric: "numeric";
                 double: "double";
-                timestamptz: "timestamptz";
-                jsonb: "jsonb";
             }>, z.ZodObject<{
                 enum: z.ZodString;
             }, z.core.$strip>]>;
@@ -1160,10 +1160,10 @@ declare const localDefinitionSchema: z.ZodObject<{
                 of: z.ZodString;
                 part: z.ZodEnum<{
                     at: "at";
-                    source: "source";
                     by: "by";
-                    conflicts: "conflicts";
                     rev: "rev";
+                    source: "source";
+                    conflicts: "conflicts";
                 }>;
             }, z.core.$strict>>;
         }, z.core.$strip>>;
@@ -1212,8 +1212,8 @@ declare const localDefinitionSchema: z.ZodObject<{
             sources: z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
                 kind: z.ZodEnum<{
-                    prefetch: "prefetch";
                     manual: "manual";
+                    prefetch: "prefetch";
                     etl: "etl";
                 }>;
                 table: z.ZodString;
@@ -1336,13 +1336,13 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 bigint: "bigint";
                 boolean: "boolean";
                 date: "date";
-                uuid: "uuid";
                 text: "text";
+                timestamptz: "timestamptz";
+                jsonb: "jsonb";
+                uuid: "uuid";
                 integer: "integer";
                 numeric: "numeric";
                 double: "double";
-                timestamptz: "timestamptz";
-                jsonb: "jsonb";
             }>, z.ZodObject<{
                 enum: z.ZodString;
             }, z.core.$strip>]>;
@@ -1364,10 +1364,10 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 of: z.ZodString;
                 part: z.ZodEnum<{
                     at: "at";
-                    source: "source";
                     by: "by";
-                    conflicts: "conflicts";
                     rev: "rev";
+                    source: "source";
+                    conflicts: "conflicts";
                 }>;
             }, z.core.$strict>>;
         }, z.core.$strip>>>;
@@ -1451,21 +1451,21 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     bigint: "bigint";
                     boolean: "boolean";
                     date: "date";
-                    uuid: "uuid";
                     text: "text";
+                    timestamptz: "timestamptz";
+                    jsonb: "jsonb";
+                    uuid: "uuid";
                     integer: "integer";
                     numeric: "numeric";
                     double: "double";
-                    timestamptz: "timestamptz";
-                    jsonb: "jsonb";
                 }>;
                 nullable: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>>>;
             executes: z.ZodString;
             returns: z.ZodDefault<z.ZodEnum<{
                 rows: "rows";
-                scalar: "scalar";
                 rowsAffected: "rowsAffected";
+                scalar: "scalar";
             }>>;
             audit: z.ZodOptional<z.ZodObject<{
                 action: z.ZodString;
@@ -1521,13 +1521,13 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 bigint: "bigint";
                 boolean: "boolean";
                 date: "date";
-                uuid: "uuid";
                 text: "text";
+                timestamptz: "timestamptz";
+                jsonb: "jsonb";
+                uuid: "uuid";
                 integer: "integer";
                 numeric: "numeric";
                 double: "double";
-                timestamptz: "timestamptz";
-                jsonb: "jsonb";
             }>, z.ZodObject<{
                 enum: z.ZodString;
             }, z.core.$strip>]>;
@@ -1549,10 +1549,10 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 of: z.ZodString;
                 part: z.ZodEnum<{
                     at: "at";
-                    source: "source";
                     by: "by";
-                    conflicts: "conflicts";
                     rev: "rev";
+                    source: "source";
+                    conflicts: "conflicts";
                 }>;
             }, z.core.$strict>>;
         }, z.core.$strip>>;
@@ -1601,8 +1601,8 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
             sources: z.ZodArray<z.ZodObject<{
                 name: z.ZodString;
                 kind: z.ZodEnum<{
-                    prefetch: "prefetch";
                     manual: "manual";
+                    prefetch: "prefetch";
                     etl: "etl";
                 }>;
                 table: z.ZodString;
@@ -1724,13 +1724,13 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     bigint: "bigint";
                     boolean: "boolean";
                     date: "date";
-                    uuid: "uuid";
                     text: "text";
+                    timestamptz: "timestamptz";
+                    jsonb: "jsonb";
+                    uuid: "uuid";
                     integer: "integer";
                     numeric: "numeric";
                     double: "double";
-                    timestamptz: "timestamptz";
-                    jsonb: "jsonb";
                 }>, z.ZodObject<{
                     enum: z.ZodString;
                 }, z.core.$strip>]>;
@@ -1752,10 +1752,10 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     of: z.ZodString;
                     part: z.ZodEnum<{
                         at: "at";
-                        source: "source";
                         by: "by";
-                        conflicts: "conflicts";
                         rev: "rev";
+                        source: "source";
+                        conflicts: "conflicts";
                     }>;
                 }, z.core.$strict>>;
             }, z.core.$strip>>>;
@@ -1839,21 +1839,21 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                         bigint: "bigint";
                         boolean: "boolean";
                         date: "date";
-                        uuid: "uuid";
                         text: "text";
+                        timestamptz: "timestamptz";
+                        jsonb: "jsonb";
+                        uuid: "uuid";
                         integer: "integer";
                         numeric: "numeric";
                         double: "double";
-                        timestamptz: "timestamptz";
-                        jsonb: "jsonb";
                     }>;
                     nullable: z.ZodDefault<z.ZodBoolean>;
                 }, z.core.$strip>>>;
                 executes: z.ZodString;
                 returns: z.ZodDefault<z.ZodEnum<{
                     rows: "rows";
-                    scalar: "scalar";
                     rowsAffected: "rowsAffected";
+                    scalar: "scalar";
                 }>>;
                 audit: z.ZodOptional<z.ZodObject<{
                     action: z.ZodString;
@@ -1909,13 +1909,13 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     bigint: "bigint";
                     boolean: "boolean";
                     date: "date";
-                    uuid: "uuid";
                     text: "text";
+                    timestamptz: "timestamptz";
+                    jsonb: "jsonb";
+                    uuid: "uuid";
                     integer: "integer";
                     numeric: "numeric";
                     double: "double";
-                    timestamptz: "timestamptz";
-                    jsonb: "jsonb";
                 }>, z.ZodObject<{
                     enum: z.ZodString;
                 }, z.core.$strip>]>;
@@ -1937,10 +1937,10 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     of: z.ZodString;
                     part: z.ZodEnum<{
                         at: "at";
-                        source: "source";
                         by: "by";
-                        conflicts: "conflicts";
                         rev: "rev";
+                        source: "source";
+                        conflicts: "conflicts";
                     }>;
                 }, z.core.$strict>>;
             }, z.core.$strip>>;
@@ -1989,8 +1989,8 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 sources: z.ZodArray<z.ZodObject<{
                     name: z.ZodString;
                     kind: z.ZodEnum<{
-                        prefetch: "prefetch";
                         manual: "manual";
+                        prefetch: "prefetch";
                         etl: "etl";
                     }>;
                     table: z.ZodString;

package/dist/client.cjs

@@ -193,6 +193,20 @@ function readOperationResponse({
   }
   return payload.data;
 }
+function readOperationResponseWithReceipt({
+  ok,
+  status,
+  body,
+  expectedSourceGeneration
+}) {
+  const data = readOperationResponse({ ok, status, body });
+  const extensions = isRecord(body) && isRecord(body.extensions) ? body.extensions : null;
+  const sourceGeneration = extensions?.sourceGeneration;
+  if (typeof sourceGeneration !== "string" || !/^[a-f0-9]{64}$/.test(sourceGeneration) || expectedSourceGeneration !== void 0 && expectedSourceGeneration !== sourceGeneration) {
+    throw new OrmOperationError("Source generation unavailable", status, "OBJECT_UNAVAILABLE");
+  }
+  return { data, sourceGeneration };
+}
 
 // src/client/sql.ts
 var BUILTIN_SQL_READ_HASH = "sha256:a50c477c952a5e0fe68ed158a4530e4aab573c09bcbb1a8ac454dc88a39a6258";
@@ -203,6 +217,11 @@ function validateIdempotencyKey(key) {
     throw new OrmClientError("idempotencyKey must be 1\u2013128 letters, digits, dots, underscores, colons or hyphens");
   }
 }
+function validateExpectedSourceGeneration(value) {
+  if (value !== void 0 && (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))) {
+    throw new OrmClientError("expectedSourceGeneration must be a lowercase 64-character hexadecimal receipt");
+  }
+}
 var dataPlanePath = (namespace) => `/_data/v2/${namespace}`;
 function resolveOpHash(manifest, op) {
   if (op.startsWith("sha256:")) return op;
@@ -215,6 +234,23 @@ function resolveOpHash(manifest, op) {
   }
   return entry.hash;
 }
+function createReadReceiptOperationResolver({ operations }) {
+  const hashesByName = /* @__PURE__ */ new Map();
+  const readHashes = /* @__PURE__ */ new Set([BUILTIN_SQL_READ_HASH]);
+  const mutationHashes = /* @__PURE__ */ new Set();
+  for (const [name, entry] of operations) {
+    hashesByName.set(name, entry.hash);
+    if (entry.kind === "query" && /^sha256:[a-f0-9]{64}$/.test(entry.hash)) readHashes.add(entry.hash);
+    if (entry.kind === "mutation") mutationHashes.add(entry.hash);
+  }
+  return ({ selector, hashOnly = false }) => {
+    const hash = selector.startsWith("sha256:") ? selector : hashOnly ? void 0 : hashesByName.get(selector);
+    if (!hash || !readHashes.has(hash) || mutationHashes.has(hash)) {
+      throw new OrmClientError("read receipts require a registered query or the built-in SQL read");
+    }
+    return hash;
+  };
+}
 function createOperationExecutor({
   baseUrl,
   namespace,
@@ -228,25 +264,42 @@ function createOperationExecutor({
     throw new OrmClientError("provide exactly one of getToken (bearer) or getDataToken (delegated)");
   }
   const root = baseUrl.replace(/\/+$/, "");
-  async function execute(op, variables = {}, options = {}) {
+  const resolveReceiptOperation = createReadReceiptOperationResolver({ operations: Object.entries(manifest.operations) });
+  async function request({ op, variables, options, requireReadReceipt = false }) {
     validateIdempotencyKey(options.idempotencyKey);
+    validateExpectedSourceGeneration(options.expectedSourceGeneration);
     if (typeof op !== "string" && op.namespace !== namespace) throw new OrmClientError("operation belongs to a different namespace");
-    const hash = typeof op === "string" ? resolveOpHash(manifest, op) : op.hash;
+    const hash = requireReadReceipt ? resolveReceiptOperation({ selector: typeof op === "string" ? op : op.hash, hashOnly: typeof op !== "string" }) : typeof op === "string" ? resolveOpHash(manifest, op) : op.hash;
     const token = await (getDataToken ?? getToken)();
     if (!token) throw new OrmClientError("not authenticated \u2014 no token available");
     const auth = getDataToken ? { [ORM_DATA_TOKEN_HEADER]: token } : { Authorization: `Bearer ${token}` };
     const response = await fetchImpl(`${root}${dataPlanePath(namespace)}`, {
       method: "POST",
       headers: { ...auth, "Content-Type": "application/json" },
-      body: JSON.stringify({ op: hash, variables, idempotencyKey: options.idempotencyKey })
+      body: JSON.stringify({
+        op: hash,
+        variables,
+        idempotencyKey: options.idempotencyKey,
+        expectedSourceGeneration: options.expectedSourceGeneration
+      })
     });
-    return readOperationResponse({
+    return {
       ok: response.ok,
       status: response.status,
       body: await response.json().catch(() => null)
-    });
+    };
+  }
+  async function execute(op, variables = {}, options = {}) {
+    const executionOptions = { ...options };
+    const response = await request({ op, variables, options: executionOptions });
+    return executionOptions.expectedSourceGeneration === void 0 ? readOperationResponse(response) : readOperationResponseWithReceipt({ ...response, expectedSourceGeneration: executionOptions.expectedSourceGeneration }).data;
+  }
+  async function executeWithReadReceipt(op, variables = {}, options = {}) {
+    const executionOptions = { ...options };
+    const response = await request({ op, variables, options: executionOptions, requireReadReceipt: true });
+    return readOperationResponseWithReceipt({ ...response, expectedSourceGeneration: executionOptions.expectedSourceGeneration });
   }
-  return { execute, sql: (variables) => execute(BUILTIN_SQL_READ_HASH, variables) };
+  return { execute, executeWithReadReceipt, sql: (variables) => execute(BUILTIN_SQL_READ_HASH, variables) };
 }
 var configured = null;
 function configureOrmOperations(config) {
@@ -315,33 +368,46 @@ function readManifestHashes(manifest) {
     if (!/^[_A-Za-z][_0-9A-Za-z]*$/.test(name) || !isRecord(entry) || typeof entry.hash !== "string" || !operationHash.test(entry.hash) || entry.kind !== "query" && entry.kind !== "mutation") {
       throw new OrmClientError(`invalid operations manifest entry "${name}" \u2014 regenerate the manifest`);
     }
-    hashes.set(name, entry.hash);
+    hashes.set(name, { hash: entry.hash, kind: entry.kind });
   }
   return hashes;
 }
 function createOperationExecutorWithTransport({ namespace, manifest, transport }) {
   if (typeof namespace !== "string" || !NAMESPACE_PATTERN.test(namespace)) throw new OrmClientError("invalid ORM namespace \u2014 expected a lowercase identifier of at most 41 characters");
   const hashes = manifest === void 0 ? /* @__PURE__ */ new Map() : readManifestHashes(manifest);
-  const knownHashes = new Set(hashes.values());
-  async function execute(op, variables = {}, options = {}) {
+  const knownHashes = new Set([...hashes.values()].map((entry) => entry.hash));
+  const resolveReceiptOperation = createReadReceiptOperationResolver({ operations: hashes });
+  async function request({ op, variables, options, requireReadReceipt = false }) {
     validateIdempotencyKey(options.idempotencyKey);
+    validateExpectedSourceGeneration(options.expectedSourceGeneration);
     if (typeof op !== "string" && op.namespace !== namespace) throw new OrmClientError("operation belongs to a different namespace");
     const selector = typeof op === "string" ? op : op.hash;
-    const hash = selector === BUILTIN_SQL_READ_HASH ? selector : hashes.get(selector) ?? (knownHashes.has(selector) ? selector : void 0);
+    const hash = requireReadReceipt ? resolveReceiptOperation({ selector, hashOnly: typeof op !== "string" }) : selector === BUILTIN_SQL_READ_HASH ? selector : hashes.get(selector)?.hash ?? (knownHashes.has(selector) ? selector : void 0);
     if (!hash) throw new OrmClientError(`unknown operation "${op}" \u2014 not in the manifest (${hashes.size} known). Re-run seq-studio orm generate.`);
     if (!isRecord(variables)) throw new OrmClientError("operation variables must be an object");
     const response = await transport({
       namespace,
       op: hash,
       variables,
-      ...options.idempotencyKey === void 0 ? {} : { idempotencyKey: options.idempotencyKey }
+      ...options.idempotencyKey === void 0 ? {} : { idempotencyKey: options.idempotencyKey },
+      ...options.expectedSourceGeneration === void 0 ? {} : { expectedSourceGeneration: options.expectedSourceGeneration }
     });
     if (!response || typeof response.ok !== "boolean" || !Number.isInteger(response.status) || response.status < 100 || response.status > 599 || response.ok !== (response.status >= 200 && response.status < 300)) {
       throw new OrmOperationError("malformed transport response", null, null);
     }
-    return readOperationResponse(response);
+    return response;
+  }
+  async function execute(op, variables = {}, options = {}) {
+    const executionOptions = { ...options };
+    const response = await request({ op, variables, options: executionOptions });
+    return executionOptions.expectedSourceGeneration === void 0 ? readOperationResponse(response) : readOperationResponseWithReceipt({ ...response, expectedSourceGeneration: executionOptions.expectedSourceGeneration }).data;
+  }
+  async function executeWithReadReceipt(op, variables = {}, options = {}) {
+    const executionOptions = { ...options };
+    const response = await request({ op, variables, options: executionOptions, requireReadReceipt: true });
+    return readOperationResponseWithReceipt({ ...response, expectedSourceGeneration: executionOptions.expectedSourceGeneration });
   }
-  return { execute, sql: (variables) => execute(BUILTIN_SQL_READ_HASH, variables) };
+  return { execute, executeWithReadReceipt, sql: (variables) => execute(BUILTIN_SQL_READ_HASH, variables) };
 }
 
 // src/client/index.ts