@fragus/sam-types 1.1.8 → 1.1.10

package/README.md

@@ -1,75 +1,48 @@
 # SAM-types
 
-SAM types is used to collect and share all interfaces (types) that one or more repositories have in
-common. To facilitate and ensure that repositories use the same types when communicating with each other.
-In most cases, if not all, this is between SAM-api and one or more of the frontend clients like the SAM-admin.
+The TypeScript types shared by SAM-api and its clients: SAM-admin-v2, SAM-superadmin-frontend,
+SAM-webcalc-v2 and MyPage. Requests, responses, error keys and enums live here once, so the API and
+every client agree on what goes over the wire.
 
-## Conventions
+Published to npm as [`@fragus/sam-types`](https://www.npmjs.com/package/@fragus/sam-types).
 
-### Request/Response interfaces
-TODO: Fill this out
+## Using it
 
-### Versioning
+Each consumer pins an exact version in its `package.json`:
 
-We use standard [semantic versioning](https://semver.org/)
+```json
+"@fragus/sam-types": "1.1.9"
+```
 
-## Development
-### Dependencies
-The project only has one dependency: `Typescript`
+Import from the package root:
 
-This is to have `tsc` available.
+```ts
+import { ContractState, INoContractsAvailableErrorParams } from '@fragus/sam-types'
+```
 
-### Compiling
+## Prerequisites
 
-To compile the `index.d.ts` file and the `index.js` file, run `npm run tsc` (or `yarn tsc`). This cleans all existing `.js` files and updates the `index.d.ts` file and the `index.js` file.
+- Node.js: the version in `.nvmrc`
+- npm
 
-### Adding new interfaces, types, and enums
+## Getting started
 
-Write your interface or type like you normally would. In order to export it, you need to add it to the `index.ts` file which holds all exported interfaces, types, and enums. The enums (for now) need to be put directly in the `index.ts` file. To fix this we need to setup some Webpack configuration etc.
+```bash
+npm install
+npm run tsc        # npm run tsc-win on Windows without bash
+```
 
-### Local development
+`npm run tsc` deletes the compiled `.js` files and builds the package again. CI runs the same build on
+every push.
 
-### Using npm
-To use the types locally in an application, add the line below as a dependency in your `package.json` file:
+## Docs
 
-`"sam-types": "file:../SAM-types"`
+- [Adding and changing types](docs/adding-types.md): where a type goes, naming, exports, and the
+  TypeScript 3.3 limit
+- [Testing in a consumer before release](docs/local-development.md): `file:../SAM-types` and how to undo it
+- [Releasing](docs/releasing.md): versioning, the GitHub release that publishes to npm, and bumping the
+  consumers
 
-The path is the relative path to the SAM-types project.
-### Using yarn
-To use the types locally you can use `yarn link`. See docs [here](https://yarnpkg.com/lang/en/docs/cli/link/).
+## Branches
 
-`cd` to the SAM-types folder and type: `yarn link`
-
-Then `cd` to your application and type `yarn link "sam-types"`. Now your application uses your local SAM-types project (using a symlink). To unlink, type `yarn unlink "sam-types"`
-
-This means that you do not have to change anything in your `package.json` file.
-
-### Regular dependency
-To use SAM-types in a project, add the line below as a dependency in your `package.json` file:
-
-`"sam-types": "OmniCar/SAM-types#0.0.1"`
-
-If you need to target something other than a specific release, consider targeting a branch or a commit as shown below:
-
-* `"sam-types": "OmniCar/SAM-types#4727d357ea"`
-* `"sam-types": "OmniCar/SAM-types#feature\/branch"`
-
-## Releasing
-
-### Using GitHub
-
-* Go to [releases](https://github.com/OmniCar/SAM-types/releases) on GitHub
-* Press "Create a new release"
-* Set the "Tag version" to the appropriate version number (see versioning above)
-* Set the "Release title" to "Version <version_number>"
-* Describe the changes. What's new? are there any breaking changes? etc.
-* If you want you can see the changes on `master` compared to a release (for example version `0.0.1`) by typing: `git diff tags/0.0.1 master`
-* Press "Publish release"
-
-### Using [hub cli](https://github.com/github/hub)
-
-If you have installed the hub cli (see link above), you can create a new release with the below command. Please note that it defaults to targeting the main (`master`) branch unless you use the `-t` option (more options [here](https://github.com/github/hub/blob/master/commands/release.go))
-
-`git release create -o -m "Release 0.0.2" "0.0.2"`
-
-If you did not set up the alias for `git = hub` you should write `hub` instead of `git` in the command above.
+`fix/`, `feature/` or `backmerge/` plus a kebab-case description. PRs target `develop`.

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.8",
+  "version": "1.1.10",
   "name": "@fragus/sam-types",
   "description": "Typescript interfaces for all types used to communicate between SAM client(s) and the SAM API",
   "author": "Fragus",

package/types/contract/contractList.d.ts

@@ -1,5 +1,7 @@
 import { IContractHealth } from './../admin/contract/health'
+import { TContractObject } from './../admin/product'
 import { ContractState } from './../index'
+import { IPaginatedQueryParams, IPaginatedResponse } from './../queryParams'
 import { IContractFilterDate, IContractFilterOption } from './contractFilter'
 
 export interface IContractListRecord {
@@ -51,3 +53,40 @@ export interface IWarrantyListRecord {
   registrationNumber: string
   sellerName: string
 }
+
+/** A contract-list row from the superadmin cross-provider search, tagged with its owning provider. */
+export interface IContractCrossProviderSearchRecord extends IContractListRecord {
+  contractProviderId: number
+  contractProviderName: string
+}
+
+export interface IContractCrossProviderSearchResponse {
+  result: IContractCrossProviderSearchRecord[]
+}
+
+export interface IContractCrossProviderSearchParams {
+  search: string
+  limit?: number
+  includeInactiveProviders?: 'yes'
+}
+
+/**
+ * The provider-agnostic contract-list filters. Sellers, templates, options and sub dealers are
+ * vocabularies of a single provider and have no cross-provider meaning.
+ */
+export interface IContractCrossProviderFilterParams {
+  contractStates?: ContractState[]
+  created?: IContractFilterDate
+  expired?: IContractFilterDate
+  activeTypes?: TContractObject[]
+}
+
+export interface IContractCrossProviderListParams
+  extends IPaginatedQueryParams<ContractListOrderByType, IContractCrossProviderFilterParams> {
+  includeInactiveProviders?: 'yes'
+}
+
+export type IContractCrossProviderListResponse = IPaginatedResponse<
+  IContractCrossProviderSearchRecord[],
+  ContractListOrderByType
+>

package/types/outage.d.ts

@@ -1,3 +1,4 @@
+import { TIsoCountry } from './country'
 import { OutageSeverityLevel } from './index'
 
 export interface IOutageResponse {
@@ -7,3 +8,68 @@ export interface IOutageResponse {
   disabledPaths: string[] | null
   severityLevel: OutageSeverityLevel | null
 }
+
+/**
+ * Request body for creating or updating an outage (Superadmin). A null text or severity falls back to the
+ * template's default. Leave both iso_countries and provider_ids null for an outage that applies to everyone.
+ */
+export interface IOutageAdminRequest {
+  outageTemplateId: number | null
+  headerText: string | null
+  message: string | null
+  severityLevel: OutageSeverityLevel | null
+  /**
+   * Paths whose requests are refused while the outage is active. A path matches anywhere in the URL, in every app,
+   * so start it with its app: /admin/contracts, /my-page/invoices. '*' refuses every request.
+   */
+  disabledPaths: string[] | null
+  isoCountries: TIsoCountry[] | null
+  providerIds: number[] | null
+}
+
+/**
+ * An outage as Superadmin lists and edits it.
+ */
+export interface IOutageAdminResponse extends IOutageAdminRequest {
+  outageId: number
+  /**
+   * ISO date string (YYYY-MM-DD) of when the outage was created
+   */
+  date: string
+  /**
+   * ISO date string (YYYY-MM-DD) of when the outage was archived; null while it is active
+   */
+  archived: string | null
+  /**
+   * What users see: the outage's own text and severity, or the template's when those are null
+   */
+  effectiveHeaderText: string
+  effectiveMessage: string
+  effectiveSeverityLevel: OutageSeverityLevel
+}
+
+/**
+ * Request body for creating or updating an outage template (Superadmin). Updating changes what users see for every
+ * active outage that leaves these values empty.
+ */
+export interface IOutageTemplateRequest {
+  name: string
+  defaultHeaderText: string
+  defaultMessage: string
+  defaultSeverityLevel: OutageSeverityLevel
+}
+
+/**
+ * An outage template: the texts and severity a new outage can start from (Superadmin).
+ */
+export interface IOutageTemplateResponse extends IOutageTemplateRequest {
+  outageTemplateId: number
+  /**
+   * Outages using the template, archived ones included; a template can only be deleted while this is 0
+   */
+  outageCount: number
+  /**
+   * Active outages using the template, whose text changes when the template is edited
+   */
+  activeOutageCount: number
+}