diff --git a/changelog.md b/changelog.md index e519b86..2a5633a 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,10 @@ # Changelog +## 2024-12-19 - 1.0.11 - fix(interfaces) +Fixed import path in ts_interfaces/index.ts + +- Corrected import path for plugins in ts_interfaces/index.ts to prevent module resolution issues. + ## 2024-12-18 - 1.0.10 - fix(test) Add initial test for portablecontract diff --git a/npmextra.json b/npmextra.json index ee0179e..7bf9660 100644 --- a/npmextra.json +++ b/npmextra.json @@ -5,7 +5,7 @@ "githost": "gitlab.com", "gitscope": "signature.digital", "gitrepo": "tools", - "description": "A TypeScript package providing utility interfaces and classes for digital contract management and integration, leveraging modular design and business context integration.", + "description": "A TypeScript package providing utilities for managing digital contracts with modular interfaces and business context integration.", "npmPackagename": "@signature.digital/tools", "license": "MIT", "projectDomain": "signature.digital", @@ -13,19 +13,27 @@ "TypeScript", "digital contracts", "contract management", - "ESM", - "interfaces", - "business integration", "modular design", + "business integration", + "interfaces", + "typescript utilities", + "contract structures", + "interfaces-driven architecture", "contract modeling", "business relationships", "data handling", - "TypeScript utilities" + "asynchronous loading", + "dynamic role assignment", + "contract validation", + "unit testing" ] } }, "npmci": { "npmGlobalTools": [], "npmAccessLevel": "public" + }, + "tsdoc": { + "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n" } } \ No newline at end of file diff --git a/package.json b/package.json index a696cfd..e6b1197 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@signature.digital/tools", "version": "1.0.10", "private": false, - "description": "A TypeScript package providing utility interfaces and classes for digital contract management and integration, leveraging modular design and business context integration.", + "description": "A TypeScript package providing utilities for managing digital contracts with modular interfaces and business context integration.", "exports": { ".": "./ts/index.js", "./interfaces": "./dist_ts_interfaces/index.js" @@ -53,13 +53,18 @@ "TypeScript", "digital contracts", "contract management", - "ESM", - "interfaces", - "business integration", "modular design", + "business integration", + "interfaces", + "typescript utilities", + "contract structures", + "interfaces-driven architecture", "contract modeling", "business relationships", "data handling", - "TypeScript utilities" + "asynchronous loading", + "dynamic role assignment", + "contract validation", + "unit testing" ] -} +} \ No newline at end of file diff --git a/readme.md b/readme.md index b9c92e8..c67998b 100644 --- a/readme.md +++ b/readme.md @@ -1,171 +1,315 @@ # @signature.digital/tools - -A package that defines standard tools for working with contracts. +A TypeScript package offering utility interfaces and classes for efficient digital contract management and business context integration with a modular design. ## Install - -To install `@signature.digital/tools`, you'll use your preferred package manager. Assuming you're using npm, follow the steps below: +To install the `@signature.digital/tools` package, use your preferred package manager. For npm, run the following command: ```bash npm install @signature.digital/tools ``` -Or, if you prefer using Yarn: +Alternatively, if you are using Yarn, you can add the package with: ```bash yarn add @signature.digital/tools ``` -Make sure that you have Node.js installed on your system to use this package. The module is distributed as an ECMAScript Module (ESM), so you'll need a strategy for dealing with ESM in your project if you're using commonjs modules. As usual, ensure that your TypeScript configuration (`tsconfig.json`) has `"module": "ESNext"` or similar settings that support ESM. +Ensure your development environment supports ECMAScript Modules. In your `tsconfig.json`, you should set the `"module"` option to `"ESNext"` or a compatible module type that supports ES Modules. ## Usage -### Overview +This guide details the comprehensive features of the `@signature.digital/tools` package, designed to streamline digital contract management in TypeScript applications. By using this package, you can leverage the structured capabilities of TypeScript to define, manage, and operate on digital contracts effectively. -`@signature.digital/tools` provides a set of interfaces and classes that serve as general utilities for working with contracts digitalization, management, and integration. With a focus on adaptability and ease of use in TypeScript projects, its toolset leverages types, interfaces, and utilities from the `@tsclass/tsclass` package to enhance contract structures. This package aims to facilitate the definition and handling of contractual data, enabling the modeling of business relationships and agreements as TypeScript objects. +### Introduction to the Module -### Core Concepts +The `@signature.digital/tools` package capitalizes on TypeScript's robust typing system to mold digital contract management paradigms. It encourages an interface-driven approach to designing contracts, promotes modularity, and integrates business context inherently within its structures. -Before diving into the various tools provided by this package, let's establish a few foundational concepts: +### Key Features -1. **Interface Driven Design:** - The module uses TypeScript interfaces as blueprints for structuring custom contract models. Interfaces such as `IPortableContract`, `IParagraph`, `IRole`, and `IInvolvedParty` are integral to the way data is defined and manipulated. +1. **Interface-Driven Design:** + Utilize TypeScript interfaces to clearly delineate data structures for contracts. This results in easily maintainable, testable, and scalable digital contract solutions. -2. **Modularity:** - This package allows developers to segment responsibilities and logic by modularizing contract components into roles, paragraphs, parties, and related structures. +2. **Modular Architecture:** + Divide and conquer complex contract datasets by representing them as reusable modules. -3. **Business Context Integration:** - Through integration with `@tsclass/tsclass`, the module facilitates the inclusion of business-related metadata into contracts, aligning with typical business use cases such as defining involved parties and their roles. +3. **Business Contextualization:** + Seamlessly integrate business metadata into your contracts to reflect real-world applications and business scenarios. ### Usage Scenarios -#### Defining a Contract +Below are practical examples to help you understand and leverage the full capabilities of the `@signature.digital/tools` package. -A `IPortableContract` is at the heart of this package. It encapsulates crucial details about a contract such as title, context, roles, parties involved, prior related contracts, and structured paragraphs or sections. +#### 1. Designing Contract Components + +Begin by defining the core components of a contract using the provided interfaces. Start with `IRole`, `IInvolvedParty`, `IParagraph`, and `IPortableContract`: ```typescript import { IPortableContract, IRole, IInvolvedParty, IParagraph } from '@signature.digital/tools'; import { tsclass } from '@signature.digital/tools'; -const legalRole: IRole = { - id: 'role-001', - name: 'Legal Advisor', - description: 'Provides legal counsel and insights on contractual obligations.' -}; - -const stakeholderRole: IRole = { - id: 'role-002', - name: 'Stakeholder', - description: 'Has a stake in the contract outcomes and implications.' -}; - -const legalAdvisorContact: tsclass.business.IContact = { - email: 'legal@firm.domain', - address: '456 Legal Ave, Lawyersville' -}; - -const stakeholderContact: tsclass.business.IContact = { - email: 'stakeholder@domain.org', - address: '789 Stakeholder Loop, Business City' -}; - -const involvedParties: IInvolvedParty[] = [ +const createRoles = (): IRole[] => [ { - role: legalRole.name, - contact: legalAdvisorContact + id: 'role-001', + name: 'Legal Advisor', + description: 'Advises on legal obligations and ensures compliance.' }, { - role: stakeholderRole.name, - contact: stakeholderContact + id: 'role-002', + name: 'Stakeholder', + description: 'Interest in the outcome of the contract.' } ]; -const introductoryParagraph: IParagraph = { - uniqueId: 'para-001', - parent: null, - title: 'Introduction', - content: 'This section provides an introduction to the contract, detailing its purpose and significance.' -}; - -const commitmentParagraph: IParagraph = { - uniqueId: 'para-002', - parent: introductoryParagraph, - title: 'Commitments', - content: 'Describes the commitments of the involved parties.' -}; - -const contract: IPortableContract = { - title: 'Digital Service Agreement', - context: 'Provides a framework of service delivery between involved entities.', - availableRoles: [legalRole, stakeholderRole], - involvedParties, - priorContracts: [], - paragraphs: [introductoryParagraph, commitmentParagraph] +const createContacts = (): tsclass.business.IContact[] => [ + { + email: 'advisor@legalfirm.com', + address: '123 Legal Firm St, Legal City' + }, + { + email: 'stakeholder@business.com', + address: '456 Business Way, Industry City' + } +]; + +const createParagraphs = (): IParagraph[] => [ + { + uniqueId: 'para-001', + parent: null, + title: 'Introduction', + content: 'Introduction to the contract, setting expectations and scope of the agreement.' + }, + { + uniqueId: 'para-002', + parent: null, + title: 'Obligations', + content: 'Details the specific obligations and responsibilities of each involved party.' + } +]; + +const createPortableContract = (): IPortableContract => { + const roles = createRoles(); + const contacts = createContacts(); + const paragraphs = createParagraphs(); + + return { + title: 'Digital Service Agreement', + context: 'A digital service provision framework between organizations.', + availableRoles: roles, + involvedParties: [ + { role: roles[0].name, contact: contacts[0] }, + { role: roles[1].name, contact: contacts[1] } + ], + priorContracts: [], + paragraphs + }; }; +const contract = createPortableContract(); console.log(contract); ``` -### Validating Contracts +This example highlights how you can define the roles, contacts, and paragraphs that collectively represent a comprehensive digital contract model. -Regarding validation, this package utilizes `@tsclass/tsclass` to enhance the consistency and robustness of contact data handling. While not embedding specific validation methods, this encourages the integration of validation strategies that developers can extend or implement themselves. +#### 2. Expanding Contract Details -### Extending the Interfaces - -Developers are encouraged to extend the interfaces to accommodate additional requirements. +Extend core contracts to encapsulate more details specific to your organizational needs. You can add dates, custom attributes, or any other relevant information: ```typescript -interface IExtendedContract extends IPortableContract { - effectiveDate: Date; - expirationDate: Date; +interface IExtendedPortableContract extends IPortableContract { + startDate: Date; + endDate: Date; + customAttributes?: Record; } -const extendedContract: IExtendedContract = { - ...contract, - effectiveDate: new Date('2023-01-01'), - expirationDate: new Date('2025-01-01') +const createExtendedContract = (): IExtendedPortableContract => { + const baseContract = createPortableContract(); + return { + ...baseContract, + startDate: new Date('2023-01-01'), + endDate: new Date('2024-01-01'), + customAttributes: { + department: 'Legal', + projectCode: 'DSA2023' + } + }; }; + +const extendedContract = createExtendedContract(); +console.log(extendedContract); ``` -### Handling Prior Contracts +#### 3. Maintaining Contract History -The `priorContracts` property allows you to model contract inheritance or reference, enabling historical traceability or derivations. +Managing contractual history provides a strategic advantage in legal and administrative processes. Employ the `priorContracts` attribute to keep track of iterations: ```typescript -const previousContract: IPortableContract = { - title: 'Precedent Service Agreement', - context: 'Sets a precedent for the current agreement.', - availableRoles: [legalRole, stakeholderRole], - involvedParties, +const initialContractVersion: IPortableContract = { + title: 'Initial Service Agreement', + context: 'Foundation agreement before the current digital service contract.', + availableRoles: createRoles(), + involvedParties: [ + { role: 'Legal Advisor', contact: createContacts()[0] } + ], priorContracts: [], paragraphs: [] }; -const referencedContract: IPortableContract = { - ...contract, - priorContracts: [previousContract] +const updatedContractVersion = { + ...initialContractVersion, + title: 'Revised Digital Service Agreement', + priorContracts: [initialContractVersion] }; -console.log(referencedContract); +console.log(updatedContractVersion); ``` -### Integrating Business Features +This functionality is crucial for firms that require detailed records of contractual changes over time. -The built-in synergy with `@tsclass/tsclass` permits a natural extension to business contact data directly within the contracts. +#### 4. Integrating Business Entities + +Leverage the power of `@tsclass/tsclass` to seamlessly embed business information within contracts, enhancing clarity and context: ```typescript -const newInvolvedParty: IInvolvedParty = { - role: 'Project Manager', +const businessParty = { + role: 'Business Analyst', contact: { - email: 'manager@domain.com', - address: '101 Managerial Blvd, Operationscity' + email: 'analyst@corporation.com', + address: '123 Business Lane, Tech City' } }; -contract.involvedParties.push(newInvolvedParty); +extendedContract.involvedParties.push(businessParty); +console.log(extendedContract.involvedParties); ``` -### Conclusion +This level of integration is perfect for incorporating stakeholders' information. -The `@signature.digital/tools` package is designed to provide the essential scaffolding necessary to build intricate, business-oriented contract models while ensuring TypeScript's static type safety. Its major strength lies in its extensibility and the clarity it brings to contract structures, making modeling, data management, and integration straightforward for any digital contract-centric application. Adopt these tools to facilitate the standardized crafting of contract-based solutions across your enterprise applications. -undefined \ No newline at end of file +#### 5. Implementing Validation Logic + +While the package promotes interface-based design, users must implement validation patterns to ensure contract data integrity. Below is an example of how to perform basic validations: + +```typescript +function isValidContractStructure(contract: IPortableContract): boolean { + return ( + contract.context !== '' && + contract.availableRoles.length > 0 && + contract.involvedParties.length > 0 && + contract.paragraphs.every(paragraph => paragraph.content !== '') + ); +} + +if (!isValidContractStructure(extendedContract)) { + throw new Error('Invalid contract structure detected!'); +} +``` + +This sample function demonstrates a straightforward mechanism to verify that the contract structure adheres to defined rules and prevents incorrect data entries. + +### Advanced Usage + +Let's delve into more intricate capabilities and scenarios that `@signature.digital/tools` can facilitate: + +#### Asynchronous Loading and Initialization + +For scenarios where parts of contracts or their dependencies are fetched from databases or APIs, the `@signature.digital/tools` suite can interact seamlessly with asynchronous sources: + +```typescript +async function fetchContractData(): Promise { + // Simulate API call + return new Promise((resolve) => { + setTimeout(() => resolve(createPortableContract()), 1000); + }); +} + +async function initializeAsyncContract() { + try { + const contractData = await fetchContractData(); + console.log('Loaded contract:', contractData); + } catch (error) { + console.error('Error fetching contract data:', error); + } +} + +initializeAsyncContract(); +``` + +This approach is vital when integrating with remote contract stores or dynamically fetching contract components. + +#### Dynamic Role Assignment + +Business environments often require flexibility in role assignments, which can be handled dynamically within the contract configurations: + +```typescript +function addDynamicRoleToContract(contract: IPortableContract, roleName: string, contactInfo: tsclass.business.IContact) { + const role: IRole = { + id: `role-${Math.random().toString(36).substr(2, 9)}`, // Random ID generator + name: roleName, + description: `Dynamic role added for ${roleName}` + }; + + contract.availableRoles.push(role); + contract.involvedParties.push({ role: role.name, contact: contactInfo }); + console.log(`Added role: ${roleName}`); +} + +addDynamicRoleToContract(contract, 'Compliance Officer', { + email: 'compliance@business.com', + address: 'Office 42, Compliance Street' +}); +console.log(contract); +``` + +Dynamic role assignments are essential when handling expansive contracts with changing stakeholder roles. + +#### Comprehensive Testing + +You should construct extensive tests for contract components by leveraging TypeScript's compatibility with common testing frameworks. Although the test cases here are isolated, they serve as foundational templates: + +```typescript +import { expect } from '@push.rocks/tapbundle'; + +tap.test('Contract Initial Structure', async () => { + const contractBase = createPortableContract(); + expect(contractBase.title).toBe('Digital Service Agreement'); + expect(contractBase.paragraphs.length).toBeGreaterThan(0); +}); + +tap.test('Role Addition', async () => { + const testContract = createPortableContract(); + const initialRoleCount = testContract.availableRoles.length; + + const newRole: IRole = { + id: 'role-003', + name: 'Tester', + description: 'Ensures quality and compliance of the contract.' + }; + + testContract.availableRoles.push(newRole); + expect(testContract.availableRoles.length).toBe(initialRoleCount + 1); +}); + +tap.start(); +``` + +These examples demonstrate basic test cases to verify the functionality and resiliency of your contract management system. + +By utilizing the `@signature.digital/tools` package, developers can construct robust, dynamic, and efficient digital contract management systems tailored to a wide array of business scenarios. The examples provided above only scratch the surface of the package's versatility and extendability, empowering developers to innovate and automate contract handling processes in TypeScript. + +## License and Legal Information + +This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. + +**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. + +### Trademarks + +This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. + +### Company Information + +Task Venture Capital GmbH +Registered at District court Bremen HRB 35230 HB, Germany + +For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. + +By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works. diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index f5a58db..0a82a03 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@signature.digital/tools', - version: '1.0.10', - description: 'A TypeScript package providing utility interfaces and classes for digital contract management and integration, leveraging modular design and business context integration.' + version: '1.0.11', + description: 'A TypeScript package providing utilities for managing digital contracts with modular interfaces and business context integration.' } diff --git a/ts_interfaces/index.ts b/ts_interfaces/index.ts index e9fdcf8..e0f3d20 100644 --- a/ts_interfaces/index.ts +++ b/ts_interfaces/index.ts @@ -1,5 +1,4 @@ -import * as plugins from '../ts/portablecontract.plugins.js'; - +import * as plugins from './plugins.js'; export interface IParagraph { uniqueId: string; parent: IParagraph | null;