@mittwald/api-models 0.1.0-alpha.1 → 4.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mittwald CM Service GmbH & Co. KG and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -20,18 +20,14 @@ yarn add @mittwald/api-models
 
 ## Setup
 
-You will need an initialized API client in order to operate with the models
-provided by this package. Provide it to the `setupApiBehaviors` method before
-any model operation is executed.
+You will need to initialize an API client in order to operate with the models
+provided by this package. Use the `api` global instance for initialization with
+some methods.
 
 ```typescript
-import { setupApiBehaviors } from "@mittwald/api-models";
-import { MittwaldAPIV2Client } from "@mittwald/api-client";
+import { api } from "@mittwald/api-models";
 
-// See the documentation of @mittwald/api-client for alternative methods of
-// client initialization: https://www.npmjs.com/package/@mittwald/api-client
-const client = MittwaldAPIClient.newUnauthenticated();
-setupApiBehaviors(client);
+api.setupWithApiToken(process.env.MW_API_TOKEN);
 ```
 
 ## Examples
@@ -291,10 +287,111 @@ class ProjectDetailed {
 ```typescript
 class ProjectDetailed {
   public static async find(id: string): Promise<ProjectDetailed | undefined> {
-    const data = await Project.behaviors.find(id);
+    const data = await config.project.behaviors.find(id);
     if (data !== undefined) {
       return new Project(data.id, data);
     }
   }
 }
 ```
+
+#### How-to implement behaviors
+
+Place a `behaviors` folder inside the model that should look like this:
+
+```
+Project/
+├─ behaviors/
+│  ├─ index.ts
+│  ├─ types.ts (behavior interface)
+│  ├─ api.ts   (behavior implementation)
+│  ├─ inmem.ts (behavior implementation)
+
+```
+
+##### Define `types.ts` first
+
+It is a good starting point to first implement the interface for the behavior.
+The interface usually just defines methods used in the behavior. Like
+
+```ts
+export interface ProjectBehaviors {
+  find: (id: string) => Promise<ProjectData | undefined>;
+  updateDescription: (projectId: string, description: string) => Promise<void>;
+}
+```
+
+Then register the behavior in the global behavior configuration
+`packages/models/src/config/config.ts`.
+
+##### Use the behaviors in the model
+
+If the behavior interface is defined, you can start implementing the model. You
+can also first implement the concrete API behavior, to "proof" the behavior is
+"working" with the real API.
+
+```ts
+import { config } from "../../config/config.js";
+
+class ProjectDetailed {
+  public static async find(id: string): Promise<ProjectDetailed | undefined> {
+    const data = await config.project.behaviors.find(id);
+    if (data !== undefined) {
+      return new Project(data.id, data);
+    }
+  }
+}
+```
+
+##### Implement the API behavior
+
+The API behavior depends on an API client. You can implement the behavior as an
+object factory, or a simple class implementing the interface. When using the
+object factory, you do not have to redeclare the method parameter types.
+
+Do the implementation specific stuff, thus preparing and executing the request,
+and finally processing the response.
+
+```ts
+import { ProjectBehaviors } from "./types.js";
+import { assertStatus, MittwaldAPIV2Client } from "@mittwald/api-client";
+
+export const apiProjectBehaviors = (
+  client: MittwaldAPIV2Client,
+): ProjectBehaviors => ({
+  find: async (id) => {
+    const response = await client.project.getProject({
+      projectId: id,
+    });
+
+    if (response.status === 200) {
+      return response.data;
+    }
+    assertStatus(response, 403);
+  },
+});
+```
+
+### Prepare for React
+
+All asynchronous methods should provide a `use`-method property. This method
+uses
+[@mittwald/react-use-promise](https://www.npmjs.com/package/@mittwald/react-use-promise)
+under the hood to "resolve" the promise in the "React way".
+
+To provide this feature to your _async_ model methods, wrap the actual method
+with the `provideReact` enhancer.
+
+```ts
+class ProjectDetailed {
+  public static find = provideReact(
+    async (id: string): Promise<ProjectDetailed | undefined> => {
+      const data = await config.behaviors.project.find(id);
+
+      if (data !== undefined) {
+        return new ProjectDetailed(data);
+      }
+    },
+  );
+}
+```

package/dist/esm/app/AppInstallation/AppInstallation.js

@@ -0,0 +1,43 @@
+import { config } from "../../config/config.js";
+import { classes } from "polytype";
+import { DataModel } from "../../base/DataModel.js";
+import assertObjectFound from "../../base/assertObjectFound.js";
+import { ReferenceModel } from "../../base/ReferenceModel.js";
+import { provideReact } from "../../lib/provideReact.js";
+export class AppInstallation extends ReferenceModel {
+    static find = provideReact(async (id) => {
+        const data = await config.behaviors.appInstallation.find(id);
+        if (data !== undefined) {
+            return new AppInstallationDetailed(data);
+        }
+    });
+    static get = provideReact(async (id) => {
+        const appInstallation = await this.find(id);
+        assertObjectFound(appInstallation, this, id);
+        return appInstallation;
+    });
+    static ofId(id) {
+        return new AppInstallation(id);
+    }
+    static list = provideReact(async (projectId, query = {}) => {
+        const data = await config.behaviors.appInstallation.list(projectId, query);
+        return data.map((d) => new AppInstallationListItem(d));
+    });
+    getDetailed = provideReact(() => AppInstallation.get(this.id));
+}
+// Common class for future extension
+class AppInstallationCommon extends classes((DataModel), AppInstallation) {
+    constructor(data) {
+        super([data], [data.id]);
+    }
+}
+export class AppInstallationDetailed extends classes(AppInstallationCommon, (DataModel)) {
+    constructor(data) {
+        super([data], [data]);
+    }
+}
+export class AppInstallationListItem extends classes(AppInstallationCommon, (DataModel)) {
+    constructor(data) {
+        super([data], [data]);
+    }
+}

package/dist/esm/app/AppInstallation/behaviors/api.js

@@ -0,0 +1,21 @@
+import { assertStatus } from "@mittwald/api-client";
+import { assertOneOfStatus } from "@mittwald/api-client";
+export const apiAppInstallationBehaviors = (client) => ({
+    find: async (id) => {
+        const response = await client.app.getAppinstallation({
+            appInstallationId: id,
+        });
+        if (response.status === 200) {
+            return response.data;
+        }
+        assertOneOfStatus(response, [404]);
+    },
+    list: async (projectId, query) => {
+        const response = await client.app.listAppinstallations({
+            queryParameters: query,
+            projectId,
+        });
+        assertStatus(response, 200);
+        return response.data;
+    },
+});

package/dist/esm/app/AppInstallation/behaviors/index.js

@@ -0,0 +1,2 @@
+export * from "./api.js";
+export * from "./types.js";

package/dist/esm/app/AppInstallation/behaviors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/app/AppInstallation/index.js

@@ -0,0 +1,2 @@
+export * from "./AppInstallation.js";
+export * from "./types.js";

package/dist/esm/app/AppInstallation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/app/index.js

@@ -0,0 +1 @@
+export * from "./AppInstallation/index.js";

package/dist/esm/base/DataModel.js

@@ -0,0 +1,7 @@
+import deepFreeze from "../lib/deepFreeze.js";
+export class DataModel {
+    data;
+    constructor(data) {
+        this.data = deepFreeze(data);
+    }
+}

package/dist/esm/base/ReferenceModel.js

@@ -0,0 +1,9 @@
+export class ReferenceModel {
+    id;
+    constructor(id) {
+        this.id = id;
+    }
+    describe() {
+        return `${this.constructor.name}@${this.id}`;
+    }
+}

package/dist/esm/base/assertObjectFound.js

@@ -0,0 +1,9 @@
+import ObjectNotFoundError from "../errors/ObjectNotFoundError.js";
+export default function assertObjectFound(obj, theClass, refIdOrObject) {
+    if (obj === undefined) {
+        const refName = typeof refIdOrObject === "string"
+            ? refIdOrObject
+            : refIdOrObject.toString();
+        throw new ObjectNotFoundError(theClass.name, refName);
+    }
+}

package/dist/esm/base/index.js

@@ -0,0 +1 @@
+export * from "./types.js";

package/dist/esm/base/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/config/behaviors/api.js

@@ -0,0 +1,40 @@
+import { MittwaldAPIV2Client } from "@mittwald/api-client";
+import { config } from "../config.js";
+import { apiProjectBehaviors } from "../../project/Project/behaviors/index.js";
+import { apiServerBehaviors } from "../../server/Server/behaviors/index.js";
+import { apiCustomerBehaviors } from "../../customer/Customer/behaviors/index.js";
+import { apiIngressBehaviors } from "../../domain/Ingress/behaviors/index.js";
+import { apiAppInstallationBehaviors } from "../../app/AppInstallation/behaviors/index.js";
+class ApiSetupState {
+    _client;
+    setupWithClient(client) {
+        if (this._client !== undefined) {
+            throw new Error("API already setup. If you want to operate on the API client use api.client.");
+        }
+        this._client = client;
+        config.behaviors.project = apiProjectBehaviors(client);
+        config.behaviors.server = apiServerBehaviors(client);
+        config.behaviors.customer = apiCustomerBehaviors(client);
+        config.behaviors.ingress = apiIngressBehaviors(client);
+        config.behaviors.appInstallation = apiAppInstallationBehaviors(client);
+    }
+    setupWithApiToken(apiToken) {
+        return this.setupWithClient(MittwaldAPIV2Client.newWithToken(apiToken));
+    }
+    setupUnauthenticated() {
+        return this.setupWithClient(MittwaldAPIV2Client.newUnauthenticated());
+    }
+    get client() {
+        if (!this._client) {
+            throw new Error("Could not get client. Behavior not initialized.");
+        }
+        return this._client;
+    }
+    get defaults() {
+        return this.client.axios.defaults;
+    }
+    get interceptors() {
+        return this.client.axios.interceptors;
+    }
+}
+export const api = new ApiSetupState();

package/dist/esm/config/behaviors/index.js

@@ -0,0 +1 @@
+export * from "./api.js";

package/dist/esm/config/config.js

@@ -0,0 +1,9 @@
+export const config = {
+    behaviors: {
+        project: undefined,
+        server: undefined,
+        customer: undefined,
+        ingress: undefined,
+        appInstallation: undefined,
+    },
+};

package/dist/esm/config/index.js

@@ -0,0 +1 @@
+export * from "./behaviors/index.js";

package/dist/esm/customer/Customer/Customer.js

@@ -0,0 +1,43 @@
+import { config } from "../../config/config.js";
+import { classes } from "polytype";
+import { DataModel } from "../../base/DataModel.js";
+import assertObjectFound from "../../base/assertObjectFound.js";
+import { ReferenceModel } from "../../base/ReferenceModel.js";
+import { provideReact } from "../../lib/provideReact.js";
+export class Customer extends ReferenceModel {
+    static ofId(id) {
+        return new Customer(id);
+    }
+    static find = provideReact(async (id) => {
+        const data = await config.behaviors.customer.find(id);
+        if (data !== undefined) {
+            return new CustomerDetailed(data);
+        }
+    });
+    static list = provideReact(async (query = {}) => {
+        const data = await config.behaviors.customer.list(query);
+        return Object.freeze(data.map((d) => new CustomerListItem(d)));
+    });
+    static get = provideReact(async (id) => {
+        const customer = await this.find(id);
+        assertObjectFound(customer, this, id);
+        return customer;
+    });
+    getDetailed = provideReact(() => Customer.get(this.id));
+}
+// Common class for future extension
+class CustomerCommon extends classes((DataModel), Customer) {
+    constructor(data) {
+        super([data], [data.customerId]);
+    }
+}
+export class CustomerDetailed extends classes(CustomerCommon, (DataModel)) {
+    constructor(data) {
+        super([data], [data]);
+    }
+}
+export class CustomerListItem extends classes(CustomerCommon, (DataModel)) {
+    constructor(data) {
+        super([data], [data]);
+    }
+}

package/dist/esm/customer/Customer/behaviors/api.js

@@ -0,0 +1,20 @@
+import { assertStatus } from "@mittwald/api-client";
+import { assertOneOfStatus } from "@mittwald/api-client";
+export const apiCustomerBehaviors = (client) => ({
+    find: async (id) => {
+        const response = await client.customer.getCustomer({
+            customerId: id,
+        });
+        if (response.status === 200) {
+            return response.data;
+        }
+        assertOneOfStatus(response, [404]);
+    },
+    list: async (query) => {
+        const response = await client.customer.listCustomers({
+            queryParameters: query,
+        });
+        assertStatus(response, 200);
+        return response.data;
+    },
+});

package/dist/esm/customer/Customer/behaviors/index.js

@@ -0,0 +1,2 @@
+export * from "./api.js";
+export * from "./types.js";

package/dist/esm/customer/Customer/behaviors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/customer/Customer/index.js

@@ -0,0 +1,2 @@
+export * from "./Customer.js";
+export * from "./types.js";

package/dist/esm/customer/Customer/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/customer/index.js

@@ -0,0 +1 @@
+export * from "./Customer/index.js";

package/dist/esm/domain/Ingress/Ingress.js

@@ -0,0 +1,56 @@
+import { config } from "../../config/config.js";
+import { classes } from "polytype";
+import { DataModel } from "../../base/DataModel.js";
+import assertObjectFound from "../../base/assertObjectFound.js";
+import { ReferenceModel } from "../../base/ReferenceModel.js";
+import { provideReact } from "../../lib/provideReact.js";
+import { IngressPath } from "../IngressPath/IngressPath.js";
+export class Ingress extends ReferenceModel {
+    static ofId(id) {
+        return new Ingress(id);
+    }
+    static ofHostname(hostname) {
+        return Ingress.ofId(hostname);
+    }
+    static list = provideReact(async (query = {}) => {
+        const data = await config.behaviors.ingress.list(query);
+        return data.map((d) => new IngressListItem(d));
+    });
+    static find = provideReact(async (id) => {
+        const data = await config.behaviors.ingress.find(id);
+        if (data !== undefined) {
+            return new IngressDetailed(data);
+        }
+    });
+    static get = provideReact(async (id) => {
+        const ingress = await this.find(id);
+        assertObjectFound(ingress, this, id);
+        return ingress;
+    });
+    getDetailed = provideReact(() => Ingress.get(this.id));
+}
+export class IngressCommon extends classes((DataModel), Ingress) {
+    baseUrl;
+    paths;
+    defaultPath;
+    constructor(data) {
+        super([data], [data.id]);
+        this.baseUrl = `https://${data.hostname}`;
+        this.paths = Object.freeze(data.paths.map((p) => new IngressPath(this, p)));
+        const defaultPath = this.paths.find((p) => p.path === "/");
+        if (defaultPath === undefined) {
+            throw new Error(`Ingress ${this.describe()} has no default path.`);
+        }
+        this.defaultPath = defaultPath;
+    }
+}
+export class IngressDetailed extends classes(IngressCommon, (DataModel)) {
+    constructor(data) {
+        super([data], [data]);
+    }
+}
+export class IngressListItem extends classes(IngressCommon, (DataModel)) {
+    constructor(data) {
+        super([data], [data]);
+    }
+}

package/dist/esm/domain/Ingress/behaviors/api.js

@@ -0,0 +1,23 @@
+import { assertStatus } from "@mittwald/api-client";
+import { assertOneOfStatus } from "@mittwald/api-client";
+export const apiIngressBehaviors = (client) => ({
+    find: async (id) => {
+        const response = await client.domain.ingressGetIngress({
+            ingressId: id,
+        });
+        if (response.status === 200) {
+            return response.data;
+        }
+        assertOneOfStatus(response, [404]);
+    },
+    list: async (query = {}) => {
+        const { projectId } = query;
+        const response = await client.domain.ingressListIngresses({
+            queryParameters: {
+                projectId,
+            },
+        });
+        assertStatus(response, 200);
+        return response.data;
+    },
+});

package/dist/esm/domain/Ingress/behaviors/index.js

@@ -0,0 +1,2 @@
+export * from "./api.js";
+export * from "./types.js";

package/dist/esm/domain/Ingress/behaviors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/domain/Ingress/index.js

@@ -0,0 +1,2 @@
+export * from "./Ingress.js";
+export * from "./types.js";

package/dist/esm/domain/Ingress/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/domain/IngressPath/IngressPath.js

@@ -0,0 +1,15 @@
+import { DataModel } from "../../base/DataModel.js";
+import { ingressTargetFactory, } from "../IngressTarget/IngressTarget.js";
+export class IngressPath extends DataModel {
+    ingress;
+    path;
+    url;
+    target;
+    constructor(ingress, data) {
+        super(data);
+        this.ingress = ingress;
+        this.path = data.path;
+        this.url = new URL(data.path, ingress.baseUrl);
+        this.target = ingressTargetFactory(this, data.target);
+    }
+}

package/dist/esm/domain/IngressPath/IngressPath.test.js

@@ -0,0 +1,16 @@
+import { IngressPath } from "./IngressPath.js";
+import { IngressDetailed } from "../Ingress/index.js";
+const ingressData = {
+    id: "abc",
+    paths: [],
+};
+const corruptIngressTargetData = {};
+const ingressPathData = {
+    path: "/",
+    target: corruptIngressTargetData,
+};
+test("Creating IngressPath with corrupt IngressTarget throws error", () => {
+    expect(() => {
+        new IngressPath(new IngressDetailed(ingressData), ingressPathData);
+    }).toThrowError("Ingress IngressDetailed@abc has no default path.");
+});

package/dist/esm/domain/IngressPath/index.js

@@ -0,0 +1,2 @@
+export * from "./IngressPath.js";
+export * from "./types.js";

package/dist/esm/domain/IngressPath/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/domain/IngressTarget/IngressTarget.js

@@ -0,0 +1,51 @@
+import { DataModel } from "../../base/DataModel.js";
+import { AppInstallation } from "../../app/AppInstallation/index.js";
+class IngressTargetBase extends DataModel {
+    path;
+    constructor(path, data) {
+        super(data);
+        this.path = path;
+    }
+}
+export class IngressRedirectTarget extends IngressTargetBase {
+    type = "redirect";
+    url;
+    constructor(path, data) {
+        super(path, data);
+        this.url = new URL(data.url);
+    }
+}
+export class IngressDirectoryTarget extends IngressTargetBase {
+    type = "directory";
+    directory;
+    constructor(path, data) {
+        super(path, data);
+        this.directory = data.directory;
+    }
+}
+export class IngressAppInstallationTarget extends IngressTargetBase {
+    type = "appInstallation";
+    appInstallation;
+    constructor(path, data) {
+        super(path, data);
+        this.appInstallation = AppInstallation.ofId(data.installationId);
+    }
+}
+export class IngressUndefinedTarget extends IngressTargetBase {
+    type = "undefined";
+}
+export const ingressTargetFactory = (path, data) => {
+    if ("directory" in data) {
+        return new IngressDirectoryTarget(path, data);
+    }
+    if ("url" in data) {
+        return new IngressRedirectTarget(path, data);
+    }
+    if ("installationId" in data) {
+        return new IngressAppInstallationTarget(path, data);
+    }
+    if ("useDefaultPage" in data) {
+        return new IngressUndefinedTarget(path, data);
+    }
+    throw new Error("Ingress target type is not supported.");
+};

package/dist/esm/domain/IngressTarget/IngressTarget.test-types.js

@@ -0,0 +1,13 @@
+const target = {};
+// @ts-expect-error use type-guard first
+void target.url;
+if (target.type === "redirect") {
+    void target.url;
+}
+if (target.type === "directory") {
+    void target.directory;
+}
+if (target.type === "appInstallation") {
+    void target.appInstallation.id;
+}
+export {};

package/dist/esm/domain/IngressTarget/index.js

@@ -0,0 +1,2 @@
+export * from "./IngressTarget.js";
+export * from "./types.js";

package/dist/esm/domain/IngressTarget/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/domain/index.js

@@ -0,0 +1 @@
+export * from "./Ingress/index.js";

package/dist/esm/errors/ObjectNotFoundError.js

@@ -0,0 +1,7 @@
+export default class ObjectNotFoundError extends Error {
+    constructor(type, refName) {
+        super(`${type}@${refName} not found`);
+        this.name = "ObjectNotFoundError";
+        Object.setPrototypeOf(this, ObjectNotFoundError.prototype);
+    }
+}

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+export { MittwaldAPIV2Client } from "@mittwald/api-client";
+export * from "./config/index.js";
+export * from "./project/index.js";
+export * from "./server/index.js";
+export * from "./domain/index.js";
+export * from "./customer/index.js";
+export * from "./base/index.js";

package/dist/esm/lib/deepFreeze.js

@@ -0,0 +1,3 @@
+import deepFreezeLib from "another-deep-freeze";
+const deepFreeze = deepFreezeLib.default;
+export default deepFreeze;