PuddleJumper

Google Drive Connector Surface
Home Guide Operator Shell Sign In
Google Drive via PuddleJumper

The Google Drive thing lives in LogicOS, but it runs through PuddleJumper.

This page is the quick explainer for the Google Drive connector contract: what LogicOS calls, what PuddleJumper proxies, and what an operator should expect when Drive folders or files are created.

Auth Sign in to PuddleJumper Runtime Check health Context Open operator guide Workspace Open LogicOS
01 LogicOS starts the work

LogicOS asks for a Drive file list, upload, or folder creation using its PJ-backed Google client.

02 PuddleJumper owns auth

The browser never gets the Google token. PJ reads the session cookie, resolves the connector, and signs the upstream request server-side.

03 Google Drive receives the call

PuddleJumper proxies to the Drive API and returns only the response LogicOS needs, such as folder ID, name, and webViewLink.

Where it lives

1 LogicOS folder creation

src/lib/logicos/google.ts creates a Drive folder for a LogicOS record and calls PJ at /api/google/drive/v3/files.

2 LogicOS connector wiring

src/lib/logicos/connectors.ts routes google-folder connector work into that folder-creation path.

3 LogicOS general Drive service

src/services/googlePJService.ts wraps listing, upload, create, copy, and delete calls using the PJ proxy.

4 PuddleJumper proxy route

PuddleJumper serves the browser-facing Google proxy under /api/google/* and the upload surface under /api/google/upload/*.

5 Save UI

SaveToCloudDialog and the file-editor GoogleSavePanel are the main LogicOS UI entry points for Drive-backed saves.

6 Operator expectation

If Google is not connected, the fix is not in the browser. The user must go through the PuddleJumper connector OAuth flow.

Core contract

List files
GET /api/google/drive/v3/files

Create folder
POST /api/google/drive/v3/files
Content-Type: application/json

Upload file bytes
POST /api/google/upload/drive/v3/files

Typical create-folder body
{
  "name": "record-id - Record title",
  "mimeType": "application/vnd.google-apps.folder",
  "parents": ["optional-parent-folder-id"]
}

Important behavior

A No token in the browser

LogicOS always uses credentials: 'include'. The PJ session cookie is the only browser-side auth material.

B Drive folder naming

Folder names are sanitized before creation so illegal control characters and path-hostile characters are stripped out.

C Parent folder selection

LogicOS uses record.googleParentId first, then falls back to LOGICOS_GOOGLE_ROOT_FOLDER_ID when present.

D Common failure mode

If the connector is missing, PJ should return an explicit not-connected/auth-required error. A spinner is the wrong answer.

Operator checklist

1. Check PuddleJumper health
   GET /health

2. Confirm Google connector auth exists for the user
   Use PJ connector flow, not a browser-direct OAuth jump

3. Retry the LogicOS action
   - Save to cloud
   - Create Google Drive folder
   - File upload / copy / list

4. If needed, inspect the PJ Google proxy route behavior
   /api/google/*
   /api/google/upload/*

Bottom line

The Google Drive feature is a LogicOS workflow with a PuddleJumper runtime contract. If you are debugging the UI, start in LogicOS. If you are debugging auth, upstream calls, or connector health, start in PuddleJumper.