@nuxtagentic/google 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+Proprietary software. All rights reserved.
+
+Use of Nuxt Agentic packages and starter materials is governed by the applicable
+commercial agreement supplied with a purchase. This repository does not grant
+an open-source license or permission to redistribute the packages as a competing
+template or module library.
+
+Third-party dependencies retain their respective licenses. This notice does not
+replace or modify those licenses.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# Google connections
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@nuxtagentic/google` owns the shared Google connection lifecycle and authenticated
+server access. It installs Identity and Prompt. Include `googleModels` from
+`@nuxtagentic/google/schema` in the host config to store service preferences.
+
+Workspace features use these Google connections. Integrations (Gmail, Calendar,
+Drive, Analytics, Search Console, Ads) connect through CloudConfig Connect instead,
+with a Google grant separate from sign-in. This shared service remains in the agentic
+starter even though the standalone Calendar, Files, and Emails dashboard modules have
+moved out.
+
+Configure the Google OAuth client with `pnpm exec cloudconfig auth add google`.
+Register `/api/auth/callback/google` for each app origin. Account linking expects
+the same Google email as the signed-in account. Enable the Google provider APIs
+required by the integration actions you choose, such as Gmail, Calendar, or Drive.
+OAuth client secrets and refresh tokens stay on the server.
+
+Use [Integrations](../integrations/README.md) to connect Google accounts for agents,
+choose permission scopes and actions, and [Automations](../automations/README.md) to
+configure triggers. Connecting a service requests its permissions without replacing the
+sign-in session; disconnecting disables the service while retaining Google sign-in.

package/module.ts

@@ -0,0 +1,21 @@
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { registerWorkspaceModule } from '@nuxtagentic/kit'
+
+export default defineNuxtModule({
+  meta: { name: '@nuxtagentic/google' },
+  moduleDependencies: {
+    '@nuxtagentic/identity': {},
+    '@nuxtagentic/prompt': {},
+  },
+  setup(_options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+    registerWorkspaceModule(
+      {
+        id: 'google',
+        runtime: resolver.resolve('./runtime'),
+        metadata: resolver.resolve('./runtime/shared/agent.ts'),
+      },
+      nuxt,
+    )
+  },
+})

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@nuxtagentic/google",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "module.ts",
+    "runtime",
+    "schema.ts",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "exports": {
+    ".": "./module.ts",
+    "./package.json": "./package.json",
+    "./schema": "./schema.ts",
+    "./runtime/*.vue": "./runtime/*.vue",
+    "./runtime/*.css": "./runtime/*.css",
+    "./runtime/*.json": "./runtime/*.json",
+    "./runtime/*.svg": "./runtime/*.svg",
+    "./runtime/*": "./runtime/*.ts"
+  },
+  "dependencies": {
+    "@cloudconfig/core": "0.2.0-beta.2",
+    "@nuxt/kit": "4.6.1",
+    "h3": "1.15.11",
+    "@nuxtagentic/prompt": "0.1.0",
+    "@nuxtagentic/kit": "0.1.0",
+    "@nuxtagentic/identity": "0.1.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.6.1",
+    "vue": "^3.5.43"
+  },
+  "cloudconfig": {
+    "models": "googleModels"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "description": "Google connection lifecycle for Nuxt Agentic.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  }
 }

package/runtime/components/ConnectionSettings.vue

@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import { useGoogleConnection } from '../composables/useGoogleConnection'
+import { useRoute } from '#imports'
+import { ref } from 'vue'
+
+import { getIntegrationErrorMessage, type GoogleService } from '../shared/google'
+
+const { service, name, icon, description } = defineProps<{
+  service: GoogleService
+  name: string
+  icon: string
+  description: string
+}>()
+const connection = useGoogleConnection(() => service)
+const route = useRoute()
+const error = ref('')
+async function disconnect() {
+  error.value = ''
+  try {
+    await connection.disconnect()
+  } catch (cause) {
+    error.value = getIntegrationErrorMessage(cause)
+  }
+}
+</script>
+
+<template>
+  <SettingsSection
+    :title="name"
+    :description="description"
+  >
+    <div class="flex items-center gap-3 py-2">
+      <UIcon
+        :name="icon"
+        class="size-5 shrink-0 text-muted"
+      />
+      <p class="min-w-0 flex-1 text-[13px] text-muted">
+        {{
+          connection.connected.value ? connection.data.value?.email : 'Connect your Google account.'
+        }}
+      </p>
+      <UDropdownMenu
+        v-if="connection.connected.value"
+        :items="[
+          {
+            label: 'Reconnect',
+            icon: 'i-lucide-refresh-cw',
+            onSelect: () => connection.connect('/dashboard/settings#connections'),
+          },
+          { label: 'Disconnect', icon: 'i-lucide-unplug', onSelect: disconnect },
+        ]"
+      >
+        <UButton
+          label="Connected"
+          trailing-icon="i-lucide-chevron-down"
+          variant="outline"
+          size="sm"
+          :loading="connection.connecting.value"
+        />
+      </UDropdownMenu>
+      <UButton
+        v-else
+        :label="connection.data.value?.available === false ? 'Invite only' : 'Connect'"
+        size="sm"
+        :disabled="
+          connection.data.value?.available === false || connection.data.value?.configured === false
+        "
+        :loading="connection.connecting.value"
+        @click="connection.connect('/dashboard/settings#connections')"
+      />
+    </div>
+    <p
+      v-if="error"
+      role="alert"
+      class="text-sm text-error"
+    >
+      {{ error }}
+    </p>
+    <p
+      v-if="route.query.googleError === service"
+      role="alert"
+      class="text-sm text-error"
+    >
+      Google could not connect this account. Use the Google account matching your sign-in email and
+      grant the requested permissions.
+    </p>
+    <slot />
+  </SettingsSection>
+</template>

package/runtime/composables/useGoogleConnection.ts

@@ -0,0 +1,112 @@
+import { useCurrentUser } from '@nuxtagentic/identity/runtime/composables/useCurrentUser'
+import {
+  useCloudConfigAuth,
+  useRequestFetch,
+  useRoute,
+  useToast,
+  useAsyncData,
+  clearNuxtData,
+  useState,
+} from '#imports'
+import { ref, computed, toValue, type MaybeRefOrGetter } from 'vue'
+import {
+  type GoogleService,
+  type GoogleConnection,
+  getIntegrationErrorMessage,
+} from '../shared/google'
+import { GOOGLE_SERVICES } from '#workspace/client'
+
+export function useGoogleConnection(service: MaybeRefOrGetter<GoogleService>) {
+  const settings = computed(() => {
+    const serviceId = toValue(service)
+    const configuration = GOOGLE_SERVICES[serviceId]
+    if (!configuration) {
+      throw new Error(`Google connection "${serviceId}" is not enabled in this application.`)
+    }
+    return { ...configuration, serviceId }
+  })
+  const user = useCurrentUser()
+  const auth = useCloudConfigAuth()
+  const fetch = useRequestFetch()
+  const route = useRoute()
+  const toast = useToast()
+  const connecting = ref(false)
+  const resource = useAsyncData(
+    computed(() => `google:${settings.value.serviceId}:connection:${user.value?.id ?? ''}`),
+    () =>
+      user.value
+        ? fetch<GoogleConnection>(`/api/integrations/google/${settings.value.serviceId}/status`)
+        : Promise.resolve<GoogleConnection>({
+            configured: false,
+            connected: false,
+            needsConsent: true,
+          }),
+    { lazy: true, deep: false, dedupe: 'defer' },
+  )
+  const connected = computed(() => resource.data.value?.connected === true && !resource.error.value)
+
+  async function connect(callbackURL = route.fullPath) {
+    const { serviceId: selectedService, scopes: requestedScopes } = settings.value
+    const reauthorize = connected.value
+    connecting.value = true
+    try {
+      const enabled = await fetch<{ connected: boolean }>(
+        `/api/integrations/google/${selectedService}/connection`,
+        { method: 'POST', body: { enabled: true } },
+      )
+      if (enabled.connected && !reauthorize && !resource.error.value) {
+        await resource.refresh()
+        return true
+      }
+      const accounts = await auth.listAccounts()
+      if (accounts.error) {
+        throw new Error(accounts.error.message)
+      }
+      const scopes = [
+        ...new Set([
+          ...(accounts.data?.find((account) => account.providerId === 'google')?.scopes ?? []),
+          ...requestedScopes,
+        ]),
+      ]
+      const result = await auth.linkSocial({
+        provider: 'google',
+        scopes,
+        callbackURL,
+        errorCallbackURL: `/dashboard/settings?googleError=${selectedService}#connections`,
+        additionalParams: {
+          prompt: 'consent',
+          access_type: 'offline',
+          include_granted_scopes: 'true',
+        },
+      })
+      if (result.error) {
+        throw new Error(result.error.message ?? 'Could not connect Google.')
+      }
+      return false
+    } catch (cause) {
+      toast.add({
+        title: 'Could not connect Google',
+        description: getIntegrationErrorMessage(cause),
+        color: 'error',
+      })
+      return false
+    } finally {
+      connecting.value = false
+    }
+  }
+
+  async function disconnect() {
+    const { serviceId: selectedService, disconnect: cleanup } = settings.value
+    await fetch(`/api/integrations/google/${selectedService}/connection`, {
+      method: 'POST',
+      body: { enabled: false },
+    })
+    await resource.refresh()
+    const prefixes = cleanup?.dataPrefixes ?? []
+    clearNuxtData((key) => prefixes.some((prefix) => key.startsWith(prefix)))
+    for (const prefix of cleanup?.userStatePrefixes ?? []) {
+      useState(`${prefix}${user.value?.id ?? ''}`, () => null).value = null
+    }
+  }
+  return { ...resource, connected, connecting, connect, disconnect }
+}

package/runtime/server/api/integrations/google/[service]/connection.post.ts

@@ -0,0 +1,43 @@
+import { createError, defineEventHandler, getRouterParam, readBody } from 'h3'
+import { googleDisconnectHooks } from '#workspace/server'
+import {
+  getGoogleIntegration,
+  assertGoogleMutation,
+  getGoogleService,
+} from '../../../../utils/google'
+
+export default defineEventHandler(async (event) => {
+  assertGoogleMutation(event)
+  const service = getGoogleService(getRouterParam(event, 'service'))
+  const body = await readBody<{ enabled?: boolean }>(event)
+  if (typeof body?.enabled !== 'boolean') {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Choose whether to enable this connection.',
+    })
+  }
+  const { enabled } = body
+  const { available, unavailableReason, user, record, api, granted } = await getGoogleIntegration(
+    event,
+    service,
+  )
+  if (enabled && !available) {
+    throw createError({ statusCode: 403, statusMessage: unavailableReason })
+  }
+  const input = { enabled, ownerId: user.id }
+  if (record) {
+    await api.googleIntegration.update(record.id, input)
+  } else {
+    await api.googleIntegration.create({
+      ...input,
+      key: `${user.id}:${service}`,
+      service,
+    })
+  }
+  if (!enabled) {
+    for (const disconnect of googleDisconnectHooks) {
+      await disconnect({ event, service, user })
+    }
+  }
+  return { connected: enabled && granted }
+})

package/runtime/server/api/integrations/google/[service]/status.get.ts

@@ -0,0 +1,21 @@
+import { defineEventHandler, getRouterParam } from 'h3'
+import {
+  getGoogleService,
+  getGoogleIntegration,
+  isGoogleConfigured,
+} from '../../../../utils/google'
+export default defineEventHandler(async (event) => {
+  const service = getGoogleService(getRouterParam(event, 'service'))
+  const { connected, granted, available, account, user } = await getGoogleIntegration(
+    event,
+    service,
+  )
+  return {
+    configured: isGoogleConfigured(event),
+    connected,
+    needsConsent: !granted,
+    available,
+    accountId: account?.accountId,
+    email: user.email,
+  }
+})

package/runtime/server/utils/google.ts

@@ -0,0 +1,222 @@
+import { createError, getHeader, getRequestURL, setHeader, type H3Event } from 'h3'
+import { useRuntimeConfig } from '#imports'
+import { useCloudConfigServer } from '#cloudconfig/server'
+import type { GoogleConfig } from '@nuxtagentic/google/schema'
+import type { GoogleService } from '../../shared/google'
+import { GOOGLE_SERVICES, googleAvailabilityHooks, getWorkspaceMetadata } from '#workspace/server'
+
+interface GoogleAccount {
+  id: string
+  accountId: string
+  providerId: string
+  scopes: string[]
+}
+
+export function getGoogleAuthPath(event: H3Event) {
+  return (
+    (useRuntimeConfig(event).public.cloudconfig as { authBasePath?: string })?.authBasePath ??
+    '/api/auth'
+  )
+}
+
+export function isGoogleConfigured(event: H3Event) {
+  const env = event.context.cloudflare?.env as Record<string, unknown> | undefined
+  return !!(
+    (env?.GOOGLE_CLIENT_ID || process.env.GOOGLE_CLIENT_ID) &&
+    (env?.GOOGLE_CLIENT_SECRET || process.env.GOOGLE_CLIENT_SECRET)
+  )
+}
+
+export async function getGoogleContext(event: H3Event) {
+  const cached = event.context.googleConnectionContext as
+    ReturnType<typeof createGoogleContext> | undefined
+  if (cached) {
+    return cached
+  }
+  const context = createGoogleContext(event)
+  event.context.googleConnectionContext = context
+  return context
+}
+
+async function createGoogleContext(event: H3Event) {
+  setHeader(event, 'Cache-Control', 'private, no-store')
+  const session = await event.$fetch<{ user?: { id: string; email: string } } | null>(
+    `${getGoogleAuthPath(event)}/get-session`,
+    { query: { disableCookieCache: true } },
+  )
+  if (!session?.user) {
+    throw createError({ statusCode: 401, statusMessage: 'Sign in to connect Google.' })
+  }
+  const accounts = await event.$fetch<GoogleAccount[]>(`${getGoogleAuthPath(event)}/list-accounts`)
+  const api = await useCloudConfigServer<GoogleConfig>(event)
+  return {
+    api,
+    user: { ...session.user, id: Number(session.user.id) },
+    account: accounts.find((account) => account.providerId === 'google'),
+  }
+}
+
+export async function getGoogleIntegration(event: H3Event, service: GoogleService) {
+  const settings = getWorkspaceMetadata(event.context.workspaceModules as string[] | undefined)
+    .GOOGLE_SERVICES[service]
+  if (!settings) {
+    throw createError({ statusCode: 400, statusMessage: 'Choose an enabled Google connection.' })
+  }
+  const context = await getGoogleContext(event)
+  const rows = await context.api.googleIntegration.list({
+    pageSize: 1,
+    filters: {
+      type: 'group',
+      logic: 'and',
+      children: [
+        { type: 'condition', field: 'key', operator: 'eq', value: `${context.user.id}:${service}` },
+      ],
+    },
+  })
+  const record = rows.data[0]
+  const granted =
+    !!context.account && settings.scopes.every((scope) => context.account!.scopes.includes(scope))
+  let unavailableReason: string | undefined
+  for (const checkAvailability of googleAvailabilityHooks) {
+    unavailableReason = await checkAvailability({ event, service, user: context.user })
+    if (unavailableReason) {
+      break
+    }
+  }
+  const available = !unavailableReason
+  return {
+    ...context,
+    record,
+    granted,
+    available,
+    unavailableReason,
+    connected: available && granted && record?.enabled !== false,
+  }
+}
+
+export async function getGoogleAccessToken(event: H3Event, accountId: string) {
+  const tokens = (event.context.googleAccessTokens ??= new Map<string, Promise<string>>()) as Map<
+    string,
+    Promise<string>
+  >
+  const cached = tokens.get(accountId)
+  if (cached) {
+    return cached
+  }
+  const token = fetchGoogleAccessToken(event, accountId)
+  tokens.set(accountId, token)
+  return token
+}
+
+async function fetchGoogleAccessToken(event: H3Event, accountId: string) {
+  try {
+    const result = await event.$fetch<{ accessToken: string }>(
+      `${getGoogleAuthPath(event)}/get-access-token`,
+      { method: 'POST', body: { accountId } },
+    )
+    if (!result.accessToken) {
+      throw new Error('Missing token')
+    }
+    return result.accessToken
+  } catch {
+    throw createError({
+      statusCode: 401,
+      statusMessage: 'Your Google connection expired. Reconnect to continue.',
+    })
+  }
+}
+
+export async function getGoogleClient(event: H3Event, service: GoogleService) {
+  const context = await getGoogleIntegration(event, service)
+  if (!context.available) {
+    throw createError({ statusCode: 403, statusMessage: context.unavailableReason })
+  }
+  if (!context.connected || !context.account) {
+    throw createError({
+      statusCode: 409,
+      statusMessage: `Connect ${GOOGLE_SERVICES[service]?.label ?? service} to continue.`,
+    })
+  }
+  const accessToken = await getGoogleAccessToken(event, context.account.id)
+  async function request<T>(
+    url: string,
+    options: {
+      method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'
+      body?: Record<string, unknown> | string
+      query?: Record<string, string | number | boolean | string[]>
+      headers?: Record<string, string>
+      responseType?: 'json' | 'arrayBuffer' | 'text'
+    } = {},
+  ): Promise<T> {
+    try {
+      return (await $fetch<T>(url, {
+        ...options,
+        headers: { Authorization: `Bearer ${accessToken}`, ...options.headers },
+        retry: 0,
+        timeout: 30_000,
+      })) as T
+    } catch (cause) {
+      const error = cause as { statusCode?: number; status?: number }
+      const status = error.statusCode ?? error.status ?? 502
+      const message = googleErrorMessages[status] ?? 'Could not reach Google. Please try again.'
+      throw createError({ statusCode: status, statusMessage: message })
+    }
+  }
+  return { ...context, request }
+}
+
+const googleErrorMessages: Record<number, string> = {
+  401: 'Your Google connection expired. Reconnect to continue.',
+  403: 'Google denied access. Check the account permissions and reconnect.',
+  404: 'This item is no longer available in Google.',
+  412: 'This item changed in Google. Refresh it before saving.',
+  429: 'Google is busy. Wait a moment and try again.',
+}
+
+export function assertGoogleMutation(event: H3Event) {
+  const origin = getHeader(event, 'origin')
+  if (origin && origin !== getRequestURL(event).origin) {
+    throw createError({ statusCode: 403, statusMessage: 'Open Google actions from this app.' })
+  }
+}
+
+export function getGoogleService(value: unknown): GoogleService {
+  if (typeof value !== 'string' || !Object.hasOwn(GOOGLE_SERVICES, value)) {
+    throw createError({ statusCode: 400, statusMessage: 'Choose a valid Google connection.' })
+  }
+  return value as GoogleService
+}
+
+export function assertGoogleId(value: unknown) {
+  if (typeof value !== 'string' || !/^[\w-]{1,2048}$/.test(value)) {
+    throw createError({ statusCode: 400, statusMessage: 'Choose a valid Google item.' })
+  }
+  return value
+}
+
+/** The unique key index also bounds user-owned job listings. */
+export function getGoogleOwnerKeys(userId: number) {
+  return [
+    { type: 'condition' as const, field: 'key', operator: 'gte' as const, value: `${userId}:` },
+    { type: 'condition' as const, field: 'key', operator: 'lt' as const, value: `${userId};` },
+  ]
+}
+
+/** Keep large pages from issuing a burst of Google requests. */
+export async function mapWithConcurrency<T, R>(
+  items: T[],
+  map: (item: T) => Promise<R>,
+  concurrency = 4,
+): Promise<R[]> {
+  const results = new Array<R>(items.length)
+  let cursor = 0
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+      while (cursor < items.length) {
+        const index = cursor++
+        results[index] = await map(items[index]!)
+      }
+    }),
+  )
+  return results
+}

package/runtime/shared/agent.ts

@@ -0,0 +1,5 @@
+import type { WorkspaceMetadata } from '@nuxtagentic/prompt/server-contributions'
+
+export default {
+  excludedModels: ['googleIntegration'],
+} satisfies WorkspaceMetadata

package/runtime/shared/google.ts

@@ -0,0 +1,13 @@
+export type GoogleService = 'drive' | 'calendar' | 'gmail'
+export interface GoogleConnection {
+  configured: boolean
+  connected: boolean
+  needsConsent: boolean
+  available?: boolean
+  accountId?: string
+  email?: string
+}
+export function getIntegrationErrorMessage(cause: unknown) {
+  const error = cause as { data?: { statusMessage?: string; message?: string }; message?: string }
+  return error?.data?.statusMessage ?? error?.data?.message ?? error?.message ?? 'Please try again.'
+}

package/schema.ts

@@ -0,0 +1,24 @@
+import { model, t } from '@cloudconfig/core'
+
+export const googleModels = {
+  googleIntegration: model(
+    {
+      key: t.text().required().unique().serverOnly(),
+      service: t.select(['drive', 'calendar', 'gmail']).required(),
+      enabled: t.boolean().default(true).serverOnly(),
+      settings: t.json().serverOnly(),
+      ownerId: t.number().required().serverOnly(),
+    },
+    {
+      access: {
+        list: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        read: ({ user, where }) => (user ? where('ownerId', 'eq', user.id) : false),
+        create: ({ user, input }) => !!user && input?.ownerId === user.id,
+        update: ({ user, input, where }) =>
+          user && input?.ownerId === user.id ? where('ownerId', 'eq', user.id) : false,
+      },
+    },
+  ),
+}
+
+export type GoogleConfig = { models: typeof googleModels }