Vibe Sheets SDK

Live Demo | GitHub Repository

The official SDK for building applications with Vibe Sheets logic. This SDK provides a decentralized, serverless way to manage Google Sheets and Apps Script deployments directly from the client-side.

Features

- Serverless Architecture: Directly interacts with Google APIs (Sheets, Drive, Apps Script) from the browser.
- Full CRUD Support: Built-in support for Create, Read, Update, and Delete operations on Google Sheets.
- Soft Delete: Implements soft delete pattern using is_enabled column.
- Advanced Filtering: Support for field projection (e.g., ?fields=name,value) in API requests.
- React Hooks: Built-in hooks for easy state management (useSheetManager, useGoogleAuth).
- Core API: Raw API functions available for non-React environments.
- Type-Safe: Written in TypeScript with full type definitions.

React Hooks Usage

The SDK provides ready-to-use React hooks to simplify integration.

$3

Handles Google OAuth 2.0 authentication flow, permission scopes, and token management.

``typescript
import { ReactHooks } from '@glennjong/vibe-sheets';

const MyComponent = () => {
const {
tokenClient,
accessToken,
loading,
error,
isAppsScriptEnabled,
isChecking,
initGoogleAuth,
handleLogin,
handleLogout,
checkAppsScriptStatus,
enableAppsScriptApi
} = ReactHooks.useGoogleAuth({
clientId: "YOUR_GOOGLE_CLIENT_ID"
});

useEffect(() => {
initGoogleAuth();
}, [initGoogleAuth]);

if (!accessToken) {
return Login with Google;
}

return (



);
};
`

$3

Manages the lifecycle of Vibe Sheets: creating new sheets, deploying the backend script, and fetching the list of existing sheets.

`typescript
import { ReactHooks } from '@glennjong/vibe-sheets';

const Dashboard = ({ accessToken }) => {
const {
loading,
error,
files, // List of Vibe Sheet files (DriveFile[])
creationStatus, // 'idle' | 'creating_sheet' | 'creating_script' | ...
creationResult, // Result after successful creation
fetchFiles,
createSheet,
testConnection
} = ReactHooks.useSheetManager(accessToken);

// 1. Fetch existing sheets on load
useEffect(() => {
if (accessToken) fetchFiles();
}, [accessToken]);

// 2. Create a new sheet
const handleCreate = async () => {
await createSheet({
sheetName: "My New Database",
columns: [
{ name: 'product', type: 'string' },
{ name: 'price', type: 'number' },
{ name: 'in_stock', type: 'boolean' }
]
});
};

return (



);
};
`

Apps Script Backend

The SDK automatically deploys a Google Apps Script project that acts as a RESTful API for your Google Sheets.

$3

All operations support the sheet query parameter (e.g., ?sheet=PendingOrders).
- If specified, the operation targets that specific sheet/tab by name.
- If omitted, defaults to the first sheet in the spreadsheet.

- GET (Read): Retrieves rows from the sheet.
- Query Params:
- sheet (Optional): The name of the tab to read from(e.g., ?sheet=mySheet). Defaults to the first tab.
- fields (Optional): Comma-separated list of columns to retrieve (e.g., ?fields=name,email).
- Behavior:
- Automatically filters out rows where is_enabled is false (soft delete).
- Always returns the id column, even if not explicitly requested in fields.
- Excludes is_enabled from the response unless explicitly asked for.

- POST (Create): Appends new rows to the sheet.
- Query Params:
- sheet (Optional): The name of the tab to read from(e.g., ?sheet=mySheet). Defaults to the first tab.
- Body: Single JSON object or an Array of objects.
- Behavior:
- This is the default action if no method parameter is provided.
- Auto-generates id (UUID) as a string, created_at, and updated_at if missing.
- Automatically adds checkbox validation for boolean fields.

- POST (Update): Updates specific columns of an existing row.
- Query Params:
- method=PUT (Required): Specifies the update operation.
- sheet (Optional): The name of the tab to read from(e.g., ?sheet=mySheet). Defaults to the first tab.
- Body: JSON object { id: "target_id", ...fields_to_update }.
- Behavior:
- Matches row by id (string comparison).
- Updates only the provided fields and refreshes updated_at.

- POST (Delete): Performs a soft delete.
- Query Params:
- method=DELETE (Required): Specifies the delete operation.
- sheet (Optional): The name of the tab to read from(e.g., ?sheet=mySheet). Defaults to the first tab.
- Body: JSON object { id: "target_id" }.
- Behavior:
- Sets is_enabled to false.
- Does not physically delete the row.

Installation

`bash
npm install @glennjong/vibe-sheets
`

Usage

$3

Wrap your application or component functionality with useGoogleAuth to handle the OAuth flow.

`tsx
import { ReactHooks } from '@glennjong/vibe-sheets';


const MyComponent = () => {
const { login, accessToken } = ReactHooks.useGoogleAuth({
clientId: "YOUR_GOOGLE_CLIENT_ID"
});

if (!accessToken) {
return Login with Google;
}

return ;
};
`

$3

Use useSheetManager to create sheets, deploy scripts, and fetch data.

`tsx
import { ReactHooks } from '@glennjong/vibe-sheets';

const VibeApp = ({ token }) => {
const {
createSheet,
loading,
creationResult
} = ReactHooks.useSheetManager(token);

const handleCreate = () => {
createSheet({
sheetName: "My New Sheet",
// Optional: Custom tab Name (defaults to 'default')
tabName: "OrderData",
// Optional: Custom prefix for file search (defaults to 'vibesheet-')
prefix: "myapp-",
// Optional: Define custom columns (defaults to name/value)
columns: [
{ name: "title", type: "string" },
{ name: "status", type: "string" },
{ name: "count", type: "number" }
]
});
};

return (



);
};
`

Core API (Non-React)

If you are not using React, you can import the core functions directly:

`typescript
import { createUserSpreadsheet, createScriptProject } from '@glennjong/vibe-sheets/core';
// Implementation details...
``