@stigmer/sdk 3.25.0 → 3.27.0

package/src/gen/team.ts

@@ -0,0 +1,132 @@
+// Code generated by stigmer-codegen. DO NOT EDIT.
+
+import { wrapError } from "./errors.js";
+import { stripUndefined } from "./proto-utils.js";
+import { type DeleteResourceInput, type ResourceRef } from "./types.js";
+import { create } from "@bufbuild/protobuf";
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceIdSchema, ApiResourceReferenceSchema, ApiResourceDeleteInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { TeamSchema, type Team } from "@stigmer/protos/ai/stigmer/iam/team/v1/api_pb";
+import { TeamCommandController } from "@stigmer/protos/ai/stigmer/iam/team/v1/command_pb";
+import { ListTeamsByOrgInputSchema, TeamsSchema, type ListTeamsByOrgInput, type Teams } from "@stigmer/protos/ai/stigmer/iam/team/v1/io_pb";
+import { TeamQueryController } from "@stigmer/protos/ai/stigmer/iam/team/v1/query_pb";
+import { TeamSpecSchema } from "@stigmer/protos/ai/stigmer/iam/team/v1/spec_pb";
+
+/** Provides operations on team resources. */
+export class TeamClient {
+  private readonly command: Client<typeof TeamCommandController>;
+  private readonly query: Client<typeof TeamQueryController>;
+
+  constructor(transport: Transport) {
+    this.command = createClient(TeamCommandController, transport);
+    this.query = createClient(TeamQueryController, transport);
+  }
+
+  async create(input: TeamInput): Promise<Team> {
+    try {
+      return await this.command.create(buildTeamProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async update(input: TeamInput): Promise<Team> {
+    try {
+      return await this.command.update(buildTeamProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async delete(input: DeleteResourceInput): Promise<Team> {
+    try {
+      return await this.command.delete(create(ApiResourceDeleteInputSchema, {
+        resourceId: input.resourceId,
+        versionMessage: input.versionMessage,
+        force: input.force,
+      }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async get(id: string): Promise<Team> {
+    try {
+      return await this.query.get(create(ApiResourceIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async getByReference(ref: ResourceRef): Promise<Team> {
+    try {
+      return await this.query.getByReference(create(ApiResourceReferenceSchema, { ...ref, kind: ApiResourceKind.team }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async listByOrg(input: ListTeamsByOrgInput): Promise<Teams> {
+    try {
+      return await this.query.listByOrg(input);
+    } catch (e) { throw wrapError(e); }
+  }
+}
+
+/** Input for creating/updating a Team. */
+export interface TeamInput {
+  /**
+   * The resource's `metadata.id`, for exact update addressing when set
+   * from a loaded resource. Required for updates to platform-scoped
+   * (org-less) kinds, where the org+slug fallback cannot match. On
+   * create, the cloud server stamps its own id regardless; the OSS
+   * server honors a caller-supplied id (existing apply semantics).
+   */
+  id?: string;
+  name: string;
+  slug?: string;
+  org: string;
+  labels?: Record<string, string>;
+  visibility?: ApiResourceVisibility;
+  description?: string;
+}
+
+export function buildTeamProto(input: TeamInput): Team {
+  return Object.assign(create(TeamSchema), {
+    apiVersion: "iam.stigmer.ai/v1",
+    kind: "Team",
+    metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      ...(input.id && { id: input.id }),
+      name: input.name,
+      org: input.org,
+      ...(input.slug && { slug: input.slug }),
+      ...(input.labels && { labels: input.labels }),
+      ...(input.visibility && { visibility: input.visibility }),
+    }),
+    spec: Object.assign(create(TeamSpecSchema), stripUndefined({
+      description: input.description,
+    })),
+  }) as Team;
+}
+
+/**
+ * Maps a fetched {@link Team} to a complete {@link TeamInput} for `update()`.
+ *
+ * The update RPC replaces the ENTIRE spec — spread this mapper's output
+ * and override only the fields you edit (spread nested objects the same
+ * way):
+ *
+ *   await client.update({ ...toTeamUpdateInput(res), description: next });
+ *
+ * Proto3 defaults normalize to `undefined`; resource references keep
+ * `version` (pinned refs) and `kind`.
+ */
+export function toTeamUpdateInput(resource: Team): TeamInput {
+  const meta = resource.metadata;
+  const spec = resource.spec ?? create(TeamSpecSchema);
+  return {
+    // Exact update addressing (id-first in the update pipeline) — for
+    // platform-scoped (org-less) kinds the org+slug fallback cannot
+    // match, so the id is the ONLY working address.
+    id: meta?.id || undefined,
+    name: meta?.name ?? "",
+    slug: meta?.slug || undefined,
+    org: meta?.org ?? "",
+    labels: meta?.labels && Object.keys(meta.labels).length > 0 ? { ...meta.labels } : undefined,
+    visibility: meta?.visibility || undefined,
+    description: spec.description || undefined,
+  };
+}

package/src/iam-principal.ts

@@ -0,0 +1,92 @@
+/**
+ * Who an IAM policy grants a role to: a person or a team, in one shape a
+ * client builds grants from and reads access lists back into.
+ *
+ * The wire spells a grantee as an `ApiResourceRef`: a person is
+ * `identity_account:<id>` with no relation qualifier, a team is
+ * `team:<id>#member` (every member of the team holds the grant). This
+ * module is the one place in the SDK that knows that spelling, so no caller
+ * writes the qualifier by hand and no caller can drop it.
+ *
+ * Reading goes through the same module: `granteeFromView` turns an access
+ * list entry back into a `Grantee` and answers `undefined` for anything it
+ * does not recognise (another kind, a team with a qualifier other than
+ * `member`), so a client never acts on a principal it would misname. A
+ * revoke built from the returned grantee names the exact row the list
+ * showed, because the server's revoke matches the qualifier exactly.
+ */
+import { create } from "@bufbuild/protobuf";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceRefView } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+import {
+  type ApiResourceRef,
+  ApiResourceRefSchema,
+} from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+
+const PERSON_KIND = ApiResourceKind[ApiResourceKind.identity_account];
+const TEAM_KIND = ApiResourceKind[ApiResourceKind.team];
+
+/** The relation that makes every member of a team the grantee. */
+const TEAM_MEMBERS_RELATION = "member";
+
+/** A person or a team an IAM policy can grant a role to. */
+export type Grantee =
+  | { readonly kind: "identity_account"; readonly id: string }
+  | { readonly kind: "team"; readonly id: string };
+
+/** The kind of a {@link Grantee}. */
+export type GranteeKind = Grantee["kind"];
+
+/** A person, by identity account id (`ida_...`). */
+export function personGrantee(id: string): Grantee {
+  return { kind: "identity_account", id };
+}
+
+/** A team, by team id (`tm_...`). */
+export function teamGrantee(id: string): Grantee {
+  return { kind: "team", id };
+}
+
+/**
+ * The `ApiResourceRef` an IAM policy spec names the grantee with: a person
+ * unqualified, a team as its members.
+ */
+export function granteeRef(grantee: Grantee): ApiResourceRef {
+  switch (grantee.kind) {
+    case "identity_account":
+      return create(ApiResourceRefSchema, { kind: PERSON_KIND, id: grantee.id });
+    case "team":
+      return create(ApiResourceRefSchema, {
+        kind: TEAM_KIND,
+        id: grantee.id,
+        relation: TEAM_MEMBERS_RELATION,
+      });
+    default: {
+      const unreachable: never = grantee;
+      return unreachable;
+    }
+  }
+}
+
+/**
+ * The grantee an access-list entry names, or `undefined` when the entry
+ * is not a person or a team's members (a structural principal, a kind this
+ * SDK does not know, or a team qualifier other than `member`).
+ */
+export function granteeFromView(
+  view: Pick<ApiResourceRefView, "kind" | "id" | "relation">,
+): Grantee | undefined {
+  if (!view.id) return undefined;
+  if (view.kind === PERSON_KIND && view.relation === "") {
+    return personGrantee(view.id);
+  }
+  if (view.kind === TEAM_KIND && view.relation === TEAM_MEMBERS_RELATION) {
+    return teamGrantee(view.id);
+  }
+  return undefined;
+}
+
+/** A stable key for a grantee: its kind and id. */
+export function granteeKey(grantee: Grantee): string {
+  return `${grantee.kind}:${grantee.id}`;
+}

package/src/index.ts

@@ -77,7 +77,19 @@ export {
   getGrantableRoles,
   hasGrantableRoles,
   isRoleGrantable,
+  getTeamGrantableRoles,
+  hasTeamGrantableRoles,
+  isRoleTeamGrantable,
 } from "./authorization-config.js";
+export {
+  type Grantee,
+  type GranteeKind,
+  personGrantee,
+  teamGrantee,
+  granteeRef,
+  granteeFromView,
+  granteeKey,
+} from "./iam-principal.js";
 export {
   iamRoleToString,
   iamRoleFromString,
@@ -244,6 +256,11 @@ export {
   toIdentityProviderUpdateInput,
   type IdentityProviderInput,
 } from "./gen/identityprovider.js";
+export {
+  TeamClient,
+  toTeamUpdateInput,
+  type TeamInput,
+} from "./gen/team.js";
 export {
   OAuthAppClient,
   toOAuthAppUpdateInput,