|
|
|
|
@ -1,315 +1,171 @@
|
|
|
|
|
# @signature.digital/tools
|
|
|
|
|
A TypeScript package offering utility interfaces and classes for efficient digital contract management and business context integration with a modular design.
|
|
|
|
|
|
|
|
|
|
A package that defines standard tools for working with contracts.
|
|
|
|
|
|
|
|
|
|
## Install
|
|
|
|
|
To install the `@signature.digital/tools` package, use your preferred package manager. For npm, run the following command:
|
|
|
|
|
|
|
|
|
|
To install `@signature.digital/tools`, you'll use your preferred package manager. Assuming you're using npm, follow the steps below:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npm install @signature.digital/tools
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Alternatively, if you are using Yarn, you can add the package with:
|
|
|
|
|
Or, if you prefer using Yarn:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
yarn add @signature.digital/tools
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
### Overview
|
|
|
|
|
|
|
|
|
|
### Introduction to the Module
|
|
|
|
|
`@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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
### Core Concepts
|
|
|
|
|
|
|
|
|
|
### Key Features
|
|
|
|
|
Before diving into the various tools provided by this package, let's establish a few foundational concepts:
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
2. **Modular Architecture:**
|
|
|
|
|
Divide and conquer complex contract datasets by representing them as reusable modules.
|
|
|
|
|
2. **Modularity:**
|
|
|
|
|
This package allows developers to segment responsibilities and logic by modularizing contract components into roles, paragraphs, parties, and related structures.
|
|
|
|
|
|
|
|
|
|
3. **Business Contextualization:**
|
|
|
|
|
Seamlessly integrate business metadata into your contracts to reflect real-world applications and business scenarios.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### Usage Scenarios
|
|
|
|
|
|
|
|
|
|
Below are practical examples to help you understand and leverage the full capabilities of the `@signature.digital/tools` package.
|
|
|
|
|
#### Defining a Contract
|
|
|
|
|
|
|
|
|
|
#### 1. Designing Contract Components
|
|
|
|
|
|
|
|
|
|
Begin by defining the core components of a contract using the provided interfaces. Start with `IRole`, `IInvolvedParty`, `IParagraph`, and `IPortableContract`:
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
import { IPortableContract, IRole, IInvolvedParty, IParagraph } from '@signature.digital/tools';
|
|
|
|
|
import { tsclass } from '@signature.digital/tools';
|
|
|
|
|
|
|
|
|
|
const createRoles = (): IRole[] => [
|
|
|
|
|
{
|
|
|
|
|
const legalRole: IRole = {
|
|
|
|
|
id: 'role-001',
|
|
|
|
|
name: 'Legal Advisor',
|
|
|
|
|
description: 'Advises on legal obligations and ensures compliance.'
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
description: 'Provides legal counsel and insights on contractual obligations.'
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const stakeholderRole: IRole = {
|
|
|
|
|
id: 'role-002',
|
|
|
|
|
name: 'Stakeholder',
|
|
|
|
|
description: 'Interest in the outcome of the contract.'
|
|
|
|
|
}
|
|
|
|
|
];
|
|
|
|
|
description: 'Has a stake in the contract outcomes and implications.'
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const createContacts = (): tsclass.business.IContact[] => [
|
|
|
|
|
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[] = [
|
|
|
|
|
{
|
|
|
|
|
email: 'advisor@legalfirm.com',
|
|
|
|
|
address: '123 Legal Firm St, Legal City'
|
|
|
|
|
role: legalRole.name,
|
|
|
|
|
contact: legalAdvisorContact
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
email: 'stakeholder@business.com',
|
|
|
|
|
address: '456 Business Way, Industry City'
|
|
|
|
|
role: stakeholderRole.name,
|
|
|
|
|
contact: stakeholderContact
|
|
|
|
|
}
|
|
|
|
|
];
|
|
|
|
|
|
|
|
|
|
const createParagraphs = (): IParagraph[] => [
|
|
|
|
|
{
|
|
|
|
|
const introductoryParagraph: IParagraph = {
|
|
|
|
|
uniqueId: 'para-001',
|
|
|
|
|
parent: null,
|
|
|
|
|
title: 'Introduction',
|
|
|
|
|
content: 'Introduction to the contract, setting expectations and scope of the agreement.'
|
|
|
|
|
},
|
|
|
|
|
{
|
|
|
|
|
content: 'This section provides an introduction to the contract, detailing its purpose and significance.'
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const commitmentParagraph: IParagraph = {
|
|
|
|
|
uniqueId: 'para-002',
|
|
|
|
|
parent: null,
|
|
|
|
|
title: 'Obligations',
|
|
|
|
|
content: 'Details the specific obligations and responsibilities of each involved party.'
|
|
|
|
|
}
|
|
|
|
|
];
|
|
|
|
|
parent: introductoryParagraph,
|
|
|
|
|
title: 'Commitments',
|
|
|
|
|
content: 'Describes the commitments of the involved parties.'
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const createPortableContract = (): IPortableContract => {
|
|
|
|
|
const roles = createRoles();
|
|
|
|
|
const contacts = createContacts();
|
|
|
|
|
const paragraphs = createParagraphs();
|
|
|
|
|
|
|
|
|
|
return {
|
|
|
|
|
const contract: IPortableContract = {
|
|
|
|
|
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] }
|
|
|
|
|
],
|
|
|
|
|
context: 'Provides a framework of service delivery between involved entities.',
|
|
|
|
|
availableRoles: [legalRole, stakeholderRole],
|
|
|
|
|
involvedParties,
|
|
|
|
|
priorContracts: [],
|
|
|
|
|
paragraphs
|
|
|
|
|
};
|
|
|
|
|
paragraphs: [introductoryParagraph, commitmentParagraph]
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const contract = createPortableContract();
|
|
|
|
|
console.log(contract);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This example highlights how you can define the roles, contacts, and paragraphs that collectively represent a comprehensive digital contract model.
|
|
|
|
|
### Validating Contracts
|
|
|
|
|
|
|
|
|
|
#### 2. Expanding Contract Details
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Extend core contracts to encapsulate more details specific to your organizational needs. You can add dates, custom attributes, or any other relevant information:
|
|
|
|
|
### Extending the Interfaces
|
|
|
|
|
|
|
|
|
|
Developers are encouraged to extend the interfaces to accommodate additional requirements.
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
interface IExtendedPortableContract extends IPortableContract {
|
|
|
|
|
startDate: Date;
|
|
|
|
|
endDate: Date;
|
|
|
|
|
customAttributes?: Record<string, any>;
|
|
|
|
|
interface IExtendedContract extends IPortableContract {
|
|
|
|
|
effectiveDate: Date;
|
|
|
|
|
expirationDate: Date;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
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: IExtendedContract = {
|
|
|
|
|
...contract,
|
|
|
|
|
effectiveDate: new Date('2023-01-01'),
|
|
|
|
|
expirationDate: new Date('2025-01-01')
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const extendedContract = createExtendedContract();
|
|
|
|
|
console.log(extendedContract);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
#### 3. Maintaining Contract History
|
|
|
|
|
### Handling Prior Contracts
|
|
|
|
|
|
|
|
|
|
Managing contractual history provides a strategic advantage in legal and administrative processes. Employ the `priorContracts` attribute to keep track of iterations:
|
|
|
|
|
The `priorContracts` property allows you to model contract inheritance or reference, enabling historical traceability or derivations.
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
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] }
|
|
|
|
|
],
|
|
|
|
|
const previousContract: IPortableContract = {
|
|
|
|
|
title: 'Precedent Service Agreement',
|
|
|
|
|
context: 'Sets a precedent for the current agreement.',
|
|
|
|
|
availableRoles: [legalRole, stakeholderRole],
|
|
|
|
|
involvedParties,
|
|
|
|
|
priorContracts: [],
|
|
|
|
|
paragraphs: []
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const updatedContractVersion = {
|
|
|
|
|
...initialContractVersion,
|
|
|
|
|
title: 'Revised Digital Service Agreement',
|
|
|
|
|
priorContracts: [initialContractVersion]
|
|
|
|
|
const referencedContract: IPortableContract = {
|
|
|
|
|
...contract,
|
|
|
|
|
priorContracts: [previousContract]
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
console.log(updatedContractVersion);
|
|
|
|
|
console.log(referencedContract);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This functionality is crucial for firms that require detailed records of contractual changes over time.
|
|
|
|
|
### Integrating Business Features
|
|
|
|
|
|
|
|
|
|
#### 4. Integrating Business Entities
|
|
|
|
|
|
|
|
|
|
Leverage the power of `@tsclass/tsclass` to seamlessly embed business information within contracts, enhancing clarity and context:
|
|
|
|
|
The built-in synergy with `@tsclass/tsclass` permits a natural extension to business contact data directly within the contracts.
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
const businessParty = {
|
|
|
|
|
role: 'Business Analyst',
|
|
|
|
|
const newInvolvedParty: IInvolvedParty = {
|
|
|
|
|
role: 'Project Manager',
|
|
|
|
|
contact: {
|
|
|
|
|
email: 'analyst@corporation.com',
|
|
|
|
|
address: '123 Business Lane, Tech City'
|
|
|
|
|
email: 'manager@domain.com',
|
|
|
|
|
address: '101 Managerial Blvd, Operationscity'
|
|
|
|
|
}
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
extendedContract.involvedParties.push(businessParty);
|
|
|
|
|
console.log(extendedContract.involvedParties);
|
|
|
|
|
contract.involvedParties.push(newInvolvedParty);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This level of integration is perfect for incorporating stakeholders' information.
|
|
|
|
|
### Conclusion
|
|
|
|
|
|
|
|
|
|
#### 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<IPortableContract> {
|
|
|
|
|
// 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.
|
|
|
|
|
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
|