@appsemble/utils 0.21.2 → 0.21.3

package/README.md

@@ -1,9 +1,9 @@
-# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.21.2/config/assets/logo.svg) Appsemble Utilities
+# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.21.3/config/assets/logo.svg) Appsemble Utilities
 
 > Internal utility functions used across multiple Appsemble projects.
 
 [![npm](https://img.shields.io/npm/v/@appsemble/utils)](https://www.npmjs.com/package/@appsemble/utils)
-[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.21.2/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.21.2)
+[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.21.3/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.21.3)
 [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io)
 
 ## Table of Contents
@@ -26,5 +26,5 @@ not guaranteed.
 
 ## License
 
-[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.21.2/LICENSE.md) ©
+[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.21.3/LICENSE.md) ©
 [Appsemble](https://appsemble.com)

package/api/paths/appQuotas.d.ts

@@ -0,0 +1,2 @@
+import { type OpenAPIV3 } from 'openapi-types';
+export declare const paths: OpenAPIV3.PathsObject;

package/api/paths/appQuotas.js

@@ -0,0 +1,38 @@
+export const paths = {
+    '/api/apps/{appId}/quotas/email': {
+        get: {
+            tags: ['app'],
+            operationId: 'getAppEmailQuota',
+            parameters: [{ $ref: '#/components/parameters/appId' }],
+            security: [{ studio: [] }, {}],
+            responses: {
+                200: {
+                    description: 'Email quota for an app',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    used: {
+                                        type: 'number',
+                                        description: 'Number of emails sent today',
+                                    },
+                                    limit: {
+                                        type: 'number',
+                                        description: 'Maximum number of emails that can be sent today',
+                                    },
+                                    reset: {
+                                        type: 'string',
+                                        format: 'date-time',
+                                        description: 'Date and time when the quota resets',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=appQuotas.js.map

package/api/paths/index.js

@@ -1,6 +1,7 @@
 import { paths as action } from './action.js';
 import { paths as translations } from './appMessages.js';
 import { paths as appOAuth2Secrets } from './appOAuth2Secrets.js';
+import { paths as appQuotas } from './appQuotas.js';
 import { paths as apps } from './apps.js';
 import { paths as appSamlSecrets } from './appSamlSecrets.js';
 import { paths as scimEndpoints } from './appScimEndpoints.js';
@@ -30,6 +31,7 @@ export const paths = {
     ...scimEndpoints,
     ...appsembleMessages,
     ...appSSLSecrets,
+    ...appQuotas,
     ...assets,
     ...blocks,
     ...emails,

package/index.d.ts

@@ -23,5 +23,6 @@ export * from './string.js';
 export * from './theme.js';
 export * from './langmap.js';
 export * from './i18n.js';
+export * from './serverActions.js';
 export * from './validation.js';
 export * from './convertToCsv.js';

package/index.js

@@ -23,6 +23,7 @@ export * from './string.js';
 export * from './theme.js';
 export * from './langmap.js';
 export * from './i18n.js';
+export * from './serverActions.js';
 export * from './validation.js';
 export * from './convertToCsv.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsemble/utils",
-  "version": "0.21.2",
+  "version": "0.21.3",
   "description": "Utility functions used in Appsemble internally",
   "keywords": [
     "app",
@@ -21,6 +21,12 @@
   "author": "Appsemble <info@appsemble.com> (https://appsemble.com)",
   "sideEffects": false,
   "type": "module",
+  "exports": {
+    ".": [
+      "./index.js",
+      "./index.ts"
+    ]
+  },
   "files": [
     "**/*.d.ts",
     "**/*.js",
@@ -31,7 +37,7 @@
     "test": "vitest"
   },
   "dependencies": {
-    "@appsemble/types": "0.21.2",
+    "@appsemble/types": "0.21.3",
     "axios": "^1.0.0",
     "cron-parser": "^4.0.0",
     "date-fns": "^2.0.0",

package/reference-schemas/remappers/conditionals.js

@@ -3,7 +3,28 @@ export const conditionalRemappers = {
         type: 'object',
         description: `Check if condition results in a truthy value.
 
-Returns value of then if condition is truthy, otherwise it returns the value of else.
+Returns value of \`then\` if condition is truthy, otherwise it returns the value of \`else\`.
+
+For example:
+
+\`\`\`yaml
+if:
+  condition: { equals: [{ prop: inputValue }, 4] }
+  then:
+    static: You guessed right!
+  else:
+    static: You guessed wrong!
+\`\`\`
+
+If the \`inputValue\` is \`4\`, it goes to the \`then\` remapper and returns:
+\`\`\`
+You guessed right!
+\`\`\`
+
+If the \`inputValue\` is something other than \`4\`, it goes to the \`else\` remapper and returns:
+\`\`\`
+You guessed wrong!
+\`\`\`
 `,
         additionalProperties: false,
         required: ['condition', 'then', 'else'],
@@ -30,13 +51,35 @@ Returns value of then if condition is truthy, otherwise it returns the value of
         description: `Compare all computed remapper values against each other.
 
 Returns \`true\` if all entries are equal, otherwise \`false\`.
+
+In the following example, if the \`inputValue\` and \`expectedValue\` are of the same value, the
+condition will return \`true\` and the \`then\` remapper will fire.
+
+\`\`\`yaml
+condition:
+  equals:
+    - prop: inputValue
+    - prop: expectedValue
+\`\`\`
 `,
     },
     gt: {
         type: 'array',
-        description: `Compare the first computed remapper value with the second computed remapper value.
+        description: `**(gt = Greater than)**
+
+Compare the first computed remapper value with the second computed remapper value.
+
+Returns \`true\` if the first entry is greater than the second entry.
+
+For example, if \`stock\` is more than 5 here, it returns \`true\`.
 
-Returns \`true\` if the first entry is greater than the second entry.`,
+\`\`\`yaml
+condition:
+  gt:
+    - prop: stock
+    - 5
+\`\`\`
+`,
         minItems: 2,
         maxItems: 2,
         items: {
@@ -45,9 +88,21 @@ Returns \`true\` if the first entry is greater than the second entry.`,
     },
     lt: {
         type: 'array',
-        description: `Compare the first computed remapper value with the second computed remapper value.
+        description: `**(lt = Lesser than)
+
+Compare the first computed remapper value with the second computed remapper value.
+
+Returns \`true\` if the first entry is lesser than the second entry.
 
-Returns \`true\` if the first entry is lesser than the second entry.`,
+For example, if \`stock\` is less than 5 here, it returns \`true\`.
+
+\`\`\`yaml
+condition:
+  lt:
+    - prop: stock
+    - 5
+\`\`\`
+`,
         minItems: 2,
         maxItems: 2,
         items: {
@@ -64,6 +119,15 @@ Returns \`true\` if the first entry is lesser than the second entry.`,
 Returns \`false\` if all entries are equal to the first entry, otherwise \`true\`.
 
 If only one remapper or none is passed, the remapper value gets computed and then inverted.
+
+If \`number\` in the following example is something other than 4, the condition returns \`true\`.
+
+\`\`\`yaml
+condition:
+  not:
+    - prop: number
+    - 4
+\`\`\`
 `,
     },
     match: {
@@ -71,6 +135,21 @@ If only one remapper or none is passed, the remapper value gets computed and the
         description: `Check if any case results in a truthy value.
 
 Returns the value of the first case where the condition equals true, otherwise returns null.
+
+In the following example, let's say the \`Gem\` is a "Ruby". The match remapper then returns
+\`value: 75\`.
+
+\`\`\`yaml
+match:
+  - case: { equals: [{ prop: Gem }, Diamond] }
+    value: 100
+  - case: { equals: [{ prop: Gem }, Ruby] }
+    value: 75
+  - case: { equals: [{ prop: Gem }, Gold] }
+    value: 50
+  - case: { equals: [{ prop: Gem }, Sapphire] }
+    value: 25
+\`\`\`
 `,
         items: {
             type: 'object',

package/reference-schemas/remappers/data.js

@@ -4,6 +4,40 @@ export const dataRemappers = {
         description: `Get the current array.map’s index or length.
 
 Returns nothing when not in the context of \`array.map’s\`.
+
+For example:
+
+Input:
+\`\`\`json
+["a", "b", "c"]
+\`\`\`
+
+This remapper definition maps through the input array and creates an object with the length of the
+array and the current index of the loop:
+\`\`\`yaml
+array.map:
+  object.from:
+    length: { array: length }
+    index: { array: index }
+\`\`\`
+
+Result:
+\`\`\`json
+[
+  {
+    "index": 0,
+    "length": 3
+  },
+  {
+    "index": 1,
+    "length": 3
+  },
+  {
+    "index": 2,
+    "length": 3
+  }
+]
+\`\`\`
 `,
     },
     app: {
@@ -260,7 +294,18 @@ Result:
     `,
     },
     static: {
-        description: 'Use a static value.',
+        description: `Create a static value
+
+\`\`\`yaml
+static: Hello!
+\`\`\`
+
+Returns the following string:
+
+\`\`\`
+Hello!
+\`\`\`
+`,
     },
     translate: {
         type: 'string',

package/reference-schemas/remappers/dates.js

@@ -1,15 +1,84 @@
 export const dateRemappers = {
     'date.add': {
         type: 'string',
-        description: 'Add the specified value to a given date.',
+        description: `Adds a specified date value to the provided date.
+
+The value to add should be specified according to the
+[parse-duration](https://www.npmjs.com/package/parse-duration) API. If you want to add a day to a
+date for example, the syntax would be \`date.add: 1d\`.
+
+Full list of supported unit types:
+- nanoseconds (ns)
+- microseconds (μs)
+- milliseconds (ms)
+- seconds (s, sec)
+- minutes (m, min)
+- hours (h, hr)
+- days (d)
+- weeks (w, wk)
+- months
+- years (y, yr)
+
+For example:
+
+Date now:
+\`\`\`json
+2023-06-30T14:50:19.601Z
+\`\`\`
+
+Remapper definition:
+\`\`\`yaml
+[{ date.now: null }, { date.add: 1w } , { date.format: null }]
+\`\`\`
+
+Result:
+\`\`\`json
+2023-07-07T14:50:19.601Z
+\`\`\`
+
+`,
     },
     'date.format': {
         enum: [null],
-        description: 'Format a date according to rfc3339.',
+        description: `Format a date according to the RFC3339 format.
+
+Here is an example of a RFC3339 complicit date:
+\`2002-10-02T15:00:00Z\`
+
+In an app definition, it’s best to use this when you want to display a date in a specific format.
+For example, if your app has a form with a Datepicker field the incoming data will be formatted
+as a simple date format. If you want to format it tot he RFC3339 format, you can use this remapper.
+
+When you submit a form with a DateField, the internal output looks like this:
+
+\`\`\`js
+2023-07-03
+\`\`\`
+
+You can then format the date so that it uses the RFC3339 format.
+
+\`\`\`yaml
+date.format: null
+\`\`\`
+
+Result:
+\`\`\`js
+"2023-07-03T09:09:50.000Z"
+\`\`\`
+`,
     },
     'date.now': {
         enum: [null],
-        description: 'Returns the current date.',
+        description: `Returns the current date as a JavaScript Date object.
+\`\`\`yaml
+date.now: null
+\`\`\`
+
+Result:
+\`\`\`js
+"Mon Jul 03 2023 11:47:18 GMT+0200 (Midden-Europese zomertijd)"
+\`\`\`
+`,
     },
     'date.parse': {
         type: 'string',

package/reference-schemas/remappers/randoms.js

@@ -1,7 +1,27 @@
 export const randomRemappers = {
     'random.choice': {
         enum: [null],
-        description: 'Pick and return a random entry from an array. If the input is not an array, the input is returned as-is.',
+        description: `Pick and return a random entry from an array. If the input is not an array, the input is returned as-is.
+For example:
+
+If you input the following array:
+\`\`\`json
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+\`\`\`
+
+\`\`\`yaml
+random.choice: null
+\`\`\`
+
+The result could return any one of these numbers.
+
+You can also combine different data types in this array and have it work in the same way. If mixed in
+strings, the result could be either one of the provided numbers or one of the provided strings.
+
+\`\`\`json
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, "Peter", "Patrick", "Michael", "Harry"]
+\`\`\`
+`,
     },
     'random.integer': {
         type: 'array',
@@ -10,7 +30,16 @@ export const randomRemappers = {
         items: {
             type: 'integer',
         },
-        description: 'Pick and return a random integer between the provided lowest and highest values.',
+        description: `Pick and return a random integer between the provided lowest and highest values.
+For example:
+\`\`\`yaml
+random.integer:
+  - 0
+  - 1000
+\`\`\`
+
+Returns a random integer between 0 and 1000.
+`,
     },
     'random.float': {
         type: 'array',
@@ -19,7 +48,16 @@ export const randomRemappers = {
         items: {
             type: 'number',
         },
-        description: 'Pick and return a random number between the provided lowest and highest values.',
+        description: `Pick and return a random float value between the provided lowest and highest values.
+For example:
+\`\`\`yaml
+random.float:
+  - 0
+  - 1
+\`\`\`
+
+Returns a random float value between 0 and 1.
+`,
     },
     'random.string': {
         type: 'object',
@@ -29,7 +67,16 @@ export const randomRemappers = {
             choice: { type: 'string', minLength: 1 },
             length: { type: 'integer', minimum: 1 },
         },
-        description: 'Pick and return a random string from a given length using characters from a given input string.',
+        description: `Pick and return a random string from a given length using characters from a given input string defined in \`choice\`.
+For example:
+\`\`\`yaml
+random.string:
+  choice: abcdefghijklmnopqrstuvwxyz0123456789
+  length: 6
+\`\`\`
+
+Returns a randomized string that is 6 characters long and consists of any characters in the \`choice\` field, like: \`g8ajss9\`.
+`,
     },
 };
 //# sourceMappingURL=randoms.js.map

package/reference-schemas/remappers/unsorted.js

@@ -1,7 +1,47 @@
 export const unsortedRemappers = {
     ics: {
         type: 'object',
-        description: 'Create a calendar event',
+        description: `Create a calendar event. This event can be downloaded as an \`.ics\` file and
+uploaded to your agenda using the [download](../reference/action#download) action.
+
+For example, the following input:
+\`\`\`yaml
+ics:
+coordinates
+  object.from:
+    latitude: 38.897700545442646
+    longitude: -77.03655660152435
+description: "Sprint planning meeting"
+duration: 1d
+end: 2023-07-19
+location: The Oval Office.
+start: 2023-07-18
+title: Important Meeting
+url: https://google.nl
+\`\`\`
+
+Creates the following ICS-formatted object:
+\`\`\`
+BEGIN:VCALENDAR
+VERSION:2.0
+CALSCALE:GREGORIAN
+PRODID:http://remappers.appsemble.localhost:9999
+METHOD:PUBLISH
+X-PUBLISHED-TTL:PT1H
+BEGIN:VEVENT
+UID:b8TsbczhfpIxPM-3lNHQz
+SUMMARY:Important Meeting
+DTSTAMP:20230703T102029Z
+DTSTART:20230717T220000Z
+DTEND:20230718T220000Z
+DESCRIPTION:Sprint planning meeting
+URL:https://google.nl
+GEO:38.897700545442646;-77.03655123710632
+LOCATION:The Oval Office.
+END:VEVENT
+END:VCALENDAR
+\`\`\`
+`,
         additionalProperties: false,
         required: ['start', 'title'],
         properties: {
@@ -43,7 +83,51 @@ export const unsortedRemappers = {
         },
     },
     'null.strip': {
-        description: 'Strip all null, undefined, and empty array values from an object.',
+        description: `Strip all null, undefined, and empty array values from an object or array.
+For example, with the following input value:
+\`\`\`json
+[0, 4, null, null, "Peter", 0.4234, null]
+\`\`\`
+\`\`\`yaml
+null.strip: null
+\`\`\`
+
+The null values will be removed, leaving a dense array:
+\`\`\`json
+[0, 4, "Peter", 0.4234]
+\`\`\`
+
+Instead of giving it \`null\` as option, you can also provide a \`depth\` property to specify how
+deep to recurse into the object or array to remove null values.
+
+For example, with the following input:
+\`\`\`json
+{
+  0: [0, null, "Peter"],
+  1: {
+    "array1": [4, null, 0.4234, null]
+  }
+}
+\`\`\`
+
+You can specify to which degree of depth you want the null values to be removed.
+With this remapper definition:
+\`\`\`yaml
+null.strip:
+  depth: 2
+\`\`\`
+
+It will only check two objects in for any null values. That means only the first array within the
+object will be checked. The result looks like this:
+\`\`\`json
+{
+  0: [0, "Peter"],
+  1: {
+    "array1": [4, null, 0.4234, null]
+  }
+}
+\`\`\`
+`,
         anyOf: [
             { enum: [null] },
             {
@@ -63,9 +147,110 @@ export const unsortedRemappers = {
     },
     log: {
         enum: ['info', 'warn', 'error'],
-        description: `Logs its input data (returns it) and its context.
+        description: `Logs in the browser's console and returns the incoming data and the remapper function's context.
+
+The context contains relevant info about the app, like the URL and locale, but also contains the
+remapper’s history.
+
+The options represent the level of logging that will show in the console.
 
-The value to set is the log level.`,
+- \`input\`: The input data going into this remapper,
+- \`context\`:
+  - \`root\`: The input data going into this remapper,
+  - \`appId\`: ID of the application,
+  - \`url\`: Absolute URL of the page where the remapper was fired,
+  - \`appUrl\`: Base URL of the application,
+  - \`pageData\`: Current page data of a FlowPage (See [page remapper](./data#page)),
+  - \`userInfo\`: User's information if they are logged in (See [user remapper](./data#user)),
+  - \`context\`:
+    - \`history\`: Complete list of this remapper’s history (See [history remapper](./history))
+  - \`history\`: Complete list of this remapper’s history (See [history remapper](./history))
+  - \`locale\`: The user’s locale,
+  - \`stepRef\`: In a loop page, gives the properties from the loop’s current data index (See [step remapper](./data#step))
+
+For example:
+
+\`\`\`json
+{
+  "input": {
+    "name": "Peter",
+    "age": 49,
+    "birthday": "07-08-2023"
+  },
+  "context": {
+    "root": {
+      "name": "Peter",
+      "age": 49,
+      "birthday": "07-08-2023"
+    },
+    "appId": 49,
+    "url": "http://remappers.appsemble.localhost:9999/en/other",
+    "appUrl": "http://remappers.appsemble.localhost:9999",
+    "pageData": {
+      "triedAppsemble": false
+    },
+    "userInfo": {
+      "email": "example@hotmail.com",
+      "email_verified": true,
+      "name": "Example User 1",
+      "picture": "https://www.gravatar.com/avatar/f46b82357ce29bcd1099915946cda468?s=128&d=mp",
+      "sub": "0000-0000-0000-0000",
+      "locale": "en",
+      "zoneinfo": "Europe/Amsterdam"
+    },
+    "context": {
+      "history": [
+        [
+          0,
+          4,
+          null,
+          null,
+          "Peter",
+          0.4234,
+          null
+        ],
+        {
+          "name": "Peter",
+          "age": 49
+        },
+        {
+          "name": "Peter",
+          "age": 49,
+          "birthday": "07-08-2023"
+        }
+      ]
+    },
+    "history": [
+      [
+        0,
+        4,
+        null,
+        null,
+        "Peter",
+        0.4234,
+        null
+      ],
+      {
+        "name": "Peter",
+        "age": 49
+      },
+      {
+        "name": "Peter",
+        "age": 49,
+        "birthday": "07-08-2023"
+      }
+    ],
+    "locale": "en",
+    "stepRef": {
+      "current": {
+        "answerType": "multiple choice",
+        "question": "How much do you enjoy working here?"
+      }
+    }
+  }
+}
+\`\`\`
+`,
     },
 };
 //# sourceMappingURL=unsorted.js.map