@nice2dev/ui-api 1.4.10 → 1.4.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +63 -0
- package/README.md +17 -0
- package/dist/NiceApiClient.d.ts +39 -0
- package/dist/NiceIntegrationsEditor.d.ts +62 -0
- package/dist/apiClient/ApiClientParts.d.ts +73 -0
- package/dist/core/index.d.ts +1 -0
- package/dist/core/integration.d.ts +172 -0
- package/dist/core.cjs +55 -55
- package/dist/core.mjs +1685 -1491
- package/dist/index.cjs +9 -3
- package/dist/index.d.ts +4 -0
- package/dist/index.mjs +3954 -1487
- package/dist/ui-api.css +1 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,68 @@
|
|
|
1
1
|
# @nice2dev/ui-api
|
|
2
2
|
|
|
3
|
+
## 1.4.12
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- c3952fe: Module integrations and environment sets, with editors in the Development Studio.
|
|
8
|
+
|
|
9
|
+
- **`@nice2dev/ui-api/core`:**
|
|
10
|
+
- New types:
|
|
11
|
+
- `NiceIntegrationDef`: package, direction and requirements; a connection (protocol, base URL, auth,
|
|
12
|
+
headers, paging, retries, rate limit); the consumed API as a collection; exposed endpoints; operations with
|
|
13
|
+
field mapping, trigger, conflict rule and incremental field.
|
|
14
|
+
- `NiceEnvironmentSets`: declared variables and sets that extend one another or apply to one database.
|
|
15
|
+
- Helpers: `resolveEnvironmentSet`, `valueOrigin`, `toApiEnvironments`, `environmentSetFor`,
|
|
16
|
+
`validateIntegrations` (issues with stable codes), `groupIntegrations` and `integrationEndpoints`.
|
|
17
|
+
- **`NiceIntegrationsEditor`:** the list grouped by package and direction, with tabs for General, Connection,
|
|
18
|
+
API (in NiceApiClient), Exposed, Operations (with mapping) and Checks.
|
|
19
|
+
- **`NiceEnvironmentSetsEditor`:** variables × sets; inherited values are shown faded and secrets stay
|
|
20
|
+
`{{secret:KEY}}`.
|
|
21
|
+
- **`niceApiStudioEditors()`:** plugs both editors into the studio.
|
|
22
|
+
- **Development Studio:**
|
|
23
|
+
- New props `editors` and `editorServices`. A file kind whose `editor` the studio does not have opens in the
|
|
24
|
+
host's plug-in, or as JSON when there is none.
|
|
25
|
+
- New tree group "Integrations".
|
|
26
|
+
- New file kinds `{prefix}.integrations.json` and `{prefix}.environments.json`, in both the native and the
|
|
27
|
+
OmniVerk presets.
|
|
28
|
+
- **OmniVerk (`@nice2dev/erp-adapter/omniverk`):**
|
|
29
|
+
- `variablesFromManifest`: the wizard fields and environment variables become declared variables.
|
|
30
|
+
- `envVarsToManifest`: publishes variables to the manifest; secrets are left out.
|
|
31
|
+
- `exposedFromControllers`, `controllerDifferences` and `controllersFromExposed`: map, compare and sync
|
|
32
|
+
controllers with exposed endpoints.
|
|
33
|
+
- `toOmniVerkConnectorSeeds`: rows for RESTConnection / RESTEndpointDefinition, SOAPConnection /
|
|
34
|
+
SOAPSavedCall and GraphQLEndpoint / GraphQLSavedQuery, with OmniVerk's stable ids.
|
|
35
|
+
|
|
36
|
+
Guide: `documentation/omniverk/OMNIVERK_UPGRADE_1.4.12.md`.
|
|
37
|
+
|
|
38
|
+
## 1.4.11
|
|
39
|
+
|
|
40
|
+
### Patch Changes
|
|
41
|
+
|
|
42
|
+
- bacce43: New `NiceApiClient`: an API client in the style of Scalar / Swagger UI, built on the
|
|
43
|
+
`@nice2dev/ui-api/core` model.
|
|
44
|
+
|
|
45
|
+
- **Try:**
|
|
46
|
+
- The collection's folders and requests on the left, searchable. Rename, duplicate and delete
|
|
47
|
+
items from the tree.
|
|
48
|
+
- The request builder: method and URL, with a preview of the URL as sent. Tabs: parameters (one
|
|
49
|
+
table with a location per row), headers, auth, body, scripts and settings.
|
|
50
|
+
- Auth: inherit, none, API key, Bearer, Basic, Digest, OAuth 2.0 (with "Get token"), AWS SigV4,
|
|
51
|
+
HMAC, mTLS or custom headers.
|
|
52
|
+
- Body: JSON, XML, text, form, multipart, file, GraphQL or SOAP.
|
|
53
|
+
- The response: status, time and size; views Pretty, Raw, Headers, Sent and code samples.
|
|
54
|
+
- **Docs:** each operation's parameters, body, responses with their schemas and examples, and code
|
|
55
|
+
samples; the collection's servers and models.
|
|
56
|
+
- **Import:** curl, OpenAPI / Swagger, Postman, HAR, GraphQL introspection or WSDL — paste or open
|
|
57
|
+
a file.
|
|
58
|
+
- **Export:** OpenAPI 3.1 (YAML or JSON), Postman, HAR or Markdown.
|
|
59
|
+
- **Environments:** switch between variable sets. Secrets are resolved through `resolveSecret`.
|
|
60
|
+
- **Sending:** requests go through `sendRequest`, the host's proxy. The default is the browser's
|
|
61
|
+
`fetch`, where CORS applies.
|
|
62
|
+
|
|
63
|
+
`value` / `defaultValue` / `onChange`, `mode` (`consume` / `document` / `both`), `readOnly`.
|
|
64
|
+
146 new `apiClient.*` keys in all 12 full dictionaries.
|
|
65
|
+
|
|
3
66
|
## 1.4.10
|
|
4
67
|
|
|
5
68
|
No changes in this release.
|
package/README.md
CHANGED
|
@@ -89,6 +89,23 @@ function App() {
|
|
|
89
89
|
}
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
+
### API Client (1.4.11)
|
|
93
|
+
|
|
94
|
+
`NiceApiClient`: Scalar / Swagger UI-style client and documentation on the core model below. It
|
|
95
|
+
imports curl, OpenAPI, Postman, HAR, GraphQL or WSDL and exports OpenAPI, Postman, HAR or Markdown.
|
|
96
|
+
|
|
97
|
+
```tsx
|
|
98
|
+
import { NiceApiClient, importOpenApi } from '@nice2dev/ui-api';
|
|
99
|
+
|
|
100
|
+
<NiceApiClient
|
|
101
|
+
defaultValue={importOpenApi(openApiYaml)}
|
|
102
|
+
environments={[{ id: 'dev', name: 'Dev', values: [{ key: 'token', value: '{{secret:API_TOKEN}}' }] }]}
|
|
103
|
+
sendRequest={hostProxyTransport} // your proxy: the browser's fetch meets CORS
|
|
104
|
+
resolveSecret={(key) => vault.get(key)}
|
|
105
|
+
mode="both" // 'consume' | 'document' | 'both'
|
|
106
|
+
/>;
|
|
107
|
+
```
|
|
108
|
+
|
|
92
109
|
## Core without React — `@nice2dev/ui-api/core` (1.4.9)
|
|
93
110
|
|
|
94
111
|
The model and converters the API tools are built on, usable in Node (importers in CI, generators,
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { default as React } from 'react';
|
|
2
|
+
import { NiceApiCallState } from './apiClient/ApiClientParts';
|
|
3
|
+
import { NiceApiCollection, NiceApiEnvironment, NiceApiImportOptions, NiceApiTransport } from './core';
|
|
4
|
+
export type { NiceApiCallState };
|
|
5
|
+
export interface NiceApiClientProps {
|
|
6
|
+
/** The collection (controlled). */
|
|
7
|
+
value?: NiceApiCollection;
|
|
8
|
+
/** The collection to start from (uncontrolled). */
|
|
9
|
+
defaultValue?: NiceApiCollection;
|
|
10
|
+
/** Every edit, import and rename — the whole collection. */
|
|
11
|
+
onChange?: (collection: NiceApiCollection) => void;
|
|
12
|
+
/** Variable sets (dev, test, prod…) the user switches between. */
|
|
13
|
+
environments?: NiceApiEnvironment[];
|
|
14
|
+
/** The active environment's id (controlled). */
|
|
15
|
+
activeEnvironment?: string;
|
|
16
|
+
defaultActiveEnvironment?: string;
|
|
17
|
+
onActiveEnvironmentChange?: (id: string) => void;
|
|
18
|
+
/** The selected request or folder id (controlled); empty = the collection itself. */
|
|
19
|
+
selectedItem?: string;
|
|
20
|
+
defaultSelectedItem?: string;
|
|
21
|
+
onSelectedItemChange?: (id: string) => void;
|
|
22
|
+
/** `consume` — send requests; `document` — read the API; `both` (default) — a switch between. */
|
|
23
|
+
mode?: 'consume' | 'document' | 'both';
|
|
24
|
+
/** Sends a resolved request — the host's proxy. Default: the browser's fetch (CORS applies). */
|
|
25
|
+
sendRequest?: NiceApiTransport;
|
|
26
|
+
/** After every send: the response (or the error) and the request as it went out — for logs, tests, history. */
|
|
27
|
+
onResponse?: (requestId: string, call: NiceApiCallState) => void;
|
|
28
|
+
/** The value of `{{secret:KEY}}` — the host's vault. */
|
|
29
|
+
resolveSecret?: (key: string) => string | undefined;
|
|
30
|
+
/** Options for importing OpenAPI with external `$ref`s, a full YAML parser, an XML parser. */
|
|
31
|
+
importOptions?: NiceApiImportOptions;
|
|
32
|
+
/** View and send only: no editing, import or new items. */
|
|
33
|
+
readOnly?: boolean;
|
|
34
|
+
/** Height of the client. Default 640. */
|
|
35
|
+
height?: number | string;
|
|
36
|
+
className?: string;
|
|
37
|
+
style?: React.CSSProperties;
|
|
38
|
+
}
|
|
39
|
+
export declare function NiceApiClient(props: NiceApiClientProps): React.ReactElement;
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import { default as React } from 'react';
|
|
2
|
+
import { NiceApiTransport, NiceEnvironmentSets, NiceIntegrationsFile } from './core';
|
|
3
|
+
export interface NiceIntegrationsEditorProps {
|
|
4
|
+
/** The module's integrations (controlled). */
|
|
5
|
+
value?: NiceIntegrationsFile;
|
|
6
|
+
defaultValue?: NiceIntegrationsFile;
|
|
7
|
+
onChange?: (value: NiceIntegrationsFile) => void;
|
|
8
|
+
/** The module's environment sets — the API tab sends with their values. */
|
|
9
|
+
environments?: NiceEnvironmentSets;
|
|
10
|
+
/** For the requirement checks: what exists around the module. */
|
|
11
|
+
known?: {
|
|
12
|
+
modules?: string[];
|
|
13
|
+
dataSources?: string[];
|
|
14
|
+
};
|
|
15
|
+
/** Sends the API tab's requests (the host's proxy). */
|
|
16
|
+
sendRequest?: NiceApiTransport;
|
|
17
|
+
resolveSecret?: (key: string) => string | undefined;
|
|
18
|
+
readOnly?: boolean;
|
|
19
|
+
/** Height. Default 640. */
|
|
20
|
+
height?: number | string;
|
|
21
|
+
className?: string;
|
|
22
|
+
style?: React.CSSProperties;
|
|
23
|
+
}
|
|
24
|
+
/** A module's integrations: the list on the left, the selected one in tabs. */
|
|
25
|
+
export declare function NiceIntegrationsEditor(props: NiceIntegrationsEditorProps): React.ReactElement;
|
|
26
|
+
export interface NiceEnvironmentSetsEditorProps {
|
|
27
|
+
/** The declared variables and the sets (controlled). */
|
|
28
|
+
value?: NiceEnvironmentSets;
|
|
29
|
+
defaultValue?: NiceEnvironmentSets;
|
|
30
|
+
onChange?: (value: NiceEnvironmentSets) => void;
|
|
31
|
+
readOnly?: boolean;
|
|
32
|
+
className?: string;
|
|
33
|
+
style?: React.CSSProperties;
|
|
34
|
+
}
|
|
35
|
+
/** Variables × sets: each set's own values, the inherited ones shown faded, secrets as `{{secret:KEY}}`. */
|
|
36
|
+
export declare function NiceEnvironmentSetsEditor(props: NiceEnvironmentSetsEditorProps): React.ReactElement;
|
|
37
|
+
/** What NiceDevelopmentStudio hands an editor plug-in (structural — no dependency on ui-forms). */
|
|
38
|
+
export interface NiceApiStudioEditorContext {
|
|
39
|
+
value: unknown;
|
|
40
|
+
onChange: (value: unknown) => void;
|
|
41
|
+
readOnly?: boolean;
|
|
42
|
+
/** The module's files — the integrations editor reads the environment sets from them. */
|
|
43
|
+
files?: readonly {
|
|
44
|
+
path: string;
|
|
45
|
+
text: string;
|
|
46
|
+
}[];
|
|
47
|
+
services?: {
|
|
48
|
+
sendRequest?: unknown;
|
|
49
|
+
resolveSecret?: (key: string) => string | undefined;
|
|
50
|
+
[name: string]: unknown;
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The studio editors for integrations and environment sets — pass to NiceDevelopmentStudio's
|
|
55
|
+
* `editors`: `editors={niceApiStudioEditors({ sendRequest: proxy })}`.
|
|
56
|
+
*/
|
|
57
|
+
export declare function niceApiStudioEditors(services?: {
|
|
58
|
+
sendRequest?: NiceApiTransport;
|
|
59
|
+
resolveSecret?: (key: string) => string | undefined;
|
|
60
|
+
}): Record<'integrations' | 'environments', {
|
|
61
|
+
render: (ctx: NiceApiStudioEditorContext) => React.ReactNode;
|
|
62
|
+
}>;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { default as React } from 'react';
|
|
2
|
+
import { NiceApiAuth, NiceApiBody, NiceApiCollection, NiceApiParam, NiceApiParamLocation, NiceApiRequest, NiceApiResolvedRequest, NiceApiResponse, NiceApiSchema } from '../core';
|
|
3
|
+
/** The method as a coloured badge (GET, POST, …). */
|
|
4
|
+
export declare function ApiMethodBadge({ method }: {
|
|
5
|
+
method: string;
|
|
6
|
+
}): React.ReactElement;
|
|
7
|
+
export interface ApiParamsTableProps {
|
|
8
|
+
rows: NiceApiParam[];
|
|
9
|
+
onChange: (rows: NiceApiParam[]) => void;
|
|
10
|
+
/** The location a new row gets — and, with `fixedLocation`, the only one shown. */
|
|
11
|
+
addLocation: NiceApiParamLocation;
|
|
12
|
+
fixedLocation?: boolean;
|
|
13
|
+
readOnly?: boolean;
|
|
14
|
+
}
|
|
15
|
+
/** Parameters as a table: on/off, key, value, location, description. */
|
|
16
|
+
export declare function ApiParamsTable({ rows, onChange, addLocation, fixedLocation, readOnly, }: ApiParamsTableProps): React.ReactElement;
|
|
17
|
+
export interface ApiAuthEditorProps {
|
|
18
|
+
auth: NiceApiAuth | undefined;
|
|
19
|
+
onChange: (auth: NiceApiAuth) => void;
|
|
20
|
+
readOnly?: boolean;
|
|
21
|
+
/** For requests and folders: offer "inherit" (default). The collection has nothing above it. */
|
|
22
|
+
allowInherit?: boolean;
|
|
23
|
+
/** Obtain an OAuth 2 token (client credentials / password) — shown with the oauth2 kind. */
|
|
24
|
+
onGetToken?: () => void;
|
|
25
|
+
tokenBusy?: boolean;
|
|
26
|
+
}
|
|
27
|
+
/** The auth of a request, folder or collection: the kind, then the fields it needs. */
|
|
28
|
+
export declare function ApiAuthEditor({ auth, onChange, readOnly, allowInherit, onGetToken, tokenBusy, }: ApiAuthEditorProps): React.ReactElement;
|
|
29
|
+
export interface ApiBodyEditorProps {
|
|
30
|
+
body: NiceApiBody;
|
|
31
|
+
onChange: (body: NiceApiBody) => void;
|
|
32
|
+
readOnly?: boolean;
|
|
33
|
+
}
|
|
34
|
+
/** The request body: its kind, then an editor for it. */
|
|
35
|
+
export declare function ApiBodyEditor({ body, onChange, readOnly, }: ApiBodyEditorProps): React.ReactElement;
|
|
36
|
+
/** A schema as a property tree: name, type, required, description — nested objects and arrays open. */
|
|
37
|
+
export declare function ApiSchemaTree({ schema, resolve, depth, }: {
|
|
38
|
+
schema: NiceApiSchema | undefined;
|
|
39
|
+
resolve: (ref: string) => NiceApiSchema | undefined;
|
|
40
|
+
depth?: number;
|
|
41
|
+
}): React.ReactElement | null;
|
|
42
|
+
/** What the client keeps per request: the last response (or error) and what was sent. */
|
|
43
|
+
export interface NiceApiCallState {
|
|
44
|
+
loading?: boolean;
|
|
45
|
+
response?: NiceApiResponse;
|
|
46
|
+
sent?: NiceApiResolvedRequest;
|
|
47
|
+
error?: string;
|
|
48
|
+
}
|
|
49
|
+
/** Code samples: a language picker and the sample, read-only. */
|
|
50
|
+
export declare function ApiCodeSamples({ request, auth, transform, height, }: {
|
|
51
|
+
request: NiceApiRequest;
|
|
52
|
+
auth: NiceApiAuth;
|
|
53
|
+
transform?: (text: string) => string;
|
|
54
|
+
height?: number;
|
|
55
|
+
}): React.ReactElement;
|
|
56
|
+
/** The response of the selected request. */
|
|
57
|
+
export declare function ApiResponsePanel({ state, request, auth, transform, }: {
|
|
58
|
+
state: NiceApiCallState | undefined;
|
|
59
|
+
request: NiceApiRequest;
|
|
60
|
+
auth: NiceApiAuth;
|
|
61
|
+
transform: (text: string) => string;
|
|
62
|
+
}): React.ReactElement;
|
|
63
|
+
/** Documentation of one request: method and path, parameters, body, responses, code. */
|
|
64
|
+
export declare function ApiRequestDocs({ request, collection, auth, transform, }: {
|
|
65
|
+
request: NiceApiRequest;
|
|
66
|
+
collection: NiceApiCollection;
|
|
67
|
+
auth: NiceApiAuth;
|
|
68
|
+
transform: (text: string) => string;
|
|
69
|
+
}): React.ReactElement;
|
|
70
|
+
/** Documentation of the collection: name, version, description, servers, auth, models. */
|
|
71
|
+
export declare function ApiCollectionDocs({ collection, }: {
|
|
72
|
+
collection: NiceApiCollection;
|
|
73
|
+
}): React.ReactElement;
|
package/dist/core/index.d.ts
CHANGED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
import { NiceApiAuth, NiceApiCollection, NiceApiEnvironment } from './model';
|
|
2
|
+
/** Which way the data moves. */
|
|
3
|
+
export type NiceIntegrationDirection = 'inbound' | 'outbound' | 'bidirectional';
|
|
4
|
+
/** The protocols a connection speaks. */
|
|
5
|
+
export type NiceConnectionProtocol = 'rest' | 'graphql' | 'soap' | 'odata' | 'grpc' | 'websocket' | 'sse' | 'webhook' | 'database' | 'sftp';
|
|
6
|
+
export declare const NICE_CONNECTION_PROTOCOLS: readonly NiceConnectionProtocol[];
|
|
7
|
+
/** How a list endpoint pages. */
|
|
8
|
+
export interface NiceConnectionPagination {
|
|
9
|
+
style: 'none' | 'page' | 'offset' | 'cursor' | 'link';
|
|
10
|
+
/** The query parameter (page / offset / cursor) and the page size parameter. */
|
|
11
|
+
param?: string;
|
|
12
|
+
sizeParam?: string;
|
|
13
|
+
size?: number;
|
|
14
|
+
/** Where the next cursor is in the response (`$.meta.next`). */
|
|
15
|
+
nextPath?: string;
|
|
16
|
+
}
|
|
17
|
+
/** Retries on failure. */
|
|
18
|
+
export interface NiceConnectionRetry {
|
|
19
|
+
attempts: number;
|
|
20
|
+
/** Milliseconds before the first retry; doubled each time with `backoff: 'exponential'`. */
|
|
21
|
+
delayMs: number;
|
|
22
|
+
backoff?: 'fixed' | 'exponential';
|
|
23
|
+
/** Status codes worth retrying. Default 429, 502, 503, 504. */
|
|
24
|
+
statuses?: number[];
|
|
25
|
+
}
|
|
26
|
+
/** How to talk to the other side. */
|
|
27
|
+
export interface NiceConnectionDef {
|
|
28
|
+
protocol: NiceConnectionProtocol;
|
|
29
|
+
/** May hold `{{VARIABLES}}`. */
|
|
30
|
+
baseUrl: string;
|
|
31
|
+
auth?: NiceApiAuth;
|
|
32
|
+
headers?: {
|
|
33
|
+
key: string;
|
|
34
|
+
value: string;
|
|
35
|
+
}[];
|
|
36
|
+
pagination?: NiceConnectionPagination;
|
|
37
|
+
retry?: NiceConnectionRetry;
|
|
38
|
+
/** Requests per second the other side allows. */
|
|
39
|
+
rateLimit?: number;
|
|
40
|
+
timeoutMs?: number;
|
|
41
|
+
}
|
|
42
|
+
/** An endpoint the module exposes (a webhook it receives, an API it serves). */
|
|
43
|
+
export interface NiceExposedEndpoint {
|
|
44
|
+
key: string;
|
|
45
|
+
method: string;
|
|
46
|
+
path: string;
|
|
47
|
+
/** The script / controller that handles it (`scripting.controllers` in OmniVerk). */
|
|
48
|
+
handler?: string;
|
|
49
|
+
/** Who may call it: `none`, an API key, the platform's session, a signature. */
|
|
50
|
+
auth?: 'none' | 'apiKey' | 'session' | 'signature';
|
|
51
|
+
description?: string;
|
|
52
|
+
}
|
|
53
|
+
/** Moving data: call an endpoint, read from / write to a data source, map the fields. */
|
|
54
|
+
export interface NiceIntegrationOperation {
|
|
55
|
+
key: string;
|
|
56
|
+
name?: string;
|
|
57
|
+
/** The id of the consumed request in `endpoints`, or the key of an exposed endpoint. */
|
|
58
|
+
endpoint?: string;
|
|
59
|
+
/** Where the data comes from: a data source key, an entity, `response`. */
|
|
60
|
+
source?: string;
|
|
61
|
+
/** Where it goes. */
|
|
62
|
+
target?: string;
|
|
63
|
+
/** Target field → source expression (`$.items[*].id`, `{{field}}`, a constant). */
|
|
64
|
+
mapping?: Record<string, string>;
|
|
65
|
+
/** `manual`, `schedule:<cron>`, `event:<name>`, `webhook`. */
|
|
66
|
+
trigger?: string;
|
|
67
|
+
/** Both sides changed: which wins. */
|
|
68
|
+
conflict?: 'source' | 'target' | 'newest' | 'manual';
|
|
69
|
+
/** Fetch only what changed since the last run, by this field. */
|
|
70
|
+
incremental?: string;
|
|
71
|
+
}
|
|
72
|
+
/** One integration of a module. */
|
|
73
|
+
export interface NiceIntegrationDef {
|
|
74
|
+
key: string;
|
|
75
|
+
name: string;
|
|
76
|
+
/** Grouping in the tree: `Banking/PSD2`, `Shipping/DHL`. */
|
|
77
|
+
package?: string;
|
|
78
|
+
direction: NiceIntegrationDirection;
|
|
79
|
+
description?: string;
|
|
80
|
+
/** What it needs to work. */
|
|
81
|
+
requires?: {
|
|
82
|
+
modules?: string[];
|
|
83
|
+
dataSources?: string[];
|
|
84
|
+
integrations?: string[];
|
|
85
|
+
};
|
|
86
|
+
connection: NiceConnectionDef;
|
|
87
|
+
/** The API it consumes. */
|
|
88
|
+
endpoints: NiceApiCollection;
|
|
89
|
+
/** What it serves. */
|
|
90
|
+
expose?: NiceExposedEndpoint[];
|
|
91
|
+
operations?: NiceIntegrationOperation[];
|
|
92
|
+
}
|
|
93
|
+
/** A module's `{prefix}.integrations.json`. */
|
|
94
|
+
export interface NiceIntegrationsFile {
|
|
95
|
+
integrations: NiceIntegrationDef[];
|
|
96
|
+
}
|
|
97
|
+
/** A declared variable (its values live in the sets). */
|
|
98
|
+
export interface NiceEnvironmentVariableDecl {
|
|
99
|
+
key: string;
|
|
100
|
+
description?: string;
|
|
101
|
+
/** Kept out of seeds: its value is `{{secret:KEY}}`, resolved by the host. */
|
|
102
|
+
secret?: boolean;
|
|
103
|
+
required?: boolean;
|
|
104
|
+
/** The value when no set gives one. */
|
|
105
|
+
defaultValue?: string;
|
|
106
|
+
}
|
|
107
|
+
/** A set of values: dev, test, prod, a customer's own. */
|
|
108
|
+
export interface NiceEnvironmentSet {
|
|
109
|
+
id: string;
|
|
110
|
+
name: string;
|
|
111
|
+
/** Takes every value of that set it does not give itself. */
|
|
112
|
+
extends?: string;
|
|
113
|
+
/** Used for one database only (the host picks the set by the database it runs on). */
|
|
114
|
+
appliesTo?: {
|
|
115
|
+
database?: string;
|
|
116
|
+
};
|
|
117
|
+
values: Record<string, string>;
|
|
118
|
+
}
|
|
119
|
+
/** A module's `{prefix}.environments.json`. */
|
|
120
|
+
export interface NiceEnvironmentSets {
|
|
121
|
+
variables: NiceEnvironmentVariableDecl[];
|
|
122
|
+
sets: NiceEnvironmentSet[];
|
|
123
|
+
}
|
|
124
|
+
/** A new integration with an empty connection and API. */
|
|
125
|
+
export declare function newIntegration(init?: Partial<NiceIntegrationDef>): NiceIntegrationDef;
|
|
126
|
+
/**
|
|
127
|
+
* The values of set `id` with everything it inherits: its own values over its parent's over the
|
|
128
|
+
* grandparent's…, then the declared defaults. A cycle stops at the first repeated set.
|
|
129
|
+
*/
|
|
130
|
+
export declare function resolveEnvironmentSet(sets: NiceEnvironmentSets, id: string): Record<string, string>;
|
|
131
|
+
/** Where a set's value of `key` comes from: itself, a set it extends (its id), a default, or nowhere. */
|
|
132
|
+
export declare function valueOrigin(sets: NiceEnvironmentSets, id: string, key: string): {
|
|
133
|
+
value?: string;
|
|
134
|
+
from: 'own' | 'inherited' | 'default' | 'none';
|
|
135
|
+
set?: string;
|
|
136
|
+
};
|
|
137
|
+
/** The sets as environments for NiceApiClient (inheritance resolved). */
|
|
138
|
+
export declare function toApiEnvironments(sets: NiceEnvironmentSets): NiceApiEnvironment[];
|
|
139
|
+
/** The set for a database: the one that applies to it, else the first without `appliesTo`. */
|
|
140
|
+
export declare function environmentSetFor(sets: NiceEnvironmentSets, database?: string): NiceEnvironmentSet | undefined;
|
|
141
|
+
/** A problem found in a module's integrations. */
|
|
142
|
+
export interface NiceIntegrationIssue {
|
|
143
|
+
severity: 'error' | 'warning';
|
|
144
|
+
integration?: string;
|
|
145
|
+
/** A stable code (for translations): `variableUndeclared`, `secretInSeed`, … */
|
|
146
|
+
code: 'keyDuplicate' | 'baseUrlMissing' | 'variableUndeclared' | 'secretInSeed' | 'requiredUnset' | 'endpointMissing' | 'extendsMissing' | 'requiresMissing';
|
|
147
|
+
message: string;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* Checks a module's integrations against its environment sets: unique keys, a base URL, every
|
|
151
|
+
* `{{variable}}` declared, no secret written as a plain value, required variables set in every set,
|
|
152
|
+
* operations pointing at existing endpoints, `extends` to existing sets, and — given the module's
|
|
153
|
+
* neighbours — what `requires` names exists.
|
|
154
|
+
*/
|
|
155
|
+
export declare function validateIntegrations(file: NiceIntegrationsFile, sets?: NiceEnvironmentSets, known?: {
|
|
156
|
+
modules?: string[];
|
|
157
|
+
dataSources?: string[];
|
|
158
|
+
}): NiceIntegrationIssue[];
|
|
159
|
+
/** The integrations grouped for a tree: package → direction → integrations. */
|
|
160
|
+
export declare function groupIntegrations(integrations: readonly NiceIntegrationDef[]): {
|
|
161
|
+
package: string;
|
|
162
|
+
directions: {
|
|
163
|
+
direction: NiceIntegrationDirection;
|
|
164
|
+
integrations: NiceIntegrationDef[];
|
|
165
|
+
}[];
|
|
166
|
+
}[];
|
|
167
|
+
/** Every request of an integration's API and every endpoint it exposes, for pickers (operation → endpoint). */
|
|
168
|
+
export declare function integrationEndpoints(integration: NiceIntegrationDef): {
|
|
169
|
+
id: string;
|
|
170
|
+
label: string;
|
|
171
|
+
exposed: boolean;
|
|
172
|
+
}[];
|