@eduware/oneroster 1.0.0

package/src/sdk/teachersmanagement.ts

@@ -0,0 +1,106 @@
+import { classesManagementAddTeacherToClass } from '../funcs/classesManagementAddTeacherToClass.js';
+import { classesManagementGetClassesForTeacher } from '../funcs/classesManagementGetClassesForTeacher.js';
+import { classesManagementGetTeachersForClass } from '../funcs/classesManagementGetTeachersForClass.js';
+import { schoolsManagementGetTeachersForClassInSchool } from '../funcs/schoolsManagementGetTeachersForClassInSchool.js';
+import { schoolsManagementGetTeachersForSchool } from '../funcs/schoolsManagementGetTeachersForSchool.js';
+import { teachersManagementGetAllTeachers } from '../funcs/teachersManagementGetAllTeachers.js';
+import { teachersManagementGetTeacher } from '../funcs/teachersManagementGetTeacher.js';
+import { ClientSDK, RequestOptions } from '../lib/sdks.js';
+import * as operations from '../models/operations/index.js';
+import { unwrapAsync } from '../types/fp.js';
+import { PageIterator, unwrapResultIterator } from '../types/operations.js';
+
+export class TeachersManagement extends ClientSDK {
+    /**
+     * Get teachers for a Class
+     *
+     * @remarks
+     * To get all teachers assigned to a specific Class. If the corresponding record cannot be located, the api will return a 404 error code and message 'Class not found.'
+     */
+    async getTeachersForClass(
+        request: operations.GetTeachersForClassRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetTeachersForClassResponse, { offset: number }>> {
+        return unwrapResultIterator(classesManagementGetTeachersForClass(this, request, options));
+    }
+
+    /**
+     * Add a teacher to a Class
+     *
+     * @remarks
+     * Enrolls a teacher to a specific Class. The responding system must return the set of sourcedIds that have been allocated to the newly created enrollment record.
+     */
+    async addTeacherToClass(
+        request: operations.AddTeacherToClassRequest,
+        options?: RequestOptions
+    ): Promise<operations.AddTeacherToClassResponse> {
+        return unwrapAsync(classesManagementAddTeacherToClass(this, request, options));
+    }
+
+    /**
+     * Get Teachers for a specific Class in a School
+     *
+     * @remarks
+     * To get all Teachers for a Class in a School on the service provider. If the specified school and/or class cannot be identified within the service provider, the api will return a 404 error code and message 'School or class not found.'
+     */
+    async getTeachersForClassInSchool(
+        request: operations.GetTeachersForClassInSchoolRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetTeachersForClassInSchoolResponse, { offset: number }>> {
+        return unwrapResultIterator(
+            schoolsManagementGetTeachersForClassInSchool(this, request, options)
+        );
+    }
+
+    /**
+     * Get all teachers for a school
+     *
+     * @remarks
+     * To get all Teachers for a School on the service provider. If the specified school cannot be identified within the service provider, the api will return a 404 error code and message 'School not found.'
+     */
+    async getTeachersForSchool(
+        request: operations.GetTeachersForSchoolRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetTeachersForSchoolResponse, { offset: number }>> {
+        return unwrapResultIterator(schoolsManagementGetTeachersForSchool(this, request, options));
+    }
+
+    /**
+     * Get all Teachers
+     *
+     * @remarks
+     * To get all Teachers on the service provider.
+     */
+    async getAllTeachers(
+        request: operations.GetAllTeachersRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetAllTeachersResponse, { offset: number }>> {
+        return unwrapResultIterator(teachersManagementGetAllTeachers(this, request, options));
+    }
+
+    /**
+     * Get a specific Teacher
+     *
+     * @remarks
+     * To get a specific Teacher on the service provider. If the corresponding record cannot be located, the api will return a 404 error code and message 'Teacher not found.'
+     */
+    async getTeacher(
+        request: operations.GetTeacherRequest,
+        options?: RequestOptions
+    ): Promise<operations.GetTeacherResponse> {
+        return unwrapAsync(teachersManagementGetTeacher(this, request, options));
+    }
+
+    /**
+     * Get Classes for a Teacher
+     *
+     * @remarks
+     * To get the set of Classes a Teacher is enrolled in. If the specified teacher cannot be identified within the service provider, the api will return a 404 error code and message 'Teacher not found.'
+     */
+    async getClassesForTeacher(
+        request: operations.GetClassesForTeacherRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetClassesForTeacherResponse, { offset: number }>> {
+        return unwrapResultIterator(classesManagementGetClassesForTeacher(this, request, options));
+    }
+}

package/src/sdk/termsmanagement.ts

@@ -0,0 +1,92 @@
+import { classesManagementGetClassesForTerm } from '../funcs/classesManagementGetClassesForTerm.js';
+import { schoolsManagementGetTermsForSchool } from '../funcs/schoolsManagementGetTermsForSchool.js';
+import { termsManagementCreateGradingPeriodForTerm } from '../funcs/termsManagementCreateGradingPeriodForTerm.js';
+import { termsManagementGetAllTerms } from '../funcs/termsManagementGetAllTerms.js';
+import { termsManagementGetGradingPeriodsForTerm } from '../funcs/termsManagementGetGradingPeriodsForTerm.js';
+import { termsManagementGetTerm } from '../funcs/termsManagementGetTerm.js';
+import { ClientSDK, RequestOptions } from '../lib/sdks.js';
+import * as operations from '../models/operations/index.js';
+import { unwrapAsync } from '../types/fp.js';
+import { PageIterator, unwrapResultIterator } from '../types/operations.js';
+
+export class TermsManagement extends ClientSDK {
+    /**
+     * Get all Terms for a School
+     *
+     * @remarks
+     * To get all Terms for a School on the service provider. If the specified school cannot be identified within the service provider, the api will return a 404 error code and message 'School not found.'
+     */
+    async getTermsForSchool(
+        request: operations.GetTermsForSchoolRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetTermsForSchoolResponse, { offset: number }>> {
+        return unwrapResultIterator(schoolsManagementGetTermsForSchool(this, request, options));
+    }
+
+    /**
+     * Get all Terms
+     *
+     * @remarks
+     * To get all Terms on the service provider.
+     */
+    async getAllTerms(
+        request: operations.GetAllTermsRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetAllTermsResponse, { offset: number }>> {
+        return unwrapResultIterator(termsManagementGetAllTerms(this, request, options));
+    }
+
+    /**
+     * Get a specific Term
+     *
+     * @remarks
+     * To get a specific Term on the service provider.
+     */
+    async getTerm(
+        request: operations.GetTermRequest,
+        options?: RequestOptions
+    ): Promise<operations.GetTermResponse> {
+        return unwrapAsync(termsManagementGetTerm(this, request, options));
+    }
+
+    /**
+     * Get Classes for a Term
+     *
+     * @remarks
+     * To get the set of Classes related to a specific Term. If the specified term cannot be identified within the service provider, the api will return a 404 error code and message 'Term not found.'
+     */
+    async getClassesForTerm(
+        request: operations.GetClassesForTermRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetClassesForTermResponse, { offset: number }>> {
+        return unwrapResultIterator(classesManagementGetClassesForTerm(this, request, options));
+    }
+
+    /**
+     * Get Grading Periods for a Term
+     *
+     * @remarks
+     * To get the set of Grading Periods related to a specific Term. If the specified Term cannot be identified within the service provider, the api will return a 404 error code and message 'Term not found.'
+     */
+    async getGradingPeriodsForTerm(
+        request: operations.GetGradingPeriodsForTermRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetGradingPeriodsForTermResponse, { offset: number }>> {
+        return unwrapResultIterator(
+            termsManagementGetGradingPeriodsForTerm(this, request, options)
+        );
+    }
+
+    /**
+     * Create a new Grading Period for a Term
+     *
+     * @remarks
+     * To create a new Grading Period for a Term. A Grading Period is a type of Academic Session. The responding system must return the set of sourcedIds that have been allocated to the newly created academicSession record.
+     */
+    async createGradingPeriodForTerm(
+        request: operations.CreateGradingPeriodForTermRequest,
+        options?: RequestOptions
+    ): Promise<operations.CreateGradingPeriodForTermResponse> {
+        return unwrapAsync(termsManagementCreateGradingPeriodForTerm(this, request, options));
+    }
+}

package/src/sdk/usersmanagement.ts

@@ -0,0 +1,104 @@
+import { classesManagementGetClassesForUser } from '../funcs/classesManagementGetClassesForUser.js';
+import { usersManagementCreateUser } from '../funcs/usersManagementCreateUser.js';
+import { usersManagementDeleteUser } from '../funcs/usersManagementDeleteUser.js';
+import { usersManagementGetAllUsers } from '../funcs/usersManagementGetAllUsers.js';
+import { usersManagementGetUser } from '../funcs/usersManagementGetUser.js';
+import { usersManagementGetUserWithDemographics } from '../funcs/usersManagementGetUserWithDemographics.js';
+import { usersManagementUpdateUser } from '../funcs/usersManagementUpdateUser.js';
+import { ClientSDK, RequestOptions } from '../lib/sdks.js';
+import * as operations from '../models/operations/index.js';
+import { unwrapAsync } from '../types/fp.js';
+import { PageIterator, unwrapResultIterator } from '../types/operations.js';
+
+export class UsersManagement extends ClientSDK {
+    /**
+     * Get all Users
+     *
+     * @remarks
+     * To get all Users on the service provider.
+     */
+    async getAllUsers(
+        request: operations.GetAllUsersRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetAllUsersResponse, { offset: number }>> {
+        return unwrapResultIterator(usersManagementGetAllUsers(this, request, options));
+    }
+
+    /**
+     * Create a new User
+     *
+     * @remarks
+     * To create a new User on the service provider. The responding system must return the set of sourcedIds that have been allocated to the newly created user record.
+     */
+    async createUser(
+        request: operations.CreateUserRequest,
+        options?: RequestOptions
+    ): Promise<operations.CreateUserResponse> {
+        return unwrapAsync(usersManagementCreateUser(this, request, options));
+    }
+
+    /**
+     * Get a specific User
+     *
+     * @remarks
+     * To get a specific User on the service provider.
+     */
+    async getUser(
+        request: operations.GetUserRequest,
+        options?: RequestOptions
+    ): Promise<operations.GetUserResponse> {
+        return unwrapAsync(usersManagementGetUser(this, request, options));
+    }
+
+    /**
+     * Update an existing User
+     *
+     * @remarks
+     * To update an existing User on the service provider. The sourcedId for the record to be updated is supplied by the requesting system.
+     */
+    async updateUser(
+        request: operations.UpdateUserRequest,
+        options?: RequestOptions
+    ): Promise<operations.UpdateUserResponse> {
+        return unwrapAsync(usersManagementUpdateUser(this, request, options));
+    }
+
+    /**
+     * Delete a User
+     *
+     * @remarks
+     * Perform a soft delete on a specific User on the service provider. This operation changes the status of the User to 'tobedeleted'.
+     */
+    async deleteUser(
+        request: operations.DeleteUserRequest,
+        options?: RequestOptions
+    ): Promise<void> {
+        return unwrapAsync(usersManagementDeleteUser(this, request, options));
+    }
+
+    /**
+     * Get a specific User with demographics
+     *
+     * @remarks
+     * To get a specific User with demographics on the service provider. If the corresponding record cannot be located, the api will return a 404 error code and message 'User not found.'
+     */
+    async getUserWithDemographics(
+        request: operations.GetUserWithDemographicsRequest,
+        options?: RequestOptions
+    ): Promise<operations.GetUserWithDemographicsResponse> {
+        return unwrapAsync(usersManagementGetUserWithDemographics(this, request, options));
+    }
+
+    /**
+     * Get Classes for a User
+     *
+     * @remarks
+     * To get the set of Classes a User is enrolled in.
+     */
+    async getClassesForUser(
+        request: operations.GetClassesForUserRequest,
+        options?: RequestOptions
+    ): Promise<PageIterator<operations.GetClassesForUserResponse, { offset: number }>> {
+        return unwrapResultIterator(classesManagementGetClassesForUser(this, request, options));
+    }
+}

package/src/types/async.ts

@@ -0,0 +1,53 @@
+export type APICall =
+    | {
+          status: 'complete';
+          request: Request;
+          response: Response;
+      }
+    | {
+          status: 'request-error';
+          request: Request;
+          response?: undefined;
+      }
+    | {
+          status: 'invalid';
+          request?: undefined;
+          response?: undefined;
+      };
+
+export class APIPromise<T> implements Promise<T> {
+    readonly #promise: Promise<[T, APICall]>;
+    readonly #unwrapped: Promise<T>;
+
+    readonly [Symbol.toStringTag] = 'APIPromise';
+
+    constructor(p: [T, APICall] | Promise<[T, APICall]>) {
+        this.#promise = p instanceof Promise ? p : Promise.resolve(p);
+        this.#unwrapped =
+            p instanceof Promise ? this.#promise.then(([value]) => value) : Promise.resolve(p[0]);
+    }
+
+    then<TResult1 = T, TResult2 = never>(
+        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined
+    ): Promise<TResult1 | TResult2> {
+        return this.#promise.then(
+            onfulfilled ? ([value]) => onfulfilled(value) : void 0,
+            onrejected
+        );
+    }
+
+    catch<TResult = never>(
+        onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined
+    ): Promise<T | TResult> {
+        return this.#unwrapped.catch(onrejected);
+    }
+
+    finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+        return this.#unwrapped.finally(onfinally);
+    }
+
+    $inspect(): Promise<[T, APICall]> {
+        return this.#promise;
+    }
+}

package/src/types/blobs.ts

@@ -0,0 +1,26 @@
+import * as z from 'zod';
+
+export const blobLikeSchema: z.ZodType<Blob, z.ZodTypeDef, Blob> = z.custom<Blob>(isBlobLike, {
+    message: 'expected a Blob, File or Blob-like object',
+    fatal: true,
+});
+
+export function isBlobLike(val: unknown): val is Blob {
+    if (val instanceof Blob) {
+        return true;
+    }
+
+    if (typeof val !== 'object' || val == null || !(Symbol.toStringTag in val)) {
+        return false;
+    }
+
+    const name = val[Symbol.toStringTag];
+    if (typeof name !== 'string') {
+        return false;
+    }
+    if (name !== 'Blob' && name !== 'File') {
+        return false;
+    }
+
+    return 'stream' in val && typeof val.stream === 'function';
+}

package/src/types/constdatetime.ts

@@ -0,0 +1,7 @@
+import * as z from 'zod';
+
+export function constDateTime(val: string): z.ZodType<string, z.ZodTypeDef, unknown> {
+    return z.custom<string>((v) => {
+        return typeof v === 'string' && new Date(v).getTime() === new Date(val).getTime();
+    }, `Value must be equivalent to ${val}`);
+}

package/src/types/enums.ts

@@ -0,0 +1,12 @@
+declare const __brand: unique symbol;
+export type Unrecognized<T> = T & { [__brand]: 'unrecognized' };
+
+export function catchUnrecognizedEnum<T>(value: T): Unrecognized<T> {
+    return value as Unrecognized<T>;
+}
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+export type ClosedEnum<T> = T[keyof T];
+export type OpenEnum<T> =
+    | Prettify<T[keyof T]>
+    | Unrecognized<T[keyof T] extends number ? number : string>;

package/src/types/fp.ts

@@ -0,0 +1,44 @@
+/**
+ * A monad that captures the result of a function call or an error if it was not
+ * successful. Railway programming, enabled by this type, can be a nicer
+ * alternative to traditional exception throwing because it allows functions to
+ * declare all _known_ errors with static types and then check for them
+ * exhaustively in application code. Thrown exception have a type of `unknown`
+ * and break out of regular control flow of programs making them harder to
+ * inspect and more verbose work with due to try-catch blocks.
+ */
+export type Result<T, E = unknown> =
+    | { ok: true; value: T; error?: never }
+    | { ok: false; value?: never; error: E };
+
+export function OK<V>(value: V): Result<V, never> {
+    return { ok: true, value };
+}
+
+export function ERR<E>(error: E): Result<never, E> {
+    return { ok: false, error };
+}
+
+/**
+ * unwrap is a convenience function for extracting a value from a result or
+ * throwing if there was an error.
+ */
+export function unwrap<T>(r: Result<T, unknown>): T {
+    if (!r.ok) {
+        throw r.error;
+    }
+    return r.value;
+}
+
+/**
+ * unwrapAsync is a convenience function for resolving a value from a Promise
+ * of a result or rejecting if an error occurred.
+ */
+export async function unwrapAsync<T>(pr: Promise<Result<T, unknown>>): Promise<T> {
+    const r = await pr;
+    if (!r.ok) {
+        throw r.error;
+    }
+
+    return r.value;
+}

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export { blobLikeSchema, isBlobLike } from './blobs.js';
+export type { ClosedEnum, OpenEnum, Unrecognized } from './enums.js';
+export { catchUnrecognizedEnum } from './enums.js';
+export type { Result } from './fp.js';
+export type { PageIterator, Paginator } from './operations.js';
+export { createPageIterator } from './operations.js';
+export { RFCDate } from './rfcdate.js';

package/src/types/operations.ts

@@ -0,0 +1,97 @@
+import { Result } from './fp.js';
+
+export type Paginator<V> = () => Promise<V & { next: Paginator<V> }> | null;
+
+export type PageIterator<V, PageState = unknown> = V & {
+    next: Paginator<V>;
+    [Symbol.asyncIterator]: () => AsyncIterableIterator<V>;
+    '~next'?: PageState | undefined;
+};
+
+export function createPageIterator<V>(
+    page: V & { next: Paginator<V> },
+    halt: (v: V) => boolean
+): {
+    [Symbol.asyncIterator]: () => AsyncIterableIterator<V>;
+} {
+    return {
+        [Symbol.asyncIterator]: async function* paginator() {
+            yield page;
+            if (halt(page)) {
+                return;
+            }
+
+            let p: typeof page | null = page;
+            for (p = await p.next(); p != null; p = await p.next()) {
+                yield p;
+                if (halt(p)) {
+                    return;
+                }
+            }
+        },
+    };
+}
+
+/**
+ * This utility create a special iterator that yields a single value and
+ * terminates. It is useful in paginated SDK functions that have early return
+ * paths when things go wrong.
+ */
+export function haltIterator<V extends object>(v: V): PageIterator<V, undefined> {
+    return {
+        ...v,
+        next: () => null,
+        [Symbol.asyncIterator]: async function* paginator() {
+            yield v;
+        },
+    };
+}
+
+/**
+ * Converts an async iterator of `Result<V, E>` into an async iterator of `V`.
+ * When error results occur, the underlying error value is thrown.
+ */
+export async function unwrapResultIterator<V, PageState>(
+    iteratorPromise: Promise<PageIterator<Result<V, unknown>, PageState>>
+): Promise<PageIterator<V, PageState>> {
+    const resultIter = await iteratorPromise;
+
+    if (!resultIter.ok) {
+        throw resultIter.error;
+    }
+
+    return {
+        ...resultIter.value,
+        next: unwrapPaginator(resultIter.next),
+        '~next': resultIter['~next'],
+        [Symbol.asyncIterator]: async function* paginator() {
+            for await (const page of resultIter) {
+                if (!page.ok) {
+                    throw page.error;
+                }
+                yield page.value;
+            }
+        },
+    };
+}
+
+function unwrapPaginator<V>(paginator: Paginator<Result<V, unknown>>): Paginator<V> {
+    return () => {
+        const nextResult = paginator();
+        if (nextResult == null) {
+            return null;
+        }
+        return nextResult.then((res) => {
+            if (!res.ok) {
+                throw res.error;
+            }
+            const out = {
+                ...res.value,
+                next: unwrapPaginator(res.next),
+            };
+            return out;
+        });
+    };
+}
+
+export const URL_OVERRIDE = Symbol('URL_OVERRIDE');

package/src/types/rfcdate.ts

@@ -0,0 +1,48 @@
+const dateRE = /^\d{4}-\d{2}-\d{2}$/;
+
+export class RFCDate {
+    private serialized: string;
+
+    /**
+     * Creates a new RFCDate instance using today's date.
+     */
+    static today(): RFCDate {
+        return new RFCDate(new Date());
+    }
+
+    /**
+     * Creates a new RFCDate instance using the provided input.
+     * If a string is used then in must be in the format YYYY-MM-DD.
+     *
+     * @param date A Date object or a date string in YYYY-MM-DD format
+     * @example
+     * new RFCDate("2022-01-01")
+     * @example
+     * new RFCDate(new Date())
+     */
+    constructor(date: Date | string) {
+        if (typeof date === 'string' && !dateRE.test(date)) {
+            throw new RangeError('RFCDate: date strings must be in the format YYYY-MM-DD: ' + date);
+        }
+
+        const value = new Date(date);
+        if (isNaN(+value)) {
+            throw new RangeError('RFCDate: invalid date provided: ' + date);
+        }
+
+        this.serialized = value.toISOString().slice(0, 'YYYY-MM-DD'.length);
+        if (!dateRE.test(this.serialized)) {
+            throw new TypeError(
+                `RFCDate: failed to build valid date with given value: ${date} serialized to ${this.serialized}`
+            );
+        }
+    }
+
+    toJSON(): string {
+        return this.toString();
+    }
+
+    toString(): string {
+        return this.serialized;
+    }
+}

package/src/types/streams.ts

@@ -0,0 +1,15 @@
+export function isReadableStream<T = Uint8Array>(val: unknown): val is ReadableStream<T> {
+    if (typeof val !== 'object' || val === null) {
+        return false;
+    }
+
+    // Check for the presence of methods specific to ReadableStream
+    const stream = val as ReadableStream<Uint8Array>;
+
+    // ReadableStream has methods like getReader, cancel, and tee
+    return (
+        typeof stream.getReader === 'function' &&
+        typeof stream.cancel === 'function' &&
+        typeof stream.tee === 'function'
+    );
+}