@hyperscale0/sdk 1.0.338 → 1.0.339

package/client.js

@@ -6,7 +6,8 @@ const routes = {
     "pathParams": [
       "accountId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "account.close": {
     "method": "POST",
@@ -20,7 +21,8 @@ const routes = {
     "method": "POST",
     "path": "/v1/accounts",
     "pathParams": [],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "account.freeze": {
     "method": "POST",
@@ -36,7 +38,9 @@ const routes = {
     "pathParams": [
       "accountId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "account.hold.retrieve": {
     "method": "GET",
@@ -45,13 +49,16 @@ const routes = {
       "accountId",
       "transferId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "account.list": {
     "method": "GET",
     "path": "/v1/accounts",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "account.retrieve": {
     "method": "GET",
@@ -59,7 +66,8 @@ const routes = {
     "pathParams": [
       "accountId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "account.statement.export": {
     "method": "GET",
@@ -68,7 +76,8 @@ const routes = {
       "accountId",
       "period"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "account.statement.retrieve": {
     "method": "GET",
@@ -77,7 +86,9 @@ const routes = {
       "accountId",
       "period"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "lines"
   },
   "account.unfreeze": {
     "method": "POST",
@@ -91,7 +102,9 @@ const routes = {
     "method": "GET",
     "path": "/v1/activity",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "activity.retrieve": {
     "method": "GET",
@@ -99,13 +112,16 @@ const routes = {
     "pathParams": [
       "activityId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "audit_event.list": {
     "method": "GET",
     "path": "/v1/audit-events",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "audit_event.retrieve": {
     "method": "GET",
@@ -113,13 +129,16 @@ const routes = {
     "pathParams": [
       "auditEventId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "consent.list": {
     "method": "GET",
     "path": "/v1/consents",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "consent.retrieve": {
     "method": "GET",
@@ -127,7 +146,8 @@ const routes = {
     "pathParams": [
       "consentId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "consent.revoke": {
     "method": "POST",
@@ -135,7 +155,8 @@ const routes = {
     "pathParams": [
       "consentId"
     ],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "customer_access.close": {
     "method": "POST",
@@ -149,7 +170,9 @@ const routes = {
     "method": "GET",
     "path": "/v1/customer-access",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "customer_access.reactivate": {
     "method": "POST",
@@ -165,7 +188,8 @@ const routes = {
     "pathParams": [
       "customerAccessId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "customer_access.suspend": {
     "method": "POST",
@@ -179,19 +203,23 @@ const routes = {
     "method": "POST",
     "path": "/v1/customers",
     "pathParams": [],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "customer.list": {
     "method": "GET",
     "path": "/v1/customers",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "customer.login": {
     "method": "POST",
     "path": "/v1/customer-identity/login",
     "pathParams": [],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "customer.logout": {
     "method": "POST",
@@ -213,7 +241,8 @@ const routes = {
     "pathParams": [
       "customerId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "customer.session.revoke": {
     "method": "POST",
@@ -227,27 +256,16 @@ const routes = {
     "method": "POST",
     "path": "/v1/customer-identity/signup",
     "pathParams": [],
-    "idempotency": "required"
-  },
-  "developer.log.list": {
-    "method": "GET",
-    "path": "/v1/developer-logs",
-    "pathParams": [],
-    "idempotency": "not_required"
-  },
-  "developer.log.retrieve": {
-    "method": "GET",
-    "path": "/v1/developer-logs/{operationId}",
-    "pathParams": [
-      "operationId"
-    ],
-    "idempotency": "not_required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "event.list": {
     "method": "GET",
     "path": "/v1/events",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "event.retrieve": {
     "method": "GET",
@@ -255,19 +273,23 @@ const routes = {
     "pathParams": [
       "eventId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "extension.list": {
     "method": "GET",
     "path": "/v1/extensions",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "collection": "items"
   },
   "internal_transfer.list": {
     "method": "GET",
     "path": "/v1/internal-transfers",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "internal_transfer.retrieve": {
     "method": "GET",
@@ -275,13 +297,16 @@ const routes = {
     "pathParams": [
       "transferId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "operation.list": {
     "method": "GET",
     "path": "/v1/operations",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "operation.retrieve": {
     "method": "GET",
@@ -289,7 +314,8 @@ const routes = {
     "pathParams": [
       "operationId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "payment_reminder.delivery.retrieve": {
     "method": "GET",
@@ -298,7 +324,8 @@ const routes = {
       "productId",
       "operationId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.actions.list": {
     "method": "GET",
@@ -306,7 +333,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.activation.retrieve": {
     "method": "GET",
@@ -314,7 +342,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.blocks.summary": {
     "method": "GET",
@@ -322,7 +351,18 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
+  },
+  "product.books.retrieve": {
+    "method": "GET",
+    "path": "/v1/products/{productId}/books",
+    "pathParams": [
+      "productId"
+    ],
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.connections.retrieve": {
     "method": "GET",
@@ -330,7 +370,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.earn.rate.list": {
     "method": "GET",
@@ -338,7 +379,9 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "product.earnings.settle": {
     "method": "POST",
@@ -346,7 +389,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "product.economic_snapshot.retrieve": {
     "method": "GET",
@@ -354,7 +398,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.guidance.retrieve": {
     "method": "GET",
@@ -362,7 +407,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.instruments.list": {
     "method": "GET",
@@ -370,13 +416,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
-  },
-  "product.list": {
-    "method": "GET",
-    "path": "/v1/products",
-    "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.margin.retrieve": {
     "method": "GET",
@@ -384,7 +425,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.objects.actions": {
     "method": "GET",
@@ -394,7 +436,9 @@ const routes = {
       "kind",
       "objectId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "actions"
   },
   "product.objects.agreements.evidence.list": {
     "method": "GET",
@@ -405,7 +449,9 @@ const routes = {
       "objectId",
       "instanceId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "product.objects.agreements.list": {
     "method": "GET",
@@ -415,7 +461,9 @@ const routes = {
       "kind",
       "objectId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "product.objects.create": {
     "method": "POST",
@@ -424,7 +472,8 @@ const routes = {
       "productId",
       "kind"
     ],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "product.objects.discover": {
     "method": "GET",
@@ -432,7 +481,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.objects.execute": {
     "method": "POST",
@@ -443,7 +493,8 @@ const routes = {
       "objectId",
       "action"
     ],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "product.objects.list": {
     "method": "GET",
@@ -452,7 +503,9 @@ const routes = {
       "productId",
       "kind"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "product.objects.preview": {
     "method": "POST",
@@ -463,7 +516,8 @@ const routes = {
       "objectId",
       "action"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.objects.retrieve": {
     "method": "GET",
@@ -473,7 +527,8 @@ const routes = {
       "kind",
       "objectId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.objects.timeline.list": {
     "method": "GET",
@@ -483,7 +538,9 @@ const routes = {
       "kind",
       "objectId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "product.operation_set.retrieve": {
     "method": "GET",
@@ -491,15 +548,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
-  },
-  "product.retrieve": {
-    "method": "GET",
-    "path": "/v1/products/{productId}",
-    "pathParams": [
-      "productId"
-    ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.schedule.list": {
     "method": "GET",
@@ -507,7 +557,9 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "product.treasury.retrieve": {
     "method": "GET",
@@ -515,7 +567,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "product.work.list": {
     "method": "GET",
@@ -523,13 +576,17 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "receipt.list": {
     "method": "GET",
     "path": "/v1/receipts",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "receipt.retrieve": {
     "method": "GET",
@@ -537,7 +594,8 @@ const routes = {
     "pathParams": [
       "receiptId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "sandbox.account.fund": {
     "method": "POST",
@@ -549,7 +607,8 @@ const routes = {
     "method": "POST",
     "path": "/v1/sandbox/clock/advance",
     "pathParams": [],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "sandbox.clock.retrieve": {
     "method": "GET",
@@ -557,7 +616,8 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "sandbox.customer_access.activate": {
     "method": "POST",
@@ -573,17 +633,13 @@ const routes = {
     "pathParams": [],
     "idempotency": "required"
   },
-  "transfer_return.create": {
-    "method": "POST",
-    "path": "/v1/transfer-returns",
-    "pathParams": [],
-    "idempotency": "required"
-  },
   "usage_record.list": {
     "method": "GET",
     "path": "/v1/usage-records",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "usage_record.retrieve": {
     "method": "GET",
@@ -591,13 +647,8 @@ const routes = {
     "pathParams": [
       "usageRecordId"
     ],
-    "idempotency": "not_required"
-  },
-  "usage.statement": {
-    "method": "GET",
-    "path": "/v1/usage/statement",
-    "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   },
   "webhook.delivery.list": {
     "method": "GET",
@@ -605,7 +656,8 @@ const routes = {
     "pathParams": [
       "webhookEndpointId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "collection": "items"
   },
   "webhook.delivery.resend": {
     "method": "POST",
@@ -620,7 +672,8 @@ const routes = {
     "method": "POST",
     "path": "/v1/webhook-endpoints",
     "pathParams": [],
-    "idempotency": "required"
+    "idempotency": "required",
+    "takesProductId": true
   },
   "webhook.endpoint.delete": {
     "method": "POST",
@@ -650,7 +703,9 @@ const routes = {
     "method": "GET",
     "path": "/v1/webhook-endpoints",
     "pathParams": [],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true,
+    "collection": "items"
   },
   "webhook.endpoint.recover": {
     "method": "POST",
@@ -690,16 +745,52 @@ const routes = {
     "pathParams": [
       "productId"
     ],
-    "idempotency": "not_required"
+    "idempotency": "not_required",
+    "takesProductId": true
   }
 };
 
+/** A refusal from Hyperscale, carrying the server's own code and message. */
+export class HyperscaleError extends Error {
+  constructor({ status, code, message, details, requestId }) {
+    super(message);
+    this.name = "HyperscaleError";
+    this.code = code;
+    if (status !== undefined) this.status = status;
+    if (details !== undefined) this.details = details;
+    if (requestId) this.requestId = requestId;
+    if (typeof details?.nextStep === "string") this.nextStep = details.nextStep;
+    if (typeof details?.shortfall === "string")
+      this.shortfall = details.shortfall;
+  }
+}
+
+/** No readable answer arrived, so the request may or may not have run. */
+export class HyperscaleConnectionError extends HyperscaleError {
+  constructor(reason, { status, idempotencyKey, cause } = {}) {
+    super({
+      status,
+      code: "connection_error",
+      message: `${reason}. The outcome is unknown: retry with the same idempotency key.`,
+    });
+    this.name = "HyperscaleConnectionError";
+    if (idempotencyKey) this.idempotencyKey = idempotencyKey;
+    if (cause) this.cause = cause;
+  }
+}
+
+export const isHyperscaleError = (error) => error instanceof HyperscaleError;
+
+const retryStatuses = new Set([408, 429, 500, 502, 503, 504]);
+
 export function createClient({
   apiKey,
   sessionToken,
   productId,
   baseUrl = "https://hyperscale0.ai",
   environment = "sandbox",
+  timeout = 30_000,
+  maxRetries = 2,
   turnstileToken,
 }) {
   if (!apiKey === !sessionToken || !productId)
@@ -707,7 +798,7 @@ export function createClient({
   const credential = sessionToken ?? apiKey;
   const origin = new URL(baseUrl);
   if (
-    origin.origin !== baseUrl ||
+    origin.origin !== baseUrl.replace(/\/+$/, "") ||
     (origin.protocol !== "https:" &&
       !["localhost", "127.0.0.1", "[::1]"].includes(origin.hostname))
   ) {
@@ -717,104 +808,253 @@ export function createClient({
   }
   if (!["sandbox", "live"].includes(environment))
     throw new Error("environment must be sandbox or live");
-  async function request(path, input, idempotencyKey, method, extraHeaders) {
-    const httpMethod = method ?? (input === undefined ? "GET" : "POST");
-    const response = await fetch(new URL(path, origin), {
-      method: httpMethod,
-      headers: {
-        authorization: `Bearer ${credential}`,
-        "x-hyperscale-environment": environment,
-        ...(input === undefined ? {} : { "content-type": "application/json" }),
-        ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
-        ...extraHeaders,
-      },
-      ...(input === undefined ? {} : { body: JSON.stringify(input) }),
-      redirect: "error",
-      signal: AbortSignal.timeout(30_000),
-    });
-    const result = await response.json();
-    if (!response.ok) {
-      const error = new Error(
-        `Hyperscale request failed with HTTP ${response.status}`,
+
+  /** One HTTP exchange: `{ result }`, or `{ error, retryAfter }`. */
+  async function attempt(method, path, body, idempotencyKey, headers) {
+    let response;
+    let text;
+    try {
+      response = await fetch(new URL(path, origin), {
+        method,
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${credential}`,
+          "x-hyperscale-environment": environment,
+          ...(body === undefined ? {} : { "content-type": "application/json" }),
+          ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
+          ...headers,
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        redirect: "error",
+        signal: AbortSignal.timeout(timeout),
+      });
+      text = await response.text();
+    } catch (cause) {
+      const reason =
+        cause?.name === "TimeoutError"
+          ? `No answer from ${origin.origin} within ${timeout} ms`
+          : `Could not reach ${origin.origin}: ${cause?.message ?? cause}`;
+      return {
+        error: new HyperscaleConnectionError(reason, {
+          status: response?.status,
+          idempotencyKey,
+          cause,
+        }),
+      };
+    }
+    let result;
+    try {
+      result = text === "" && response.ok ? undefined : JSON.parse(text);
+    } catch {
+      const reason = `HTTP ${response.status} from ${origin.origin} was not a Hyperscale answer`;
+      return {
+        error: new HyperscaleConnectionError(reason, {
+          status: response.status,
+          idempotencyKey,
+        }),
+      };
+    }
+    if (response.ok) return { result };
+    return {
+      error: new HyperscaleError({
+        status: response.status,
+        code: result?.error?.code ?? "internal_error",
+        message: result?.error?.message ?? `HTTP ${response.status}`,
+        details: result?.error?.details,
+        requestId: result?.requestId ?? response.headers.get("x-request-id"),
+      }),
+      retryAfter: Number(response.headers.get("retry-after")) || 0,
+    };
+  }
+
+  /** Reads retry, and writes retry only under an idempotency key. */
+  async function request(method, path, body, idempotencyKey, headers) {
+    for (let retries = 0; ; retries += 1) {
+      const {
+        result,
+        error,
+        retryAfter = 0,
+      } = await attempt(method, path, body, idempotencyKey, headers);
+      if (!error) return result;
+      if (
+        retries >= maxRetries ||
+        (method !== "GET" && !idempotencyKey) ||
+        !(
+          error instanceof HyperscaleConnectionError ||
+          retryStatuses.has(error.status)
+        )
+      )
+        throw error;
+      const backoff =
+        Math.min(500 * 2 ** retries, 8_000) * (0.5 + Math.random() / 2);
+      await new Promise((resolve) =>
+        setTimeout(resolve, Math.max(backoff, Math.min(retryAfter, 10) * 1000)),
       );
-      error.status = response.status;
-      error.code = result?.error?.code;
-      error.details = result?.error?.details;
-      error.requestId = response.headers.get("x-request-id");
-      throw error;
     }
-    return result;
   }
-  const productPath = `/v1/products/${encodeURIComponent(productId)}`;
-  const actionPath = sessionToken
-    ? `${productPath}/operations`
-    : "/v1/operations";
-  return {
-    reminderDelivery: (operationId) =>
-      request(
-        `${productPath}/payment-reminders/${encodeURIComponent(operationId)}`,
-      ),
-    discover: () => request(`${productPath}/objects`),
-    call: (name, input = {}, options = {}) => {
-      const route = routes[name];
-      if (!route) throw new Error(`Unknown operation: ${name}`);
-      const remaining = { ...input };
-      const path = route.path.replace(/\{([^}]+)\}/g, (_, param) => {
-        let value = remaining[param];
-        if (value === undefined && param === "productId") {
-          value = productId;
-        }
-        if (value === undefined || value === null) {
-          throw new Error(`${name} requires ${param} in input`);
-        }
-        delete remaining[param];
-        return encodeURIComponent(String(value));
-      });
-      const extraHeaders = { ...(options.headers ?? {}) };
-      const turnstile = options.turnstileToken ?? turnstileToken;
-      if (turnstile) {
-        extraHeaders["x-turnstile-token"] ??= turnstile;
-      }
-      if (route.method === "GET") {
-        const params = new URLSearchParams();
-        for (const [key, value] of Object.entries(remaining)) {
-          if (value === undefined || value === null) continue;
-          params.set(
-            key,
-            typeof value === "string" ? value : JSON.stringify(value),
-          );
-        }
-        const query = params.toString();
-        const targetPath = query ? `${path}?${query}` : path;
-        return request(
-          targetPath,
-          undefined,
-          options.idempotencyKey,
-          route.method,
-          extraHeaders,
-        );
-      }
-      return request(
-        path,
-        remaining,
-        options.idempotencyKey,
-        route.method,
-        extraHeaders,
+
+  // A Product key's own operations (key create's allowedOperationIds) are
+  // listed by id and name in the Product's operation set.
+  let operationSet;
+  async function productOperationName(name) {
+    if (sessionToken) return name;
+    operationSet ??= call("product.operation_set.retrieve", {}).catch(
+      (error) => {
+        operationSet = undefined;
+        throw error;
+      },
+    );
+    const { operations } = await operationSet;
+    const operation = operations.find(
+      (entry) => entry.operationName === name || entry.operationId === name,
+    );
+    if (!operation)
+      throw new Error(
+        `Unknown operation ${name}. This Product's own operations are listed by product.operation_set.retrieve.`,
       );
-    },
-    instruments: () => request(`${productPath}/instruments`),
-    actions: (instrument) =>
-      request(
-        `${productPath}/actions${instrument ? `?instrument=${encodeURIComponent(instrument)}` : ""}`,
-      ),
-    act: (name, input, { idempotencyKey } = {}) => {
-      if (!idempotencyKey)
-        throw new Error("act requires an idempotencyKey for safe retries");
+    return operation.operationName;
+  }
+
+  async function call(name, input = {}, options = {}) {
+    const route = routes[name];
+    const headers = { ...options.headers };
+    const turnstile = options.turnstileToken ?? turnstileToken;
+    if (turnstile) headers["x-turnstile-token"] ??= turnstile;
+    if (!route) {
+      const operation = await productOperationName(name);
+      const path = sessionToken
+        ? `/v1/products/${encodeURIComponent(productId)}/operations`
+        : "/v1/operations";
+      // Reads ignore the key; writes need one.
       return request(
-        `${actionPath}/${encodeURIComponent(name)}`,
+        "POST",
+        `${path}/${encodeURIComponent(operation)}`,
         input,
-        idempotencyKey,
+        options.idempotencyKey ?? crypto.randomUUID(),
+        headers,
+      );
+    }
+    const remaining =
+      route.takesProductId && input.productId === undefined
+        ? { ...input, productId }
+        : { ...input };
+    const path = route.path.replace(/\{([^}]+)\}/g, (_, param) => {
+      const value = remaining[param];
+      if (value === undefined || value === null)
+        throw new Error(`${name} requires ${param} in input`);
+      delete remaining[param];
+      return encodeURIComponent(String(value));
+    });
+    const idempotencyKey =
+      options.idempotencyKey ??
+      (route.idempotency === "required" ? crypto.randomUUID() : undefined);
+    if (route.method !== "GET")
+      return request(route.method, path, remaining, idempotencyKey, headers);
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(remaining))
+      if (value !== undefined && value !== null)
+        query.set(
+          key,
+          typeof value === "string" ? value : JSON.stringify(value),
+        );
+    const search = query.toString();
+    return request(
+      "GET",
+      search ? `${path}?${search}` : path,
+      undefined,
+      idempotencyKey,
+      headers,
+    );
+  }
+
+  async function* paginate(name, input = {}, options) {
+    const collection = routes[name]?.collection;
+    if (!collection) throw new Error(`${name} is not a cursor list`);
+    const seen = new Set();
+    let page = await call(name, input, options);
+    yield* page[collection];
+    while (page.nextCursor) {
+      if (seen.has(page.nextCursor))
+        throw new Error(`${name} repeated cursor ${page.nextCursor}`);
+      seen.add(page.nextCursor);
+      page = await call(name, { ...input, cursor: page.nextCursor }, options);
+      yield* page[collection];
+    }
+  }
+
+  // What run sent under a key whose outcome is unknown, so a retry with that
+  // key resends it even if the first attempt moved the object on.
+  const sent = new Map();
+  async function run(kind, objectId, action, options = {}) {
+    const { onBehalfOf, fields, inputs, instanceId } = options;
+    const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+    let body = sent.get(idempotencyKey);
+    if (!body) {
+      const read = { kind, objectId, ...(onBehalfOf ? { onBehalfOf } : {}) };
+      let page = await call("product.objects.actions", read);
+      const { revision } = page;
+      const actions = [...page.actions];
+      while (page.nextCursor) {
+        page = await call("product.objects.actions", {
+          ...read,
+          cursor: page.nextCursor,
+        });
+        if (page.revision !== revision)
+          throw new HyperscaleError({
+            code: "state_conflict",
+            message: `${kind} ${objectId} changed while its actions were read. Run it again.`,
+          });
+        actions.push(...page.actions);
+      }
+      const matches = actions.filter(
+        (entry) =>
+          entry.name === action &&
+          (!instanceId || entry.target.instanceId === instanceId),
       );
-    },
+      if (matches.length !== 1)
+        throw new HyperscaleError({
+          code: matches.length ? "invalid_request" : "not_found",
+          message: matches.length
+            ? `${action} runs on several agreements of ${kind} ${objectId}. Pass instanceId: ${matches.map((entry) => entry.target.instanceId).join(", ")}.`
+            : `${kind} ${objectId} has no action ${action}. Its actions: ${[...new Set(actions.map((entry) => entry.name))].join(", ") || "none"}.`,
+        });
+      const [selected] = matches;
+      const { availability } = selected;
+      if (availability.status === "unavailable")
+        throw new HyperscaleError({
+          code: availability.blockers[0]?.code ?? "state_conflict",
+          message: availability.blockers
+            .map((blocker) => blocker.reason)
+            .join(" "),
+          details: { blockers: availability.blockers },
+        });
+      body = {
+        kind,
+        objectId,
+        action,
+        expectedRevision: revision,
+        productBuildId: selected.productBuildId,
+        digest: selected.digest,
+        target: selected.target,
+        ...(fields ? { fields } : {}),
+        ...(inputs ? { input: inputs } : {}),
+        ...(onBehalfOf ? { onBehalfOf } : {}),
+      };
+    }
+    sent.delete(idempotencyKey);
+    try {
+      return await call("product.objects.execute", body, { idempotencyKey });
+    } catch (error) {
+      if (error instanceof HyperscaleConnectionError)
+        sent.set(idempotencyKey, body);
+      throw error;
+    }
+  }
+
+  return {
+    discover: () => call("product.objects.discover", {}),
+    call,
+    paginate,
+    objects: { run },
   };
 }