@qlik/api 0.0.4 → 0.0.5

package/docs/authentication.md

@@ -0,0 +1,220 @@
+# Authentication
+
+◁ [Back to overview](../README.md)
+
+When integrating a 3rd-party solution with Qlik Cloud Services users always have to authenticate with Qlik's backend services to interact with them. Authentication with `@qlik/api` works seamlessly and uses the same authentication mechanisms as those in the `@qlik/embed` libraries. The general idea is to provide a capable yet simple-to-use authentication api that works out of the box for most users. There are a few authentication options so that users can use what suits them best.
+
+## The Host Config
+
+Authentication is done by setting up a host config.
+
+The examples below uses an api-key and can be run in node.
+
+```ts
+import { auth, spaces } from "@qlik/api";
+
+const hostConfig = {
+  authType: "apikey",
+  host: "my-org.region.qlikcloud.com", // a qlikcloud tenant
+  apiKey: "<api-key>",
+};
+
+// sets a default host config for every api request
+auth.setDefaultConfig(hostConfig);
+
+const { data: mySpaces } = spaces.getSpaces();
+
+console.log(mySpaces);
+```
+
+A host config can also be passed in to every single api request which then will override any default host config previously set.
+
+```ts
+import spaces from "@qlik/api/spaces";
+
+const hostConfig = {
+    authType: "apikey"
+    host: "my-org.region.qlikcloud.com", // a qlikcloud tenant
+    apiKey: "<api-key>",
+  }
+
+const { data: mySpaces } = spaces.getSpaces({}, {
+  hostConfig,
+});
+
+console.log(mySpaces);
+```
+
+## The Auth Module
+
+An auth module in `@qlik/api` is an object with a few implemented methods. When connecting to Qlik Cloud Services (or Qlik Sense Enterprise for Windows) with `@qlik/api` or with `@qlik/embed` libraries an auth module is used for configuring the communication.
+
+```ts
+// This is an authentication module in @qlik/api
+
+const authModule = {
+  /** Gets the auth params needed for rest calls */
+  getRestCallAuthParams: () => Promise.resolve({
+    /** will be applied to rest requests headers */
+    headers: { ... },
+    /** will be added as query parameters to the request */
+    queryParams: { ... },
+    /** will set the credentials attribute on the rest request */
+    credentials: ("include"|"omit"|"same-origin"),
+  }),
+
+  /** Gets params for websocket connect requests */
+  getWebSocketAuthParams: () => Promise.resolve({
+    // will be added as query parameters to the websocket connect request
+     queryParams: { ... }
+  });
+
+  /** Will be called when there's an authentication error (e.g. user is not logged in) during an api call. */
+  handleAuthenticationError: () => {
+    // ... maybe start a login process
+    return Promise.resolve();
+  }
+
+  /** optional method to get auth params when web resources are fetched (such as images etc) */
+  getWebResourceAuthParams: () => Promise.resolve();
+
+  /**
+  * Optional runtime check for validating a host configs options, return false if
+  * something is missing or if there are invalid properties in the host config.
+  */
+  validateHostConfig: (hostConfig) => true;
+}
+```
+
+## The Default Auth Modules
+
+- [Oauth2](#oauth2)
+- [Cookie](#cookie)
+- [Windows Cookie](#windows-cookie)
+- [API Key](#api-key)
+
+### Oauth2
+
+Uses a `clientId` from an oauth client created by a Qlik tenant admin. And optionally a `clientSecret`. A user will go through a login flow in order to get hold of an access token that is valid for 6 hours. This token will be used as query parameters for api requests. If a `clientSecret` is used a refresh token will also be received. This can be used to refresh the access token and is valid for 30 days. The user can select where these tokens should be stored (only in a browser). Either in local storate or session storage (default).
+
+```ts
+type Oauth2AuthConfig = {
+  /** The URL to the cloud tenant or windows server. If scheme is excluded https is used. May include a virtual proxy prefix on windows. Any trailing slashes are stripped. */
+  host?: string;
+  /** Client ID of oauth client created by tenant admin */
+  clientId: string;
+  /** Client ID of oauth client created by tenant admin */
+  clientSecret?: string;
+  /** The location where the client should be redirected after obtaining the access token */
+  redirectUri?: string;
+  /** If set, store the access token in either local or session storage, otherwise not stored */
+  accessTokenStorage?: "session" | "local";
+  /** A string with comma separated values of oauth2 scopes https://oauth.net/2/scope defaults to "user_default" */
+  scope?: string;
+};
+```
+
+When using OAuth2 in a browser we recommend setting up a "redirect page" which is handy to use for pointing the redirection of an oauth login flow when fetching the access tokens. An oauth server will ask the client to redirect back to the hosting application after login is completed. In a single page application context this can potentially be any URL, so we recommend using this html template and use it for redirections.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <script
+      crossorigin="anonymous"
+      type="application/javascript"
+      data-host="<tenant-url>"
+      src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components/dist/oauth-callback.js"
+    ></script>
+  </head>
+</html>
+```
+
+### Cookie
+
+Uses a `webIntegrationId` created by a tenant admin. Will get the a CSRF token and append to api calls when necessary. To use this method in an integration scenario it is required that 3d party cookies are allowed.
+
+```ts
+type CookieAuthConfig = {
+  /** The URL to the cloud tenant or windows server. If scheme is excluded https is used. May include a virtual proxy prefix on windows. Any trailing slashes are stripped. */
+  host?: string;
+  /** Web Integration Id created by tenant admin */
+  webIntegrationId?: string;
+  /** If set to false the `credentials` property will be set to same-origin  */
+  crossSiteCookies?: boolean;
+};
+```
+
+### Windows Cookie
+
+Will do the necessary actions in order to communication with a Qlik Sense Enterprise for Windows server. This includes fetching an XrfKey from the Qlik Sense Server Repository Service. To use this method in an integration scenario it is required that 3d party cookies are allowed.
+
+```ts
+type WindowsCookieAuthConfig = {
+  /** The URL to the cloud tenant or windows server. If scheme is excluded https is used. May include a virtual proxy prefix on windows. Any trailing slashes are stripped. */
+  host?: string;
+  /** location of the login page, auth module will redirect to this page when an unauthenticated api call is made */
+  loginUri?: string;
+  /** If set to false the `credentials` property will be set to same-origin  */
+  crossSiteCookies?: boolean;
+};
+```
+
+### API Key
+
+Appends an `apiKey` to api requests that has been created by a user with a "developer" role on a Qlik Cloud tenant. Typically used when running integration code in a node environment.
+
+```ts
+type ApiKeyAuthConfig = {
+  /** api key created by a developer role on a tenant */
+  apiKey: string;
+};
+```
+
+## Custom auth module
+
+It is possible to register your own authentication module that then can be used when needed.
+
+```ts
+import { registerAuthModule, type AuthModule } from "@qlik/api/auth";
+
+// declare the type of configuration needed your custom auth module
+
+type CustomAuthConfig = {
+  configPropA: string;
+  optionalConfigPropB: boolean;
+};
+
+// Add your CustomAuthConfig to the known global auth types
+
+declare global {
+  interface QlikAuthModules {
+    custom: { config: CustomAuthConfig };
+  }
+}
+
+// implement your auth module as described above
+
+const authModule = {
+  ...
+};
+
+registerAuthModule("custom", authModule);
+```
+
+After this has been done the auth module can be used in a host config.
+
+```ts
+import { setDefaultHostConfig type HostConfig } from "@qlik/api/auth";
+
+const hostConfig: HostConfig = {
+  authType: "custom",
+  configPropA: "some-config-or-a-key",
+  optionalConfigPropB: false
+}
+
+setDefaultHostConfig(hostConfig);
+```
+
+◁ [Back to overview](../README.md)

package/docs/examples/create-app.md

@@ -0,0 +1,51 @@
+# Create an app and add some data
+
+◁ [Back to examples](../examples.md)
+
+This examples shows how to:
+
+- Create an app with the `apps` api
+- Connect to the app
+- Add a load script
+- Reload the data
+- Run a calculation with a qix engine expression.
+
+```ts
+import { apps, auth, qix } from "@qlik/api";
+
+const hostConfig = {
+  host: "your-tenant.region.qlikcloud.com",
+  authType: "apikey",
+  apiKey: "<api-key>",
+};
+
+auth.setDefaultHostConfig(hostConfig);
+
+async function main() {
+  try {
+    const { data } = await apps.createApp({ attributes: { name: "Anders App" } });
+    const appId = data.attributes?.id;
+    console.log("We have created:", appId);
+    // do stuff with the app
+    const session = qix.openAppSession({ appId });
+    const app = await session.getDoc();
+    console.log("Setting up some data");
+    await app.setScript("Load RecNo() as N autogenerate(100);");
+    await app.doReload();
+    console.log("Reloaded data done");
+    const evalResult = await app.evaluate("SUM([N])");
+    console.log(`Eval result: ${evalResult}`);
+    if (appId) {
+      await apps.deleteApp(appId);
+      console.log("We have now deleted:", appId);
+    }
+    session.close();
+  } catch (e) {
+    console.error(e);
+  }
+}
+
+await main();
+```
+
+◁ [Back to examples](../examples.md)

package/docs/examples/create-session-app.md

@@ -0,0 +1,88 @@
+# Create a session app
+
+◁ [Back to examples](../examples.md)
+
+This examples shows how to:
+
+- create a session app by opening a qix session to an app with a random id that starts with "SessionApp\_"
+- connect to the app and add some data to it
+- create an object and setup an event listener to when hypercube changes
+- reload the data to trigger the changed event.
+
+```ts
+import { auth, qix } from "@qlik/api";
+
+auth.setDefaultHostConfig({
+  host: "your-tenant.region.qlikcloud.com",
+  authType: "apikey",
+  apiKey: "<api-key>",
+
+async function main() {
+  try {
+    // Create a session app
+    const randomId = Math.random().toString(32).substring(3);
+    const appId = `SessionApp_${randomId}`;
+    // if appId starts with SessionApp_ and have a unique id it will become a session app.
+
+    // Open a websocket session with the session app id
+    const session = qix.openAppSession({ appId });
+    // Get the app object
+    const app = await session.getDoc();
+
+    // Set a script in the app
+    const script = `
+  TempTable:
+  Load
+  RecNo() as ID,
+  Rand() as Value
+  AutoGenerate 100
+  `;
+    await app.setScript(script);
+
+    // Create an object with a hypercube using fields in the data model
+    const properties = {
+      qInfo: {
+        qType: "my-straight-hypercube",
+      },
+      qHyperCubeDef: {
+        qDimensions: [
+          {
+            qDef: { qFieldDefs: ["ID"] },
+          },
+        ],
+        qMeasures: [
+          {
+            qDef: { qDef: "=Sum(Value)" },
+          },
+        ],
+        qInitialDataFetch: [
+          {
+            qHeight: 5,
+            qWidth: 2,
+          },
+        ],
+      },
+    };
+    const hypercube = await app.createObject(properties);
+    await hypercube.getLayout();
+
+    // Register an event listener for change events
+    hypercube.on("changed", () => {
+      console.log("changed ✅");
+    });
+
+    console.log("performing reload, expect a change to the hypercube object to happen");
+    // Do a reload of the app
+    await app.doReload();
+
+    // Close session
+    await session.close();
+  } catch (e) {
+    console.error(e);
+  }
+}
+
+main();
+```
+
+◁ [Back to examples](../examples.md)

package/docs/examples/fetch-spaces.md

@@ -0,0 +1,104 @@
+# Fetch Spaces in a Qlik Tenant
+
+◁ [Back to examples](../examples.md)
+
+## NodeJS using an API Key
+
+This examples shows how to fetch the space list from a tenant.
+
+```typescript
+import { auth, spaces } from "@qlik/api";
+
+const x = {
+  host: "your-tenant.region.qlikcloud.com",
+  authType: "apikey",
+  apiKey: "<api-key>",
+};
+
+auth.setDefaultHostConfig(x);
+
+async function main() {
+  const { data: mySpaces } = await spaces.getSpaces({});
+  console.log(mySpaces.data); // the data response (list of spaces)
+}
+
+await main();
+```
+
+Run the code with
+
+```shell
+node fetch-spaces.mjs
+```
+
+## NodeJS using Oauth2
+
+Create a file `fetch-spaces.mjs` and add the following:
+
+```typescript
+import { auth, spaces } from "@qlik/api";
+
+const hostConfig = {
+  host: "your-tenant.region.qlikcloud.com",
+  authType: "oauth2",
+  clientId: "<client-id>",
+  clientSecret "<client-secret>",
+};
+
+auth.setDefaultHostConfig(hostConfig);
+
+async function main() {
+  const { data: mySpaces } = await spaces.getSpaces({});
+  console.log(mySpaces.data); // the data response (list of spaces)
+}
+
+await main();
+```
+
+Run the code with
+
+```shell
+node fetch-spaces.mjs
+```
+
+## Browser using cookies
+
+When using a browser you can load the library files from a CDN provider. It is also possible to use npm and a bundler to get the code into your application. In the html below we are making an api call to fetch the spaces from a tenant and we add the names of the spaces as div elements in the dom.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Fetching spaces with @qlik/api</title>
+  </head>
+  <body>
+    <div id="space-container" class="container">
+      <div>Spaces:</div>
+      <!-- Spaces will be addeed here -->
+    </div>
+    <script type="module">
+      import { auth, spaces } from "https://cdn.jsdelivr.net/npm/@qlik/api/index.mjs";
+
+      auth.setDefaultHostConfig({
+        host: "your-tenant.region.qlikcloud.com",
+        authType: "cookie",
+        webIntegrationId: "<web-integration-id>",
+      });
+
+      const { data: mySpaces } = await spaces.getSpaces();
+      const spaceContainer = document.getElementById("space-container");
+      for (const space of mySpaces.data) {
+        const div = document.createElement("div");
+        div.innerText = space.name;
+        spaceContainer.appendChild(div);
+      }
+    </script>
+  </body>
+</html>
+```
+
+## Browser using Oauth2
+
+Use the same example as above but change the host config to use [Oauth2](authentication.md#oauth2)
+
+◁ [Back to examples](../examples.md)

package/docs/examples/show-sheet-list.md

@@ -0,0 +1,81 @@
+# Show Sheet List in a Qlik Sense Application
+
+◁ [Back to examples](../examples.md)
+
+For this example the id of a Qlik Sense Application that you have access to is needed. To get the id of an app, click on the "More actions" button on the app from the Qlik Cloud Hub and click on "details". There the app id is visible. Another option is to open the app and look at the URL. The app id is located as `/sense/<app-id>/` in the url.
+
+## NodeJS using an API Key
+
+```ts
+import { auth, qix } from "@qlik/api";
+
+const hostConfig = {
+  authType = "apikey",
+  host: "your-tenant.region.qlikcloud.com",
+  apiKey: "<api-key>",
+};
+
+// to use "Oauth2" auth module switch hostConfig to oauth2 and set clientId
+// and clientSecret instead of apiKey.
+
+const appId = "<app-id>";
+
+auth.setDefaultHostConfig(hostConfig);
+
+async function main() {
+  const session = qix.openAppSession({ appId });
+  const app = await session.getDoc();
+
+  const sheetList = await app.getSheetList();
+  console.log(sheetList);
+  session.close();
+}
+
+main();
+```
+
+In this example we're using the api method `app.getSheetList()` which comes from a "sense mixin" which is an extension of the official QIX API used for Qlik Sense Applications. In `@qlik/api` all "sense mixins" have been included to easily interact with Qlik Sense Applications in the same way in-house Qlik Developers do.
+
+## Browser using Cookies
+
+When using a browser you can load the library files from a CDN provider. It is also possible to use npm and a bundler to get the code into your application. In the html below we are making an api call to fetch the sheet list from a Qlik Sense App and we add the sheet titles as div elements in the dom.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Fetching sheet list from an app with @qlik/api</title>
+  </head>
+  <body>
+    <div id="sheet-container" class="container">
+      <div>Sheets:</div>
+      <!-- Sheets will be addeed here -->
+    </div>
+    <script type="module">
+      import { auth, qix } from "https://cdn.jsdelivr.net/npm/@qlik/api/index.mjs";
+      auth.setDefaultHostConfig({
+        host: "your-tenant.region.qlikcloud.com",
+        authType: "cookie",
+        webIntegrationId: "<web-ingetration-id>",
+      });
+      const appId = "<api-key>";
+      const session = qix.openAppSession({ appId });
+      const app = await session.getDoc();
+      const sheetList = await app.getSheetList();
+      const sheetContainer = document.getElementById("sheet-container");
+      for (const sheet of sheetList) {
+        const div = document.createElement("div");
+        div.innerText = sheet.qMeta.title;
+        sheetContainer.appendChild(div);
+      }
+      session.close(); // closing the app
+    </script>
+  </body>
+</html>
+```
+
+## Browser using Oauth2
+
+Use the same example as above but change the host config to use [Oauth2](authentication.md#oauth2)
+
+◁ [Back to examples](../examples.md)

package/docs/examples.md

@@ -1,4 +1,12 @@
 # Examples
 
-**TODO:**
-Add more examples here
+◁ [Back to overview](../README.md)
+
+Heres's some examples on common scenarios on how to interact with Qlik API's using `@qlik/api`
+
+The code in the examples use ES Module Syntax. It is possible to use CommonJS format for the NodeJS examples, but we recommend using ES Modules since it's where the whole Javascript EcoSystem is moving towards. The code you write can also easily be ported between browsers and NodeJS when using ES Modules.
+
+- [Fetching spaces](./examples/fetch-spaces.md)
+- [Show Sheet List in an app](./examples/show-sheet-list.md)
+- [Create an app](./examples/create-app.md)
+- [Create session app](./examples/create-session-app.md)

package/docs/features.md

@@ -0,0 +1,129 @@
+# Features
+
+◁ [Back to overview](../README.md)
+
+- [Typed API calls](#typed-api-calls)
+- [Caching](#caching)
+- [Paging](#paging)
+- [Request/response interceptors](#interceptors)
+
+## Typed API Calls
+
+Each API comes with full typescript support which will greatly help the developer experience. Use the types to understand how the API works by going into the type definition. In most editors (e.g. vscode) you can CMD+click (mac) or CTRL+click (windows) on an api-call to see the type definition of parameters, return structures etc etc.
+
+## Caching
+
+Request responses are cached in the browser so requests can be fired away without being concerned about causing unnecessary traffic. Ongoing requests are also re-used if two equal requests go out at the same time. A request can be forced by adding an option to the call `{ noCache: true }`. Clearing cache can be automatically handled as shown [below](#automatic-cache-clearing-and-auto-csrf).
+
+```ts
+import { getItems } from "@qlik/api/items";
+
+try {
+  await getItems();
+  await getItems();
+  await getItems();
+  await getItems();
+  // the 4 requests above will result in only one request over network
+
+  // empty query object as 1st parameter, 2nd parameter is the ApiCallOptions
+  await getItems({}, { noCache: true });
+  // this request above will result in a network call because of the noCache option
+} catch (e) {
+  // something went wrong
+}
+```
+
+### Automatic cache clearing and auto csrf
+
+Requests that need parameters are all using documented types inherited from the spec files. Requests that require a valid csrf-token automatically fetch it (once if needed) and add it to the outgoing requests headers. Requests that change resources (for example POST/PUT) automatically clear the cache.
+
+```ts
+import { getSpaces, createSpace } from "@qlik/api/spaces";
+
+try {
+  let { data: spaceList } = await getSpaces({});
+  // spaceList has 2 items
+  const { data: space } = await createSpace({ name: "My space", description: "description", type: "shared" });
+  // the call above automatically adds a csrf-token header. If no csrf-token has been fetched yet it will first fetch it.
+  // space now has the Space type and your editor will show the types e.g:
+  // space.id;
+  // space.createdAt;
+
+  { data: spaceList } = await getSpaces(); // cached response has automatically been cleared because of createSpace call above
+  // spaceList has 3 items
+} catch (e) {
+  // something went wrong
+}
+```
+
+### Manual cache clearing
+
+The cache for an api can be cleared with the `clearCache` method. This clears all cached responses for that specific api. It is recommended to use the [automatic cache clearing](#automatic-cache-clearing-and-auto-csrf).
+
+```ts
+import { getSpaces, clearCache: clearSpaceCache } from "@qlik/api/spaces";
+
+try {
+  await getSpaces();
+  clearSpaceCache(); // clears all cached responses for the space api.
+  await getSpaces();
+  // the 2 requests above will both go out on the network
+} catch (e) {
+  // something went wrong
+}
+```
+
+**note** `clearCache` only affects one api, all other api caches are unaffected.
+
+## Paging
+
+Many "list" APIs return links to the next and previous page in the list GET response body. If the API follows the conventions and declares this in the OpenAPI spec next and prev functions will be available in the API response type. Note that the next and prev functions are only defined when there actually is a next and prev page.
+
+## Interceptors
+
+Consumer of `@qlik/api` can inject an interceptor in every api method. There are two interception points, before request and after response. The request interceptor can also be an async function.
+
+**NOTE:** to add headers to the request, use a regular object instead of `new Headers()`. It causes a loss of all the original headers. See the example below.
+
+```ts
+import { getItems, interceptors } from "@qlik/api/items";
+
+// intercept requests
+interceptors.getItems.request.use((url, request) => {
+  const headers = {
+    ...request.headers,
+    "x-qlik-custom-header": "value",
+  };
+
+  // modify fetch request
+  request.headers = headers;
+
+  return request;
+});
+
+// intercept responses
+interceptors.getItems.response.use((response) => {
+  response.data.YOU_ARE_INTERCEPTED = true;
+  return response;
+});
+
+try {
+  const { status, data: items } = await getItems();
+
+  if (items.YOU_ARE_INTERCEPTED) {
+    // ok!
+  }
+}
+```
+
+when adding an interceptor you get an interceptor ID that can be used to eject the interceptor later.
+
+```ts
+const interceptorId = interceptors.getItems.response.use(...);
+// now interceptor will execute on response
+
+interceptors.getItems.response.eject(interceptorId);
+// now interceptor will NOT execute on response
+```
+
+◁ [Back to overview](../README.md)