Integration and API Spec

Integration and API Spec

Weekly Business Review Automation

Used by Agent 1 (Data Collection Agent). Provides last week's invoiced revenue, payments received, and outstanding accounts receivable via the Xero Accounting API.

// Output fields written to credential / memory store
xero.weekly_invoiced_revenue   : float  // sum of AUTHORISED invoice amounts for the date range
xero.payments_received         : float  // sum of payments applied in the date range
xero.accounts_receivable       : float  // current outstanding AR balance

Used by Agent 1 (Data Collection Agent). Provides open deal count, total pipeline value, deals closed in the last seven days, and stage movement via the HubSpot CRM API v3.

// Output fields written to credential / memory store
hubspot.open_deal_count         : int    // count of deals with stage != closed
hubspot.total_pipeline_value    : float  // sum of amount property on open deals
hubspot.deals_closed_this_week  : int    // deals moved to CLOSED_WON in date range
hubspot.deals_lost_this_week    : int    // deals moved to CLOSED_LOST in date range
hubspot.stage_movement_summary  : object // map of stage_id -> deal count delta

Used by Agent 1 (write) and Agent 2 (read). The master Google Sheet holds weekly data rows, a target thresholds reference tab, and prior-week comparison data. Agent 2 reads from it to generate the narrative.

// Agent 1 write: append row to WeeklyData
sheets.appendRow(GOOGLE_SHEET_ID, 'WeeklyData', [
  week_start_date, invoiced_revenue, payments_received,
  accounts_receivable, open_deal_count, pipeline_value,
  deals_closed, deals_lost, stage_movement_json
])

// Agent 2 read: last row of WeeklyData + full Thresholds tab
sheets.getLastRow(GOOGLE_SHEET_ID, 'WeeklyData')  -> current_week_data
sheets.getRange(GOOGLE_SHEET_ID, 'ThresholdTable') -> threshold_definitions

Used by Agent 3 (Distribution Agent). The standing weekly review deck is updated with new figures and the narrative text by replacing named text placeholders via the Slides API.

// Input from Agent 2 + Agent 1 data
slides_template_id   : string  // from credential store
replacement_map      : object  // { placeholder_key: value } for all {{}} tokens

// Step 1: copy template
drive.copyFile(GOOGLE_SLIDES_TEMPLATE_ID, 'Weekly Review ' + week_start_date, GOOGLE_SLIDES_ARCHIVE_FOLDER_ID)
  -> new_presentation_id : string

// Step 2: batch replace placeholders
slides.batchUpdate(new_presentation_id, replaceAllText(replacement_map))

// Output
slides.new_presentation_url : string  // shared link passed to Gmail and Slack agents

Used by Agent 3 (Distribution Agent). Sends the completed pack link and exception summary to the leadership distribution list using a standardised subject line and body template.

// Input
gmail.to      : GMAIL_DISTRIBUTION_LIST
gmail.from    : GMAIL_SENDER_ADDRESS
gmail.subject : 'Weekly Business Review | ' + week_start_date
gmail.body_html : rendered HTML including slides_new_presentation_url + exception_flags
gmail.body_text : plain-text fallback

// Output
gmail.message_id : string  // stored in WeeklyData row pack_sent_at field

Used by Agent 3 (Distribution Agent). Posts a formatted notification to the leadership channel confirming the pack is ready, with a direct link to the deck and a summary of any flagged metrics.

// Input
slack.channel   : SLACK_CHANNEL_ID
slack.token     : SLACK_BOT_TOKEN
slack.blocks    : BlockKit JSON array
  header.text   : 'Weekly Business Review | ' + week_start_date
  section.text  : 'Pack ready: ' + slides_new_presentation_url
  context.text  : exception_flags OR 'All metrics on target this week.'

// Output
slack.ts        : string  // message timestamp, logged for audit

// Credential store contents — Weekly Business Review automation
// All values are encrypted at rest. Reference by key name only in workflow logic.

// Xero
XERO_OAUTH_CLIENT_ID          : string   // Xero app client ID
XERO_OAUTH_CLIENT_SECRET      : string   // Xero app client secret
XERO_OAUTH_REFRESH_TOKEN      : string   // auto-rotated on each API call
XERO_TENANT_ID                : string   // Xero organisation tenant UUID

// HubSpot
HUBSPOT_PRIVATE_APP_TOKEN     : string   // Bearer token, rotate every 90 days
HUBSPOT_PIPELINE_ID           : string   // CRM pipeline UUID for deal queries
HUBSPOT_STAGE_CLOSED_WON      : string   // Stage ID for Closed Won
HUBSPOT_STAGE_CLOSED_LOST     : string   // Stage ID for Closed Lost

// Google (shared service account for Sheets, Slides, Gmail)
GOOGLE_SERVICE_ACCOUNT_KEY    : json     // full service account key JSON
GOOGLE_SHEET_ID               : string   // master Google Sheet file ID
GOOGLE_SLIDES_TEMPLATE_ID     : string   // blank template presentation ID
GOOGLE_SLIDES_ARCHIVE_FOLDER_ID : string // Drive folder ID for dated copies
GMAIL_SENDER_ADDRESS          : string   // sending address or alias
GMAIL_OAUTH_REFRESH_TOKEN     : string   // only if user OAuth used instead of SA
GMAIL_DISTRIBUTION_LIST       : string   // comma-separated recipient addresses

// Slack
SLACK_BOT_TOKEN               : string   // xoxb- prefixed bot token
SLACK_CHANNEL_ID              : string   // leadership channel ID (not name)

// Orchestration
SCHEDULE_TIMEZONE             : string   // e.g. 'America/New_York'
ALERT_EMAIL                   : string   // support@gofullspec.com (error alerts)