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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Workshape
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { ApiErrorCode, Operation, OperationPathParamName, OperationRequestHeader, apiOperations, ApiOperationName } from '@work-shape/catalyst-api-contract';
+export * from '@work-shape/catalyst-api-contract';
+
+/**
+ * The sign-in library's mount. It is not a product operation: the library owns its paths and
+ * payloads, and a session cookie is the only credential it accepts.
+ */
+declare const AUTH_MOUNT_PATH = "/api/auth";
+declare const authSessionSchema: z.ZodNullable<z.ZodObject<{
+    session: z.ZodObject<{
+        id: z.ZodString;
+        userId: z.ZodString;
+        expiresAt: z.ZodString;
+    }, z.core.$strip>;
+    user: z.ZodObject<{
+        id: z.ZodString;
+        email: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+type AuthSession = NonNullable<z.infer<typeof authSessionSchema>>;
+interface AuthResult {
+    ok: boolean;
+    message?: string;
+}
+declare function getAuthSession(apiBaseUrl: string): Promise<AuthSession | null>;
+declare function signInWithEmail(input: {
+    apiBaseUrl: string;
+    email: string;
+    password: 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.
+ */
+declare function signInForSessionFetch(input: {
+    apiBaseUrl: string;
+    origin: string;
+    email: string;
+    password: string;
+    fetchImpl?: typeof fetch;
+}): Promise<typeof fetch>;
+declare function signOut(apiBaseUrl: string): Promise<void>;
+
+/**
+ * Every way a call can fail once its input was accepted. `status` is the HTTP status, or 0 when
+ * no response arrived. `payload` is what the server sent with a refusal; when the request never
+ * got an answer or the answer could not be read, it is the underlying failure.
+ */
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly code?: ApiErrorCode;
+    readonly payload: unknown;
+    readonly correlationId?: string;
+    /** How long a caller over a rate limit has to wait, from a 429 `RATE_LIMITED` answer. */
+    readonly retryAfterSeconds?: number;
+    constructor(status: number, message: string, payload: unknown);
+}
+/** The request got no answer, or the answer broke off. */
+declare function transportError(cause: unknown): ApiError;
+/** The server refused the call. Its body is untrusted and need not be an error envelope. */
+declare function refusalError(response: Response): Promise<ApiError>;
+/** The server answered a success whose body cannot be read as JSON. */
+declare function unreadableResponseError(status: number, cause: unknown): ApiError;
+/**
+ * The server answered a success that the operation's schema refuses: usually a client of
+ * another release than the server, such as an enum value or an event type this client does not
+ * know. `paths` names where the answer differs and never what it held.
+ */
+declare class ApiResponseShapeError extends ApiError {
+    /** Dotted paths of the fields the schema refused, each once. */
+    readonly paths: readonly string[];
+    constructor(status: number, cause: z.ZodError);
+}
+
+interface ApiClientOptions {
+    baseUrl: string;
+    /**
+     * The bearer credential of every request. Without a token source the client relies on the
+     * browser's session cookie instead; with one, cookies are never sent.
+     */
+    getToken?: () => string | undefined | Promise<string | undefined>;
+    fetchImpl?: typeof fetch;
+    /** Only available without a token source; browser navigation cannot send a bearer token. */
+    browserManagedDownloads?: boolean;
+    /**
+     * Called when the server answers that a method and path is no operation of its catalog:
+     * this client was built for another release than the server now runs.
+     */
+    onUnknownOperation?: () => void;
+    /**
+     * Called when a successful answer does not match the schema of its operation, which reads
+     * the same way: the server speaks another release's contract than this client.
+     */
+    onResponseMismatch?: () => void;
+}
+
+type Catalog = typeof apiOperations;
+/** Operations by id, as `apiOperations` holds the release's. */
+type OperationCatalog = Record<string, Operation>;
+/** `{ key: Value }`, with the key optional when an empty value would do. */
+type Part<Key extends string, Value> = Record<never, never> extends Value ? Partial<Record<Key, Value>> : Record<Key, Value>;
+type ParamsPart<Path extends string> = [OperationPathParamName<Path>] extends [never] ? unknown : {
+    params: Record<OperationPathParamName<Path>, string>;
+};
+/** The keys a query schema accepts, with the types its values have once they are parsed. */
+type QueryValues<Schema extends z.ZodType> = {
+    [Key in keyof z.input<Schema>]: Key extends keyof z.output<Schema> ? z.output<Schema>[Key] : never;
+};
+type QueryPart<Op> = Op extends {
+    query: infer Schema extends z.ZodType;
+} ? Part<"query", QueryValues<Schema>> : unknown;
+type BodyPart<Op> = Op extends {
+    multipart: true;
+} ? {
+    file: File;
+} : Op extends {
+    body: infer Schema extends z.ZodType;
+} ? {
+    body: z.input<Schema>;
+} : unknown;
+type ControlPart<Op extends Operation> = {
+    signal?: AbortSignal;
+} & (Op["response"] extends {
+    kind: "sse";
+} ? {
+    /** Called when the server has nothing after the given position and sends no stream. */
+    onCaughtUp?: () => void;
+} : 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.
+ */
+type IdempotencyPart<Op> = Op extends {
+    headers: {
+        request: readonly (infer Header extends OperationRequestHeader)[];
+    };
+} ? "Idempotency-Key" extends Header ? {
+    idempotencyKey?: string;
+} : unknown : unknown;
+type InputOf<Op extends Operation> = ParamsPart<Op["path"]> & QueryPart<Op> & BodyPart<Op> & IdempotencyPart<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.
+ */
+type OperationOutcome<Output, Run = unknown> = {
+    /** The Operation Run that records the call. */
+    operationRunId: string | undefined;
+    /** The answer is the recorded one of an earlier call with the same `Idempotency-Key`. */
+    replayed: boolean;
+} & ({
+    status: "done";
+    output: Output;
+}
+/** Nothing ran yet: somebody else decides. `location` is where the run is read again. */
+ | {
+    status: "pending_approval";
+    run: Run;
+    location: string | undefined;
+});
+/**
+ * The output of a call that ran. A call that waits for somebody else's approval changed
+ * nothing yet, so it throws with `heldMessage`: for a caller that has no way to show a call
+ * that waits.
+ */
+declare function completedOutput<Output>(outcome: OperationOutcome<Output>, heldMessage?: string): Output;
+type OutputOf<Op extends Operation> = Op["response"] extends {
+    kind: "sse";
+    schema: infer Schema extends z.ZodType;
+} ? AsyncIterable<z.output<Schema>> : Op["response"] extends {
+    schema: infer Schema extends z.ZodType;
+} ? Op extends {
+    accepted: infer Accepted extends z.ZodType;
+} ? Promise<OperationOutcome<z.output<Schema>, z.output<Accepted>>> : Op extends {
+    deferred: true;
+} ? Promise<z.output<Schema> | undefined> : Promise<z.output<Schema>> : Promise<Blob>;
+/** What the method of a catalog operation takes: `params`, `query`, `body` or `file`, `signal`. */
+type OperationInput<Name extends ApiOperationName> = InputOf<Catalog[Name]>;
+type UrlInput<Op extends Operation> = Pick<InputOf<Op>, Extract<keyof InputOf<Op>, "params" | "query">>;
+type OperationMethod<Op extends Operation> = Record<never, never> extends InputOf<Op> ? (input?: InputOf<Op>) => OutputOf<Op> : (input: InputOf<Op>) => OutputOf<Op>;
+type FirstSegment<Id extends string> = Id extends `${infer First}.${string}` ? First : Id;
+type AfterSegment<Id extends string, First extends string> = Id extends `${First}.${infer Rest}` ? Rest : never;
+/** One method per operation, nested by the segments of its id: `conversations.runs.start`. */
+type MethodTree<Operations extends OperationCatalog, Ids extends string, Prefix extends string = ""> = {
+    [Segment in FirstSegment<Ids>]: `${Prefix}${Segment}` extends keyof Operations ? OperationMethod<Operations[`${Prefix}${Segment}`]> : MethodTree<Operations, AfterSegment<Ids, Segment>, `${Prefix}${Segment}.`>;
+};
+type OperationMethods<Operations extends OperationCatalog> = MethodTree<Operations, keyof Operations & string>;
+type ApiOperationMethods = OperationMethods<Catalog>;
+/** The client of the given operations: one method each, and what every client has. */
+type ApiClientFor<Operations extends OperationCatalog> = OperationMethods<Operations> & {
+    /** Whether the browser itself may fetch a file by URL, which only a session cookie allows. */
+    browserManagedDownloads: boolean;
+    /** The absolute URL of an operation, for a link or an element that loads it itself. */
+    urlFor<Name extends keyof Operations & string>(name: Name, input: UrlInput<Operations[Name]>): string;
+};
+type ApiClient = ApiClientFor<Catalog>;
+/**
+ * The first-party client. Its methods are not written down anywhere: each operation of the
+ * catalog becomes one method, and every method goes through the same call.
+ */
+declare function createApiClient(options: ApiClientOptions): ApiClient;
+/**
+ * The same client for operations that are not the release's own catalog, such as the
+ * operations a capability registers on its instance.
+ */
+declare function createApiClientFor<const Operations extends OperationCatalog>(operations: Operations, options: ApiClientOptions): ApiClientFor<Operations>;
+/**
+ * Reads a list operation to its end, one largest page after the other:
+ * `listAll((paging) => client.users.list({ query: paging }))`. One call of a list method answers
+ * a single page, and a screen that shows a whole list must not stop at the first.
+ */
+declare function listAll<Item>(readPage: (paging: {
+    limit: number;
+    cursor?: string;
+}) => Promise<{
+    items: Item[];
+    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 };

package/dist/index.js

@@ -0,0 +1,403 @@
+// src/auth.ts
+import { z } from "zod";
+var AUTH_MOUNT_PATH = "/api/auth";
+var authSessionSchema = z.object({
+  session: z.object({ id: z.string(), userId: z.string(), expiresAt: z.string() }),
+  user: z.object({ id: z.string(), email: z.string(), name: z.string() })
+}).nullable();
+var authFailureSchema = z.object({
+  message: z.string().optional(),
+  error: z.object({ message: z.string().optional() }).optional()
+});
+async function getAuthSession(apiBaseUrl) {
+  const response = await fetch(authUrl(apiBaseUrl, "/get-session"), {
+    credentials: "include"
+  });
+  if (!response.ok) {
+    return null;
+  }
+  return authSessionSchema.parse(await response.json());
+}
+async function signInWithEmail(input) {
+  const response = await fetch(authUrl(input.apiBaseUrl, "/sign-in/email"), {
+    method: "POST",
+    credentials: "include",
+    headers: {
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({
+      email: input.email,
+      password: input.password,
+      rememberMe: true
+    })
+  });
+  if (response.ok) {
+    return { ok: true };
+  }
+  const failure = authFailureSchema.safeParse(await response.json().catch(() => void 0));
+  return {
+    ok: false,
+    message: failure.data?.message ?? failure.data?.error?.message ?? "Sign in failed"
+  };
+}
+async function signInForSessionFetch(input) {
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const response = await fetchImpl(authUrl(input.apiBaseUrl, "/sign-in/email"), {
+    method: "POST",
+    headers: { "content-type": "application/json", origin: input.origin },
+    body: JSON.stringify({ email: input.email, password: input.password })
+  });
+  if (!response.ok) {
+    throw new Error(`Sign-in as '${input.email}' was refused with status ${response.status}`);
+  }
+  const cookie = response.headers.getSetCookie().map((value) => value.split(";", 1)[0]).join("; ");
+  return (resource, init) => {
+    const request = new Request(resource, init);
+    request.headers.set("cookie", cookie);
+    request.headers.set("origin", input.origin);
+    return fetchImpl(request);
+  };
+}
+async function signOut(apiBaseUrl) {
+  await fetch(authUrl(apiBaseUrl, "/sign-out"), {
+    method: "POST",
+    credentials: "include"
+  });
+}
+function authUrl(apiBaseUrl, path) {
+  return `${apiBaseUrl.replace(/\/$/u, "")}${AUTH_MOUNT_PATH}${path}`;
+}
+
+// src/errors.ts
+import {
+  appErrorCodeSchema,
+  rateLimitedDetailsSchema
+} from "@work-shape/catalyst-api-contract";
+import { z as z2 } from "zod";
+var ApiError = class extends Error {
+  status;
+  code;
+  payload;
+  correlationId;
+  /** How long a caller over a rate limit has to wait, from a 429 `RATE_LIMITED` answer. */
+  retryAfterSeconds;
+  constructor(status, message, payload) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = readApiErrorCode(payload);
+    this.payload = payload;
+    this.correlationId = readCorrelationId(payload);
+    this.retryAfterSeconds = readRetryAfterSeconds(payload);
+  }
+};
+var REQUEST_FAILED = "API request failed";
+function transportError(cause) {
+  return new ApiError(0, REQUEST_FAILED, cause);
+}
+async function refusalError(response) {
+  const text = await response.text().catch(() => "");
+  const payload = parseJsonOrText(text);
+  return new ApiError(response.status, readErrorMessage(payload) ?? REQUEST_FAILED, payload);
+}
+function unreadableResponseError(status, cause) {
+  return new ApiError(status, "API response is not valid JSON", cause);
+}
+var ApiResponseShapeError = class extends ApiError {
+  /** Dotted paths of the fields the schema refused, each once. */
+  paths;
+  constructor(status, cause) {
+    super(status, "API response does not match the contract", cause);
+    this.name = "ApiResponseShapeError";
+    this.paths = [...new Set(cause.issues.map((issue) => issue.path.join(".") || "(root)"))];
+  }
+};
+function parseJsonOrText(text) {
+  try {
+    const parsed = JSON.parse(text);
+    return parsed;
+  } catch {
+    return text;
+  }
+}
+function readErrorEnvelope(payload) {
+  if (!payload || typeof payload !== "object" || !("error" in payload)) return void 0;
+  const error = payload.error;
+  return error && typeof error === "object" ? error : void 0;
+}
+function readErrorMessage(payload) {
+  const error = readErrorEnvelope(payload);
+  return error && "message" in error && typeof error.message === "string" ? error.message : void 0;
+}
+function readApiErrorCode(payload) {
+  const error = readErrorEnvelope(payload);
+  if (!error || !("code" in error)) return void 0;
+  const parsed = appErrorCodeSchema.safeParse(error.code);
+  return parsed.success ? parsed.data : void 0;
+}
+function readCorrelationId(payload) {
+  const error = readErrorEnvelope(payload);
+  return error && "correlationId" in error && typeof error.correlationId === "string" ? error.correlationId : void 0;
+}
+function readRetryAfterSeconds(payload) {
+  const parsed = z2.object({ error: z2.object({ details: rateLimitedDetailsSchema }) }).safeParse(payload);
+  return parsed.success ? parsed.data.error.details.retryAfterSeconds : void 0;
+}
+
+// src/client.ts
+import {
+  apiOperations
+} from "@work-shape/catalyst-api-contract";
+
+// src/server-sent-events.ts
+async function* readServerSentEvents(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let finished = false;
+  try {
+    while (!finished) {
+      const { done, value } = await reader.read();
+      finished = done;
+      buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+      const blocks = buffer.replaceAll("\r\n", "\n").split("\n\n");
+      buffer = done ? "" : blocks.pop() ?? "";
+      for (const block of blocks) {
+        const data = readEventData(block);
+        if (data !== void 0) {
+          yield data;
+        }
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+    reader.releaseLock();
+  }
+}
+function readEventData(block) {
+  const data = block.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice("data:".length).replace(/^ /u, "")).join("\n");
+  return data === "" ? void 0 : data;
+}
+
+// src/transport.ts
+import { isUnknownOperationResponse } from "@work-shape/catalyst-api-contract";
+function createApiTransport(options) {
+  const baseUrl = options.baseUrl.replace(/\/$/u, "");
+  const cookieMode = options.getToken === void 0;
+  const urlFor = (operation, request) => `${baseUrl}${operation.buildPath({ params: request.params, query: request.query })}`;
+  return {
+    browserManagedDownloads: cookieMode && (options.browserManagedDownloads ?? true),
+    urlFor,
+    reportResponseMismatch: () => options.onResponseMismatch?.(),
+    async send(operation, request) {
+      const url = urlFor(operation, request);
+      const headers = new Headers();
+      if (operation.response.kind === "sse") {
+        headers.set("accept", "text/event-stream");
+      }
+      let body;
+      if (operation.multipart) {
+        if (!request.file) {
+          throw new Error(`Operation "${operation.id}" needs a file`);
+        }
+        body = new FormData();
+        body.append("file", request.file);
+      } else if (operation.body) {
+        headers.set("content-type", "application/json");
+        body = JSON.stringify(operation.body.parse(request.body));
+      }
+      if (operation.headers?.request?.includes("Idempotency-Key")) {
+        headers.set("idempotency-key", request.idempotencyKey ?? createIdempotencyKey());
+      }
+      const token = await options.getToken?.();
+      if (token) {
+        headers.set("authorization", `Bearer ${token}`);
+      }
+      let response;
+      try {
+        response = await (options.fetchImpl ?? fetch)(url, {
+          method: operation.method,
+          headers,
+          body,
+          credentials: cookieMode ? "include" : "omit",
+          signal: request.signal
+        });
+      } catch (error) {
+        throw request.signal?.aborted ? error : transportError(error);
+      }
+      if (response.ok) {
+        return response;
+      }
+      const refusal = await refusalError(response);
+      if (response.status === 404 && isUnknownOperationResponse(refusal.payload)) {
+        options.onUnknownOperation?.();
+      }
+      throw refusal;
+    }
+  };
+}
+function createIdempotencyKey() {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+// src/client.ts
+function completedOutput(outcome, heldMessage = "The call waits for an approval and has changed nothing yet") {
+  if (outcome.status === "done") return outcome.output;
+  throw new Error(heldMessage);
+}
+function createApiClient(options) {
+  return createApiClientFor(apiOperations, options);
+}
+function createApiClientFor(operations, options) {
+  const transport = createApiTransport(options);
+  const methods = buildMethodTree(
+    operations,
+    (operation, request) => callOperation(transport, operation, request)
+  );
+  if (!hasEveryOperation(operations, methods)) {
+    throw new Error("The client's methods do not cover the operation catalog");
+  }
+  return Object.assign(methods, {
+    browserManagedDownloads: transport.browserManagedDownloads,
+    urlFor: (name, input) => transport.urlFor(operationOf(operations, name), input)
+  });
+}
+function operationOf(operations, name) {
+  const operation = operations[name];
+  if (!operation) throw new Error(`Unknown operation "${name}"`);
+  return operation;
+}
+var LARGEST_PAGE = 200;
+async function listAll(readPage) {
+  const items = [];
+  let cursor;
+  do {
+    const page = await readPage({ limit: LARGEST_PAGE, ...cursor ? { cursor } : {} });
+    items.push(...page.items);
+    cursor = page.nextCursor;
+  } while (cursor);
+  return items;
+}
+function buildMethodTree(operations, call) {
+  const root = {};
+  for (const operation of Object.values(operations)) {
+    const segments = operation.id.split(".");
+    const name = segments.pop() ?? "";
+    let node = root;
+    for (const segment of segments) {
+      const next = node[segment] ??= {};
+      if (typeof next === "function") {
+        throw new Error(`Operation id "${operation.id}" continues the id of another operation`);
+      }
+      node = next;
+    }
+    if (node[name]) {
+      throw new Error(`Operation id "${operation.id}" is the start of another operation's id`);
+    }
+    node[name] = (request = {}) => call(operation, request);
+  }
+  return root;
+}
+function hasEveryOperation(operations, tree) {
+  return Object.keys(operations).every((id) => {
+    let node = tree;
+    for (const segment of id.split(".")) {
+      node = typeof node === "object" ? node[segment] : void 0;
+    }
+    return typeof node === "function";
+  });
+}
+function callOperation(transport, operation, request) {
+  const { response } = operation;
+  if (response.kind === "sse") {
+    return streamEvents(transport, operation, response.schema, request);
+  }
+  if (response.kind === "blob") {
+    return transport.send(operation, request).then((answer) => readBody(() => answer.blob(), request));
+  }
+  const { accepted } = operation;
+  return transport.send(operation, request).then(async (answer) => {
+    if (operation.deferred && answer.status === 202) {
+      return void 0;
+    }
+    const text = await readBody(() => answer.text(), request);
+    if (!accepted) {
+      return parseJson(transport, text, response.schema, answer.status);
+    }
+    const outcome = {
+      operationRunId: answer.headers.get("operation-run-id") ?? void 0,
+      replayed: answer.headers.get("idempotent-replayed") === "true"
+    };
+    return answer.status === 202 ? {
+      ...outcome,
+      status: "pending_approval",
+      run: parseJson(transport, text, accepted, answer.status),
+      location: answer.headers.get("location") ?? void 0
+    } : {
+      ...outcome,
+      status: "done",
+      output: parseJson(transport, text, response.schema, answer.status)
+    };
+  });
+}
+async function* streamEvents(transport, operation, schema, request) {
+  const answer = await transport.send(operation, request);
+  if (answer.status === 204) {
+    request.onCaughtUp?.();
+    return;
+  }
+  if (!answer.body) {
+    return;
+  }
+  try {
+    for await (const data of readServerSentEvents(answer.body)) {
+      yield parseJson(transport, data, schema, answer.status);
+    }
+  } catch (error) {
+    throw asCallFailure(error, request);
+  }
+}
+async function readBody(read, request) {
+  try {
+    return await read();
+  } catch (error) {
+    throw asCallFailure(error, request);
+  }
+}
+function asCallFailure(error, request) {
+  return error instanceof ApiError || request.signal?.aborted ? error : transportError(error);
+}
+function parseJson(transport, text, schema, status) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw unreadableResponseError(status, error);
+  }
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    transport.reportResponseMismatch();
+    throw new ApiResponseShapeError(status, parsed.error);
+  }
+  return parsed.data;
+}
+
+// src/index.ts
+export * from "@work-shape/catalyst-api-contract";
+export {
+  AUTH_MOUNT_PATH,
+  ApiError,
+  ApiResponseShapeError,
+  completedOutput,
+  createApiClient,
+  createApiClientFor,
+  getAuthSession,
+  listAll,
+  refusalError,
+  signInForSessionFetch,
+  signInWithEmail,
+  signOut,
+  transportError,
+  unreadableResponseError
+};

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@work-shape/catalyst-api-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.8.0-rc.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/work-shape/catalyst",
+    "directory": "packages/api-client"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@work-shape/catalyst-api-contract": "0.8.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.