@hyperscale0/sdk 1.0.338 → 1.0.339

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+`@hyperscale0/sdk` ships as `1.0.N` with Hyperscale release rN, so `1.0.341` is the client for r341. Install `@latest` or pin `^1.0.0`. The `3.x` and `4.x` versions on npm are an old numbering, deprecated, and older than every `1.0.N`.
+
+Newest first. A release that changed nothing the SDK sees has no entry.
+
+## 1.0.341
+
+### Added
+
+- `npx @hyperscale0/sdk types --product <prd_…> --name <Name>` prints a declaration of your Product's kinds, actions, fields and inputs. `createClient<Name>()` then rejects a kind or action the Product does not have, at compile time.
+- `product.books.retrieve` reads a Product's position, revenue to date and monthly books in one call.
+- `product.objects.execute` answers with `receiptId`, the same id as the `hyperscale-receipt-id` header.
+- This changelog ships in the package.
+
+### Changed
+
+- A retrieve answers with the resource itself. `customer.retrieve`, `account.retrieve`, `receipt.retrieve`, `operation.retrieve`, `internal_transfer.retrieve`, `webhook.endpoint.retrieve` and the other resource retrieves used to answer `{ item }`; read the fields off the result.
+- Prices read in halalas like every other amount. The fees and rates on `product.retrieve`, `product.activation.retrieve`, `composer.plan`, `catalog.pricing.retrieve`, `product.margin.retrieve` and each `usage.statement` rate used to be riyal decimals: a `monthly` of `"2500"` now reads `"250000"`, and a rate of `"0.25"` reads `"25"`. `expectedPricing` takes halalas.
+- The client sends `Accept: application/json`, so `account.statement.export` keeps answering with the JSON envelope while curl gets the CSV file.
+
+## 1.0.340
+
+### Removed
+
+- The route table no longer lists `product.list`, `product.retrieve`, `developer.log.list`, `developer.log.retrieve`, `transfer_return.create` or `usage.statement`. A Product key could not call them. `call` with one of these names now throws `Unknown operation` instead of sending a request the server refuses.
+
+## 1.0.339
+
+### Added
+
+- `HyperscaleError` carries the server's `code`, `message`, `details`, `requestId`, `nextStep` and `shortfall`. `HyperscaleConnectionError` means no readable answer arrived.
+- The client makes an idempotency key for every write that needs one and keeps it across its own retries.
+- `objects.run` reads an action, throws its blocker, and sends the revision, Build and target it read.
+- `paginate` walks every list. `productId` is optional in inputs.

package/README.md

@@ -1,85 +1,122 @@
 # @hyperscale0/sdk
 
-Read [how Hyperscale fits](https://hyperscale0.ai/docs/runtime.md#how-hyperscale-fits). The SDK calls the shared operation API and grants no additional authority.
+TypeScript client for running a Hyperscale Product: customers, payments, schedules and the sandbox clock.
 
-One client for every Hyperscale Product. Platform types ship with the package.
-Object kinds, fields and action availability come from the admitted Build at runtime.
+```sh
+npm i @hyperscale0/sdk
+```
 
-```js
-import { createClient } from "@hyperscale0/sdk";
+The SDK runs a Product that already exists. Create the Product with `hyperscale product create` or in the Build portal, and copy its `prd_…` id. `hyperscale key create --product <id>` shows the key's secret once. Export them as `HYPERSCALE_PRODUCT_ID` and `HYPERSCALE_API_KEY`.
+
+## Quickstart
+
+This runs as written in sandbox against the gym program from the [HSX guide](https://hyperscale0.ai/docs/hsx.md#schedules): a `membership` object with `start_membership`, `accept_membership` and `end_membership`.
+
+```ts
+import { createClient, HyperscaleError } from "@hyperscale0/sdk";
 
-const productId = process.env.HYPERSCALE_PRODUCT_ID;
-const client = createClient({
+const hs = createClient({
   apiKey: process.env.HYPERSCALE_API_KEY,
-  productId,
+  productId: process.env.HYPERSCALE_PRODUCT_ID,
 });
-const discovery = await client.discover();
-// Choose a kind and supply metadata according to its createSchema.
-const kind = discovery.kinds[0].kind;
-const object = await client.call(
-  "product.objects.create",
-  { productId, kind },
-  {
-    idempotencyKey: "object-create-001",
-  },
-);
-const available = await client.call("product.objects.actions", {
-  productId,
-  kind,
-  objectId: object.objectId,
+
+// A test customer with SAR 300 in a sandbox balance. Amounts are halalas.
+const { customerId } = await hs.call("customer.create", {
+  entity: { kind: "person", displayName: "Noura Alharbi", country: "SA" },
+  test: true,
+});
+const { accountId } = await hs.call("account.create", {
+  owner: { type: "customer", id: customerId },
+  role: "customer_balance",
+  currency: "SAR",
+});
+await hs.call("sandbox.account.fund", {
+  destinationAccountId: accountId,
+  amount: "30000",
+  currency: "SAR",
 });
-```
 
-Choose the intended action by name and check `availability.status`. An
-`unavailable` action lists its `blockers`. A `requires_input` action is runnable
-once you supply what it names in `subjectFields` and `actionInputs`: collect its
-`requiredNow` fields and requirements against `fieldsSchema` and `inputSchema`.
-After that review, execute it with the complete context returned by the server:
+// A membership Noura owns. The gym starts it tomorrow and she accepts it.
+const { effectiveAt } = await hs.call("sandbox.clock.retrieve", {});
+const day = (n) =>
+  new Date(Date.parse(effectiveAt) + n * 86_400_000).toISOString();
+const { objectId } = await hs.call("product.objects.create", {
+  kind: "membership",
+  fields: { plan: "Monthly" },
+  onBehalfOf: customerId,
+});
+await hs.objects.run("membership", objectId, "start_membership", {
+  inputs: { startsAt: day(1) },
+});
+await hs.objects.run("membership", objectId, "accept_membership", {
+  onBehalfOf: customerId,
+});
 
-```js
-const action = available.actions.find((item) => item.name === chosenActionName);
-if (!action || action.availability.status === "unavailable") {
-  throw new Error("The selected action is unavailable");
-}
-const result = await client.call(
-  "product.objects.execute",
-  {
-    productId,
-    kind,
-    objectId: object.objectId,
-    action: action.name,
-    expectedRevision: available.revision,
-    productBuildId: action.productBuildId,
-    digest: action.digest,
-    target: action.target,
-    fields: collectedFields,
-    input: collectedInput,
-  },
-  { idempotencyKey: "object-action-001" },
+// Two days on, the first SAR 250 of dues runs.
+const { ran } = await hs.call("sandbox.clock.advance", { at: day(2) });
+console.log(
+  ran.map((piece) => `${piece.action} ${piece.amount?.value} ${piece.status}`),
 );
+
+// A refusal carries the server's own words.
+try {
+  await hs.objects.run("membership", objectId, "end_membership", {
+    onBehalfOf: customerId,
+  });
+} catch (error) {
+  if (!(error instanceof HyperscaleError)) throw error;
+  console.log(error.code, error.message);
+}
 ```
 
-`chosenActionName`, `collectedFields` and `collectedInput` are application inputs
-from that review. Object creation does not create an agreement or move money.
-Use `product.objects.list` and `product.objects.retrieve` to read stored objects.
-`discover()` returns the authored object contract in one request, including fields
-and exposed actions. All six operations also use the descriptor-backed generic
-operation transport in `client.call`. Names and types match the operation descriptors.
-
-To take a customer's step, such as a buyer paying into escrow, add
-`onBehalfOf: "<customer id>"` to `product.objects.create`, `actions`, `execute`
-or `preview`. The call runs with that customer's accounts, the Product key keeps
-its view of every record, and the agreement records both the key and the
-customer. A create with `onBehalfOf` makes that customer the owner.
-
-Copy the whole target, including `instanceId` when present. Refresh availability
-after a revision or Build conflict. Reuse the same key and body for an uncertain
-request. The client never retries a mutation automatically.
-
-Low-level `instruments()`, `actions()` and `act()` remain for admitted inspection
-and operations. Instrument creation stays internal to object attachment execution.
-Keys stay in your environment. Set `baseUrl` and `environment` to select an estate
-and sandbox or live plane.
+`objects.run` reads the action first. If it can't run, it throws `HyperscaleError` with the reason. Otherwise it sends the revision, Build and target it read.
+
+## Types
+
+Until you generate your Product's types, `kind`, `action`, `fields` and `input` take any string and any record. The generator reads `product.objects.discover` with `HYPERSCALE_API_KEY`, plus `HYPERSCALE_BASE_URL` and `HYPERSCALE_ENVIRONMENT` when set, and prints one declaration:
+
+```sh
+npx @hyperscale0/sdk types --product $HYPERSCALE_PRODUCT_ID --name DeskAndKey > desk-and-key.d.ts
+```
+
+```ts
+import { createClient } from "@hyperscale0/sdk";
+import type { DeskAndKey } from "./desk-and-key";
+
+const hs = createClient<DeskAndKey>({
+  apiKey: process.env.HYPERSCALE_API_KEY,
+  productId: process.env.HYPERSCALE_PRODUCT_ID,
+});
+```
+
+With the type argument, a kind such as `"day-pass"` when the Product has `day_pass`, or an action such as `"pay_daypass"`, fails to compile instead of failing at runtime. `objects.run`, `product.objects.create`, `product.objects.execute`, `product.objects.preview` and every call that takes a `kind` check against it, and money fields are minor-unit strings. Regenerate the file after each publish. Without a type argument, `createClient()` takes any kind and action.
+
+## 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`.
+
+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`.
+
+## Operations
+
+`client.call(name, input)` runs any operation, and names autocomplete. `productId` comes from the client. `client.paginate(name, input)` iterates every record of a list.
+
+| Job          | Operations                                                                                                                                                                                      |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Objects      | `product.objects.discover`, `product.objects.create`, `product.objects.list`, `product.objects.retrieve`, `product.objects.actions`, `product.objects.execute`, `product.objects.timeline.list` |
+| Customers    | `customer.create`, `customer.list`, `customer.retrieve`                                                                                                                                         |
+| Money        | `account.create`, `account.balance.retrieve`, `account.statement.retrieve`, `internal_transfer.list`, `receipt.list`                                                                            |
+| Sandbox      | `sandbox.account.fund`, `sandbox.clock.retrieve`, `sandbox.clock.advance`                                                                                                                       |
+| The business | `activity.list`, `product.schedule.list`, `product.work.list`, `product.treasury.retrieve`, `product.books.retrieve`                                                                            |
+| Webhooks     | `webhook.endpoint.create`, `webhook.endpoint.list`, `webhook.delivery.list`, `event.list`                                                                                                       |
+
+Your Product's own operations from `key create`, such as `membership_dues_instances_list`, go through `call` too. [openapi.json](https://hyperscale0.ai/openapi.json) lists every platform operation with its schema, and [Product actions](https://hyperscale0.ai/docs/runtime.md) explains how they fit together.
+
+Set `environment: "live"` for live money; the default is sandbox.
+
+## Versions
+
+The SDK ships as `1.0.N` with Hyperscale release rN. `CHANGELOG.md`, in the package, lists what each version added, changed and removed. The `3.x` and `4.x` versions on npm are deprecated and older than every `1.0.N`, so pin `^1.0.0`.
 
 Security: https://hyperscale0.ai/security
 

package/bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { typesCommand } from "./product-types.js";
+
+try {
+  process.stdout.write(await typesCommand(process.argv.slice(2), process.env));
+} catch (error) {
+  process.stderr.write(
+    `${error.code ? `${error.code}: ` : ""}${error.message}\n`,
+  );
+  process.exitCode = 1;
+}

package/client.d.ts

@@ -1,46 +1,193 @@
 import type {
+  ErrorCode,
+  ListOperations,
   Operations,
-  payment_reminder_delivery_retrieveOutput,
+  product_objects_actionsOutput,
   product_objects_discoverOutput,
-  product_instruments_listOutput,
-  product_actions_listOutput,
+  product_objects_executeOutput,
 } from "./platform.js";
 export type * from "./platform.js";
 
 export interface ClientOptions {
+  /** A Product key from `hyperscale key create`. */
   apiKey?: string;
+  /** A customer session token, in place of a Product key. */
   sessionToken?: string;
+  /** The key's Product. Calls fill it in when their input leaves it out. */
   productId: string;
+  /** Defaults to https://hyperscale0.ai. */
   baseUrl?: string;
+  /** Defaults to sandbox. */
   environment?: "sandbox" | "live";
+  /** Milliseconds each attempt may take. Defaults to 30000. */
+  timeout?: number;
+  /** Retries for reads, and for writes under an idempotency key. Defaults to 2. */
+  maxRetries?: number;
   turnstileToken?: string;
 }
-export interface ActionInput {
+
+export interface CallOptions {
+  /** The client makes one for operations that need it; yours wins. */
+  idempotencyKey?: string;
+  turnstileToken?: string;
+  headers?: Record<string, string>;
+}
+
+/** One action of a generated Product type: subject fields and input. */
+export interface ActionTypes {
+  fields: Record<string, unknown>;
+  input: Record<string, unknown>;
+}
+
+/**
+ * What `npx @hyperscale0/sdk types --product <id>` generates. Pass it as
+ * `createClient<P>()` to type each kind, its fields, its actions and their
+ * input. Without it, kinds and actions are any string.
+ */
+export interface ProductTypes {
+  kinds: Record<
+    string,
+    { fields: Record<string, unknown>; actions: Record<string, ActionTypes> }
+  >;
+}
+
+type KindName<P extends ProductTypes> = keyof P["kinds"] & string;
+type ActionName<
+  P extends ProductTypes,
+  Kind extends KindName<P>,
+> = keyof P["kinds"][Kind]["actions"] & string;
+
+export interface RunOptions<Action extends ActionTypes = ActionTypes> {
+  /** The customer the action runs for, such as the object's owner. */
+  onBehalfOf?: string;
+  fields?: Action["fields"];
+  inputs?: Action["input"];
+  /** Chooses one agreement when the action runs on several. */
   instanceId?: string;
-  fields?: Record<string, unknown>;
-  parties?: Record<string, string>;
-  input?: Record<string, unknown>;
-}
-export interface Client {
-  reminderDelivery(
-    operationId: string,
-  ): Promise<payment_reminder_delivery_retrieveOutput>;
+  idempotencyKey?: string;
+}
+
+/** Input with productId optional, since the client fills it in. */
+export type CallInput<T> = T extends { readonly productId: string }
+  ? { [K in keyof T as K extends "productId" ? never : K]: T[K] } & {
+      readonly productId?: string;
+    }
+  : T;
+
+type Narrow<T, U> = Omit<T, keyof U> & U;
+
+/**
+ * Call input with kind, action, fields and input narrowed to a generated
+ * Product type. Without one, it is CallInput unchanged.
+ */
+export type ProductCallInput<
+  P extends ProductTypes,
+  Name extends keyof Operations,
+> = string extends keyof P["kinds"]
+  ? CallInput<Operations[Name]["input"]>
+  : Name extends "product.objects.create"
+    ? {
+        [Kind in KindName<P>]: Narrow<
+          CallInput<Operations[Name]["input"]>,
+          { readonly kind: Kind; readonly fields?: P["kinds"][Kind]["fields"] }
+        >;
+      }[KindName<P>]
+    : Name extends "product.objects.execute" | "product.objects.preview"
+      ? {
+          [Kind in KindName<P>]: {
+            [Action in ActionName<P, Kind>]: Narrow<
+              CallInput<Operations[Name]["input"]>,
+              {
+                readonly kind: Kind;
+                readonly action: Action;
+                readonly fields?: P["kinds"][Kind]["actions"][Action]["fields"];
+                readonly input?: P["kinds"][Kind]["actions"][Action]["input"];
+              }
+            >;
+          }[ActionName<P, Kind>];
+        }[KindName<P>]
+      : Operations[Name]["input"] extends { readonly kind: infer Kind }
+        ? string extends Kind
+          ? Narrow<
+              CallInput<Operations[Name]["input"]>,
+              { readonly kind: KindName<P> }
+            >
+          : CallInput<Operations[Name]["input"]>
+        : CallInput<Operations[Name]["input"]>;
+
+type Unavailable = Extract<
+  product_objects_actionsOutput["actions"][number]["availability"],
+  { status: "unavailable" }
+>;
+export type ActionBlockerCode = Unavailable["blockers"][number]["code"];
+
+export type ListItem<Name extends keyof ListOperations & keyof Operations> =
+  Operations[Name]["output"] extends {
+    readonly [Key in ListOperations[Name]]: ReadonlyArray<infer Item>;
+  }
+    ? Item
+    : never;
+
+/** A refusal from Hyperscale: `message` is the server's own text. */
+export declare class HyperscaleError extends Error {
+  readonly code: ErrorCode | ActionBlockerCode | "connection_error";
+  /** The HTTP status, when an answer arrived. */
+  readonly status?: number;
+  readonly details?: Readonly<Record<string, unknown>>;
+  readonly requestId?: string;
+  /** What to do next, when the server names it. */
+  readonly nextStep?: string;
+  /** Minor units missing from the paying account, when money ran short. */
+  readonly shortfall?: string;
+}
+
+/** No readable answer: the request may have run. Retry with the same key. */
+export declare class HyperscaleConnectionError extends HyperscaleError {
+  readonly code: "connection_error";
+  /** The key the request carried; pass it again to retry safely. */
+  readonly idempotencyKey?: string;
+}
+
+export declare function isHyperscaleError(
+  error: unknown,
+): error is HyperscaleError;
+
+export interface Client<P extends ProductTypes = ProductTypes> {
+  /** The Product's object kinds, their fields and their actions. */
   discover(): Promise<product_objects_discoverOutput>;
   call<Name extends keyof Operations>(
     name: Name,
-    input: Operations[Name]["input"],
-    options?: {
-      idempotencyKey?: string;
-      turnstileToken?: string;
-      headers?: Record<string, string>;
-    },
+    input: ProductCallInput<P, Name>,
+    options?: CallOptions,
   ): Promise<Operations[Name]["output"]>;
-  instruments(): Promise<product_instruments_listOutput>;
-  actions(instrument?: string): Promise<product_actions_listOutput>;
-  act(
-    name: string,
-    input: ActionInput,
-    options: { idempotencyKey: string },
-  ): Promise<Record<string, unknown>>;
-}
-export function createClient(options: ClientOptions): Client;
+  /** An operation of your own Product, by id or name from `key create`. */
+  call<Name extends string>(
+    // A typed client sends platform operations through the overload above only.
+    name: string extends keyof P["kinds"]
+      ? Name
+      : Name extends keyof Operations
+        ? never
+        : Name,
+    input?: Record<string, unknown>,
+    options?: CallOptions,
+  ): Promise<unknown>;
+  /** Every record of a cursor list, page by page. */
+  paginate<Name extends keyof ListOperations & keyof Operations>(
+    name: Name,
+    input: ProductCallInput<P, Name>,
+    options?: CallOptions,
+  ): AsyncGenerator<ListItem<Name>, void, undefined>;
+  objects: {
+    /** Reads the action's current state, then runs it. */
+    run<Kind extends KindName<P>, Action extends ActionName<P, Kind>>(
+      kind: Kind,
+      objectId: string,
+      action: Action,
+      options?: RunOptions<P["kinds"][Kind]["actions"][Action]>,
+    ): Promise<product_objects_executeOutput>;
+  };
+}
+/** Pass a type from `npx @hyperscale0/sdk types` as P to type kinds and actions. */
+export function createClient<P extends ProductTypes = ProductTypes>(
+  options: ClientOptions,
+): Client<P>;