@twin.org/nft-service 0.0.1-next.10

package/dist/esm/index.mjs

@@ -0,0 +1,455 @@
+import { Guards, ComponentFactory, GeneralError, Urn } from '@twin.org/core';
+import { HttpStatusCode, HeaderTypes } from '@twin.org/web';
+import { NftConnectorFactory } from '@twin.org/nft-models';
+
+/**
+ * The source used when communicating about these routes.
+ */
+const ROUTES_SOURCE = "nftRoutes";
+/**
+ * The tag to associate with the routes.
+ */
+const tagsNft = [
+    {
+        name: "NFT",
+        description: "Endpoints which are modelled to access an NFT contract."
+    }
+];
+/**
+ * The REST routes for NFT.
+ * @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 generateRestRoutesNft(baseRouteName, componentName) {
+    const mintRoute = {
+        operationId: "nftMint",
+        summary: "Mint an NFT",
+        tag: tagsNft[0].name,
+        method: "POST",
+        path: `${baseRouteName}/`,
+        handler: async (httpRequestContext, request) => nftMint(httpRequestContext, componentName, request),
+        requestType: {
+            type: "INftMintRequest",
+            examples: [
+                {
+                    id: "nftMintExample",
+                    request: {
+                        body: {
+                            issuer: "tst1prctjk5ck0dutnsunnje6u90jk5htx03qznjjmkd6843pzltlgz87srjzzv",
+                            tag: "MY-NFT",
+                            immutableMetadata: {
+                                docName: "bill-of-lading",
+                                mimeType: "application/pdf",
+                                fingerprint: "0xf0b95a98b3dbc5ce1c9ce59d70af95a97599f100a7296ecdd1eb108bebfa047f"
+                            },
+                            metadata: {
+                                data: "tst1prctjk5ck0dutnsunnje6u90jk5htx03qznjjmkd6843pzltlgz87srjzzv"
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "ICreatedResponse",
+                examples: [
+                    {
+                        id: "nftMintResponseExample",
+                        response: {
+                            statusCode: HttpStatusCode.created,
+                            headers: {
+                                [HeaderTypes.Location]: "nft:iota:aW90YS1uZnQ6dHN0OjB4NzYyYjljNDllYTg2OWUwZWJkYTliYmZhNzY5Mzk0NDdhNDI4ZGNmMTc4YzVkMTVhYjQ0N2UyZDRmYmJiNGViMg=="
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const resolveRoute = {
+        operationId: "nftResolve",
+        summary: "Resolve an NFT",
+        tag: tagsNft[0].name,
+        method: "GET",
+        path: `${baseRouteName}/:id`,
+        handler: async (httpRequestContext, request) => nftResolve(httpRequestContext, componentName, request),
+        requestType: {
+            type: "INftResolveRequest",
+            examples: [
+                {
+                    id: "nftResolveExample",
+                    request: {
+                        pathParams: {
+                            id: "nft:iota:aW90YS1uZnQ6dHN0OjB4NzYyYjljNDllYTg2OWUwZWJkYTliYmZhNzY5Mzk0NDdhNDI4ZGNmMTc4YzVkMTVhYjQ0N2UyZDRmYmJiNGViMg=="
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INftResolveResponse",
+                examples: [
+                    {
+                        id: "nftResolveResponseExample",
+                        response: {
+                            body: {
+                                issuer: "tst1prctjk5ck0dutnsunnje6u90jk5htx03qznjjmkd6843pzltlgz87srjzzv",
+                                owner: "tst1prctjk5ck0dutnsunnje6u90jk5htx03qznjjmkd6843pzltlgz87srjzzv",
+                                tag: "MY-NFT",
+                                immutableMetadata: {
+                                    docName: "bill-of-lading",
+                                    mimeType: "application/pdf",
+                                    fingerprint: "0xf0b95a98b3dbc5ce1c9ce59d70af95a97599f100a7296ecdd1eb108bebfa047f"
+                                },
+                                metadata: {
+                                    data: "AAAAA"
+                                }
+                            }
+                        }
+                    }
+                ]
+            }
+        ]
+    };
+    const burnRoute = {
+        operationId: "nftBurn",
+        summary: "Burn an NFT",
+        tag: tagsNft[0].name,
+        method: "DELETE",
+        path: `${baseRouteName}/:id`,
+        handler: async (httpRequestContext, request) => nftBurn(httpRequestContext, componentName, request),
+        requestType: {
+            type: "INftBurnRequest",
+            examples: [
+                {
+                    id: "nftBurnExample",
+                    request: {
+                        pathParams: {
+                            id: "nft:iota:aW90YS1uZnQ6dHN0OjB4NzYyYjljNDllYTg2OWUwZWJkYTliYmZhNzY5Mzk0NDdhNDI4ZGNmMTc4YzVkMTVhYjQ0N2UyZDRmYmJiNGViMg=="
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ]
+    };
+    const transferRoute = {
+        operationId: "nftTransfer",
+        summary: "Transfer an NFT",
+        tag: tagsNft[0].name,
+        method: "POST",
+        path: `${baseRouteName}/:id/transfer`,
+        handler: async (httpRequestContext, request) => nftTransfer(httpRequestContext, componentName, request),
+        requestType: {
+            type: "INftTransferRequest",
+            examples: [
+                {
+                    id: "nftTransferExample",
+                    request: {
+                        pathParams: {
+                            id: "nft:iota:aW90YS1uZnQ6dHN0OjB4NzYyYjljNDllYTg2OWUwZWJkYTliYmZhNzY5Mzk0NDdhNDI4ZGNmMTc4YzVkMTVhYjQ0N2UyZDRmYmJiNGViMg=="
+                        },
+                        body: {
+                            recipient: "tst1prctjk5ck0dutnsunnje6u90jk5htx03qznjjmkd6843pzltlgz87srjzzv",
+                            metadata: {
+                                data: "AAAAA"
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ]
+    };
+    const updateRoute = {
+        operationId: "nftUpdate",
+        summary: "Update an NFT",
+        tag: tagsNft[0].name,
+        method: "PUT",
+        path: `${baseRouteName}/:id`,
+        handler: async (httpRequestContext, request) => nftUpdate(httpRequestContext, componentName, request),
+        requestType: {
+            type: "INftUpdateRequest",
+            examples: [
+                {
+                    id: "nftUpdateExample",
+                    request: {
+                        pathParams: {
+                            id: "nft:iota:aW90YS1uZnQ6dHN0OjB4NzYyYjljNDllYTg2OWUwZWJkYTliYmZhNzY5Mzk0NDdhNDI4ZGNmMTc4YzVkMTVhYjQ0N2UyZDRmYmJiNGViMg=="
+                        },
+                        body: {
+                            metadata: {
+                                data: "AAAAA"
+                            }
+                        }
+                    }
+                }
+            ]
+        },
+        responseType: [
+            {
+                type: "INoContentResponse"
+            }
+        ]
+    };
+    return [mintRoute, resolveRoute, burnRoute, transferRoute, updateRoute];
+}
+/**
+ * Mint an NFT.
+ * @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 nftMint(httpRequestContext, componentName, request) {
+    Guards.object(ROUTES_SOURCE, "request", request);
+    Guards.object(ROUTES_SOURCE, "request.body", request.body);
+    Guards.stringValue(ROUTES_SOURCE, "request.body.issuer", request.body.issuer);
+    Guards.stringValue(ROUTES_SOURCE, "request.body.tag", request.body.tag);
+    const component = ComponentFactory.get(componentName);
+    const id = await component.mint(request.body.issuer, request.body.tag, request.body.immutableMetadata, request.body.metadata, request.body.namespace, httpRequestContext.userIdentity);
+    return {
+        statusCode: HttpStatusCode.created,
+        headers: {
+            [HeaderTypes.Location]: id
+        }
+    };
+}
+/**
+ * Resolve an NFT.
+ * @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 nftResolve(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);
+    const result = await component.resolve(request.pathParams.id, httpRequestContext.userIdentity);
+    return {
+        body: result
+    };
+}
+/**
+ * Burn an NFT.
+ * @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 nftBurn(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.burn(request.pathParams.id, httpRequestContext.userIdentity);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * Transfer an NFT.
+ * @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 nftTransfer(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, "request.body.recipient", request.body.recipient);
+    const component = ComponentFactory.get(componentName);
+    await component.transfer(request.pathParams.id, request.body.recipient, request.body.metadata, httpRequestContext.userIdentity);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+/**
+ * Update an NFT.
+ * @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 nftUpdate(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.object(ROUTES_SOURCE, "request.body.metadata", request.body.metadata);
+    const component = ComponentFactory.get(componentName);
+    await component.update(request.pathParams.id, request.body.metadata, httpRequestContext.userIdentity);
+    return {
+        statusCode: HttpStatusCode.noContent
+    };
+}
+
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Service for performing NFT operations to a connector.
+ */
+class NftService {
+    /**
+     * The namespace supported by the nft service.
+     */
+    static NAMESPACE = "nft";
+    /**
+     * Runtime name for the class.
+     */
+    CLASS_NAME = "NftService";
+    /**
+     * The default namespace for the connector to use.
+     * @internal
+     */
+    _defaultNamespace;
+    /**
+     * Create a new instance of NftService.
+     * @param options The options for the service.
+     */
+    constructor(options) {
+        const names = NftConnectorFactory.names();
+        if (names.length === 0) {
+            throw new GeneralError(this.CLASS_NAME, "noConnectors");
+        }
+        this._defaultNamespace = options?.config?.defaultNamespace ?? names[0];
+    }
+    /**
+     * Mint an NFT.
+     * @param issuer The issuer for the NFT, will also be the initial owner.
+     * @param tag The tag for the NFT.
+     * @param immutableMetadata The immutable metadata for the NFT.
+     * @param metadata The metadata for the NFT.
+     * @param namespace The namespace of the connector to use for the NFT, defaults to service configured namespace.
+     * @param identity The identity to perform the nft operation on.
+     * @returns The id of the created NFT in urn format.
+     */
+    async mint(issuer, tag, immutableMetadata, metadata, namespace, identity) {
+        Guards.stringValue(this.CLASS_NAME, "issuer", issuer);
+        Guards.stringValue(this.CLASS_NAME, "tag", tag);
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        try {
+            const connectorNamespace = namespace ?? this._defaultNamespace;
+            const nftConnector = NftConnectorFactory.get(connectorNamespace);
+            const nftUrn = await nftConnector.mint(identity, issuer, tag, immutableMetadata, metadata);
+            return nftUrn;
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "mintFailed", undefined, error);
+        }
+    }
+    /**
+     * Resolve an NFT.
+     * @param id The id of the NFT to resolve.
+     * @param identity The identity to perform the nft operation on.
+     * @returns The data for the NFT.
+     */
+    async resolve(id, identity) {
+        Urn.guard(this.CLASS_NAME, "id", id);
+        try {
+            const nftConnector = this.getConnector(id);
+            return nftConnector.resolve(id);
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "resolveFailed", undefined, error);
+        }
+    }
+    /**
+     * Burn an NFT.
+     * @param id The id of the NFT to burn in urn format.
+     * @param identity The identity to perform the nft operation on.
+     * @returns Nothing.
+     */
+    async burn(id, identity) {
+        Urn.guard(this.CLASS_NAME, "id", id);
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        try {
+            const nftConnector = this.getConnector(id);
+            await nftConnector.burn(identity, id);
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "burnFailed", undefined, error);
+        }
+    }
+    /**
+     * Transfer an NFT.
+     * @param id The id of the NFT to transfer in urn format.
+     * @param recipient The recipient of the NFT.
+     * @param metadata Optional mutable data to include during the transfer.
+     * @param identity The identity to perform the nft operation on.
+     * @returns Nothing.
+     */
+    async transfer(id, recipient, metadata, identity) {
+        Urn.guard(this.CLASS_NAME, "id", id);
+        Guards.stringValue(this.CLASS_NAME, "recipient", recipient);
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        try {
+            const nftConnector = this.getConnector(id);
+            await nftConnector.transfer(identity, id, recipient, metadata);
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "transferFailed", undefined, error);
+        }
+    }
+    /**
+     * Update the data of the NFT.
+     * @param id The id of the NFT to update in urn format.
+     * @param metadata The mutable data to update.
+     * @param identity The identity to perform the nft operation on.
+     * @returns Nothing.
+     */
+    async update(id, metadata, identity) {
+        Urn.guard(this.CLASS_NAME, "id", id);
+        Guards.object(this.CLASS_NAME, "metadata", metadata);
+        Guards.stringValue(this.CLASS_NAME, "identity", identity);
+        try {
+            const nftConnector = this.getConnector(id);
+            await nftConnector.update(identity, id, metadata);
+        }
+        catch (error) {
+            throw new GeneralError(this.CLASS_NAME, "updateFailed", undefined, error);
+        }
+    }
+    /**
+     * Get the connector from the uri.
+     * @param id The id of the NFT in urn format.
+     * @returns The connector.
+     * @internal
+     */
+    getConnector(id) {
+        const idUri = Urn.fromValidString(id);
+        if (idUri.namespaceIdentifier() !== NftService.NAMESPACE) {
+            throw new GeneralError(this.CLASS_NAME, "namespaceMismatch", {
+                namespace: NftService.NAMESPACE,
+                id
+            });
+        }
+        return NftConnectorFactory.get(idUri.namespaceMethod());
+    }
+}
+
+const restEntryPoints = [
+    {
+        name: "nft",
+        defaultBaseRoute: "nft",
+        tags: tagsNft,
+        generateRoutes: generateRestRoutesNft
+    }
+];
+
+export { NftService, generateRestRoutesNft, nftBurn, nftMint, nftResolve, nftTransfer, nftUpdate, restEntryPoints, tagsNft };

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./models/INftServiceConfig";
+export * from "./models/INftServiceConstructorOptions";
+export * from "./nftRoutes";
+export * from "./nftService";
+export * from "./restEntryPoints";

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

@@ -0,0 +1,9 @@
+/**
+ * Configuration for the NFT Service.
+ */
+export interface INftServiceConfig {
+    /**
+     * What is the default connector to use for NFT. If not provided the first connector from the factory will be used.
+     */
+    defaultNamespace?: string;
+}

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

@@ -0,0 +1,10 @@
+import type { INftServiceConfig } from "./INftServiceConfig";
+/**
+ * Options for the nft service constructor.
+ */
+export interface INftServiceConstructorOptions {
+    /**
+     * The configuration for the service.
+     */
+    config?: INftServiceConfig;
+}

package/dist/types/nftRoutes.d.ts

@@ -0,0 +1,53 @@
+import type { ICreatedResponse, IHttpRequestContext, INoContentResponse, IRestRoute, ITag } from "@twin.org/api-models";
+import type { INftBurnRequest, INftMintRequest, INftResolveRequest, INftResolveResponse, INftTransferRequest, INftUpdateRequest } from "@twin.org/nft-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsNft: ITag[];
+/**
+ * The REST routes for NFT.
+ * @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 generateRestRoutesNft(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Mint an NFT.
+ * @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 nftMint(httpRequestContext: IHttpRequestContext, componentName: string, request: INftMintRequest): Promise<ICreatedResponse>;
+/**
+ * Resolve an NFT.
+ * @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 nftResolve(httpRequestContext: IHttpRequestContext, componentName: string, request: INftResolveRequest): Promise<INftResolveResponse>;
+/**
+ * Burn an NFT.
+ * @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 nftBurn(httpRequestContext: IHttpRequestContext, componentName: string, request: INftBurnRequest): Promise<INoContentResponse>;
+/**
+ * Transfer an NFT.
+ * @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 nftTransfer(httpRequestContext: IHttpRequestContext, componentName: string, request: INftTransferRequest): Promise<INoContentResponse>;
+/**
+ * Update an NFT.
+ * @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 nftUpdate(httpRequestContext: IHttpRequestContext, componentName: string, request: INftUpdateRequest): Promise<INoContentResponse>;

package/dist/types/nftService.d.ts

@@ -0,0 +1,68 @@
+import { type INftComponent } from "@twin.org/nft-models";
+import type { INftServiceConstructorOptions } from "./models/INftServiceConstructorOptions";
+/**
+ * Service for performing NFT operations to a connector.
+ */
+export declare class NftService implements INftComponent {
+    /**
+     * The namespace supported by the nft service.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Runtime name for the class.
+     */
+    readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of NftService.
+     * @param options The options for the service.
+     */
+    constructor(options?: INftServiceConstructorOptions);
+    /**
+     * Mint an NFT.
+     * @param issuer The issuer for the NFT, will also be the initial owner.
+     * @param tag The tag for the NFT.
+     * @param immutableMetadata The immutable metadata for the NFT.
+     * @param metadata The metadata for the NFT.
+     * @param namespace The namespace of the connector to use for the NFT, defaults to service configured namespace.
+     * @param identity The identity to perform the nft operation on.
+     * @returns The id of the created NFT in urn format.
+     */
+    mint<T = unknown, U = unknown>(issuer: string, tag: string, immutableMetadata?: T, metadata?: U, namespace?: string, identity?: string): Promise<string>;
+    /**
+     * Resolve an NFT.
+     * @param id The id of the NFT to resolve.
+     * @param identity The identity to perform the nft operation on.
+     * @returns The data for the NFT.
+     */
+    resolve<T = unknown, U = unknown>(id: string, identity?: string): Promise<{
+        issuer: string;
+        owner: string;
+        tag: string;
+        immutableMetadata?: T;
+        metadata?: U;
+    }>;
+    /**
+     * Burn an NFT.
+     * @param id The id of the NFT to burn in urn format.
+     * @param identity The identity to perform the nft operation on.
+     * @returns Nothing.
+     */
+    burn(id: string, identity?: string): Promise<void>;
+    /**
+     * Transfer an NFT.
+     * @param id The id of the NFT to transfer in urn format.
+     * @param recipient The recipient of the NFT.
+     * @param metadata Optional mutable data to include during the transfer.
+     * @param identity The identity to perform the nft operation on.
+     * @returns Nothing.
+     */
+    transfer<T = unknown>(id: string, recipient: string, metadata?: T, identity?: string): Promise<void>;
+    /**
+     * Update the data of the NFT.
+     * @param id The id of the NFT to update in urn format.
+     * @param metadata The mutable data to update.
+     * @param identity The identity to perform the nft operation on.
+     * @returns Nothing.
+     */
+    update<T = unknown>(id: string, metadata: T, identity?: string): Promise<void>;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,2 @@
+import type { IRestRouteEntryPoint } from "@twin.org/api-models";
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/nft-service - Changelog
+
+## v0.0.1-next.10
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/nft-service - Examples