canvas

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package canvas defines domain types shared across all canvas-cli packages.

Index

Examples

Constants

View Source 
const SchemaVersion = "2026-07-25"

SchemaVersion is the current JSON output contract version.

Variables

This section is empty.

Functions

func ArchiveConversation 

func ArchiveConversation(ctx context.Context, client *Client, conversationID string) error

ArchiveConversation archives a conversation by setting its workflow_state to "archived".

func DownloadExport 

func DownloadExport(ctx context.Context, client *Client, attachmentURL string, w io.Writer) error

DownloadExport downloads an export file from an attachment URL.

func DownloadFile 

func DownloadFile(ctx context.Context, client *Client, fileID string, w io.Writer) error

DownloadFile downloads a file by its ID into the provided writer. It first fetches the file metadata from GET /api/v1/files/{fileID} to obtain the download URL, then streams the file content into w.

func Get 

func Get[T any](ctx context.Context, client *Client, path string) (T, error)

Get fetches a single item from the Canvas API. It wraps Request without pagination and decodes the response into T.

func IsCookieSessionExpired added in v0.3.0 

func IsCookieSessionExpired(resp *http.Response, bodyBytes []byte, baseURL string) bool

IsCookieSessionExpired checks whether an HTTP response indicates that the cookie session has expired and the user needs to re-authenticate.

func ListAnnouncements 

func ListAnnouncements(ctx context.Context, client *Client, courseID string, query url.Values) ([]DiscussionTopic, PaginationMeta, error)

ListAnnouncements returns all announcements for a course. It sends GET /api/v1/announcements with context_codes[]=course_{courseID}. The per_page parameter defaults to 100.

func ListAssignments 

func ListAssignments(ctx context.Context, client *Client, courseID string, query url.Values) ([]Assignment, PaginationMeta, error)

ListAssignments returns all assignments for a course. It sends GET /api/v1/courses/{courseID}/assignments.

func ListContentExports 

func ListContentExports(ctx context.Context, client *Client, courseID string) ([]ContentExport, PaginationMeta, error)

ListContentExports returns all content exports for a course.

func ListConversations 

func ListConversations(ctx context.Context, client *Client, opts *RequestOptions) ([]Conversation, PaginationMeta, error)

ListConversations returns all conversations for the authenticated user.

func ListCourses 

func ListCourses(ctx context.Context, client *Client, query url.Values) ([]Course, PaginationMeta, error)

ListCourses returns all courses for the authenticated user. It sends GET /api/v1/courses with the given query parameters. The per_page parameter defaults to 100.

func ListDiscussionEntries 

func ListDiscussionEntries(ctx context.Context, client *Client, courseID, discussionID string, query url.Values) ([]DiscussionEntry, PaginationMeta, error)

ListDiscussionEntries returns all entries (replies) for a discussion topic.

func ListDiscussions 

func ListDiscussions(ctx context.Context, client *Client, courseID string, query url.Values) ([]DiscussionTopic, PaginationMeta, error)

ListDiscussions returns all discussion topics for a course.

func ListEnrollments 

func ListEnrollments(ctx context.Context, client *Client, courseID string, opts *RequestOptions) ([]Enrollment, PaginationMeta, error)

ListEnrollments returns all enrollments for a course. It sends GET /api/v1/courses/{courseID}/enrollments with include[]=total_scores. The opts parameter controls additional query parameters, pagination limit, and page size.

func ListEpubExports 

func ListEpubExports(ctx context.Context, client *Client) ([]CourseEpubExport, PaginationMeta, error)

ListEpubExports returns all courses with their latest ePub export status.

func ListFiles 

func ListFiles(ctx context.Context, client *Client, courseID string, query url.Values) ([]File, PaginationMeta, error)

ListFiles returns all files for a course. It sends GET /api/v1/courses/{courseID}/files with the given query parameters. The per_page parameter defaults to 100.

func ListModuleItems 

func ListModuleItems(ctx context.Context, client *Client, courseID, moduleID string, query url.Values) ([]ModuleItem, PaginationMeta, error)

ListModuleItems returns all items within a module. It sends GET /api/v1/courses/{courseID}/modules/{moduleID}/items.

func ListModules 

func ListModules(ctx context.Context, client *Client, courseID string, query url.Values) ([]Module, PaginationMeta, error)

ListModules returns all modules for a course. It sends GET /api/v1/courses/{courseID}/modules.

func ListPages 

func ListPages(ctx context.Context, client *Client, courseID string, query url.Values) ([]Page, PaginationMeta, error)

ListPages returns all pages for a course. It sends GET /api/v1/courses/{courseID}/pages. The per_page parameter defaults to 100.

func ListSubmissions 

func ListSubmissions(ctx context.Context, client *Client, courseID, assignmentID string, opts *RequestOptions) ([]Submission, PaginationMeta, error)

ListSubmissions returns all submissions for an assignment in a course. It sends GET /api/v1/courses/{courseID}/assignments/{assignmentID}/submissions with include[]=user. The opts parameter controls additional query parameters, pagination limit, and page size.

func ListUsers 

func ListUsers(ctx context.Context, client *Client, courseID string, opts *RequestOptions) ([]User, PaginationMeta, error)

ListUsers returns all users in a course filtered by enrollment type. It sends GET /api/v1/courses/{courseID}/users with enrollment_type[]=student. The opts parameter controls additional query parameters, pagination limit, and page size.

func ParseLinkHeader 

func ParseLinkHeader(header string) map[string]string

ParseLinkHeader extracts rel=URL pairs from a Canvas Link header. It parses the standard RFC 5988 format: <URL>; rel="next", <URL>; rel="prev" Keys are normalized to lowercase.

Example 
header := `<https://school.instructure.com/api/v1/courses?page=2>; rel="next", <https://school.instructure.com/api/v1/courses?page=1>; rel="prev"`
links := ParseLinkHeader(header)
fmt.Println(links["next"])
fmt.Println(links["prev"])

Output:
https://school.instructure.com/api/v1/courses?page=2
https://school.instructure.com/api/v1/courses?page=1

func ShouldRetry 

func ShouldRetry(resp *http.Response, attempt, maxRetries int) (bool, time.Duration)

ShouldRetry determines if a request should be retried and calculates the backoff delay. It returns true if the response indicates a retryable condition and the attempt count hasn't exceeded maxRetries.

func UploadFile 

func UploadFile(ctx context.Context, client *Client, courseID, filePath string, content []byte) (string, error)

UploadFile uploads a file to a Canvas course using the 3-step flow: 1. POST /api/v1/courses/{courseID}/files to notify Canvas (name, size, content_type). 2. POST to the returned upload_url with upload_params + file content (multipart). 3. Handle 201 (file JSON in body) or follow 3xx redirect for the final file info. Returns the file ID on success.

func WaitForExport 

func WaitForExport(ctx context.Context, client *Client, progressURL string, pollInterval time.Duration) error

WaitForExport polls a progress URL until completion or failure.

Types

type ActivityItem 

type ActivityItem struct {
	ID        string `json:"id"`
	Title     string `json:"title"`
	Message   string `json:"message,omitempty"`
	Type      string `json:"type"`
	ReadState string `json:"read_state,omitempty"`
	CreatedAt string `json:"created_at"`
	HTMLURL   string `json:"html_url,omitempty"`
}

ActivityItem represents an item in the user's activity stream.

func GetActivityStream 

func GetActivityStream(ctx context.Context, client *Client) ([]ActivityItem, error)

GetActivityStream returns the user's activity stream.

type Assignment 

type Assignment struct {
	ID                      string   `json:"id"`
	CourseID                string   `json:"course_id"`
	Name                    string   `json:"name"`
	DescriptionHTML         string   `json:"description_html,omitempty"`
	DueAt                   *string  `json:"due_at"`
	UnlockAt                *string  `json:"unlock_at"`
	LockAt                  *string  `json:"lock_at"`
	Published               bool     `json:"published"`
	PointsPossible          float64  `json:"points_possible"`
	SubmissionTypes         []string `json:"submission_types"`
	HasSubmittedSubmissions bool     `json:"has_submitted_submissions"`
}

Assignment represents a Canvas assignment.

func GetAssignment 

func GetAssignment(ctx context.Context, client *Client, courseID, assignmentID string) (Assignment, error)

GetAssignment returns a single assignment by ID. It sends GET /api/v1/courses/{courseID}/assignments/{assignmentID}.

func UpdateAssignment 

func UpdateAssignment(ctx context.Context, client *Client, courseID, assignmentID string, updates map[string]any) (Assignment, error)

UpdateAssignment updates an assignment with the given fields. It sends PUT /api/v1/courses/{courseID}/assignments/{assignmentID} with the updates map wrapped in an assignment key.

type AssignmentGroup 

type AssignmentGroup struct {
	ID          string       `json:"id"`
	Name        string       `json:"name"`
	Position    int          `json:"position"`
	GroupWeight float64      `json:"group_weight"`
	Assignments []Assignment `json:"assignments,omitempty"`
}

AssignmentGroup represents a group of assignments.

func ListAssignmentGroups 

func ListAssignmentGroups(ctx context.Context, client *Client, courseID string) ([]AssignmentGroup, error)

ListAssignmentGroups returns all assignment groups for a course. It sends GET /api/v1/courses/{courseID}/assignment_groups with include[]=assignments.

type Attachment 

type Attachment struct {
	ID          string `json:"id"`
	Filename    string `json:"filename"`
	DisplayName string `json:"display_name"`
	URL         string `json:"url"`
	Size        int64  `json:"size"`
	ContentType string `json:"content_type"`
}

Attachment represents a file attached to a submission or other resource.

type AuditConfig 

type AuditConfig struct {
	Enabled bool   `yaml:"enabled"`
	Path    string `yaml:"path,omitempty"`
}

AuditConfig controls audit logging.

type AuditEvent 

type AuditEvent struct {
	Time            string            `json:"time"`
	SchemaVersion   string            `json:"schema_version"`
	Command         string            `json:"command"`
	Profile         string            `json:"profile"`
	BaseURL         string            `json:"base_url"`
	Method          string            `json:"method"`
	Path            string            `json:"path"`
	Resource        map[string]string `json:"resource"`
	RequestHash     string            `json:"request_hash"`
	ResponseStatus  int               `json:"response_status"`
	CanvasRequestID string            `json:"canvas_request_id,omitempty"`
	DryRun          bool              `json:"dry_run"`
	Success         bool              `json:"success"`
}

AuditEvent records a single mutation for the local audit log.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the HTTP client for the Canvas API.

func NewClient 

func NewClient(baseURL, token, version string, timeout time.Duration, retries int) *Client

NewClient creates a new Canvas API client.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, method, path string, query url.Values, body io.Reader) (*http.Response, error)

Do executes an HTTP request with automatic retry for transient failures.

func (*Client) DoURL 

func (c *Client) DoURL(ctx context.Context, method, absoluteURL string, body io.Reader) (*http.Response, error)

DoURL executes a request to an absolute URL (for pagination next links and upload redirects). No base URL prepending. Auth headers are only sent when the URL host matches the configured base URL host.

func (*Client) DoURLWithHeaders added in v0.3.0 

func (c *Client) DoURLWithHeaders(ctx context.Context, method, absoluteURL string, body io.Reader, headers http.Header) (*http.Response, error)

DoURLWithHeaders is like DoURL but also applies custom headers.

func (*Client) DoWithHeaders 

func (c *Client) DoWithHeaders(ctx context.Context, method, path string, query url.Values, body io.Reader, headers http.Header) (*http.Response, error)

DoWithHeaders executes an HTTP request with custom headers and automatic retry.

func (*Client) SetHTTPClient 

func (c *Client) SetHTTPClient(hc *http.Client)

SetHTTPClient replaces the underlying HTTP client. This is useful for configuring custom redirect policies (e.g., for file uploads).

func (*Client) WithCookie added in v0.3.0 

func (c *Client) WithCookie(cookie, csrfToken string) *Client

WithCookie sets cookie-based authentication on the client. If token is also set (via NewClient), token auth takes precedence. csrfToken may be empty; the client will attempt to cache it from response headers.

type Config 

type Config struct {
	CurrentProfile string             `yaml:"current_profile"`
	Profiles       map[string]Profile `yaml:"profiles"`
	Output         OutputConfig       `yaml:"output,omitempty"`
	Audit          AuditConfig        `yaml:"audit,omitempty"`
}

Config is the top-level configuration structure.

type ContentExport 

type ContentExport struct {
	ID            string      `json:"id"`
	CreatedAt     string      `json:"created_at"`
	ExportType    string      `json:"export_type"`
	WorkflowState string      `json:"workflow_state"`
	ProgressURL   string      `json:"progress_url"`
	UserID        string      `json:"user_id"`
	Attachment    *Attachment `json:"attachment,omitempty"`
}

ContentExport represents a Canvas content export job.

func GetContentExport 

func GetContentExport(ctx context.Context, client *Client, courseID, exportID string) (ContentExport, error)

GetContentExport returns the status of a content export.

func StartContentExport 

func StartContentExport(ctx context.Context, client *Client, courseID, exportType string) (ContentExport, error)

StartContentExport creates a new content export for a course.

type Conversation 

type Conversation struct {
	ID            string `json:"id"`
	Subject       string `json:"subject"`
	WorkflowState string `json:"workflow_state"`
	LastMessage   string `json:"last_message"`
	LastMessageAt string `json:"last_message_at"`
	MessageCount  int    `json:"message_count"`
	Participants  []User `json:"participants,omitempty"`
}

Conversation represents a Canvas inbox conversation.

func GetConversation 

func GetConversation(ctx context.Context, client *Client, conversationID string) (Conversation, error)

GetConversation returns a single conversation by ID.

func ReplyToConversation 

func ReplyToConversation(ctx context.Context, client *Client, conversationID, body string) (Conversation, error)

ReplyToConversation adds a message to an existing conversation.

func SendMessage 

func SendMessage(ctx context.Context, client *Client, recipients []string, subject, body string) (Conversation, error)

SendMessage creates a new conversation with the given recipients, subject, and body.

type CookieSessionExpiredError added in v0.3.0 

type CookieSessionExpiredError struct {
	Location string // The redirect URL that triggered the detection.
}

CookieSessionExpiredError indicates that the session cookie is no longer valid and the user needs to re-authenticate.

func (*CookieSessionExpiredError) Error added in v0.3.0 

func (e *CookieSessionExpiredError) Error() string

type Course 

type Course struct {
	ID               string       `json:"id"`
	Name             string       `json:"name"`
	CourseCode       string       `json:"course_code"`
	WorkflowState    string       `json:"workflow_state"`
	EnrollmentTermID string       `json:"enrollment_term_id"`
	Term             *Term        `json:"term,omitempty"`
	Enrollments      []Enrollment `json:"enrollments,omitempty"`
}

Course represents a Canvas course.

func GetCourse 

func GetCourse(ctx context.Context, client *Client, courseID string, query url.Values) (Course, error)

GetCourse returns a single course by ID. It sends GET /api/v1/courses/{courseID} with include[]=term by default.

type CourseEpubExport 

type CourseEpubExport struct {
	ID         string      `json:"id"`
	Name       string      `json:"name"`
	EpubExport *EpubExport `json:"epub_export,omitempty"`
}

CourseEpubExport represents a course with its latest ePub export.

type DiscussionEntry 

type DiscussionEntry struct {
	ID        string  `json:"id"`
	UserID    string  `json:"user_id"`
	UserName  string  `json:"user_name,omitempty"`
	Message   string  `json:"message"`
	CreatedAt string  `json:"created_at"`
	UpdatedAt string  `json:"updated_at"`
	ParentID  *string `json:"parent_id"`
}

DiscussionEntry represents a single reply/entry in a discussion topic.

func ReplyToDiscussion 

func ReplyToDiscussion(ctx context.Context, client *Client, courseID, discussionID, message string) (DiscussionEntry, error)

ReplyToDiscussion posts a new top-level entry to a discussion topic.

func ReplyToEntry 

func ReplyToEntry(ctx context.Context, client *Client, courseID, discussionID, entryID, message string) (DiscussionEntry, error)

ReplyToEntry posts a reply to an existing discussion entry.

type DiscussionTopic 

type DiscussionTopic struct {
	ID             string  `json:"id"`
	Title          string  `json:"title"`
	Message        string  `json:"message"`
	PostedAt       *string `json:"posted_at"`
	LastReplyAt    *string `json:"last_reply_at"`
	DiscussionType string  `json:"discussion_type"`
	Published      bool    `json:"published"`
	IsAnnouncement bool    `json:"is_announcement"`
	UserName       string  `json:"user_name,omitempty"`
}

DiscussionTopic represents a Canvas discussion topic.

func CreateAnnouncement 

func CreateAnnouncement(ctx context.Context, client *Client, courseID, title, message string) (DiscussionTopic, error)

CreateAnnouncement creates a new announcement for a course. It sends POST /api/v1/courses/{courseID}/discussion_topics with is_announcement=true.

func CreateDiscussion 

func CreateDiscussion(ctx context.Context, client *Client, courseID, title, message string) (DiscussionTopic, error)

CreateDiscussion creates a new discussion topic for a course.

func GetAnnouncement 

func GetAnnouncement(ctx context.Context, client *Client, courseID, announcementID string) (DiscussionTopic, error)

GetAnnouncement returns a single announcement by ID. Announcements are discussion topics, so this fetches from the discussion topics endpoint.

func GetDiscussion 

func GetDiscussion(ctx context.Context, client *Client, courseID, discussionID string) (DiscussionTopic, error)

GetDiscussion returns a single discussion topic by ID.

type DownloadCourseFilesOptions added in v0.4.0 

type DownloadCourseFilesOptions struct {
	CourseID    string
	OutDir      string
	NoOverwrite bool
}

DownloadCourseFilesOptions controls a bulk course-files download.

type Enrollment 

type Enrollment struct {
	ID              string  `json:"id"`
	UserID          string  `json:"user_id"`
	CourseID        string  `json:"course_id"`
	Type            string  `json:"type"`
	EnrollmentState string  `json:"enrollment_state"`
	Role            string  `json:"role"`
	Grades          *Grades `json:"grades,omitempty"`
	User            *User   `json:"user,omitempty"`
}

Enrollment represents a course enrollment.

type Envelope 

type Envelope struct {
	OK    bool       `json:"ok"`
	Data  any        `json:"data,omitempty"`
	Error *ErrorInfo `json:"error,omitempty"`
	Meta  Meta       `json:"meta"`
}

Envelope is the top-level JSON output wrapper.

func NormalizeError 

func NormalizeError(resp *http.Response, command string, baseURL ...string) Envelope

NormalizeError converts an HTTP error response into a structured Envelope. If baseURL is provided (variadic), cookie session expiry is checked and overrides the error when detected.

type EpubExport 

type EpubExport struct {
	ID            string      `json:"id"`
	CreatedAt     string      `json:"created_at"`
	WorkflowState string      `json:"workflow_state"`
	ProgressURL   string      `json:"progress_url"`
	UserID        string      `json:"user_id"`
	Attachment    *Attachment `json:"attachment,omitempty"`
}

EpubExport represents a Canvas ePub export job.

func GetEpubExport 

func GetEpubExport(ctx context.Context, client *Client, courseID, exportID string) (EpubExport, error)

GetEpubExport returns the status of an ePub export.

func StartEpubExport 

func StartEpubExport(ctx context.Context, client *Client, courseID string) (EpubExport, error)

StartEpubExport creates a new ePub export for a course.

type ErrorInfo 

type ErrorInfo struct {
	Code            string `json:"code"`
	Message         string `json:"message"`
	Category        string `json:"category"`
	Retryable       bool   `json:"retryable"`
	Status          int    `json:"status,omitempty"`
	CanvasRequestID string `json:"canvas_request_id,omitempty"`
	ResponseBody    any    `json:"response_body,omitempty"`
}

ErrorInfo describes a structured error returned in the JSON envelope.

func NormalizeErrorFromBody added in v0.3.0 

func NormalizeErrorFromBody(resp *http.Response, bodyBytes []byte, baseURL ...string) ErrorInfo

NormalizeErrorFromBody creates an ErrorInfo from an HTTP response whose body has already been read. Use this when the body bytes are needed for other purposes (e.g. JSON envelope construction) before error processing. If baseURL is provided (variadic), cookie session expiry is checked.

type File 

type File struct {
	ID          string `json:"id"`
	FolderID    string `json:"folder_id"`
	DisplayName string `json:"display_name"`
	Filename    string `json:"filename"`
	URL         string `json:"url"`
	Size        int64  `json:"size"`
	ContentType string `json:"content_type"`
	CreatedAt   string `json:"created_at"`
	UpdatedAt   string `json:"updated_at"`
}

File represents a Canvas file.

func GetFile 

func GetFile(ctx context.Context, client *Client, fileID string) (File, error)

GetFile returns metadata for a single file by ID.

type FileDownloadResult added in v0.4.0 

type FileDownloadResult struct {
	Total        int                 `json:"total"`
	Downloaded   int                 `json:"downloaded"`
	Failed       int                 `json:"failed"`
	Entries      []FileManifestEntry `json:"-"`
	ManifestPath string              `json:"manifest_path"`
}

FileDownloadResult holds the outcome of a course files download operation.

func DownloadCourseFiles added in v0.4.0 

func DownloadCourseFiles(ctx context.Context, client *Client, opts DownloadCourseFilesOptions) (*FileDownloadResult, error)

DownloadCourseFiles lists all files for a course, downloads each one into outDir, and writes manifest.json + manifest.ndjson alongside them. Files that already exist are skipped when noOverwrite is true. The returned FileDownloadResult summarizes the operation; its Entries slice holds per-file status for callers that need the detail.

type FileManifestEntry added in v0.4.0 

type FileManifestEntry struct {
	FileID         string `json:"file_id"`
	Filename       string `json:"filename"`
	DisplayName    string `json:"display_name"`
	ContentType    string `json:"content_type"`
	Size           int64  `json:"size"`
	LocalPath      string `json:"local_path"`
	DownloadStatus string `json:"download_status"`
	Error          string `json:"error,omitempty"`
}

FileManifestEntry represents a single file entry in the download manifest.

type GradeImportResult 

type GradeImportResult struct {
	Submissions []Submission `json:"submissions"`
}

GradeImportResult holds the result of a bulk grade import.

type Grades 

type Grades struct {
	CurrentScore *float64 `json:"current_score"`
	FinalScore   *float64 `json:"final_score"`
	CurrentGrade *string  `json:"current_grade"`
	FinalGrade   *string  `json:"final_grade"`
}

Grades holds current and final grade information for an enrollment.

type Meta 

type Meta struct {
	SchemaVersion string     `json:"schema_version"`
	Command       string     `json:"command"`
	RequestID     string     `json:"request_id"`
	Profile       string     `json:"profile,omitempty"`
	BaseURL       string     `json:"base_url,omitempty"`
	DurationMS    int64      `json:"duration_ms,omitempty"`
	RequestCount  int        `json:"request_count,omitempty"`
	Paginated     bool       `json:"paginated,omitempty"`
	PageSize      int        `json:"page_size,omitempty"`
	Limit         *int       `json:"limit"`
	RateLimit     *RateLimit `json:"rate_limit,omitempty"`
	Warnings      []string   `json:"warnings,omitempty"`
}

Meta carries execution metadata for every command response.

type Module 

type Module struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	Position      int    `json:"position"`
	Published     bool   `json:"published"`
	ItemsCount    int    `json:"items_count"`
	WorkflowState string `json:"workflow_state"`
}

Module represents a Canvas course module.

func GetModule 

func GetModule(ctx context.Context, client *Client, courseID, moduleID string) (Module, error)

GetModule returns a single module by ID. It sends GET /api/v1/courses/{courseID}/modules/{moduleID}.

func PublishModule 

func PublishModule(ctx context.Context, client *Client, courseID, moduleID string, published bool) (Module, error)

PublishModule publishes or unpublishes a module. It sends PUT /api/v1/courses/{courseID}/modules/{moduleID} with module.published set to the given value.

type ModuleItem 

type ModuleItem struct {
	ID        string  `json:"id"`
	ModuleID  string  `json:"module_id"`
	Title     string  `json:"title"`
	Type      string  `json:"type"`
	Position  int     `json:"position"`
	ContentID string  `json:"content_id,omitempty"`
	HTMLURL   string  `json:"html_url,omitempty"`
	URL       *string `json:"url,omitempty"`
	Published *bool   `json:"published,omitempty"`
}

ModuleItem represents an item within a module.

func GetModuleItem 

func GetModuleItem(ctx context.Context, client *Client, courseID, moduleID, itemID string) (ModuleItem, error)

GetModuleItem returns a single module item by ID.

type OutputConfig 

type OutputConfig struct {
	JSONPretty bool `yaml:"json_pretty"`
	NoColor    bool `yaml:"no_color"`
}

OutputConfig controls output formatting.

type Page 

type Page struct {
	URL       string `json:"url"`
	Title     string `json:"title"`
	Body      string `json:"body,omitempty"`
	Published bool   `json:"published"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

Page represents a Canvas wiki page.

func GetPage 

func GetPage(ctx context.Context, client *Client, courseID, pageURL string) (Page, error)

GetPage returns a single page by its URL slug. It sends GET /api/v1/courses/{courseID}/pages/{pageURL}.

func UpdatePage 

func UpdatePage(ctx context.Context, client *Client, courseID, pageURL string, updates map[string]any) (Page, error)

UpdatePage updates a wiki page with the given fields. It sends PUT /api/v1/courses/{courseID}/pages/{pageURL} with the updates map wrapped in a wiki_page key.

type PaginationMeta 

type PaginationMeta struct {
	Paginated    bool `json:"paginated"`
	PageSize     int  `json:"page_size"`
	Limit        int  `json:"limit"`
	RequestCount int  `json:"request_count"`
	TotalItems   int  `json:"total_items"`
}

PaginationMeta captures pagination statistics for a request.

func List 

func List[T any](ctx context.Context, client *Client, path string, query url.Values, pageSize int) ([]T, PaginationMeta, error)

List fetches a paginated list of items from the Canvas API. It wraps Request with Paginate=true and decodes the response into []T.

func Paginate 

func Paginate[T any](ctx context.Context, client *Client, path string, query url.Values, limit, pageSize int) ([]T, PaginationMeta, error)

Paginate auto-paginates a Canvas list endpoint and decodes all items. If limit > 0, it stops after collecting that many items. pageSize controls the per_page query parameter.

type Profile 

type Profile struct {
	BaseURL       string `yaml:"base_url"`
	Token         string `yaml:"token"`
	Cookie        string `yaml:"cookie,omitempty"`
	CSRFToken     string `yaml:"csrf_token,omitempty"`
	Timeout       string `yaml:"timeout,omitempty"`
	Retries       int    `yaml:"retries,omitempty"`
	PageSize      int    `yaml:"page_size,omitempty"`
	ReadOnly      bool   `yaml:"read_only,omitempty"`
	DefaultCourse string `yaml:"default_course,omitempty"`
}

Profile holds per-profile connection and behavior settings.

type Progress 

type Progress struct {
	ID            string   `json:"id"`
	ContextID     string   `json:"context_id"`
	ContextType   string   `json:"context_type"`
	UserID        string   `json:"user_id"`
	Tag           string   `json:"tag"`
	Completion    *float64 `json:"completion,omitempty"`
	WorkflowState string   `json:"workflow_state"`
}

Progress represents a Canvas progress object.

func GetProgress 

func GetProgress(ctx context.Context, client *Client, progressURL string) (Progress, error)

GetProgress returns the status of a progress operation.

type RateLimit 

type RateLimit struct {
	RequestCost float64 `json:"request_cost"`
	Remaining   float64 `json:"remaining"`
}

RateLimit captures Canvas rate-limit response headers.

func CaptureRateMeta 

func CaptureRateMeta(resp *http.Response) *RateLimit

CaptureRateMeta reads rate-limit headers from a response.

Example 
resp := &http.Response{
	Header: http.Header{
		"X-Request-Cost":         []string{"2.0"},
		"X-Rate-Limit-Remaining": []string{"38.0"},
	},
}
meta := CaptureRateMeta(resp)
fmt.Printf("cost=%.1f remaining=%.1f\n", meta.RequestCost, meta.Remaining)

Output:
cost=2.0 remaining=38.0

type RequestOptions 

type RequestOptions struct {
	Method     string
	PathOrURL  string
	Query      url.Values
	Body       io.Reader
	Headers    http.Header
	Paginate   bool
	PageSize   int
	Limit      int
	DecodeInto any
}

RequestOptions describes a single API request to be executed by the client.

type ResponseMeta 

type ResponseMeta struct {
	RateLimit  *RateLimit     `json:"rate_limit,omitempty"`
	Pagination PaginationMeta `json:"pagination"`
	Warnings   []string       `json:"warnings,omitempty"`
}

ResponseMeta captures metadata from a Canvas API response.

func Request 

func Request(ctx context.Context, client *Client, opts *RequestOptions) (*ResponseMeta, error)

Request executes a Canvas API request with optional pagination and decoding.

type Rubric 

type Rubric struct {
	ID             string  `json:"id"`
	Title          string  `json:"title"`
	PointsPossible float64 `json:"points_possible"`
	Criteria       []any   `json:"criteria,omitempty"`
}

Rubric represents a Canvas rubric.

func ListRubrics 

func ListRubrics(ctx context.Context, client *Client, courseID string) ([]Rubric, error)

ListRubrics returns all rubrics for a course. It sends GET /api/v1/courses/{courseID}/rubrics.

type Section 

type Section struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	CourseID      string `json:"course_id"`
	TotalStudents *int   `json:"total_students,omitempty"`
}

Section represents a course section.

func ListSections 

func ListSections(ctx context.Context, client *Client, courseID string) ([]Section, error)

ListSections returns all sections for a course. It sends GET /api/v1/courses/{courseID}/sections with include[]=total_students.

type Submission 

type Submission struct {
	ID            string       `json:"id"`
	UserID        string       `json:"user_id"`
	AssignmentID  string       `json:"assignment_id"`
	Score         *float64     `json:"score"`
	Grade         *string      `json:"grade"`
	SubmittedAt   *string      `json:"submitted_at"`
	WorkflowState string       `json:"workflow_state"`
	Late          bool         `json:"late"`
	Missing       bool         `json:"missing"`
	Excused       bool         `json:"excused"`
	Attempt       *int         `json:"attempt"`
	Attachments   []Attachment `json:"attachments,omitempty"`
	User          *User        `json:"user,omitempty"`
}

Submission represents a student submission.

func AddComment 

func AddComment(ctx context.Context, client *Client, courseID, assignmentID, userID, comment string) (Submission, error)

AddComment adds a text comment to a specific user's submission.

func GetSubmission 

func GetSubmission(ctx context.Context, client *Client, courseID, assignmentID, userID string) (Submission, error)

GetSubmission returns a single submission for a specific user and assignment. It sends GET /api/v1/courses/{courseID}/assignments/{assignmentID}/submissions/{userID}.

func GradeRubric 

func GradeRubric(ctx context.Context, client *Client, courseID, assignmentID, userID string, rubricAssessment map[string]any) (Submission, error)

GradeRubric submits a rubric assessment for a specific user's submission.

func ImportGrades 

func ImportGrades(ctx context.Context, client *Client, courseID, assignmentID string, gradeData map[string]string) ([]Submission, error)

ImportGrades posts a batch of grades for an assignment.

func SetGrade 

func SetGrade(ctx context.Context, client *Client, courseID, assignmentID, userID, score string) (Submission, error)

SetGrade sets a posted grade for a specific user's submission.

func SubmitAssignment 

func SubmitAssignment(ctx context.Context, client *Client, courseID, assignmentID string, sub SubmissionRequest) (Submission, error)

SubmitAssignment posts a submission for an assignment. It sends POST /api/v1/courses/{courseID}/assignments/{assignmentID}/submissions. The submission_type must be one of: online_text_entry, online_url, online_upload.

type SubmissionRequest 

type SubmissionRequest struct {
	SubmissionType string   `json:"submission_type"`
	Body           string   `json:"body,omitempty"`
	URL            string   `json:"url,omitempty"`
	FileIDs        []string `json:"file_ids,omitempty"`
}

SubmissionRequest holds the parameters for submitting an assignment.

type Tab 

type Tab struct {
	ID         string `json:"id"`
	Label      string `json:"label"`
	Type       string `json:"type"`
	HTMLURL    string `json:"html_url"`
	FullURL    string `json:"full_url"`
	Position   int    `json:"position"`
	Visibility string `json:"visibility"`
}

Tab represents a course navigation tab.

func ListCourseTabs 

func ListCourseTabs(ctx context.Context, client *Client, courseID string) ([]Tab, error)

ListCourseTabs returns the navigation tabs for a course. It sends GET /api/v1/courses/{courseID}/tabs.

type Term 

type Term struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

Term represents an academic term.

type TodoItem 

type TodoItem struct {
	Assignment    *Assignment `json:"assignment,omitempty"`
	ContextCode   string      `json:"context_code"`
	ID            string      `json:"id"`
	Title         string      `json:"title"`
	Type          string      `json:"type"`
	DueDate       *string     `json:"due_date"`
	WorkflowState string      `json:"workflow_state"`
}

TodoItem represents a todo item for the user.

func GetTodoItems 

func GetTodoItems(ctx context.Context, client *Client) ([]TodoItem, error)

GetTodoItems returns the user's todo items.

type UpcomingEvent 

type UpcomingEvent struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	StartAt     string `json:"start_at"`
	EndAt       string `json:"end_at,omitempty"`
	ContextCode string `json:"context_code"`
	Type        string `json:"type"`
	HTMLURL     string `json:"html_url,omitempty"`
}

UpcomingEvent represents an upcoming calendar event.

func GetUpcomingEvents 

func GetUpcomingEvents(ctx context.Context, client *Client) ([]UpcomingEvent, error)

GetUpcomingEvents returns the user's upcoming events.

type User 

type User struct {
	ID           string  `json:"id"`
	Name         string  `json:"name"`
	SortableName string  `json:"sortable_name"`
	ShortName    string  `json:"short_name"`
	Email        *string `json:"email,omitempty"`
	LoginID      string  `json:"login_id,omitempty"`
}

User represents a Canvas user.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.