@groton/veracross-api 0.0.1 → 0.0.2

package/dist/spec/Authorization-API.d.ts

@@ -0,0 +1,628 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/oauth/token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create Access Token
+         * @description All requests to the Data API must be made with an access token. Review [Access Tokens](../../../../docs/concepts/access-tokens.md) for additional details.
+         *
+         *     #### Endpoint applies to:
+         *
+         *     | Grant Type | Applicable |
+         *     |------------|------------|
+         *     | Client Credentials | ✅ |
+         *     | Authorization Code | ✅ |
+         *     | Refresh Token      | ✅ |
+         *
+         *     #### Related links
+         *     - https://tools.ietf.org/html/rfc6749#section-3.2
+         *     - https://www.oauth.com/oauth2-servers/accessing-data/obtaining-an-access-token/
+         *     - https://www.oauth.com/oauth2-servers/making-authenticated-requests/refreshing-an-access-token/
+         */
+        post: operations["create-access-token"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/oauth/introspect": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Token Introspection
+         * @description The Token Introspection extension defines a mechanism for resource servers to obtain information about access tokens. With this spec, resource servers can check the validity of access tokens, and find out other information such as which user and which scopes are associated with the token.
+         *
+         *     #### Endpoint applies to:
+         *
+         *     | Grant Type | Applicable |
+         *     |------------|------------|
+         *     | Client Credentials | ✅ |
+         *     | Authorization Code | ✅ |
+         *     | Refresh Token      | ✅ |
+         *
+         *     #### Related links
+         *     - https://tools.ietf.org/html/rfc7662
+         *     - https://www.oauth.com/oauth2-servers/token-introspection-endpoint/
+         *     - https://oauth.net/2/token-introspection/
+         */
+        post: operations["post-oauth-introspect"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/oauth/revoke": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Revoke Token
+         * @description Post with client credentials to revoke an access token. The authorization server responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.
+         *
+         *     <!-- theme: warning -->
+         *     > Note: per the OAuth spec, attempting to revoke an invalid token has no effect.
+         *
+         *     The content of the response body should be ignored by the client as all necessary information is conveyed in the response code.
+         *
+         *     A revoked token can no longer be used for any other endpoint. The response codes/bodies may vary depending on the endpoint. For example, Token Info (`GET /oauth/token/info`) returns `401 Unauthorized`, whereas Token Introspection (`POST /oauth/introspect`) still returns `200 OK`, but `active: false` in the body.
+         *
+         *     #### Endpoint applies to:
+         *     | Grant Type | Applicable |
+         *     |------------|------------|
+         *     | Client Credentials | ✅ |
+         *     | Authorization Code | ✅ |
+         *     | Refresh Token      | ✅ |
+         *
+         *     #### Related links
+         *     - https://tools.ietf.org/html/rfc7009
+         *     - https://www.oauth.com/oauth2-servers/listing-authorizations/revoking-access/
+         *     - https://oauth.net/2/token-revocation/
+         */
+        post: operations["post-oauth-revoke"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/oauth/authorize": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Authorize
+         * @description This endpoint starts the OAuth SSO flow. The response is an HTML page intended for humans (in contrast to other endpoints, which are intended for servers). Users can log in to a vendor site with their existing Veracross account.
+         *
+         *     <!--
+         *     focus: false
+         *     -->
+         *     ![A Veracross login page](https://assets.veracross.com/_documentation/api/images/vc-login-page.png)
+         *
+         *     As a vendor, you need to formulate this URL with the proper parameters:
+         *     1. The `client_id` string that identifies your site as a Veracross OAuth Application.
+         *     2. One of the already registered `redirect_uri` that Veracross will redirect users to upon successful login (remember, this value should be URL encoded in the request).
+         *     3. `response_type=code`, which means that upon successful login, Veracross systems will also give you an **authorization code** that you will use to exchange for an **access token** to use with subsequent requests.
+         *     4. The `scope`, which specifies a list of scopes, separated by spaces, for the scopes for which you want to authorize the user, for example `scope = sso`.
+         *
+         *     > Note: Using SSO requires having an OAuth Application [registered at each school](https://community.veracross.com/s/article/Creating-an-OAuth-Application-School-Workflow). Vendors must provide the `redirect_uri`s and `scope`s they require, and will receive the corresponding OAuth `client_id` and `client_secret` values.
+         *
+         *     Unlike most public OAuth implementations (eg, "Log In with Facebook", "Log In with Google", etc), Veracross users won't see a separate "approval" screen when logging in. This is intentional; at Veracross, SSO to a vendor site is pre-approved with the set up of the OAuth Application by an administrator, and no separate approval from end users is necessary.
+         *
+         *     #### Endpoint applies to:
+         *
+         *     | Grant Type | Applicable |
+         *     |------------|------------|
+         *     | Client Credentials | ❌ |
+         *     | Authorization Code | ✅ |
+         *     | Refresh Token      | ❌ |
+         *
+         *     #### Related links:
+         *     - https://tools.ietf.org/html/rfc6749#section-3.1
+         *     - https://www.oauth.com/oauth2-servers/accessing-data/authorization-request/
+         */
+        get: operations["get-oauth-authorize"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/oauth/userinfo": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * User Info
+         * @description The access token is used to retrieve info about the user that has logged in, such as their Veracross Account ID and username.
+         *
+         *     > Note: `sub` is the internal account id, and uniquely identifies a user at a school. It must be combined with the school route to become globally unique. For example, different users at different schools might have the same `sub` value. Also note that schools may configure their own format for `preferred_username`, so it should only be used for display purposes (eg, some schools use email, some schools use other id's, etc)
+         *
+         *     #### Endpoint applies to:
+         *
+         *     | Grant Type | Applicable |
+         *     |------------|------------|
+         *     | Client Credentials | ❌ |
+         *     | Authorization Code | ✅ |
+         *     | Refresh Token      | ❌ |
+         *
+         *     #### Related links
+         *     - https://www.oauth.com/oauth2-servers/signing-in-with-google/verifying-the-user-info/
+         *     - https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
+         *     - https://community.veracross.com/s/article/Person-Role-Definitions
+         */
+        get: operations["get-oauth-userinfo"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/oauth/discovery/keys": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * JSON Web Key Set (JWKS)
+         * @description The JSON Web Key Set (JWKS) endpoint returns the public keys used to verify JSON Web Tokens (JWTs) issued by the authorization server.
+         *     This endpoint is commonly used in OpenID Connect 1.0 (OIDC) flows to verify the authenticity and integrity of ID tokens.
+         *
+         *     #### Related links
+         *     - https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+         *     - https://www.rfc-editor.org/rfc/rfc7517.html
+         *     - https://datatracker.ietf.org/doc/html/rfc7518
+         *     - https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationExamples
+         */
+        get: operations["jwks"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/.well-known/openid-configuration": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * OpenID Provider Configuration
+         * @description The OpenID Provider Configuration endpoint provides metadata about the OpenID Provider (OP). This metadata includes information such as the issuer identifier, authorization endpoint, token endpoint, userinfo endpoint, and supported scopes and claims.
+         *
+         *     Clients can use this metadata to dynamically configure themselves to interact with the OP without requiring manual configuration.
+         *
+         *     #### Related links
+         *     - https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest
+         *     - https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+         */
+        get: operations["openid-configuration"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        ErrorResponse: {
+            /** @description An error code */
+            error: string;
+            /** @description The description of the error */
+            error_description: string;
+            /** @description A unique ID for this specific error. Please provide this error id when you ask for help with an error. */
+            error_id?: string;
+        };
+        EmptyObject: Record<string, never>;
+    };
+    responses: {
+        /** @description Unauthorized */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /**
+         * @description Unsupported media type.
+         *     This happens when the requests lacks the header `application/x-www-form-urlencoded`.
+         */
+        UnsupportedMediaType: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["EmptyObject"];
+            };
+        };
+    };
+    parameters: {
+        /** @description Needs to be `application/x-www-form-urlencoded` */
+        ContentTypeFormUrlEncoded: string;
+    };
+    requestBodies: {
+        TokenAndCredentials: {
+            content: {
+                "application/x-www-form-urlencoded": {
+                    client_id: string;
+                    client_secret: string;
+                    token: string;
+                };
+            };
+        };
+    };
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    "create-access-token": {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Needs to be `application/x-www-form-urlencoded` */
+                "Content-Type": components["parameters"]["ContentTypeFormUrlEncoded"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * @description <!--
+         *     type: tab
+         *     title: Client Credentials
+         *     -->
+         *     #### Client Credentials
+         *     This grant type is suitable for "server to server" authentication where data access happens independent of any specific user's session.
+         *
+         *     <!--
+         *     type: tab
+         *     title: Authorization Code
+         *     -->
+         *     #### Authorization Code
+         *     This grant type should be used during SSO to exchange the provided authorization code for an access token that is associated with an individual user. Review [Creating a SSO integration](../../../../docs/guides/creating-an-sso-integration.md) for additional details.
+         *
+         *     <!--
+         *     type: tab
+         *     title: Refresh Token
+         *     -->
+         *     #### Refresh Token
+         *     This grant type is used to create a new access token when the former access token has expired. Refresh Tokens should only be used once.
+         *     <!-- type: tab-end -->
+         */
+        requestBody?: {
+            content: {
+                "application/x-www-form-urlencoded": {
+                    /** @enum {string} */
+                    grant_type: "client_credentials" | "authorization_code" | "refresh_token";
+                    client_id: string;
+                    /** @description required for all grant types. Treat the client_secret as confidential. */
+                    client_secret: string;
+                    /** @description list of scopes for this access token */
+                    scope?: string;
+                    /** @description required only for authorization_code as grant_type */
+                    code?: string;
+                    /** @description required only for authorization_code as grant_type */
+                    redirect_uri?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Success */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        access_token: string;
+                        created_at: number;
+                        expires_in: number;
+                        scope: string;
+                        refresh_token?: string;
+                        token_type: string;
+                        /** @description JWT string returned only with the Authorization Code grant type when the `openid` scope is requested. The JWT contains the user info (equivalent to the User Info endpoint). The JWT's signature may be verified using the public key provided by the JWKS endpoint. */
+                        id_token?: string;
+                    };
+                };
+            };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            415: components["responses"]["UnsupportedMediaType"];
+        };
+    };
+    "post-oauth-introspect": {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Needs to be `application/x-www-form-urlencoded` */
+                "Content-Type": components["parameters"]["ContentTypeFormUrlEncoded"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: components["requestBodies"]["TokenAndCredentials"];
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        active: boolean;
+                        scope?: string;
+                        /** @description null when used on token issued with authorization_code as grant_type */
+                        client_id?: string | null;
+                        token_type?: string;
+                        exp?: number;
+                        iat?: number;
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            415: components["responses"]["UnsupportedMediaType"];
+        };
+    };
+    "post-oauth-revoke": {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Needs to be `application/x-www-form-urlencoded` */
+                "Content-Type": components["parameters"]["ContentTypeFormUrlEncoded"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: components["requestBodies"]["TokenAndCredentials"];
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["EmptyObject"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            415: components["responses"]["UnsupportedMediaType"];
+        };
+    };
+    "get-oauth-authorize": {
+        parameters: {
+            query: {
+                /** @description This is the client_id from your OAuth Application. It will be different for each school that you work with. */
+                client_id: string;
+                /**
+                 * @description Veracross will redirect to this URI upon successful login. It needs to be URL encoded, HTTPS, and registered on your OAuth Application.
+                 *
+                 *     It redirects with the `code` parameter which will be exchanged for the `access_token`.
+                 */
+                redirect_uri: string;
+                /** @description Needs to be `code` */
+                response_type: string;
+                /** @description List of requested scopes (separated by spaces). To complete SSO, the `sso` scope must be requested. All requested scopes must already be enabled by the school on your OAuth Application. */
+                scope: string;
+            };
+            header: {
+                /** @description Needs to be `application/x-www-form-urlencoded` */
+                "Content-Type": components["parameters"]["ContentTypeFormUrlEncoded"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Responds HTML with Veracross login form if the browser isn't authorized yet. Otherwise it goes directly to the `redirect_uri` */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    "get-oauth-userinfo": {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description The access token */
+                Authorization: string;
+                /** @description Needs to be `application/x-www-form-urlencoded` */
+                "Content-Type": components["parameters"]["ContentTypeFormUrlEncoded"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        sub: string;
+                        preferred_username: string;
+                        email?: string | null;
+                        roles?: string[] | null;
+                    };
+                };
+            };
+            /** @description Unauthorized */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": unknown;
+                };
+            };
+            /**
+             * @description Forbidden.
+             *     This happens when the access token lacks a required scope.
+             */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /**
+             * @description Not Found.
+             *     There was no user associated with the provided access token. This can happen if the request uses an access token created with the Client Credentials grant type; since those exist apart from an individual user identity, there's no user info that can be provided. User info requests should only be made with Authorization Code access tokens.
+             */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            415: components["responses"]["UnsupportedMediaType"];
+        };
+    };
+    jwks: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        keys: {
+                            /** @description Key type parameter identifies the cryptographic algorithm family used with the key, such as "RSA" or "EC" */
+                            kty: string;
+                            /** @description Modulus parameter of the RSA public key */
+                            n?: string;
+                            /** @description Exponent parameter of the RSA public key */
+                            e?: string;
+                            /** @description Key ID parameter is used to match a specific key. It is typically used to identify the key in a set of keys */
+                            kid: string;
+                            /**
+                             * @description Intended use of the public key, such as "sig" for signature or "enc" for encryption
+                             * @enum {string}
+                             */
+                            use: "sig" | "enc";
+                            /** @description Algorithm intended for use with the key, such as "RS256" for RSA SHA-256 */
+                            alg: string;
+                        }[];
+                    };
+                };
+            };
+        };
+    };
+    "openid-configuration": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description Issuer URL */
+                        issuer: string;
+                        /** @description Authorization endpoint URL */
+                        authorization_endpoint: string;
+                        /** @description Token endpoint URL */
+                        token_endpoint: string;
+                        /** @description Revocation endpoint URL */
+                        revocation_endpoint?: string;
+                        /** @description Introspection endpoint URL */
+                        introspection_endpoint?: string;
+                        /** @description User Info endpoint URL */
+                        userinfo_endpoint?: string;
+                        /** @description JWKS endpoint URL */
+                        jwks_uri: string;
+                        /** @description List of supported scopes (this might not be an exhaustive list) */
+                        scopes_supported?: string[];
+                        /** @description List of supported OAuth2 `response_type` values */
+                        response_types_supported: string[];
+                        /** @description List of supported Oauth2 `response_mode` values */
+                        response_modes_supported?: string[];
+                        /** @description List of supported OAuth2 `grant_type` values */
+                        grant_types_supported?: string[];
+                        /** @description List of supported OAuth2 Client Authentication methods in the token endpoint */
+                        token_endpoint_auth_methods_supported?: string[];
+                        /** @description List of supported Subject Identifier types */
+                        subject_types_supported: string[];
+                        /** @description List of supported JWS signing algorithms (`alg` values) for the ID token */
+                        id_token_signing_alg_values_supported: string[];
+                        /** @description List of supported Claim Types */
+                        claim_types_supported?: string[];
+                        /** @description List of supported Claim Names we MAY be able to supply values for (this might not be an exhaustive list) */
+                        claims_supported?: string[];
+                    };
+                };
+            };
+        };
+    };
+}

package/dist/spec/Authorization-API.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/spec/Data-API.d.ts

@@ -28993,7 +28993,7 @@ export interface operations {
                             /**
                              * @description Internal Location Resource Description
                              *
-                             *     The description of the internal resource for this event. If no resource is assigned, returns an empty string.
+                             *     The description of the internal resource for this event.
                              */
                             readonly location: string;
                             /** @description Depart From */
@@ -29200,7 +29200,7 @@ export interface operations {
                         /**
                          * @description Internal Location Resource Description
                          *
-                         *     The description of the internal resource for this event. If no resource is assigned, returns an empty string.
+                         *     The description of the internal resource for this event.
                          */
                         readonly location?: string;
                         /** @description Depart From */
@@ -29413,7 +29413,7 @@ export interface operations {
                             /**
                              * @description Internal Location Resource Description
                              *
-                             *     The description of the internal resource for this event. If no resource is assigned, returns an empty string.
+                             *     The description of the internal resource for this event.
                              */
                             readonly location: string;
                             /** @description Depart From */
@@ -29623,7 +29623,7 @@ export interface operations {
                         /**
                          * @description Internal Location Resource Description
                          *
-                         *     The description of the internal resource for this event. If no resource is assigned, returns an empty string.
+                         *     The description of the internal resource for this event.
                          */
                         readonly location?: string;
                         /** @description Depart From */