nuxt-google-sheets-import 0.1.4 → 0.1.7

package/README.md

@@ -1,10 +1,10 @@
-# @tribeweb/nuxt-google-sheets-import
+# nuxt-google-sheets-import
 
 Schema-driven Google Sheets importer for Nuxt Content.
 
 ## Status
 
-This package scaffold is extracted from a working local module and is ready for standalone hardening/publishing.
+Nuxt module for schema-driven Google Sheets import/export workflows with Nuxt Content.
 
 ## Features
 
@@ -13,107 +13,63 @@ This package scaffold is extracted from a working local module and is ready for
 - Writes frontmatter markdown, JSON, or YAML output
 - Supports overwrite strategies (`overwrite`, `skip`, `overwrite-frontmatter`)
 - Exposes UI components and composables for import workflow
+- Includes a built-in `/google-sheets-import` page with tabbed setup/import/export flow
+- Supports TSV clipboard copy for Google Sheets-friendly paste
 
-## Install (workspace)
+## Install
 
 ```bash
-pnpm add @tribeweb/nuxt-google-sheets-import
+pnpm add nuxt-google-sheets-import
 ```
 
-## Configure
+## Configuration
 
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  modules: ['@tribeweb/nuxt-google-sheets-import'],
+  modules: ['nuxt-google-sheets-import'],
   googleSheetsImport: {
     apiBase: '/api/google-sheets-import',
     googleApiKeyRuntimeKey: 'googleApiKey',
-    schemaRegistryImport: '#imports',
-    schemaRegistryExport: 'schemas',
-    defaultContentDir: 'content',
-    collectionTypeBySchema: {
-      machines: 'page',
-      materials: 'data'
-    }
+    defaultContentDir: 'content/data'
   }
 })
 ```
 
+Collection type (`page` vs `data`) is derived from your Nuxt Content `content.config.ts` collections.
+
 ## Environment
 
 ```bash
 NUXT_GOOGLE_API_KEY=your_google_sheets_api_key
 ```
 
-## Google setup (permissions + API key)
-
-This module currently reads Google Sheets using an API key, so the sheet must be publicly readable.
+## Quick Start
 
-> Security note:
-> API-key access is best suited to non-sensitive sheets that are intentionally shared as `Anyone with the link`.
-> For private or sensitive spreadsheets, prefer OAuth 2.0 or a service account flow instead of API-key access.
+1. Add the module and runtime env var.
+2. Define your Zod `schemas` export in `~/utils/googleSheetImportSchemas.ts`.
+3. Ensure matching Nuxt Content collections exist in `content.config.ts`.
+4. Start dev server and open `/google-sheets-import`.
+5. Use tabs in order:
+   - `Setup Google Sheet`: confirm schema headers and copy as needed.
+   - `Import data`: load sheet rows and write content files.
+   - `Export data`: query existing records, copy TSV for Sheets, or download CSV.
 
-### 1) Set sheet permissions (Google Sheets)
-
-1. Open your sheet in Google Sheets.
-2. Click `Share`.
-3. Under `General access`, set to `Anyone with the link`.
-4. Set role to `Viewer`.
-5. Copy the spreadsheet ID from the URL:
-  - `https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit`
-
-If your Google Workspace policy blocks public link sharing, API key access will fail. In that case you need OAuth/service-account based auth (not part of this module yet).
-
-### 2) Create API key (Google Cloud Console)
-
-1. Open Google Cloud Console: https://console.cloud.google.com/
-2. Create/select a project.
-3. Enable Google Sheets API:
-  - https://console.cloud.google.com/apis/library/sheets.googleapis.com
-4. Create credentials (API key):
-  - https://console.cloud.google.com/apis/credentials
-  - Click `Create credentials` → `API key`
-5. Restrict the key (recommended):
-  - **API restrictions**: `Restrict key` → select `Google Sheets API`
-  - **Application restrictions**:
-    - Server usage: `IP addresses` (recommended for backend)
-    - Browser-only usage: `HTTP referrers` (if applicable)
-6. Put the key into `NUXT_GOOGLE_API_KEY`.
-
-### 3) Quick verification
-
-Call your module endpoint with a known sheet ID and confirm it returns tab metadata:
+Quick endpoint check:
 
 `GET /api/google-sheets-import/sheets?spreadsheetId=<SPREADSHEET_ID>`
 
-### 4) Troubleshooting (common errors)
-
-- `403 PERMISSION_DENIED` / `The caller does not have permission`
-  - The sheet is not publicly readable with link.
-  - Fix: set `Share` → `General access` → `Anyone with the link` + `Viewer`.
-
-- `403 API key not valid` or `API has not been used in project`
-  - The key is wrong, restricted to the wrong API, or Sheets API is not enabled.
-  - Fix: enable `Google Sheets API` and ensure key restriction includes it.
-
-- `403 Requests from this referrer/IP are blocked`
-  - Your key application restrictions do not match where requests come from.
-  - Fix: update key restrictions (`IP addresses` for server use is preferred).
-
-- `404 Requested entity was not found`
-  - Spreadsheet ID is incorrect or malformed.
-  - Fix: copy ID from `https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit`.
-
-- `400 Unable to parse range`
-  - Invalid A1 range (for example typo in sheet tab or columns).
-  - Fix: verify tab name and use ranges like `A:Z`.
-
 ## Exported runtime
 
-- Components: `GoogleSheetsImportSource`, `GoogleSheetsImportExecute`, `GoogleSheetsImportSchemaGuide`
+- Components: `GoogleSheetsImportSource`, `GoogleSheetsImportExecute`, `GoogleSheetsImportSchemaGuide`, `GoogleSheetsImportExport`
 - Composables: `useGoogleSheetsImport`, `useGoogleSheetsImportWorkflow`
 
+The module adds a route at `/google-sheets-import` with `UTabs` for:
+
+- `Setup Google Sheet` (schema guide)
+- `Import data` (sheet source/import flow)
+- `Export data` (export existing content records)
+
 ### Schema helper component
 
 Use `GoogleSheetsImportSchemaGuide` to let editors choose a schema and see the expected Google Sheet column headers.
@@ -126,23 +82,34 @@ Benefits:
 
 - Reduces import failures by giving editors exact header names before filling a sheet
 - Supports nested/array header patterns used by schema mapping (for example `items[0].name`)
+- Uses a single column for arrays of scalar values (for example `tags` with `foo, bar, baz`)
 - For `page` collections, shows Nuxt Content built-in page override fields and allows copying them separately
 - Supports two copy modes:
   - line-by-line copy
-  - CSV-row copy (pastes horizontally into Google Sheets)
+  - tab-separated row copy (pastes horizontally into Google Sheets)
 
 Optional prop:
 
 - `initialSchema?: string`
 
-## Schema registry
+### Suggested Cell Examples
 
-The module resolves Zod schemas from a configurable module import so it does not depend on app-specific paths.
+Use these value patterns when filling sheets:
 
-- `schemaRegistryImport` (default: `#imports`)
-- `schemaRegistryExport` (default: `schemas`)
+- `string`: `example text`
+- `number`: `123`
+- `boolean`: `true` or `false`
+- `enum` / `literal`: use one of the schema's allowed values
+- `date-like string`: `2026-01-01`
+- `string[]` (scalar array): `foo, bar, baz` in a single cell
+- `object[]` (array of objects): use indexed headers like `items[0].name`, `items[0].price`
 
-Expected shape:
+## Schema Source
+
+Define a `schemas` export in `~/utils/googleSheetImportSchemas.ts`.
+The module auto-imports this as `googleSheetsImportSchemas` for app and server runtime use.
+
+Example:
 
 ```ts
 export const schemas = {
@@ -151,39 +118,12 @@ export const schemas = {
 }
 ```
 
-If your schemas are exported from a custom file, point the module to it:
-
-```ts
-export default defineNuxtConfig({
-  modules: ['@tribeweb/nuxt-google-sheets-import'],
-  googleSheetsImport: {
-    schemaRegistryImport: '~/server/google-sheets/schemas',
-    schemaRegistryExport: 'schemas'
-  }
-})
-```
-
-## Playground smoke test (`values` + `write`)
+## Export Behavior
 
-The playground includes:
+- `Copy for Google Sheets` in `GoogleSheetsImportExport` copies **TSV** to the clipboard for reliable Sheets paste.
+- `Download .csv` provides quoted CSV output for file-based workflows.
 
-- `playground/server/google-sheets/schemas.ts` (tiny local schema registry)
-- `POST /api/google-sheets-import/values-smoke` (local transform/validation payload)
-- `playground/scripts/smoke.mjs` (calls `values-smoke`, then module `write` for `frontmatter`, `json`, `yaml`)
-
-Run with Nuxt dev server active:
-
-```bash
-pnpm --dir packages/nuxt-google-sheets-import smoke:playground
-```
-
-Optional custom base URL:
-
-```bash
-SMOKE_BASE_URL=http://localhost:3000 pnpm --dir packages/nuxt-google-sheets-import smoke:playground
-```
-
-## Additional API endpoint
+## Additional API Endpoint
 
 - `GET {apiBase}/schema-columns`
   - Query: `schema?`
@@ -193,31 +133,78 @@ SMOKE_BASE_URL=http://localhost:3000 pnpm --dir packages/nuxt-google-sheets-impo
     - `collectionType`: `page | data | unknown`
     - `pageOverrideColumns`: Nuxt Content page override fields (when `collectionType === 'page'`)
 
+## Google Setup (Permissions + API Key)
+
+This module reads Google Sheets using an API key, so the sheet must be publicly readable.
+
+> Security note:
+> API-key access is best suited to non-sensitive sheets that are intentionally shared as `Anyone with the link`.
+> For private or sensitive spreadsheets, prefer OAuth 2.0 or a service account flow instead of API-key access.
+
+### 1) Set sheet permissions (Google Sheets)
+
+1. Open your sheet in Google Sheets.
+2. Click `Share`.
+3. Under `General access`, set to `Anyone with the link`.
+4. Set role to `Viewer`.
+5. Copy the spreadsheet ID from the URL:
+  - `https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit`
+
+If your Google Workspace policy blocks public link sharing, API key access will fail. In that case you need OAuth/service-account based auth (not part of this module yet).
+
+### 2) Create API key (Google Cloud Console)
+
+1. Open Google Cloud Console: https://console.cloud.google.com/
+2. Create/select a project.
+3. Enable Google Sheets API:
+  - https://console.cloud.google.com/apis/library/sheets.googleapis.com
+4. Create credentials (API key):
+  - https://console.cloud.google.com/apis/credentials
+  - Click `Create credentials` -> `API key`
+5. Restrict the key (recommended):
+  - **API restrictions**: `Restrict key` -> select `Google Sheets API`
+  - **Application restrictions**:
+    - Server usage: `IP addresses` (recommended for backend)
+    - Browser-only usage: `HTTP referrers` (if applicable)
+6. Put the key into `NUXT_GOOGLE_API_KEY`.
+
+### 3) Troubleshooting (common errors)
+
+- `403 PERMISSION_DENIED` / `The caller does not have permission`
+  - The sheet is not publicly readable with link.
+  - Fix: set `Share` -> `General access` -> `Anyone with the link` + `Viewer`.
+
+- `403 API key not valid` or `API has not been used in project`
+  - The key is wrong, restricted to the wrong API, or Sheets API is not enabled.
+  - Fix: enable `Google Sheets API` and ensure key restriction includes it.
+
+- `403 Requests from this referrer/IP are blocked`
+  - Your key application restrictions do not match where requests come from.
+  - Fix: update key restrictions (`IP addresses` for server use is preferred).
+
+- `404 Requested entity was not found`
+  - Spreadsheet ID is incorrect or malformed.
+  - Fix: copy ID from `https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit`.
+
+- `400 Unable to parse range`
+  - Invalid A1 range (for example typo in sheet tab or columns).
+  - Fix: verify tab name and use ranges like `A:Z`.
+
 ## Publish checklist
 
 - Add playground integration tests for `/values` and `/write`
 - Add CI (`lint`, `typecheck`, `build`) and release workflow
 - Verify Nuxt 4 peer compatibility matrix
 
-## Publish (next step)
-
-```bash
-pnpm --dir packages/nuxt-google-sheets-import release:check
-```
-
-Then authenticate and publish:
+## Release
 
 ```bash
-npm login
-pnpm --dir packages/nuxt-google-sheets-import publish --access public
+npm run release
 ```
 
-Or use one-command release scripts (bumps version + checks + publishes):
+If needed, authenticate and publish manually:
 
 ```bash
 npm login
-pnpm --dir packages/nuxt-google-sheets-import release:patch
-# or: release:minor / release:major
+npm publish --access public
 ```
-
-These scripts use `npm version --no-git-tag-version`, so they update `package.json` version without creating a git tag/commit.

package/dist/module.d.mts

@@ -4,7 +4,6 @@ interface ModuleOptions {
     apiBase: string;
     googleApiKeyRuntimeKey: string;
     defaultContentDir: string;
-    collectionTypeBySchema: Record<string, 'page' | 'data'>;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-google-sheets-import",
   "configKey": "googleSheetsImport",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { defineNuxtModule, createResolver, extendPages, addServerHandler, addImportsDir, addComponentsDir, addImports } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, extendPages, addServerHandler, addImportsDir, addComponentsDir, addImports, addServerImports } from '@nuxt/kit';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -6,6 +6,9 @@ const module$1 = defineNuxtModule({
     configKey: "googleSheetsImport"
   },
   moduleDependencies: {
+    "@nuxt/content": {
+      version: ">=3"
+    },
     "@nuxt/ui": {
       version: ">=4"
     }
@@ -13,32 +16,20 @@ const module$1 = defineNuxtModule({
   defaults: {
     apiBase: "/api/google-sheets-import",
     googleApiKeyRuntimeKey: "googleApiKey",
-    defaultContentDir: "content/data",
-    collectionTypeBySchema: {}
-    // schemaRegistryImport: '#imports',
-    // schemaRegistryExport: 'schemas',
+    defaultContentDir: "content/data"
   },
   setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
-    const normalizedCollectionTypeBySchema = Object.entries(options.collectionTypeBySchema).reduce((acc, [key, value]) => {
-      const trimmed = key.trim();
-      acc[trimmed] = value;
-      acc[trimmed.toLowerCase()] = value;
-      acc[trimmed.replace(/[-\s]+/g, "_").toLowerCase()] = value;
-      return acc;
-    }, {});
     nuxt.options.runtimeConfig.googleSheetsImport = {
+      ...nuxt.options.runtimeConfig.googleSheetsImport,
       apiBase: options.apiBase,
       googleApiKeyRuntimeKey: options.googleApiKeyRuntimeKey,
-      defaultContentDir: options.defaultContentDir,
-      collectionTypeBySchema: normalizedCollectionTypeBySchema
-      // schemaRegistryImport: options.schemaRegistryImport,
-      // schemaRegistryExport: options.schemaRegistryExport,
+      defaultContentDir: options.defaultContentDir
     };
     nuxt.options.runtimeConfig.public.googleSheetsImport = {
+      ...nuxt.options.runtimeConfig.public.googleSheetsImport,
       apiBase: options.apiBase,
-      defaultContentDir: options.defaultContentDir,
-      collectionTypeBySchema: normalizedCollectionTypeBySchema
+      defaultContentDir: options.defaultContentDir
     };
     nuxt.options.css.push(resolver.resolve("./runtime/assets/css/main.css"));
     extendPages((pages) => {
@@ -78,6 +69,11 @@ const module$1 = defineNuxtModule({
       path: resolver.resolve("./runtime/components")
     });
     addImports([
+      {
+        from: "~/utils/googleSheetImportSchemas",
+        name: "schemas",
+        as: "googleSheetsImportSchemas"
+      },
       {
         from: resolver.resolve("./runtime/types/googleSheetsApi"),
         name: "GoogleSheetsApiValues",
@@ -109,6 +105,13 @@ const module$1 = defineNuxtModule({
         type: true
       }
     ]);
+    addServerImports([
+      {
+        from: "~/utils/googleSheetImportSchemas",
+        name: "schemas",
+        as: "googleSheetsImportSchemas"
+      }
+    ]);
   }
 });
 

package/dist/runtime/components/GoogleSheetsImportExecute.vue

@@ -1,4 +1,7 @@
 <script setup>
+import { useGoogleSheetsImportWorkflow } from "../composables/useGoogleSheetsImportWorkflow";
+import { useToast } from "#imports";
+import { computed } from "vue";
 const props = defineProps({
   query: { type: Object, required: true }
 });

package/dist/runtime/components/GoogleSheetsImportExport.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/GoogleSheetsImportExport.vue

@@ -0,0 +1,196 @@
+<script setup>
+import { computed, ref, watch } from "vue";
+import { googleSheetsImportSchemas, queryCollection, useAsyncData, useToast } from "#imports";
+import { copyTextWithSuccessToast } from "../utils/clipboard";
+import { toCsvRow, toTsvRow } from "../utils/delimited";
+import { flattenRecordToStringMap } from "../utils/pathMapping";
+const toast = useToast();
+const queryCollectionLoose = queryCollection;
+const selectedSchema = ref("");
+const {
+  data: rowsData,
+  pending,
+  error: loadError,
+  status,
+  execute,
+  clear
+} = useAsyncData(
+  "google-sheets-import-export-records",
+  async () => {
+    if (!selectedSchema.value) {
+      return [];
+    }
+    const result = await queryCollectionLoose(selectedSchema.value).all();
+    return result;
+  },
+  {
+    immediate: false,
+    default: () => []
+  }
+);
+const rows = computed(() => rowsData.value ?? []);
+const error = computed(() => loadError.value?.message ?? "");
+watch(selectedSchema, () => {
+  clear();
+});
+const schemaMap = computed(() => googleSheetsImportSchemas ?? {});
+const schemaOptions = computed(() => Object.keys(schemaMap.value).sort((left, right) => left.localeCompare(right)).map((schema) => ({ label: schema, value: schema })));
+const headers = computed(() => {
+  const all = /* @__PURE__ */ new Set();
+  for (const row of rows.value) {
+    flattenRecordToStringMap(row).forEach((_, key) => all.add(key));
+  }
+  return Array.from(all).sort((left, right) => left.localeCompare(right));
+});
+const csvText = computed(() => {
+  if (!headers.value.length) {
+    return "";
+  }
+  const lines = [];
+  lines.push(toCsvRow(headers.value));
+  for (const row of rows.value) {
+    const flat = flattenRecordToStringMap(row);
+    const values = headers.value.map((header) => flat.get(header) ?? "");
+    lines.push(toCsvRow(values));
+  }
+  return `${lines.join("\n")}
+`;
+});
+const tsvText = computed(() => {
+  if (!headers.value.length) {
+    return "";
+  }
+  const lines = [];
+  lines.push(toTsvRow(headers.value));
+  for (const row of rows.value) {
+    const flat = flattenRecordToStringMap(row);
+    const values = headers.value.map((header) => flat.get(header) ?? "");
+    lines.push(toTsvRow(values));
+  }
+  return `${lines.join("\n")}
+`;
+});
+const previewText = computed(() => {
+  if (!csvText.value) {
+    return "";
+  }
+  return csvText.value.split("\n").slice(0, 11).join("\n");
+});
+async function loadRecords() {
+  if (!selectedSchema.value) {
+    return;
+  }
+  await execute();
+  if (status.value === "success") {
+    toast.add({
+      title: "Export ready",
+      description: `Loaded ${rows.value.length} row(s) from collection ${selectedSchema.value}.`,
+      color: "success"
+    });
+  }
+}
+async function copyCsv() {
+  await copyTextWithSuccessToast({
+    text: tsvText.value,
+    toast,
+    description: "Tab-separated rows copied for Google Sheets paste.",
+    title: "Copied"
+  });
+}
+function downloadCsv() {
+  if (!csvText.value) {
+    return;
+  }
+  const blob = new Blob([csvText.value], { type: "text/csv;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = `${selectedSchema.value || "export"}.csv`;
+  link.click();
+  URL.revokeObjectURL(url);
+}
+</script>
+
+<template>
+  <div class="space-y-4">
+    <UAlert
+      title="Export Existing Content"
+      description="Load records from a Nuxt Content collection and export them as CSV for Google Sheets."
+      color="neutral"
+      variant="subtle"
+    />
+
+    <UAlert
+      v-if="error"
+      title="Could not load collection"
+      :description="error"
+      color="error"
+      variant="subtle"
+    />
+
+    <UFormField
+      label="Collection schema"
+      name="schema"
+      description="Pick the schema/collection to export."
+    >
+      <USelect
+        v-model="selectedSchema"
+        :items="schemaOptions"
+        value-key="value"
+        class="w-full max-w-sm"
+        icon="i-heroicons-cube-20-solid"
+      />
+    </UFormField>
+
+    <div class="flex flex-wrap gap-2">
+      <UButton
+        label="Load records"
+        icon="i-heroicons-arrow-down-tray-20-solid"
+        :disabled="!selectedSchema"
+        :loading="pending"
+        @click="loadRecords"
+      />
+      <UButton
+        label="Copy for Google Sheets"
+        icon="i-heroicons-clipboard-document-20-solid"
+        color="neutral"
+        variant="subtle"
+        :disabled="!tsvText"
+        @click="copyCsv"
+      />
+      <UButton
+        label="Download .csv"
+        icon="i-heroicons-document-arrow-down-20-solid"
+        color="neutral"
+        variant="subtle"
+        :disabled="!csvText"
+        @click="downloadCsv"
+      />
+    </div>
+
+    <UAlert
+      v-if="status === 'success'"
+      title="Export prepared"
+      :description="`${rows.length} row(s), ${headers.length} column(s).`"
+      color="success"
+      variant="subtle"
+    />
+
+    <UCollapsible
+      v-if="previewText"
+      class="flex flex-col gap-2 w-full"
+    >
+      <UButton
+        label="Preview CSV (first 10 rows)"
+        color="neutral"
+        variant="subtle"
+        trailing-icon="i-lucide-chevron-down"
+        block
+      />
+
+      <template #content>
+        <pre class="text-xs whitespace-pre-wrap">{{ previewText }}</pre>
+      </template>
+    </UCollapsible>
+  </div>
+</template>

package/dist/runtime/components/GoogleSheetsImportExport.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;