@bratislava/ginis-sdk 0.5.1 → 1.0.0
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/README.md +102 -63
- package/dist/index.d.ts +2096 -230
- package/dist/index.js +1053 -112
- package/package.json +45 -19
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@bratislava/ginis-sdk)
|
|
4
4
|
|
|
5
|
-
A small wrapper for most commonly used requests towards the GINIS system. Made to be used by applications of city of [Bratislava](https://github.com/bratislava)
|
|
5
|
+
A small wrapper for most commonly used requests towards the GINIS system. Made to be used by applications of city of [Bratislava](https://github.com/bratislava).
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
@@ -10,7 +10,7 @@ A small wrapper for most commonly used requests towards the GINIS system. Made t
|
|
|
10
10
|
|
|
11
11
|
## Using the library
|
|
12
12
|
|
|
13
|
-
To understand how the structure of `Ginis
|
|
13
|
+
To understand how the structure of `Ginis` and `urls` part of the config relates to the GINIS system, read the [GINIS section](https://bratislava.github.io/GINIS) of our documentation site.
|
|
14
14
|
|
|
15
15
|
You'll need the GINIS credentials. If interacting with the Bratislava deployment, you also need to be connected through VPN or on internal network.
|
|
16
16
|
|
|
@@ -24,97 +24,136 @@ const ginis = new Ginis({
|
|
|
24
24
|
ssl: 'http://host/your/ssl/endpoint/Ssl.svc',
|
|
25
25
|
},
|
|
26
26
|
// credentials
|
|
27
|
-
username: process.env
|
|
28
|
-
password: process.env
|
|
27
|
+
username: process.env['GINIS_USERNAME'],
|
|
28
|
+
password: process.env['GINIS_PASSWORD'],
|
|
29
29
|
// if debug === true prints all the requests and responses into console
|
|
30
|
-
//
|
|
30
|
+
// WARNING - these logs WILL include credentials!
|
|
31
31
|
debug: true,
|
|
32
32
|
})
|
|
33
33
|
```
|
|
34
34
|
|
|
35
|
-
Use the
|
|
35
|
+
Use the requests:
|
|
36
36
|
|
|
37
37
|
```ts
|
|
38
38
|
// the options object uses same keys as the requests in Ginis docs
|
|
39
39
|
// i.e. https://robot.gordic.cz/xrg/Default.html?c=OpenMethodDetail&moduleName=UDE&version=390&methodName=seznam-dokumentu&type=request
|
|
40
|
-
// will throw
|
|
41
|
-
const data = await ginis.
|
|
40
|
+
// will throw a Ginis error if the request fails
|
|
41
|
+
const data = await ginis.ssl.detailDokumentu({
|
|
42
42
|
'Id-dokumentu': 'MAG0X03RYYSN',
|
|
43
43
|
})
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
+
All requests and responses of this library are via JavaScript objects. However, due to underlying Ginis API using XMLs, the object properties are kept consistent with them. They are using a dash case with only the very first letter being capital written in Czech such as `'Id-dokumentu'`, `'Souvisejici-dokumenty'`, or `'Historie-dokumentu'`.
|
|
47
|
+
|
|
48
|
+
### Error handling
|
|
49
|
+
|
|
50
|
+
The library should only throw instances of `GinisError` for all expected or predictable erroneous situations. If the underlying cause is `AxiosError`, the whole error will be available inside the `GinisError` object under `axiosError` property.
|
|
51
|
+
|
|
52
|
+
### Response guarantees
|
|
53
|
+
|
|
54
|
+
All responses from this library are validated using `zod` to check for required parameters. Furthermore, all array properties are guaranteed to be defined and to be array. If there are no elements, the array will be empty and if there is only one elements, it will still be wrapped in an array.
|
|
55
|
+
|
|
56
|
+
All values are only defined as strings and are not validated further; e.g. there is no check if
|
|
57
|
+
|
|
58
|
+
- value matches one of the enum values for enum fields
|
|
59
|
+
- value is numeric or in specified range for number fields
|
|
60
|
+
- value matches the format for date fields
|
|
61
|
+
|
|
46
62
|
## Extending the library
|
|
47
63
|
|
|
48
64
|
The `src/api` is structured after the GINIS modules, each subdirectory a single service, each file a single action - for more info on the hierarchy, see our [GINIS docs](https://bratislava.github.io/GINIS).
|
|
49
65
|
|
|
50
|
-
|
|
66
|
+
TS docs frequently reference [the official Gordic documentation](https://robot.gordic.cz/xrg/Default.html) (you'll need to create an account to access it). Once you are logged in, you can browse the full docs with request/response formats and all the available endpoints (of which we wrap just a subset).
|
|
51
67
|
|
|
52
|
-
|
|
68
|
+
You can read / reproduce / add new requests in the `/src/api/[service-name]/[Action-name].ts`. Read through a couple files and you should be set. Since the Ginis API uses SOAP directly or inside a multipart request, there are some challenges when dealing with XMLs.
|
|
53
69
|
|
|
54
|
-
|
|
70
|
+
### XML accommodations
|
|
55
71
|
|
|
56
|
-
|
|
72
|
+
#### Request type
|
|
57
73
|
|
|
58
|
-
|
|
74
|
+
The most important part of this particular Ginis API is that the order of the parameters for each request must be in the same order as defined in request's Gordic documentation. JavaScript objects don't guarantee any property order when iterating over them. For this reason, all properties for all requests are defined in an array, and the request type is dynamically derived from it:
|
|
59
75
|
|
|
60
|
-
|
|
76
|
+
```ts
|
|
77
|
+
// https://robot.gordic.cz/xrg/Default.html?c=OpenMethodDetail&moduleName=SSL&version=390&methodName=Detail-dokumentu&type=request
|
|
78
|
+
const detailDokumentuRequestProperties = [
|
|
79
|
+
'Id-dokumentu',
|
|
80
|
+
'Vyradit-historii',
|
|
81
|
+
'Vyradit-obsah-spisu',
|
|
82
|
+
'Vyradit-prilohy',
|
|
83
|
+
'Vyradit-souvisejici',
|
|
84
|
+
'Id-esu',
|
|
85
|
+
'Vyradit-doruceni',
|
|
86
|
+
'Id-eu',
|
|
87
|
+
] as const
|
|
88
|
+
|
|
89
|
+
export type DetailDokumentuRequest = {
|
|
90
|
+
[K in (typeof detailDokumentuRequestProperties)[number] as K]?: string
|
|
91
|
+
}
|
|
92
|
+
```
|
|
61
93
|
|
|
62
|
-
|
|
94
|
+
Currently, all request properties are marked as optional strings regardless of their actual type or if they are required by the endpoint. There is no input validation on the library side and all requests are ultimately accepted or rejected directly by the underlying Ginis API.
|
|
63
95
|
|
|
64
|
-
|
|
96
|
+
#### Response type
|
|
65
97
|
|
|
66
|
-
|
|
98
|
+
Instead of response type we primarily define a validation `zod` schema. We validate the output of the Ginis API to guarantee, that all the required fields are present and populated. We don't validate values as all simple properties are only utilizing string type - see [response guarantees](#response-guarantees).
|
|
67
99
|
|
|
68
100
|
```ts
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
)
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
<o:Username>${config.username}</o:Username>
|
|
90
|
-
<o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">${
|
|
91
|
-
config.password
|
|
92
|
-
}</o:Password>
|
|
93
|
-
</o:UsernameToken>
|
|
94
|
-
</o:Security>
|
|
95
|
-
</s:Header>
|
|
96
|
-
<s:Body>
|
|
97
|
-
<Seznam-dokumentu
|
|
98
|
-
xmlns="http://www.gordic.cz/svc/xrg-ude/v_1.0.0.0">
|
|
99
|
-
<requestXml>
|
|
100
|
-
<Xrg
|
|
101
|
-
xmlns="http://www.gordic.cz/xrg/ude/seznam-dokumentu/request/v_1.0.0.0">
|
|
102
|
-
<Seznam-dokumentu>
|
|
103
|
-
${Object.entries(bodyObj).map(([key, value]) => `<${key}>${value}</${key}>`)}
|
|
104
|
-
</Seznam-dokumentu>
|
|
105
|
-
</Xrg>
|
|
106
|
-
</requestXml>
|
|
107
|
-
</Seznam-dokumentu>
|
|
108
|
-
</s:Body>
|
|
109
|
-
</s:Envelope>
|
|
110
|
-
`
|
|
111
|
-
return makeAxiosRequest(axiosConfig, url, body, config.debug)
|
|
112
|
-
}
|
|
101
|
+
const detailElPodaniSchema = z.object({
|
|
102
|
+
'Datum-prijeti': z.string(),
|
|
103
|
+
'Stav-zpracovani': z.string(),
|
|
104
|
+
'Duvod-odmitnuti': z.string().optional(),
|
|
105
|
+
'Stav-podani-kod': z.string(),
|
|
106
|
+
'Stav-podani-text': z.string().optional(),
|
|
107
|
+
'Stav-odpovedi-kod': z.string(),
|
|
108
|
+
'Stav-odpovedi-text': z.string().optional(),
|
|
109
|
+
'Id-dokumentu': z.string().optional(),
|
|
110
|
+
Vec: z.string().optional(),
|
|
111
|
+
'Spis-znacka': z.string().optional(),
|
|
112
|
+
Znacka: z.string().optional(),
|
|
113
|
+
})
|
|
114
|
+
|
|
115
|
+
const navazanyDokumentSchema = z.object({
|
|
116
|
+
'Id-dokumentu': z.string(),
|
|
117
|
+
Vec: z.string().optional(),
|
|
118
|
+
'Spis-znacka': z.string().optional(),
|
|
119
|
+
Znacka: z.string().optional(),
|
|
120
|
+
})
|
|
113
121
|
```
|
|
114
122
|
|
|
115
|
-
|
|
123
|
+
Also, we transform all the array fields to actually contain array - empty, with one element, or multiple elements - regardless if the response contains the property or not via the `coercedArray` helper.
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
const detailElPodaniResponseSchema = z.object({
|
|
127
|
+
'Detail-el-podani': detailElPodaniSchema,
|
|
128
|
+
'Navazany-dokument': coercedArray(navazanyDokumentSchema),
|
|
129
|
+
})
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Then, the response type is derived from the schema as such:
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
export type DetailElPodaniResponse = z.infer<typeof detailElPodaniResponseSchema>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Developing and running tests
|
|
139
|
+
|
|
140
|
+
For each new service / request you should add appropriate tests in the `__tests__` subdirectory of the service directory, one file per request.
|
|
141
|
+
|
|
142
|
+
You need to have GINIS credentials setup in `.env` file - see `.env.example`. If interacting with the Bratislava deployment, you also need to be connected through VPN or on internal network.
|
|
143
|
+
|
|
144
|
+
Start the test using
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
npm run test
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
If you are experiencing circular structure errors related to `req` and/or `rsp` in jest while testing locally, instead use
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
npm run test:detect
|
|
154
|
+
```
|
|
116
155
|
|
|
117
|
-
|
|
156
|
+
which detects open handles preventing this issue.
|
|
118
157
|
|
|
119
158
|
## License
|
|
120
159
|
|