@powerhousedao/contributor-billing 0.1.27 → 0.1.30

package/README.md

@@ -1,22 +1,179 @@
 # Document Model Boilerplate
 
-Invoice package that can be used to create invoice document models and request payments in Fiat and Crypto.
+This Document Model Boilerplate provides code generation for scaffolding editors and models. 
+It ensures compatibility with host applications like Connect and the Reactors for seamless document model and editor integration.
 
-## Requirements
+## Standard Document Model Workflow with help of the boilerplate.
+This tutorial will guide you through the process of creating a new document model using the Document Model Editor in the Connect app. 
 
-`.env` file in the root of the project
+<details>
+<summary>Available NPM commands</summary>
 
-## Installation
+-   `generate`: Updates the generated code according to the JSON spec and GraphQL schema of your document model, made in Connect.
+-   `lint`: Checks for errors with ESLint and TypeScript checking.
+-   `format`: Formats the code using Prettier.
+-   `build`: Builds the library project using Vite.
+-   `storybook`: Starts Storybook in development mode.
+-   `build-storybook`: Builds Storybook.
+-   `test`: Runs Jest for testing.
+
+</details>
+
+### 1. Defining Your Document Model GraphQL Schema
+Start by creating your own 'Powerhouse Project' (Document model + editor).
+
+Step 1: Run the following command to set up your project inside this directory:
+
+```bash
+npm create document-model-lib
+```
+
+Step 2: Use the Document Model Editor in the Connect app
+
+The following command gives you access to all the powerhouse CLI tools available, install it globally if you are a poweruser. 
+
+```bash
+npm install ph-cmd
+```
+Now you are able to launch Connect in Studio Mode (Locally):
+
+```bash
+npm run connect
+```
+
+Open the 'Document Model' creator at the bottom of connect to define your document mode with it's GraphQL Schema Definition.
+This schema will define the structure and fields for your document model using GraphQL. 
+Follow one of our tutorials on Academy to get familiar with the process. 
+
+### 2. Defining Document Model Operations
+Using the Document Model Operations Editor, define the operations for your document model and their GraphQL counterparts. 
+These operations will handle state changes within your document model.
+
+**Best Practices:**
+
+- Clearly define CRUD operations (Create, Read, Update, Delete).
+- Use GraphQL input types to specify the parameters for each operation.
+- Ensure that operations align with user intent to maintain a clean and understandable API.
+
+### 3. Generating Scaffolding Code
+Export your document model as a .zip file from Connect.
+Import the .zip file into your project directory created in Step 1.
+Run the following command to generate the scaffolding code:
+
+```bash
+npm run generate YourModelName.phdm.zip
+```
+
+This will create a new directory under /document-models containing:
+
+JSON file with the document model specification.
+GraphQL file with state and operation schemas.
+A gen/ folder with autogenerated code.
+A src/ folder for your custom code implementation.
+
+### 4. Implementing Reducer Code and Unit Tests
+Navigate to the reducer directory:
+
+```bash
+cd document-models/"YourModelName"/src/reducers
+```
+
+Implement the reducer functions for each document model operation. These functions will handle state transitions.
+
+Add utility functions in:
 
 ```bash
-npm install
+document-models/"YourModelName"/src/utils.ts
 ```
 
-## Usage
+Write unit tests to ensure the correctness of your reducers:
+
+Test files should be located in:
+
+```bash
+document-models/"YourModelName"/src/reducers/tests
+```
+
+Run the tests:
+
+```bash
+npm test
+```
+
+Test the editor functionality:
+
+```bash
+npm run connect
+```
+
+### 5. Implementing Document Editors
+Generate the editor template for your document model:
+
+```bash
+npm run generate -- --editor YourModelName --document-types powerhouse/YourModelName
+```
+
+The --editor flag specifies the name of your document model.
+The --document-types flag links the editor to your document model type.
+After generation:
+
+Open the editor template:
 
 ```bash
-npm run connect // to run the Connect app
-npm run reactor // to run the Reactor backend
+editors/YourModelName/editor.tsx
+```
 
+Customize the editor interface to suit your document model.
+
+### 6. Testing the Document Editor
+Run the Connect app to test your document editor:
+
+```bash
+npm run connect
 ```
 
+Verify that the editor functions as expected.
+Perform end-to-end testing to ensure smooth integration between the document model and its editor.
+
+### 7. Adding a Manifest File
+Create a manifest file to describe your document model and editor. This enables proper integration with the host application.
+
+**Example manifest.json:**
+
+```json
+{
+  "name": "your-model-name",
+  "description": "A brief description of your document model.",
+  "category": "your-category", // e.g., "Finance", "People Ops", "Legal"
+  "publisher": {
+    "name": "your-publisher-name",
+    "url": "your-publisher-url"
+  },
+  "documentModels": [
+    {
+      "id": "your-model-id",
+      "name": "your-model-name"
+    }
+  ],
+  "editors": [
+    {
+      "id": "your-editor-id",
+      "name": "your-editor-name",
+      "documentTypes": ["your-model-id"]
+    }
+  ]
+}
+```
+
+### Steps to finalize:
+
+Place the manifest file at your project root.
+Update your index.js to export your modules and include the new document model and editor.
+
+### Final Thoughts
+You've now successfully created a Document Model and its corresponding Editor using the Connect app!
+
+Next Steps:
+- Expand functionality: Add more operations or complex logic to your document model.
+- Improve UX: Enhance the document editor for a smoother user experience.
+- Integrate with other systems: Use APIs or GraphQL to connect your document model with external services.

package/dist/document-models/billing-statement/actions.d.ts

@@ -3,6 +3,7 @@ export declare const actions: {
     editLineItemTag: (input: import("./index.js").EditLineItemTagInput) => import("./index.js").EditLineItemTagAction;
     addLineItem: (input: import("./index.js").AddLineItemInput) => import("./index.js").AddLineItemAction;
     editLineItem: (input: import("./index.js").EditLineItemInput) => import("./index.js").EditLineItemAction;
+    deleteLineItem: (input: import("./index.js").DeleteLineItemInput) => import("./index.js").DeleteLineItemAction;
     editBillingStatement: (input: import("./index.js").EditBillingStatementInput) => import("./index.js").EditBillingStatementAction;
     editContributor: (input: import("./index.js").EditContributorInput) => import("./index.js").EditContributorAction;
     editStatus: (input: import("./index.js").EditStatusInput) => import("./index.js").EditStatusAction;

package/dist/document-models/billing-statement/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../document-models/billing-statement/actions.ts"],"names":[],"mappings":"AAOA,sDAAsD;AACtD,eAAO,MAAM,OAAO;sBAGZ,gDACI;kBAEK,4CAAuB;mBAA2K,6CAAwB;2BAAnG,qDAAgC;sBAAyM,gDAA2B;iBAAoL,2CAAsB;;eAA6vM,CAAC,eAAe,CAAC;gBAAkE,CAAC,eAAe,CAAC;iBAAmE,CAAC,aAAa,CAAC,eAAe,CAAC;;;;gBAAqS,CAAC;CAD9zO,CAAC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../document-models/billing-statement/actions.ts"],"names":[],"mappings":"AAOA,sDAAsD;AACtD,eAAO,MAAM,OAAO;sBAGZ,gDACI;kBAE2F,4CAAuB;mBAA2K,6CAAwB;qBAAgL,+CAA0B;2BAAnY,qDAAgC;sBAAyM,gDAA2B;iBAAoL,2CAAsB;;eAA6vM,CAAC,eAAe,CAAC;gBAAkE,CAAC,eAAe,CAAC;iBAAmE,CAAC,aAAa,CAAC,eAAe,CAAC;;;;gBAAqS,CAAC;CAD9zO,CAAC"}

package/dist/document-models/billing-statement/gen/document-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-model.d.ts","sourceRoot":"","sources":["../../../../document-models/billing-statement/gen/document-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,eAAO,MAAM,aAAa,EAAE,wBA8H3B,CAAC"}
+{"version":3,"file":"document-model.d.ts","sourceRoot":"","sources":["../../../../document-models/billing-statement/gen/document-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D,eAAO,MAAM,aAAa,EAAE,wBAyI3B,CAAC"}

package/dist/document-models/billing-statement/gen/document-model.js

@@ -1,117 +1,128 @@
 export const documentModel = {
-    id: "powerhouse/billing-statement",
-    name: "Billing Statement",
-    extension: ".phdm",
-    description: "The Billing Statement Document Model captures a contributor’s issued charges, with itemized line entries and auto-calculated totals in cash and POWT's.",
     author: {
         name: "Powerhouse",
         website: "https://powerhouse.inc",
     },
+    description: "The Billing Statement Document Model captures a contributor’s issued charges, with itemized line entries and auto-calculated totals in cash and POWT's.",
+    extension: "",
+    id: "powerhouse/billing-statement",
+    name: "Billing Statement",
     specifications: [
         {
-            version: 1,
             changeLog: [],
-            state: {
-                global: {
-                    schema: "type BillingStatementState {\n  contributor: PHID  # Change to AID when available\n  dateIssued: DateTime!\n  dateDue: DateTime\n  lineItems: [BillingStatementLineItem!]!\n  status: BillingStatementStatus!\n  currency: String!\n  totalCash: Float!\n  totalPowt: Float!\n  notes: String\n}\n\ntype BillingStatementLineItem {\n  id: OID!\n  description: String!\n  quantity: Float!\n  unit: BillingStatementUnit!\n  unitPricePwt: Float!\n  unitPriceCash: Float!\n  totalPricePwt: Float!\n  totalPriceCash: Float!\n  lineItemTag: [BillingStatementTag!]!\n}\n\ntype BillingStatementTag {\n  dimension: String!\n  value: String!\n  label: String\n}\n\nenum BillingStatementStatus {\n  DRAFT\n  ISSUED\n  ACCEPTED\n  REJECTED\n  PAID\n}\n\nenum BillingStatementStatusInput {\n  DRAFT\n  ISSUED\n  ACCEPTED\n  REJECTED\n  PAID\n}\n\nenum BillingStatementUnit {\n  MINUTE\n  HOUR\n  DAY\n  UNIT\n}\n\nenum BillingStatementUnitInput {\n  MINUTE\n  HOUR\n  DAY\n  UNIT\n}\n\n",
-                    initialValue: '"{\\n  \\"contributor\\": \\"\\",\\n  \\"dateIssued\\": \\"2025-06-10T15:42:17.873Z\\",\\n  \\"dateDue\\": \\"2025-06-10T15:42:17.873Z\\",\\n  \\"lineItems\\": [],\\n  \\"status\\": \\"DRAFT\\",\\n  \\"currency\\": \\"\\",\\n  \\"totalCash\\": 0,\\n  \\"totalPowt\\": 0,\\n  \\"notes\\": \\"\\"\\n}"',
-                    examples: [],
-                },
-                local: {
-                    schema: "",
-                    initialValue: '""',
-                    examples: [],
-                },
-            },
             modules: [
                 {
+                    description: "",
                     id: "dnNu8Q38g6PEhUWWnwSWA1mTr40=",
                     name: "general",
-                    description: "",
                     operations: [
                         {
-                            id: "obKvjYTcH1TKFjSO5DGtmC9HS7w=",
-                            name: "EDIT_BILLING_STATEMENT",
                             description: "",
-                            schema: "input EditBillingStatementInput {\n  dateIssued: DateTime\n  dateDue: DateTime\n  currency: String\n  notes: String\n}",
-                            template: "",
-                            reducer: "",
                             errors: [],
                             examples: [],
+                            id: "obKvjYTcH1TKFjSO5DGtmC9HS7w=",
+                            name: "EDIT_BILLING_STATEMENT",
+                            reducer: "",
+                            schema: "input EditBillingStatementInput {\n  dateIssued: DateTime\n  dateDue: DateTime\n  currency: String\n  notes: String\n}",
                             scope: "global",
+                            template: "",
                         },
                         {
-                            id: "pkU1fg9dl0SDxHb+294KsqUDMN4=",
-                            name: "EDIT_CONTRIBUTOR",
                             description: "",
-                            schema: "input EditContributorInput {\n  contributor: PHID!\n}",
-                            template: "",
-                            reducer: "",
                             errors: [],
                             examples: [],
+                            id: "pkU1fg9dl0SDxHb+294KsqUDMN4=",
+                            name: "EDIT_CONTRIBUTOR",
+                            reducer: "",
+                            schema: "input EditContributorInput {\n  contributor: PHID!\n}",
                             scope: "global",
+                            template: "",
                         },
                         {
-                            id: "sAZCp+O/axy6cbtI/rrV0/A5eMw=",
-                            name: "EDIT_STATUS",
                             description: "",
-                            schema: "input EditStatusInput {\n  status: BillingStatementStatusInput!\n}",
-                            template: "",
-                            reducer: "",
                             errors: [],
                             examples: [],
+                            id: "sAZCp+O/axy6cbtI/rrV0/A5eMw=",
+                            name: "EDIT_STATUS",
+                            reducer: "",
+                            schema: "input EditStatusInput {\n  status: BillingStatementStatusInput!\n}",
                             scope: "global",
+                            template: "",
                         },
                     ],
                 },
                 {
+                    description: "",
                     id: "kNoQafB6U1J4Gq8GrcjRyGhrRvg=",
                     name: "line_items",
-                    description: "",
                     operations: [
                         {
-                            id: "5s+0/bYYzWZd4rOdj53uQ2orOaE=",
-                            name: "ADD_LINE_ITEM",
                             description: "BillingStatementState.totalCash / .totalPowt will be a sum of the line item values.",
-                            schema: "input AddLineItemInput {\n  id: OID!\n  description: String!\n  quantity: Float!\n  unit: BillingStatementUnitInput!\n  unitPricePwt: Float!\n  unitPriceCash: Float!\n  totalPricePwt: Float!\n  totalPriceCash: Float!\n}",
-                            template: "",
-                            reducer: "",
                             errors: [],
                             examples: [],
+                            id: "5s+0/bYYzWZd4rOdj53uQ2orOaE=",
+                            name: "ADD_LINE_ITEM",
+                            reducer: "",
+                            schema: "input AddLineItemInput {\n  id: OID!\n  description: String!\n  quantity: Float!\n  unit: BillingStatementUnitInput!\n  unitPricePwt: Float!\n  unitPriceCash: Float!\n  totalPricePwt: Float!\n  totalPriceCash: Float!\n}",
                             scope: "global",
+                            template: "",
                         },
                         {
+                            description: "BillingStatementState.totalCash / .totalPowt will be a sum of the line item values.",
+                            errors: [],
+                            examples: [],
                             id: "iBzTjNAr/a4NsuxZmy821GoN/NE=",
                             name: "EDIT_LINE_ITEM",
-                            description: "BillingStatementState.totalCash / .totalPowt will be a sum of the line item values.",
+                            reducer: "",
                             schema: "input EditLineItemInput {\n  id: OID!\n  description: String\n  quantity: Float\n  unit: BillingStatementUnitInput\n  unitPricePwt: Float\n  unitPriceCash: Float\n  totalPricePwt: Float\n  totalPriceCash: Float\n}",
+                            scope: "global",
                             template: "",
-                            reducer: "",
+                        },
+                        {
+                            description: "",
                             errors: [],
                             examples: [],
+                            id: "6b6bad0d-ef1c-4aa8-81eb-6ca605bf46b8",
+                            name: "DELETE_LINE_ITEM",
+                            reducer: "",
+                            schema: "input DeleteLineItemInput {\n  id: OID!\n}",
                             scope: "global",
+                            template: "",
                         },
                     ],
                 },
                 {
+                    description: "",
                     id: "jg5q35JaHcb5iNDdFkB2xYYNrDU=",
                     name: "tags",
-                    description: "",
                     operations: [
                         {
-                            id: "k5kMjZ+cO/7fVOPTvyTZ07XMVEA=",
-                            name: "EDIT_LINE_ITEM_TAG",
                             description: "",
-                            schema: "input EditLineItemTagInput {\n  lineItemId: OID!\n  dimension: String!\n  value: String!\n  label: String\n}",
-                            template: "",
-                            reducer: "",
                             errors: [],
                             examples: [],
+                            id: "k5kMjZ+cO/7fVOPTvyTZ07XMVEA=",
+                            name: "EDIT_LINE_ITEM_TAG",
+                            reducer: "",
+                            schema: "input EditLineItemTagInput {\n  lineItemId: OID!\n  dimension: String!\n  value: String!\n  label: String\n}",
                             scope: "global",
+                            template: "",
                         },
                     ],
                 },
             ],
+            state: {
+                global: {
+                    examples: [],
+                    initialValue: '"{\\n  \\"contributor\\": null,\\n  \\"dateIssued\\": \\"2025-06-10T15:42:17.873Z\\",\\n  \\"dateDue\\": \\"2025-06-10T15:42:17.873Z\\",\\n  \\"lineItems\\": [],\\n  \\"status\\": \\"DRAFT\\",\\n  \\"currency\\": \\"\\",\\n  \\"totalCash\\": 0,\\n  \\"totalPowt\\": 0,\\n  \\"notes\\": \\"\\"\\n}"',
+                    schema: "type BillingStatementState {\n  contributor: PHID  # Change to AID when available\n  dateIssued: DateTime!\n  dateDue: DateTime\n  lineItems: [BillingStatementLineItem!]!\n  status: BillingStatementStatus!\n  currency: String!\n  totalCash: Float!\n  totalPowt: Float!\n  notes: String\n}\n\ntype BillingStatementLineItem {\n  id: OID!\n  description: String!\n  quantity: Float!\n  unit: BillingStatementUnit!\n  unitPricePwt: Float!\n  unitPriceCash: Float!\n  totalPricePwt: Float!\n  totalPriceCash: Float!\n  lineItemTag: [BillingStatementTag!]!\n}\n\ntype BillingStatementTag {\n  dimension: String!\n  value: String!\n  label: String\n}\n\nenum BillingStatementStatus {\n  DRAFT\n  ISSUED\n  ACCEPTED\n  REJECTED\n  PAID\n}\n\nenum BillingStatementStatusInput {\n  DRAFT\n  ISSUED\n  ACCEPTED\n  REJECTED\n  PAID\n}\n\nenum BillingStatementUnit {\n  MINUTE\n  HOUR\n  DAY\n  UNIT\n}\n\nenum BillingStatementUnitInput {\n  MINUTE\n  HOUR\n  DAY\n  UNIT\n}\n\n",
+                },
+                local: {
+                    examples: [],
+                    initialValue: '""',
+                    schema: "",
+                },
+            },
+            version: 1,
         },
     ],
 };