@leaddreamer/inventorylogic 0.0.3-beta.94 → 0.0.3-beta.95

package/README.md

@@ -22,6 +22,9 @@ frontEnd and NodeJS BackEnd</p>
 <dt><a href="#module_Addresses">Addresses</a></dt>
 <dd><p>Types and functins for handling addresses</p>
 </dd>
+<dt><a href="#module_AuthMachine">AuthMachine</a></dt>
+<dd><p>Typedefs and functions for an oAuth authentication generator</p>
+</dd>
 <dt><a href="#module_BusinessData">BusinessData</a></dt>
 <dd><p>Functions for managing (potentially)private data for an organization.
 Unified structure as a sub-record of organization, or CityManager accounts</p>
@@ -66,6 +69,10 @@ Unified structure as a sub-record of fan, organization, or CityManager accounts<
 <dt><a href="#module_SquarespaceProduct">SquarespaceProduct</a></dt>
 <dd><p>Typedefs, constants, support functions and database operations related to Products</p>
 </dd>
+<dt><a href="#module_Services">Services</a></dt>
+<dd><p>Typedefs, constants, support functions and database operations related to supported Services Matrials
+users</p>
+</dd>
 <dt><a href="#module_User">User</a></dt>
 <dd><p>Typedefs, constants, support functions and database operations related to individual
 users</p>
@@ -352,6 +359,143 @@ Fetches all address records for an account
 
 ### Addresses~ChainType : <code>WriteBatch</code> \| <code>Transaction</code> \| <code>void</code>
 **Kind**: inner typedef of [<code>Addresses</code>](#module_Addresses)  
+<a name="module_AuthMachine"></a>
+
+## AuthMachine
+Typedefs and functions for an oAuth authentication generator
+
+
+* [AuthMachine](#module_AuthMachine)
+    * [~GenerateAuthUrlOpts](#module_AuthMachine..GenerateAuthUrlOpts) : <code>object</code>
+    * [~TokenInfo](#module_AuthMachine..TokenInfo) : <code>object</code>
+    * [~OAuth2ClientEndpoints](#module_AuthMachine..OAuth2ClientEndpoints) : <code>object</code>
+    * [~OAuth2ClientOptions](#module_AuthMachine..OAuth2ClientOptions) : <code>object</code>
+    * [~initOAuthManager](#module_AuthMachine..initOAuthManager) ⇒ <code>OAuth2Client</code>
+
+<a name="module_AuthMachine..GenerateAuthUrlOpts"></a>
+
+### AuthMachine~GenerateAuthUrlOpts : <code>object</code>
+Options object for GenerateAuthUrl
+
+**Kind**: inner typedef of [<code>AuthMachine</code>](#module_AuthMachine)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| access_type | <code>&quot;online&quot;</code> \| <code>&quot;offline&quot;</code> | Recommended. Indicates whether your application can refresh access tokens when the user is not present at the browser. Valid parameter values are 'online', which is the default value, and 'offline'. Set the value to 'offline' if your application needs to refresh access tokens when the user is not present at the browser. This value instructs the Google authorization server to return a refresh token and an access token the first time that your application exchanges an authorization code for tokens. |
+| hd | <code>string</code> | The hd (hosted domain) parameter streamlines the login process for G Suite hosted accounts. By including the domain of the G Suite user (for example, mycollege.edu), you can indicate that the account selection UI should be optimized for accounts at that domain. To optimize for G Suite accounts generally instead of just one domain, use an asterisk: hd=*. Don't rely on this UI optimization to control who can access your app, as client-side requests can be modified. Be sure to validate that the returned ID token has an hd claim value that matches what you expect (e.g. mycolledge.edu). Unlike the request parameter, the ID token claim is contained within a security token from Google, so the value can be trusted. |
+| response_type | <code>&quot;CODE&quot;</code> | The 'response_type' will always be set to 'CODE'. |
+| client_id | <code>string</code> | The client ID for your application. The value passed into the constructor will be used if not provided. You can find this value in the API Console. |
+| redirect_url | <code>URL</code> | Determines where the API server redirects the user after the user completes the authorization flow. The value must exactly match one of the 'redirect_uri' values listed for your project in the API Console. Note that the http or https scheme, case, and trailing slash ('/') must all match. The value passed into the constructor will be used if not provided. |
+| scope | <code>Array.string</code> \| <code>string</code> | Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. These values inform the consent screen that Google displays to the user. Scopes enable your application to only request access to the resources that it needs while also enabling users to control the amount of access that they grant to your application. Thus, there is an inverse relationship between the number of scopes requested and the likelihood of obtaining user consent. The OAuth 2.0 API Scopes document provides a full list of scopes that you might use to access Google APIs. We recommend that your application request access to authorization scopes in context whenever possible. By requesting access to user data in context, via incremental authorization, you help users to more easily understand why your application needs the access it is requesting. |
+| state | <code>string</code> | Recommended. Specifies any string value that your application uses to maintain state between your authorization request and the authorization server's response. The server returns the exact value that you send as a name=value pair in the hash (#) fragment of the 'redirect_uri' after the user consents to or denies your application's access request. You can use this parameter for several purposes, such as directing the user to the correct resource in your application, sending nonces, and mitigating cross-site request forgery. Since your redirect_uri can be guessed, using a state value can increase your assurance that an incoming connection is the result of an authentication request. If you generate a random string or encode the hash of a cookie or another value that captures the client's state, you can validate the response to additionally ensure that the request and response originated in the same browser, providing protection against attacks such as cross-site request forgery. See the OpenID Connect documentation for an example of how to create and confirm a state token. |
+| include_granted_scopes | <code>boolean</code> | Optional. Enables applications to use incremental authorization to request access to additional scopes in context. If you set this parameter's value to true and the authorization request is granted, then the new access token will also cover any scopes to which the user previously granted the application access. See the incremental authorization section for examples. |
+| login_hint | <code>tring</code> | Optional. If your application knows which user is trying to authenticate, it can use this parameter to provide a hint to the Google Authentication Server. The server uses the hint to simplify the login flow either by prefilling the email field in the sign-in form or by selecting the appropriate multi-login session. Set the parameter value to an email address or sub identifier, which is equivalent to the user's Google ID. |
+| prompt | <code>&quot;none&quot;</code> \| <code>&quot;consent&quot;</code> \| <code>&quot;select\_account&quot;</code> | Optional. A space-delimited, case-sensitive list of prompts to present the user. If you don't specify this parameter, the user will be prompted only the first time your app requests access.  Possible values are: 'none' - Donot display any authentication or consent screens. Must not be        specified with other values. 'consent' - 	Prompt the user for consent. 'select_account' - Prompt the user to select an account. |
+| code_challenge_method | <code>&quot;plain&quot;</code> \| <code>&quot;S256&quot;</code> | Recommended. Specifies what method was used to encode a 'code_verifier' that will be used during authorization code exchange. This parameter must be used with the 'code_challenge' parameter. The value of the 'code_challenge_method' defaults to "plain" if not present in the request that includes a 'code_challenge'. The only supported values for this parameter are "S256" or "plain". |
+| code_challenge | <code>string</code> | Recommended. Specifies an encoded 'code_verifier' that will be used as a server-side challenge during authorization code exchange. This parameter must be used with the 'code_challenge' parameter described above. |
+| keyValues | <code>Array.object</code> | A way for developers and/or the auth team to provide a set of key value pairs to be added as query parameters to the authorization url. |
+| keyValues.key | <code>string</code> |  |
+| keyValues.value | <code>string</code> |  |
+
+<a name="module_AuthMachine..TokenInfo"></a>
+
+### AuthMachine~TokenInfo : <code>object</code>
+Description of TokenInfo returned by oAuth manager
+
+**Kind**: inner typedef of [<code>AuthMachine</code>](#module_AuthMachine)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| aud | <code>string</code> | The application that is the intended user of the access token. |
+| user_id | <code>string</code> | This value lets you correlate profile information from multiple Google APIs. It is only present in the response if you included the profile scope in your request in step 1. The field value is an immutable identifier for the logged-in user that can be used to create and manage user sessions in your application. The identifier is the same regardless of which client ID is used to retrieve it. This enables multiple applications in the same organization to correlate profile information. |
+| scopes | <code>Array.string</code> | An array of scopes that the user granted access to. |
+| expiry_date | <code>number</code> | The datetime when the token becomes invalid. |
+| sub | <code>string</code> | An identifier for the user, unique among all Google accounts and never reused. A Google account can have multiple emails at different points in time, but the sub value is never changed. Use sub within your application as the unique-identifier key for the user. |
+| azp | <code>string</code> | The client_id of the authorized presenter. This claim is only needed when the party requesting the ID token is not the same as the audience of the ID token. This may be the case at Google for hybrid apps where a web application and Android app have a different client_id but share the same project. |
+| access_type | <code>string</code> | Indicates whether your application can refresh access tokens when the user is not present at the browser. Valid parameter values are 'online', which is the default value, and 'offline'. Set the value to 'offline' if your application needs to refresh access tokens when the user is not present at the browser. This value instructs the Google authorization server to return a refresh token and an access token the first time that your application exchanges an authorization code for tokens. |
+| email | <code>string</code> | The user's email address. This value may not be unique to this user and is not suitable for use as a primary key. Provided only if your scope included the email scope value. |
+| email_verified | <code>boolean</code> | True if the user's e-mail address has been verified; otherwise false. |
+
+<a name="module_AuthMachine..OAuth2ClientEndpoints"></a>
+
+### AuthMachine~OAuth2ClientEndpoints : <code>object</code>
+An object containing the various https endpoints for oAuth API
+
+**Kind**: inner typedef of [<code>AuthMachine</code>](#module_AuthMachine)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| tokenInfoUrl | <code>string</code> | The endpoint for viewing access token information |
+| oauth2AuthBaseUrl | <code>string</code> \| <code>URL</code> | The base URL for auth endpoints. |
+| oauth2TokenUrl | <code>string</code> \| <code>URL</code> | The base endpoint for token retrieval |
+| oauth2RevokeUrl | <code>string</code> \| <code>URL</code> | The base endpoint to revoke tokens. |
+| oauth2FederatedSignonPemCertsUrl | <code>string</code> \| <code>URL</code> | Sign on certificates in PEM format. |
+| oauth2FederatedSignonJwkCertsUrl | <code>string</code> \| <code>URL</code> | Sign on certificates in JWK format. |
+| oauth2IapPublicKeyUrl | <code>string</code> \| <code>URL</code> | IAP Public Key URL. This URL contains a JSON dictionary that maps the `kid` claims to the public key values. |
+
+**Example**  
+```js
+'https://oauth2.googleapis.com/tokeninfo'
+```
+**Example**  
+```js
+'https://accounts.google.com/o/oauth2/v2/auth'
+```
+**Example**  
+```js
+'https://oauth2.googleapis.com/token'
+```
+**Example**  
+```js
+'https://oauth2.googleapis.com/revoke'
+```
+**Example**  
+```js
+'https://www.googleapis.com/oauth2/v1/certs'
+```
+**Example**  
+```js
+'https://www.googleapis.com/oauth2/v3/certs'
+```
+**Example**  
+```js
+'https://www.gstatic.com/iap/verify/public_key'
+```
+<a name="module_AuthMachine..OAuth2ClientOptions"></a>
+
+### AuthMachine~OAuth2ClientOptions : <code>object</code>
+The secret of this manager is you can take advantage of the "endpoints"
+optional property to create a manager for *non*Google applications
+
+**Kind**: inner typedef of [<code>AuthMachine</code>](#module_AuthMachine)  
+**Extends**: <code>AuthClientOptions,OAuth2JSONOptions</code>  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| clientId | <code>string</code> | The authentication client ID. |
+| clientSecret | <code>string</code> | The authentication client secret. |
+| redirectUri | <code>string</code> | The URI to redirect to after completing the auth request. |
+| endpoints | <code>OAuth2ClientEndpoints</code> | Customizable endpoints. |
+| issuers | <code>string</code> | The allowed OAuth2 token issuers. |
+| clientAuthentication | <code>&quot;basic&quot;</code> \| <code>&quot;post&quot;</code> \| <code>&quot;none&quot;</code> | The client authentication type. Supported values are basic, post, and none. Defaults to post if not provided. https://datatracker.ietf.org/doc/html/rfc7591#section-2 |
+
+<a name="module_AuthMachine..initOAuthManager"></a>
+
+### AuthMachine~initOAuthManager ⇒ <code>OAuth2Client</code>
+Creates and initializing an oAuth2 manager *IF* it hasn't already
+been created
+
+**Kind**: inner typedef of [<code>AuthMachine</code>](#module_AuthMachine)  
+
+| Param | Type |
+| --- | --- |
+| manager | <code>class</code> | 
+| manager_options | <code>OAuth2ClientOptions</code> | 
+
 <a name="module_BusinessData"></a>
 
 ## BusinessData
@@ -3642,6 +3786,195 @@ value for the index; if *not* found add the variant.
 | variantAttributes | <code>Array.string</code> |  |
 | variants | <code>Array.PhysicalProductVariant</code> |  |
 
+<a name="module_Services"></a>
+
+## Services
+Typedefs, constants, support functions and database operations related to supported Services Matrials
+users
+
+
+* [Services](#module_Services)
+    * _static_
+        * [.createService](#module_Services.createService) ⇒ <code>Promise.Service</code>
+        * [.deleteService(service)](#module_Services.deleteService) ⇒ <code>Promise.&lt;void&gt;</code>
+        * [.deleteServiceById(service)](#module_Services.deleteServiceById) ⇒ <code>Promise.&lt;void&gt;</code>
+        * [.updateServiceByID(service)](#module_Services.updateServiceByID) ⇒ <code>promise.Service</code>
+        * [.updateService(service)](#module_Services.updateService) ⇒ <code>promise.Service</code>
+        * [.knownService(Id)](#module_Services.knownService) ⇒ <code>Promise.boolean</code>
+        * [.fetchServices()](#module_Services.fetchServices) ⇒ <code>Array.Service</code>
+        * [.fetchServicesPaginated(limit)](#module_Services.fetchServicesPaginated) ⇒ <code>PaginatedFetch</code>
+        * [.fetchService(serviceId)](#module_Services.fetchService) ⇒ <code>Promise.Service</code>
+        * [.fetchServiceName(serviceId)](#module_Services.fetchServiceName) ⇒ <code>Promise.string</code>
+    * _inner_
+        * [~ServiceDefault](#module_Services..ServiceDefault) : <code>ServiceDescriptor</code>
+        * [~ServiceDefaultForm](#module_Services..ServiceDefaultForm) : <code>ServiceDescriptor</code>
+        * [~summarizeService(service)](#module_Services..summarizeService) ⇒ <code>string</code>
+        * [~ServiceDescriptor](#module_Services..ServiceDescriptor) : <code>object</code>
+        * [~PaginatedFetch](#module_Services..PaginatedFetch) : <code>object</code>
+
+<a name="module_Services.createService"></a>
+
+### Services.createService ⇒ <code>Promise.Service</code>
+**Kind**: static constant of [<code>Services</code>](#module_Services)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| service | <code>ServiceDescriptor</code> | minimal record of Service |
+
+<a name="module_Services.deleteService"></a>
+
+### Services.deleteService(service) ⇒ <code>Promise.&lt;void&gt;</code>
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+
+| Param | Type |
+| --- | --- |
+| service | <code>ServiceDescriptor</code> | 
+
+<a name="module_Services.deleteServiceById"></a>
+
+### Services.deleteServiceById(service) ⇒ <code>Promise.&lt;void&gt;</code>
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| service | <code>ServiceDescriptor</code> | minimal record of Service |
+| service.Id | <code>string</code> | record Id of account |
+
+<a name="module_Services.updateServiceByID"></a>
+
+### Services.updateServiceByID(service) ⇒ <code>promise.Service</code>
+writes record back to database.  Assumes only Id is valid
+
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+**Returns**: <code>promise.Service</code> - a copy of the data written  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| service | <code>ServiceDescriptor</code> | a partially-populated service record for updates |
+
+<a name="module_Services.updateService"></a>
+
+### Services.updateService(service) ⇒ <code>promise.Service</code>
+writes record back to database.  Assumes only Id is valid
+
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+**Returns**: <code>promise.Service</code> - a copy of the data written  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| service | <code>ServiceDescriptor</code> | a partially-populated service record for updates |
+
+<a name="module_Services.knownService"></a>
+
+### Services.knownService(Id) ⇒ <code>Promise.boolean</code>
+Checks if this is a known Service Id
+
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+**Returns**: <code>Promise.boolean</code> - true is this Id is in database  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| Id | <code>string</code> | Id value to check |
+
+<a name="module_Services.fetchServices"></a>
+
+### Services.fetchServices() ⇒ <code>Array.Service</code>
+Fetches ALL Service records.  Not very useful
+
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+<a name="module_Services.fetchServicesPaginated"></a>
+
+### Services.fetchServicesPaginated(limit) ⇒ <code>PaginatedFetch</code>
+Fetchs an object to fetch pages of service data, ascending by name, "limit" at a time
+
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+**Returns**: <code>PaginatedFetch</code> - object with pagination methods  
+
+| Param | Type |
+| --- | --- |
+| limit | <code>number</code> | 
+
+<a name="module_Services.fetchService"></a>
+
+### Services.fetchService(serviceId) ⇒ <code>Promise.Service</code>
+Fetches a single Service record by Id
+
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+
+| Param | Type |
+| --- | --- |
+| serviceId | <code>ServiceDescriptor.id</code> | 
+
+<a name="module_Services.fetchServiceName"></a>
+
+### Services.fetchServiceName(serviceId) ⇒ <code>Promise.string</code>
+Fetches and returns the summarized name from a Service record
+
+**Kind**: static method of [<code>Services</code>](#module_Services)  
+**Returns**: <code>Promise.string</code> - the summarized name from the record  
+
+| Param | Type |
+| --- | --- |
+| serviceId | <code>string</code> | 
+
+<a name="module_Services..ServiceDefault"></a>
+
+### Services~ServiceDefault : <code>ServiceDescriptor</code>
+**Kind**: inner constant of [<code>Services</code>](#module_Services)  
+**Default**: <code>{&quot;Id&quot;:null,&quot;refPath&quot;:null,&quot;name&quot;:null,&quot;api_base_url&quot;:null,&quot;auth&quot;:&quot;&quot;,&quot;endpoints&quot;:&quot;&quot;}</code>  
+**Read only**: true  
+<a name="module_Services..ServiceDefaultForm"></a>
+
+### Services~ServiceDefaultForm : <code>ServiceDescriptor</code>
+**Kind**: inner constant of [<code>Services</code>](#module_Services)  
+**Default**: <code>{&quot;description&quot;:&quot;text&quot;,&quot;unit&quot;:&quot;&quot;,&quot;rate&quot;:&quot;number&quot;,&quot;MATERIAL&quot;:&quot;&quot;,&quot;image&quot;:&quot;url&quot;}</code>  
+**Read only**: true  
+<a name="module_Services..summarizeService"></a>
+
+### Services~summarizeService(service) ⇒ <code>string</code>
+Returns a standardized formatted name string
+
+**Kind**: inner method of [<code>Services</code>](#module_Services)  
+**Returns**: <code>string</code> - formatted name string  
+
+| Param | Type |
+| --- | --- |
+| service | <code>ServiceDescriptor</code> | 
+
+<a name="module_Services..ServiceDescriptor"></a>
+
+### Services~ServiceDescriptor : <code>object</code>
+a record
+
+**Kind**: inner typedef of [<code>Services</code>](#module_Services)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| Id | <code>string</code> | Id of document (redundant for convenience) |
+| refPath | <code>string</code> | if from database, full path to document |
+| name | <code>string</code> | descriptive name for an available service |
+| api_base_url | <code>string</code> | base url of API endpoints |
+| auth | <code>OAuth2ClientOptions</code> |  |
+| endpoints | <code>OAuth2ClientEndpoints</code> |  |
+
+<a name="module_Services..PaginatedFetch"></a>
+
+### Services~PaginatedFetch : <code>object</code>
+An object to allow for paginating a table read from Firestore. REQUIRES a sorting choice
+
+**Kind**: inner typedef of [<code>Services</code>](#module_Services)  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| Query | <code>Query</code> | that forms basis for the table read |
+| limit | <code>number</code> | page size |
+| snapshot | <code>QuerySnapshot</code> | last successful snapshot/page fetched |
+| status | <code>enum</code> | status of pagination object |
+| PageForward | <code>method</code> | pages the fetch forward |
+| PageBack | <code>method</code> | pages the fetch backward |
+
 <a name="module_User"></a>
 
 ## User
@@ -3715,7 +4048,7 @@ Builds a User record from the authentication "user" data
 
 | Param | Type |
 | --- | --- |
-| user | <code>User</code> | 
+| user | <code>UserObject</code> | 
 | user.isAnonymous | <code>boolean</code> | 
 | user.displayName | <code>string</code> | 
 | user.photoURL | <code>string</code> | 

package/business/AuthMachine/index.js

@@ -0,0 +1,229 @@
+/**
+ * Typedefs and functions for an oAuth authentication generator
+ * @module AuthMachine
+ */
+
+/**
+ * Options object for GenerateAuthUrl
+ * @typedef {object} GenerateAuthUrlOpts
+ * @property {?"online"|"offline"} access_type
+ * Recommended. Indicates whether your application can refresh access tokens
+ * when the user is not present at the browser. Valid parameter values are
+ * 'online', which is the default value, and 'offline'. Set the value to
+ * 'offline' if your application needs to refresh access tokens when the user
+ * is not present at the browser. This value instructs the Google
+ * authorization server to return a refresh token and an access token the
+ * first time that your application exchanges an authorization code for
+ * tokens.
+ * @property {?string} hd
+ * The hd (hosted domain) parameter streamlines the login process for G Suite
+ * hosted accounts. By including the domain of the G Suite user (for example,
+ * mycollege.edu), you can indicate that the account selection UI should be
+ * optimized for accounts at that domain. To optimize for G Suite accounts
+ * generally instead of just one domain, use an asterisk: hd=*.
+ * Don't rely on this UI optimization to control who can access your app,
+ * as client-side requests can be modified. Be sure to validate that the
+ * returned ID token has an hd claim value that matches what you expect
+ * (e.g. mycolledge.edu). Unlike the request parameter, the ID token claim is
+ * contained within a security token from Google, so the value can be trusted.
+ * @property {?"CODE"} response_type
+ * The 'response_type' will always be set to 'CODE'.
+ * @property {?string} client_id
+ * The client ID for your application. The value passed into the constructor
+ * will be used if not provided. You can find this value in the API Console.
+ * @property {?URL} redirect_url
+ * Determines where the API server redirects the user after the user
+ * completes the authorization flow. The value must exactly match one of the
+ * 'redirect_uri' values listed for your project in the API Console. Note that
+ * the http or https scheme, case, and trailing slash ('/') must all match.
+ * The value passed into the constructor will be used if not provided.
+ * @property {Array.string|string} scope
+ * Required. A space-delimited list of scopes that identify the resources that
+ * your application could access on the user's behalf. These values inform the
+ * consent screen that Google displays to the user. Scopes enable your
+ * application to only request access to the resources that it needs while
+ * also enabling users to control the amount of access that they grant to your
+ * application. Thus, there is an inverse relationship between the number of
+ * scopes requested and the likelihood of obtaining user consent. The
+ * OAuth 2.0 API Scopes document provides a full list of scopes that you might
+ * use to access Google APIs. We recommend that your application request
+ * access to authorization scopes in context whenever possible. By requesting
+ * access to user data in context, via incremental authorization, you help
+ * users to more easily understand why your application needs the access it is
+ * requesting.
+ * @property {?string} state
+ * Recommended. Specifies any string value that your application uses to
+ * maintain state between your authorization request and the authorization
+ * server's response. The server returns the exact value that you send as a
+ * name=value pair in the hash (#) fragment of the 'redirect_uri' after the
+ * user consents to or denies your application's access request. You can use
+ * this parameter for several purposes, such as directing the user to the
+ * correct resource in your application, sending nonces, and mitigating
+ * cross-site request forgery. Since your redirect_uri can be guessed, using a
+ * state value can increase your assurance that an incoming connection is the
+ * result of an authentication request. If you generate a random string or
+ * encode the hash of a cookie or another value that captures the client's
+ * state, you can validate the response to additionally ensure that the
+ * request and response originated in the same browser, providing protection
+ * against attacks such as cross-site request forgery. See the OpenID Connect
+ * documentation for an example of how to create and confirm a state token.
+ * @property {?boolean} include_granted_scopes
+ * Optional. Enables applications to use incremental authorization to request
+ * access to additional scopes in context. If you set this parameter's value
+ * to true and the authorization request is granted, then the new access token
+ * will also cover any scopes to which the user previously granted the
+ * application access. See the incremental authorization section for examples.
+ * @property {?tring} login_hint
+ * Optional. If your application knows which user is trying to authenticate,
+ * it can use this parameter to provide a hint to the Google Authentication
+ * Server. The server uses the hint to simplify the login flow either by
+ * prefilling the email field in the sign-in form or by selecting the
+ * appropriate multi-login session. Set the parameter value to an email
+ * address or sub identifier, which is equivalent to the user's Google ID.
+ * @property {?"none"|"consent"|"select_account"} prompt
+ * Optional. A space-delimited, case-sensitive list of prompts to present the
+ * user. If you don't specify this parameter, the user will be prompted only
+ * the first time your app requests access.  Possible values are:
+ *
+ * 'none' - Donot display any authentication or consent screens. Must not be
+ *        specified with other values.
+ * 'consent' - 	Prompt the user for consent.
+ * 'select_account' - Prompt the user to select an account.
+ * @property {?"plain"|"S256"} code_challenge_method
+ * Recommended. Specifies what method was used to encode a 'code_verifier'
+ * that will be used during authorization code exchange. This parameter must
+ * be used with the 'code_challenge' parameter. The value of the
+ * 'code_challenge_method' defaults to "plain" if not present in the request
+ * that includes a 'code_challenge'. The only supported values for this
+ * parameter are "S256" or "plain".
+ * @property {?string} code_challenge
+ * Recommended. Specifies an encoded 'code_verifier' that will be used as a
+ * server-side challenge during authorization code exchange. This parameter
+ * must be used with the 'code_challenge' parameter described above.
+ * @property {Array.object} keyValues
+ * A way for developers and/or the auth team to provide a set of key value
+ * pairs to be added as query parameters to the authorization url.
+ * @property {string} keyValues.key
+ * @property {string} keyValues.value
+ */
+
+/**
+ * Description of TokenInfo returned by oAuth manager
+ * @typedef {object} TokenInfo
+ * @property {string} aud
+ * The application that is the intended user of the access token.
+ * @property {?string} user_id
+ * This value lets you correlate profile information from multiple Google
+ * APIs. It is only present in the response if you included the profile scope
+ * in your request in step 1. The field value is an immutable identifier for
+ * the logged-in user that can be used to create and manage user sessions in
+ * your application. The identifier is the same regardless of which client ID
+ * is used to retrieve it. This enables multiple applications in the same
+ * organization to correlate profile information.
+ * @property {Array.string} scopes
+ * An array of scopes that the user granted access to.
+ * @property {number} expiry_date
+ * The datetime when the token becomes invalid.
+ * @property {?string} sub
+ * An identifier for the user, unique among all Google accounts and never
+ * reused. A Google account can have multiple emails at different points in
+ * time, but the sub value is never changed. Use sub within your application
+ * as the unique-identifier key for the user.
+ * @property {?string} azp
+ * The client_id of the authorized presenter. This claim is only needed when
+ * the party requesting the ID token is not the same as the audience of the ID
+ * token. This may be the case at Google for hybrid apps where a web
+ * application and Android app have a different client_id but share the same
+ * project.
+ * @property {?string} access_type
+ * Indicates whether your application can refresh access tokens
+ * when the user is not present at the browser. Valid parameter values are
+ * 'online', which is the default value, and 'offline'. Set the value to
+ * 'offline' if your application needs to refresh access tokens when the user
+ * is not present at the browser. This value instructs the Google
+ * authorization server to return a refresh token and an access token the
+ * first time that your application exchanges an authorization code for
+ * tokens.
+ * @property {?string} email
+ * The user's email address. This value may not be unique to this user and
+ * is not suitable for use as a primary key. Provided only if your scope
+ * included the email scope value.
+ * @property {?boolean} email_verified
+ * True if the user's e-mail address has been verified; otherwise false.
+ */
+
+/**
+ * An object containing the various https endpoints for oAuth API
+ * @typedef {object} OAuth2ClientEndpoints
+ * @property {string} tokenInfoUrl
+ * The endpoint for viewing access token information
+ * @example
+ * 'https://oauth2.googleapis.com/tokeninfo'
+ * @property {string|URL} oauth2AuthBaseUrl
+ * The base URL for auth endpoints.
+ * @example
+ * 'https://accounts.google.com/o/oauth2/v2/auth'
+ * @property {string|URL} oauth2TokenUrl
+ * The base endpoint for token retrieval
+ * @example
+ * 'https://oauth2.googleapis.com/token'
+ * @property {string|URL} oauth2RevokeUrl
+ * The base endpoint to revoke tokens.
+ * @example
+ * 'https://oauth2.googleapis.com/revoke'
+ * @property {string|URL} oauth2FederatedSignonPemCertsUrl
+ * Sign on certificates in PEM format.
+ * @example
+ * 'https://www.googleapis.com/oauth2/v1/certs'
+ * @property {string|URL} oauth2FederatedSignonJwkCertsUrl
+ * Sign on certificates in JWK format.
+ * @example
+ * 'https://www.googleapis.com/oauth2/v3/certs'
+ * @property {string|URL} oauth2IapPublicKeyUrl
+ * IAP Public Key URL.
+ * This URL contains a JSON dictionary that maps the `kid` claims to the public key values.
+ * @example
+ * 'https://www.gstatic.com/iap/verify/public_key'
+ */
+
+/**
+ * The secret of this manager is you can take advantage of the "endpoints"
+ * optional property to create a manager for *non*Google applications
+ * @typedef {object} OAuth2ClientOptions
+ * @extends AuthClientOptions,OAuth2JSONOptions
+ * @alias {@link OAuth2JSONOptions.client_id}
+ * @property {?string} clientId
+ * The authentication client ID.
+ * @alias {@link OAuth2JSONOptions.client_secret}
+ * @property {?string} clientSecret
+ * The authentication client secret.
+ * @alias {@link OAuth2JSONOptions.redirect_uris}
+ * @property {?string} redirectUri
+ * The URI to redirect to after completing the auth request.
+ * @property {?OAuth2ClientEndpoints} endpoints
+ * Customizable endpoints.
+ * @property {?string} issuers
+ * The allowed OAuth2 token issuers.
+ * @property {?"basic"|"post"|"none"} clientAuthentication
+ * The client authentication type. Supported values are basic, post, and none.
+ * Defaults to post if not provided.
+ * https://datatracker.ietf.org/doc/html/rfc7591#section-2
+ */
+
+/**
+ * Creates and initializing an oAuth2 manager *IF* it hasn't already
+ * been created
+ * @callback initOAuthManager
+ * @param {class} manager 
+ * @param {OAuth2ClientOptions} manager_options 
+ * @returns {OAuth2Client}
+ */
+export function initOAuthManager(manager, manager_options) {
+  if (manager)
+    return manager;
+  else {
+    return new OAuth2Client(
+      manager_options
+    );
+  }
+};

package/business/Services/index.js

@@ -0,0 +1,212 @@
+/**
+ * Typedefs, constants, support functions and database operations related to supported Services Matrials
+ * users
+ * @module Services
+ */
+
+import {
+  writeRecord,
+  writeBack,
+  updateRecord,
+  fetchRecord,
+  collectRecords,
+  deleteRecord,
+  PaginateFetch,
+} from "@leaddreamer/firebase-wrapper";
+import { Forms, fillForm } from "@leaddreamer/staticforms";
+
+import { SERVICES } from "../boilerplate/index.js";
+
+//////////////////////////////////////////////////////////////////////
+// Constants
+
+/**
+ * a record
+ * @typedef {object} ServiceDescriptor
+ * @property {string} Id Id of document (redundant for convenience)
+ * @property {string} refPath if from database, full path to document
+ * @property {string} name descriptive name for an available service
+ * @property {string} api_base_url base url of API endpoints
+ * @property {OAuth2ClientOptions} auth 
+ * @property {OAuth2ClientEndpoints} endpoints 
+ */
+
+/**
+ * @readonly
+ * @constant
+ * @type {ServiceDescriptor}
+ * @default
+ */
+const ServiceDefault = {
+  Id: null,
+  refPath: null,
+  name: null,
+  api_base_url: null,
+  auth: {},
+  endpoints: {},
+};
+
+/**
+ * @readonly
+ * @constant
+ * @type {ServiceDescriptor}
+ * @default
+ */
+const ServiceDefaultForm = {
+  description: "text",
+  unit: `lookup:${UNITS}`,
+  rate: "number",
+  [MATERIAL]:`lookup:${MATERIAL}`,
+  image: "url",
+};
+
+Forms.Base[SERVICES] = ServiceDefault;
+Forms.BaseForm[SERVICES] = ServiceDefaultForm;
+Forms.CreateForm[SERVICES] = ServiceDefaultForm;
+Forms.Summarize[SERVICES] = summarizeService;
+Forms.Save[SERVICES] = updateService;
+Forms.SearchBy[SERVICES] = "description";
+
+//////////////////////////////////////////////////////////////////////
+// record operations
+/**
+ * @param {ServiceDescriptor} service
+ * @returns {Promise<void>}
+ */
+export async function deleteService(service) {
+  return deleteRecord(service, SERVICES);
+}
+
+/**
+ * @param {ServiceDescriptor} service minimal record of Service
+ * @param {!string} service.Id record Id of account
+ * @returns {Promise<void>}
+ */
+export async function deleteServiceById(service) {
+  if (!service?.Id) return;
+
+  return deleteRecord(service, SERVICES);
+}
+
+/**
+ * @param {ServiceDescriptor} service minimal record of Service
+ * @returns {Promise.Service}
+ */
+export const createService = (service) => {
+  //need a "no duplicate" function - whatever that means in this context
+  return writeRecord(SERVICES, service);
+};
+
+/**
+ * writes record back to database.  Assumes only Id is valid
+ * @param {ServiceDescriptor} service a partially-populated service record for updates
+ * @returns {promise.Service} a copy of the data written
+ */
+export async function updateServiceByID(service, parent = null) {
+  // will update just the fields provided
+  return writeBack({
+    ...service,
+    refPath: `${parent?.refPath}/${SERVICES}/${service.Id}`,
+  });
+}
+
+/**
+ * writes record back to database.  Assumes only Id is valid
+ * @param {ServiceDescriptor} service a partially-populated service record for updates
+ * @returns {promise.Service} a copy of the data written
+ */
+export async function updateService(service) {
+  
+  return updateRecord(
+    fillForm(service, SERVICES), //saves only APPROPRIATE fields -does NOT populate missing fields
+    null,
+    SERVICE
+  );
+}
+
+//////////////////////////////////////////////////////////////////////
+// fetches
+
+/**
+ * Checks if this is a known Service Id
+ * @param {!string} Id Id value to check
+ * @returns {Promise.boolean} true is this Id is in database
+ */
+export async function knownService(Id) {
+  let exists = true;
+  try {
+    await fetchService(Id);
+  } catch (err) {
+    exists = false;
+  }
+  return exists;
+}
+
+//////////////////////////////////////////////////////////////////////
+// fetches
+
+/**
+ * Fetches ALL Service records.  Not very useful
+ * @returns {Array.Service}
+ */
+export async function fetchServices() {
+  return collectRecords(SERVICES);
+}
+
+/**
+ * An object to allow for paginating a table read from Firestore. REQUIRES a sorting choice
+ * @typedef {object} PaginatedFetch
+ * @property {Query} Query that forms basis for the table read
+ * @property {number} limit page size
+ * @property {QuerySnapshot} snapshot last successful snapshot/page fetched
+ * @property {enum} status status of pagination object
+ * @property {method} PageForward pages the fetch forward
+ * @property {method} PageBack pages the fetch backward
+
+ */
+
+/**
+ * Fetchs an object to fetch pages of service data, ascending by name, "limit" at a time
+ * @param {number} limit
+ * @returns {PaginatedFetch} object with pagination methods
+ */
+
+export async function fetchServicesPaginated(limit) {
+  return new PaginateFetch(
+    SERVICES,
+    null, //filter
+    [{ fieldRef: "NAME", dirStr: "asc" }], //sort
+    null, //ref
+    limit,
+  );
+}
+
+/**
+ * Fetches a single Service record by Id
+ * @param {!ServiceDescriptor.id} serviceId
+ * @returns {Promise.Service}
+ */
+export async function fetchService(serviceId) {
+  return fetchRecord(SERVICES, serviceId);
+}
+
+/**
+ * Fetches and returns the summarized name from a Service record
+ * @param {!string} serviceId
+ * @returns {Promise.string} the summarized name from the record
+ */
+export async function fetchServiceName(serviceId) {
+  const service = await fetchService(serviceId);
+  return summarizeService(service);
+}
+
+//////////////////////////////////////////////////////////////////////
+// utilities
+/**
+ * Returns a standardized formatted name string
+ * @param {ServiceDescriptor}
+ * @returns {string} formatted name string
+ */
+function summarizeService(service) {
+  return `${service?.name}`;
+}

package/business/User/index.js

@@ -125,7 +125,7 @@ export const createUser = (user) => {
 
 /**
  * Builds a User record from the authentication "user" data
- * @param {User} user
+ * @param {UserObject} user
  * @param {boolean} user.isAnonymous
  * @param {?string} user.displayName
  * @param {?string} user.photoURL

package/business/boilerplate/index.js

@@ -45,6 +45,8 @@ export const USER = "User";
 export const USERS = USER;
 export const ACTIVEUSER = "ActiveUser";
 
+export const SERVICES = "Stores";
+
 export const MARKUPS = "markups";
 
 export const BASE = `base`;

package/business/index.js

@@ -5,6 +5,7 @@
  */
 export * from "./boilerplate/index.js";
 export * from "./Addresses/index.js";
+export * from "./AuthMachine/index.js";
 export * from "./BusinessData/index.js";
 export * from "./Commodities/index.js";
 export * from "./Fundamentals/index.js";
@@ -14,5 +15,6 @@ export * from "./Messages/index.js";
 export * from "./Payment/index.js";
 export * from "./PrivateData/index.js";
 export * from "./Product/index.js";
+export * from "./Services/index.js";
 export * from "./User/index.js";
 export * from "./Utilities/index.js";

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=22"
   },
-  "version": "0.0.3-beta.94",
+  "version": "0.0.3-beta.95",
   "description": "Business & Database Logic for Inventory Services",
   "repository": {
     "type": "git",