@hyperscale0/sdk 3.0.0 → 3.2.0

package/README.md

@@ -1,25 +1,74 @@
 # @hyperscale0/sdk
 
 One client for every Hyperscale Product. Platform types ship with the package.
-Instrument fields and public action inputs come from the admitted Build at runtime.
+Object kinds, fields and action availability come from the admitted Build at runtime.
 
 ```js
 import { createClient } from "@hyperscale0/sdk";
 
+const productId = process.env.HYPERSCALE_PRODUCT_ID;
 const client = createClient({
   apiKey: process.env.HYPERSCALE_API_KEY,
-  productId: process.env.HYPERSCALE_PRODUCT_ID,
+  productId,
 });
-const { instruments, actions } = await client.discover();
+const discovery = await client.call("product.objects.discover", { productId });
+// 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,
+});
+```
+
+Choose the intended action by name. Check `availability.status` and collect its
+`requiredNow` fields and requirements against `fieldsSchema` and `inputSchema`.
+After that review, execute it with the complete context returned by the server:
+
+```js
+const action = available.actions.find((item) => item.name === chosenActionName);
+if (!action || action.availability.status !== "available") {
+  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" },
+);
 ```
 
-Use `client.call(operationName, input, { idempotencyKey })` for platform operations.
-Their names and types match the operation descriptors.
+`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.
+These six operations use the descriptor-backed generic operation transport in
+`client.call`. Names and types match the operation descriptors.
+
+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.
 
-Call `client.act(name, input, { idempotencyKey })` with an action name and input
-from discovery. Reuse the same idempotency key and input when retrying a request.
-The client never retries a mutation automatically. Keys stay in your environment.
-Set `baseUrl` and `environment` to select an estate and sandbox or live plane.
+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.
 
 Security: https://hyperscale0.ai/security
 

package/client.d.ts

@@ -5,8 +5,15 @@ import type {
 } from "./platform.js";
 export type * from "./platform.js";
 
+import type {
+  sandbox_rehearsal_createOutput,
+  payment_reminder_delivery_retrieveOutput,
+} from "./portal.js";
+
 export interface ClientOptions {
-  apiKey: string;
+  apiKey?: string;
+  sessionToken?: string;
+  staffTenantId?: string;
   productId: string;
   baseUrl?: string;
   environment?: "sandbox" | "live";
@@ -18,6 +25,13 @@ export interface ActionInput {
   input?: Record<string, unknown>;
 }
 export interface Client {
+  rehearse(
+    name: string,
+    options: { idempotencyKey: string },
+  ): Promise<sandbox_rehearsal_createOutput>;
+  reminderDelivery(
+    operationId: string,
+  ): Promise<payment_reminder_delivery_retrieveOutput>;
   discover(): Promise<{
     instruments: product_instruments_listOutput;
     actions: product_actions_listOutput;

package/client.js

@@ -1,11 +1,20 @@
 export function createClient({
   apiKey,
+  sessionToken,
+  staffTenantId,
   productId,
   baseUrl = "https://hyperscale0.ai",
   environment = "sandbox",
 }) {
-  if (!apiKey || !productId)
-    throw new Error("apiKey and productId are required");
+  if (
+    !apiKey === !sessionToken ||
+    !productId ||
+    (staffTenantId && !sessionToken)
+  )
+    throw new Error(
+      "Choose one API key or session token and a Product; staff requires a session",
+    );
+  const credential = sessionToken ?? apiKey;
   const origin = new URL(baseUrl);
   if (
     origin.origin !== baseUrl ||
@@ -22,7 +31,7 @@ export function createClient({
     const response = await fetch(new URL(path, origin), {
       method: input === undefined ? "GET" : "POST",
       headers: {
-        authorization: `Bearer ${apiKey}`,
+        authorization: `Bearer ${credential}`,
         "x-hyperscale-environment": environment,
         ...(input === undefined ? {} : { "content-type": "application/json" }),
         ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
@@ -38,13 +47,34 @@ export function createClient({
       );
       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 = staffTenantId
+    ? `/v1/admin/tenants/${encodeURIComponent(staffTenantId)}/products/${encodeURIComponent(productId)}/operations`
+    : sessionToken
+      ? `${productPath}/operations`
+      : "/v1/operations";
   return {
+    rehearse: (name, { idempotencyKey } = {}) => {
+      if (!sessionToken || staffTenantId || !idempotencyKey)
+        throw new Error(
+          "rehearse requires a tenant session and idempotency key",
+        );
+      return request(
+        "/v1/sandbox/rehearsals",
+        { productId, name },
+        idempotencyKey,
+      );
+    },
+    reminderDelivery: (operationId) =>
+      request(
+        `${productPath}/payment-reminders/${encodeURIComponent(operationId)}`,
+      ),
     discover: async () => {
       const [instruments, actions] = await Promise.all([
         request(`${productPath}/instruments`),
@@ -71,7 +101,7 @@ export function createClient({
       if (!idempotencyKey)
         throw new Error("act requires an idempotencyKey for safe retries");
       return request(
-        `/v1/operations/${encodeURIComponent(name)}`,
+        `${actionPath}/${encodeURIComponent(name)}`,
         input,
         idempotencyKey,
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/sdk",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "type": "module",
   "sideEffects": false,
   "license": "LicenseRef-Hyperscale-Proprietary",
@@ -22,5 +22,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "ceeb9999f9724709720171ecbd457ac180941901"
+  "gitHead": "a238da0dbb6ed4e454852cf7f8dbdf1015520d18"
 }