@synnaxlabs/client 0.56.2 → 0.57.0

package/src/status/status.ts

@@ -0,0 +1,241 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import {
+  errors,
+  id,
+  narrow,
+  type optional,
+  primitive,
+  record,
+  TimeStamp,
+} from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type Status, type Variant } from "@/status/types.gen";
+
+// Input type for creating statuses - uses conditional typing for optional details
+type Base<V extends Variant> = {
+  key: string;
+  name: string;
+  variant: V;
+  message: string;
+  description?: string;
+  time: TimeStamp;
+};
+
+/** A status before it is stamped with a key, a time, and a name. */
+export type Crude<
+  DetailsSchema extends z.ZodType = z.ZodNever,
+  V extends Variant = Variant,
+> = optional.Optional<Base<V>, "key" | "time" | "name"> &
+  ([DetailsSchema] extends [z.ZodNever] ? {} : { details: z.output<DetailsSchema> });
+
+/**
+ * Interface that errors may optionally implement to provide richer rendering when
+ * passed to {@link fromException}. Implementers return a partial {@link Crude} spec
+ * whose fields override the defaults derived from the underlying `Error`. This is a
+ * duck-typed contract: `fromException` checks for the presence of a `toStatus` method
+ * via the `in` operator, so there is no need to import this interface to use it.
+ */
+export interface Custom {
+  toStatus(): Partial<Crude<z.ZodRecord, "error">>;
+}
+
+const customReturnZ = z.object({
+  message: z.string().optional(),
+  description: z.string().optional(),
+  details: record.unknownZ().optional(),
+});
+
+const safeToStatus = (exc: unknown): z.infer<typeof customReturnZ> | undefined => {
+  if (
+    exc == null ||
+    typeof exc !== "object" ||
+    !("toStatus" in exc) ||
+    typeof exc.toStatus !== "function"
+  )
+    return undefined;
+  let raw: unknown;
+  try {
+    raw = exc.toStatus();
+  } catch {
+    return undefined;
+  }
+  const parsed = customReturnZ.safeParse(raw);
+  return parsed.success ? parsed.data : undefined;
+};
+
+/** Details a status built by {@link fromException} carries. */
+export const exceptionDetailsSchema = z
+  .object({
+    stack: z.string(),
+    error: z.instanceof(Error),
+  })
+  .and(record.unknownZ());
+
+/** Flattens an error's cause chain into one readable line. */
+const causeChain = (err: Error): string | undefined => {
+  const parts: string[] = [];
+  let cause: unknown = err.cause;
+  for (let i = 0; i < 8 && cause instanceof Error; i++) {
+    if (cause.message.length > 0) parts.push(cause.message);
+    cause = cause.cause;
+  }
+  if (parts.length === 0) return undefined;
+  return parts.join(": ");
+};
+
+/**
+ * Turns any thrown value into an error status, flattening its cause chain into the
+ * description and keeping the error and its stack in the details.
+ */
+export const fromException = (
+  exc: unknown,
+  message?: string,
+): Status<typeof exceptionDetailsSchema, z.ZodLiteral<"error">> => {
+  const err = errors.fromUnknown(exc);
+  const detail = causeChain(err);
+  const crude: Crude<typeof exceptionDetailsSchema, "error"> = {
+    variant: "error",
+    message: message ?? err.message,
+    description:
+      message != null
+        ? [err.message, detail].filter((part) => part != null).join(": ")
+        : detail,
+    details: { stack: err.stack ?? "", error: err },
+  };
+  // Probe the original (pre-coercion) value so a non-Error throwable with a custom
+  // `toStatus()` method still contributes its status fields.
+  const custom = safeToStatus(exc);
+  if (custom != null) {
+    if (message != null && custom.message != null)
+      crude.message = `${message}: ${custom.message}`;
+    else if (custom.message != null) crude.message = custom.message;
+    if (custom.description != null) crude.description = custom.description;
+    if (custom.details != null && crude.details != null)
+      crude.details = { ...crude.details, ...custom.details };
+  }
+  return create<typeof exceptionDetailsSchema, "error">(crude);
+};
+
+/**
+ * Converts an exception-shaped status (one built via {@link fromException}) back into a
+ * thrown-shaped {@link Error}. The returned error carries the status's wrapped message,
+ * copies `name` and `stack` from the inner error preserved on `details.error`, and
+ * stashes the full status on `cause` for callers that need the rich shape. Use this
+ * when bridging the status pipeline back into a context that expects a real Error —
+ * typically before `throw`-ing across an error boundary.
+ */
+export const toError = (
+  s: Status<typeof exceptionDetailsSchema, z.ZodLiteral<"error">>,
+): Error => {
+  const inner = s.details.error;
+  const err = new Error(s.message, { cause: s });
+  err.name = inner.name;
+  err.stack = inner.stack;
+  return err;
+};
+
+/** Stamps a {@link Crude} status with a fresh key and the current time. */
+export const create = <
+  DetailsSchema extends z.ZodType = z.ZodNever,
+  V extends Variant = Variant,
+>(
+  spec: Crude<DetailsSchema, V>,
+): Status<DetailsSchema, z.ZodType<V>> =>
+  ({
+    key: id.create(),
+    time: TimeStamp.now(),
+    name: "",
+    ...spec,
+    description: spec.description ?? "",
+  }) as Status<DetailsSchema, z.ZodType<V>>;
+
+/**
+ * Reads the details of a status whose schema is not statically known, as when
+ * scanning the generically-typed status table for rows belonging to a domain.
+ * @returns The details, or undefined when the status carries none.
+ */
+export const detailsOf = (status: Status): record.Unknown | undefined =>
+  (status as { details?: record.Unknown }).details;
+
+/** @returns the variant when it is one of the kept ones, else undefined. */
+export const keepVariants = (
+  variant?: Variant,
+  keep: Variant | Variant[] = [],
+): Variant | undefined => {
+  if (variant == null) return undefined;
+  if (Array.isArray(keep)) {
+    if (keep.includes(variant)) return variant;
+    return undefined;
+  }
+  return keep === variant ? variant : undefined;
+};
+
+/** @returns the variant unless it is one of the removed ones. */
+export const removeVariants = (
+  variant?: Variant,
+  remove: Variant | Variant[] = [],
+): Variant | undefined => {
+  if (variant == null) return undefined;
+  if (Array.isArray(remove)) {
+    if (remove.includes(variant)) return undefined;
+    return variant;
+  }
+  return remove === variant ? undefined : variant;
+};
+
+/** Options for {@link toString}. */
+export interface ToStringOptions {
+  includeTimestamp?: boolean;
+  includeName?: boolean;
+}
+
+const DEFAULT_TO_STRING_OPTIONS: ToStringOptions = {
+  includeTimestamp: false,
+  includeName: true,
+};
+
+const renderDescription = (description: string): string => {
+  if (description.includes("\n")) return `Description:\n${description}`;
+  try {
+    const parsed = JSON.parse(description);
+    return `Description:\n${JSON.stringify(parsed, null, 2)}`;
+  } catch {
+    return `Description: ${description}`;
+  }
+};
+
+/** Renders a status as readable text, pretty-printing a JSON description. */
+export const toString = <Details extends z.ZodType = z.ZodNever>(
+  stat: Status<Details>,
+  options: ToStringOptions = {},
+): string => {
+  const opts = { ...DEFAULT_TO_STRING_OPTIONS, ...options };
+  const parts: string[] = [];
+  let header = stat.variant.toUpperCase();
+  if (opts.includeName && primitive.isNonZero(stat.name)) header += ` [${stat.name}]`;
+  header += `: ${stat.message}`;
+  if (opts.includeTimestamp) header += ` (${stat.time.toString("dateTime", "local")})`;
+  parts.push(header);
+  if (primitive.isNonZero(stat.description))
+    parts.push(renderDescription(stat.description));
+  if ("details" in stat && narrow.isObject(stat.details)) {
+    const details = stat.details as Record<string, unknown>;
+    if ("stack" in details && typeof details.stack === "string" && details.stack !== "")
+      parts.push(`Stack Trace:\n${details.stack}`);
+    const extraDetails = Object.fromEntries(
+      Object.entries(details).filter(([k]) => k !== "stack" && k !== "error"),
+    );
+    if (Object.keys(extraDetails).length > 0)
+      parts.push(`Details:\n${JSON.stringify(extraDetails, null, 2)}`);
+  }
+  return parts.join("\n\n");
+};

package/src/status/types.gen.ts

@@ -0,0 +1,108 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+// Code generated by Oracle. DO NOT EDIT.
+
+import { id, type optional, telem, TimeStamp, zod } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { label } from "@/label";
+
+export const VARIANTS = [
+  "success",
+  "info",
+  "warning",
+  "error",
+  "loading",
+  "disabled",
+] as const;
+export const variantZ = z.enum(VARIANTS);
+export const successVariantZ = z.literal("success");
+export const infoVariantZ = z.literal("info");
+export const warningVariantZ = z.literal("warning");
+export const errorVariantZ = z.literal("error");
+export const loadingVariantZ = z.literal("loading");
+export const disabledVariantZ = z.literal("disabled");
+export type Variant = z.infer<typeof variantZ>;
+
+export const keyZ = z.string();
+export type Key = z.infer<typeof keyZ>;
+
+export interface StatusSchemas<
+  Details extends z.ZodType = z.ZodType,
+  V extends z.ZodType<Variant> = z.ZodType<Variant>,
+> {
+  details: Details;
+  v: V;
+}
+
+export type StatusZodObject<
+  Details extends z.ZodType = z.ZodNever,
+  V extends z.ZodType<Variant> = typeof variantZ,
+> = z.ZodObject<{
+  key: z.ZodDefault<typeof keyZ>;
+  name: z.ZodDefault<z.ZodString>;
+  variant: V;
+  message: z.ZodString;
+  description: z.ZodDefault<z.ZodString>;
+  time: z.ZodDefault<typeof telem.timeStampZ>;
+  labels: ReturnType<typeof zod.nullToUndefined<z.ZodArray<typeof label.labelZ>>>;
+  details: [Details] extends [z.ZodNever] ? z.ZodOptional<z.ZodUnknown> : Details;
+}>;
+
+export interface StatusZFunction {
+  <
+    Details extends z.ZodType = z.ZodNever,
+    V extends z.ZodType<Variant> = typeof variantZ,
+  >(args: {
+    details?: Details;
+    v?: V;
+  }): StatusZodObject<Details, V>;
+  <
+    Details extends z.ZodType = z.ZodNever,
+    V extends z.ZodType<Variant> = typeof variantZ,
+  >(
+    args?: Partial<StatusSchemas<Details, V>>,
+  ): StatusZodObject<Details, V>;
+}
+
+export const statusZ: StatusZFunction = <
+  Details extends z.ZodType,
+  V extends z.ZodType<Variant>,
+>({ details, v }: Partial<StatusSchemas<Details, V>> = {}) =>
+  z.object({
+    key: keyZ.default(id.create),
+    name: z.string().default(""),
+    variant: v ?? variantZ,
+    message: z.string(),
+    description: z.string().default(""),
+    time: telem.timeStampZ.default(() => TimeStamp.now()),
+    details: details ?? z.unknown().optional(),
+    labels: zod.nullToUndefined(label.labelZ.array()),
+  });
+export type Status<
+  Details extends z.ZodType = z.ZodNever,
+  V extends z.ZodType<Variant> = typeof variantZ,
+> = {
+  key: Key;
+  name: string;
+  variant: z.infer<V>;
+  message: string;
+  description: string;
+  time: telem.TimeStamp;
+  labels?: label.Label[];
+} & ([Details] extends [z.ZodNever] ? {} : { details: z.infer<Details> });
+export type New<
+  Details extends z.ZodType = z.ZodNever,
+  V extends z.ZodType<Variant> = typeof variantZ,
+> = Omit<
+  optional.Optional<Status<Details, V>, "key" | "name" | "description" | "time">,
+  "details"
+> &
+  ([Details] extends [z.ZodNever] ? {} : { details: z.input<Details> });

package/src/table/actions.gen.ts

@@ -8,12 +8,22 @@
 // included in the file licenses/APL.txt.
 
 // Code generated by Oracle. DO NOT EDIT.
-import { array } from "@synnaxlabs/x";
+import { zod } from "@synnaxlabs/x";
 import { type Draft } from "immer";
 import { z } from "zod";
 
 import { actions } from "@/actions";
-import { cellTemplateZ, cellZ, keyZ, type Table } from "@/table/types.gen";
+import { cellTemplateZ, cellZ, keyZ, type Table, tableZ } from "@/table/types.gen";
+
+/**
+ * Create replaces the document with the given created state. Emitted by the Core on
+ * create so remote caches ingest new documents; clients never dispatch it.
+ */
+export const createPayloadZ = z.object({
+  table: tableZ,
+});
+
+export type CreatePayload = z.infer<typeof createPayloadZ>;
 
 /** Rename renames the table. */
 export const renamePayloadZ = z.object({
@@ -25,33 +35,28 @@ export type RenamePayload = z.infer<typeof renamePayloadZ>;
 /**
  * AddRow inserts a row at the given index. Three flows:
  *
- * 1. User gesture with cell_template against a non-empty table:
- *    replicate the template once per existing column.
- * 2. User gesture with cell_template against a fully-empty table:
- *    seed a 1x1 grid (one template replica plus one default-sized
- *    column).
- * 3. Undo replay of RemoveRow (cell_template is null, cells is
- *    non-empty): use cells as-is. If the original RemoveRow had
- *    stripped the table down to no columns, the explicit cells
- *    trigger the same column-bootstrap as flow 2.
+ * 1. User gesture with cell_template against a non-empty table: replicate the template
+ * once per existing column. 2. User gesture with cell_template against a fully-empty
+ * table: seed a 1x1 grid (one template replica plus one default-sized column). 3. Undo
+ * replay of RemoveRow (cell_template is null, cells is non-empty): use cells as-is. If
+ * the original RemoveRow had stripped the table down to no columns, the explicit cells
+ * trigger the same column-bootstrap as flow 2.
  *
- * Derived replica keys come from the template's key with the last
- * four hex digits replaced by the column index. Out-of-range
- * indices clamp to the end.
+ * Derived replica keys come from the template's key with the last four hex digits
+ * replaced by the column index. Out-of-range indices clamp to the end.
  */
 export const addRowPayloadZ = z.object({
   index: z.uint32(),
   size: z.number(),
-  cells: array.nullishToEmpty(cellZ),
+  cells: cellZ.array().default(() => []),
   cellTemplate: cellZ.optional(),
 });
 
 export type AddRowPayload = z.infer<typeof addRowPayloadZ>;
 
 /**
- * RemoveRow removes the row at the given index. All cells referenced by the
- * removed row are also dropped from the cells map. No-op if the
- * index is out of range.
+ * RemoveRow removes the row at the given index. All cells referenced by the removed row
+ * are also dropped from the cells map. No-op if the index is out of range.
  */
 export const removeRowPayloadZ = z.object({
   index: z.uint32(),
@@ -62,35 +67,30 @@ export type RemoveRowPayload = z.infer<typeof removeRowPayloadZ>;
 /**
  * AddCol inserts a column at the given index. Three flows:
  *
- * 1. User gesture with cell_template against a non-empty table:
- *    replicate the template once per existing row.
- * 2. User gesture with cell_template against a fully-empty table:
- *    seed a 1x1 grid (one template replica plus one default-sized
- *    row).
- * 3. Undo replay of RemoveCol (cell_template is null, cells is
- *    non-empty): use cells as-is. If the original RemoveCol had
- *    stripped the table down to no rows, the explicit cells
- *    trigger the same row-bootstrap as flow 2.
+ * 1. User gesture with cell_template against a non-empty table: replicate the template
+ * once per existing row. 2. User gesture with cell_template against a fully-empty
+ * table: seed a 1x1 grid (one template replica plus one default-sized row). 3. Undo
+ * replay of RemoveCol (cell_template is null, cells is non-empty): use cells as-is. If
+ * the original RemoveCol had stripped the table down to no rows, the explicit cells
+ * trigger the same row-bootstrap as flow 2.
  *
- * Derived replica keys come from the template's key with the last
- * four hex digits replaced by the row index. Cells whose row
- * index exceeds the row count are added to the cells map but not
- * referenced by any row. Out-of-range indices clamp to the end of
+ * Derived replica keys come from the template's key with the last four hex digits
+ * replaced by the row index. Cells whose row index exceeds the row count are added to
+ * the cells map but not referenced by any row. Out-of-range indices clamp to the end of
  * every row's cells list.
  */
 export const addColPayloadZ = z.object({
   index: z.uint32(),
   size: z.number(),
-  cells: array.nullishToEmpty(cellZ),
+  cells: cellZ.array().default(() => []),
   cellTemplate: cellZ.optional(),
 });
 
 export type AddColPayload = z.infer<typeof addColPayloadZ>;
 
 /**
- * RemoveCol removes the column at the given index. All cells in that column
- * (across every row) are dropped from the cells map. No-op if the
- * index is out of range.
+ * RemoveCol removes the column at the given index. All cells in that column (across
+ * every row) are dropped from the cells map. No-op if the index is out of range.
  */
 export const removeColPayloadZ = z.object({
   index: z.uint32(),
@@ -106,7 +106,9 @@ export const resizeRowPayloadZ = z.object({
 
 export type ResizeRowPayload = z.infer<typeof resizeRowPayloadZ>;
 
-/** ResizeCol resizes the column at the given index. No-op if the index is out of range. */
+/**
+ * ResizeCol resizes the column at the given index. No-op if the index is out of range.
+ */
 export const resizeColPayloadZ = z.object({
   index: z.uint32(),
   size: z.number(),
@@ -115,8 +117,8 @@ export const resizeColPayloadZ = z.object({
 export type ResizeColPayload = z.infer<typeof resizeColPayloadZ>;
 
 /**
- * SetCell replaces the cell at cell.key with the provided value. No-op if
- * no cell with that key exists in the table.
+ * SetCell replaces the cell at cell.key with the provided value. No-op if no cell with
+ * that key exists in the table.
  */
 export const setCellPayloadZ = z.object({
   cell: cellZ,
@@ -125,21 +127,24 @@ export const setCellPayloadZ = z.object({
 export type SetCellPayload = z.infer<typeof setCellPayloadZ>;
 
 /**
- * EraseCells erases the cells whose keys are in cells. Any row whose every
- * cell is in the selection is removed entirely; same for columns.
- * Cells that survive that row/column removal have their variant
- * and props replaced with the template's, keeping their original
- * keys. Cells in the selection whose keys are not in the table's
- * cells map are silently skipped.
+ * EraseCells erases the cells whose keys are in cells. Any row whose every cell is in
+ * the selection is removed entirely; same for columns. Cells that survive that
+ * row/column removal have their variant and props replaced with the template's, keeping
+ * their original keys. Cells in the selection whose keys are not in the table's cells
+ * map are silently skipped.
  */
 export const eraseCellsPayloadZ = z.object({
-  cells: array.nullishToEmpty(z.string()),
+  cells: z
+    .string()
+    .array()
+    .default(() => []),
   template: cellTemplateZ,
 });
 
 export type EraseCellsPayload = z.infer<typeof eraseCellsPayloadZ>;
 
 export const actionZ = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("create"), create: createPayloadZ }),
   z.object({ type: z.literal("rename"), rename: renamePayloadZ }),
   z.object({ type: z.literal("add_row"), addRow: addRowPayloadZ }),
   z.object({ type: z.literal("remove_row"), removeRow: removeRowPayloadZ }),
@@ -153,49 +158,74 @@ export const actionZ = z.discriminatedUnion("type", [
 
 export type Action = z.infer<typeof actionZ>;
 
-export const rename = (payload: RenamePayload): Action => ({
+export const create = (payload: z.input<typeof createPayloadZ>): Action => ({
+  type: "create",
+  create: zod.parse(createPayloadZ, payload, {
+    label: "table create action payload",
+  }),
+});
+
+export const rename = (payload: z.input<typeof renamePayloadZ>): Action => ({
   type: "rename",
-  rename: payload,
+  rename: zod.parse(renamePayloadZ, payload, {
+    label: "table rename action payload",
+  }),
 });
 
-export const addRow = (payload: AddRowPayload): Action => ({
+export const addRow = (payload: z.input<typeof addRowPayloadZ>): Action => ({
   type: "add_row",
-  addRow: payload,
+  addRow: zod.parse(addRowPayloadZ, payload, {
+    label: "table add_row action payload",
+  }),
 });
 
-export const removeRow = (payload: RemoveRowPayload): Action => ({
+export const removeRow = (payload: z.input<typeof removeRowPayloadZ>): Action => ({
   type: "remove_row",
-  removeRow: payload,
+  removeRow: zod.parse(removeRowPayloadZ, payload, {
+    label: "table remove_row action payload",
+  }),
 });
 
-export const addCol = (payload: AddColPayload): Action => ({
+export const addCol = (payload: z.input<typeof addColPayloadZ>): Action => ({
   type: "add_col",
-  addCol: payload,
+  addCol: zod.parse(addColPayloadZ, payload, {
+    label: "table add_col action payload",
+  }),
 });
 
-export const removeCol = (payload: RemoveColPayload): Action => ({
+export const removeCol = (payload: z.input<typeof removeColPayloadZ>): Action => ({
   type: "remove_col",
-  removeCol: payload,
+  removeCol: zod.parse(removeColPayloadZ, payload, {
+    label: "table remove_col action payload",
+  }),
 });
 
-export const resizeRow = (payload: ResizeRowPayload): Action => ({
+export const resizeRow = (payload: z.input<typeof resizeRowPayloadZ>): Action => ({
   type: "resize_row",
-  resizeRow: payload,
+  resizeRow: zod.parse(resizeRowPayloadZ, payload, {
+    label: "table resize_row action payload",
+  }),
 });
 
-export const resizeCol = (payload: ResizeColPayload): Action => ({
+export const resizeCol = (payload: z.input<typeof resizeColPayloadZ>): Action => ({
   type: "resize_col",
-  resizeCol: payload,
+  resizeCol: zod.parse(resizeColPayloadZ, payload, {
+    label: "table resize_col action payload",
+  }),
 });
 
-export const setCell = (payload: SetCellPayload): Action => ({
+export const setCell = (payload: z.input<typeof setCellPayloadZ>): Action => ({
   type: "set_cell",
-  setCell: payload,
+  setCell: zod.parse(setCellPayloadZ, payload, {
+    label: "table set_cell action payload",
+  }),
 });
 
-export const eraseCells = (payload: EraseCellsPayload): Action => ({
+export const eraseCells = (payload: z.input<typeof eraseCellsPayloadZ>): Action => ({
   type: "erase_cells",
-  eraseCells: payload,
+  eraseCells: zod.parse(eraseCellsPayloadZ, payload, {
+    label: "table erase_cells action payload",
+  }),
 });
 
 export type HandlerResult = actions.HandlerResult<Action>;
@@ -203,6 +233,7 @@ export type HandlerResult = actions.HandlerResult<Action>;
 export type ReduceAllResult = actions.ReduceAllResult<Table, Action>;
 
 export interface Handlers {
+  create: (state: Draft<Table>, payload: CreatePayload) => HandlerResult;
   rename: (state: Draft<Table>, payload: RenamePayload) => HandlerResult;
   addRow: (state: Draft<Table>, payload: AddRowPayload) => HandlerResult;
   removeRow: (state: Draft<Table>, payload: RemoveRowPayload) => HandlerResult;
@@ -217,6 +248,8 @@ export interface Handlers {
 export const createReduceAll = (handlers: Handlers) =>
   actions.createReduceAll<Table, Action>((state, action) => {
     switch (action.type) {
+      case "create":
+        return handlers.create(state, action.create);
       case "rename":
         return handlers.rename(state, action.rename);
       case "add_row":