@instructure/platform-mock-canvas-api 0.6.0 → 0.7.0

package/dist/types/cohorts.d.ts

@@ -0,0 +1,1082 @@
+/**
+ * A global announcement for an account.
+ */
+export interface AccountNotification {
+    id?: Id;
+    /** The subject of the notification. */
+    subject?: string;
+    /** The message to be sent in the notification. */
+    message?: string;
+    /** When to send out the notification. */
+    start_at?: string;
+    /** When to expire the notification. */
+    end_at?: string;
+    /** The icon to display with the message. Defaults to warning. */
+    icon?: AccountNotificationIcon;
+    /**
+     * Role names the notification is sent to. Empty means all roles. Use
+     * `role_ids`.
+     * @deprecated
+     */
+    roles?: string[];
+    /** Roles the notification is sent to. Empty means all roles. */
+    role_ids?: number[];
+    /**
+     * The author of the notification. Available only to admins using
+     * `include_all`.
+     * @nullable
+     */
+    author?: AccountNotificationAuthor;
+    /**
+     * Cohorts the announcement is targeted at. Empty when the
+     * announcement is not cohort-targeted. Added by the cohorts feature.
+     */
+    cohort_ids?: Id[];
+}
+/**
+ * The author of the notification. Available only to admins using
+ * `include_all`.
+ * @nullable
+ */
+export type AccountNotificationAuthor = {
+    id?: Id;
+    name?: string;
+} | null;
+/**
+ * Form body of the create and update global notification operations. The
+ * nested `account_notification[...]` keys are sent flat, exactly as
+ * Canvas documents them.
+ */
+export interface AccountNotificationForm {
+    /** The subject of the notification. */
+    'account_notification[subject]'?: string;
+    /** The message body of the notification. */
+    'account_notification[message]'?: string;
+    /** When to start showing the notification. */
+    'account_notification[start_at]'?: string;
+    /** When to stop showing the notification. */
+    'account_notification[end_at]'?: string;
+    /** The icon to display with the notification. */
+    'account_notification[icon]'?: AccountNotificationFormAccountNotificationIcon;
+    /**
+     * Roles to send the notification to, by role id or role name.
+     * Omitting this sends to everyone.
+     */
+    'account_notification_roles[]'?: string[];
+    /**
+     * Cohorts to send the notification to. Active members of these
+     * cohorts and of every cohort beneath them see it. Added by the
+     * cohorts feature; sending an empty array on update clears cohort
+     * targeting.
+     */
+    'account_notification_cohort_ids[]'?: Id[];
+}
+/**
+ * The icon to display with the notification.
+ */
+export type AccountNotificationFormAccountNotificationIcon = (typeof AccountNotificationFormAccountNotificationIcon)[keyof typeof AccountNotificationFormAccountNotificationIcon];
+export declare const AccountNotificationFormAccountNotificationIcon: {
+    readonly warning: "warning";
+    readonly information: "information";
+    readonly question: "question";
+    readonly error: "error";
+    readonly calendar: "calendar";
+};
+/**
+ * The icon to display with the message. Defaults to warning.
+ */
+export type AccountNotificationIcon = (typeof AccountNotificationIcon)[keyof typeof AccountNotificationIcon];
+export declare const AccountNotificationIcon: {
+    readonly warning: "warning";
+    readonly information: "information";
+    readonly question: "question";
+    readonly error: "error";
+    readonly calendar: "calendar";
+};
+export type AddCohortEnrollmentScopeBody = {
+    scopable_type: AddCohortEnrollmentScopeBodyScopableType;
+    /** Id of the course, account, collection, or program. */
+    scopable_id: string;
+    /**
+     * Optional. Omitting it stores `false`. Any non-boolean
+     * value, including `null` or the string `"true"`, is
+     * rejected with `400`.
+     */
+    applies_to_descendants?: boolean;
+};
+export type AddCohortEnrollmentScopeBodyScopableType = (typeof AddCohortEnrollmentScopeBodyScopableType)[keyof typeof AddCohortEnrollmentScopeBodyScopableType];
+export declare const AddCohortEnrollmentScopeBodyScopableType: {
+    readonly course: "course";
+    readonly account: "account";
+    readonly collection: "collection";
+    readonly program: "program";
+};
+export type AddCohortLeaderBody = {
+    /** Id of an existing user in this root account. */
+    user_id: Id;
+    /**
+     * A role whose base type is `CohortLeader`. Defaults to the
+     * built-in Cohort Leader role.
+     */
+    role_id?: Id;
+};
+export type AddCohortMembersBody = {
+    /**
+     * Ids of existing users to add. At most 500 per request.
+     * @minItems 1
+     * @maxItems 500
+     */
+    user_ids: Id[];
+};
+/**
+ * Outcome of an add-members request. Ids that could not be added are
+ * reported rather than failing the whole request.
+ */
+export interface AddMembersResult {
+    added: CohortMembership[];
+    skipped: AddMembersResultSkippedItem[];
+}
+export type AddMembersResultSkippedItem = {
+    user_id: Id;
+    reason: AddMembersResultSkippedItemReason;
+};
+export type AddMembersResultSkippedItemReason = (typeof AddMembersResultSkippedItemReason)[keyof typeof AddMembersResultSkippedItemReason];
+export declare const AddMembersResultSkippedItemReason: {
+    readonly already_member: "already_member";
+    readonly user_not_found: "user_not_found";
+    readonly user_not_in_root_account: "user_not_in_root_account";
+};
+/**
+ * The request was rejected.
+ */
+export type BadRequestResponse = Error | ValidationError;
+/**
+ * Form body of the Canvas bulk enrolment operation, with the two
+ * cohort parameters added. Identical under either form encoding.
+ */
+export type BulkEnrollmentForm = unknown & {
+    /**
+     * Ids of the users to enrol. Required unless `cohort_ids[]`
+     * is given.
+     */
+    'user_ids[]'?: Id[];
+    /**
+     * Ids of the courses to enrol each user in.
+     * @minItems 1
+     */
+    'course_ids[]': Id[];
+    /**
+     * Enrol each user as a student, teacher, TA, observer, or
+     * designer. When `enrollment_role_id` is given, this must
+     * match that role's base type, and when omitted alongside
+     * `enrollment_role_id` Canvas derives it from that role's base
+     * type instead of applying the default.
+     */
+    enrollment_type?: BulkEnrollmentFormEnrollmentType;
+    /** Custom course-level role to apply to the created enrolments. */
+    enrollment_role_id?: Id;
+    /**
+     * Pre-existing Canvas bulk_enrollment parameter. Canvas accepts it
+     * and ignores it; it has no effect on the enrolment created. Use
+     * `cohort_ids[]` to target cohorts.
+     * @deprecated
+     */
+    cohort?: boolean;
+    /**
+     * Existing Canvas bulk_enrollment parameter controlling
+     * whether each enrolled user is notified.
+     */
+    notify?: boolean;
+    /** Start time applied to every created enrolment. */
+    start_at?: string;
+    /** End time applied to every created enrolment. */
+    end_at?: string;
+    /**
+     * Cohorts whose active members should be enrolled. Added by
+     * the cohorts feature.
+     */
+    'cohort_ids[]'?: Id[];
+    /**
+     * Also enrol the active members of every cohort beneath each
+     * listed cohort. Added by the cohorts feature.
+     */
+    include_descendant_cohorts?: boolean;
+};
+/**
+ * Enrol each user as a student, teacher, TA, observer, or
+ * designer. When `enrollment_role_id` is given, this must
+ * match that role's base type, and when omitted alongside
+ * `enrollment_role_id` Canvas derives it from that role's base
+ * type instead of applying the default.
+ */
+export type BulkEnrollmentFormEnrollmentType = (typeof BulkEnrollmentFormEnrollmentType)[keyof typeof BulkEnrollmentFormEnrollmentType];
+export declare const BulkEnrollmentFormEnrollmentType: {
+    readonly StudentEnrollment: "StudentEnrollment";
+    readonly TeacherEnrollment: "TeacherEnrollment";
+    readonly TaEnrollment: "TaEnrollment";
+    readonly ObserverEnrollment: "ObserverEnrollment";
+    readonly DesignerEnrollment: "DesignerEnrollment";
+};
+/**
+ * A group of people placed in a Canvas account.
+ */
+export interface Cohort {
+    id: Id;
+    /**
+     * Root account at the top of `account_id`'s account hierarchy.
+     * Equal to `account_id` when the cohort is placed in the root
+     * account itself. The same value for every cohort in one
+     * parent/child hierarchy.
+     */
+    root_account_id: Id;
+    /**
+     * Root cohort at the top of this cohort's hierarchy tree: the
+     * ancestor whose own `parent_cohort_id` is null. Equal to `id`
+     * when this cohort is itself a root. A client walks up to the
+     * root structurally by fetching this id, with no dedicated route.
+     */
+    root_cohort_id: Id;
+    /**
+     * The account the cohort is placed in, a root account or a
+     * sub-account.
+     */
+    account_id: Id;
+    /**
+     * Cohort one level above this one. Null only for a root cohort,
+     * the anchor of a hierarchy tree. An account may anchor several
+     * independent root cohorts; see **Account scoping** in the API
+     * description.
+     */
+    parent_cohort_id: Id | null;
+    /**
+     * @minLength 1
+     * @maxLength 255
+     */
+    name: string;
+    /**
+     * Free-text description of the cohort.
+     * @nullable
+     */
+    description?: string | null;
+    /**
+     * Level in the hierarchy. The root cohort is 1.
+     * @minimum 1
+     * @maximum 10
+     */
+    depth: number;
+    workflow_state: WorkflowState;
+    /**
+     * Unique SIS identifier within the root account.
+     * @maxLength 255
+     * @nullable
+     */
+    sis_source_id?: string | null;
+    /** SIS import that last touched this cohort, if any. */
+    sis_batch_id?: Id | null;
+    /**
+     * Fields last changed outside SIS. A subsequent SIS import leaves
+     * these alone unless it explicitly overrides stickiness.
+     */
+    stuck_sis_fields?: string[];
+    created_at: string;
+    updated_at: string;
+    /**
+     * Active members of this cohort. Present with `include[]=member_count`.
+     * @minimum 0
+     */
+    member_count?: number;
+    /**
+     * Active leaders of this cohort. Present with `include[]=leader_count`.
+     * @minimum 0
+     */
+    leader_count?: number;
+    /**
+     * Active cohorts one level below this one. Present with
+     * `include[]=child_count`.
+     * @minimum 0
+     */
+    child_count?: number;
+}
+/**
+ * One course, account, collection, or program an admin has opted into
+ * a cohort's enrollment reach. Purely an allow-list entry: it grants no
+ * enrollment by itself and carries no `workflow_state`.
+ */
+export interface CohortEnrollmentScope {
+    id: Id;
+    cohort_id: Id;
+    /** Kind of resource this scope grants enrollment reach into. */
+    scopable_type: CohortEnrollmentScopeScopableType;
+    /**
+     * Stored per scope row, never per cohort. Always present in the
+     * response.
+     *
+     * Defaults to `false`. This is the opposite of Canvas
+     * `role_overrides.applies_to_descendants`, which defaults to
+     * `true`. A scope created without this field, or from a blank SIS
+     * CSV cell, does not cascade.
+     *
+     * Only meaningful on an `account` scope. On a `course`, `program`,
+     * or `collection` scope it is accepted, stored, and returned, but
+     * has no effect.
+     *
+     * What an `account` scope reaches when this is `true` is not yet
+     * settled: either the sub-accounts beneath that account, or the
+     * cohort's child cohorts. Until this contract names one, a server
+     * stores and returns the value but does not resolve any cascade
+     * from it.
+     */
+    applies_to_descendants: boolean;
+    /**
+     * Id of the course, account, collection, or program. Course and
+     * account ids are Canvas ids; collection and program ids are
+     * Journey ids. Serialised as a string either way, since the two id
+     * spaces don't share a type.
+     */
+    scopable_id: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Kind of resource this scope grants enrollment reach into.
+ */
+export type CohortEnrollmentScopeScopableType = (typeof CohortEnrollmentScopeScopableType)[keyof typeof CohortEnrollmentScopeScopableType];
+export declare const CohortEnrollmentScopeScopableType: {
+    readonly course: "course";
+    readonly account: "account";
+    readonly collection: "collection";
+    readonly program: "program";
+};
+/**
+ * A leader assignment. The rights it grants (managing membership of the
+ * cohort, and no content editing) always reach every cohort beneath the
+ * one the assignment lives on.
+ */
+export interface CohortLeader {
+    /** Id of the assignment itself, used to remove it. */
+    id: Id;
+    /** Cohort this assignment was returned for. */
+    cohort_id: Id;
+    user_id: Id;
+    root_account_id: Id;
+    role_id: Id;
+    role: CohortLeaderRole;
+    /**
+     * Always true. A leader's rights cannot be confined to a single
+     * level of the hierarchy.
+     *
+     * Which cohorts an assignment reaches is resolved live against the
+     * current `parent_cohort_id` chain at request time. An
+     * implementation may instead maintain a cache or closure table of
+     * descendants, but only if it is invalidated within the same
+     * transaction that commits a delete (`deleteCohort`), so no
+     * request can ever observe a stale ancestor chain.
+     */
+    applies_to_descendants: true;
+    /**
+     * True when this assignment lives on an ancestor and was returned
+     * because of `include_inherited`. Remove it from `source_cohort_id`,
+     * not from `cohort_id`.
+     */
+    inherited: boolean;
+    /**
+     * Cohort the assignment actually lives on. Equal to `cohort_id`
+     * unless `inherited` is true.
+     */
+    source_cohort_id: Id;
+    workflow_state: WorkflowState;
+    created_at: string;
+    updated_at: string;
+    user?: UserDisplay;
+}
+export type CohortLeaderRole = {
+    id: Id;
+    label: string;
+    base_role_type: 'CohortLeader';
+};
+/**
+ * One person's place in one cohort.
+ */
+export interface CohortMembership {
+    id: Id;
+    cohort_id: Id;
+    user_id: Id;
+    root_account_id: Id;
+    workflow_state: WorkflowState;
+    sis_batch_id?: Id | null;
+    created_at: string;
+    updated_at: string;
+    /**
+     * When the member was last active in Canvas, as shown in the
+     * members list "Last active" column and sortable via
+     * `sort=last_activity_at`. Null when no activity has been
+     * recorded for the user.
+     * @nullable
+     */
+    last_activity_at?: string | null;
+    /**
+     * True when this member also holds an active leader assignment
+     * on this cohort or on one of its ancestors, so the members list
+     * can badge them as a Leader without a second call. Reflects
+     * leadership that reaches this cohort, not membership.
+     */
+    is_leader?: boolean;
+    /**
+     * The member's role label as shown in the members list "Role"
+     * column. Null when the member has no role to display. This is a
+     * display-only label; a `CohortMembership` carries no permissions
+     * of its own.
+     * @nullable
+     */
+    role?: CohortMembershipRole;
+    /**
+     * Included by default so lists are renderable without a second
+     * call. Its identity fields are present by default; `sis_user_id`
+     * and `login_id` appear only under the permission rules on
+     * `UserDisplay`.
+     */
+    user?: UserDisplay;
+}
+/**
+ * The member's role label as shown in the members list "Role"
+ * column. Null when the member has no role to display. This is a
+ * display-only label; a `CohortMembership` carries no permissions
+ * of its own.
+ * @nullable
+ */
+export type CohortMembershipRole = {
+    id?: Id | null;
+    label: string;
+} | null;
+/**
+ * A cohort and the subtree beneath it.
+ */
+export interface CohortTreeNode {
+    cohort: Cohort;
+    /** Active direct children, newest first, capped at 100 per node. */
+    children: CohortTreeNode[];
+    /**
+     * True when this node has children that the requested `depth` cut
+     * off. Fetch the subtree again from this node to see them.
+     */
+    truncated: boolean;
+    /**
+     * True when this node has more than 100 active direct children and
+     * `children` holds only the first 100. Call `listCohorts` with
+     * `parent_cohort_id` set to this node's cohort id for the complete
+     * set. Independent of `truncated`: either, both, or neither may be
+     * true.
+     */
+    children_truncated: boolean;
+}
+/**
+ * The account notification form with the fields Canvas requires on
+ * create marked required.
+ */
+export type CreateAccountNotificationForm = AccountNotificationForm & {
+    [key: string]: unknown;
+} & Required<Pick<AccountNotificationForm & {
+    [key: string]: unknown;
+}, 'account_notification[subject]' | 'account_notification[message]' | 'account_notification[start_at]' | 'account_notification[end_at]'>>;
+export type CreateCohortBody = {
+    cohort: CreateCohortBodyCohort;
+};
+export type CreateCohortBodyCohort = {
+    /**
+     * Display name of the cohort.
+     * @minLength 1
+     * @maxLength 255
+     */
+    name: string;
+    /** Free-text description of the cohort. */
+    description?: string;
+    /**
+     * Cohort to nest the new cohort under. Null creates a
+     * root cohort instead, with no parent.
+     */
+    parent_cohort_id: Id | null;
+    /**
+     * Unique SIS identifier for the cohort within the root account.
+     * @maxLength 255
+     */
+    sis_source_id?: string;
+};
+/**
+ * One course enrollment, as returned by the Canvas List Enrollments
+ * operation. This contract lists the subset of fields the cohort
+ * Enrollments tab renders; a live Canvas response carries more, and a
+ * client should tolerate additional properties. This is a plain Canvas
+ * enrollment and holds no cohort reference.
+ */
+export interface Enrollment {
+    id: Id;
+    user_id: Id;
+    course_id: Id;
+    course_section_id?: Id;
+    root_account_id: Id;
+    type: EnrollmentType;
+    /** Enrollment role name, a base type or a custom course-level role. */
+    role: string;
+    role_id: Id;
+    enrollment_state: EnrollmentEnrollmentState;
+    created_at: string;
+    updated_at: string;
+    /** @nullable */
+    last_activity_at?: string | null;
+    /**
+     * The enrolled user. Included by default so the tab renders without
+     * a second call, following the Canvas List Enrollments default.
+     */
+    user?: UserDisplay;
+}
+export type EnrollmentEnrollmentState = (typeof EnrollmentEnrollmentState)[keyof typeof EnrollmentEnrollmentState];
+export declare const EnrollmentEnrollmentState: {
+    readonly active: "active";
+    readonly invited: "invited";
+    readonly creation_pending: "creation_pending";
+    readonly deleted: "deleted";
+    readonly rejected: "rejected";
+    readonly completed: "completed";
+    readonly inactive: "inactive";
+};
+export type EnrollmentType = (typeof EnrollmentType)[keyof typeof EnrollmentType];
+export declare const EnrollmentType: {
+    readonly StudentEnrollment: "StudentEnrollment";
+    readonly TeacherEnrollment: "TeacherEnrollment";
+    readonly TaEnrollment: "TaEnrollment";
+    readonly ObserverEnrollment: "ObserverEnrollment";
+    readonly DesignerEnrollment: "DesignerEnrollment";
+};
+/**
+ * The general Canvas error shape. `error_code` is present when the
+ * failure has a machine-readable cause; clients should branch on it
+ * rather than on `message`, which is localised.
+ */
+export interface CohortsApiError {
+    /** @minItems 1 */
+    errors: ErrorErrorsItem[];
+}
+/**
+ * Machine-readable cause of a rejected cohort request.
+ */
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export declare const ErrorCode: {
+    readonly feature_disabled: "feature_disabled";
+    readonly max_depth_exceeded: "max_depth_exceeded";
+    readonly max_cohorts_exceeded: "max_cohorts_exceeded";
+    readonly max_members_exceeded: "max_members_exceeded";
+    readonly cohort_has_children: "cohort_has_children";
+    readonly invalid_role: "invalid_role";
+    readonly too_many_enrollments: "too_many_enrollments";
+    readonly duplicate_scope: "duplicate_scope";
+};
+export type ErrorErrorsItem = {
+    message: string;
+    error_code?: ErrorCode;
+};
+/**
+ * Both grant sources were evaluated for this cohort and neither
+ * conveyed the required permission: no role the caller holds in an
+ * account this cohort is in or any account above it carries it, and no
+ * Leader assignment on this cohort or on one of its ancestors carries
+ * it either. See **Authorization** in the API description for how the
+ * two combine.
+ */
+export type ForbiddenResponse = UnauthorizedError;
+export type GetCohort200 = Cohort & {
+    /**
+     * Present when requested via `include[]=ancestors`.
+     * Ordered root first, excluding the cohort itself.
+     */
+    ancestors?: Cohort[];
+};
+export type GetCohortIncludeItem = (typeof GetCohortIncludeItem)[keyof typeof GetCohortIncludeItem];
+export declare const GetCohortIncludeItem: {
+    readonly member_count: "member_count";
+    readonly leader_count: "leader_count";
+    readonly child_count: "child_count";
+    readonly ancestors: "ancestors";
+};
+export type GetCohortParams = {
+    /**
+     * Extra data to compute for the cohort. `ancestors` adds the chain of
+     * cohorts from the root down to the parent, root first. The
+     * permission is evaluated on the named cohort only; the ancestor
+     * chain is returned on the read reach set out under
+     * **Authorization**.
+     */
+    'include[]'?: GetCohortIncludeItem[];
+};
+export type GetCohortTreeParams = {
+    /**
+     * How many levels of the tree to return, counting the requested
+     * cohort as level 1. `1` returns the cohort with no children.
+     * Defaults to `2`: the cohort and its direct children, so a client
+     * expands one level at a time unless it asks for more. `10` returns
+     * the full hierarchy.
+     * @minimum 1
+     * @maximum 10
+     */
+    depth?: number;
+};
+/**
+ * A Canvas id. Serialised as a JSON string instead when the request
+ * carries `Accept: application/json+canvas-string-ids`, so clients should
+ * accept both an integer and a numeric string here.
+ */
+export type Id = number;
+/**
+ * Extra data to compute for each cohort. Each value costs an extra
+ * aggregate, so ask only for what you display.
+ */
+export type IncludeParameter = IncludeParameterItem[];
+export type IncludeParameterItem = (typeof IncludeParameterItem)[keyof typeof IncludeParameterItem];
+export declare const IncludeParameterItem: {
+    readonly member_count: "member_count";
+    readonly leader_count: "leader_count";
+    readonly child_count: "child_count";
+};
+/**
+ * The error shape the existing Canvas bulk enrolment validation emits
+ * today: one human-readable string, no error code. Only validation
+ * that predates the cohorts feature uses it.
+ */
+export interface LegacyStringError {
+    errors: string;
+}
+export type ListCohortEnrollmentScopesParams = {
+    /**
+     * Restrict to scopes of these kinds. Omitting returns every kind.
+     */
+    'scopable_type[]'?: ListCohortEnrollmentScopesScopableTypeItem[];
+    /**
+     * Field to sort enrollment scopes by. Defaults to `created_at`.
+     */
+    sort?: SortCohortEnrollmentScopesParameter;
+    /**
+     * Direction to sort in, applied to whichever field `sort` names.
+     * Defaults to `desc`. Ties on a non-unique sort field break by id
+     * ascending, so pagination stays stable across pages even when sorting
+     * by a non-unique field like `name` or `workflow_state`.
+     */
+    order?: OrderParameter;
+    /**
+     * Page of results to return. Prefer following the `Link` header.
+     * @minimum 1
+     */
+    page?: PageParameter;
+    /**
+     * Results per page.
+     * @minimum 1
+     * @maximum 100
+     */
+    per_page?: PerPageParameter;
+};
+export type ListCohortEnrollmentScopesScopableTypeItem = (typeof ListCohortEnrollmentScopesScopableTypeItem)[keyof typeof ListCohortEnrollmentScopesScopableTypeItem];
+export declare const ListCohortEnrollmentScopesScopableTypeItem: {
+    readonly course: "course";
+    readonly account: "account";
+    readonly collection: "collection";
+    readonly program: "program";
+};
+export type ListCohortEnrollmentsParams = {
+    /**
+     * Partial, case-insensitive match against the name of the resource.
+     * Shorter than two characters is rejected.
+     * @minLength 2
+     */
+    search_term?: SearchTermParameter;
+    /**
+     * Also list the enrollments of members of cohorts beneath this
+     * one, de-duplicated by user.
+     */
+    include_descendants?: boolean;
+    /**
+     * Enrollment types to return. Omitting returns every type. Matches
+     * the Canvas List Enrollments `type[]` filter.
+     */
+    'type[]'?: ListCohortEnrollmentsTypeItem[];
+    /**
+     * Enrollment states to return. Defaults to `active` and `invited`,
+     * matching the Canvas List Enrollments `state[]` filter.
+     */
+    'state[]'?: ListCohortEnrollmentsStateItem[];
+    /**
+     * Field to sort enrollments by. Defaults to `created_at`. The
+     * `user_name` and `user_sortable_name` values sort on the enrolled
+     * user's `UserDisplay` field, same as members.
+     */
+    sort?: SortCohortEnrollmentsParameter;
+    /**
+     * Direction to sort in, applied to whichever field `sort` names.
+     * Defaults to `desc`. Ties on a non-unique sort field break by id
+     * ascending, so pagination stays stable across pages even when sorting
+     * by a non-unique field like `name` or `workflow_state`.
+     */
+    order?: OrderParameter;
+    /**
+     * Page of results to return. Prefer following the `Link` header.
+     * @minimum 1
+     */
+    page?: PageParameter;
+    /**
+     * Results per page.
+     * @minimum 1
+     * @maximum 100
+     */
+    per_page?: PerPageParameter;
+};
+export type ListCohortEnrollmentsStateItem = (typeof ListCohortEnrollmentsStateItem)[keyof typeof ListCohortEnrollmentsStateItem];
+export declare const ListCohortEnrollmentsStateItem: {
+    readonly active: "active";
+    readonly invited: "invited";
+    readonly creation_pending: "creation_pending";
+    readonly deleted: "deleted";
+    readonly rejected: "rejected";
+    readonly completed: "completed";
+    readonly inactive: "inactive";
+};
+export type ListCohortEnrollmentsTypeItem = (typeof ListCohortEnrollmentsTypeItem)[keyof typeof ListCohortEnrollmentsTypeItem];
+export declare const ListCohortEnrollmentsTypeItem: {
+    readonly StudentEnrollment: "StudentEnrollment";
+    readonly TeacherEnrollment: "TeacherEnrollment";
+    readonly TaEnrollment: "TaEnrollment";
+    readonly ObserverEnrollment: "ObserverEnrollment";
+    readonly DesignerEnrollment: "DesignerEnrollment";
+};
+export type ListCohortLeadersParams = {
+    /**
+     * Also return Leaders assigned to ancestor cohorts. The permission
+     * is evaluated on the named cohort only; the ancestor read reach is
+     * set out under **Authorization**.
+     */
+    include_inherited?: boolean;
+    /**
+     * Field to sort leader assignments by. Defaults to `created_at`. The
+     * `user_name` and `user_sortable_name` values sort on the nested user
+     * record's corresponding `UserDisplay` field, same as members.
+     */
+    sort?: SortCohortLeadersParameter;
+    /**
+     * Direction to sort in, applied to whichever field `sort` names.
+     * Defaults to `desc`. Ties on a non-unique sort field break by id
+     * ascending, so pagination stays stable across pages even when sorting
+     * by a non-unique field like `name` or `workflow_state`.
+     */
+    order?: OrderParameter;
+    /**
+     * Page of results to return. Prefer following the `Link` header.
+     * @minimum 1
+     */
+    page?: PageParameter;
+    /**
+     * Results per page.
+     * @minimum 1
+     * @maximum 100
+     */
+    per_page?: PerPageParameter;
+};
+export type ListCohortMembersParams = {
+    /**
+     * Partial, case-insensitive match against the name of the resource.
+     * Shorter than two characters is rejected.
+     * @minLength 2
+     */
+    search_term?: SearchTermParameter;
+    /**
+     * Also return members of cohorts beneath this one. The permission
+     * is evaluated on the named cohort only; the descendant reach is
+     * set out under **Authorization**.
+     */
+    include_descendants?: boolean;
+    /**
+     * Which lifecycle states to return. Repeatable, matching the Canvas
+     * `workflow_state[]` list filter: `active`, `deleted`, or `all` for
+     * both. Defaults to `active` only.
+     */
+    'workflow_state[]'?: WorkflowStateFilterParameter;
+    /**
+     * Field to sort memberships by. Defaults to `created_at`. The
+     * `user_name` and `user_sortable_name` values sort on the nested
+     * user record's corresponding `UserDisplay` field (`name`,
+     * `sortable_name`). `last_activity_at` sorts on the member's most
+     * recent activity; rows with no recorded activity sort last
+     * regardless of `order`.
+     */
+    sort?: SortCohortMembersParameter;
+    /**
+     * Direction to sort in, applied to whichever field `sort` names.
+     * Defaults to `desc`. Ties on a non-unique sort field break by id
+     * ascending, so pagination stays stable across pages even when sorting
+     * by a non-unique field like `name` or `workflow_state`.
+     */
+    order?: OrderParameter;
+    /**
+     * Page of results to return. Prefer following the `Link` header.
+     * @minimum 1
+     */
+    page?: PageParameter;
+    /**
+     * Results per page.
+     * @minimum 1
+     * @maximum 100
+     */
+    per_page?: PerPageParameter;
+};
+export type ListCohortsParams = {
+    /**
+     * Partial, case-insensitive match against the name of the resource.
+     * Shorter than two characters is rejected.
+     * @minLength 2
+     */
+    search_term?: SearchTermParameter;
+    /**
+     * Return only the direct children of this cohort.
+     */
+    parent_cohort_id?: Id;
+    /**
+     * Return only the parentless cohorts placed in this account.
+     * Mutually exclusive with `parent_cohort_id`.
+     */
+    roots?: boolean;
+    /**
+     * Which lifecycle states to return. Repeatable, matching the Canvas
+     * `workflow_state[]` list filter: `active`, `deleted`, or `all` for
+     * both. Defaults to `active` only.
+     */
+    'workflow_state[]'?: WorkflowStateFilterParameter;
+    /**
+     * Extra data to compute for each cohort. Each value costs an extra
+     * aggregate, so ask only for what you display.
+     */
+    'include[]'?: IncludeParameter;
+    /**
+     * Field to sort cohorts by. Defaults to `created_at`. The computed
+     * counts gated behind `include[]` (`member_count`, `leader_count`,
+     * `child_count`) are not sortable, since they're only populated when
+     * explicitly requested.
+     */
+    sort?: SortCohortsParameter;
+    /**
+     * Direction to sort in, applied to whichever field `sort` names.
+     * Defaults to `desc`. Ties on a non-unique sort field break by id
+     * ascending, so pagination stays stable across pages even when sorting
+     * by a non-unique field like `name` or `workflow_state`.
+     */
+    order?: OrderParameter;
+    /**
+     * Page of results to return. Prefer following the `Link` header.
+     * @minimum 1
+     */
+    page?: PageParameter;
+    /**
+     * Results per page.
+     * @minimum 1
+     * @maximum 100
+     */
+    per_page?: PerPageParameter;
+};
+/**
+ * Nothing here for this caller. One response covers several causes on
+ * purpose, so that the API never reveals whether a cohort exists: the
+ * resource does not exist, the caller may not view it at all, the
+ * `institutional_cohorts` flag is off for this root account, or the
+ * account or cohort belongs to a different root account than the
+ * caller. A soft-deleted cohort still exists and remains addressable
+ * by id; it is not a `404`.
+ */
+export type NotFoundResponse = Error;
+export type OrderParameter = (typeof OrderParameter)[keyof typeof OrderParameter];
+export declare const OrderParameter: {
+    readonly asc: "asc";
+    readonly desc: "desc";
+};
+/**
+ * Page of results to return. Prefer following the `Link` header.
+ */
+export type PageParameter = number;
+/**
+ * Results per page.
+ */
+export type PerPageParameter = number;
+/**
+ * Progress of an asynchronous Canvas job. Poll `url` until
+ * `workflow_state` is `completed` or `failed`.
+ */
+export interface Progress {
+    /** The id of the Progress object. */
+    id?: number;
+    /** The context owning the job. */
+    context_id?: number;
+    context_type?: string;
+    /** The id of the user who started the job. */
+    user_id?: number;
+    /** The type of operation. */
+    tag?: string;
+    /** Percent completed. */
+    completion?: number;
+    workflow_state?: ProgressWorkflowState;
+    created_at?: string;
+    updated_at?: string;
+    /**
+     * Optional details about the job.
+     * @nullable
+     */
+    message?: string | null;
+    /**
+     * Optional results of the job. Omitted while the job is still pending.
+     * @nullable
+     */
+    results?: ProgressResults;
+    /** Url where a progress update can be retrieved. */
+    url?: string;
+}
+/**
+ * Optional results of the job. Omitted while the job is still pending.
+ * @nullable
+ */
+export type ProgressResults = {
+    [key: string]: unknown;
+} | null;
+export type ProgressWorkflowState = (typeof ProgressWorkflowState)[keyof typeof ProgressWorkflowState];
+export declare const ProgressWorkflowState: {
+    readonly queued: "queued";
+    readonly running: "running";
+    readonly completed: "completed";
+    readonly failed: "failed";
+};
+/**
+ * Partial, case-insensitive match against the name of the resource.
+ * Shorter than two characters is rejected.
+ */
+export type SearchTermParameter = string;
+export type SortCohortEnrollmentScopesParameter = (typeof SortCohortEnrollmentScopesParameter)[keyof typeof SortCohortEnrollmentScopesParameter];
+export declare const SortCohortEnrollmentScopesParameter: {
+    readonly created_at: "created_at";
+    readonly scopable_type: "scopable_type";
+};
+export type SortCohortEnrollmentsParameter = (typeof SortCohortEnrollmentsParameter)[keyof typeof SortCohortEnrollmentsParameter];
+export declare const SortCohortEnrollmentsParameter: {
+    readonly created_at: "created_at";
+    readonly user_name: "user_name";
+    readonly user_sortable_name: "user_sortable_name";
+};
+export type SortCohortLeadersParameter = (typeof SortCohortLeadersParameter)[keyof typeof SortCohortLeadersParameter];
+export declare const SortCohortLeadersParameter: {
+    readonly created_at: "created_at";
+    readonly role_id: "role_id";
+    readonly user_name: "user_name";
+    readonly user_sortable_name: "user_sortable_name";
+};
+export type SortCohortMembersParameter = (typeof SortCohortMembersParameter)[keyof typeof SortCohortMembersParameter];
+export declare const SortCohortMembersParameter: {
+    readonly created_at: "created_at";
+    readonly user_name: "user_name";
+    readonly user_sortable_name: "user_sortable_name";
+    readonly last_activity_at: "last_activity_at";
+};
+export type SortCohortsParameter = (typeof SortCohortsParameter)[keyof typeof SortCohortsParameter];
+export declare const SortCohortsParameter: {
+    readonly created_at: "created_at";
+    readonly name: "name";
+    readonly workflow_state: "workflow_state";
+    readonly depth: "depth";
+};
+/**
+ * The shape Canvas returns when a caller lacks a required permission.
+ */
+export interface UnauthorizedError {
+    status: 'unauthorized';
+    errors: UnauthorizedErrorErrorsItem[];
+}
+export type UnauthorizedErrorErrorsItem = {
+    message: string;
+};
+export type UpdateCohortBody = {
+    cohort: UpdateCohortBodyCohort;
+    /** Allow this request to change fields marked sticky by SIS. */
+    override_sis_stickiness?: boolean;
+};
+export type UpdateCohortBodyCohort = {
+    /**
+     * @minLength 1
+     * @maxLength 255
+     */
+    name?: string;
+    /** Free-text description of the cohort. */
+    description?: string;
+    /** @maxLength 255 */
+    sis_source_id?: string;
+};
+export type UpdateCohortLeaderBody = {
+    /**
+     * A role whose base type is `CohortLeader`. Required: an
+     * update names the role to move to explicitly.
+     */
+    role_id: Id;
+};
+/**
+ * The subset of a Canvas user shown alongside cohort records.
+ */
+export interface UserDisplay {
+    id: Id;
+    name: string;
+    sortable_name?: string;
+    short_name?: string;
+    avatar_url?: string;
+    /**
+     * Present only when the caller holds `read_sis` on the cohort's
+     * account chain, or `manage_sis` on the root account. Omitted
+     * entirely when the caller may not read SIS ids; `null` when the
+     * caller may read them but the user has no SIS id. A Leader grant
+     * never conveys this; it takes an account permission.
+     * @nullable
+     */
+    sis_user_id?: string | null;
+    /**
+     * Present only when the caller holds `view_user_logins` on the
+     * cohort's account chain. Omitted entirely when the caller may not
+     * read login ids; `null` when the caller may read them but the user
+     * has no login. A Leader grant never conveys this; it takes an
+     * account permission.
+     * @nullable
+     */
+    login_id?: string | null;
+}
+/**
+ * Per-attribute validation failures, in the shape Canvas produces from
+ * model errors. Keys are attribute names.
+ */
+export interface ValidationError {
+    errors: ValidationErrorErrors;
+}
+export type ValidationErrorErrors = {
+    [key: string]: ValidationErrorErrorsItem[];
+};
+export type ValidationErrorErrorsItem = {
+    attribute: string;
+    type: string;
+    message: string;
+};
+/**
+ * Lifecycle state. Cohort records are never hard-deleted; they move to
+ * `deleted` and stop appearing in default listings.
+ */
+export type WorkflowState = (typeof WorkflowState)[keyof typeof WorkflowState];
+export declare const WorkflowState: {
+    readonly active: "active";
+    readonly deleted: "deleted";
+};
+/**
+ * Which lifecycle states to return. Repeatable, matching the Canvas
+ * `workflow_state[]` list filter: `active`, `deleted`, or `all` for
+ * both. Defaults to `active` only.
+ */
+export type WorkflowStateFilterParameter = WorkflowStateFilterParameterItem[];
+export type WorkflowStateFilterParameterItem = (typeof WorkflowStateFilterParameterItem)[keyof typeof WorkflowStateFilterParameterItem];
+export declare const WorkflowStateFilterParameterItem: {
+    readonly active: "active";
+    readonly deleted: "deleted";
+    readonly all: "all";
+};
+//# sourceMappingURL=cohorts.d.ts.map