@nuxtagentic/integrations 0.0.0-stage → 0.1.0

package/runtime/server/utils/integration-adapters.ts

@@ -0,0 +1,836 @@
+import { getIntegrationDefinition, getIntegrationToolName } from '../../shared/catalog'
+
+type Input = Record<string, unknown>
+export type Credentials = Record<string, string>
+type Endpoint = {
+  method?: string
+  path: string
+  form?: boolean
+  graphql?: string
+  approval?: boolean
+}
+export type IntegrationAction = Endpoint & {
+  id: string
+  name: string
+  label: string
+  parameters: Record<string, unknown>
+}
+
+// Paths and methods are owned by adapters. Agents never supply an API URL or headers.
+const endpoints: Record<string, Endpoint[]> = {
+  github: [
+    { path: '/user/repos' },
+    { method: 'POST', path: '/repos/{owner}/{repo}/issues/{number}/comments' },
+    { method: 'POST', path: '/repos/{owner}/{repo}/issues' },
+  ],
+  ga: [
+    { method: 'POST', path: '/v1beta/properties/{propertyId}:runReport' },
+    { method: 'POST', path: '/v1beta/properties/{propertyId}:runReport' },
+    { method: 'POST', path: '/v1alpha/properties/{propertyId}/audiences' },
+  ],
+  gsc: [
+    { method: 'POST', path: '/webmasters/v3/sites/{siteUrl}/searchAnalytics/query' },
+    { method: 'POST', path: '/v1/urlInspection/index:inspect' },
+    { method: 'POST', path: '/v3/urlNotifications:publish' },
+  ],
+  gads: [
+    { method: 'POST', path: '/v25/customers/{customerId}/googleAds:search' },
+    { method: 'POST', path: '/v25/customers/{customerId}/campaignBudgets:mutate' },
+    { method: 'POST', path: '/v25/customers/{customerId}/adGroupCriteria:mutate' },
+  ],
+  meta: [
+    { path: '/{accountId}/insights' },
+    { method: 'POST', path: '/{accountId}/campaigns' },
+    { method: 'POST', path: '/{campaignId}' },
+    { method: 'POST', path: '/{adId}' },
+  ],
+  x: [
+    { path: '/12/stats/accounts/{accountId}' },
+    { method: 'POST', path: '/12/accounts/{accountId}/promoted_tweets', form: true },
+    { method: 'PUT', path: '/12/accounts/{accountId}/line_items/{lineItemId}', form: true },
+  ],
+  tiktok: [
+    { path: '/open_api/v1.3/report/integrated/get/' },
+    { method: 'POST', path: '/open_api/v1.3/campaign/update/' },
+    { method: 'POST', path: '/open_api/v1.3/adgroup/status/update/' },
+  ],
+  reddit: [
+    { method: 'POST', path: '/api/v3/ad_accounts/{accountId}/reports' },
+    { method: 'PATCH', path: '/api/v3/campaigns/{campaignId}' },
+  ],
+  stripe: [
+    { path: '/v1/payment_intents' },
+    { method: 'POST', path: '/v1/invoices', form: true },
+    { method: 'POST', path: '/v1/refunds', form: true, approval: true },
+  ],
+  shopify: [
+    {
+      path: '',
+      graphql:
+        'query Orders($first: Int!, $after: String) { orders(first: $first, after: $after) { nodes { id name createdAt displayFinancialStatus totalPriceSet { shopMoney { amount currencyCode } } } pageInfo { hasNextPage endCursor } } }',
+    },
+    {
+      path: '',
+      graphql:
+        'mutation UpdateProduct($product: ProductUpdateInput!) { productUpdate(product: $product) { product { id title } userErrors { field message } } }',
+    },
+    {
+      path: '',
+      graphql:
+        'mutation TagCustomer($id: ID!, $tags: [String!]!) { tagsAdd(id: $id, tags: $tags) { node { id } userErrors { field message } } }',
+    },
+  ],
+  hubspot: [
+    { path: '/crm/v3/objects/contacts' },
+    { method: 'PATCH', path: '/crm/v3/objects/deals/{dealId}' },
+    { method: 'POST', path: '/crm/v3/objects/notes' },
+  ],
+  linear: [
+    {
+      path: '',
+      graphql:
+        'query Issues($first: Int) { issues(first: $first) { nodes { id identifier title url state { name } } } }',
+    },
+    {
+      path: '',
+      graphql:
+        'mutation CreateIssue($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }',
+    },
+    {
+      path: '',
+      graphql:
+        'mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { id identifier title url } } }',
+    },
+  ],
+  vercel: [
+    { path: '/v6/deployments' },
+    { path: '/v3/deployments/{deploymentId}/events' },
+    { method: 'POST', path: '/v10/projects/{projectId}/promote/{deploymentId}' },
+  ],
+  gmail: [
+    { path: '/gmail/v1/users/me/messages' },
+    { method: 'POST', path: '/gmail/v1/users/me/drafts' },
+    { method: 'POST', path: '/gmail/v1/users/me/messages/send' },
+  ],
+  discord: [
+    { path: '/guilds/{guildId}/channels' },
+    { method: 'POST', path: '/channels/{channelId}/messages' },
+  ],
+  intercom: [
+    { path: '/conversations' },
+    { method: 'POST', path: '/conversations/{conversationId}/reply', approval: true },
+    { method: 'POST', path: '/conversations/{conversationId}/tags' },
+  ],
+  notion: [
+    { path: '/v1/pages/{pageId}' },
+    { method: 'POST', path: '/v1/pages' },
+    { method: 'PATCH', path: '/v1/databases/{databaseId}' },
+  ],
+  gcal: [
+    { path: '/calendar/v3/calendars/{calendarId}/events' },
+    { method: 'POST', path: '/calendar/v3/calendars/{calendarId}/events' },
+  ],
+  gdrive: [
+    { path: '/drive/v3/files' },
+    { method: 'POST', path: '/drive/v3/files' },
+    { method: 'PATCH', path: '/drive/v3/files/{fileId}' },
+  ],
+  slack: [{ path: '/conversations.list' }, { method: 'POST', path: '/chat.postMessage' }],
+}
+
+const bases: Record<string, string> = {
+  github: 'https://api.github.com',
+  ga: 'https://analyticsdata.googleapis.com',
+  gsc: 'https://www.googleapis.com',
+  gads: 'https://googleads.googleapis.com',
+  meta: 'https://graph.facebook.com',
+  x: 'https://ads-api.x.com',
+  tiktok: 'https://business-api.tiktok.com',
+  reddit: 'https://ads-api.reddit.com',
+  stripe: 'https://api.stripe.com',
+  hubspot: 'https://api.hubapi.com',
+  linear: 'https://api.linear.app/graphql',
+  vercel: 'https://api.vercel.com',
+  gmail: 'https://gmail.googleapis.com',
+  discord: 'https://discord.com/api/v10',
+  intercom: 'https://api.intercom.io',
+  notion: 'https://api.notion.com',
+  gcal: 'https://www.googleapis.com',
+  gdrive: 'https://www.googleapis.com',
+  slack: 'https://slack.com/api',
+}
+const bodyHints: Record<string, string> = {
+  ga_run_reports:
+    'dateRanges: [{startDate, endDate}], metrics: [{name}], optional dimensions: [{name}].',
+  ga_compare_date_ranges:
+    'Two dateRanges: [{startDate, endDate}, {startDate, endDate}], metrics: [{name}], optional dimensions: [{name}].',
+  ga_create_audiences:
+    'displayName, description, membershipDurationDays, filterClauses with audience filters.',
+  gsc_read_search_performance:
+    'startDate and endDate (YYYY-MM-DD), optional dimensions and rowLimit.',
+  gsc_inspect_urls: 'inspectionUrl and siteUrl.',
+  gsc_request_indexing:
+    'url and type: URL_UPDATED or URL_DELETED. Google restricts eligible indexing content.',
+  gads_read_campaign_stats: 'query: a Google Ads Query Language SELECT query.',
+  gads_adjust_bids_and_budgets:
+    'operations: [{update:{resourceName, amountMicros}}] for a budget, or operations: [{update:{resourceName, cpcBidMicros}}] with resource: bid.',
+  gads_pause_keywords: 'operations: [{update:{resourceName}}]. The server enforces PAUSED status.',
+  meta_create_campaigns:
+    'name, objective, special_ad_categories and optional status. Use PAUSED to create a draft campaign.',
+  meta_adjust_budgets: 'daily_budget or lifetime_budget in the account currency’s minor units.',
+  meta_pause_ads: 'An empty object. The server enforces PAUSED status.',
+  x_create_promoted_posts: 'line_item_id and tweet_ids.',
+  x_adjust_bids: 'bid_amount_local_micro and optional bid_type.',
+  tiktok_adjust_budgets: 'campaign_id and budget.',
+  tiktok_pause_ad_groups: 'adgroup_ids. The server enforces DISABLE status.',
+  reddit_read_campaign_stats: 'data: {starts_at, ends_at, fields, breakdowns}.',
+  reddit_adjust_budgets:
+    'data: {goal_value, spend_cap}, in microcurrency. goal_value requires a campaign with budget optimization enabled.',
+  stripe_create_invoices:
+    'customer and optional collection_method, days_until_due, description. Returns a draft invoice.',
+  stripe_issue_refunds:
+    'payment_intent or charge, optional amount and reason. Requires owner approval before execution.',
+  hubspot_update_deal_stages: 'properties: {dealstage}.',
+  hubspot_log_activity: 'properties: {hs_timestamp, hs_note_body}, optional associations.',
+  discord_post_messages:
+    'content, optional allowed_mentions. The bot needs permission to send in the selected channel.',
+  intercom_draft_replies:
+    'body: the reply text, admin_id: the sender ID. Creates an approval draft; approval sends the reply.',
+  intercom_tag_conversations: 'id: tag ID, admin_id: sender ID.',
+  gcal_create_events:
+    'summary, start: {dateTime, timeZone}, end: {dateTime, timeZone}, optional attendees.',
+  gdrive_create_files: 'name, mimeType and optional parents. Creates a file or folder.',
+  gdrive_move_files:
+    'An empty object. Supply query.addParents and query.removeParents with folder IDs.',
+}
+
+const providerBodyHints: Record<string, string> = {
+  gmail: 'Email fields: to, subject, text, optional threadId.',
+  slack: 'channel and text.',
+}
+
+const verificationPaths: Record<string, string> = {
+  github: '/user',
+  ga: '/v1beta/accountSummaries',
+  gsc: '/webmasters/v3/sites',
+  gads: '/v25/customers:listAccessibleCustomers',
+  meta: '/me',
+  x: '/12/accounts',
+  tiktok: '/open_api/v1.3/advertiser/info/',
+  reddit: '/api/v3/me',
+  stripe: '/v1/account',
+  hubspot: '/account-info/v3/details',
+  vercel: '/v2/user',
+  gmail: '/gmail/v1/users/me/profile',
+  discord: '/users/@me',
+  intercom: '/me',
+  notion: '/v1/users/me',
+  gcal: '/calendar/v3/users/me/calendarList',
+  gdrive: '/drive/v3/about',
+  slack: '/auth.test',
+}
+
+const verificationQueries: Record<string, string> = {
+  linear: 'query { viewer { id name email } }',
+  shopify: 'query { shop { name myshopifyDomain } }',
+}
+
+/** Builds the agent-facing tool definitions for every action an integration exposes. */
+export function listIntegrationActions(provider: string): IntegrationAction[] {
+  const definition = getIntegrationDefinition(provider)
+  return (endpoints[provider] ?? []).map((endpoint, index) => {
+    const action = definition!.actions[index]!
+    const toolName = getIntegrationToolName(provider, action.id)
+    const pathFields = [...endpoint.path.matchAll(/\{(\w+)\}/g)].map((match) => match[1]!)
+    const properties: Record<string, unknown> = Object.fromEntries(
+      pathFields.map((field) => [
+        field,
+        { type: 'string', description: `The provider's ${field}.` },
+      ]),
+    )
+    // Google Ads falls back to the connected customer and calendars default to "primary".
+    const required = pathFields.filter(
+      (field) => !(provider === 'gads' && field === 'customerId') && field !== 'calendarId',
+    )
+    if (endpoint.graphql) {
+      properties.body = {
+        type: 'object',
+        description:
+          'GraphQL variables. Shopify Orders: first, after; UpdateProduct: product; TagCustomer: id, tags. Linear: first, input, or id and input.',
+      }
+      required.push('body')
+    } else if (endpoint.method && endpoint.method !== 'GET') {
+      properties.body = {
+        type: 'object',
+        description:
+          bodyHints[toolName] ??
+          providerBodyHints[provider] ??
+          `JSON fields accepted by ${definition!.name} for ${action.label}.`,
+      }
+      required.push('body')
+    }
+    properties.query = {
+      type: 'object',
+      description: 'Optional provider query parameters, including filters and pagination.',
+    }
+    if (provider === 'gmail' && index === 0) {
+      properties.messageId = {
+        type: 'string',
+        description:
+          'Read a specific message with full headers and content. Omit to list messages.',
+      }
+    }
+    if (provider === 'gads' && index === 1) {
+      properties.resource = {
+        type: 'string',
+        enum: ['budget', 'bid'],
+        description: 'Choose campaign budget (default) or ad-group CPC bid updates.',
+      }
+    }
+    return {
+      ...endpoint,
+      ...action,
+      name: toolName,
+      parameters: { type: 'object', properties, required, additionalProperties: false },
+    }
+  })
+}
+
+/**
+ * Calls a cheap read-only endpoint to prove the credentials work.
+ *
+ * @returns The account name to show on the connection card.
+ */
+export async function verifyIntegration(provider: string, credentials: Credentials) {
+  const graphql = verificationQueries[provider]
+  const response = graphql
+    ? await sendProviderRequest({
+        provider,
+        credentials,
+        endpoint: { graphql, path: '' },
+        input: { body: {} },
+      })
+    : await sendProviderRequest({
+        provider,
+        credentials,
+        endpoint: { path: verificationPaths[provider] ?? '/', method: 'GET' },
+        input: { query: getVerificationQuery(provider, credentials) },
+      })
+  const value = toRecord(response)
+  const data = toRecord(value.data)
+  return String(
+    value.login ??
+      value.emailAddress ??
+      value.name ??
+      value.account_name ??
+      toRecord(value.user).name ??
+      toRecord(data.shop).name ??
+      toRecord(data.viewer).name ??
+      toRecord(data.user).display_name ??
+      value.team ??
+      getIntegrationDefinition(provider)!.name,
+  )
+}
+
+function getVerificationQuery(provider: string, credentials: Credentials): Input {
+  if (provider === 'gdrive') {
+    return { fields: 'user' }
+  }
+  if (provider === 'tiktok') {
+    return { advertiser_ids: [credentials.advertiserId] }
+  }
+  return {}
+}
+
+export interface ProviderRequestOptions {
+  signal?: AbortSignal
+  /** Lets the provider deduplicate retried writes. Only Stripe honours it today. */
+  idempotencyKey?: string
+}
+
+/** Runs one catalog action against the provider API with the stored credentials. */
+export async function executeIntegrationAction(
+  provider: string,
+  actionId: string,
+  { credentials, input }: { credentials: Credentials; input: Input },
+  options: ProviderRequestOptions = {},
+) {
+  const action = listIntegrationActions(provider).find((entry) => entry.id === actionId)
+  if (!action) {
+    throw new Error('Choose an action supported by this integration.')
+  }
+  const query = getActionQuery(provider, action, toRecord(input.query))
+  const parameters = {
+    ...input,
+    body: getActionBody(provider, actionId, toRecord(input.body)),
+    query:
+      provider === 'vercel' && actionId === 'read_build_logs' ? { ...query, follow: 0 } : query,
+  }
+  const endpoint = getActionEndpoint(provider, action, input, credentials)
+  const result = await sendProviderRequest(
+    { provider, credentials, endpoint, input: parameters },
+    options,
+  )
+
+  // These read actions combine two listings into a single tool result.
+  if (provider === 'stripe' && actionId === 'read_payments_and_customers') {
+    const customers = await sendProviderRequest(
+      { provider, credentials, endpoint: { path: '/v1/customers' }, input },
+      { signal: options.signal },
+    )
+    return { payments: result, customers }
+  }
+  if (provider === 'hubspot' && actionId === 'read_contacts_and_deals') {
+    const deals = await sendProviderRequest(
+      { provider, credentials, endpoint: { path: '/crm/v3/objects/deals' }, input },
+      { signal: options.signal },
+    )
+    return { contacts: result, deals }
+  }
+  return result
+}
+
+/** Write actions only forward the query parameters their provider documents. */
+function getActionQuery(provider: string, action: IntegrationAction, query: Input) {
+  const isWrite = (action.method && action.method !== 'GET') || action.graphql
+  if (!isWrite) {
+    return query
+  }
+  const allowedKeys =
+    provider === 'gdrive' && action.id === 'move_files'
+      ? ['addParents', 'removeParents', 'fields', 'supportsAllDrives']
+      : ['teamId']
+  return pick(query, allowedKeys)
+}
+
+function getActionEndpoint(
+  provider: string,
+  action: IntegrationAction,
+  input: Input,
+  credentials: Credentials,
+): Endpoint {
+  // Installation tokens list the installation's repositories, not a user's.
+  if (
+    provider === 'github' &&
+    action.id === 'read_repositories' &&
+    credentials.githubInstallation
+  ) {
+    return { path: '/installation/repositories' }
+  }
+  if (provider === 'gmail' && action.id === 'read_email' && input.messageId) {
+    return { path: '/gmail/v1/users/me/messages/{messageId}' }
+  }
+  if (provider === 'gads' && action.id === 'adjust_bids_and_budgets' && input.resource === 'bid') {
+    return { ...action, path: '/v25/customers/{customerId}/adGroups:mutate' }
+  }
+  return action
+}
+
+interface ProviderRequest {
+  provider: string
+  credentials: Credentials
+  endpoint: Endpoint
+  input: Input
+}
+
+async function sendProviderRequest(
+  { provider, credentials, endpoint, input }: ProviderRequest,
+  { signal, idempotencyKey }: ProviderRequestOptions = {},
+) {
+  const url = buildRequestUrl(provider, credentials, endpoint, input)
+  const method = endpoint.graphql ? 'POST' : (endpoint.method ?? 'GET')
+  const body = buildRequestBody(provider, credentials, endpoint, input)
+  const headers = buildRequestHeaders(provider, credentials)
+  if (provider === 'x') {
+    headers.Authorization = await signOAuth1Request(
+      method,
+      url,
+      credentials,
+      endpoint.form ? encodeFormData(body) : undefined,
+    )
+  }
+  let encodedBody: string | URLSearchParams | undefined
+  if (method !== 'GET') {
+    headers['Content-Type'] = endpoint.form
+      ? 'application/x-www-form-urlencoded'
+      : 'application/json'
+    encodedBody = endpoint.form
+      ? encodeFormData(body)
+      : JSON.stringify(endpoint.graphql ? { query: endpoint.graphql, variables: body } : body)
+  }
+  if (provider === 'stripe' && idempotencyKey && method === 'POST') {
+    headers['Idempotency-Key'] = idempotencyKey
+  }
+  const response = await fetch(url, {
+    method,
+    headers,
+    body: encodedBody,
+    signal: signal ?? AbortSignal.timeout(30000),
+    redirect: 'error',
+  })
+  const providerName = getIntegrationDefinition(provider)!.name
+  if (!response.ok) {
+    throw new Error(
+      `${providerName} returned ${response.status}. Check the account, token permissions, and action parameters.`,
+    )
+  }
+  const result = await readJson(response)
+  assertProviderAccepted(provider, toRecord(result))
+  return result
+}
+
+function getBaseUrl(provider: string, credentials: Credentials, path: string) {
+  if (provider === 'shopify') {
+    const shop = credentials.shop?.replace(/^https:\/\//, '').replace(/\/$/, '')
+    if (!shop || !/^[a-z0-9][a-z0-9-]*\.myshopify\.com$/.test(shop)) {
+      throw new Error('Enter your store.myshopify.com domain.')
+    }
+    return `https://${shop}/admin/api/2026-07/graphql.json`
+  }
+  const base = bases[provider]
+  if (!base) {
+    throw new Error('This integration has no adapter.')
+  }
+  // Some Google products split their API across hosts by version.
+  if (provider === 'ga' && (path.includes('/audiences') || path === '/v1beta/accountSummaries')) {
+    return 'https://analyticsadmin.googleapis.com'
+  }
+  if (provider === 'gsc' && path.startsWith('/v1/')) {
+    return 'https://searchconsole.googleapis.com'
+  }
+  if (provider === 'gsc' && path.startsWith('/v3/')) {
+    return 'https://indexing.googleapis.com'
+  }
+  return base
+}
+
+function buildRequestUrl(
+  provider: string,
+  credentials: Credentials,
+  endpoint: Endpoint,
+  input: Input,
+) {
+  const path = endpoint.path.replace(/\{(\w+)\}/g, (_match, name: string) => {
+    const value =
+      input[name] ?? credentials[name] ?? (name === 'calendarId' ? 'primary' : undefined)
+    if (typeof value !== 'string' && typeof value !== 'number') {
+      throw new Error(`Provide ${name} for this action.`)
+    }
+    return encodeURIComponent(String(value))
+  })
+  const url = new URL(getBaseUrl(provider, credentials, endpoint.path) + path)
+  for (const [key, value] of Object.entries(toRecord(input.query))) {
+    if (value != null) {
+      url.searchParams.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value))
+    }
+  }
+  const isTiktokRead = provider === 'tiktok' && !endpoint.method
+  if (isTiktokRead && credentials.advertiserId && !url.searchParams.has('advertiser_id')) {
+    url.searchParams.set('advertiser_id', credentials.advertiserId)
+  }
+  return url
+}
+
+function buildRequestHeaders(provider: string, credentials: Credentials) {
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    Authorization: `Bearer ${credentials.token}`,
+    'User-Agent': 'nuxt-agentic-integrations',
+  }
+  switch (provider) {
+    case 'github':
+      headers['X-GitHub-Api-Version'] = '2022-11-28'
+      break
+    case 'gads':
+      headers['developer-token'] = credentials.developerToken ?? ''
+      if (credentials.loginCustomerId) {
+        headers['login-customer-id'] = credentials.loginCustomerId
+      }
+      break
+    case 'tiktok':
+      headers['Access-Token'] = credentials.token ?? ''
+      delete headers.Authorization
+      break
+    case 'shopify':
+      headers['X-Shopify-Access-Token'] = credentials.token ?? ''
+      delete headers.Authorization
+      break
+    case 'discord':
+      headers.Authorization = `Bot ${credentials.token}`
+      break
+    case 'intercom':
+      headers['Intercom-Version'] = '2.14'
+      break
+    case 'notion':
+      headers['Notion-Version'] = '2022-06-28'
+      break
+  }
+  return headers
+}
+
+function buildRequestBody(
+  provider: string,
+  credentials: Credentials,
+  endpoint: Endpoint,
+  input: Input,
+): Input {
+  const body = toRecord(input.body)
+  const method = endpoint.graphql ? 'POST' : (endpoint.method ?? 'GET')
+  if (provider === 'gmail' && method === 'POST') {
+    const message = {
+      raw: encodeRawEmail(body),
+      ...(body.threadId ? { threadId: body.threadId } : {}),
+    }
+    return endpoint.path.endsWith('/drafts') ? { message } : message
+  }
+  if (provider === 'intercom' && endpoint.path.endsWith('/reply')) {
+    return { ...body, message_type: 'comment', type: 'admin' }
+  }
+  if (provider === 'tiktok' && credentials.advertiserId) {
+    return { ...body, advertiser_id: credentials.advertiserId }
+  }
+  return body
+}
+
+/** Some providers report failures inside a 200 response. */
+function assertProviderAccepted(provider: string, value: Input) {
+  const providerName = getIntegrationDefinition(provider)!.name
+  const hasTiktokError = provider === 'tiktok' && value.code !== 0 && value.code !== undefined
+  if (value.ok === false || hasTiktokError || Array.isArray(value.errors)) {
+    throw new Error(
+      `${providerName} could not complete this action. Check its permissions and parameters.`,
+    )
+  }
+  // GraphQL mutations return user errors next to a successful status.
+  for (const payload of Object.values(toRecord(value.data))) {
+    const userErrors = toRecord(payload).userErrors
+    if (Array.isArray(userErrors) && userErrors.length) {
+      throw new Error(`${providerName} rejected these action parameters.`)
+    }
+  }
+}
+
+function toRecord(value: unknown): Input {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Input) : {}
+}
+
+function pick(value: Input, keys: string[]) {
+  return Object.fromEntries(
+    keys.filter((key) => value[key] !== undefined).map((key) => [key, value[key]]),
+  )
+}
+
+/** Narrows agent input to the fields each write action may change. */
+function getActionBody(provider: string, action: string, body: Input): Input {
+  if (provider === 'meta' && action === 'pause_ads') {
+    return { status: 'PAUSED' }
+  }
+  if (provider === 'meta' && action === 'adjust_budgets') {
+    return pick(body, ['daily_budget', 'lifetime_budget'])
+  }
+  if (provider === 'x' && action === 'adjust_bids') {
+    return pick(body, ['bid_amount_local_micro', 'bid_type'])
+  }
+  if (provider === 'tiktok' && action === 'pause_ad_groups') {
+    return { adgroup_ids: body.adgroup_ids, operation_status: 'DISABLE' }
+  }
+  if (provider === 'tiktok' && action === 'adjust_budgets') {
+    return pick(body, ['campaign_id', 'budget'])
+  }
+  if (provider === 'hubspot' && action === 'update_deal_stages') {
+    return { properties: { dealstage: toRecord(body.properties).dealstage } }
+  }
+  if (provider === 'linear' && action === 'update_status') {
+    return { id: body.id, input: { stateId: toRecord(body.input).stateId } }
+  }
+  if (provider === 'gdrive' && action === 'move_files') {
+    return {}
+  }
+  if (provider === 'gads' && action === 'pause_keywords') {
+    return {
+      operations: toArray(body.operations).map((operation) => ({
+        update: {
+          resourceName: toRecord(toRecord(operation).update).resourceName,
+          status: 'PAUSED',
+        },
+        updateMask: 'status',
+      })),
+    }
+  }
+  if (provider === 'gads' && action === 'adjust_bids_and_budgets') {
+    return {
+      operations: toArray(body.operations).map((operation) => {
+        const update = pick(toRecord(toRecord(operation).update), [
+          'resourceName',
+          'amountMicros',
+          'cpcBidMicros',
+        ])
+        return {
+          update,
+          updateMask: update.cpcBidMicros !== undefined ? 'cpc_bid_micros' : 'amount_micros',
+        }
+      }),
+    }
+  }
+  if (provider === 'reddit' && action === 'adjust_budgets') {
+    return { data: pick(toRecord(body.data), ['goal_value', 'spend_cap']) }
+  }
+  return body
+}
+
+function toArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+/** Encodes nested objects with bracket keys (`a[b]=c`), as Stripe and X expect. */
+function encodeFormData(value: Input, prefix = '', form = new URLSearchParams()) {
+  for (const [key, item] of Object.entries(value)) {
+    const name = prefix ? `${prefix}[${key}]` : key
+    if (item !== null && typeof item === 'object') {
+      encodeFormData(item as Input, name, form)
+    } else if (item !== undefined) {
+      form.set(name, String(item))
+    }
+  }
+  return form
+}
+
+/** Builds the base64url RFC 2822 message Gmail's send and draft endpoints require. */
+function encodeRawEmail(body: Input) {
+  const to = String(body.to ?? '')
+  const subject = String(body.subject ?? '')
+  // Line breaks would let input inject extra headers.
+  if (!to || /[\r\n]/.test(to + subject)) {
+    throw new Error('Provide a recipient and a subject without line breaks.')
+  }
+  const encodedSubject = encodeBase64(new TextEncoder().encode(subject))
+  const message = [
+    `To: ${to}`,
+    `Subject: =?UTF-8?B?${encodedSubject}?=`,
+    'MIME-Version: 1.0',
+    'Content-Type: text/plain; charset=UTF-8',
+    '',
+    String(body.text ?? ''),
+  ].join('\r\n')
+  return encodeBase64(new TextEncoder().encode(message))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+}
+
+function encodeBase64(bytes: Uint8Array) {
+  return btoa(String.fromCharCode(...bytes))
+}
+
+const maxResponseBytes = 2_000_000
+
+/**
+ * Reads a JSON or NDJSON response, refusing bodies large enough to flood an agent's context.
+ */
+export async function readJson(response: Response) {
+  if (!response.body) {
+    return null
+  }
+  const text = new TextDecoder().decode(await readLimitedBody(response.body))
+  if (!text) {
+    return null
+  }
+  if (response.headers.get('content-type')?.includes('ndjson')) {
+    return text
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as unknown)
+  }
+  return JSON.parse(text) as unknown
+}
+
+async function readLimitedBody(stream: ReadableStream<Uint8Array>) {
+  const reader = stream.getReader()
+  const chunks: Uint8Array[] = []
+  let length = 0
+  while (true) {
+    const { value, done } = await reader.read()
+    if (done) {
+      break
+    }
+    length += value.length
+    if (length > maxResponseBytes) {
+      await reader.cancel()
+      throw new Error('The result is too large. Use a smaller date range or page size.')
+    }
+    chunks.push(value)
+  }
+  const bytes = new Uint8Array(length)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.length
+  }
+  return bytes
+}
+
+/** RFC 3986 encoding, which OAuth 1.0a requires instead of `encodeURIComponent`'s. */
+function encodeOAuthValue(value: string) {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  )
+}
+
+function compareOAuthPairs([leftKey, leftValue]: string[], [rightKey, rightValue]: string[]) {
+  if (leftKey !== rightKey) {
+    return leftKey! < rightKey! ? -1 : 1
+  }
+  if (leftValue === rightValue) {
+    return 0
+  }
+  return leftValue! < rightValue! ? -1 : 1
+}
+
+/** Signs a request with OAuth 1.0a HMAC-SHA1, which the X Ads API still requires. */
+async function signOAuth1Request(
+  method: string,
+  url: URL,
+  credentials: Credentials,
+  form?: URLSearchParams,
+) {
+  const parameters: Record<string, string> = {
+    oauth_consumer_key: credentials.consumerKey ?? '',
+    oauth_token: credentials.token ?? '',
+    oauth_nonce: crypto.randomUUID(),
+    oauth_timestamp: String(Math.floor(Date.now() / 1000)),
+    oauth_signature_method: 'HMAC-SHA1',
+    oauth_version: '1.0',
+  }
+  const normalizedParameters = [
+    ...Object.entries(parameters),
+    ...url.searchParams.entries(),
+    ...(form?.entries() ?? []),
+  ]
+    .map(([key, value]) => [encodeOAuthValue(key), encodeOAuthValue(value)])
+    .sort(compareOAuthPairs)
+    .map(([key, value]) => `${key}=${value}`)
+    .join('&')
+  const signatureBase = [
+    method,
+    encodeOAuthValue(url.origin + url.pathname),
+    encodeOAuthValue(normalizedParameters),
+  ].join('&')
+  const signingKey = [credentials.consumerSecret ?? '', credentials.tokenSecret ?? '']
+    .map(encodeOAuthValue)
+    .join('&')
+  const key = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(signingKey),
+    { name: 'HMAC', hash: 'SHA-1' },
+    false,
+    ['sign'],
+  )
+  const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(signatureBase))
+  parameters.oauth_signature = encodeBase64(new Uint8Array(signature))
+  const header = Object.entries(parameters)
+    .map(([key, value]) => `${encodeOAuthValue(key)}="${encodeOAuthValue(value)}"`)
+    .join(', ')
+  return `OAuth ${header}`
+}