SDK Reference

npm install @gkit/sheets-sdk
# or
pnpm add @gkit/sheets-sdk
# or
bun add @gkit/sheets-sdk

import { SheetsClient } from "@gkit/sheets-sdk";
 
const client = new SheetsClient({
  userKey: process.env.SHEETS_USER_KEY!,
  apiKey: process.env.SHEETS_API_KEY!,
  // Optional:
  baseUrl: "https://sheetsapi.gkit.mreshank.com", // default
  timeout: 10_000, // ms, default 30 000
  retries: 3, // on 5xx or network error
});

const { data, meta } = await client.get<Product>("Products", {
  limit: 20,
  offset: 0,
  sort: "-price",
  search: "category:books",
  fields: ["id", "name", "price"],
});

const products = await client.getAll<Product>("Products", {
  sort: "name",
  search: "category:books",
});
// Returns T[] - all matching rows

const created = await client.post<Product>("Products", {
  id: crypto.randomUUID(),
  name: "Widget Pro",
  price: "49.99",
  category: "Widgets",
});
// Returns the appended row

const [product] = await client.find<Product>("Products", "id", productId);
if (!product) throw new Error("Not found");

interface SheetResponse<T> {
  data: T[];
  meta: {
    total: number;
    limit: number;
    offset: number;
  };
}
 
interface SheetsClientConfig {
  userKey: string;
  apiKey: string;
  baseUrl?: string; // default: "https://sheetsapi.gkit.mreshank.com"
  timeout?: number; // ms, default 30 000
  retries?: number; // default 3
}

import { SheetsApiError } from "@gkit/sheets-sdk";
 
try {
  const { data } = await client.get("Products");
} catch (err) {
  if (err instanceof SheetsApiError) {
    console.error(err.status); // HTTP status code
    console.error(err.message); // Error message from the API
    console.error(err.sheet); // Which sheet caused the error
  }
}

async function* paginate<T>(
  client: SheetsClient,
  sheet: string,
  params: Record<string, string | number> = {},
): AsyncGenerator<T[]> {
  const pageSize = 100;
  let offset = 0;
  let total = Infinity;
 
  while (offset < total) {
    const { data, meta } = await client.get<T>(sheet, {
      ...params,
      limit: pageSize,
      offset,
    });
    total = meta.total;
    offset += pageSize;
    yield data;
  }
}
 
// Usage:
for await (const page of paginate(client, "Products")) {
  processPage(page);
}