@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/roles.d.ts

@@ -0,0 +1,431 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.roles` (Roles): 20 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_role_roles_post">;
+ *
+ * Reference with examples: roles.md
+ */
+/* eslint-disable */
+
+/** `g8.api.roles.<member>` -> the operationId it calls. */
+export interface RolesMembers {
+  createRole: "create_role_roles_post";
+  deleteRole: "delete_role_roles__role_id__delete";
+  deleteServiceProviderAssignments: "delete_service_provider_assignments_roles_service_provider_assignments__email__delete";
+  getDomainSettings: "get_domain_settings_roles_domain_settings_get";
+  getJoinRequestCount: "get_join_request_count_roles_join_requests_count_get";
+  getMyPermissions: "get_my_permissions_roles_me_permissions_get";
+  getRole: "get_role_roles__role_id__get";
+  getUserRole: "get_user_role_roles_users__user_id__get";
+  listJoinRequests: "list_join_requests_roles_join_requests_get";
+  listOrgUsers: "list_org_users_roles_org_users_get";
+  listPendingInvites: "list_pending_invites_roles_pending_invites_get";
+  listPermissions: "list_permissions_roles_permissions_get";
+  listPermissionsGrouped: "list_permissions_grouped_roles_permissions_grouped_get";
+  listRoleOptions: "list_role_options_roles_options_get";
+  listRoles: "list_roles_roles_get";
+  listServiceProviderAssignments: "list_service_provider_assignments_roles_service_provider_assignments_get";
+  listServiceProviderAvailableLists: "list_service_provider_available_lists_roles_service_provider_available_lists_get";
+  rejectJoinRequest: "reject_join_request_roles_join_requests__request_id__reject_post";
+  revokePendingInvite: "revoke_pending_invite_roles_pending_invites__email__delete";
+  updateRole: "update_role_roles__role_id__put";
+}
+
+/** Input and output of every `g8.api.roles` operation, keyed by operationId. */
+export interface RolesOperations {
+  /**
+   * POST /roles
+   * Create Role
+   * tier: write · scope: account:write
+   */
+  create_role_roles_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RoleCreateRequest;
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * DELETE /roles/{role_id}
+   * Delete Role
+   * tier: destructive · scope: account:delete
+   */
+  delete_role_roles__role_id__delete: {
+    input: {
+    path: {
+      /** Role id (UUID). */
+      role_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * DELETE /roles/service-provider/assignments/{email}
+   * Delete Service Provider Assignments
+   * tier: destructive · scope: account:delete
+   */
+  delete_service_provider_assignments_roles_service_provider_assignments__email__delete: {
+    input: {
+    path: {
+      /** The service provider's email address. */
+      email: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * GET /roles/domain-settings
+   * Get Domain Settings
+   * tier: read · scope: account:read
+   */
+  get_domain_settings_roles_domain_settings_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * GET /roles/join-requests/count
+   * Get Join Request Count
+   * tier: read · scope: account:read
+   */
+  get_join_request_count_roles_join_requests_count_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * GET /roles/me/permissions
+   * Get My Permissions
+   * tier: read · scope: account:read
+   */
+  get_my_permissions_roles_me_permissions_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * GET /roles/{role_id}
+   * Get Role
+   * tier: read · scope: account:read
+   */
+  get_role_roles__role_id__get: {
+    input: {
+    path: {
+      /** Role id (UUID). */
+      role_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * GET /roles/users/{user_id}
+   * Get User Role
+   * tier: read · scope: account:read
+   */
+  get_user_role_roles_users__user_id__get: {
+    input: {
+    path: {
+      /** Identity-provider user id. */
+      user_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * GET /roles/join-requests
+   * List Join Requests
+   * tier: read · scope: account:read
+   */
+  list_join_requests_roles_join_requests_get: {
+    input: {
+    query?: {
+      /** Queue state to list: `pending`, `approved` or `rejected`. */
+      status?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgListPayload_;
+  };
+  /**
+   * GET /roles/org-users
+   * List Org Users
+   * tier: read · scope: account:read
+   */
+  list_org_users_roles_org_users_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgListPayload_;
+  };
+  /**
+   * GET /roles/pending-invites
+   * List Pending Invites
+   * tier: read · scope: account:read
+   */
+  list_pending_invites_roles_pending_invites_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgListPayload_;
+  };
+  /**
+   * GET /roles/permissions
+   * List Permissions
+   * tier: read · scope: account:read
+   */
+  list_permissions_roles_permissions_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgListPayload_;
+  };
+  /**
+   * GET /roles/permissions/grouped
+   * List Permissions Grouped
+   * tier: read · scope: account:read
+   */
+  list_permissions_grouped_roles_permissions_grouped_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * GET /roles/options
+   * List Role Options
+   * tier: read · scope: account:read
+   */
+  list_role_options_roles_options_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgListPayload_;
+  };
+  /**
+   * GET /roles
+   * List Roles
+   * tier: read · scope: account:read
+   */
+  list_roles_roles_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgListPayload_;
+  };
+  /**
+   * GET /roles/service-provider/assignments
+   * List Service Provider Assignments
+   * tier: read · scope: account:read
+   */
+  list_service_provider_assignments_roles_service_provider_assignments_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgListPayload_;
+  };
+  /**
+   * GET /roles/service-provider/available-lists
+   * List Service Provider Available Lists
+   * tier: read · scope: account:read
+   */
+  list_service_provider_available_lists_roles_service_provider_available_lists_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgListPayload_;
+  };
+  /**
+   * POST /roles/join-requests/{request_id}/reject
+   * Reject Join Request
+   * tier: write · scope: account:write
+   */
+  reject_join_request_roles_join_requests__request_id__reject_post: {
+    input: {
+    path: {
+      /** Join request id (UUID). */
+      request_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * DELETE /roles/pending-invites/{email}
+   * Revoke Pending Invite
+   * tier: destructive · scope: account:delete
+   */
+  revoke_pending_invite_roles_pending_invites__email__delete: {
+    input: {
+    path: {
+      /** Email address the invitation was sent to. */
+      email: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+  /**
+   * PUT /roles/{role_id}
+   * Update Role
+   * tier: destructive · scope: account:delete
+   */
+  update_role_roles__role_id__put: {
+    input: {
+    path: {
+      /** Role id (UUID). */
+      role_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RoleUpdateRequest;
+  };
+    output: ApiResponse_OrgPayload_;
+  };
+}
+
+// 8 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_OrgListPayload_ {
+  data: OrgListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_OrgPayload_ {
+  data: OrgPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * An open envelope for a LIST result, so a bare list keeps its shape.
+ *
+ * Most of these handlers return a bare `list[...]`; a few return a named
+ * envelope (`{"team_members": [...], "total": n}`). Both are reachable as
+ * `items`, and a named envelope KEEPS its own key as well so a caller
+ * already reading the app's shape is not broken by the wrapper.
+ */
+export interface OrgListPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope for a single role, team, member or account record.
+ *
+ * Open on purpose. The app's own response models on this surface grow with
+ * the product - `RoleResponse` gained `rep_limits` and `manages_role_slugs`,
+ * `TeamResponse` gained channel counts and a campaign count - and a pinned
+ * mirror would SILENTLY DROP whatever it had not caught up on. A dropped
+ * permission in a role read is the worst possible kind of stale: it reads as
+ * "they do not have it".
+ */
+export type OrgPayload = Record<string, unknown>;
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/**
+ * Per-role reveal/ownership limits. Mirrors `roles.RepLimitsSettings`.
+ *
+ * The three `Literal`s are closed here rather than left as strings because
+ * they reach the app's own `Literal` inside `_apply_rep_limits`.
+ */
+export interface RepLimitsSettings {
+  conflict_company_owned?: "allow" | "warn" | "block";
+  conflict_contact_active?: "allow" | "warn" | "block";
+  max_companies?: number | null;
+  max_contacts?: number | null;
+  reveal_monthly_credit_budget?: number | null;
+  reveal_policy?: "within_limits" | "monthly_credit_budget" | "no_limit";
+}
+
+/**
+ * Define a new role. Mirrors `roles.RoleCreateRequest`.
+ *
+ * `permissions` is bounded by the app's own non-escalation guard
+ * (`_assert_can_grant_permissions`): a caller may not mint a role granting a
+ * permission they do not themselves hold. That guard runs INSIDE the handler
+ * and is deliberately not duplicated here - see the router docstring.
+ */
+export interface RoleCreateRequest {
+  description?: string | null;
+  manages_role_slugs?: Array<string> | null;
+  name: string;
+  permissions?: Array<string>;
+  rep_limits?: RepLimitsSettings | null;
+  slug: string;
+}
+
+/**
+ * Replace a role's definition. Mirrors `roles.RoleUpdateRequest`.
+ *
+ * `permissions` is a REPLACEMENT, not a merge, and it takes effect for
+ * everyone who already holds the role. That is why the operation is tiered
+ * `destructive` rather than `write`.
+ */
+export interface RoleUpdateRequest {
+  description?: string | null;
+  manages_role_slugs?: Array<string> | null;
+  name?: string | null;
+  permissions?: Array<string> | null;
+  rep_limits?: RepLimitsSettings | null;
+}