@hyperscale0/sdk 1.0.382 → 1.0.385

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 Newest first. A release that changed nothing the SDK sees has no entry.
 
+## Unreleased
+
+### Added
+
+- `HyperscaleError.trace`, with `gate` and `remedy` lifted from it: the admission gate that refused, its law in one sentence, the facts it saw and the remedy, an operation with the fields to change or the person who must act. `RefusalTrace` types it.
+
+- `client.call(name, input, { rehearse: true })` runs a mutation with no effect. The client sends `X-Hyperscale-Rehearsal: true`, and the call answers `OperationRehearsal`: the would-be `outcome`, `status`, `output` or `error`, receipt and ledger `postings`. A platform read refuses the option.
+
+### Changed
+
+- `bank_statement` joined the `resourceKind` union: `activity.list` takes it as a filter and `activity.retrieve` can answer with it. An exhaustive switch over `resourceKind` needs the new case.
+
 ## 1.0.364
 
 ### Added

package/README.md

@@ -93,7 +93,7 @@ With the type argument, a kind such as `"day-pass"` when the Product has `day_pa
 
 ## Errors and retries
 
-Every refusal is a `HyperscaleError` with the server's `message`, `code`, `status`, `details` and `requestId`, plus `nextStep` and `shortfall` when the server sends them. When no readable answer arrives (a timeout, a dropped connection, an HTML error page), the client throws `HyperscaleConnectionError`: the call may have run, so retry it with the same `idempotencyKey`.
+Every refusal is a `HyperscaleError` with the server's `message`, `code`, `status`, `details` and `requestId`, plus `nextStep` and `shortfall` when the server sends them, and `trace` with `gate` and `remedy`: which admission gate refused, its law, the facts it saw and what would let the call pass ([errors](../../docs/public/api.md#errors)). When no readable answer arrives (a timeout, a dropped connection, an HTML error page), the client throws `HyperscaleConnectionError`: the call may have run, so retry it with the same `idempotencyKey`.
 
 The client makes an idempotency key for every write that needs one and keeps it across its own retries. Pass `{ idempotencyKey }` as the third argument to choose it. Reads retry on 408, 429 and 5xx, and writes retry only under a key. Set `timeout` (default 30000 ms) and `maxRetries` (default 2) in `createClient`.
 

package/client.d.ts

@@ -1,13 +1,19 @@
 import type {
   ErrorCode,
+  ErrorResponse,
   ListOperations,
-  Operations,
+  OperationRehearsal,
+  OperationsFor,
   product_objects_actionsOutput,
   product_objects_discoverOutput,
   product_objects_executeOutput,
+  RehearsableOperation,
 } from "./platform.js";
 export type * from "./platform.js";
 
+/** The operations a Product key or a customer session may call. */
+export type Operations = OperationsFor<"api_key" | "customer_session">;
+
 export interface ClientOptions {
   /** A Product key from `hyperscale key create`. */
   apiKey?: string;
@@ -31,6 +37,11 @@ export interface CallOptions {
   idempotencyKey?: string;
   turnstileToken?: string;
   headers?: Record<string, string>;
+  /**
+   * True runs a mutation with no effect: admission and execution run, nothing
+   * is kept, and the call answers OperationRehearsal in place of its output.
+   */
+  rehearse?: boolean;
 }
 
 /** One action of a generated Product type: subject fields and input. */
@@ -139,8 +150,17 @@ export declare class HyperscaleError extends Error {
   readonly nextStep?: string;
   /** Minor units missing from the paying account, when money ran short. */
   readonly shortfall?: string;
+  /** Which admission gate refused, the law it applied, the facts it saw and the remedy. */
+  readonly trace?: RefusalTrace;
+  /** The refusing gate, from `trace`. */
+  readonly gate?: RefusalTrace["gate"];
+  /** What would pass: an operation and the fields to change, or who must act. */
+  readonly remedy?: RefusalTrace["remedy"];
 }
 
+/** The refusal trace every error body carries; see docs/design/refusals.md. */
+export type RefusalTrace = NonNullable<ErrorResponse["error"]["trace"]>;
+
 /** No readable answer: the request may have run. Retry with the same key. */
 export declare class HyperscaleConnectionError extends HyperscaleError {
   readonly code: "connection_error";
@@ -155,10 +175,16 @@ export declare function isHyperscaleError(
 export interface Client<P extends ProductTypes = ProductTypes> {
   /** The Product's object kinds, their fields and their actions. */
   discover(): Promise<product_objects_discoverOutput>;
+  /** A rehearsed mutation: what it would do, with nothing kept. */
+  call<Name extends keyof Operations & RehearsableOperation>(
+    name: Name,
+    input: ProductCallInput<P, Name>,
+    options: CallOptions & { rehearse: true },
+  ): Promise<OperationRehearsal>;
   call<Name extends keyof Operations>(
     name: Name,
     input: ProductCallInput<P, Name>,
-    options?: CallOptions,
+    options?: CallOptions & { rehearse?: false },
   ): Promise<Operations[Name]["output"]>;
   /** An operation of your own Product, by id or name from `key create`. */
   call<Name extends string>(
@@ -175,7 +201,7 @@ export interface Client<P extends ProductTypes = ProductTypes> {
   paginate<Name extends keyof ListOperations & keyof Operations>(
     name: Name,
     input: ProductCallInput<P, Name>,
-    options?: CallOptions,
+    options?: Omit<CallOptions, "rehearse">,
   ): AsyncGenerator<ListItem<Name>, void, undefined>;
   objects: {
     /** Reads the action's current state, then runs it. */