@sheet2db/sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,329 @@
+# Sheet2DB Documentation
+
+## Overview
+
+`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
+
+```bash
+npm install sheet2db
+```
+
+## Configuration Options
+
+### Sheet2DBOptions
+
+- **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.
+
+## Usage
+
+### Import and Initialize
+
+```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));
+```
+
+### Search
+
+Searches for records in the spreadsheet.
+
+#### 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));
+```
+
+### UpdateRow
+
+Updates a specific row in the spreadsheet.
+
+#### Parameters
+
+- **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));
+```
+
+### UpdateWithQuery
+
+Updates rows based on a query.
+
+#### Parameters
+
+- **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));
+```
+
+### BatchUpdate
+
+Updates multiple records in batches.
+
+#### 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
+
+```typescript
+sheet2db.BatchUpdate({ batches: [{ query: 'name=John', record: { age: 33 } }], sheet: 'Sheet1' })
+    .then(response => console.log(response))
+    .catch(error => console.error(error));
+```
+
+### DeleteRow
+
+Deletes a specific row in the spreadsheet.
+
+#### Parameters
+
+- **row**: `number` - The row number to delete.
+- **sheet** (optional): `string` - The name of the sheet to delete the row from.
+
+#### Example
+
+```typescript
+sheet2db.DeleteRow({ row: 1, sheet: 'Sheet1' })
+    .then(response => console.log(response))
+    .catch(error => console.error(error));
+```
+
+### DeleteWithQuery
+
+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));
+```
+
+### Clear
+
+Clears all data from a sheet.
+
+#### Parameters
+
+- **sheet**: `string` - The name of the sheet to clear.
+
+#### Example
+
+```typescript
+sheet2db.Clear({ sheet: 'Sheet1' })
+    .then(response => console.log(response))
+    .catch(error => console.error(error));
+```
+
+### CreateSheet
+
+Creates a new sheet in the spreadsheet.
+
+#### Parameters
+
+- **title** (optional): `string` - The title of the new sheet.
+
+#### Example
+
+```typescript
+sheet2db.CreateSheet({ title: 'NewSheet' })
+    .then(response => console.log(response))
+    .catch(error => console.error(error));
+```
+
+### DeleteSheet
+
+Deletes a sheet from the spreadsheet.
+
+#### Parameters
+
+- **sheet**: `string` - The name of the sheet to delete.
+
+#### Example
+
+```typescript
+sheet2db.DeleteSheet({ sheet: 'Sheet1' })
+    .then(response => console.log(response))
+    .catch(error => console.error(error));
+```
+
+
+
+## Environment Detection
+
+The library automatically detects the environment (browser or Node.js) and uses the appropriate `fetch` implementation.
+
+```typescript
+let fetchFunction: typeof fetch;
+
+if (typeof window !== 'undefined' && typeof window.fetch !== 'undefined') {
+    fetchFunction = window.fetch.bind(window);
+} else {
+    fetchFunction = async (...args) => {
+        const fetch = global.fetch;
+        return fetch(...args);
+    };
+}
+```
+
+## Error Handling
+
+Each method returns a promise that resolves to the API response or rejects with an error.
+
+```typescript
+sheet2db.ReadContent()
+    .then(data => console.log(data))
+    .catch(error => console.error(error));
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sheet2db/sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "",
   "main": "dist/index.js",
   "scripts": {
@@ -14,7 +14,7 @@
     }
   },
   "author": "",
-  "license": "ISC",
+  "license": "MIT",
   "devDependencies": {
     "@jest/globals": "^29.7.0",
     "jest": "^29.7.0",