@weclapp/sdk 2.0.0-dev.6 → 2.0.0-dev.60

package/README.md

@@ -1,17 +1,19 @@
-<br/>
+# weclapp SDK Generator
 
-<div align="center">
-    <h3>weclapp sdk generator</h3>
-</div>
+## Introduction
 
-<br/>
+This is an SDK generator, it will take an [`openapi.json`](https://swagger.io/specification/) from [weclapp](https://weclapp.com/) and build services and typescript types according to the entities defined in it. Each service is responsible for a _single_ entity. Every service contains all functions available for this
+entity, this may include functions such as `update`, `remove`, `some` and many more. With these functions you can send requests to your weclapp system to get data or manipulate them.
 
-### Getting started
+An entity is a resource with properties in weclapp. This can be an article, a contract or a quotation. The SDK generates a well-defined typescript type for each entity and its property. In this way, the SDK makes it possible to work with the data retrieved via the API in a type-safe manner.
+
+Check out [generated types and utilities](#generated-types-and-utilities) for more possibilities!
 
-This is an SDK generator, it will take an [`openapi.json`](https://swagger.io/specification/) from [weclapp](https://weclapp.com/) and build services and types according to the entities defined in it.
 What's being generated depends on the weclapp version you're using.
 
-The SDK generator requires the current or LTS version of nodejs, as well as npm v9 or v8.
+## Getting started
+
+The SDK generator requires the current or LTS version of nodejs, as well as npm v10.
 
 You can install the generator via the package manager of your choice:
 
@@ -31,28 +33,525 @@ This way, every time someone installs or updates dependencies, the SDK is genera
 ```json5
 {
   // in your package.json
-  "scripts": {
-    "sdk:generate": "build-weclapp-sdk company.weclapp.com --key [your api key] --cache --target browser",
-    "postinstall": "npm run sdk:generate",
+  scripts: {
+    'sdk:generate': 'build-weclapp-sdk company.weclapp.com --key [your api key] --cache --target browser',
+    postinstall: 'npm run sdk:generate'
   }
 }
 ```
 
+### Available flags
+
+| Flag                   | Description                                                                                                                                              | Value / Type                                 |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `--cache` / `-c`       | Extra query params when fetching the openapi.json from a server.                                                                                         | `boolean`                                    |
+| `--deprecated` / `-d`  | Include deprecated functions and services.                                                                                                               | `boolean`                                    |
+| `--from-env` / `-e`    | Use env variables `WECLAPP_BACKEND_URL` and `WECLAPP_API_KEY` as credentials.                                                                            | `boolean`                                    |
+| `--generate-unique`    | Generate additional `.unique` functions.                                                                                                                 | `boolean`                                    |
+| `--use-query-language` | Use the advanced query language. The property _filter_ will be removed from _SomeQuery_ and _CountQuery_ and the property _where_ will be added instead. | `boolean`                                    |
+| `--help` / `-h`        | Show help.                                                                                                                                               | `boolean`                                    |
+| `--key` / `-k`         | API Key in case of using a remote.                                                                                                                       | `string`                                     |
+| `--target` / `-t`      | Specify the target platform.                                                                                                                             | `browser`, `browser.rx`, `node` or `node.rx` |
+| `--query` / `-q`       | Extra query params when fetching the openapi.json from a server                                                                                          | `string`                                     |
+| `--version` / `-v`     | Show version of SDK.                                                                                                                                     | `boolean`                                    |
+
 After that, you can import the sdk via `@weclapp/sdk`.
 Check out the [docs](docs) for how the generated SDK looks like and how to use it!
 
-### Available flags
+## Initialization
+
+To initialize a service a `ServiceConfig` is needed, you can specify a global config in case you don't want to pass the config every time to the service you
+want to use manually. If you pass an empty object as ServiceConfig the [location](https://developer.mozilla.org/en-US/docs/Web/API/Window/location) will be used to get the domain and the protocol (secure config option).
+
+### Service config
+
+The configuration looks like the following (taken from [globalConfig.ts](/src/generator/01-base/static/globalConfig.ts.txt)):
+
+```ts
+interface ServiceConfig {
+  // Your API-Key, this is optional in the sense of if you omit this, and you're in a browser, the
+  // cookie-authentication (include-credentials) will be used.
+  key?: string;
+
+  // Your domain, if omitted location.host will be used.
+  domain?: string;
+
+  // If you want to use https, defaults to false.
+  secure?: boolean;
+
+  // If you want that some and count requests are bundled into multi requests.
+  multiRequest?: boolean;
+
+  // If you want that the ignoreMissingProperties parameter to be set for each post request.
+  ignoreMissingProperties?: boolean;
+
+  // Optional request/response interceptors.
+  interceptors?: {
+    // Takes the generated request, you can either return a new request,
+    // a response (which will be taken as "the" response) or nothing.
+    // The payload contains the raw input generated by the SDK.
+    request?: (
+      request: Request,
+      payload: RequestPayload
+    ) => Request | Response | void | Promise<Request | Response | void>;
+
+    // Takes the response. This can either be the one from the server or an
+    // artificially-crafted one by the request interceptor.
+    response?: (response: Response) => Response | void | Promise<Response | void>;
+  };
+
+  // Whether POST should be used instead of GET for some() and count() operations
+  usePost?: boolean;
+}
+```
+
+### Using the config
+
+There are three ways of accessing a service through the SDK:
+
+#### Using the global config
+
+```ts
+import { setGlobalConfig, partyService } from '@weclapp/sdk';
+
+setGlobalConfig({
+  key: 'mykey',
+  domain: 'myweclapp.com'
+});
+
+const party = partyService();
+
+console.log(`Total amount of parties: ${await party.count()}`);
+```
+
+#### Using a config per service
+
+```ts
+import { partyService } from '@weclapp/sdk';
+
+const party = partyService({
+  key: 'mykey',
+  domain: 'myweclapp.com'
+});
+
+console.log(`Total amount of parties: ${await party.count()}`);
+```
+
+> If a global config is specified as well the one passed to the service will **always** take precedence over the global one!
+
+#### Using the raw function
+
+The raw function can be used if none of the provided function suits your needs. The services use the raw function, which makes the API requests via [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API):
+
+```ts
+import { raw } from '@weclapp/sdk';
+
+const result = await raw(
+    cfg: ServiceConfig | undefined = globalConfig,
+    endpoint: string,
+    payload: RequestPayload = {}
+);
+```
+
+where `RequestPayload` looks like this:
+
+```ts
+interface RequestPayload {
+  method?: RequestPayloadMethod; // Optional request method, default is GET
+  query?: Record<string, any>; // Optional query parameters
+  body?: any; // Optional body
+
+  // In case the response body is an object with a result-prop the value will be extracted
+  unwrap?: boolean;
+
+  // If in any case the response should be returned as a blob.
+  // Required for download endpoints as json will be parsed automatically.
+  forceBlob?: boolean;
+}
+```
+
+and `RequestOptions` looks like this:
+
+```ts
+interface RequestOptions {
+  signal?: AbortSignal;
+}
+```
+
+## Generated types and utilities
+
+The generator generates various utilities that can be used to integrate it in a generic way into your app.
+
+### Exported constants
+
+| Constant                    | Description                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `wServiceWith[method]Names` | An array of services (strings) that have this function. Example: `wServiceWithUpdateNames`.                            |
+| `wCustomValueServiceNames`  | An array of services (strings) that work with `CustomValue`.                                                           |
+| `wEnums`                    | Object with the name of the enum as key and the corresponding enum as value.                                           |
+| `wServiceFactories`         | Object with all services where the name is the key and the value a function taking a config and returning the service. |
+| `wServices`                 | Object with all services where the name is the key and the value the service (that is using the global config).        |
+| `wEntityProperties`         | Object with all entity names as key and properties including the type and format as value.                             |
+
+### Exported types
+
+| Type                    | Description                                                                                                 | Type guards available?                |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `WServiceWith[method]`  | A tuple of strings with the names of the services that contain this function. Example: `WServiceWithSome`.  | Yes, for example `isWServiceWithSome` |
+| `WServicesWith[method]` | An interface with the service-name as key and corresponding service as value. Example: `WServicesWithSome`. |                                       |
+| `WCustomValueService`   | Tuple of services (strings) that work with `CustomValue`.                                                   | Yes: `isWCustomValueService`          |
+| `WEnums`                | Type of `wEnums`.                                                                                           |                                       |
+| `WEnum`                 | All keys of `WEnums`.                                                                                       |                                       |
+| `WEntities`             | Interface will all entities from weclapp with their name as key and type as value                           |                                       |
+| `WEntity`               | All keys of `WEntities`.                                                                                    |                                       |
+| `WServiceFactories`     | Type of `wServiceFactories`.                                                                                |                                       |
+| `WServices`             | Type of `wServices`.                                                                                        |                                       |
+| `WEntityProperties`     | Generalized type of `wEntityProperties`.                                                                    |                                       |
+
+## Services and raw-function in depth
+
+As already described above, the api endpoints can be requested via services or the raw function. The advantage of wServices over the raw function is that all endpoints of the entities are available as functions and these functions are typed. This makes it easier to work with the data provided via the weclapp API.
+
+A service of an entity has in general the following base function:
+
+    some: // get entity data
+    create: // creates a entity
+    count: // get the count of entities
+    remove: // deletes a entity
+    update: // updates a entity
+
+In addition, there are some custom endpoint functions. The generated PartyService is shown below as an example:
+
+```ts
+interface PartyService {
+  some: PartyService_Some;
+  create: PartyService_Create;
+  count: PartyService_Count;
+  remove: PartyService_Remove;
+  update: PartyService_Update;
+  postCreatePublicPageById: PartyService_PostCreatePublicPageById;
+  getDownloadImageById: PartyService_GetDownloadImageById;
+  getTopPurchaseArticlesById: PartyService_GetTopPurchaseArticlesById;
+  getTopSalesArticlesById: PartyService_GetTopSalesArticlesById;
+  postUploadImageById: PartyService_PostUploadImageById;
+}
+```
+
+### Example
+
+```ts
+import { PartyType, setGlobalConfig, wServices } from '@weclapp/sdk';
+
+setGlobalConfig({
+  domain: 'company.weclapp.com',
+  secure: true
+});
+
+// to get the count of parties via service
+const serviceN = await wServices['party'].count();
+
+// to get the count of parties via raw
+const rawN = await raw(undefined, '/party/count');
+
+// to get all parties via service
+const partiesService = await wServices['party'].some();
+
+// to get all parties via raw
+const partiesRaw = await raw(undefined, '/party');
+
+// to create a party via service
+const contact = await wServices['party'].create({
+  partyType: PartyType.PERSON,
+  lastName: 'Mueller'
+}); // the returned object is already typed as Party
+
+// to create a party via raw
+const contactRaw = await await raw(undefined, '/party', {
+  // the returned object has the type any.
+  method: 'POST',
+  body: { partyType: PartyType.PERSON, lastName: 'Mueller' }
+});
+
+// to delete a party via service
+await wServices['party'].remove(contact.id);
 
-| Flag                | Description                                                                   | Value / Type                                 |
-|---------------------|-------------------------------------------------------------------------------|----------------------------------------------|
-| `--help` / `-h`     | Show help.                                                                    | `boolean`                                    |
-| `--version` / `-v`  | Show version of SDK.                                                          | `boolean`                                    |
-| `--key` / `-k`      | API Key in case of using a remote.                                            | `string`                                     |
-| `--cache` / `-c`    | Extra query params when fetching the openapi.json from a server.              | `boolean`                                    |
-| `--from-env` / `-e` | Use env variables `WECLAPP_BACKEND_URL` and `WECLAPP_API_KEY` as credentials. | `boolean`                                    |
-| `--target` / `-t`   | Specify the target platform.                                                  | `browser`, `browser.rx`, `node` or `node.rx` |
-| `--generate-unique` | Generate additional `.unique` functions.                                      | `boolean`                                    |
+// to delete a party via raw
+if (contactRaw && typeof contactRaw.id === 'string') {
+  await raw(undefined, `/party/id/${contactRaw.id}`, {
+    method: 'DELETE'
+  });
+}
+```
+
+### Service request params
+
+#### Filtering
+
+With the some and count functions you can filter the requested data.
+
+```ts
+wServices['article'].some({
+  filter: {
+    name: { EQ: 'toy 1' },
+    articleNumber: { EQ: '12345' }
+  }
+});
+```
+
+The SDK makes an AND operator between the properties. So this equivalent to the follwing expression:
+
+    name EQ 'toy 1' AND articleNumber EQ '12345'.
+
+If you want an OR operator you have to set an array in the or property:
+
+```ts
+wServices['article'].some({
+  or: [
+    {
+      name: { EQ: 'toy 1' },
+      articleNumber: { EQ: '12345' }
+    }
+  ]
+});
+```
+
+The above example is the equivalent of the expression
+
+    name EQ 'toy 1' OR articleNumber EQ '12345'.
+
+To combine OR and AND clauses, you can also group OR expressions by adding several objects to the array:
+
+```ts
+wServices['article'].some({
+  or: [
+    {
+      name: { EQ: 'toy 1' },
+      articleNumber: { EQ: '12345' }
+    },
+    {
+      batchNumberRequired: { EQ: true }
+    }
+  ]
+});
+```
+
+This is evaluated to:
+(name EQ 'toy 1' OR articleNumber EQ '12345') AND batchNumberRequired EQ true
+
+#### Where filter
+
+> Warning: This is still a beta feature
+
+It is also possible to specify complex filter expressions that can combine multiple conditions and express relations between properties:
+
+```ts
+wServices['article'].some({
+  where: {
+    AND: [
+      {
+        OR: [{ name: { LIKE: '%test%', lower: true } }, { articleNumber: { LIKE: '%345%' } }]
+      },
+      { batchNumberRequired: { EQ: true } }
+    ]
+  }
+});
+```
+
+"where" parameters are ANDed with other filter parameters.
+
+It is also possible to set an empty list within an IN-query:
+
+```ts
+wServices['article'].some({
+  where: {
+    id: {
+      IN: []
+    }
+  }
+});
+```
+
+This actually evaluates to `filter = 1 = 0`. The API does not accept filtering for empty lists. Therefore, in this case you have to send a falsy expression. You cannot send `false` directly, though.
+
+#### Sort
+
+You can sort your requested data with an array properties.
+
+```ts
+wServices['article'].some({
+  sort: [{ name: 'asc' }, { minimumPurchaseQuantity: 'desc' }]
+});
+```
+
+Sort by name (ascending) and then minimumPurchaseQuantity descending.
+
+#### Pagination
+
+By default the API returns only the first 100 entities. You can increase the size of one response to the maximum of 1000. To get the next 1000 entities you have increase the page number.
+
+```ts
+wServices['article'].some({
+  pagination: {
+    page: 2,
+    pageSize: 10
+  }
+});
+```
+
+This returns the first 10 articles of the second page.
+
+#### Select
+
+With the select option you can fetch specific subset of properties:
+
+```ts
+wServices['article'].some({
+  select: { articleNumber: true }
+});
+```
+
+This only returns the articleNumber property of all articles.
+
+#### Ordering
+
+With the some function you can order requested data. You can either merely order by fields or by complex expressions.
+
+```ts
+/**
+ * Order by createdDate in ascending order.
+ *
+ * ?orderBy=createdDate asc
+ */
+wServices['article'].some({
+  orderBy: [{ FIELD: 'createdDate', SORT: 'asc' }]
+});
+```
+
+```ts
+/**
+ * First order by createdDate in ascending order, then by articleNumber in descending order
+ * If you omit SORT the default ordering will be set to ascending.
+ *
+ * ?orderBy=createdDate asc, articleNumber desc
+ */
+wServices['article'].some({
+  orderBy: [{ FIELD: 'createdDate' }, { FIELD: 'articleNumber', SORT: 'desc' }]
+});
+```
+
+```ts
+/**
+ * Order with conditional sorting: if internalNote is not null then 1,
+ * if packagingQuantity > 400 then 2, otherwise 3.
+ * Then order by articleNumber in ascending order.
+ *
+ * ?orderBy=(not internalNote null) ? 1 : (packagingQuantity > 400) ? 2 : 3 asc, articleNumber asc
+ */
+wServices['article'].some({
+  orderBy: [
+    {
+      CASE: [
+        { WHEN: { internalNote: { NULL: false } }, THEN: 1 },
+        { WHEN: { packagingQuantity: { GT: 400 } }, THEN: 2 }
+      ],
+      ELSE: 3,
+      SORT: 'asc'
+    },
+    { FIELD: 'articleNumber' }
+  ]
+});
+```
+
+The `THEN` and `ELSE` values can also be a `FieldOrderBy` to fall back to a field-based ordering:
+
+```ts
+/**
+ * Order with conditional sorting: if internalNote is not null, order by articleNumber,
+ * otherwise order by createdDate.
+ *
+ * ?orderBy=(not internalNote null) ? articleNumber : createdDate asc
+ */
+wServices['article'].some({
+  orderBy: [
+    {
+      CASE: [{ WHEN: { internalNote: { NULL: false } }, THEN: { FIELD: 'articleNumber' } }],
+      ELSE: { FIELD: 'createdDate' },
+      SORT: 'asc'
+    }
+  ]
+});
+```
+
+For properties that are objects or arrays of objects, use dot-notation to reference nested fields:
+
+```ts
+/**
+ * Order by a nested property of an array/object field.
+ *
+ * ?orderBy=articlePrices.price asc
+ */
+wServices['article'].some({
+  orderBy: [{ FIELD: 'articlePrices.price', SORT: 'asc' }]
+});
+```
+
+There are three modifier functions, `TRIM`, `LOWER` and `LENGTH`, which can be used to adjust the expessions:
+
+```ts
+/**
+ * First order by the length of the trimmed lastName in descending order, then by firstName in ascending order
+ *
+ * ?orderBy=length(trim(lastName)) desc, firstName asc
+ */
+wServices['party'].some({
+  orderBy: [
+    {
+      FIELD: 'lastName',
+      LENGTH: true,
+      TRIM: true,
+      SORT: 'desc'
+    },
+    { FIELD: 'firstName' }
+  ]
+});
+```
+
+### Aborting a request
+
+To abort a request an AbortController has to be instantiated and its signal has to be passed to the request. The controller can
+abort the request when needed and the case can be handled with a catch.
+
+```ts
+import { wServices } from '@sdk/dist';
+
+const controller = new AbortController();
+let count = 0;
+
+wServices.article
+  .count(
+    {
+      where: {
+        active: { EQ: true }
+      }
+    },
+    { signal: controller.signal }
+  )
+  .then((c) => (count = c))
+  .catch((err) => {
+    if (controller.signal.aborted) {
+      if (controller.signal.reason) {
+        console.log(`Request aborted with reason: ${controller.signal.reason}`);
+      } else {
+        console.log('Request aborted but no reason was given.');
+      }
+    } else {
+      console.log(err);
+    }
+  });
+
+controller.abort('Abort article count request');
+```
 
-### Contributing
+## Contributing
 
-Check out the [contributing guidelines](.github/CONTRIBUTING.md).
+Check out the [contributing guidelines](.github/CONTRIBUTING.md).