@work-shape/catalyst-api-client 0.8.0-rc.1 → 0.8.0-rc.10

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ApiErrorCode, Operation, OperationPathParamName, OperationRequestHeader, apiOperations, ApiOperationName } from '@work-shape/catalyst-api-contract';
+import { ApiErrorCode, LocaleCode, Operation, OperationPathParamName, OperationRequestHeader, apiOperations, ApiOperationName } from '@work-shape/catalyst-api-contract';
 export * from '@work-shape/catalyst-api-contract';
 
 /**
@@ -22,6 +22,8 @@ declare const authSessionSchema: z.ZodNullable<z.ZodObject<{
 type AuthSession = NonNullable<z.infer<typeof authSessionSchema>>;
 interface AuthResult {
     ok: boolean;
+    /** The sign-in library's code for a refusal, such as `INVALID_EMAIL_OR_PASSWORD`. */
+    code?: string;
     message?: string;
 }
 declare function getAuthSession(apiBaseUrl: string): Promise<AuthSession | null>;
@@ -82,6 +84,13 @@ interface ApiClientOptions {
      */
     getToken?: () => string | undefined | Promise<string | undefined>;
     fetchImpl?: typeof fetch;
+    /** Cancels this client's requests when its owning session ends. */
+    signal?: AbortSignal;
+    /**
+     * The language every request asks the server to answer in, read at each request. A browser's
+     * own Accept-Language names its settings, not the language a person chose in the interface.
+     */
+    locale?: LocaleCode;
     /** Only available without a token source; browser navigation cannot send a bearer token. */
     browserManagedDownloads?: boolean;
     /**
@@ -127,7 +136,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 +153,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 +178,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 +197,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

@@ -6,6 +6,7 @@ var authSessionSchema = z.object({
   user: z.object({ id: z.string(), email: z.string(), name: z.string() })
 }).nullable();
 var authFailureSchema = z.object({
+  code: z.string().optional(),
   message: z.string().optional(),
   error: z.object({ message: z.string().optional() }).optional()
 });
@@ -37,6 +38,7 @@ async function signInWithEmail(input) {
   const failure = authFailureSchema.safeParse(await response.json().catch(() => void 0));
   return {
     ok: false,
+    ...failure.data?.code === void 0 ? {} : { code: failure.data.code },
     message: failure.data?.message ?? failure.data?.error?.message ?? "Sign in failed"
   };
 }
@@ -180,7 +182,9 @@ function readEventData(block) {
 }
 
 // src/transport.ts
-import { isUnknownOperationResponse } from "@work-shape/catalyst-api-contract";
+import {
+  isUnknownOperationResponse
+} from "@work-shape/catalyst-api-contract";
 function createApiTransport(options) {
   const baseUrl = options.baseUrl.replace(/\/$/u, "");
   const cookieMode = options.getToken === void 0;
@@ -209,10 +213,20 @@ 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?.();
+      const sessionSignal = options.signal;
+      const signal = sessionSignal && request.signal ? AbortSignal.any([sessionSignal, request.signal]) : sessionSignal ?? request.signal;
       if (token) {
         headers.set("authorization", `Bearer ${token}`);
       }
+      const locale = options.locale;
+      if (locale !== void 0) {
+        headers.set("accept-language", locale);
+      }
+      signal?.throwIfAborted();
       let response;
       try {
         response = await (options.fetchImpl ?? fetch)(url, {
@@ -220,10 +234,10 @@ function createApiTransport(options) {
           headers,
           body,
           credentials: cookieMode ? "include" : "omit",
-          signal: request.signal
+          signal
         });
       } catch (error) {
-        throw request.signal?.aborted ? error : transportError(error);
+        throw signal?.aborted ? error : transportError(error);
       }
       if (response.ok) {
         return response;
@@ -311,7 +325,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 +361,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 +372,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 +393,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.1",
+  "version": "0.8.0-rc.10",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@work-shape/catalyst-api-contract": "0.8.0-rc.1"
+    "@work-shape/catalyst-api-contract": "0.8.0-rc.10"
   },
   "devDependencies": {
     "@types/node": "^24.13.1",