@metagptx/web-sdk 0.0.1

package/README.md

@@ -0,0 +1,414 @@
+# FuncSea WebSDK
+
+A TypeScript SDK for interacting with FuncSea API, providing modules for authentication, entity management, API calls, and integrations.
+
+## Installation
+
+```bash
+npm install @metagptx/web-sdk
+# or
+pnpm install @metagptx/web-sdk
+# or
+yarn add @metagptx/web-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from '@metagptx/web-sdk';
+
+// Create client instance (no configuration needed)
+const client = createClient();
+
+// Use the client
+const user = await client.auth.me();
+```
+
+## Modules
+
+The SDK provides four main modules:
+
+- **auth**: User authentication operations
+- **entities**: Dynamic entity CRUD operations
+- **apiCall**: Custom API calls
+- **integrations**: Integration function invocations
+
+## API Reference
+
+### Auth Module
+
+Handles user authentication and session management.
+
+#### `auth.me()`
+
+Get current user information.
+
+**HTTP Details:**
+- **Method:** `GET`
+- **Path:** `/api/v1/auth/me`
+- **Parameters:** None
+
+**Example:**
+```typescript
+const response = await client.auth.me();
+console.log(response.data);
+```
+
+#### `auth.logout()`
+
+Logout the current user.
+
+**HTTP Details:**
+- **Method:** `POST`
+- **Path:** `/api/v1/auth/logout`
+- **Parameters:** None
+
+**Example:**
+```typescript
+await client.auth.logout();
+```
+
+#### `auth.toLogin()`
+
+Redirect to the login page. This is a utility function that redirects the browser to the login URL with the current page as the redirect parameter.
+
+**Example:**
+```typescript
+client.auth.toLogin();
+```
+
+---
+
+### Entities Module
+
+Provides dynamic CRUD operations for any entity type. Access entities using property syntax: `client.entities.{entityName}.{operation}()`.
+
+#### `entities[entityName].query(params?)`
+
+Query entities with filtering, sorting, and pagination.
+
+**HTTP Details:**
+- **Method:** `GET`
+- **Path:** `/api/entities/{entityName}`
+- **Parameters:**
+  - `query` (optional): Query conditions object
+  - `sort` (optional): Sort field and order (e.g., `"-createdAt"`)
+  - `limit` (optional): Maximum number of results
+  - `skip` (optional): Number of results to skip
+  - `fields` (optional): Array of fields to return
+
+**Example:**
+```typescript
+const response = await client.entities.users.query({
+  query: { status: 'active' },
+  sort: '-createdAt',
+  limit: 10,
+  skip: 0,
+  fields: ['id', 'name', 'email'],
+});
+```
+
+#### `entities[entityName].get(params)`
+
+Get a single entity by ID.
+
+**HTTP Details:**
+- **Method:** `GET`
+- **Path:** `/api/entities/{entityName}/{id}`
+- **Parameters:**
+  - `id` (required): Entity ID
+  - `fields` (optional): Array of fields to return
+
+**Example:**
+```typescript
+const response = await client.entities.users.get({
+  id: '12345',
+  fields: ['id', 'name', 'email'],
+});
+```
+
+#### `entities[entityName].create(params)`
+
+Create a new entity.
+
+**HTTP Details:**
+- **Method:** `POST`
+- **Path:** `/api/entities/{entityName}`
+- **Body:**
+  - `data` (required): Entity data object
+
+**Example:**
+```typescript
+const response = await client.entities.users.create({
+  data: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    status: 'active',
+  },
+});
+```
+
+#### `entities[entityName].update(params)`
+
+Update an existing entity.
+
+**HTTP Details:**
+- **Method:** `PUT`
+- **Path:** `/api/entities/{entityName}/{id}`
+- **Body:**
+  - `id` (required): Entity ID
+  - `data` (required): Updated entity data
+
+**Example:**
+```typescript
+const response = await client.entities.users.update({
+  id: '12345',
+  data: {
+    name: 'Jane Doe',
+    status: 'inactive',
+  },
+});
+```
+
+#### `entities[entityName].delete(params)`
+
+Delete a single entity by ID.
+
+**HTTP Details:**
+- **Method:** `DELETE`
+- **Path:** `/api/entities/{entityName}/{id}`
+- **Parameters:**
+  - `id` (required): Entity ID
+
+**Example:**
+```typescript
+await client.entities.users.delete({ id: '12345' });
+```
+
+#### `entities[entityName].createBatch(params)`
+
+Create multiple entities in a single request.
+
+**HTTP Details:**
+- **Method:** `POST`
+- **Path:** `/api/entities/{entityName}/batch`
+- **Body:**
+  - `data` (required): Array of entity data objects
+
+**Example:**
+```typescript
+const response = await client.entities.users.createBatch({
+  data: [
+    { name: 'John Doe', email: 'john@example.com' },
+    { name: 'Jane Smith', email: 'jane@example.com' },
+  ],
+});
+```
+
+#### `entities[entityName].updateBatch(params)`
+
+Update multiple entities in a single request.
+
+**HTTP Details:**
+- **Method:** `PUT`
+- **Path:** `/api/entities/{entityName}/batch`
+- **Body:**
+  - `data` (required): Array of entity data objects (must include `id` for each)
+
+**Example:**
+```typescript
+const response = await client.entities.users.updateBatch({
+  data: [
+    { id: '12345', status: 'active' },
+    { id: '67890', status: 'inactive' },
+  ],
+});
+```
+
+#### `entities[entityName].deleteBatch(params)`
+
+Delete multiple entities by their IDs.
+
+**HTTP Details:**
+- **Method:** `DELETE`
+- **Path:** `/api/entities/{entityName}/batch`
+- **Body:**
+  - `ids` (required): Array of entity IDs
+
+**Example:**
+```typescript
+await client.entities.users.deleteBatch({
+  ids: ['12345', '67890', '11111'],
+});
+```
+
+---
+
+### API Call Module
+
+Provides a flexible way to make custom API calls with any HTTP method.
+
+#### `apiCall.invoke(params)`
+
+Invoke a custom API call with specified method, URL, and data.
+
+**HTTP Details:**
+- **Method:** Configurable (GET, POST, PUT, PATCH, DELETE, etc.)
+- **Path:** Configurable
+- **Parameters:**
+  - `url` (required): API endpoint path
+  - `method` (optional): HTTP method (defaults to 'GET')
+  - `data` (optional): Request data (body for POST/PUT/PATCH, query params for GET/DELETE)
+  - `options` (optional): Additional axios request options
+
+**Example:**
+```typescript
+// GET request with query parameters
+const response = await client.apiCall.invoke({
+  url: '/api/v1/custom/endpoint',
+  method: 'GET',
+  data: { filter: 'active' },
+});
+
+// POST request with body data
+const response = await client.apiCall.invoke({
+  url: '/api/v1/custom/action',
+  method: 'POST',
+  data: { name: 'Test', value: 123 },
+  options: {
+    headers: { 'X-Custom-Header': 'value' },
+  },
+});
+```
+
+---
+
+### Integrations Module
+
+Provides dynamic access to integration functions. Access integrations using property syntax: `client.integrations.{packageName}.{functionName}(params)`.
+
+#### `integrations.core[functionName](params?)`
+
+Invoke a core integration function.
+
+**HTTP Details:**
+- **Method:** `POST`
+- **Path:** `/api/integrations/core/{functionName}`
+- **Body:**
+  - `payload` (optional): Function payload data (object or FormData)
+  - `option` (optional): Additional request options
+
+**Example:**
+```typescript
+const response = await client.integrations.core.sendEmail({
+  payload: {
+    to: 'user@example.com',
+    subject: 'Hello',
+    body: 'Welcome!',
+  },
+});
+```
+
+#### `integrations[packageName][functionName](params?)`
+
+Invoke a provider-specific integration function.
+
+**HTTP Details:**
+- **Method:** `POST`
+- **Path:** `/api/integrations/providers/{packageName}/{functionName}`
+- **Body:**
+  - `payload` (optional): Function payload data (object or FormData)
+  - `option` (optional): Additional request options
+
+**Example:**
+```typescript
+// Regular JSON payload
+const response = await client.integrations.stripe.createPayment({
+  payload: {
+    amount: 1000,
+    currency: 'usd',
+  },
+});
+
+// FormData payload for file uploads
+const formData = new FormData();
+formData.append('file', fileBlob);
+formData.append('metadata', JSON.stringify({ key: 'value' }));
+
+const response = await client.integrations.storage.uploadFile({
+  payload: formData,
+});
+```
+
+---
+
+## Configuration
+
+### Client Configuration Options
+
+In most cases, you don't need to pass any configuration:
+
+```typescript
+// Default usage (recommended)
+const client = createClient();
+```
+
+However, you can optionally customize the client behavior for advanced use cases:
+
+```typescript
+const client = createClient({
+  baseURL: '/custom-api',              // Custom base URL (defaults to '/')
+  timeout: 30000,                      // Request timeout in milliseconds (defaults to 60000)
+  headers: {                           // Custom headers
+    'X-Custom-Header': 'value',
+  },
+  // Any other axios configuration options
+});
+```
+
+**Note:** The `baseURL` and `timeout` options are reserved for future use or special deployment scenarios. Most users should rely on the default values.
+
+### Automatic 401 Handling
+
+The SDK automatically handles 401 (Unauthorized) responses by redirecting to the login page. This behavior is built-in and requires no additional configuration.
+
+---
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions. You can use generic types for typed responses:
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const response = await client.entities.users.get<User>({ id: '12345' });
+const user: User = response.data;
+```
+
+---
+
+## Error Handling
+
+All API calls return promises that may reject with an error. Always handle errors appropriately:
+
+```typescript
+try {
+  const response = await client.entities.users.get({ id: '12345' });
+  console.log(response.data);
+} catch (error) {
+  if (error.response) {
+    // Server responded with error status
+    console.error('Error:', error.response.status, error.response.data);
+  } else if (error.request) {
+    // Request made but no response received
+    console.error('No response received:', error.request);
+  } else {
+    // Error setting up the request
+    console.error('Error:', error.message);
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+import * as axios0 from "axios";
+import { AxiosRequestConfig } from "axios";
+
+//#region src/utils/request.d.ts
+/**
+ * Request instance configuration options
+ */
+interface RequestConfig extends AxiosRequestConfig {
+  baseURL?: string;
+  timeout?: number;
+  onUnauthorized?: () => void;
+}
+/**
+ * Creates an axios request instance with default configuration
+ * @param config - Optional configuration for the request instance
+ * @returns Configured axios instance
+ */
+//#endregion
+//#region src/client.d.ts
+interface ClientConfig extends RequestConfig {}
+declare const createClient: (config?: ClientConfig) => {
+  auth: {
+    me(): Promise<axios0.AxiosResponse<any, any, {}>>;
+    logout(): Promise<axios0.AxiosResponse<any, any, {}>>;
+    toLogin: () => void;
+  };
+  entities: Record<string, {
+    query<T = any>(params?: {
+      query?: Record<string, unknown>;
+      sort?: string;
+      limit?: number;
+      skip?: number;
+      fields?: string[];
+    }): Promise<axios0.AxiosResponse<T, any, {}>>;
+    get<T = any>(params: {
+      id: string;
+      fields?: string[];
+    }): Promise<axios0.AxiosResponse<T, any, {}>>;
+    create<T = any>(params: {
+      data: Record<string, unknown>;
+    }): Promise<axios0.AxiosResponse<T, any, {}>>;
+    update<T = any>(params: {
+      id: string;
+      data: Record<string, unknown>;
+    }): Promise<axios0.AxiosResponse<T, any, {}>>;
+    delete<T = any>(params: {
+      id: string;
+    }): Promise<axios0.AxiosResponse<T, any, {}>>;
+    deleteBatch<T = any>(params: {
+      ids: string[];
+    }): Promise<axios0.AxiosResponse<T, any, {}>>;
+    createBatch<T = any>(params: {
+      data: Record<string, unknown>[];
+    }): Promise<axios0.AxiosResponse<T, any, {}>>;
+    updateBatch<T = any>(params: {
+      data: Record<string, unknown>[];
+    }): Promise<axios0.AxiosResponse<T, any, {}>>;
+  }>;
+  apiCall: {
+    invoke<T = any>(params: ApiCallParams): Promise<axios0.AxiosResponse<T, any, {}>>;
+  };
+  integrations: Record<string, Record<string, IntegrationFunction>>;
+};
+//#endregion
+//#region src/types/index.d.ts
+/**
+ * Common reusable types for the funcsea-websdk
+ */
+type AnyType = any;
+//#endregion
+//#region src/modules/apiCall.d.ts
+/**
+ * API call parameters interface
+ */
+interface ApiCallParams {
+  url: string;
+  method?: string;
+  data?: Record<string, AnyType>;
+  options?: AxiosRequestConfig;
+}
+/**
+ * Creates an API call module for making custom HTTP requests
+ * @param params - Configuration object
+ * @param params.requestInstance - Axios instance for making HTTP requests
+ * @returns Object containing invoke method for API calls
+ */
+//#endregion
+//#region src/modules/integrations.d.ts
+/**
+ * Integration function parameters interface
+ */
+interface IntegrationParams {
+  payload?: Record<string, AnyType> | FormData;
+  option?: Record<string, AnyType>;
+}
+/**
+ * Integration function type
+ */
+type IntegrationFunction = (params?: IntegrationParams) => Promise<AnyType>;
+/**
+ * Creates an integrations module using proxy for dynamic package and function access
+ * @param params - Configuration object
+ * @param params.requestInstance - Axios instance for making HTTP requests
+ * @returns Proxy object that dynamically creates integration calls
+ */
+
+//#endregion
+export { type AnyType, type ApiCallParams, type ClientConfig, type IntegrationFunction, type IntegrationParams, type RequestConfig, createClient };

package/dist/index.js

@@ -0,0 +1 @@
+import e from"axios";import t from"qs";const n=(n={})=>{let{onUnauthorized:r,...i}=n,a={timeout:6e4,paramsSerializer:e=>t.stringify(e,{arrayFormat:`brackets`}),...i,headers:{"Content-Type":`application/json`,...i.headers}},o=e.create(a);return o.interceptors.request.use(e=>e,e=>Promise.reject(e)),o.interceptors.response.use(e=>e,e=>(e.response?.status===401&&r&&r(),Promise.reject(e))),o},r=e=>typeof e==`string`?e.startsWith(`_`)||e.startsWith(`$`)||e===`constructor`||e===`toString`||e===`valueOf`||e===`inspect`||e===`toJSON`:!0,i=()=>{let e=window.location.href,t=new URLSearchParams({from_url:e});window.location.href=`/api/v1/auth/login?${t.toString()}`},a=e=>{let{requestInstance:t}=e;return{async me(){return t.get(`/api/v1/auth/me`)},async logout(){return t.post(`/api/v1/auth/logout`)},toLogin:i}},o=e=>{let{requestInstance:t,entityName:n}=e,r=`/api/entities/${n}`;return{async query(e){return t.get(r,{params:e})},async get(e){let{id:n,...i}=e;return t.get(`${r}/${n}`,{params:i})},async create(e){return t.post(r,e.data)},async update(e){return t.put(`${r}/${e.id}`,e.data)},async delete(e){return t.delete(`${r}/${e.id}`)},async deleteBatch(e){return t.delete(`${r}/batch`,{data:{ids:e.ids}})},async createBatch(e){return t.post(`${r}/batch`,e.data)},async updateBatch(e){return t.put(`${r}/batch`,e.data)}}},s=e=>{let{requestInstance:t}=e,n=new Map;return new Proxy({},{get(e,i){if(!r(i))return n.has(i)||n.set(i,o({requestInstance:t,entityName:i})),n.get(i)}})},c=e=>{let{requestInstance:t}=e;return{async invoke(e){let{url:n,method:r=`GET`,data:i,options:a={}}=e,o={method:r.toUpperCase(),url:n,...a};return i&&[`POST`,`PUT`,`PATCH`].includes(o.method)?o.data=i:i&&[`GET`,`DELETE`].includes(o.method)&&(o.params=i),t.request(o)}}},l=e=>{let{requestInstance:t}=e;return new Proxy({},{get(e,n){if(!r(n))return new Proxy({},{get(e,i){if(!r(i))return(e={})=>{let r=`/api/integrations/core/${i}`;n!==`core`&&(r=`/api/integrations/providers/${n}/${i}`);let{payload:a={},option:o={}}=e,s=a instanceof FormData?{...o,headers:{...o.headers,"Content-Type":void 0}}:o;return t.post(r,a,s)}}})}})},u=(e={})=>{let t=n({baseURL:`/`,...e,onUnauthorized:i}),r=a({requestInstance:t}),o=s({requestInstance:t}),u=c({requestInstance:t}),d=l({requestInstance:t});return{auth:r,entities:o,apiCall:u,integrations:d}};export{u as createClient};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@metagptx/web-sdk",
+  "type": "module",
+  "version": "0.0.1",
+  "packageManager": "pnpm@10.15.0+sha512.486ebc259d3e999a4e8691ce03b5cac4a71cbeca39372a9b762cb500cfdf0873e2cb16abe3d951b1ee2cf012503f027b98b6584e4df22524e0c7450d9ec7aa7b",
+  "description": "TypeScript SDK for interacting with FuncSea API",
+  "author": "MetaGPTX",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:coverage": "vitest --coverage run",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp && npm publish",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "precommit": "npm run typecheck && lint-staged && npm run test:coverage",
+    "commit-msg": "echo commit-msg"
+  },
+  "dependencies": {
+    "@types/qs": "^6.14.0",
+    "axios": "^1.12.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "lint-staged": "^16.2.3",
+    "qs": "^6.14.0",
+    "simple-git-hooks": "^2.13.1"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^5.4.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.15.17",
+    "@vitest/coverage-v8": "^3.2.4",
+    "bumpp": "^10.1.0",
+    "eslint": "^9.36.0",
+    "tsdown": "^0.11.9",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.3"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "npm run precommit",
+    "commit-msg": "npm run commit-msg"
+  },
+  "lint-staged": {
+    "*.{js,ts,mts,mjs,md}": [
+      "prettier --write",
+      "eslint --ext .js,.ts . --quiet"
+    ]
+  }
+}