Developer Handover Pack

Developer Handover Pack

Contract Generation & Management

Fires the moment a HubSpot deal stage transitions to Closed Won. The agent reads the full deal record, selects the correct contract template from the Google Drive template library based on the deal's service_type field, and merges all variable fields including party names, entity type, start date, fee schedule, and payment terms into a new document copy. If any mandatory field is missing or returns a null value the agent halts, logs the incomplete record, and sends a Gmail flag to the assigned account manager rather than producing a partial draft. Once population is complete the draft is saved to a standardised path in Google Drive and an approval request is dispatched to the responsible manager.

// Input
hubspot.deal.id            : string  // unique deal ID from webhook payload
hubspot.deal.dealname      : string
hubspot.deal.contact.email : string
hubspot.deal.contact.name  : string
hubspot.deal.company.name  : string
hubspot.deal.company.entity_type : string
hubspot.deal.service_type  : string  // used for template selection
hubspot.deal.start_date    : ISO8601 date
hubspot.deal.fee_amount    : number  // USD
hubspot.deal.payment_terms : string
hubspot.deal.jurisdiction  : string

// Output (success path)
gdrive.draft.file_id       : string  // Google Drive file ID of populated draft
gdrive.draft.file_url      : string  // shareable review link
gdrive.draft.file_name     : string  // e.g. DRAFT_AcmeCorp_ServiceAgreement_2025-06-01
gmail.approval_request.sent : boolean
gmail.approval_request.to  : string  // manager email resolved from deal owner

// Output (missing field path)
agent.status               : 'INCOMPLETE_RECORD'
agent.missing_fields       : string[]  // list of null field names
gmail.flag_sent_to         : string  // assigned account manager email

Activated when the manager clicks the approve link embedded in the Gmail approval notification. The agent receives the approval signal, retrieves the draft file from Google Drive, creates a DocuSign envelope using a predefined signing template that auto-places signature and date fields, and dispatches the envelope to the client. DocuSign's built-in reminder rules are configured at envelope creation for Day 3 and Day 5 automated reminders, eliminating all manual chasing. On the 'envelope completed' webhook event from DocuSign, the agent downloads the executed PDF, saves it to the executed-contracts folder in Google Drive with a standardised filename, updates the HubSpot deal record with contract status and file link, and creates a draft invoice in Xero using the fee schedule and payment terms from the deal record.

// On approval (input from manager action)
approval.token             : string  // HMAC-signed token in approval URL
approval.deal_id           : string  // HubSpot deal ID passed in token payload
approval.gdrive_file_id    : string  // draft file ID passed in token payload
approval.approved_by       : string  // manager email
approval.timestamp         : ISO8601 datetime

// Input from Google Drive (retrieved on approval)
gdrive.draft.file_url      : string  // link to approved draft PDF export

// DocuSign envelope creation input
docusign.recipient.name    : string  // from hubspot.deal.contact.name
docusign.recipient.email   : string  // from hubspot.deal.contact.email
docusign.template_id       : string  // predefined DocuSign signing template ID
docusign.reminders         : { day3: true, day5: true }

// Output (envelope sent)
docusign.envelope.id       : string
docusign.envelope.status   : 'sent'

// Output (on DocuSign 'envelope_completed' webhook)
docusign.signed_pdf.url    : string
gdrive.executed.file_id    : string  // filed in /executed-contracts/
gdrive.executed.file_name  : string  // e.g. EXECUTED_AcmeCorp_ServiceAgreement_2025-06-01
hubspot.deal.contract_status : 'Executed'
hubspot.deal.executed_doc_link : string
xero.invoice.id            : string  // draft invoice ID
xero.invoice.status        : 'DRAFT'
xero.invoice.amount_due    : number  // from hubspot.deal.fee_amount
xero.invoice.due_date      : ISO8601 date  // derived from payment_terms

// ============================================================
// CONTRACT GENERATION & MANAGEMENT: END-TO-END DATA FLOW
// ============================================================

// TRIGGER
// HubSpot deal stage webhook fires on transition to 'Closed Won'
INBOUND_WEBHOOK {
  event_type        : 'deal.propertyChange'
  property_name     : 'dealstage'
  property_value    : 'closedwon'
  object_id         : deal.id              // e.g. '123456789'
  occurred_at       : ISO8601 datetime
}

// ============================================================
// AGENT 1: CONTRACT DRAFTING AGENT
// ============================================================

// Step 1: Fetch full deal record from HubSpot
GET hubspot.deals/{deal.id}
  -> deal.dealname
  -> deal.contact.name
  -> deal.contact.email
  -> deal.company.name
  -> deal.company.entity_type
  -> deal.service_type           // key for template lookup
  -> deal.start_date             // ISO8601
  -> deal.fee_amount             // USD float
  -> deal.payment_terms          // e.g. 'Net 30'
  -> deal.jurisdiction
  -> deal.hubspot_owner_id       // used to resolve approver

// Step 2: Guard — null-check mandatory fields
IF ANY OF [contact.name, company.name, service_type,
           start_date, fee_amount, payment_terms] IS NULL:
  agent.status = 'INCOMPLETE_RECORD'
  agent.missing_fields = [<null field names>]
  -> Gmail: flag email to hubspot.deal.owner.email
  -> HALT (no further processing)

// Step 3: Dedupe check
QUERY gdrive /drafts/ WHERE filename CONTAINS deal.id
  IF file_found:
    -> re-send existing approval_request_url to manager
    -> HALT

// Step 4: Resolve template from Notion index
GET notion.database/{TEMPLATE_DB_ID}
  filter: { service_type == deal.service_type }
  -> notion.template_record.gdrive_file_id  // master template file ID

// Step 5: Create draft document copy in Google Drive
POST gdrive.files.copy({
  fileId   : notion.template_record.gdrive_file_id,
  name     : 'DRAFT_{company.name}_{service_type}_{start_date}',
  parents  : [DRAFT_FOLDER_ID]
})
  -> gdrive.draft.file_id
  -> gdrive.draft.file_url

// Step 6: Merge variable fields into draft (Docs API batch update)
POST gdrive.documents/{gdrive.draft.file_id}.batchUpdate
  replaceAllText: {{CONTACT_NAME}}   -> deal.contact.name
  replaceAllText: {{COMPANY_NAME}}   -> deal.company.name
  replaceAllText: {{ENTITY_TYPE}}    -> deal.company.entity_type
  replaceAllText: {{START_DATE}}     -> deal.start_date
  replaceAllText: {{FEE_AMOUNT}}     -> deal.fee_amount
  replaceAllText: {{PAYMENT_TERMS}}  -> deal.payment_terms
  replaceAllText: {{JURISDICTION}}   -> deal.jurisdiction
  replaceAllText: {{SERVICE_TYPE}}   -> deal.service_type

// Step 7: Resolve manager email from HubSpot owner record
GET hubspot.owners/{deal.hubspot_owner_id}
  -> owner.manager_email
  IF owner.manager_email IS NULL:
    -> fallback: credential_store.DEFAULT_APPROVER_EMAIL

// Step 8: Send approval request via Gmail
POST gmail.send({
  to      : manager_email,
  subject : 'Contract ready for approval: {deal.dealname}',
  body    : approval_template with gdrive.draft.file_url,
            approve_url  = orchestration_layer/approve?token={HMAC_TOKEN},
            changes_url  = orchestration_layer/reject?token={HMAC_TOKEN}
})
// HMAC_TOKEN payload: { deal_id, gdrive_file_id, expires_at: now+72h }

// -- AGENT 1 HANDOFF -> HUMAN GATE -> AGENT 2 --

// ============================================================
// HUMAN GATE: MANAGER INTERNAL APPROVAL (STEP 4 - MANUAL)
// ============================================================
// Manager reviews draft at gdrive.draft.file_url
// Manager clicks approve_url or changes_url

// IF changes_url clicked:
//   POST gmail.send to deal.owner.email with manager comment
//   HALT — manual restart required

// IF approve_url clicked:
//   orchestration_layer validates HMAC_TOKEN (expiry + signature)
//   -> approval.token_valid = true
//   -> triggers Signature and Filing Agent

// ============================================================
// AGENT 2: SIGNATURE AND FILING AGENT
// ============================================================

// Step 9: Export approved draft to PDF
GET gdrive.files/{gdrive.draft.file_id}/export?mimeType=application/pdf
  -> draft_pdf.bytes

// Step 10: Create DocuSign envelope
POST docusign.envelopes({
  templateId  : credential_store.DOCUSIGN_TEMPLATE_ID,
  document    : { name: gdrive.draft.file_name, content: draft_pdf.bytes },
  recipients  : [{ name: deal.contact.name, email: deal.contact.email }],
  reminders   : { reminderEnabled: true, reminderDelay: 3,
                  reminderFrequency: 2 }   // Day 3, then Day 5
})
  -> docusign.envelope.id
  -> docusign.envelope.status = 'sent'

// Step 11: Await DocuSign 'envelope_completed' webhook
INBOUND_WEBHOOK docusign.connect {
  event            : 'envelope-completed'
  envelopeId       : docusign.envelope.id
  completedDateTime: ISO8601 datetime
  documents[0].url : signed_pdf.download_url
}

// Step 12: Download signed PDF from DocuSign
GET docusign.envelopes/{envelope.id}/documents/combined
  -> signed_pdf.bytes

// Step 13: File executed contract to Google Drive
// Ensure /executed-contracts/YYYY/MM/ subfolder exists
POST gdrive.files.create (folder if missing)
POST gdrive.files.create({
  name    : 'EXECUTED_{company.name}_{service_type}_{start_date}',
  parents : [EXECUTED_CONTRACTS_FOLDER_ID/YYYY/MM],
  content : signed_pdf.bytes
})
  -> gdrive.executed.file_id
  -> gdrive.executed.file_url

// Step 14: Update HubSpot deal record
PATCH hubspot.deals/{deal.id} ({
  contract_status       : 'Executed',
  contract_executed_link: gdrive.executed.file_url,
  dealstage             : 'Contract Executed'   // confirm custom stage name
})

// Step 15: Create draft invoice in Xero
POST xero.invoices({
  Type        : 'ACCREC',
  Status      : 'DRAFT',
  Contact     : { Name: deal.company.name },
  LineItems   : [{ Description: deal.service_type,
                   UnitAmount : deal.fee_amount,
                   Quantity   : 1 }],
  Date        : deal.start_date,
  DueDate     : start_date + payment_terms_days   // e.g. +30 for Net 30
})
  -> xero.invoice.id
  -> xero.invoice.status = 'DRAFT'

// ============================================================
// FLOW COMPLETE
// deal.contract_status = Executed | invoice created in Xero
// executed PDF filed to Google Drive with standardised name
// ============================================================