@work-shape/catalyst-api-client 0.8.0-rc.2 → 0.8.0-rc.3

package/dist/index.d.ts

@@ -127,7 +127,12 @@ type ControlPart<Op extends Operation> = {
 } ? {
     /** Called when the server has nothing after the given position and sends no stream. */
     onCaughtUp?: () => void;
-} : unknown);
+} & (Op["response"] extends {
+    skip: infer Skip extends z.ZodType;
+} ? {
+    /** Called for an event this client does not know, which the stream passes over. */
+    onSkipped?: (value: z.output<Skip>) => void;
+} : unknown) : unknown);
 /**
  * An operation that takes an `Idempotency-Key` gets a new one with every call. A caller that
  * sends the same call again after an answer that never arrived passes the key of the first.
@@ -139,7 +144,18 @@ type IdempotencyPart<Op> = Op extends {
 } ? "Idempotency-Key" extends Header ? {
     idempotencyKey?: string;
 } : unknown : unknown;
-type InputOf<Op extends Operation> = ParamsPart<Op["path"]> & QueryPart<Op> & BodyPart<Op> & IdempotencyPart<Op> & ControlPart<Op>;
+/**
+ * An operation that takes `Catalyst-Unattended` is sent with it when `unattended` is set: nobody
+ * watches the caller's terminal, so a call that needs a confirmation waits in the Inbox.
+ */
+type UnattendedPart<Op> = Op extends {
+    headers: {
+        request: readonly (infer Header extends OperationRequestHeader)[];
+    };
+} ? "Catalyst-Unattended" extends Header ? {
+    unattended?: boolean;
+} : unknown : unknown;
+type InputOf<Op extends Operation> = ParamsPart<Op["path"]> & QueryPart<Op> & BodyPart<Op> & IdempotencyPart<Op> & UnattendedPart<Op> & ControlPart<Op>;
 /**
  * How a call of an operation that may wait for an approval came out. A refusal and a failure
  * are thrown as `ApiError`, as for every operation.
@@ -153,7 +169,10 @@ type OperationOutcome<Output, Run = unknown> = {
     status: "done";
     output: Output;
 }
-/** Nothing ran yet: somebody else decides. `location` is where the run is read again. */
+/**
+ * Nothing ran yet: somebody decides it, an approver or, for a run `pending_confirmation`, the
+ * caller in their Inbox. `location` is where the run is read again.
+ */
  | {
     status: "pending_approval";
     run: Run;
@@ -169,6 +188,8 @@ type OutputOf<Op extends Operation> = Op["response"] extends {
     kind: "sse";
     schema: infer Schema extends z.ZodType;
 } ? AsyncIterable<z.output<Schema>> : Op["response"] extends {
+    kind: "redirect";
+} ? Promise<undefined> : Op["response"] extends {
     schema: infer Schema extends z.ZodType;
 } ? Op extends {
     accepted: infer Accepted extends z.ZodType;

package/dist/index.js

@@ -209,6 +209,9 @@ function createApiTransport(options) {
       if (operation.headers?.request?.includes("Idempotency-Key")) {
         headers.set("idempotency-key", request.idempotencyKey ?? createIdempotencyKey());
       }
+      if (request.unattended && operation.headers?.request?.includes("Catalyst-Unattended")) {
+        headers.set("catalyst-unattended", "1");
+      }
       const token = await options.getToken?.();
       if (token) {
         headers.set("authorization", `Bearer ${token}`);
@@ -311,7 +314,13 @@ function hasEveryOperation(operations, tree) {
 function callOperation(transport, operation, request) {
   const { response } = operation;
   if (response.kind === "sse") {
-    return streamEvents(transport, operation, response.schema, request);
+    return streamEvents(transport, operation, response, request);
+  }
+  if (response.kind === "redirect") {
+    return transport.send(operation, request).then(async (answer) => {
+      await answer.body?.cancel();
+      return void 0;
+    });
   }
   if (response.kind === "blob") {
     return transport.send(operation, request).then((answer) => readBody(() => answer.blob(), request));
@@ -341,7 +350,7 @@ function callOperation(transport, operation, request) {
     };
   });
 }
-async function* streamEvents(transport, operation, schema, request) {
+async function* streamEvents(transport, operation, response, request) {
   const answer = await transport.send(operation, request);
   if (answer.status === 204) {
     request.onCaughtUp?.();
@@ -352,7 +361,12 @@ async function* streamEvents(transport, operation, schema, request) {
   }
   try {
     for await (const data of readServerSentEvents(answer.body)) {
-      yield parseJson(transport, data, schema, answer.status);
+      const event = readEvent(transport, data, response, answer.status);
+      if (event.skipped) {
+        request.onSkipped?.(event.value);
+        continue;
+      }
+      yield event.value;
     }
   } catch (error) {
     throw asCallFailure(error, request);
@@ -368,6 +382,22 @@ async function readBody(read, request) {
 function asCallFailure(error, request) {
   return error instanceof ApiError || request.signal?.aborted ? error : transportError(error);
 }
+function readEvent(transport, text, response, status) {
+  const { skip } = response;
+  if (skip) {
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch (error) {
+      throw unreadableResponseError(status, error);
+    }
+    const parsed = response.schema.safeParse(value);
+    if (parsed.success) return { skipped: false, value: parsed.data };
+    const skipped = skip.safeParse(value);
+    if (skipped.success) return { skipped: true, value: skipped.data };
+  }
+  return { skipped: false, value: parseJson(transport, text, response.schema, status) };
+}
 function parseJson(transport, text, schema, status) {
   let value;
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@work-shape/catalyst-api-client",
-  "version": "0.8.0-rc.2",
+  "version": "0.8.0-rc.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@work-shape/catalyst-api-contract": "0.8.0-rc.2"
+    "@work-shape/catalyst-api-contract": "0.8.0-rc.3"
   },
   "devDependencies": {
     "@types/node": "^24.13.1",