@stigmer/sdk 0.0.36 → 0.0.39

package/github.js

@@ -0,0 +1,51 @@
+import { createClient } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { ExchangeOAuthCodeRequestSchema, GetOAuthAuthorizeUrlRequestSchema, GitHubService, } from "@stigmer/protos/ai/stigmer/platform/github/v1/service_pb";
+import { wrapError } from "./gen/errors";
+/**
+ * Client for GitHub OAuth integration.
+ *
+ * Provides methods to initiate the OAuth flow (get authorize URL) and
+ * exchange the authorization code for an access token. The access token
+ * is returned to the caller — the backend never persists it.
+ */
+export class GitHubClient {
+    github;
+    constructor(transport) {
+        this.github = createClient(GitHubService, transport);
+    }
+    /** Get the GitHub OAuth authorize URL to redirect the user to. */
+    async getOAuthAuthorizeUrl(params) {
+        try {
+            const resp = await this.github.getOAuthAuthorizeUrl(create(GetOAuthAuthorizeUrlRequestSchema, {
+                redirectUri: params.redirectUri,
+            }));
+            return {
+                authorizeUrl: resp.authorizeUrl,
+                state: resp.state,
+            };
+        }
+        catch (e) {
+            throw wrapError(e);
+        }
+    }
+    /** Exchange an OAuth authorization code for an access token. */
+    async exchangeOAuthCode(params) {
+        try {
+            const resp = await this.github.exchangeOAuthCode(create(ExchangeOAuthCodeRequestSchema, {
+                code: params.code,
+                state: params.state,
+                redirectUri: params.redirectUri,
+            }));
+            return {
+                accessToken: resp.accessToken,
+                tokenType: resp.tokenType,
+                scope: resp.scope,
+            };
+        }
+        catch (e) {
+            throw wrapError(e);
+        }
+    }
+}
+//# sourceMappingURL=github.js.map

package/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA+B,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EACL,8BAA8B,EAC9B,iCAAiC,EACjC,aAAa,GACd,MAAM,0DAA0D,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA2BzC;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,CAA+B;IAEtD,YAAY,SAAoB;QAC9B,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACvD,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,oBAAoB,CACxB,MAAkC;QAElC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,oBAAoB,CACjD,MAAM,CAAC,iCAAiC,EAAE;gBACxC,WAAW,EAAE,MAAM,CAAC,WAAW;aAChC,CAAC,CACH,CAAC;YACF,OAAO;gBACL,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,KAAK,EAAE,IAAI,CAAC,KAAK;aAClB,CAAC;QACJ,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,iBAAiB,CACrB,MAA+B;QAE/B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAC9C,MAAM,CAAC,8BAA8B,EAAE;gBACrC,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,WAAW,EAAE,MAAM,CAAC,WAAW;aAChC,CAAC,CACH,CAAC;YACF,OAAO;gBACL,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,KAAK,EAAE,IAAI,CAAC,KAAK;aAClB,CAAC;QACJ,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF"}

package/index.d.ts

@@ -2,6 +2,7 @@ export { Stigmer } from "./stigmer";
 export { type StigmerConfig, type TokenProvider } from "./config";
 export { StigmerError, type ErrorCode, isNotFound, isUnauthenticated, isPermissionDenied, isRetryable, type ErrorCategory, isConnectError, classifyError, isRetryableError, getUserMessage, type RpcErrorMetadata, annotateRpcError, getRpcMetadata, } from "./errors";
 export { SearchClient, type SearchParams, type SearchResponse, ApiResourceKind, } from "./search";
+export { GitHubClient, type GetOAuthAuthorizeUrlParams, type OAuthAuthorizeUrlResponse, type ExchangeOAuthCodeParams, type OAuthTokenResponse, } from "./github";
 export { type DeleteResourceInput, type ResourceRef, type Page, type ListParams, type ListResult, type EnvSpecInput, type EnvVarInput, } from "./gen/types";
 export { AgentClient, type AgentInput, type McpServerUsageInput, type ToolApprovalOverrideInput, type SubAgentInput, type McpAccessInput, } from "./gen/agent";
 export { AgentExecutionClient, type AgentExecutionInput, type ExecutionConfigInput, type ContextManagementConfigInput, type AttachmentInput, } from "./gen/agentexecution";

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAGlE,OAAO,EACL,YAAY,EACZ,KAAK,SAAS,EACd,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,KAAK,aAAa,EAClB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,cAAc,GACf,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,eAAe,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,WAAW,EACX,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EACjC,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,EACnB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,iBAAiB,EACjB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,EACtB,KAAK,qBAAqB,GAC3B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,sBAAsB,EACtB,KAAK,qBAAqB,GAC3B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EACL,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,uBAAuB,EACvB,KAAK,sBAAsB,GAC5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,sBAAsB,EACtB,KAAK,qBAAqB,GAC3B,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/index.js

@@ -5,6 +5,8 @@ export { Stigmer } from "./stigmer";
 export { StigmerError, isNotFound, isUnauthenticated, isPermissionDenied, isRetryable, isConnectError, classifyError, isRetryableError, getUserMessage, annotateRpcError, getRpcMetadata, } from "./errors";
 // Search client
 export { SearchClient, ApiResourceKind, } from "./search";
+// GitHub OAuth client
+export { GitHubClient, } from "./github";
 // Re-export all resource client classes and input types
 export { AgentClient, } from "./gen/agent";
 export { AgentExecutionClient, } from "./gen/agentexecution";

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAE9B,mBAAmB;AACnB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,iBAAiB;AACjB,OAAO,EACL,YAAY,EAEZ,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EAEX,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,cAAc,EAEd,gBAAgB,EAChB,cAAc,GACf,MAAM,UAAU,CAAC;AAElB,gBAAgB;AAChB,OAAO,EACL,YAAY,EAGZ,eAAe,GAChB,MAAM,UAAU,CAAC;AAalB,wDAAwD;AACxD,OAAO,EACL,WAAW,GAMZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,GAKrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,GAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAoB,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,eAAe,GAGhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,GAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,eAAe,GAKhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAqB,MAAM,eAAe,CAAC;AACjE,OAAO,EACL,aAAa,GAMd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAmB,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,cAAc,GAMf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,uBAAuB,GAExB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAE9B,mBAAmB;AACnB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,iBAAiB;AACjB,OAAO,EACL,YAAY,EAEZ,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EAEX,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,cAAc,EAEd,gBAAgB,EAChB,cAAc,GACf,MAAM,UAAU,CAAC;AAElB,gBAAgB;AAChB,OAAO,EACL,YAAY,EAGZ,eAAe,GAChB,MAAM,UAAU,CAAC;AAElB,sBAAsB;AACtB,OAAO,EACL,YAAY,GAKb,MAAM,UAAU,CAAC;AAalB,wDAAwD;AACxD,OAAO,EACL,WAAW,GAMZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,GAKrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,GAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAoB,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,eAAe,GAGhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,qBAAqB,GAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,eAAe,GAKhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,GAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAqB,MAAM,eAAe,CAAC;AACjE,OAAO,EACL,aAAa,GAMd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAmB,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,cAAc,GAMf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,uBAAuB,GAExB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/sdk",
-  "version": "0.0.36",
+  "version": "0.0.39",
   "description": "Stigmer TypeScript SDK — typed API client for all Stigmer platform resources",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,6 +35,6 @@
   },
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.0.0",
-    "@stigmer/protos": "0.0.36"
+    "@stigmer/protos": "0.0.39"
   }
 }

package/src/__tests__/config.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { validateConfig, type StigmerConfig } from "../config";
+
+describe("validateConfig", () => {
+  const validApiKeyConfig: StigmerConfig = {
+    baseUrl: "https://api.stigmer.io",
+    apiKey: "sk_live_abc123",
+  };
+
+  const validTokenProviderConfig: StigmerConfig = {
+    baseUrl: "https://api.stigmer.io",
+    getAccessToken: () => "token",
+  };
+
+  it("accepts a valid config with apiKey", () => {
+    expect(() => validateConfig(validApiKeyConfig)).not.toThrow();
+  });
+
+  it("accepts a valid config with getAccessToken", () => {
+    expect(() => validateConfig(validTokenProviderConfig)).not.toThrow();
+  });
+
+  it("rejects missing baseUrl", () => {
+    expect(() =>
+      validateConfig({ baseUrl: "", apiKey: "key" }),
+    ).toThrow("stigmer: baseUrl is required");
+  });
+
+  it("rejects missing both apiKey and getAccessToken", () => {
+    expect(() =>
+      validateConfig({ baseUrl: "https://api.stigmer.io" }),
+    ).toThrow("stigmer: either apiKey or getAccessToken must be provided");
+  });
+
+  it("rejects empty apiKey without getAccessToken", () => {
+    expect(() =>
+      validateConfig({ baseUrl: "https://api.stigmer.io", apiKey: "" }),
+    ).toThrow("stigmer: either apiKey or getAccessToken must be provided");
+  });
+
+  it("rejects providing both apiKey and getAccessToken", () => {
+    expect(() =>
+      validateConfig({
+        baseUrl: "https://api.stigmer.io",
+        apiKey: "sk_live_abc123",
+        getAccessToken: () => "token",
+      }),
+    ).toThrow(
+      "stigmer: apiKey and getAccessToken are mutually exclusive — provide one, not both",
+    );
+  });
+});

package/src/__tests__/errors.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import { ConnectError, Code } from "@connectrpc/connect";
+import { StigmerError, type ErrorCode } from "../gen/errors";
+import {
+  classifyError,
+  isRetryableError,
+  getUserMessage,
+  annotateRpcError,
+  getRpcMetadata,
+  type ErrorCategory,
+} from "../errors";
+
+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("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("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("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

@@ -0,0 +1,138 @@
+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/proto-utils.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { stripUndefined } from "../../gen/proto-utils";
+
+describe("stripUndefined", () => {
+  it("removes keys with undefined values", () => {
+    const result = stripUndefined({ a: 1, b: undefined, c: "hello" });
+    expect(result).toEqual({ a: 1, c: "hello" });
+    expect("b" in result).toBe(false);
+  });
+
+  it("preserves null values (falsy but defined)", () => {
+    const result = stripUndefined({ a: null });
+    expect(result).toEqual({ a: null });
+  });
+
+  it("preserves 0 (falsy but defined)", () => {
+    const result = stripUndefined({ count: 0 });
+    expect(result).toEqual({ count: 0 });
+  });
+
+  it("preserves empty string (falsy but defined)", () => {
+    const result = stripUndefined({ name: "" });
+    expect(result).toEqual({ name: "" });
+  });
+
+  it("preserves false (falsy but defined)", () => {
+    const result = stripUndefined({ enabled: false });
+    expect(result).toEqual({ enabled: false });
+  });
+
+  it("returns empty object when all values are undefined", () => {
+    const result = stripUndefined({ a: undefined, b: undefined });
+    expect(result).toEqual({});
+  });
+
+  it("returns all keys when nothing is undefined", () => {
+    const input = { x: 1, y: "two", z: true };
+    const result = stripUndefined(input);
+    expect(result).toEqual(input);
+  });
+
+  it("preserves nested objects without deep-stripping", () => {
+    const nested = { inner: undefined };
+    const result = stripUndefined({ outer: nested });
+    expect(result).toEqual({ outer: nested });
+    expect((result as Record<string, unknown>).outer).toBe(nested);
+  });
+
+  it("returns empty object for empty input", () => {
+    const result = stripUndefined({});
+    expect(result).toEqual({});
+  });
+});