@stigmer/sdk 3.35.0 → 3.37.0

package/src/__tests__/errors.test.ts

@@ -1,349 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { ConnectError, Code } from "@connectrpc/connect";
-import { ErrorInfoSchema } from "@stigmer/protos/google/rpc/error_details_pb";
-import { StigmerError, type ErrorCode } from "../gen/errors";
-import {
-  classifyError,
-  isRetryableError,
-  isTransientStreamError,
-  getUserMessage,
-  getErrorReason,
-  annotateRpcError,
-  getRpcMetadata,
-  type ErrorCategory,
-} from "../errors";
-
-/**
- * Guest launch-gate refusal contract (shared-agent abuse controls).
- *
- * The cloud backend resolves owner-customizable refusal copy server-side and
- * carries it in the gRPC status description; the SDK must surface that copy
- * VERBATIM through getUserMessage — no client-side mapping exists by design.
- * These tests pin the two halves of that contract:
- *
- * 1. RESOURCE_EXHAUSTED / FAILED_PRECONDITION descriptions pass through
- *    getUserMessage untouched.
- * 2. The platform-default copy (mirrors GuestLimitReason in the cloud
- *    backend) never collides with the sanitizer's rewrite patterns.
- */
-describe("guest launch-gate refusal copy passthrough", () => {
-  // Mirrors GuestLimitReason default copy in the cloud stigmer-service.
-  // If those strings change, update here — this guardrail exists to catch a
-  // default that a sanitizer pattern would silently rewrite.
-  const platformDefaultCopy = [
-    "You\u2019re sending messages too quickly. Please wait a moment before sending another.",
-    "This agent is currently unavailable. Please check back later.",
-    "This conversation has ended. Please start a new conversation to continue.",
-    "This agent can\u2019t be embedded on this site.",
-  ];
-
-  const refusalCodes: Array<[string, Code]> = [
-    ["ResourceExhausted (rate limit)", Code.ResourceExhausted],
-    ["FailedPrecondition (fail-closed / bounds)", Code.FailedPrecondition],
-    ["PermissionDenied (embed origin)", Code.PermissionDenied],
-  ];
-
-  it.each(refusalCodes)(
-    "surfaces a %s status description verbatim",
-    (_label, code) => {
-      for (const copy of platformDefaultCopy) {
-        expect(getUserMessage(new ConnectError(copy, code))).toBe(copy);
-      }
-    },
-  );
-
-  it("surfaces owner-customized copy verbatim", () => {
-    const ownerCopy = "Whoa, slow down! Try again in a minute or two.";
-    expect(
-      getUserMessage(new ConnectError(ownerCopy, Code.ResourceExhausted)),
-    ).toBe(ownerCopy);
-  });
-
-  it("classifies rate-limit refusals as retryable and bounds refusals as not", () => {
-    expect(
-      isRetryableError(new ConnectError("copy", Code.ResourceExhausted)),
-    ).toBe(true);
-    expect(
-      isRetryableError(new ConnectError("copy", Code.FailedPrecondition)),
-    ).toBe(false);
-  });
-});
-
-describe("classifyError", () => {
-  const stigmerMappings: Array<[string, ErrorCategory]> = [
-    ["unauthenticated", "auth"],
-    ["permission-denied", "permission"],
-    ["not-found", "not-found"],
-    ["invalid-argument", "validation"],
-    ["already-exists", "validation"],
-    ["failed-precondition", "validation"],
-    ["resource-exhausted", "unavailable"],
-    ["internal", "server"],
-    ["unavailable", "unavailable"],
-    ["cancelled", "cancelled"],
-    ["unknown", "server"],
-  ];
-
-  it.each(stigmerMappings)(
-    "maps StigmerError code '%s' to category '%s'",
-    (errorCode, expectedCategory) => {
-      const result = classifyError(
-        new StigmerError(errorCode as ErrorCode, "test", Code.Unknown),
-      );
-      expect(result).toBe(expectedCategory);
-    },
-  );
-
-  const connectMappings: Array<[Code, ErrorCategory]> = [
-    [Code.Unauthenticated, "auth"],
-    [Code.PermissionDenied, "permission"],
-    [Code.NotFound, "not-found"],
-    [Code.InvalidArgument, "validation"],
-    [Code.FailedPrecondition, "validation"],
-    [Code.OutOfRange, "validation"],
-    [Code.AlreadyExists, "validation"],
-    [Code.Aborted, "validation"],
-    [Code.Internal, "server"],
-    [Code.Unknown, "server"],
-    [Code.DataLoss, "server"],
-    [Code.Unimplemented, "server"],
-    [Code.Unavailable, "unavailable"],
-    [Code.DeadlineExceeded, "unavailable"],
-    [Code.ResourceExhausted, "unavailable"],
-    [Code.Canceled, "cancelled"],
-  ];
-
-  it.each(connectMappings)(
-    "maps ConnectError code %i to category '%s'",
-    (code, expectedCategory) => {
-      const result = classifyError(new ConnectError("test", code));
-      expect(result).toBe(expectedCategory);
-    },
-  );
-
-  it("returns 'unknown' for plain Error", () => {
-    expect(classifyError(new Error("random"))).toBe("unknown");
-  });
-
-  it("returns 'unknown' for string", () => {
-    expect(classifyError("just a string")).toBe("unknown");
-  });
-
-  it("returns 'unknown' for null", () => {
-    expect(classifyError(null)).toBe("unknown");
-  });
-});
-
-describe("isRetryableError", () => {
-  it("returns true for 'server' category errors", () => {
-    expect(
-      isRetryableError(new StigmerError("internal", "boom", Code.Internal)),
-    ).toBe(true);
-  });
-
-  it("returns true for 'unavailable' category errors", () => {
-    expect(
-      isRetryableError(
-        new StigmerError("unavailable", "down", Code.Unavailable),
-      ),
-    ).toBe(true);
-  });
-
-  it("returns false for 'auth' category errors", () => {
-    expect(
-      isRetryableError(
-        new StigmerError("unauthenticated", "bad token", Code.Unauthenticated),
-      ),
-    ).toBe(false);
-  });
-
-  it("returns false for 'not-found' category errors", () => {
-    expect(
-      isRetryableError(
-        new StigmerError("not-found", "gone", Code.NotFound),
-      ),
-    ).toBe(false);
-  });
-
-  it("returns false for plain Error", () => {
-    expect(isRetryableError(new Error("oops"))).toBe(false);
-  });
-});
-
-describe("isTransientStreamError", () => {
-  it("is true for retryable category errors (server / unavailable)", () => {
-    expect(
-      isTransientStreamError(
-        new StigmerError("unavailable", "down", Code.Unavailable),
-      ),
-    ).toBe(true);
-    expect(
-      isTransientStreamError(new ConnectError("boom", Code.Internal)),
-    ).toBe(true);
-  });
-
-  // The crux of #174: WebKit (Safari / WKWebView) phrases a failed fetch as a
-  // bare `TypeError: Load failed`, which classifies as `unknown` (not
-  // retryable) — yet it is exactly the transient drop we must auto-reconnect.
-  it.each([
-    "Load failed",
-    "TypeError: Load failed",
-    "Failed to fetch",
-    "fetch failed",
-    "read ECONNRESET",
-    "connect ETIMEDOUT",
-  ])("is true for transport noise %j (even as a bare TypeError)", (message) => {
-    expect(isTransientStreamError(new TypeError(message))).toBe(true);
-  });
-
-  it.each([
-    new StigmerError("not-found", "gone", Code.NotFound),
-    new StigmerError("invalid-argument", "bad", Code.InvalidArgument),
-    new StigmerError("unauthenticated", "no token", Code.Unauthenticated),
-    new Error("some deterministic application error"),
-  ])("is false for deterministic / unknown errors", (error) => {
-    expect(isTransientStreamError(error)).toBe(false);
-  });
-});
-
-describe("getUserMessage", () => {
-  it("extracts message from StigmerError", () => {
-    const err = new StigmerError("not-found", "Agent not found", Code.NotFound);
-    expect(getUserMessage(err)).toBe("Agent not found");
-  });
-
-  it("extracts rawMessage from ConnectError", () => {
-    const err = new ConnectError("Agent not found", Code.NotFound);
-    expect(getUserMessage(err)).toBe("Agent not found");
-  });
-
-  it("extracts message from plain Error", () => {
-    expect(getUserMessage(new Error("something"))).toBe("something");
-  });
-
-  it("extracts message from string", () => {
-    expect(getUserMessage("a string error")).toBe("a string error");
-  });
-
-  it("sanitizes 'no healthy upstream' to readable message", () => {
-    const err = new StigmerError(
-      "unavailable",
-      "no healthy upstream",
-      Code.Unavailable,
-    );
-    expect(getUserMessage(err)).toBe(
-      "The server is temporarily unavailable.",
-    );
-  });
-
-  it("sanitizes 'ECONNREFUSED'", () => {
-    expect(getUserMessage(new Error("connect ECONNREFUSED 127.0.0.1"))).toBe(
-      "Unable to connect to the server.",
-    );
-  });
-
-  it("sanitizes 'fetch failed'", () => {
-    expect(getUserMessage(new Error("fetch failed"))).toBe(
-      "Unable to reach the server. Check your connection.",
-    );
-  });
-
-  it("sanitizes WebKit's 'Load failed' (Safari / WKWebView)", () => {
-    expect(getUserMessage(new TypeError("Load failed"))).toBe(
-      "The connection to the server was lost.",
-    );
-  });
-
-  it("uses category fallback when message is empty", () => {
-    const err = new StigmerError("not-found", "", Code.NotFound);
-    expect(getUserMessage(err)).toBe("The requested resource was not found.");
-  });
-
-  it("uses custom fallback when provided and message is empty", () => {
-    const err = new StigmerError("not-found", "", Code.NotFound);
-    expect(getUserMessage(err, "Custom fallback")).toBe("Custom fallback");
-  });
-
-  it("uses 'unknown' category fallback for non-SDK errors without message", () => {
-    expect(getUserMessage(42)).toBe("An unexpected error occurred.");
-  });
-});
-
-describe("getErrorReason", () => {
-  const errorInfoDetail = {
-    desc: ErrorInfoSchema,
-    value: {
-      domain: "stigmer.ai",
-      reason: "SLACK_WORKSPACE_ALREADY_CONNECTED",
-      metadata: { team_name: "Acme HQ", channel_app_id: "" },
-    },
-  };
-
-  it("extracts the reason from a ConnectError's ErrorInfo detail", () => {
-    const error = new ConnectError(
-      "workspace taken",
-      Code.FailedPrecondition,
-      undefined,
-      [errorInfoDetail],
-    );
-
-    expect(getErrorReason(error)).toEqual({
-      reason: "SLACK_WORKSPACE_ALREADY_CONNECTED",
-      domain: "stigmer.ai",
-      metadata: { team_name: "Acme HQ", channel_app_id: "" },
-    });
-  });
-
-  it("walks the cause chain of an SDK-wrapped StigmerError", () => {
-    const connectError = new ConnectError(
-      "workspace taken",
-      Code.FailedPrecondition,
-      undefined,
-      [errorInfoDetail],
-    );
-    const wrapped = new StigmerError(
-      "failed-precondition",
-      connectError.rawMessage,
-      Code.FailedPrecondition,
-      { cause: connectError },
-    );
-
-    expect(getErrorReason(wrapped)?.reason).toBe(
-      "SLACK_WORKSPACE_ALREADY_CONNECTED",
-    );
-  });
-
-  it("returns null for errors without an ErrorInfo detail", () => {
-    expect(
-      getErrorReason(new ConnectError("bare refusal", Code.FailedPrecondition)),
-    ).toBeNull();
-    expect(
-      getErrorReason(
-        new StigmerError("failed-precondition", "bare refusal", 9),
-      ),
-    ).toBeNull();
-    expect(getErrorReason(new Error("plain"))).toBeNull();
-    expect(getErrorReason("not an error")).toBeNull();
-    expect(getErrorReason(null)).toBeNull();
-  });
-});
-
-
-describe("annotateRpcError / getRpcMetadata", () => {
-  it("roundtrips metadata on an error object", () => {
-    const err = new Error("test");
-    const metadata = { method: "Get", path: "/api/agent" };
-    annotateRpcError(err, metadata);
-    expect(getRpcMetadata(err)).toEqual(metadata);
-  });
-
-  it("returns undefined for unannotated errors", () => {
-    expect(getRpcMetadata(new Error("no metadata"))).toBeUndefined();
-  });
-
-  it("returns undefined for non-object errors", () => {
-    expect(getRpcMetadata("string error")).toBeUndefined();
-    expect(getRpcMetadata(null)).toBeUndefined();
-    expect(getRpcMetadata(42)).toBeUndefined();
-  });
-});

package/src/__tests__/gen/errors.test.ts

@@ -1,138 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { ConnectError, Code } from "@connectrpc/connect";
-import {
-  StigmerError,
-  wrapError,
-  isNotFound,
-  isUnauthenticated,
-  isPermissionDenied,
-  isRetryable,
-} from "../../gen/errors";
-
-describe("StigmerError", () => {
-  it("has name 'StigmerError'", () => {
-    const err = new StigmerError("not-found", "resource missing", Code.NotFound);
-    expect(err.name).toBe("StigmerError");
-  });
-
-  it("inherits from Error", () => {
-    const err = new StigmerError("internal", "boom", Code.Internal);
-    expect(err).toBeInstanceOf(Error);
-  });
-
-  it("exposes code and connectCode", () => {
-    const err = new StigmerError("unauthenticated", "bad token", Code.Unauthenticated);
-    expect(err.code).toBe("unauthenticated");
-    expect(err.connectCode).toBe(Code.Unauthenticated);
-    expect(err.message).toBe("bad token");
-  });
-});
-
-describe("wrapError", () => {
-  const connectCodeMappings: Array<[Code, string]> = [
-    [Code.NotFound, "not-found"],
-    [Code.PermissionDenied, "permission-denied"],
-    [Code.Unauthenticated, "unauthenticated"],
-    [Code.InvalidArgument, "invalid-argument"],
-    [Code.AlreadyExists, "already-exists"],
-    [Code.ResourceExhausted, "resource-exhausted"],
-    [Code.FailedPrecondition, "failed-precondition"],
-    [Code.Internal, "internal"],
-    [Code.Unavailable, "unavailable"],
-    [Code.Canceled, "cancelled"],
-  ];
-
-  it.each(connectCodeMappings)(
-    "maps ConnectError code %i to ErrorCode '%s'",
-    (connectCode, expectedErrorCode) => {
-      const connectErr = new ConnectError("test", connectCode);
-      const result = wrapError(connectErr);
-      expect(result).toBeInstanceOf(StigmerError);
-      expect(result.code).toBe(expectedErrorCode);
-    },
-  );
-
-  it("maps unmapped ConnectError codes to 'unknown'", () => {
-    const connectErr = new ConnectError("test", 0 as unknown as Code);
-    const result = wrapError(connectErr);
-    expect(result.code).toBe("unknown");
-  });
-
-  it("passes through StigmerError unchanged", () => {
-    const original = new StigmerError("not-found", "gone", Code.NotFound);
-    const result = wrapError(original);
-    expect(result).toBe(original);
-  });
-
-  it("wraps plain Error as 'unknown'", () => {
-    const result = wrapError(new Error("something broke"));
-    expect(result).toBeInstanceOf(StigmerError);
-    expect(result.code).toBe("unknown");
-    expect(result.message).toBe("something broke");
-  });
-
-  it("wraps string as 'unknown'", () => {
-    const result = wrapError("raw string error");
-    expect(result).toBeInstanceOf(StigmerError);
-    expect(result.code).toBe("unknown");
-    expect(result.message).toBe("raw string error");
-  });
-});
-
-describe("predicates", () => {
-  it("isNotFound returns true for not-found StigmerError", () => {
-    expect(isNotFound(new StigmerError("not-found", "x", Code.NotFound))).toBe(true);
-  });
-
-  it("isNotFound returns false for other codes", () => {
-    expect(isNotFound(new StigmerError("internal", "x", Code.Internal))).toBe(false);
-  });
-
-  it("isNotFound returns false for non-StigmerError", () => {
-    expect(isNotFound(new Error("not found"))).toBe(false);
-  });
-
-  it("isUnauthenticated returns true for unauthenticated StigmerError", () => {
-    expect(
-      isUnauthenticated(new StigmerError("unauthenticated", "x", Code.Unauthenticated)),
-    ).toBe(true);
-  });
-
-  it("isUnauthenticated returns false for other codes", () => {
-    expect(
-      isUnauthenticated(new StigmerError("not-found", "x", Code.NotFound)),
-    ).toBe(false);
-  });
-
-  it("isPermissionDenied returns true for permission-denied StigmerError", () => {
-    expect(
-      isPermissionDenied(
-        new StigmerError("permission-denied", "x", Code.PermissionDenied),
-      ),
-    ).toBe(true);
-  });
-
-  it("isPermissionDenied returns false for other codes", () => {
-    expect(
-      isPermissionDenied(new StigmerError("internal", "x", Code.Internal)),
-    ).toBe(false);
-  });
-
-  it("isRetryable returns true for internal", () => {
-    expect(isRetryable(new StigmerError("internal", "x", Code.Internal))).toBe(true);
-  });
-
-  it("isRetryable returns true for unavailable", () => {
-    expect(isRetryable(new StigmerError("unavailable", "x", Code.Unavailable))).toBe(
-      true,
-    );
-  });
-
-  it("isRetryable returns false for not-found", () => {
-    expect(isRetryable(new StigmerError("not-found", "x", Code.NotFound))).toBe(false);
-  });
-
-  it("isRetryable returns false for non-StigmerError", () => {
-    expect(isRetryable(new Error("server error"))).toBe(false);
-  });
-});

package/src/__tests__/gen/invitation-client.test.ts

@@ -1,132 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { create, toBinary, fromBinary } from "@bufbuild/protobuf";
-import { timestampDate } from "@bufbuild/protobuf/wkt";
-import { InvitationSchema } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
-import { InvitationSpecSchema } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/spec_pb";
-import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
-import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
-import { stripUndefined, toTimestamp } from "../../gen/proto-utils";
-
-/**
- * Exercises the same code path as the generated `buildInvitationProto` to
- * verify that Timestamp fields serialize without error after the codegen fix.
- */
-function buildInvitationProto(input: {
-  name: string;
-  org: string;
-  role: IamRole;
-  expiresAt: Date | string;
-  maxRedemptions?: number;
-  label?: string;
-}) {
-  const expiresAt = input.expiresAt !== undefined ? toTimestamp(input.expiresAt) : undefined;
-  return Object.assign(create(InvitationSchema), {
-    apiVersion: "iam.stigmer.ai/v1",
-    kind: "Invitation",
-    metadata: Object.assign(create(ApiResourceMetadataSchema), {
-      name: input.name,
-      org: input.org,
-    }),
-    spec: Object.assign(create(InvitationSpecSchema), stripUndefined({
-      role: input.role,
-      maxRedemptions: input.maxRedemptions,
-      expiresAt,
-      label: input.label,
-    })),
-  });
-}
-
-describe("buildInvitationProto", () => {
-  it("produces a message with a valid Timestamp from a Date", () => {
-    const expiresAt = new Date("2026-06-19T12:00:00.000Z");
-    const msg = buildInvitationProto({
-      name: "test-invite",
-      org: "acme",
-      role: IamRole.viewer,
-      expiresAt,
-    });
-
-    expect(msg.spec?.expiresAt).toBeDefined();
-    expect(msg.spec!.expiresAt!.seconds).toBe(
-      BigInt(Math.floor(expiresAt.getTime() / 1000)),
-    );
-    expect(timestampDate(msg.spec!.expiresAt!).getTime()).toBe(
-      expiresAt.getTime(),
-    );
-  });
-
-  it("produces a message with a valid Timestamp from an ISO string", () => {
-    const isoString = "2026-07-01T00:00:00.000Z";
-    const msg = buildInvitationProto({
-      name: "string-invite",
-      org: "acme",
-      role: IamRole.member,
-      expiresAt: isoString,
-    });
-
-    const expected = new Date(isoString);
-    expect(msg.spec?.expiresAt).toBeDefined();
-    expect(msg.spec!.expiresAt!.seconds).toBe(
-      BigInt(Math.floor(expected.getTime() / 1000)),
-    );
-  });
-
-  it("serializes to binary without error (the original bug)", () => {
-    const msg = buildInvitationProto({
-      name: "binary-test",
-      org: "acme",
-      role: IamRole.admin,
-      expiresAt: new Date(Date.now() + 7 * 86_400_000),
-      maxRedemptions: 1,
-      label: "test label",
-    });
-
-    const bytes = toBinary(InvitationSchema, msg);
-    expect(bytes.length).toBeGreaterThan(0);
-
-    const decoded = fromBinary(InvitationSchema, bytes);
-    expect(decoded.spec?.expiresAt).toBeDefined();
-    expect(decoded.spec!.expiresAt!.seconds).toBe(msg.spec!.expiresAt!.seconds);
-    expect(decoded.spec?.role).toBe(IamRole.admin);
-    expect(decoded.spec?.maxRedemptions).toBe(1);
-    expect(decoded.spec?.label).toBe("test label");
-    expect(decoded.metadata?.name).toBe("binary-test");
-    expect(decoded.metadata?.org).toBe("acme");
-  });
-
-  it("handles 7-day expiry (matches UI default options)", () => {
-    const now = Date.now();
-    const sevenDays = new Date(now + 7 * 86_400_000);
-    const msg = buildInvitationProto({
-      name: "7day",
-      org: "test-org",
-      role: IamRole.viewer,
-      expiresAt: sevenDays,
-    });
-
-    const bytes = toBinary(InvitationSchema, msg);
-    const decoded = fromBinary(InvitationSchema, bytes);
-    const decodedDate = timestampDate(decoded.spec!.expiresAt!);
-
-    const diffMs = Math.abs(decodedDate.getTime() - sevenDays.getTime());
-    expect(diffMs).toBeLessThan(1000);
-  });
-
-  it("handles 30-day expiry (matches UI default options)", () => {
-    const now = Date.now();
-    const thirtyDays = new Date(now + 30 * 86_400_000);
-    const msg = buildInvitationProto({
-      name: "30day",
-      org: "test-org",
-      role: IamRole.owner,
-      expiresAt: thirtyDays,
-    });
-
-    const bytes = toBinary(InvitationSchema, msg);
-    const decoded = fromBinary(InvitationSchema, bytes);
-    const decodedDate = timestampDate(decoded.spec!.expiresAt!);
-
-    const diffMs = Math.abs(decodedDate.getTime() - thirtyDays.getTime());
-    expect(diffMs).toBeLessThan(1000);
-  });
-});