@sheet2db/sdk 1.0.9 → 2.0.1

package/README.md

@@ -1,329 +1,179 @@
-# Sheet2DB Documentation
+# 📘 Sheet2DBClient SDK
 
-## Overview
+The `Sheet2DBClient` SDK allows developers to interact with their Google Sheets via the Sheet2DB platform using a clean and typed interface. It provides full CRUD support along with helper utilities for managing sheets.
 
-`Sheet2DB` is a TypeScript class that provides an easy interface to interact with Google Sheets via the [`sheet2db`](https://sheet2db.com) API. This class abstracts the complexity of API calls and provides a simple way to read, write, update, and delete data in Google Sheets. It supports both browser and Node.js environments.
+---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @sheet2db/sdk
 ```
 
-## Configuration Options
+---
 
-### Sheet2DBOptions
+## 🚀 Usage
 
-- **mode**: `'apikey' | 'connectionId'` - Authentication mode.
-- **apiKey**: `string` (required for `'apikey'` mode) - API key for accessing the spreadsheet.
-- **spreadsheetId**: `string` (required for `'apikey'` mode) - The ID of the Google spreadsheet.
-- **version**: `"v1"` - API version, always "v1".
-- **connectionId**: `string` (required for `'connectionId'` mode) - Connection ID for accessing the spreadsheet.
-- **basicAuth**: `{ username: string; password: string; }` (optional for `'connectionId'` mode) - Basic authentication credentials.
-- **jwtAuth**: `{ bearerToken: string; }` (optional for `'connectionId'` mode) - JWT authentication token.
-- **fetchFn**: `typeof fetch` (optional) - Custom fetch function.
+```ts
+import { Sheet2DBClient } from '@sheet2db/sdk';
 
-## Usage
+const client = new Sheet2DBClient('your-api-id');
 
-### Import and Initialize
+// Optional authentication
+client.useBearerTokenAuthentication('your-token');
 
-```typescript
-import { Sheet2DB,Sheet2DBOptions } from 'sheet2db';
-
-const options: Sheet2DBOptions = {
-    mode: 'apikey',
-    apiKey: 'your-api-key',
-    spreadsheetId: 'your-spreadsheet-id',
-    version: 'v1'
-};
-
-const options: Sheet2DBOptions = {
-    mode: 'connectionId',
-    connectionId: 'your-connection-id',
-    version: 'v1'
-};
-
-const sheet2db = new Sheet2DB(options);
-```
-
-## Methods
-
-### ReadContent
-
-Fetches content from the spreadsheet.
-
-#### Parameters
-
-- **limit** (optional): `number` - Maximum number of records to return.
-- **offset** (optional): `number` - Number of records to skip before starting to return records.
-- **sheet** (optional): `string` - The name of the sheet to read from.
-- **format** (optional): `'records' | 'dict' | 'series' | 'split' | 'index' | 'raw'` - The format of the returned data.
-- **cast_numbers** (optional): `string` - Cast numbers to specified type.
-- **value_render** (optional): `'FORMATTED_VALUE' | 'UNFORMATTED_VALUE' | 'FORMULA'` - The value render option.
-
-#### Example
-
-```typescript
-sheet2db.ReadContent({ sheet: 'Sheet1', limit: 10 })
-    .then(data => console.log(data))
-    .catch(error => console.error(error));
-```
-
-### Keys
-
-Gets the keys of the spreadsheet.
-
-#### Parameters
-
-- **sheet** (optional): `string` - The name of the sheet to get keys from.
-
-#### Example
-
-```typescript
-sheet2db.Keys({ sheet: 'Sheet1' })
-    .then(keys => console.log(keys))
-    .catch(error => console.error(error));
-```
-
-### Count
-
-Gets the count of rows in the spreadsheet.
-
-#### Parameters
-
-- **sheet** (optional): `string` - The name of the sheet to count rows in.
-
-#### Example
-
-```typescript
-sheet2db.Count({ sheet: 'Sheet1' })
-    .then(count => console.log(count))
-    .catch(error => console.error(error));
-```
-
-### Title
-
-Gets the title of the spreadsheet.
-
-#### Example
-
-```typescript
-sheet2db.Title()
-    .then(title => console.log(title))
-    .catch(error => console.error(error));
-```
-
-### Range
-
-Gets a range of values from the spreadsheet.
-
-#### Parameters
-
-- **range**: `string` - The range to fetch, in A1 notation.
-
-#### Example
-
-```typescript
-sheet2db.Range({ range: 'A1:B2' })
-    .then(range => console.log(range))
-    .catch(error => console.error(error));
+// Example: Read rows
+const data = await client.Read({ limit: 10 }, 'Sheet1');
 ```
 
-### Search
+---
 
-Searches for records in the spreadsheet.
+## 🔐 Authentication Methods
 
-#### Parameters
-
-- **sheet** (optional): `string` - The name of the sheet to search in.
-- **or** (optional): `boolean` - If true, uses OR logic for the search.
-- **query**: `string` - The search query.
-
-#### Example
-
-```typescript
-sheet2db.Search({ query: 'name=John', sheet: 'Sheet1' })
-    .then(records => console.log(records))
-    .catch(error => console.error(error));
-```
-
-### Insert
-
-Inserts data into the spreadsheet.
-
-#### Parameters
-
-- **data**: `Record<string, any> | Record<string, any>[]` - The data to insert.
-- **sheet** (optional): `string` - The name of the sheet to insert data into.
-
-#### Example
-
-```typescript
-sheet2db.Insert({ data: { name: 'John', age: 30 }, sheet: 'Sheet1' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
+```ts
+client.useBasicAuthentication(username: string, password: string);
+client.useJWTAuthentication(token: string);
+client.useBearerTokenAuthentication(token: string);
 ```
 
-### UpdateRow
+---
 
-Updates a specific row in the spreadsheet.
+## 🧠 Type Definitions
 
-#### Parameters
+### `ReadOptions`
 
-- **row**: `number` - The row number to update.
-- **data**: `Record<string, any>` - The data to update.
-- **sheet** (optional): `string` - The name of the sheet to update data in.
-
-#### Example
-
-```typescript
-sheet2db.UpdateRow({ row: 1, data: { age: 31 }, sheet: 'Sheet1' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
+```ts
+{
+  limit?: number;
+  offset: number;
+  sortColumn?: string;
+  sortDirection: 'asc' | 'desc';
+  sortColumnFormat?: 'date';
+  filter?: string;
+  format: 'rows' | 'columns' | 'matrix';
+  columns?: string[];
+  castNumbers?: string[];
+}
 ```
 
-### UpdateWithQuery
-
-Updates rows based on a query.
-
-#### Parameters
+### `InsertOptions`
 
-- **sheet** (optional): `string` - The name of the sheet to update data in.
-- **query**: `string` - The query to identify rows to update.
-- **data**: `Record<string, any>` - The data to update.
-
-#### Example
-
-```typescript
-sheet2db.UpdateWithQuery({ query: 'name=John', data: { age: 32 }, sheet: 'Sheet1' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
+```ts
+{
+  data: any[];
+}
 ```
 
-### BatchUpdate
-
-Updates multiple records in batches.
+### `UpdateOptions`
 
-#### Parameters
-
-- **sheet** (optional): `string` - The name of the sheet to update data in.
-- **batches**: `{ query: string, record: Record<string, any> }[]` - The batch update data.
-
-#### Example
+```ts
+// Update by row
+{
+  type: 'row';
+  row: number;
+  data: Record<string, any>;
+}
 
-```typescript
-sheet2db.BatchUpdate({ batches: [{ query: 'name=John', record: { age: 33 } }], sheet: 'Sheet1' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
+// Update by filter
+{
+  type: 'filter';
+  filter: string;
+  data: Record<string, any>;
+}
 ```
 
-### DeleteRow
-
-Deletes a specific row in the spreadsheet.
+### `DeleteOptions`
 
-#### Parameters
-
-- **row**: `number` - The row number to delete.
-- **sheet** (optional): `string` - The name of the sheet to delete the row from.
-
-#### Example
+```ts
+// Delete by row
+{
+  type: 'row';
+  row: number;
+}
 
-```typescript
-sheet2db.DeleteRow({ row: 1, sheet: 'Sheet1' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
+// Delete by filter
+{
+  type: 'filter';
+  filter: string;
+}
 ```
 
-### DeleteWithQuery
+### `AddSheetOptions`
 
-Deletes rows based on a query.
-
-#### Parameters
-
-- **query**: `string` - The query to identify rows to delete.
-- **sheet** (optional): `string` - The name of the sheet to delete rows from.
-
-#### Example
-
-```typescript
-sheet2db.DeleteWithQuery({ query: 'name=John', sheet: 'Sheet1' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
+```ts
+{
+  name: string;
+  firstRow?: string[];
+  copyColumnsFrom?: string;
+}
 ```
 
-### Clear
+---
 
-Clears all data from a sheet.
+## 📚 Methods
 
-#### Parameters
+### `Read<T>(options: ReadOptions, sheet?: string): Promise<T>`
 
-- **sheet**: `string` - The name of the sheet to clear.
+Reads data from the sheet based on options provided.
 
-#### Example
+---
 
-```typescript
-sheet2db.Clear({ sheet: 'Sheet1' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
-```
+### `Insert(options: InsertOptions, sheet?: string): Promise<{ inserted: number }>`
 
-### CreateSheet
+Inserts rows of data into the specified sheet.
 
-Creates a new sheet in the spreadsheet.
+---
 
-#### Parameters
+### `Update(options: UpdateOptions, sheet?: string): Promise<{ updated: number }>`
 
-- **title** (optional): `string` - The title of the new sheet.
+Updates rows based on a filter or row number.
 
-#### Example
+---
 
-```typescript
-sheet2db.CreateSheet({ title: 'NewSheet' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
-```
+### `Delete(options: DeleteOptions, sheet?: string): Promise<{ deleted: number }>`
 
-### DeleteSheet
+Deletes rows based on a filter or row number.
 
-Deletes a sheet from the spreadsheet.
+---
 
-#### Parameters
+### `AddSheet(options: AddSheetOptions): Promise<{ ok: true }>`
 
-- **sheet**: `string` - The name of the sheet to delete.
+Adds a new sheet with optional headers or by copying from another sheet.
 
-#### Example
+---
 
-```typescript
-sheet2db.DeleteSheet({ sheet: 'Sheet1' })
-    .then(response => console.log(response))
-    .catch(error => console.error(error));
-```
+### `DeleteSheet(sheet: string): Promise<{ ok: true }>`
 
+Deletes a sheet by name.
 
+---
 
-## Environment Detection
+## 🧪 Example
 
-The library automatically detects the environment (browser or Node.js) and uses the appropriate `fetch` implementation.
+```ts
+await client.Insert({
+  data: [
+    { name: 'Alice', age: 28 },
+    { name: 'Bob', age: 31 }
+  ]
+}, 'People');
 
-```typescript
-let fetchFunction: typeof fetch;
+await client.Update({
+  type: 'row',
+  row: 2,
+  data: { age: 32 }
+}, 'People');
 
-if (typeof window !== 'undefined' && typeof window.fetch !== 'undefined') {
-    fetchFunction = window.fetch.bind(window);
-} else {
-    fetchFunction = async (...args) => {
-        const fetch = global.fetch;
-        return fetch(...args);
-    };
-}
+await client.Delete({
+  type: 'filter',
+  filter: 'name:eq:Bob'
+}, 'People');
 ```
 
-## Error Handling
+---
 
-Each method returns a promise that resolves to the API response or rejects with an error.
+## 🧾 Notes
 
-```typescript
-sheet2db.ReadContent()
-    .then(data => console.log(data))
-    .catch(error => console.error(error));
-```
+* All options are validated using `zod` for runtime type safety.
+* `sheet` argument is optional; default sheet will be used if not specified.
+* Supports pagination, sorting, and filtering.

package/dist/index.d.mts

@@ -0,0 +1,141 @@
+import { AxiosInstance } from 'axios';
+import { z } from 'zod';
+
+declare const DataAPIReadOptionsDTO: z.ZodObject<{
+    limit: z.ZodEffects<z.ZodOptional<z.ZodString>, number | undefined, string | undefined>;
+    offset: z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodString>>, number, string | undefined>;
+    sortColumn: z.ZodOptional<z.ZodString>;
+    sortDirection: z.ZodDefault<z.ZodOptional<z.ZodEnum<["asc", "desc"]>>>;
+    sortColumnFormat: z.ZodOptional<z.ZodLiteral<"date">>;
+    filter: z.ZodOptional<z.ZodString>;
+    format: z.ZodDefault<z.ZodOptional<z.ZodEnum<["rows", "columns", "matrix"]>>>;
+    columns: z.ZodEffects<z.ZodOptional<z.ZodString>, string[] | undefined, string | undefined>;
+    castNumbers: z.ZodEffects<z.ZodOptional<z.ZodString>, string[] | undefined, string | undefined>;
+}, "strip", z.ZodTypeAny, {
+    offset: number;
+    sortDirection: "asc" | "desc";
+    format: "rows" | "columns" | "matrix";
+    limit?: number | undefined;
+    filter?: string | undefined;
+    sortColumn?: string | undefined;
+    sortColumnFormat?: "date" | undefined;
+    columns?: string[] | undefined;
+    castNumbers?: string[] | undefined;
+}, {
+    limit?: string | undefined;
+    filter?: string | undefined;
+    offset?: string | undefined;
+    sortColumn?: string | undefined;
+    sortDirection?: "asc" | "desc" | undefined;
+    sortColumnFormat?: "date" | undefined;
+    columns?: string | undefined;
+    format?: "rows" | "columns" | "matrix" | undefined;
+    castNumbers?: string | undefined;
+}>;
+declare const DataAPIInsertOptionsDTO: z.ZodObject<{
+    data: z.ZodArray<z.ZodAny, "many">;
+}, "strip", z.ZodTypeAny, {
+    data: any[];
+}, {
+    data: any[];
+}>;
+declare const DataAPIUpdateOptionsDTO: z.ZodUnion<[z.ZodObject<{
+    data: z.ZodRecord<z.ZodString, z.ZodAny>;
+    row: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, number, string | number>;
+    type: z.ZodDefault<z.ZodLiteral<"row">>;
+}, "strip", z.ZodTypeAny, {
+    data: Record<string, any>;
+    type: "row";
+    row: number;
+}, {
+    data: Record<string, any>;
+    row: string | number;
+    type?: "row" | undefined;
+}>, z.ZodObject<{
+    data: z.ZodRecord<z.ZodString, z.ZodAny>;
+    filter: z.ZodString;
+    type: z.ZodDefault<z.ZodLiteral<"filter">>;
+}, "strip", z.ZodTypeAny, {
+    data: Record<string, any>;
+    filter: string;
+    type: "filter";
+}, {
+    data: Record<string, any>;
+    filter: string;
+    type?: "filter" | undefined;
+}>]>;
+declare const DataAPIDeleteOptionsDTO: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+    row: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, number, string | number>;
+}, "strip", z.ZodTypeAny, {
+    row: number;
+}, {
+    row: string | number;
+}>, {
+    row: number;
+    type: "row";
+}, {
+    row: string | number;
+}>, z.ZodObject<{
+    filter: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    filter: string;
+}, {
+    filter: string;
+}>]>, {
+    row: number;
+    type: "row";
+} | {
+    filter: string;
+    type: "filter";
+}, {
+    row: string | number;
+} | {
+    filter: string;
+}>;
+declare const DataAPIAddSheetOptionsDTO: z.ZodObject<{
+    name: z.ZodString;
+    firstRow: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    copyColumnsFrom: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    firstRow?: string[] | undefined;
+    copyColumnsFrom?: string | undefined;
+}, {
+    name: string;
+    firstRow?: string[] | undefined;
+    copyColumnsFrom?: string | undefined;
+}>;
+
+type ReadOptions = z.infer<typeof DataAPIReadOptionsDTO>;
+type InsertOptions = z.infer<typeof DataAPIInsertOptionsDTO>;
+type UpdateOptions = z.infer<typeof DataAPIUpdateOptionsDTO>;
+type DeleteOptions = z.infer<typeof DataAPIDeleteOptionsDTO>;
+type AddSheetOptions = z.infer<typeof DataAPIAddSheetOptionsDTO>;
+
+declare class Sheet2DBClient {
+    authentication: string | null;
+    axios: AxiosInstance;
+    constructor(apiId: string, version?: "v1");
+    private endpoint;
+    useBasicAuthentication(username: string, password: string): void;
+    useJWTAuthentication(token: string): void;
+    useBearerTokenAuthentication(token: string): void;
+    Read<T = any>(options: ReadOptions, sheet?: string): Promise<T>;
+    Update(options: UpdateOptions, sheet?: string): Promise<{
+        updated: number;
+    }>;
+    Insert(options: InsertOptions, sheet?: string): Promise<{
+        inserted: number;
+    }>;
+    Delete(options: DeleteOptions, sheet?: string): Promise<{
+        deleted: number;
+    }>;
+    AddSheet(options: AddSheetOptions): Promise<{
+        ok: true;
+    }>;
+    DeleteSheet(sheet: string): Promise<{
+        ok: true;
+    }>;
+}
+
+export { Sheet2DBClient };