@twin.org/rights-management-service 0.0.1-next.10

package/dist/esm/index.mjs

@@ -0,0 +1,448 @@
+import { HttpParameterHelper } from '@twin.org/api-models';
+import { Guards, ComponentFactory, Coerce, GeneralError, Is } from '@twin.org/core';
+import { OdrlContexts } from '@twin.org/standards-w3c-odrl';
+import { HttpStatusCode } from '@twin.org/web';
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The source used when communicating about these routes.
+ */
+const ROUTES_SOURCE = "rightsManagementRoutes";
+/**
+ * The tag to associate with the routes.
+ */
+const tags = [
+    {
+        name: "Policy Administration Point",
+        description: "Endpoints for managing ODRL policies in the Policy Administration Point"
+    }
+];
+/**
+ * The REST routes for the Rights Management.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+function generateRestRoutesRightsManagement(baseRouteName, componentName) {
+    const createRoute = {
+        operationId: "papCreate",
+        summary: "Create a policy",
+        tag: tags[0].name,
+        method: "POST",
+        path: `${baseRouteName}/pap/`,
+        handler: async (httpRequestContext, request) => papCreate(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapCreateRequest",
+            examples: [
+                {
+                    id: "papCreateExample",
+                    request: {
+                        body: {
+                            "@context": OdrlContexts.ContextRoot,
+                            "@type": "Set",
+                            permission: [
+                                {
+                                    target: "http://example.com/asset/1",
+                                    action: "use"
+                                }
+                            ]
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "ICreatedResponse",
+                examples: [
+                    {
+                        id: "papCreateResponseExample",
+                        response: {
+                            statusCode: 201,
+                            headers: {
+                                location: "urn:rights-management:abc123def456"
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const updateRoute = {
+        operationId: "papUpdate",
+        summary: "Update a policy",
+        tag: tags[0].name,
+        method: "PUT",
+        path: `${baseRouteName}/pap/:id`,
+        handler: async (httpRequestContext, request) => papUpdate(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapUpdateRequest",
+            examples: [
+                {
+                    id: "papUpdateExample",
+                    request: {
+                        pathParams: {
+                            id: "urn:rights-management:abc123def456"
+                        },
+                        body: {
+                            "@context": OdrlContexts.ContextRoot,
+                            "@type": "Set",
+                            uid: "urn:rights-management:abc123def456",
+                            permission: [
+                                {
+                                    target: "http://example.com/asset/2",
+                                    action: "read"
+                                }
+                            ]
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ]
+    };
+    const retrieveRoute = {
+        operationId: "papRetrieve",
+        summary: "Retrieve a policy",
+        tag: tags[0].name,
+        method: "GET",
+        path: `${baseRouteName}/pap/:id`,
+        handler: async (httpRequestContext, request) => papRetrieve(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapRetrieveRequest",
+            examples: [
+                {
+                    id: "papRetrieveExample",
+                    request: {
+                        pathParams: {
+                            id: "urn:rights-management:abc123def456"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IPapRetrieveResponse",
+                examples: [
+                    {
+                        id: "papRetrieveResponseExample",
+                        response: {
+                            body: {
+                                "@context": OdrlContexts.ContextRoot,
+                                "@type": "Set",
+                                uid: "urn:rights-management:abc123def456",
+                                permission: [
+                                    {
+                                        target: "http://example.com/asset/1",
+                                        action: "use"
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const removeRoute = {
+        operationId: "papRemove",
+        summary: "Remove a policy",
+        tag: tags[0].name,
+        method: "DELETE",
+        path: `${baseRouteName}/pap/:id`,
+        handler: async (httpRequestContext, request) => papRemove(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapRemoveRequest",
+            examples: [
+                {
+                    id: "papRemoveExample",
+                    request: {
+                        pathParams: {
+                            id: "urn:rights-management:abc123def456"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ]
+    };
+    const queryRoute = {
+        operationId: "papQuery",
+        summary: "Query policies",
+        tag: tags[0].name,
+        method: "GET",
+        path: `${baseRouteName}/pap/query`,
+        handler: async (httpRequestContext, request) => papQuery(httpRequestContext, componentName, request),
+        requestType: {
+            type: "IPapQueryRequest",
+            examples: [
+                {
+                    id: "papQueryExample",
+                    request: {
+                        query: {
+                            cursor: "optional-pagination-cursor"
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "IPapQueryResponse",
+                examples: [
+                    {
+                        id: "papQueryResponseExample",
+                        response: {
+                            body: {
+                                cursor: "next-page-cursor",
+                                policies: [
+                                    {
+                                        "@context": OdrlContexts.ContextRoot,
+                                        "@type": "Set",
+                                        uid: "urn:rights-management:abc123def456",
+                                        permission: [
+                                            {
+                                                target: "http://example.com/asset/1",
+                                                action: "use"
+                                            }
+                                        ]
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    return [createRoute, updateRoute, retrieveRoute, removeRoute, queryRoute];
+}
+/**
+ * PAP: Create a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papCreate(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.body", request.body);
+    Guards.stringValue(ROUTES_SOURCE, "httpRequestContext.nodeIdentity", httpRequestContext.nodeIdentity);
+    const component = ComponentFactory.get(componentName);
+    const policy = request.body;
+    const uid = await component.papCreate(policy);
+    return {
+        statusCode: HttpStatusCode.created,
+        headers: {
+            location: uid
+        }
+    };
+}
+/**
+ * PAP: Update a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papUpdate(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
+    Guards.object(ROUTES_SOURCE, "request.body", request.body);
+    Guards.stringValue(ROUTES_SOURCE, "httpRequestContext.nodeIdentity", httpRequestContext.nodeIdentity);
+    const component = ComponentFactory.get(componentName);
+    await component.papUpdate(request.body);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * PAP: Retrieve a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papRetrieve(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
+    Guards.stringValue(ROUTES_SOURCE, "httpRequestContext.nodeIdentity", httpRequestContext.nodeIdentity);
+    const component = ComponentFactory.get(componentName);
+    const policy = await component.papRetrieve(request.pathParams.id);
+    return {
+        body: policy
+    };
+}
+/**
+ * PAP: Remove a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papRemove(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.pathParams", request.pathParams);
+    Guards.stringValue(ROUTES_SOURCE, "request.pathParams.id", request.pathParams.id);
+    const component = ComponentFactory.get(componentName);
+    await component.papRemove(request.pathParams.id);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * PAP: Query policies.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+async function papQuery(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    const component = ComponentFactory.get(componentName);
+    const result = await component.papQuery(HttpParameterHelper.objectFromString(request.query?.conditions), request.query?.cursor, Coerce.integer(request.query?.pageSize));
+    return {
+        body: {
+            cursor: result.cursor,
+            policies: result.policies
+        }
+    };
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Service for performing Rights Management operations.
+ * This is a unified service that provides access to all Rights Management components.
+ */
+class RightsManagementService {
+    /**
+     * The namespace supported by the Rights Management service.
+     */
+    static NAMESPACE = "rights-management";
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "RightsManagementService";
+    /**
+     * The PAP component implementation.
+     * @internal
+     */
+    _papComponent;
+    /**
+     * Create a new instance of RightsManagementService.
+     * @param options The options for the service.
+     */
+    constructor(options) {
+        this._papComponent = ComponentFactory.get(options?.papComponentType ?? "pap");
+    }
+    /**
+     * PAP: Create a new policy with auto-generated UID.
+     * @param policy The policy to create (uid will be auto-generated).
+     * @returns The UID of the created policy.
+     */
+    async papCreate(policy) {
+        try {
+            Guards.object(this.CLASS_NAME, "policy", policy);
+            const result = await this._papComponent.create(policy);
+            return result;
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papCreateFailed", undefined, error);
+        }
+    }
+    /**
+     * PAP: Update an existing policy.
+     * @param policy The policy to update (must include uid).
+     * @returns Nothing.
+     */
+    async papUpdate(policy) {
+        try {
+            Guards.object(this.CLASS_NAME, "policy", policy);
+            await this._papComponent.update(policy);
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papUpdateFailed", undefined, error);
+        }
+    }
+    /**
+     * PAP: Retrieve a policy.
+     * @param policyId The id of the policy to retrieve.
+     * @returns The policy.
+     */
+    async papRetrieve(policyId) {
+        try {
+            Guards.stringValue(this.CLASS_NAME, "policyId", policyId);
+            const policy = await this._papComponent.retrieve(policyId);
+            return policy;
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papRetrieveFailed", undefined, error);
+        }
+    }
+    /**
+     * PAP: Remove a policy.
+     * @param policyId The id of the policy to remove.
+     * @returns Nothing.
+     */
+    async papRemove(policyId) {
+        try {
+            Guards.stringValue(this.CLASS_NAME, "policyId", policyId);
+            await this._papComponent.remove(policyId);
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papRemoveFailed", undefined, error);
+        }
+    }
+    /**
+     * PAP: Query the policies using the specified conditions.
+     * @param conditions The conditions to use for the query.
+     * @param cursor The cursor to use for pagination.
+     * @param pageSize The number of results to return per page.
+     * @returns Cursor for next page of results and the policies matching the query.
+     */
+    async papQuery(conditions, cursor, pageSize) {
+        try {
+            if (!Is.empty(conditions)) {
+                Guards.object(this.CLASS_NAME, "conditions", conditions);
+            }
+            if (!Is.empty(cursor)) {
+                Guards.stringValue(this.CLASS_NAME, "cursor", cursor);
+            }
+            if (!Is.empty(pageSize)) {
+                Guards.integer(this.CLASS_NAME, "pageSize", pageSize);
+            }
+            const result = await this._papComponent.query(conditions, cursor, pageSize);
+            return result;
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "papQueryFailed", undefined, error);
+        }
+    }
+}
+
+/**
+ * Entry points for the REST API.
+ */
+const restEntryPoints = [
+    {
+        name: "rights-management",
+        defaultBaseRoute: "rights-management",
+        tags,
+        generateRoutes: generateRestRoutesRightsManagement
+    }
+];
+
+export { RightsManagementService, generateRestRoutesRightsManagement, papCreate, papQuery, papRemove, papRetrieve, papUpdate, restEntryPoints, tags };

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./models/IRightsManagementServiceConstructorOptions";
+export * from "./rightsManagementRoutes";
+export * from "./rightsManagementService";
+export * from "./restEntryPoints";

package/dist/types/models/IRightsManagementServiceConstructorOptions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The constructor options for the RightsManagementService.
+ */
+export interface IRightsManagementServiceConstructorOptions {
+    /**
+     * The type of the Policy Administration Point (PAP) component.
+     * @default pap
+     */
+    papComponentType?: string;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,5 @@
+import type { IRestRouteEntryPoint } from "@twin.org/api-models";
+/**
+ * Entry points for the REST API.
+ */
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/dist/types/rightsManagementRoutes.d.ts

@@ -0,0 +1,53 @@
+import { type ICreatedResponse, type IHttpRequestContext, type INoContentResponse, type IRestRoute, type ITag } from "@twin.org/api-models";
+import type { IPapCreateRequest, IPapQueryRequest, IPapQueryResponse, IPapRemoveRequest, IPapRetrieveRequest, IPapRetrieveResponse, IPapUpdateRequest } from "@twin.org/rights-management-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tags: ITag[];
+/**
+ * The REST routes for the Rights Management.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesRightsManagement(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * PAP: Create a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papCreate(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapCreateRequest): Promise<ICreatedResponse>;
+/**
+ * PAP: Update a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papUpdate(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapUpdateRequest): Promise<INoContentResponse>;
+/**
+ * PAP: Retrieve a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papRetrieve(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapRetrieveRequest): Promise<IPapRetrieveResponse>;
+/**
+ * PAP: Remove a policy.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papRemove(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapRemoveRequest): Promise<INoContentResponse>;
+/**
+ * PAP: Query policies.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function papQuery(httpRequestContext: IHttpRequestContext, componentName: string, request: IPapQueryRequest): Promise<IPapQueryResponse>;

package/dist/types/rightsManagementService.d.ts

@@ -0,0 +1,58 @@
+import type { EntityCondition } from "@twin.org/entity";
+import type { IRightsManagementComponent } from "@twin.org/rights-management-models";
+import type { IOdrlPolicy } from "@twin.org/standards-w3c-odrl";
+import type { IRightsManagementServiceConstructorOptions } from "./models/IRightsManagementServiceConstructorOptions";
+/**
+ * Service for performing Rights Management operations.
+ * This is a unified service that provides access to all Rights Management components.
+ */
+export declare class RightsManagementService implements IRightsManagementComponent {
+    /**
+     * The namespace supported by the Rights Management service.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of RightsManagementService.
+     * @param options The options for the service.
+     */
+    constructor(options?: IRightsManagementServiceConstructorOptions);
+    /**
+     * PAP: Create a new policy with auto-generated UID.
+     * @param policy The policy to create (uid will be auto-generated).
+     * @returns The UID of the created policy.
+     */
+    papCreate(policy: Omit<IOdrlPolicy, "uid">): Promise<string>;
+    /**
+     * PAP: Update an existing policy.
+     * @param policy The policy to update (must include uid).
+     * @returns Nothing.
+     */
+    papUpdate(policy: IOdrlPolicy): Promise<void>;
+    /**
+     * PAP: Retrieve a policy.
+     * @param policyId The id of the policy to retrieve.
+     * @returns The policy.
+     */
+    papRetrieve(policyId: string): Promise<IOdrlPolicy>;
+    /**
+     * PAP: Remove a policy.
+     * @param policyId The id of the policy to remove.
+     * @returns Nothing.
+     */
+    papRemove(policyId: string): Promise<void>;
+    /**
+     * PAP: Query the policies using the specified conditions.
+     * @param conditions The conditions to use for the query.
+     * @param cursor The cursor to use for pagination.
+     * @param pageSize The number of results to return per page.
+     * @returns Cursor for next page of results and the policies matching the query.
+     */
+    papQuery(conditions?: EntityCondition<IOdrlPolicy>, cursor?: string, pageSize?: number): Promise<{
+        cursor?: string;
+        policies: IOdrlPolicy[];
+    }>;
+}