@stigmer/sdk 0.0.36

package/src/gen/workflow.ts

@@ -0,0 +1,116 @@
+// Code generated by stigmer-codegen. DO NOT EDIT.
+
+import { wrapError } from "./errors";
+import { type EnvSpecInput, type ResourceRef } from "./types";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { WorkflowSchema, type Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import { WorkflowIdSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/io_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import { WorkflowSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+/** Provides operations on workflow resources. */
+export class WorkflowClient {
+  private readonly command: Client<typeof WorkflowCommandController>;
+  private readonly query: Client<typeof WorkflowQueryController>;
+
+  constructor(transport: Transport) {
+    this.command = createClient(WorkflowCommandController, transport);
+    this.query = createClient(WorkflowQueryController, transport);
+  }
+
+  async apply(input: WorkflowInput): Promise<Workflow> {
+    try {
+      return await this.command.apply(buildWorkflowProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async create(input: WorkflowInput): Promise<Workflow> {
+    try {
+      return await this.command.create(buildWorkflowProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async update(input: WorkflowInput): Promise<Workflow> {
+    try {
+      return await this.command.update(buildWorkflowProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async delete(id: string): Promise<Workflow> {
+    try {
+      return await this.command.delete(create(WorkflowIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async get(id: string): Promise<Workflow> {
+    try {
+      return await this.query.get(create(WorkflowIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async getByReference(ref: ResourceRef): Promise<Workflow> {
+    try {
+      return await this.query.getByReference(create(ApiResourceReferenceSchema, ref));
+    } catch (e) { throw wrapError(e); }
+  }
+}
+
+/** Input for creating/updating a Workflow. */
+export interface WorkflowInput {
+  name: string;
+  org: string;
+  description?: string;
+  document: WorkflowDocumentInput;
+  tasks?: WorkflowTaskInput[];
+  envSpec?: EnvSpecInput;
+}
+
+/** SDK input type for WorkflowDocument. */
+export interface WorkflowDocumentInput {
+  dsl?: string;
+  namespace: string;
+  name: string;
+  version: string;
+  description?: string;
+}
+
+/** SDK input type for WorkflowTask. */
+export interface WorkflowTaskInput {
+  name: string;
+  kind: WorkflowTaskKind;
+  taskConfig: JsonObject;
+  export?: ExportInput;
+  flow?: FlowControlInput;
+}
+
+/** SDK input type for Export. */
+export interface ExportInput {
+  as?: string;
+}
+
+/** SDK input type for FlowControl. */
+export interface FlowControlInput {
+  then?: string;
+}
+
+function buildWorkflowProto(input: WorkflowInput): Workflow {
+  return Object.assign(create(WorkflowSchema), {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Workflow",
+    metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      name: input.name,
+      org: input.org,
+    }),
+    spec: Object.assign(create(WorkflowSpecSchema), {
+      description: input.description,
+      document: input.document,
+      tasks: input.tasks,
+      envSpec: input.envSpec,
+    }),
+  }) as Workflow;
+}

package/src/gen/workflowexecution.ts

@@ -0,0 +1,147 @@
+// Code generated by stigmer-codegen. DO NOT EDIT.
+
+import { wrapError } from "./errors";
+import { type EnvVarInput } from "./types";
+import { create } from "@bufbuild/protobuf";
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { WorkflowExecutionSchema, type WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { WorkflowExecutionIdSchema, WorkflowExecutionUpdateStatusInputSchema, SubmitWorkflowApprovalInputSchema, SendSignalInputSchema, CancelWorkflowExecutionInputSchema, TerminateWorkflowExecutionInputSchema, RecoverWorkflowExecutionInputSchema, PauseWorkflowExecutionInputSchema, ResumeWorkflowExecutionInputSchema, ListWorkflowExecutionsRequestSchema, WorkflowExecutionListSchema, ListWorkflowExecutionsByWorkflowRequestSchema, SubscribeWorkflowExecutionRequestSchema, type WorkflowExecutionUpdateStatusInput, type SubmitWorkflowApprovalInput, type SendSignalInput, type CancelWorkflowExecutionInput, type TerminateWorkflowExecutionInput, type RecoverWorkflowExecutionInput, type PauseWorkflowExecutionInput, type ResumeWorkflowExecutionInput, type ListWorkflowExecutionsRequest, type WorkflowExecutionList, type ListWorkflowExecutionsByWorkflowRequest, type SubscribeWorkflowExecutionRequest } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+import { WorkflowExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/spec_pb";
+import { ApiResourceIdSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+/** Provides operations on workflowexecution resources. */
+export class WorkflowExecutionClient {
+  private readonly command: Client<typeof WorkflowExecutionCommandController>;
+  private readonly query: Client<typeof WorkflowExecutionQueryController>;
+
+  constructor(transport: Transport) {
+    this.command = createClient(WorkflowExecutionCommandController, transport);
+    this.query = createClient(WorkflowExecutionQueryController, transport);
+  }
+
+  async create(input: WorkflowExecutionInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.create(buildWorkflowExecutionProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async update(input: WorkflowExecutionInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.update(buildWorkflowExecutionProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async updateStatus(input: WorkflowExecutionUpdateStatusInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.updateStatus(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async submitApproval(input: SubmitWorkflowApprovalInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.submitApproval(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async delete(id: string): Promise<WorkflowExecution> {
+    try {
+      return await this.command.delete(create(ApiResourceIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async sendSignal(input: SendSignalInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.sendSignal(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async cancel(input: CancelWorkflowExecutionInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.cancel(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async terminate(input: TerminateWorkflowExecutionInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.terminate(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async recover(input: RecoverWorkflowExecutionInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.recover(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async pause(input: PauseWorkflowExecutionInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.pause(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async resume(input: ResumeWorkflowExecutionInput): Promise<WorkflowExecution> {
+    try {
+      return await this.command.resume(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async get(id: string): Promise<WorkflowExecution> {
+    try {
+      return await this.query.get(create(WorkflowExecutionIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async list(input: ListWorkflowExecutionsRequest): Promise<WorkflowExecutionList> {
+    try {
+      return await this.query.list(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async listByWorkflow(input: ListWorkflowExecutionsByWorkflowRequest): Promise<WorkflowExecutionList> {
+    try {
+      return await this.query.listByWorkflow(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async *subscribe(input: SubscribeWorkflowExecutionRequest, signal?: AbortSignal): AsyncGenerator<WorkflowExecution> {
+    try {
+      for await (const msg of this.query.subscribe(input, { signal })) {
+        yield msg;
+      }
+    } catch (e) { throw wrapError(e); }
+  }
+}
+
+/** Input for creating/updating a WorkflowExecution. */
+export interface WorkflowExecutionInput {
+  name: string;
+  org: string;
+  workflowInstanceId?: string;
+  workflowId?: string;
+  triggerMessage?: string;
+  triggerMetadata?: Record<string, string>;
+  runtimeEnv?: Record<string, EnvVarInput>;
+  callbackToken?: Uint8Array;
+}
+
+function buildWorkflowExecutionProto(input: WorkflowExecutionInput): WorkflowExecution {
+  return Object.assign(create(WorkflowExecutionSchema), {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "WorkflowExecution",
+    metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      name: input.name,
+      org: input.org,
+    }),
+    spec: Object.assign(create(WorkflowExecutionSpecSchema), {
+      workflowInstanceId: input.workflowInstanceId,
+      workflowId: input.workflowId,
+      triggerMessage: input.triggerMessage,
+      triggerMetadata: input.triggerMetadata,
+      runtimeEnv: input.runtimeEnv,
+      callbackToken: input.callbackToken,
+    }),
+  }) as WorkflowExecution;
+}

package/src/gen/workflowinstance.ts

@@ -0,0 +1,91 @@
+// Code generated by stigmer-codegen. DO NOT EDIT.
+
+import { wrapError } from "./errors";
+import { type ResourceRef } from "./types";
+import { create } from "@bufbuild/protobuf";
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { WorkflowInstanceSchema, type WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { WorkflowInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/command_pb";
+import { WorkflowInstanceIdSchema, GetWorkflowInstancesByWorkflowRequestSchema, WorkflowInstanceListSchema, type GetWorkflowInstancesByWorkflowRequest, type WorkflowInstanceList } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/io_pb";
+import { WorkflowInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/query_pb";
+import { WorkflowInstanceSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/spec_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+/** Provides operations on workflowinstance resources. */
+export class WorkflowInstanceClient {
+  private readonly command: Client<typeof WorkflowInstanceCommandController>;
+  private readonly query: Client<typeof WorkflowInstanceQueryController>;
+
+  constructor(transport: Transport) {
+    this.command = createClient(WorkflowInstanceCommandController, transport);
+    this.query = createClient(WorkflowInstanceQueryController, transport);
+  }
+
+  async apply(input: WorkflowInstanceInput): Promise<WorkflowInstance> {
+    try {
+      return await this.command.apply(buildWorkflowInstanceProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async create(input: WorkflowInstanceInput): Promise<WorkflowInstance> {
+    try {
+      return await this.command.create(buildWorkflowInstanceProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async update(input: WorkflowInstanceInput): Promise<WorkflowInstance> {
+    try {
+      return await this.command.update(buildWorkflowInstanceProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async delete(id: string): Promise<WorkflowInstance> {
+    try {
+      return await this.command.delete(create(WorkflowInstanceIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async get(id: string): Promise<WorkflowInstance> {
+    try {
+      return await this.query.get(create(WorkflowInstanceIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async getByWorkflow(input: GetWorkflowInstancesByWorkflowRequest): Promise<WorkflowInstanceList> {
+    try {
+      return await this.query.getByWorkflow(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async getByReference(ref: ResourceRef): Promise<WorkflowInstance> {
+    try {
+      return await this.query.getByReference(create(ApiResourceReferenceSchema, ref));
+    } catch (e) { throw wrapError(e); }
+  }
+}
+
+/** Input for creating/updating a WorkflowInstance. */
+export interface WorkflowInstanceInput {
+  name: string;
+  org: string;
+  workflowId?: string;
+  description?: string;
+  envRefs?: ResourceRef[];
+}
+
+function buildWorkflowInstanceProto(input: WorkflowInstanceInput): WorkflowInstance {
+  return Object.assign(create(WorkflowInstanceSchema), {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "WorkflowInstance",
+    metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      name: input.name,
+      org: input.org,
+    }),
+    spec: Object.assign(create(WorkflowInstanceSpecSchema), {
+      workflowId: input.workflowId,
+      description: input.description,
+      envRefs: input.envRefs,
+    }),
+  }) as WorkflowInstance;
+}

package/src/index.ts

@@ -0,0 +1,124 @@
+// Public API for @stigmer/sdk
+
+// Top-level client
+export { Stigmer } from "./stigmer";
+
+// Configuration
+export { type StigmerConfig, type TokenProvider } from "./config";
+
+// Error handling
+export {
+  StigmerError,
+  type ErrorCode,
+  isNotFound,
+  isUnauthenticated,
+  isPermissionDenied,
+  isRetryable,
+  type ErrorCategory,
+  isConnectError,
+  classifyError,
+  isRetryableError,
+  getUserMessage,
+  type RpcErrorMetadata,
+  annotateRpcError,
+  getRpcMetadata,
+} from "./errors";
+
+// Search client
+export {
+  SearchClient,
+  type SearchParams,
+  type SearchResponse,
+  ApiResourceKind,
+} from "./search";
+
+// Shared types (from generated code)
+export {
+  type DeleteResourceInput,
+  type ResourceRef,
+  type Page,
+  type ListParams,
+  type ListResult,
+  type EnvSpecInput,
+  type EnvVarInput,
+} from "./gen/types";
+
+// Re-export all resource client classes and input 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";
+export {
+  AgentInstanceClient,
+  type AgentInstanceInput,
+} from "./gen/agentinstance";
+export { ApiKeyClient, type ApiKeyInput } from "./gen/apikey";
+export {
+  EnvironmentClient,
+  type EnvironmentInput,
+} from "./gen/environment";
+export {
+  ExecutionContextClient,
+  type ExecutionContextInput,
+} from "./gen/executioncontext";
+export {
+  IamPolicyClient,
+  type IamPolicyInput,
+  type ApiResourceRefInput,
+} from "./gen/iampolicy";
+export {
+  IdentityAccountClient,
+  type IdentityAccountInput,
+} from "./gen/identityaccount";
+export {
+  IdentityProviderClient,
+  type IdentityProviderInput,
+} from "./gen/identityprovider";
+export {
+  McpServerClient,
+  type McpServerInput,
+  type StdioServerConfigInput,
+  type HttpServerConfigInput,
+  type ToolApprovalPolicyInput,
+} from "./gen/mcpserver";
+export {
+  OrganizationClient,
+  type OrganizationInput,
+} from "./gen/organization";
+export { ProjectClient, type ProjectInput } from "./gen/project";
+export {
+  SessionClient,
+  type SessionInput,
+  type WorkspaceEntryInput,
+  type WorkspaceSourceInput,
+  type GitRepoSourceInput,
+  type LocalPathSourceInput,
+} from "./gen/session";
+export { SkillClient, type SkillInput } from "./gen/skill";
+export {
+  WorkflowClient,
+  type WorkflowInput,
+  type WorkflowDocumentInput,
+  type WorkflowTaskInput,
+  type ExportInput,
+  type FlowControlInput,
+} from "./gen/workflow";
+export {
+  WorkflowExecutionClient,
+  type WorkflowExecutionInput,
+} from "./gen/workflowexecution";
+export {
+  WorkflowInstanceClient,
+  type WorkflowInstanceInput,
+} from "./gen/workflowinstance";

package/src/internal/interceptors.ts

@@ -0,0 +1,83 @@
+import { ConnectError, Code, type Interceptor } from "@connectrpc/connect";
+import type { TokenProvider } from "../config";
+import { annotateRpcError } from "../errors";
+
+/**
+ * Create an interceptor that attaches `Authorization: Bearer <token>` to
+ * every outgoing request. Supports both static API keys and dynamic token
+ * providers.
+ */
+export function createAuthInterceptor(
+  getAccessToken: TokenProvider,
+): Interceptor {
+  return (next) => async (request) => {
+    const token = await getAccessToken();
+    if (token) {
+      request.header.set("Authorization", `Bearer ${token}`);
+    }
+    return next(request);
+  };
+}
+
+/**
+ * Interceptor that annotates every error with the RPC method name and
+ * service path that produced it. Must run before error-transforming
+ * interceptors so the raw request context is available.
+ */
+export const rpcMetadataInterceptor: Interceptor =
+  (next) => async (request) => {
+    try {
+      return await next(request);
+    } catch (error: unknown) {
+      if (error !== null && typeof error === "object") {
+        const segments = request.url.split("/");
+        const method = segments.at(-1) ?? "";
+        const service = segments.at(-2) ?? "";
+        annotateRpcError(error, {
+          method: method.charAt(0).toLowerCase() + method.slice(1),
+          path: `/${service}/${method}`,
+        });
+      }
+      throw error;
+    }
+  };
+
+/**
+ * Interceptor that strips gRPC status-code prefixes (e.g., `[internal]`)
+ * from error messages. The structured code remains on `ConnectError.code`.
+ */
+export const errorStripInterceptor: Interceptor = (next) => async (request) => {
+  try {
+    return await next(request);
+  } catch (error: unknown) {
+    if (error instanceof Error && error.message) {
+      error.message = error.message.replace(/^\[.*?]\s*/, "");
+    }
+    throw error;
+  }
+};
+
+/**
+ * Create an interceptor that invokes a callback on UNAUTHENTICATED (code 16).
+ * The callback fires at most once per client to prevent cascading redirects.
+ */
+export function createAuthRedirectInterceptor(
+  onUnauthenticated: () => void,
+): Interceptor {
+  let fired = false;
+  return (next) => async (request) => {
+    try {
+      return await next(request);
+    } catch (error: unknown) {
+      if (
+        !fired &&
+        error instanceof ConnectError &&
+        error.code === Code.Unauthenticated
+      ) {
+        fired = true;
+        onUnauthenticated();
+      }
+      throw error;
+    }
+  };
+}

package/src/search.ts

@@ -0,0 +1,71 @@
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { SearchService } from "@stigmer/protos/ai/stigmer/search/v1/query_pb";
+import { SearchRequestSchema } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { PageInfoSchema } from "@stigmer/protos/ai/stigmer/commons/rpc/pagination_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { wrapError } from "./gen/errors";
+
+/** Re-export ApiResourceKind for use with SearchClient. */
+export { ApiResourceKind };
+
+/** Parameters for a cross-resource search query. */
+export interface SearchParams {
+  /** Resource kinds to include in the search. */
+  readonly kinds: ApiResourceKind[];
+  /** Organization slug to scope the query. */
+  readonly org: string;
+  /** Free-text search query. */
+  readonly query?: string;
+  /** Whether to exclude public (non-org) resources from results. */
+  readonly excludePublic?: boolean;
+  /** Pagination parameters. */
+  readonly page?: { num: number; size: number };
+}
+
+/** A page of cross-resource search results. */
+export interface SearchResponse {
+  readonly entries: SearchResult[];
+  readonly totalCount: number;
+  readonly totalPages: number;
+}
+
+/**
+ * Cross-resource search client.
+ *
+ * Unlike the per-resource `list()` methods (which search within a single
+ * resource kind), `SearchClient.query()` searches across multiple resource
+ * kinds in a single call.
+ */
+export class SearchClient {
+  private readonly search: Client<typeof SearchService>;
+
+  constructor(transport: Transport) {
+    this.search = createClient(SearchService, transport);
+  }
+
+  /** Perform a cross-resource search. */
+  async query(params: SearchParams): Promise<SearchResponse> {
+    try {
+      const resp = await this.search.search(
+        create(SearchRequestSchema, {
+          kinds: params.kinds,
+          query: params.query,
+          org: params.org,
+          excludePublic: params.excludePublic ?? false,
+          page: params.page
+            ? create(PageInfoSchema, params.page)
+            : undefined,
+        }),
+      );
+      return {
+        entries: resp.entries,
+        totalCount: resp.totalCount,
+        totalPages: resp.totalPages,
+      };
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+}