md / _PRD / _internal / appscript / appscript.apis.md
Molino⺢Pro

appscript.apis

Master Codebase Guidebook
Markdown + HTML Dev-Docs Renderer - Frontend Client Module

Default Index
Open README.md
Root: README.mdappscript
Milestones
⬆ Parent folder📁 archive📝 appscript-office-server-firstLoop📝 appscript.apis📝 office-server-plan📝 README

Yes. That is the right generic tool layer.

What you want now is a two-tier tool architecture:

Tier 1 — generic deployed Apps Script tools

These are reusable capability endpoints, not tied to any one entity.

Gmail • sendEmail • listEmails • getEmail • getAttachment • createDraft • replyEmail

Docs • createDoc • getDoc • appendDocContent • replaceDocContent • insertDocSections • exportDocPdf

Sheets • createSheet • appendRows • getRows • updateRows • findRows • logActivity

Calendar • createEvent • updateEvent • listEvents • getEvent • attachFileToEvent • createReminderEvent

Drive • createFile • copyFile • moveFile • shareFile • listFiles • exportFilePdf

⸻

Tier 2 — app-level orchestrators in your Next app

These are your real business actions.

Examples: • createTripAgendaAndInviteGuests • publishOfferAsPdfAndEmail • logMeetingAndCreateFollowup • buildClientBriefAndShare • createTripDaySchedule • sendPostSessionSummary

These should call the generic GAS endpoints through your own server actions.

⸻

Correct authority split

Apps Script • external Google Workspace executor • thin atomic actions • no business logic beyond validation and execution

Next server actions • business orchestration • entity-aware logic • document/trip/product/offer context • permissions • persistence in Prisma • revalidation

UI / toolbar / sections • intent launchers only • no direct Google logic • no secrets • no business rules

⸻

Best endpoint shape

Use one stable wrapper per tool, not many ad hoc routes.

Recommended pattern

POST /api/tools/google/gmail/send POST /api/tools/google/docs/create POST /api/tools/google/docs/export-pdf POST /api/tools/google/sheets/append POST /api/tools/google/calendar/create POST /api/tools/google/drive/share

Or if GAS is the executor:

POST /api/tools/google/run

with payload:

{ tool: "docs.create", input: { title: "Weekly Summary", content: "..." } }

But for maintainability, the first option is better.

⸻

Recommended atomic contract

Each endpoint should be: • single responsibility • deterministic • idempotent where possible • return machine-usable data • safe to call from document/trip/product flows

Example:

type CreateDocInput = { title: string; content?: string; folderId?: string; };

type CreateDocResult = { ok: true; documentId: string; url: string; };

⸻

What to build first

Build these first, in this order:

Round 1 • sendEmail • createDoc • appendDocContent • exportDocPdf • createEvent • appendRows • shareFile

Round 2 • listEvents • getRows • listFiles • createDraft • updateEvent • findRows

Round 3 • replyEmail • attachFileToEvent • copyFile • moveFile • replaceDocContent

That gives you the highest practical 20/80 coverage.

⸻

How this maps to your document system

A document toolbar command should never call Gmail/Docs/Calendar directly from UI.

Instead:

Toolbar click → Next server action → optional Prisma save / context resolution → generic GAS endpoint → store returned ids/links/meta in document/project/trip → revalidatePath

Example:

"Create meeting doc + invite" → createMeetingPackAction() → createDoc() → exportDocPdf() → createEvent() → sendEmail() → logActivity()

⸻

Generic metadata you should persist

Whenever one of these tools runs, persist traceability in your entities:

meta: { externalRefs: { googleDocId?: string; googleSheetId?: string; googleFileId?: string; googleCalendarEventId?: string; gmailMessageId?: string; }; }

That will matter later for: • updates • retries • exports • auditing • AI-assisted follow-up actions

⸻

Best fit for your toolbar and sidebar

Toolbar

Direct production commands: • Export PDF • Create Meeting • Send Summary • Share Doc • Schedule Event • Publish Offer • Trip Agenda

Sidebar tools

Context builders: • assistants • trip planner • product planner • experience planner • doc list • folders

So: • sidebar = compose intent • toolbar = execute intent • server action = orchestrate • GAS = perform Google side effects

⸻

Minimal deployment principle

Do not deploy 30 endpoints first.

Deploy 7 stable primitives first: • docs.create • docs.exportPdf • gmail.send • calendar.create • sheets.append • drive.share • drive.list

Then wire them into one or two real app flows.

⸻

Recommended folder structure

In your app:

app/(api)/tools/google/docs/create/route.ts app/(api)/tools/google/docs/export-pdf/route.ts app/(api)/tools/google/gmail/send/route.ts app/(api)/tools/google/calendar/create/route.ts app/(api)/tools/google/sheets/append/route.ts app/(api)/tools/google/drive/share/route.ts

In Apps Script:

doPost(e) handleDocsCreate(payload) handleDocsExportPdf(payload) handleGmailSend(payload) handleCalendarCreate(payload) handleSheetsAppend(payload) handleDriveShare(payload)

⸻

Final conclusion

Your plan is correct, but the key is this: • Apps Script endpoints = generic atomic capability layer • Next server actions = domain orchestration layer • Document/Trip/Product sections = context + payload sources • Toolbar = execution surface • Sidebar = composition surface

That is the right foundation for your next milestone.

Next best move: define the exact request/response schemas for the first 7 deployed endpoints.

<!-- ***** -->

Atomic, Granular, Generic List of API Endpoints/Functions** A. Gmail API

  • users.messages.send — Send email (with/without attachments)

  • users.messages.list — List received/sent emails (filter by label/date)

  • users.messages.get — Get email details (for logging or follow-up)

  • users.messages.attachments.get — Retrieve attachments (e.g., PDFs)

B. Google Drive API

  • files.create — Create/upload files (Docs, PDFs)

  • files.export — Export Google Docs/Sheets as PDF

  • files.get — Retrieve file metadata (for sharing/logging)

  • files.list — List files/folders (for quick access)

  • permissions.create — Share files with users/groups

C. Google Docs API

  • documents.create — Create new Google Doc (meeting notes, reports)

  • documents.get — Retrieve document content (for logs/review)

  • documents.batchUpdate — Update document content (add meeting notes, outcomes)

D. Google Sheets API

  • spreadsheets.create — Create new sheet (activity log, tracker)

  • spreadsheets.values.append — Add new row (log activity, meeting outcome)

  • spreadsheets.values.get — Retrieve log data (for review/reporting)

  • spreadsheets.values.update — Update log entries

E. Google Calendar API

  • events.insert — Create/schedule calendar event (with invitees)

  • events.get — Retrieve event details (for follow-ups/logs)

  • events.list — List upcoming/past events (for activity review)

  • events.patch — Update event (add docs, change time, etc.)

  • events.attachments — Add attachments to events (via conferenceData or description links)

  • Add invitees

  • Attach Google Doc/PDF (via Drive link in description or as attachment)

3 Send email invitation with attached agenda/report (messages.send with attachment) 4 After meeting, update Google Doc with notes (docs.batchUpdate) 5 Share updated Doc/PDF with attendees (drive.permissions.create or messages.send) 6 Export Doc as PDF if needed (drive.files.export) 7 Review weekly logs in Sheets (sheets.values.get) 8 Send summary/follow-up emails (messages.send) 6. Custom Endpoint List (for your own API/middleware)

  • /send-email (params: to, subject, body, attachments)

  • /log-activity (params: activity_type, details, timestamp)

  • /create-doc (params: title, content, template)

  • /update-doc (params: doc_id, content)

  • /export-doc-pdf (params: doc_id)

  • /create-event (params: title, time, attendees, description, attachments)

  • /share-file (params: fileid, useremail, permission)

  • /get-logs (params: daterange, activitytype)

  • /send-followup (params: to, subject, body, related_event)

Summary Table:

Routine Step API Used Endpoint/Functionality Send/receive emails Gmail API send, list, get, attachments Log activities Sheets API append, get, update Create/update docs Docs API create, get, batchUpdate Generate/share PDFs Drive API export, create, permissions | Schedule events/invite | Calendar API | insert, get, list, patch, attachments|

| Share docs in events/email | Drive/Gmail API | permissions, send |

| Automate follow-ups | Gmail/Calendar | send, insert |

This toolkit covers 80% of weekly survival and growth actions for almost any business.

If you want a sample workflow or code snippets, just ask! 🚀