@superdoc-dev/esign 1.0.0-next.3 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @superdoc-dev/esign
 
-React eSignature component for document signing workflows with SuperDoc.
+React component that wraps SuperDoc for document signing workflows with audit trails and compliance tracking.
 
 ## Installation
 
@@ -11,445 +11,130 @@ npm install @superdoc-dev/esign superdoc
 ## Quick Start
 
 ```jsx
+import React from 'react';
 import SuperDocESign from '@superdoc-dev/esign';
 import 'superdoc/dist/style.css';
 
 function App() {
+  const handleSubmit = async (data) => {
+    // Send to your backend
+    await fetch('/api/sign', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data)
+    });
+    alert('Document signed!');
+  };
+
   return (
     <SuperDocESign
-      eventId="unique-session-id"
+      eventId={`session-${Date.now()}`}
       
       document={{
-        source: "contract.pdf",
-        mode: "full",
-        displayOptions: {
-          scrollRequired: true
-        }
+        source: "https://storage.googleapis.com/public_static_hosting/public_demo_docs/employment_agreement.docx",
+        validation: { scroll: { required: true } }
       }}
       
       fields={{
         document: [
-          { alias: 'company', value: 'Acme Corp' }
+          { id: 'employee_name', value: 'Jane Smith' },
+          { id: 'position', value: 'Senior Engineer' },
+          { id: 'salary', value: '$120,000' }
         ],
         signer: [
           {
             id: 'signature',
             type: 'signature',
             validation: { required: true },
-            label: 'Your Signature'
+            label: 'Type your full name'
+          },
+          {
+            id: 'accept_terms',
+            type: 'checkbox',
+            validation: { required: true },
+            label: 'I accept the terms'
           }
         ]
       }}
       
-      onSubmit={async (data) => {
-        await api.saveSignature(data);
-      }}
+      onSubmit={handleSubmit}
     />
   );
 }
 ```
 
-## API Reference
-
-### Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `eventId` | string | ✓ | Unique identifier for signing session |
-| `document` | object | ✓ | Document configuration |
-| `fields` | object | | Field definitions |
-| `download` | object | | Download button config |
-| `submit` | object | | Submit button config |
-| `onSubmit` | function | ✓ | Submit handler |
-| `onDownload` | function | | Download handler |
-| `onStateChange` | function | | State change handler |
-| `onFieldChange` | function | | Field change handler |
-| `isDisabled` | boolean | | Disable all interactions |
-
-### Document Configuration
-
-```jsx
-document={{
-  source: File | Blob | string,  // Required
-  mode: 'full' | 'download_only' | 'preview',
-  displayOptions: {
-    scrollRequired: boolean,
-    watermark: boolean
-  }
-}}
-```
+## Backend - Create Signed PDF
 
-### Field Reference System
+Use the SuperDoc API to create the final signed document:
 
-Fields can be referenced using either `id` or `alias`:
-
-- **`id`**: System identifier (e.g., "field_123")
-- **`alias`**: Human-readable name (e.g., "customer_name")
-
-This allows the same value to appear multiple places in a document:
-
-```jsx
-// Document template might have:
-// "Dear {{customer_name}},"
-// "Agreement between {{company}} and {{customer_name}}"
-// "Signed by: {{customer_name}}"
-
-fields={{
-  document: [
-    { 
-      alias: 'customer_name',  // Used in document {{customer_name}}
-      value: 'John Doe' 
-    },
-    { 
-      alias: 'company', 
-      value: 'Acme Corp' 
-    },
-    { 
-      id: 'date_field',
-      alias: 'sign_date',  // Can have both id and alias
-      value: '2024-01-15' 
-    }
-  ],
+```javascript
+// Node.js/Express
+app.post('/api/sign', async (req, res) => {
+  const { eventId, auditTrail, documentFields, signerFields } = req.body;
   
-  signer: [
-    {
-      id: 'sig_001',
-      alias: 'signature',  // Document shows {{signature}} 
-      type: 'signature',
-      validation: { required: true }
+  // 1. Fill document fields
+  const annotated = await fetch('https://api.superdoc.dev/v1/annotate', {
+    method: 'POST',
+    headers: { 
+      'Authorization': `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json'
     },
-    {
-      id: 'consent_terms',
-      alias: 'terms_accepted',  // Can reference as {{terms_accepted}}
-      type: 'consent',
-      label: 'I accept the terms'
-    }
-  ]
-}}
-```
-
-**How it works:**
-1. Document fields are injected on load using their id/alias
-2. Signer fields are collected and can replace placeholders using their alias
-3. The same alias can appear multiple times in the document
-4. All instances get the same value
-
-### Field Configuration
-
-```jsx
-fields={{
-  // Values to inject into document
-  document: [
-    { 
-      id: 'field_id',      // Optional
-      alias: 'field_name', // Optional (at least one of id or alias required)
-      value: 'any value' 
-    }
-  ],
+    body: JSON.stringify({
+      document: 'template.docx',
+      fields: [...documentFields, ...signerFields]
+    })
+  });
   
-  // Fields for signer to complete
-  signer: [
-    {
-      id: 'unique_id',     // Required for signer fields
-      alias: 'field_ref',  // Optional alias for document references
-      type: 'signature' | 'consent' | 'checkbox' | 'text',
-      validation: {
-        required: boolean,
-        minLength: number,
-        maxLength: number
-      },
-      label: 'Field Label',
-      component: CustomComponent // Optional - consistent with download/submit!
-    }
-  ]
-}}
-```
-
-### UI Customization
-
-Simple customization:
-```jsx
-download={{
-  fileName: "contract.pdf",
-  label: "Download Contract",
-  variant: "secondary"
-}}
-
-submit={{
-  label: "Sign Document",
-  loadingLabel: "Processing...",
-  variant: "primary"
-}}
-```
-
-Full custom components:
-```jsx
-download={{
-  component: ({ onClick, fileName, isDisabled }) => (
-    <CustomButton onClick={onClick} disabled={isDisabled}>
-      Download {fileName}
-    </CustomButton>
-  )
-}}
-
-submit={{
-  component: ({ onClick, isValid, isDisabled, isSubmitting }) => (
-    <CustomButton 
-      onClick={onClick} 
-      disabled={!isValid || isDisabled}
-    >
-      {isSubmitting ? 'Processing...' : 'Sign & Submit'}
-    </CustomButton>
-  )
-}}
-```
-
-### Custom Field Components
-
-```jsx
-// Custom signature pad component
-const CustomSignaturePad = ({ value, onChange, isDisabled, label }) => (
-  <div className="custom-signature">
-    <label>{label}</label>
-    <canvas 
-      // ... canvas signature implementation
-      onMouseUp={(e) => onChange(canvasDataURL)}
-      style={{ border: '1px solid #000', cursor: 'crosshair' }}
-    />
-  </div>
-);
-
-// Use it in fields
-fields={{
-  signer: [
-    {
-      id: 'signature',
-      type: 'signature',
-      validation: { required: true },
-      component: CustomSignaturePad  // Consistent with download/submit!
-    }
-  ]
-}}
-```
-
-## Examples
-
-### Basic Agreement
-
-```jsx
-<SuperDocESign
-  eventId="session-123"
-  document={{ source: "terms.pdf" }}
-  fields={{
-    signer: [
-      {
-        id: 'accept',
-        type: 'consent',
-        validation: { required: true },
-        label: 'I accept the terms'
-      }
-    ]
-  }}
-  onSubmit={handleSubmit}
-/>
-```
-
-### Employment Offer with Repeated Fields
-
-```jsx
-// Example: Employment offer with repeated fields
-<SuperDocESign
-  eventId="offer-123"
-  
-  document={{
-    source: offerLetter,  // Contains {{employee_name}}, {{salary}}, etc.
-    mode: "full",
-    displayOptions: {
-      scrollRequired: true
-    }
-  }}
-  
-  fields={{
-    document: [
-      { 
-        alias: 'employee_name',  // Appears 5 times in document
-        value: 'Jane Smith' 
-      },
-      { 
-        alias: 'position',       // Appears 3 times
-        value: 'Senior Engineer' 
-      },
-      { 
-        alias: 'salary',         // Appears 2 times
-        value: '$120,000' 
-      },
-      {
-        alias: 'start_date',
-        value: 'February 1, 2024'
-      }
-    ],
-    
-    signer: [
-      {
-        id: 'employee_signature',
-        alias: 'employee_sig',   // {{employee_sig}} in document
-        type: 'signature',
-        validation: { required: true },
-        label: 'Your Signature'
-      },
-      {
-        id: 'accept_offer',
-        alias: 'offer_accepted',
-        type: 'consent',
-        validation: { required: true },
-        label: 'I accept this offer'
-      }
-    ]
-  }}
-  
-  submit={{
-    label: 'Accept Offer'
-  }}
-  
-  onSubmit={handleAcceptOffer}
-/>
-```
-
-### Full Contract with All Features
-
-```jsx
-<SuperDocESign
-  eventId="contract-456"
-  
-  document={{
-    source: serviceAgreement,
-    mode: "full",
-    displayOptions: {
-      scrollRequired: true,
-      watermark: true
-    }
-  }}
-  
-  fields={{
-    document: [
-      { alias: 'client_name', value: 'John Doe' },
-      { alias: 'company', value: 'Acme Corp' },
-      { alias: 'service_type', value: 'Premium Support' },
-      { alias: 'contract_date', value: new Date().toLocaleDateString() }
-    ],
-    signer: [
-      {
-        id: 'client_signature',
-        alias: 'signature',
-        type: 'signature',
-        validation: { required: true },
-        label: 'Your Signature'
-      },
-      {
-        id: 'consent_terms',
-        type: 'consent',
-        validation: { required: true },
-        label: 'I agree to the terms and conditions'
-      },
-      {
-        id: 'consent_privacy',
-        type: 'consent',
-        validation: { required: true },
-        label: 'I acknowledge the privacy policy'
-      },
-      {
-        id: 'email_updates',
-        type: 'checkbox',
-        validation: { required: false },
-        label: 'Send me email updates'
-      }
-    ]
-  }}
-  
-  download={{
-    fileName: 'service_agreement_signed.pdf',
-    label: 'Download Agreement',
-    variant: 'secondary'
-  }}
-  
-  submit={{
-    label: 'Sign Agreement',
-    loadingLabel: 'Processing...',
-    invalidLabel: 'Please complete all required fields',
-    variant: 'success'
-  }}
-  
-  onSubmit={async (data) => {
-    await api.saveSignedContract(data);
-    console.log('Signed by:', data.signerFields);
-  }}
-  
-  onDownload={(blob, fileName) => {
-    console.log('Downloaded:', fileName);
-  }}
+  // 2. Add digital signature
+  const signed = await fetch('https://api.superdoc.dev/v1/sign', {
+    method: 'POST', 
+    headers: { 
+      'Authorization': `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      document: await annotated.blob(),
+      auditTrail: auditTrail
+    })
+  });
   
-  onStateChange={(state) => {
-    console.log('Valid:', state.isValid);
-  }}
+  // 3. Save PDF
+  await saveToStorage(await signed.blob(), `signed_${eventId}.pdf`);
   
-  isDisabled={false}
-/>
+  res.json({ success: true });
+});
 ```
 
-## Progressive Customization
-
-The component supports three levels of customization:
+See [Python, Ruby, and more examples](https://docs.superdoc.dev/solutions/esign/backend).
 
-```jsx
-// Level 1: Use all defaults
-<SuperDocESign 
-  eventId="session-1"
-  document={{ source: "doc.pdf" }} 
-  onSubmit={handleSubmit} 
-/>
-
-// Level 2: Simple customization
-<SuperDocESign
-  eventId="session-2"
-  document={{ source: "doc.pdf" }}
-  submit={{ label: "I Agree", variant: "success" }}
-  download={{ label: "Get Copy" }}
-  onSubmit={handleSubmit}
-/>
+## What You Receive
 
-// Level 3: Full custom components
-<SuperDocESign
-  eventId="session-3"
-  document={{ source: "doc.pdf" }}
-  submit={{ component: CustomSubmitButton }}
-  download={{ component: CustomDownloadButton }}
-  fields={{
-    signer: [{
-      id: 'sig',
-      type: 'signature',
-      component: CustomSignaturePad
-    }]
-  }}
-  onSubmit={handleSubmit}
-/>
+```javascript
+{
+  eventId: "session-123",
+  timestamp: "2024-01-15T10:30:00Z",
+  duration: 45000,
+  documentFields: [
+    { id: "employee_name", value: "Jane Smith" }
+  ],
+  signerFields: [
+    { id: "signature", value: "Jane Smith" },
+    { id: "accept_terms", value: true }
+  ],
+  auditTrail: [
+    { type: "ready", timestamp: "..." },
+    { type: "scroll", timestamp: "..." },
+    { type: "field_change", timestamp: "..." },
+    { type: "submit", timestamp: "..." }
+  ],
+  isFullyCompleted: true
+}
 ```
 
-## TypeScript
-
-Full TypeScript support with exported types:
+## Documentation
 
-```typescript
-import SuperDocESign from '@superdoc-dev/esign';
-import type { 
-  SuperDocESignProps,
-  SubmitData, 
-  SigningState,
-  DocumentField,
-  SignerField,
-  FieldComponentProps
-} from '@superdoc-dev/esign';
-```
+Full docs at [docs.superdoc.dev/solutions/esign](https://docs.superdoc.dev/solutions/esign)
 
 ## License
 
-MIT
+AGPLv3

package/dist/defaults/CheckboxInput.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { FieldComponentProps } from '../types';
+export declare const CheckboxInput: React.FC<FieldComponentProps>;
+//# sourceMappingURL=CheckboxInput.d.ts.map

package/dist/defaults/CheckboxInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckboxInput.d.ts","sourceRoot":"","sources":["../../src/defaults/CheckboxInput.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAoBvD,CAAC"}

package/dist/defaults/SignatureInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SignatureInput.d.ts","sourceRoot":"","sources":["../../src/defaults/SignatureInput.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmB,MAAM,OAAO,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAiDxD,CAAC"}
+{"version":3,"file":"SignatureInput.d.ts","sourceRoot":"","sources":["../../src/defaults/SignatureInput.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAsBxD,CAAC"}

package/dist/defaults/index.d.ts

@@ -1,5 +1,5 @@
 export { SignatureInput } from './SignatureInput';
-export { ConsentCheckbox } from './ConsentCheckbox';
+export { CheckboxInput } from './CheckboxInput';
 export { createDownloadButton } from './DownloadButton';
 export { createSubmitButton } from './SubmitButton';
 //# sourceMappingURL=index.d.ts.map

package/dist/defaults/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/defaults/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/defaults/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-import { default as React } from 'react';
-import { SignatureInput, ConsentCheckbox } from './defaults';
+import { SignatureInput, CheckboxInput } from './defaults';
 import type * as Types from "./types";
 export * from './types';
-export { SignatureInput, ConsentCheckbox };
-declare const SuperDocESign: React.ForwardRefExoticComponent<Types.SuperDocESignProps & React.RefAttributes<any>>;
+export { SignatureInput, CheckboxInput };
+declare const SuperDocESign: import('react').ForwardRefExoticComponent<Types.SuperDocESignProps & import('react').RefAttributes<any>>;
 export default SuperDocESign;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAON,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,KAAK,KAAK,MAAM,SAAS,CAAC;AACtC,OAAO,EACL,cAAc,EACd,eAAe,EAGhB,MAAM,YAAY,CAAC;AAEpB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAI3C,QAAA,MAAM,aAAa,sFA+alB,CAAC;AAIF,eAAe,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,KAAK,KAAK,MAAM,SAAS,CAAC;AACtC,OAAO,EACL,cAAc,EACd,aAAa,EAGd,MAAM,YAAY,CAAC;AAEpB,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC;AAIzC,QAAA,MAAM,aAAa,0GA0alB,CAAC;AAIF,eAAe,aAAa,CAAC"}