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

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,14 +22,64 @@ 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;
+    /** The HTTP status of a refusal; 429 is the instance's limit on attempts. */
+    status?: number;
+}
+/** The second factor of a sign-in: a code from the authenticator app, or a backup code. */
+type SecondFactorKind = "app" | "backup";
+/** A sign-in: refused, signed in, or waiting for the second factor (TWO-FACTOR-1). */
+interface SignInResult extends AuthResult {
+    /** The password was right and the account asks for a code before there is a session. */
+    secondFactor?: true;
+}
+/** What an authenticator app reads, and the ten backup codes, shown once. */
+interface TwoFactorSetup {
+    totpUri: string;
+    backupCodes: string[];
 }
 declare function getAuthSession(apiBaseUrl: string): Promise<AuthSession | null>;
 declare function signInWithEmail(input: {
     apiBaseUrl: string;
     email: string;
     password: string;
+}): Promise<SignInResult>;
+/**
+ * The second sign-in step: a code from the authenticator app, or a backup code, which signs in
+ * once. `trustBrowser` skips the code in this browser for 30 days from now.
+ */
+declare function verifySecondFactor(input: {
+    apiBaseUrl: string;
+    code: string;
+    kind: SecondFactorKind;
+    trustBrowser?: boolean;
+}): Promise<AuthResult>;
+/**
+ * Starts the setup of two-factor sign-in with the password. The factor is on only after the
+ * first code from the app is confirmed with `verifySecondFactor`.
+ */
+declare function startTwoFactorSetup(input: {
+    apiBaseUrl: string;
+    password: string;
+}): Promise<AuthResult & {
+    setup?: TwoFactorSetup;
+}>;
+/** Turns two-factor sign-in off with the password; every trusted browser is forgotten. */
+declare function turnOffTwoFactor(input: {
+    apiBaseUrl: string;
+    password: string;
 }): Promise<AuthResult>;
+/** Replaces all ten backup codes with the password. The new ones are shown once. */
+declare function regenerateBackupCodes(input: {
+    apiBaseUrl: string;
+    password: string;
+}): Promise<AuthResult & {
+    backupCodes?: string[];
+}>;
+/** Every browser of the person asks for the code again at its next sign-in. */
+declare function forgetTrustedBrowsers(apiBaseUrl: string): Promise<AuthResult>;
 /**
  * For a tool outside a browser, which keeps no cookies: signs in and returns a fetch that
  * carries the session cookie and the origin the instance trusts on every request.
@@ -82,6 +132,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 +184,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 +201,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 +226,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 +245,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;
@@ -218,4 +296,4 @@ declare function listAll<Item>(readPage: (paging: {
     nextCursor?: string;
 }>): Promise<Item[]>;
 
-export { AUTH_MOUNT_PATH, type ApiClient, type ApiClientFor, type ApiClientOptions, ApiError, type ApiOperationMethods, ApiResponseShapeError, type AuthResult, type AuthSession, type OperationInput, type OperationOutcome, completedOutput, createApiClient, createApiClientFor, getAuthSession, listAll, refusalError, signInForSessionFetch, signInWithEmail, signOut, transportError, unreadableResponseError };
+export { AUTH_MOUNT_PATH, type ApiClient, type ApiClientFor, type ApiClientOptions, ApiError, type ApiOperationMethods, ApiResponseShapeError, type AuthResult, type AuthSession, type OperationInput, type OperationOutcome, type SecondFactorKind, type SignInResult, type TwoFactorSetup, completedOutput, createApiClient, createApiClientFor, forgetTrustedBrowsers, getAuthSession, listAll, refusalError, regenerateBackupCodes, signInForSessionFetch, signInWithEmail, signOut, startTwoFactorSetup, transportError, turnOffTwoFactor, unreadableResponseError, verifySecondFactor };

package/dist/index.js

@@ -6,9 +6,15 @@ 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()
 });
+var signInAnswerSchema = z.object({ twoFactorRedirect: z.boolean().optional() });
+var twoFactorSetupSchema = z.object({
+  totpURI: z.string(),
+  backupCodes: z.array(z.string())
+});
 async function getAuthSession(apiBaseUrl) {
   const response = await fetch(authUrl(apiBaseUrl, "/get-session"), {
     credentials: "include"
@@ -32,12 +38,64 @@ async function signInWithEmail(input) {
     })
   });
   if (response.ok) {
-    return { ok: true };
+    const answer = signInAnswerSchema.safeParse(await response.json().catch(() => void 0));
+    return answer.data?.twoFactorRedirect === true ? { ok: true, secondFactor: true } : { ok: true };
+  }
+  return failureOf(response, "Sign in failed");
+}
+async function verifySecondFactor(input) {
+  const path = input.kind === "app" ? "/two-factor/verify-totp" : "/two-factor/verify-backup-code";
+  const response = await postAuth(input.apiBaseUrl, path, {
+    code: input.code.replaceAll(/\s/gu, ""),
+    trustDevice: input.trustBrowser === true
+  });
+  return response.ok ? { ok: true } : failureOf(response, "The code was not accepted");
+}
+async function startTwoFactorSetup(input) {
+  const response = await postAuth(input.apiBaseUrl, "/two-factor/enable", {
+    password: input.password
+  });
+  if (!response.ok) {
+    return failureOf(response, "Two-factor sign-in could not be set up");
+  }
+  const setup = twoFactorSetupSchema.parse(await response.json());
+  return { ok: true, setup: { totpUri: setup.totpURI, backupCodes: setup.backupCodes } };
+}
+async function turnOffTwoFactor(input) {
+  const response = await postAuth(input.apiBaseUrl, "/two-factor/disable", {
+    password: input.password
+  });
+  return response.ok ? { ok: true } : failureOf(response, "Two-factor sign-in stayed on");
+}
+async function regenerateBackupCodes(input) {
+  const response = await postAuth(input.apiBaseUrl, "/two-factor/generate-backup-codes", {
+    password: input.password
+  });
+  if (!response.ok) {
+    return failureOf(response, "No new backup codes were made");
   }
+  const { backupCodes } = twoFactorSetupSchema.pick({ backupCodes: true }).parse(await response.json());
+  return { ok: true, backupCodes };
+}
+async function forgetTrustedBrowsers(apiBaseUrl) {
+  const response = await postAuth(apiBaseUrl, "/two-factor/forget-trusted-browsers", {});
+  return response.ok ? { ok: true } : failureOf(response, "The browsers are still trusted");
+}
+function postAuth(apiBaseUrl, path, body) {
+  return fetch(authUrl(apiBaseUrl, path), {
+    method: "POST",
+    credentials: "include",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+}
+async function failureOf(response, fallback) {
   const failure = authFailureSchema.safeParse(await response.json().catch(() => void 0));
   return {
     ok: false,
-    message: failure.data?.message ?? failure.data?.error?.message ?? "Sign in failed"
+    status: response.status,
+    ...failure.data?.code === void 0 ? {} : { code: failure.data.code },
+    message: failure.data?.message ?? failure.data?.error?.message ?? fallback
   };
 }
 async function signInForSessionFetch(input) {
@@ -50,6 +108,12 @@ async function signInForSessionFetch(input) {
   if (!response.ok) {
     throw new Error(`Sign-in as '${input.email}' was refused with status ${response.status}`);
   }
+  const answer = signInAnswerSchema.safeParse(
+    await response.clone().json().catch(() => void 0)
+  );
+  if (answer.data?.twoFactorRedirect === true) {
+    throw new Error(`'${input.email}' signs in with a second factor; use an API key for this tool`);
+  }
   const cookie = response.headers.getSetCookie().map((value) => value.split(";", 1)[0]).join("; ");
   return (resource, init) => {
     const request = new Request(resource, init);
@@ -180,7 +244,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 +275,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 +296,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 +387,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 +423,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 +434,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 +455,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 {
@@ -392,12 +495,17 @@ export {
   completedOutput,
   createApiClient,
   createApiClientFor,
+  forgetTrustedBrowsers,
   getAuthSession,
   listAll,
   refusalError,
+  regenerateBackupCodes,
   signInForSessionFetch,
   signInWithEmail,
   signOut,
+  startTwoFactorSetup,
   transportError,
-  unreadableResponseError
+  turnOffTwoFactor,
+  unreadableResponseError,
+  verifySecondFactor
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@work-shape/catalyst-api-client",
-  "version": "0.8.0-rc.1",
+  "version": "0.8.0-rc.11",
   "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.11"
   },
   "devDependencies": {
     "@types/node": "^24.13.1",