@groton/canvas-api 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.3.8](https://github.com/groton-school/canvas-cli/compare/api/0.3.7...api/0.3.8) (2026-04-06)
+
+
+### Features
+
+* deprecate pathParams, searchParams, params in favor of path, query, body ([beceb0f](https://github.com/groton-school/canvas-cli/commit/beceb0f40a68cb22a2325c02b54d85e050643641))
+
+
+### Bug Fixes
+
+* explicitly (rather than implictly) target Node LTS version ([7140d44](https://github.com/groton-school/canvas-cli/commit/7140d446a12ad17b381a2a7c5427482260067a34))
+
+## [0.3.7](https://github.com/groton-school/canvas-cli/compare/api/0.3.6...api/0.3.7) (2026-01-29)
+
+
+### Features
+
+* update to 2026-01-14 release ([91c1a2e](https://github.com/groton-school/canvas-cli/commit/91c1a2e57cb3718096b5ea30e09380b756b6f1a9))
+* update to 2026-01-28 spec ([9ab62f7](https://github.com/groton-school/canvas-cli/commit/9ab62f7c2f6de140a1b24b6aa25ed8b951cbfbb0))
+
 ## [0.3.6](https://github.com/groton-school/canvas-cli/compare/api/0.3.5...api/0.3.6) (2026-01-13)
 
 

package/dist/Client/Base.d.ts

@@ -0,0 +1,51 @@
+import { PathString, URLString } from '@battis/descriptive-types';
+import { JSONObject, JSONValue } from '@battis/typescript-tricks';
+import { UploadResponse } from './UploadResponse.js';
+export type Init = {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path?: JSONObject;
+    /** @deprecated Use {@link Init.path} */
+    pathParams?: JSONObject;
+    query?: JSONObject;
+    /** @deprecated Use {@link Init.query} */
+    searchParams?: JSONObject;
+    body?: JSONObject;
+    /** @deprecated Use {@link Init.body} */
+    params?: JSONObject;
+};
+export type FileLocation = {
+    filePath?: PathString;
+    url?: URLString;
+};
+export type UploadParams = {
+    response: UploadResponse;
+    file: FileLocation;
+};
+export interface Base {
+    /** Base instance URL for API requests */
+    readonly instance_url: URLString;
+    /**
+     * For optimal compatibility, requests to the Canvas API should include the
+     * following headers:
+     *
+     * ```txt
+     *   Content-Type: application/x-www-form-urlencoded
+     *   Accept: application/json+canvas-string-ids
+     * ```
+     *
+     * This method is best implemented by passing its arguments, a token-fetching
+     * method, and the instance URL to {@link fetchAllPages}.
+     *
+     * @param endpoint Endpoint path, relative to `instance_url`
+     * @param init Request method and parameters
+     * @see https://developerdocs.instructure.com/services/canvas#schema
+     */
+    fetchAs<T extends JSONValue = JSONValue>(endpoint: string, init?: Init): Promise<T>;
+    /**
+     * Steps 2 and 3 of the file upload process
+     *
+     * @param params Opaque upload response and file location information
+     * @see https://developerdocs.instructure.com/services/canvas/basics/file.file_uploads
+     */
+    upload<T extends JSONValue = JSONValue>(params: UploadParams): Promise<T>;
+}

package/dist/Client/Base.js

@@ -0,0 +1 @@
+export {};

package/dist/Client/Masquerade.d.ts

@@ -0,0 +1,18 @@
+export type Masquerade = {
+    /**
+     * Masquerading is making an API call on behalf of another user. It will
+     * behave as if the target user had made the API call with their own access
+     * token (even if they don't have one), including permission checks,
+     * enrollments, etc. In order to masquerade via the API, the calling user must
+     * have the "Become other users" permission. If the target user is also an
+     * admin, the calling user must additionally have every permission that the
+     * target user has. For auditing purposes, all calls log both the calling user
+     * and the target user.
+     *
+     * To masquerade, add an as_user_id parameter to any request. It can be either
+     * a Canvas user ID, or an SIS user ID
+     *
+     * @see https://developerdocs.instructure.com/services/canvas/basics/file.masquerading
+     */
+    as_user_id?: string | number;
+};

package/dist/Client/Masquerade.js

@@ -0,0 +1 @@
+export {};

package/dist/Client/Paginated.d.ts

@@ -0,0 +1,33 @@
+import { JSONObject } from '@battis/typescript-tricks';
+import { Base } from './Base.js';
+export type Paginated = {
+    /**
+     * Requests that return multiple items will be paginated to 10 items by
+     * default. You can set a custom per-page amount with the ?per_page parameter.
+     * There is an unspecified limit to how big you can set per_page to, so be
+     * sure to always check for the Link header.
+     *
+     * @see https://developerdocs.instructure.com/services/canvas/basics/file.pagination
+     */
+    per_page?: number;
+};
+type AllPagesOptions<ReturnType> = {
+    instance_url: Base['instance_url'];
+    endpoint: string | URL | Request;
+    path?: JSONObject;
+    /** @deprecated Use {@link AllPagesOptions.path} */
+    pathParams?: JSONObject;
+    query?: JSONObject;
+    /** @deprecated Use {@link AllPagesOptions.query} */
+    searchParams?: JSONObject;
+    body?: JSONObject;
+    /** @deprecated Use {@link AllPagesOptions.body} */
+    params?: JSONObject;
+    accessToken?: () => string | undefined | Promise<string | undefined>;
+    init?: RequestInit;
+    fetch: (endpoint: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    pageCallback?: (page: ReturnType) => void;
+};
+/** Fetch all pages of paginated results at once */
+export declare function fetchAllPages<ReturnType>({ instance_url, endpoint, path, pathParams, query, searchParams, body, params, accessToken, init, fetch, pageCallback }: AllPagesOptions<ReturnType>): Promise<ReturnType & ({} | null)>;
+export {};

package/dist/Client/Paginated.js

@@ -0,0 +1,79 @@
+import { isError } from '#utilities';
+import { constructInit, flattenEndpoint } from './Request.js';
+/** Fetch all pages of paginated results at once */
+export async function fetchAllPages({ instance_url, endpoint, path, pathParams, query, searchParams, body, params, accessToken, init, fetch, pageCallback }) {
+    path = path || pathParams;
+    query = query || searchParams;
+    body = body || params;
+    let nextEndpoint = flattenEndpoint(endpoint.toString(), {
+        path,
+        query
+    });
+    init = constructInit(init, {
+        body,
+        access_token: accessToken ? await accessToken() : undefined
+    });
+    let result = undefined;
+    do {
+        const response = await fetch(new URL(nextEndpoint, instance_url), result
+            ? constructInit(init, {
+                access_token: accessToken ? await accessToken() : undefined
+            })
+            : init);
+        if (response.ok) {
+            const page = (await response.json());
+            if (isError(page)) {
+                throw new Error('Error', {
+                    cause: { endpoint, init, response, error: page }
+                });
+            }
+            if (Array.isArray(page)) {
+                if (pageCallback) {
+                    pageCallback(page);
+                }
+                if (!result) {
+                    result = page;
+                }
+                else {
+                    result.push(...page);
+                }
+                const matches = /<([^>]+)>;\s*rel="next"/gm.exec(response.headers.get('link') || '');
+                nextEndpoint = matches && matches.length >= 2 ? matches[1] : undefined;
+            }
+            else {
+                result = page;
+            }
+        }
+        else {
+            let body = await response.text();
+            try {
+                body = JSON.parse(body);
+            }
+            catch (_) {
+                // ignore failure to parse
+            }
+            const cause = {
+                request: {
+                    url: response.url,
+                    method: init?.method,
+                    headers: result ? undefined : init?.headers,
+                    body: result ? undefined : init?.body
+                },
+                response: {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: response.headers,
+                    body
+                },
+                previous_accumulated_pages: result
+            };
+            throw new Error(response.status.toString(), {
+                cause
+            });
+        }
+    } while (Array.isArray(result) && nextEndpoint);
+    if (result === undefined) {
+        throw new Error(`Unexpected undefined result: ${JSON.stringify({ endpoint, init: result ? undefined : init })}`);
+    }
+    return result;
+}

package/dist/Client/Request.d.ts

@@ -0,0 +1,18 @@
+import { JSONObject } from '@battis/typescript-tricks';
+type EndpointParameters = {
+    path?: JSONObject;
+    /** @deprecated Use {@link EndpointParameters.path} */
+    pathParams?: JSONObject;
+    query?: JSONObject;
+    /** @deprecated Use {@link EndpointParameters.query} */
+    searchParams?: JSONObject;
+};
+type RequestParameters = {
+    body?: JSONObject;
+    /** @deprecated Use {@link RequestParameters.body} */
+    params?: JSONObject;
+    access_token?: string;
+};
+export declare function flattenEndpoint(endpoint: string, { path, query, pathParams, searchParams }: EndpointParameters): string;
+export declare function constructInit(init?: RequestInit, { body, params, access_token }?: RequestParameters): RequestInit;
+export {};

package/dist/Client/Request.js

@@ -0,0 +1,36 @@
+import { stringify } from '#utilities';
+const headers = {
+    'Content-Type': 'application/x-www-form-urlencoded',
+    Accept: 'application/json+canvas-string-ids'
+};
+export function flattenEndpoint(endpoint, { path, query, pathParams, searchParams }) {
+    path = path || pathParams;
+    query = query || searchParams;
+    if (path) {
+        endpoint = Object.keys(path || {}).reduce((populatedEndpoint, paramName) => {
+            if (path[paramName]) {
+                return populatedEndpoint.replaceAll(`{${paramName}}`, path[paramName].toString());
+            }
+            return populatedEndpoint;
+        }, endpoint);
+    }
+    if (query) {
+        endpoint = `${endpoint}${endpoint.includes('?') ? '&' : '?'}${stringify(query)}`;
+    }
+    return endpoint;
+}
+export function constructInit(init = {}, { body, params, access_token } = {}) {
+    body = body || params;
+    if (body) {
+        init.body = stringify(body);
+    }
+    if (!init.headers) {
+        init.headers = {};
+    }
+    init.headers = {
+        ...init.headers,
+        ...headers,
+        Authorization: access_token ? `Bearer ${access_token}` : undefined
+    };
+    return init;
+}

package/dist/Client/UploadResponse.d.ts

@@ -0,0 +1,18 @@
+import { URLString } from '@battis/descriptive-types';
+/** @see https://developerdocs.instructure.com/services/canvas/basics/file.file_uploads#step-2-upload-the-file-data-to-the-url-given-in-the-previous-response */
+export type UploadResponse = {
+    /**
+     * Using the data in the JSON response from Step 1, the application can now
+     * upload the actual file data, by POSTing a specially formulated request to
+     * the URL given in the upload_url field of the response.
+     */
+    upload_url: URLString;
+    /**
+     * The parameters POSTed with this request come directly from the
+     * upload_params part of the JSON response in Step 1.
+     */
+    upload_params: {
+        key: string;
+        [param: string]: string;
+    };
+};

package/dist/Client/UploadResponse.js

@@ -0,0 +1 @@
+export {};

package/dist/Client/index.d.ts

@@ -0,0 +1,7 @@
+import { Base } from './Base.js';
+export * from './Base.js';
+export * from './Masquerade.js';
+export * from './Paginated.js';
+export * from './UploadResponse.js';
+export declare function init(client: Base): void;
+export declare function client(): Base;

package/dist/Client/index.js

@@ -0,0 +1,14 @@
+export * from './Base.js';
+export * from './Masquerade.js';
+export * from './Paginated.js';
+export * from './UploadResponse.js';
+let _client = undefined;
+export function init(client) {
+    _client = client;
+}
+export function client() {
+    if (!_client) {
+        throw new Error('Client not initialized');
+    }
+    return _client;
+}

package/dist/Endpoints/Lti/Accounts/get.d.ts

@@ -1,4 +1,4 @@
-import { Masquerade } from '@groton/canvas-api.client.base';
+import { Masquerade } from '#client';
 import { Account } from '../../../Resources/Accounts.js';
 export type getPathParameters = {
     /**
@@ -9,12 +9,19 @@ export type getPathParameters = {
     account_id: string | number;
 };
 export type getSearchParameters = Masquerade;
-type Options = {
+type Options = ({
+    path: getPathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: getPathParameters;
-} & ({
+}) & ({
+    query?: Partial<getSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<getSearchParameters>;
     strict?: false;
 } | {
+    query?: Partial<getSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: getSearchParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Accounts/get.js

@@ -1,4 +1,4 @@
-import { client } from '../../../Client.js';
+import { client } from '#client';
 /**
  * Get account
  *

package/dist/Endpoints/Lti/Assignments/Files/OriginalityReport/show_originality_report_files.d.ts

@@ -1,4 +1,4 @@
-import { Masquerade } from '@groton/canvas-api.client.base';
+import { Masquerade } from '#client';
 import { OriginalityReport } from '../../../../../Resources/OriginalityReports.js';
 export type show_originality_report_filesPathParameters = {
     /**
@@ -15,12 +15,19 @@ export type show_originality_report_filesPathParameters = {
     file_id: string | number;
 };
 export type show_originality_report_filesSearchParameters = Masquerade;
-type Options = {
+type Options = ({
+    path: show_originality_report_filesPathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: show_originality_report_filesPathParameters;
-} & ({
+}) & ({
+    query?: Partial<show_originality_report_filesSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<show_originality_report_filesSearchParameters>;
     strict?: false;
 } | {
+    query?: Partial<show_originality_report_filesSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: show_originality_report_filesSearchParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Assignments/Files/OriginalityReport/show_originality_report_files.js

@@ -1,4 +1,4 @@
-import { client } from '../../../../../Client.js';
+import { client } from '#client';
 /**
  * Show an Originality Report
  *

package/dist/Endpoints/Lti/Assignments/Files/OriginalityReport/update.d.ts

@@ -1,4 +1,4 @@
-import { Masquerade } from '@groton/canvas-api.client.base';
+import { Masquerade } from '#client';
 import { OriginalityReport } from '../../../../../Resources/OriginalityReports.js';
 export type updatePathParameters = {
     /**
@@ -61,14 +61,25 @@ export type updateFormParameters = Masquerade & {
      */
     'originality_report[error_message]': string;
 };
-type Options = {
+type Options = ({
+    path: updatePathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: updatePathParameters;
-} & ({
+}) & ({
+    query?: Partial<updateSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<updateSearchParameters>;
+    body?: Partial<updateFormParameters>;
+    /** @deprecated Use {@link Options.body} */
     params?: Partial<updateFormParameters>;
     strict?: false;
 } | {
+    query?: Partial<updateSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: updateSearchParameters;
+    body?: Partial<updateFormParameters>;
+    /** @deprecated Use {@link Options.body} */
     params: updateFormParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Assignments/Files/OriginalityReport/update.js

@@ -1,4 +1,4 @@
-import { client } from '../../../../../Client.js';
+import { client } from '#client';
 /**
  * Edit an Originality Report
  *

package/dist/Endpoints/Lti/Assignments/Submissions/History/get.d.ts

@@ -1,5 +1,5 @@
+import { Masquerade } from '#client';
 import { JSONValue } from '@battis/typescript-tricks';
-import { Masquerade } from '@groton/canvas-api.client.base';
 export type getPathParameters = {
     /**
      * ID
@@ -15,12 +15,19 @@ export type getPathParameters = {
     submission_id: string | number;
 };
 export type getSearchParameters = Masquerade;
-type Options = {
+type Options = ({
+    path: getPathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: getPathParameters;
-} & ({
+}) & ({
+    query?: Partial<getSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<getSearchParameters>;
     strict?: false;
 } | {
+    query?: Partial<getSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: getSearchParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Assignments/Submissions/History/get.js

@@ -1,4 +1,4 @@
-import { client } from '../../../../../Client.js';
+import { client } from '#client';
 /**
  * Get the history of a single submission
  *

package/dist/Endpoints/Lti/Assignments/Submissions/OriginalityReport/create.d.ts

@@ -1,4 +1,4 @@
-import { Masquerade } from '@groton/canvas-api.client.base';
+import { Masquerade } from '#client';
 import { OriginalityReport } from '../../../../../Resources/OriginalityReports.js';
 export type createPathParameters = {
     /**
@@ -83,14 +83,25 @@ export type createFormParameters = Masquerade & {
      */
     'originality_report[attempt]': number | string;
 };
-type Options = {
+type Options = ({
+    path: createPathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: createPathParameters;
-} & ({
+}) & ({
+    query?: Partial<createSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<createSearchParameters>;
+    body?: Partial<createFormParameters>;
+    /** @deprecated Use {@link Options.body} */
     params?: Partial<createFormParameters>;
     strict?: false;
 } | {
+    query?: Partial<createSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: createSearchParameters;
+    body?: Partial<createFormParameters>;
+    /** @deprecated Use {@link Options.body} */
     params: createFormParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Assignments/Submissions/OriginalityReport/create.js

@@ -1,4 +1,4 @@
-import { client } from '../../../../../Client.js';
+import { client } from '#client';
 /**
  * Create an Originality Report
  *

package/dist/Endpoints/Lti/Assignments/Submissions/OriginalityReport/show_originality_report_submissions.d.ts

@@ -1,4 +1,4 @@
-import { Masquerade } from '@groton/canvas-api.client.base';
+import { Masquerade } from '#client';
 import { OriginalityReport } from '../../../../../Resources/OriginalityReports.js';
 export type show_originality_report_submissionsPathParameters = {
     /**
@@ -21,12 +21,19 @@ export type show_originality_report_submissionsPathParameters = {
     id: string | number;
 };
 export type show_originality_report_submissionsSearchParameters = Masquerade;
-type Options = {
+type Options = ({
+    path: show_originality_report_submissionsPathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: show_originality_report_submissionsPathParameters;
-} & ({
+}) & ({
+    query?: Partial<show_originality_report_submissionsSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<show_originality_report_submissionsSearchParameters>;
     strict?: false;
 } | {
+    query?: Partial<show_originality_report_submissionsSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: show_originality_report_submissionsSearchParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Assignments/Submissions/OriginalityReport/show_originality_report_submissions.js

@@ -1,4 +1,4 @@
-import { client } from '../../../../../Client.js';
+import { client } from '#client';
 /**
  * Show an Originality Report
  *

package/dist/Endpoints/Lti/Assignments/Submissions/OriginalityReport/update.d.ts

@@ -1,4 +1,4 @@
-import { Masquerade } from '@groton/canvas-api.client.base';
+import { Masquerade } from '#client';
 import { OriginalityReport } from '../../../../../Resources/OriginalityReports.js';
 export type updatePathParameters = {
     /**
@@ -67,14 +67,25 @@ export type updateFormParameters = Masquerade & {
      */
     'originality_report[error_message]': string;
 };
-type Options = {
+type Options = ({
+    path: updatePathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: updatePathParameters;
-} & ({
+}) & ({
+    query?: Partial<updateSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<updateSearchParameters>;
+    body?: Partial<updateFormParameters>;
+    /** @deprecated Use {@link Options.body} */
     params?: Partial<updateFormParameters>;
     strict?: false;
 } | {
+    query?: Partial<updateSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: updateSearchParameters;
+    body?: Partial<updateFormParameters>;
+    /** @deprecated Use {@link Options.body} */
     params: updateFormParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Assignments/Submissions/OriginalityReport/update.js

@@ -1,4 +1,4 @@
-import { client } from '../../../../../Client.js';
+import { client } from '#client';
 /**
  * Edit an Originality Report
  *

package/dist/Endpoints/Lti/Assignments/Submissions/get.d.ts

@@ -1,5 +1,5 @@
+import { Masquerade } from '#client';
 import { JSONValue } from '@battis/typescript-tricks';
-import { Masquerade } from '@groton/canvas-api.client.base';
 export type getPathParameters = {
     /**
      * ID
@@ -15,12 +15,19 @@ export type getPathParameters = {
     submission_id: string | number;
 };
 export type getSearchParameters = Masquerade;
-type Options = {
+type Options = ({
+    path: getPathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: getPathParameters;
-} & ({
+}) & ({
+    query?: Partial<getSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<getSearchParameters>;
     strict?: false;
 } | {
+    query?: Partial<getSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: getSearchParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Assignments/Submissions/get.js

@@ -1,4 +1,4 @@
-import { client } from '../../../../Client.js';
+import { client } from '#client';
 /**
  * Get a single submission
  *

package/dist/Endpoints/Lti/Assignments/get.d.ts

@@ -1,4 +1,4 @@
-import { Masquerade } from '@groton/canvas-api.client.base';
+import { Masquerade } from '#client';
 import { LtiAssignment } from '../../../Resources/PlagiarismDetectionPlatformAssignments.js';
 export type getPathParameters = {
     /**
@@ -12,12 +12,19 @@ export type getSearchParameters = Masquerade & Partial<{
     /** The id of the user. Can be a Canvas or LTI id for the user. */
     user_id: string;
 }>;
-type Options = {
+type Options = ({
+    path: getPathParameters;
+} | {
+    /** @deprecated Use {@link Options.path} */
     pathParams: getPathParameters;
-} & ({
+}) & ({
+    query?: Partial<getSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams?: Partial<getSearchParameters>;
     strict?: false;
 } | {
+    query?: Partial<getSearchParameters>;
+    /** @deprecated Use {Options.query} */
     searchParams: getSearchParameters;
     strict: true;
 });

package/dist/Endpoints/Lti/Assignments/get.js

@@ -1,4 +1,4 @@
-import { client } from '../../../Client.js';
+import { client } from '#client';
 /**
  * Get a single assignment (lti)
  *